cron-up 26.10.26 → 26.10.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cron-up",
-  "version": "26.10.26",
+  "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

@@ -10,35 +10,7 @@ import { cmdInstall, cmdUninstall } from './service.mjs';
 import { cmdList } from './list.mjs';
 import { cmdOverview } from './overview.mjs';
 import { cmdLogs } from './logs.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,
-  },
-};
+import { SPECS, thisCamel } from './args.mjs';
 
 // 严格十进制整数命令行值（谓词 isDecInt 见 internals）：
 // Number("0x10")、parseInt("5x") 都会静默给出错误结果，必须显式拒绝。
@@ -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 = {};

package/src/config.mjs

@@ -4,7 +4,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps, ExitError, isPlainObject, isDecInt } from './internals.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';
 
@@ -31,7 +37,7 @@ 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('数值越界');
@@ -160,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`, {
@@ -214,6 +213,17 @@ 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);
 }

package/src/constants.mjs

@@ -100,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 年；窗口小了尾窗会塌缩成零：落点已

package/src/cron.mjs

@@ -249,9 +249,9 @@ export function taskIdHash(taskId) {
 // 不是 nextAfter 给出的下个落点——后者严格在未来，会把展示拐到明天），
 // 否则是下一落点 + 按 id 的抖动。先于窗口检查尾窗：2 月 29 日这类长周期
 // 任务的下一落点可能在展示窗口之外，正在等待的投递却依然成立。taskView
-// 的 nxt/fire 与 predictedFire 共用这一个口径，落点与投递同源，两边不会
-// 各说各话。返回 {slot, fire}，均为 Date 或 null（窗口内没有落点时双双
-// 为 null）。cron 须已解析且 satisfiable。
+// 的 nxt/fire 与 wanted 都以这里的落点为单一来源，两边不会各说各话。返回
+// {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);
@@ -285,16 +285,6 @@ export function nextDelivery(cron, task, now, withinDays = DISPLAY_SEARCH_DAYS)
   // 经过该分支，故不予复刻。
 }
 
-// 任务按 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。
 function recurringDelayMs(cron, slot, taskId, withinDays) {

package/src/display.mjs

@@ -122,7 +122,8 @@ 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();
 }
@@ -142,10 +143,10 @@ export function fmtFireRange(nxt, fire) {
   }
   const r = new Date(Math.round(fire.getTime() / 1000) * 1000);
   if (sameMinute(nxt, r)) return fmtMDHM(nxt);
+  const secs = r.getSeconds() ? `:${pad2(r.getSeconds())}` : '';
   const tail = sameDay(nxt, r)
-    ? `${pad2(r.getHours())}:${pad2(r.getMinutes())}`
-      + (r.getSeconds() ? `:${pad2(r.getSeconds())}` : '')
-    : `${fmtMDHM(r)}${r.getSeconds() ? `:${pad2(r.getSeconds())}` : ''}`;
+    ? `${pad2(r.getHours())}:${pad2(r.getMinutes())}${secs}`
+    : `${fmtMDHM(r)}${secs}`;
   return `${fmtMDHM(nxt)} → ${tail}`;
 }
 

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 {
@@ -64,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

@@ -42,8 +42,9 @@ 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) {
-      say(`注：${err} 有内容（最后写入 ${fmtMDHM(fs.statSync(err).mtime)}），`
+    const st = fs.statSync(err);
+    if (st.size > 0) {
+      say(`注：${err} 有内容（最后写入 ${fmtMDHM(st.mtime)}），`
         + '巡检若异常先看它');
     }
   } catch {

package/src/overview.mjs

@@ -5,16 +5,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps } from './internals.mjs';
+import { deps, packageVersion } from './internals.mjs';
 import {
   loadConfig,
   loadState,
   validateConfig,
   loadHeartbeat,
   heartbeatStale,
+  isCooling,
+  cooldownEtaMinutes,
 } from './config.mjs';
 import { taskFileExists } from './tasks.mjs';
-import { packageVersion } from './paths.mjs';
 import { serviceLine, launcherHealth } from './service.mjs';
 import {
   humanDelta,
@@ -26,6 +27,7 @@ import {
   elapsedZh,
   fmtMDHM,
   fmtHM,
+  sameMinute,
 } from './display.mjs';
 
 // 总览页任务盘点。返回 [告警, 已在告警里说明冷却的工作区集合, 本轮发现
@@ -81,11 +83,10 @@ function overviewTasks(cfg, cols, consumers, state) {
     }
     if (wanted && !consumers.has(ws)) {
       const ent = state[ws] ?? {};
-      const cooldown = ent.cooldownUntil ?? 0;
-      if (cooldown > cur) {
+      if (isCooling(ent, cur)) {
         // 与「下轮会自动启动」互斥：冷却中就是不会启动，两条同现会自相
         // 矛盾，这里合并成一条。
-        const eta = Math.max(0, Math.floor((cooldown - cur) / 60));
+        const eta = cooldownEtaMinutes(ent, cur);
         alerts.push(
           `${ws} 有任务即将执行（或错过待补执行），但保活会话连续失败 `
           + `${ent.fails ?? '?'} 次正处冷却中，约 ${eta} 分钟后才会重试；`
@@ -109,8 +110,7 @@ function overviewTasks(cfg, cols, consumers, state) {
   if (soonest) {
     const [fire, ws, summary, nxt] = soonest;
     // 预计与设定不在同一分钟时，附注 cron 落点，解释两个时间的差。
-    const setTag = (nxt && (fmtHM(fire) !== fmtHM(nxt)
-      || fire.getDate() !== nxt.getDate()))
+    const setTag = (nxt && !sameMinute(fire, nxt))
       ? `，设定 ${fmtHM(nxt)}` : '';
     const line = `最近：${fmtMDHM(fire)}（${humanDelta(fire.getTime() - now.getTime())}`
       + `${setTag}） ${path.basename(ws)} · ${summary}`;
@@ -132,7 +132,7 @@ function overviewSessions(cols, state, suppressCooling, discovered) {
   const cooling = [];
   const dead = [];
   for (const [ws, ent] of Object.entries(state)) {
-    if ((ent.cooldownUntil ?? 0) > cur) cooling.push([ws, ent]);
+    if (isCooling(ent, cur)) cooling.push([ws, ent]);
     else if (deps.trackedAlive(ent)) live.push([ws, ent]);
     else dead.push(ws); // 记录还在、进程已没：带失败计数的保留至老化，其余下轮清理
   }
@@ -151,7 +151,7 @@ function overviewSessions(cols, state, suppressCooling, discovered) {
   }
   for (const [ws, ent] of cooling) {
     if (suppressCooling.has(ws)) continue; // 任务区已给过带上下文的合并告警
-    const eta = Math.max(0, Math.floor(((ent.cooldownUntil ?? 0) - cur) / 60));
+    const eta = cooldownEtaMinutes(ent, cur);
     alerts.push(`${ws} 保活连续失败 ${ent.fails ?? '?'} 次，冷却中，约 ${eta} `
       + '分钟后重试');
   }
@@ -205,7 +205,7 @@ export async function cmdOverview(args) {
   const state = loadState();
   const curOv = Math.floor(Date.now() / 1000);
   const heartbeat = loadHeartbeat();
-  const coolingWarned = new Set();
+  let coolingWarned = new Set();
   let discovered = null;
 
   if (cfgError !== null) {
@@ -221,7 +221,7 @@ export async function cmdOverview(args) {
     const minIdTag = cfg.autoMinId ? '，id 自动改小' : '，id 保持原样';
     const retainTag = cfg.sessionRetain === 'always'
       ? '，会话常驻' : '，会话按执行回收';
-    if (actualIv === null || actualIv === undefined) {
+    if (actualIv == null) {
       deps.print(`巡检：配置为每 ${cfg.intervalSeconds} 秒一轮（服务未加载），`
         + `提前 ${cfg.leadSeconds} 秒启动会话${renewTag}${minIdTag}${retainTag}`);
     } else {
@@ -252,9 +252,10 @@ export async function cmdOverview(args) {
     }
     alerts.push(...validateConfig(cfg));
     deps.print('');
-    const [taskAlerts, cooled, found] = overviewTasks(cfg, cols, consumers, state);
+    const [taskAlerts, coolingWarnedNow, found] = overviewTasks(
+      cfg, cols, consumers, state);
     alerts.push(...taskAlerts);
-    for (const w of cooled) coolingWarned.add(w);
+    coolingWarned = coolingWarnedNow;
     discovered = found;
   }
 

package/src/paths.mjs

@@ -3,8 +3,6 @@
 
 import os from 'node:os';
 import path from 'node:path';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
 
 export const LABEL = 'local.cron-up';
 
@@ -56,14 +54,3 @@ export const paths = makePaths({
   plistPath: path.join(HOME, 'Library', 'LaunchAgents', `${LABEL}.plist`),
   sessionDir: path.join(HOME, '.claude', 'sessions'),
 });
-
-// 版本号读 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;
-  }
-}

package/src/patrol.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps } from './internals.mjs';
+import { deps, packageVersion } from './internals.mjs';
 import {
   FAIL_LIMIT,
   COOLDOWN_SECONDS,
@@ -25,6 +25,7 @@ import {
   loadHeartbeat,
   saveHeartbeat,
   heartbeatStale,
+  isCooling,
 } from './config.mjs';
 import {
   maintainWorkspace,
@@ -38,7 +39,7 @@ import {
   scriptProcLogPath,
   rotateOnce,
 } from './sessions.mjs';
-import { TASK_REL, packageVersion } from './paths.mjs';
+import { TASK_REL } from './paths.mjs';
 import { elapsedZh, pad2 } from './display.mjs';
 
 // 事件类型 → 轮末汇总里的中文标签。patrolWorkspace 与 cmdRun 往同一个
@@ -129,7 +130,7 @@ export function acquireRunLock() {
   return null;
 }
 
-export function releaseLock(handle) {
+function releaseLock(handle) {
   if (!handle?.lockPath) return;
   try {
     fs.unlinkSync(handle.lockPath);
@@ -158,7 +159,11 @@ export function rotatePatrolLogs() {
 }
 
 // 下次「需要会话在场」的时刻（ms）：各任务下次触发的最小值；有错过待补
-// 执行的一次性任务时视为立刻需要。窗口内无安排返回 Infinity。
+// 执行的一次性任务时视为立刻需要。窗口内无安排返回 Infinity。锚点刻意取
+// cron 裸落点而非 nextDelivery 的抖动后投递时刻：落点总不晚于投递时刻，
+// 按落点算余量更小、回收更保守，是安全方向；真正的重拉闸门是下面的
+// wanted(leadMs)，margin 只需保住新会话登记。若改用 fire，落点后、投递
+// 前的整段延迟窗内都不会回收，回收频率被悄悄改变。
 function needHorizonMs(tasks, now) {
   let horizon = Infinity;
   for (const t of tasks) {
@@ -212,23 +217,28 @@ export async function patrolWorkspace(
     return;
   }
 
+  // 结束本代会话的完整收尾：停掉 → 摘 state → 重扫消费者。换代与 window
+  // 回收是同一个动作，差别只在触发条件与文案；消费者快照拍于轮初，刚结束
+  // 的这代可能正是快照里的消费者，不重扫会让陈旧登记挡住下面的重拉。
+  let mineAlive = deps.trackedAlive(ent);
+  const retire = async (kind, msg) => {
+    await deps.stopSession(ent);
+    note(kind, msg);
+    delete state[ws];
+    ent = null;
+    mineAlive = false;
+    consumers = (await deps.scanSessions())[0];
+  };
+
   // 换代：超龄且日志静默（无任务在执行的证据）的会话主动结束，需要时下
   // 文自然重拉。换代是维护，不计失败。
-  let mineAlive = deps.trackedAlive(ent);
   if (ent !== null && mineAlive) {
     const age = cur - (ent.startedAt ?? cur);
     if (age > SESSION_MAX_AGE_SECONDS
         && sessionLogIdleSeconds(
           ent.log || sessionLogPath(ws), cur) > SESSION_IDLE_SECONDS) {
-      await deps.stopSession(ent);
-      note('ageout', `换代 ${ws} pid=${ent.pid}：会话已连续运行 `
+      await retire('ageout', `换代 ${ws} pid=${ent.pid}：会话已连续运行 `
         + `${Math.floor(age / 86400)} 天且近期无输出，结束后按需重拉`);
-      delete state[ws];
-      ent = null;
-      mineAlive = false;
-      // 消费者快照拍于轮初，被换代的这代可能正是快照里的消费者：重扫一
-      // 次，别让陈旧登记挡住下面的重拉。
-      consumers = (await deps.scanSessions())[0];
     }
   }
 
@@ -248,16 +258,9 @@ export async function patrolWorkspace(
         > SESSION_RECYCLE_IDLE_SECONDS
       && needHorizonMs(tasks, now) - now.getTime()
         > SESSION_FIRE_MARGIN_SECONDS * 1000) {
-    const pid = ent.pid;
-    await deps.stopSession(ent);
-    note('recycle', `回收 ${ws} pid=${pid}：本代任务已执行完毕且界面静默，`
-      + '结束会话，下次需要时重拉');
-    delete state[ws];
-    ent = null;
-    mineAlive = false;
-    // 同上：快照里的消费者可能正是刚结束的这代。用户自己的会话若在场，
-    // 重扫依旧看见，不会在同目录双开。
-    consumers = (await deps.scanSessions())[0];
+    // 用户自己的会话若在场，retire 的重扫依旧看见，不会在同目录双开。
+    await retire('recycle', `回收 ${ws} pid=${ent.pid}：本代任务已执行完毕且`
+      + '界面静默，结束会话，下次需要时重拉');
   }
 
   // 登记成功即健康证据，当场清零失败计数，不等「有任务想要会话」的轮
@@ -276,7 +279,7 @@ export async function patrolWorkspace(
 
   if (!tasks.some((t) => taskWanted(t, now, leadMs))) return;
 
-  const cooling = Boolean(ent && (ent.cooldownUntil ?? 0) > cur);
+  const cooling = isCooling(ent, cur);
 
   // 活着但没有消费。健康只在真实启动所需的时间内成立；超时就是卡在无人
   // 应答的提问界面，永不登记——退休它并推进失败计数。
@@ -507,7 +510,7 @@ export async function cmdRun(args) {
     const kept = Object.fromEntries(
       Object.entries(state).filter(([, ent]) => {
         if (deps.trackedAlive(ent)) return true;
-        if ((ent.cooldownUntil ?? 0) > cur) return true;
+        if (isCooling(ent, cur)) return true;
         if ((ent.fails ?? 0) > 0) {
           ent.deadSince ??= cur;
           return cur - ent.deadSince < FAIL_TTL_SECONDS;

package/src/registry.mjs

@@ -6,7 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps } from './internals.mjs';
+import { deps, isPlainObject } from './internals.mjs';
 import { parsePid } from './config.mjs';
 import { lexReal } from './tasks.mjs';
 
@@ -73,7 +73,7 @@ export async function scanSessions() {
   const interactive = [];
   for (const f of files) {
     const s = await readSessionFile(f);
-    if (s && typeof s === 'object' && s.kind === 'interactive') {
+    if (isPlainObject(s) && s.kind === 'interactive') {
       interactive.push(s);
     }
   }

package/src/service.mjs

@@ -4,8 +4,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps, ExitError, isPlainObject } from './internals.mjs';
+import {
+  deps,
+  ExitError,
+  isPlainObject,
+  ensurePrivateDir,
+} from './internals.mjs';
 import { paths, LABEL } from './paths.mjs';
+import { SPECS, thisCamel } from './args.mjs';
 // paths.home 仅用于 resolveLauncher 的默认 HOME；其余产物路径一律走
 // deps.paths（测试要整体重定向）。
 import { scriptProcLogPath } from './sessions.mjs';
@@ -33,7 +39,9 @@ export function launchctl(...args) {
 }
 
 export function launchctlInfo() {
-  const r = launchctl('print', `${guiTarget()}/${LABEL}`);
+  // 走 deps 而非同文件裸名：与 bootout/bootstrap 的打桩面保持一致，测试可
+  // 在 launchctl 一层整体模拟 launchd。
+  const r = deps.launchctl('print', `${guiTarget()}/${LABEL}`);
   if (r.status !== 0) return null;
   const info = {};
   for (const key of ['state', 'last exit code']) {
@@ -244,15 +252,11 @@ 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'],
-];
+// 生效的参数」。名单直接从解析器的选项表派生——force 不落盘，其余选项都
+// 会写进配置；新加可持久化选项时这里自动跟进，不会静默漏报。
+const IGNORED_INSTALL_FLAGS = Object.keys(SPECS.install.options)
+  .filter((name) => name !== 'force')
+  .map((name) => [thisCamel(name), `--${name}`]);
 
 export async function cmdInstall(args) {
   // --config 在这里只会造成误解：install 写盘、launchd 每轮读取的都是固定
@@ -263,12 +267,8 @@ export async function cmdInstall(args) {
       + `使用 ${deps.paths.configPath}，如需临时改配置请直接编辑该文件`);
   }
   fs.mkdirSync(deps.paths.dataDir, { recursive: true });
-  fs.mkdirSync(deps.paths.sessionLogDir, { recursive: true });
-  try {
-    fs.chmodSync(deps.paths.sessionLogDir, 0o700);
-  } catch {
-    // 维持现状。
-  }
+  // dataDir 只建不 chmod：本分支可能保留旧配置而不写盘，不搭车改权限。
+  ensurePrivateDir(deps.paths.sessionLogDir);
 
   let cfg;
   if (fs.existsSync(deps.paths.configPath) && !args.force) {

package/src/sessions.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps } from './internals.mjs';
+import { deps, ensurePrivateDir } from './internals.mjs';
 
 // pid 是否对应活进程。走到这儿的 pid 已经过入口范围校验。
 export function alive(pid) {
@@ -97,12 +97,7 @@ export function rotateOnce(file) {
 // 拉起一个 detached 的 pty TUI，返回 {pid, procStart}。
 export function spawnSession(ws) {
   const logPath = sessionLogPath(ws);
-  fs.mkdirSync(path.dirname(logPath), { recursive: true });
-  try {
-    fs.chmodSync(path.dirname(logPath), 0o700);
-  } catch {
-    // 目录权限维持现状。
-  }
+  ensurePrivateDir(path.dirname(logPath));
   // window 模式下「一代会话 = 一次执行」：script(1) 打开即截断，不轮转的
   // 话上一代（上一次任务执行）的界面记录会随本次拉起被抹掉。无条件保留
   // 一代（.1）——总量上界两代，活着的一代增长再快也只影响自身，不会经

package/src/tasks.mjs

@@ -124,17 +124,11 @@ export function* discover(roots, maxDepth) {
   }
 }
 
-// 读一个工作区的任务列表，坏形状一律返回 null。
+// 读一个工作区的任务列表，坏形状一律返回 null。读盘与顶层形状校验复用
+// loadTaskDoc（renew 也要同一口径 round-trip 整份文档）。
 export function readTasks(ws) {
-  let doc;
-  try {
-    doc = JSON.parse(fs.readFileSync(
-      path.join(ws, TASK_REL), 'utf-8'));
-  } catch {
-    return null;
-  }
-  if (!isPlainObject(doc) || !Array.isArray(doc.tasks)) return null;
-  return doc.tasks.filter(isPlainObject);
+  const doc = deps.loadTaskDoc(path.join(ws, TASK_REL));
+  return doc === null ? null : doc.tasks.filter(isPlainObject);
 }
 
 // 任务文件在「读到」与「写回」之间被别的写者改了（Claude Code 更新