cron-up 26.9.1

package/src/overview.mjs

@@ -0,0 +1,260 @@
+// 无子命令时的总览页：一眼看清服务、配置、任务、保活会话与需要留意的
+// 事。它回答「现在一切正常吗」：除汇总现状外，还把巡检视角的异常集中成
+// 一个「需要留意」清单。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { deps } from './internals.mjs';
+import { loadConfig, loadState, validateConfig, isInt } from './config.mjs';
+import { packageVersion, TASK_REL } from './paths.mjs';
+import { serviceLine, launcherHealth } from './service.mjs';
+import {
+  humanDelta,
+  clip,
+  pad,
+  dispWidth,
+  taskView,
+  sessionAgeZh,
+  fmtMDHM,
+} from './display.mjs';
+
+// 总览页任务盘点。返回 [告警, 已在告警里说明冷却的工作区集合, 本轮发现
+// 的工作区集合]（第三个供会话部分识别「已移出巡检视野」的会话）。
+function overviewTasks(cfg, cols, consumers, state) {
+  const alerts = [];
+  const coolingWarned = new Set();
+  const discovered = new Set();
+  const now = new Date();
+  const cur = Math.floor(now.getTime() / 1000);
+  const leadMs = cfg.leadSeconds * 1000;
+
+  let nWs = 0;
+  let nTasks = 0;
+  let unrenewed = 0;
+  let soonest = null;
+  for (const [ws] of deps.discover(cfg.roots, cfg.maxDepth)) {
+    discovered.add(ws);
+    let tasks;
+    try {
+      tasks = deps.readTasks(ws);
+    } catch {
+      continue;
+    }
+    if (tasks === null) {
+      // 与巡检同一条规则：文件还在却读不出，总览页要把它摆进「需要留
+      // 意」，而不是装作这个工作区不存在。
+      if (fs.existsSync(path.join(ws, TASK_REL))) {
+        alerts.push(`${ws} 的任务文件读不出：其中的定时任务一个都不会执行`);
+      }
+      continue;
+    }
+    if (tasks.length === 0) continue;
+    nWs += 1;
+    nTasks += tasks.length;
+    let bad = 0;
+    let wanted = false;
+    for (const t of tasks) {
+      // 与 renew 同一条字段规则：显式周期任务却没有 truthy permanent，仍
+      // 受 7 天过期约束。从原始任务计数，与 cron 合法性无关，坏 cron 也照
+      // 提醒。
+      if (t.recurring && !t.permanent) unrenewed += 1;
+      const v = taskView(t, now, leadMs);
+      if (!v.valid) {
+        bad += 1;
+        continue;
+      }
+      if (v.nxt && (!soonest || v.nxt.getTime() < soonest[0].getTime())) {
+        soonest = [v.nxt, ws, v.summary];
+      }
+      if (v.wanted) wanted = true;
+    }
+    if (bad > 0) {
+      alerts.push(`${ws} 有 ${bad} 个任务的 cron 无法解析，`
+        + `巡检会跳过${bad > 1 ? '它们' : '它'}`);
+    }
+    if (wanted && !consumers.has(ws)) {
+      const ent = state[ws] ?? {};
+      const cooldown = ent.cooldownUntil ?? 0;
+      if (cooldown > cur) {
+        // 与「下轮会自动启动」互斥：冷却中就是不会启动，两条同现会自相
+        // 矛盾，这里合并成一条。
+        const eta = Math.max(0, Math.floor((cooldown - cur) / 60));
+        alerts.push(
+          `${ws} 有任务即将执行（或错过待补执行），但保活会话连续失败 `
+          + `${ent.fails ?? '?'} 次正处冷却中，约 ${eta} 分钟后才会重试；`
+          + `请运行 cron-up logs ${path.basename(ws)} 排查`);
+        coolingWarned.add(ws);
+      } else {
+        alerts.push(`${ws} 有任务即将执行（或错过待补执行），但当前没有交互`
+          + '会话，下轮巡检会自动启动');
+      }
+    }
+  }
+
+  deps.print(nTasks > 0
+    ? `任务：${nTasks} 个，分布在 ${nWs} 个工作区`
+    : '任务：暂无');
+  if (soonest) {
+    const [nxt, ws, summary] = soonest;
+    const line = `最近：${fmtMDHM(nxt)}（${humanDelta(nxt.getTime() - now.getTime())}） `
+      + `${path.basename(ws)} · ${summary}`;
+    deps.print(clip(line, cols));
+  }
+  if (!cfg.autoRenew && unrenewed > 0) {
+    alerts.push(
+      `自动续期已关闭：${unrenewed} 个周期任务尚未标记 permanent，创建满 7 `
+      + '天后会末次执行并被删除。运行 cron-up renew 立即续期，或在配置中'
+      + '开启 autoRenew');
+  }
+  return [alerts, coolingWarned, discovered];
+}
+
+function overviewSessions(cols, state, suppressCooling = new Set(),
+  discovered = null) {
+  const alerts = [];
+  const cur = Math.floor(Date.now() / 1000);
+  const live = [];
+  const cooling = [];
+  const dead = [];
+  for (const [ws, ent] of Object.entries(state)) {
+    if ((ent.cooldownUntil ?? 0) > cur) cooling.push([ws, ent]);
+    else if (deps.trackedAlive(ent)) live.push([ws, ent]);
+    else dead.push(ws); // 记录还在、进程已没：下轮巡检即清理
+  }
+  let tail = '';
+  if (cooling.length) tail += `，冷却 ${cooling.length} 个`;
+  if (dead.length) tail += `，已失效 ${dead.length} 个`;
+  if (live.length) {
+    const desc = live.map(([ws, ent]) =>
+      `${path.basename(ws)}（pid ${ent.pid}，已运行 `
+      + `${sessionAgeZh(ent.startedAt ?? cur, cur)}）`).join('、');
+    const head = `会话：保活 ${live.length} 个（`;
+    const fixed = dispWidth(head) + dispWidth(tail) + dispWidth('）');
+    deps.print(`${head}${clip(desc, cols - fixed)}）${tail}`);
+  } else {
+    deps.print(`会话：无保活会话${tail}`);
+  }
+  for (const [ws, ent] of cooling) {
+    if (suppressCooling.has(ws)) continue; // 任务区已给过带上下文的合并告警
+    const eta = Math.max(0, Math.floor(((ent.cooldownUntil ?? 0) - cur) / 60));
+    alerts.push(`${ws} 保活连续失败 ${ent.fails ?? '?'} 次，冷却中，约 ${eta} `
+      + '分钟后重试');
+  }
+  if (discovered !== null) {
+    for (const [ws, ent] of live) {
+      if (!discovered.has(ws)) {
+        alerts.push(
+          `${ws} 的保活会话（pid ${ent.pid}）仍在运行，但该目录已不在巡检范`
+          + '围内（任务文件被删或已移出 roots），cron-up 不会再回收或换代'
+          + '它；不需要时请自行结束');
+      }
+    }
+  }
+  return alerts;
+}
+
+const COMMANDS = [
+  ['list', '逐个列出任务的内容摘要、执行时间与会话状态'],
+  ['logs [目录片段] [-f]', '查看巡检日志或后台会话记录'],
+  ['run', '立即手动巡检一轮'],
+  ['renew', '立即给所有周期任务补 permanent（跳过 7 天过期）'],
+  ['install --force', '更新配置并重新安装（全部参数见 --help）'],
+];
+
+export async function cmdOverview(args) {
+  const cols = deps.terminalWidth();
+  const v = packageVersion();
+  deps.print(`cron-up ${v ?? ''} —— 为定时任务提前备好交互会话`);
+
+  const cfgPath = args?.config ?? deps.paths.configPath;
+  let cfg = null;
+  let cfgError = null;
+  try {
+    cfg = loadConfig(cfgPath, { missingOk: true, corruptOk: true });
+  } catch (e) {
+    if (e.code !== 'ENOENT') cfgError = e;
+  }
+  // 数值字段被手改成非整数：巡检入口会以退出码 2 失败，总览若不先挡下会
+  // 在 leadMs 计算处炸掉。判定式与 cmdRun 的守卫保持一致。
+  const badFields = [];
+  if (cfg !== null) {
+    if (!isInt(cfg.intervalSeconds) || cfg.intervalSeconds <= 0) {
+      badFields.push('intervalSeconds');
+    }
+    if (!isInt(cfg.leadSeconds) || cfg.leadSeconds < 0) {
+      badFields.push('leadSeconds');
+    }
+  }
+
+  const info = deps.launchctlInfo();
+  deps.print(serviceLine(info, fs.existsSync(deps.paths.plistPath)));
+
+  const alerts = [];
+  // plist 写死的 node/入口路径失效（Node 版本目录被清）时 launchd 每轮
+  // 都静默拉不起来，这是总览唯一能发现它的地方。
+  const health = launcherHealth();
+  if (health) alerts.push(health);
+  const [consumers, registryAlert] = await deps.scanSessions();
+  if (registryAlert) alerts.push(registryAlert);
+  const state = loadState();
+  const coolingWarned = new Set();
+  let discovered = null;
+
+  if (cfgError !== null) {
+    // 页面不能死在半路：损坏配置是「需要留意」的一种；巡检本身仍会以退出
+    // 码 2 失败，详情见 cron-up logs。
+    deps.print(`配置：文件损坏，不是合法 JSON：${cfgPath}`);
+    alerts.push(`配置损坏，当前每轮巡检都会失败退出；修复 ${cfgPath} 或重新`
+      + `运行 cron-up install。解析错误：${cfgError.message}`);
+  } else if (cfg === null) {
+    deps.print('配置：缺失，运行 cron-up install 生成');
+  } else if (badFields.length) {
+    const vals = badFields.map((k) => `${k}=${JSON.stringify(cfg[k])}`).join('、');
+    deps.print(`配置：${badFields.join('、')} 应为整数秒，当前 ${vals}`);
+    alerts.push(`配置字段类型不对（${vals}），请修复 ${cfgPath}；leadSeconds `
+      + '不对时每轮巡检都会以退出码 2 失败');
+  } else {
+    const actualIv = info ? info.interval : null;
+    const renewTag = cfg.autoRenew ? '，自动续期开' : '，自动续期关';
+    if (actualIv === null || actualIv === undefined) {
+      deps.print(`巡检：配置为每 ${cfg.intervalSeconds} 秒一轮（服务未加载），`
+        + `提前 ${cfg.leadSeconds} 秒启动会话${renewTag}`);
+    } else {
+      deps.print(`巡检：每 ${actualIv} 秒一轮，提前 ${cfg.leadSeconds} 秒启动`
+        + `会话${renewTag}`);
+      if (actualIv !== cfg.intervalSeconds) {
+        alerts.push(`launchd 实际间隔 ${actualIv} 秒与配置 ${cfg.intervalSeconds} `
+          + '秒不一致，重新运行 cron-up install 后生效');
+      }
+    }
+    const suffix = `（深度 ${cfg.maxDepth}）`;
+    const rootsText = cfg.roots.join('、');
+    const prefix = '扫描：';
+    deps.print(prefix
+      + clip(rootsText, cols - dispWidth(prefix) - dispWidth(suffix))
+      + suffix);
+    alerts.push(...validateConfig(cfg, () => {}));
+    deps.print('');
+    const [taskAlerts, cooled, found] = overviewTasks(cfg, cols, consumers, state);
+    alerts.push(...taskAlerts);
+    for (const w of cooled) coolingWarned.add(w);
+    discovered = found;
+  }
+
+  // 会话状态来自 state.json，与配置无关：未安装/配置损坏时也可能有残留保
+  // 活会话，照常展示。
+  alerts.push(...overviewSessions(cols, state, coolingWarned, discovered));
+
+  if (alerts.length) {
+    deps.print('需要留意：');
+    for (const a of alerts) deps.print(`  · ${clip(a, cols - 4)}`);
+    deps.print('');
+  }
+
+  deps.print('常用命令：');
+  const nameW = Math.max(...COMMANDS.map(([n]) => dispWidth(n)));
+  for (const [name, desc] of COMMANDS) {
+    deps.print(`  cron-up ${pad(name, nameW)}  ${desc}`);
+  }
+}

package/src/paths.mjs

@@ -0,0 +1,45 @@
+// HOME 派生的全部产物路径。这些是另一个程序（launchd/Claude Code）也会
+// 触达的契约面，改名要慎重——因此集中在一个地方。
+
+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';
+export const OLD_LABEL = 'local.doorman';
+
+const HOME = os.homedir();
+// 被预热的 agent 工作区里，定时任务文件的相对路径。
+export const TASK_REL = path.join('.claude', 'scheduled_tasks.json');
+
+// 路径对象整体可替换（deps.paths）：测试把产物目录重定向到 tmp，不碰真实
+// HOME。getter 让 sessionLogDir/configPath/statePath 跟随替换后的前缀。
+export const paths = {
+  home: HOME,
+  appSupport: path.join(HOME, 'Library', 'Application Support', 'cron-up'),
+  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.appSupport, 'config.json');
+  },
+  get statePath() {
+    return path.join(this.appSupport, 'state.json');
+  },
+};
+
+// 版本号读 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

@@ -0,0 +1,396 @@
+// 一轮巡检：发现工作区 → 自动续期 → 保证该有会话的地方有一个健康会话。
+// 这是 launchd 的入口（每 N 秒被拉起一次，跑完即退）。状态机覆盖：失败
+// 冷却、卡死退休、超龄换代、孤儿接管、空任务回收。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { deps, ExitError } from './internals.mjs';
+import {
+  FAIL_LIMIT,
+  COOLDOWN_SECONDS,
+  WARMUP_GRACE_SECONDS,
+  SESSION_MAX_AGE_SECONDS,
+  SESSION_IDLE_SECONDS,
+  PATROL_LOG_ROTATE_BYTES,
+} from './constants.mjs';
+import { loadConfig, loadState, saveState, isInt } from './config.mjs';
+import { renewWorkspace, TaskFileChanged } from './tasks.mjs';
+import { taskWanted } from './cron.mjs';
+import {
+  sessionLogPath,
+  sessionLogIdleSeconds,
+} from './sessions.mjs';
+import { TASK_REL } from './paths.mjs';
+
+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}`,
+  );
+}
+
+// ---- 巡检互斥锁 ----
+// flock 的替代：O_EXCL 创建 + 持锁 pid。内核不会在持有者死亡时自动释放
+// 这种锁，所以抢锁失败要读 pid 判活，死锁/半成品文件按 stale 清理后有
+// 限重试。对 300 秒一轮的单机 launchd，残余的 pid 复用窗口最坏只跳过一
+// 轮，可接受。
+
+function tryCreateLock(lockPath) {
+  try {
+    return fs.openSync(lockPath, 'wx', 0o600);
+  } catch (e) {
+    if (e.code === 'EEXIST') return null;
+    throw e;
+  }
+}
+
+function readLockPid(lockPath) {
+  let text;
+  try {
+    text = fs.readFileSync(lockPath, 'utf-8').trim();
+  } catch {
+    return null;
+  }
+  return /^\d+$/.test(text) ? parseInt(text, 10) : null;
+}
+
+export function acquireRunLock() {
+  fs.mkdirSync(deps.paths.appSupport, { recursive: true });
+  const lockPath = path.join(deps.paths.appSupport, 'run.lock');
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const fd = tryCreateLock(lockPath);
+    if (fd !== null) {
+      try {
+        fs.writeFileSync(fd, `${process.pid}\n`);
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+      return { lockPath };
+    }
+    const holder = readLockPid(lockPath);
+    if (holder !== null) {
+      let live = false;
+      try {
+        process.kill(holder, 0);
+        live = true;
+      } catch (e) {
+        // EPERM：进程存在但不是我们的——当作活锁，不删别人的锁。
+        live = e.code === 'EPERM';
+      }
+      if (live) return null;
+    }
+    // 持有者已死 / 空文件 / pid 损坏：当作 stale 清掉重试。
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      return null; // 别人抢先重建了锁
+    }
+  }
+  return null;
+}
+
+export function releaseLock(handle) {
+  if (!handle?.lockPath) return;
+  try {
+    fs.unlinkSync(handle.lockPath);
+  } catch {
+    // 锁文件已不在即达成目的。
+  }
+}
+
+// ---- 日志轮转 ----
+
+export function rotatePatrolLogs() {
+  // launchd 按路径每次重开文件，轮初改名是安全的：本轮 fd 继续写改名后
+  // 的 inode，下轮打开新文件。
+  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);
+      }
+    } catch {
+      // 轮转失败不阻断巡检。
+    }
+  }
+}
+
+// 保证一个工作区里有一个健康的消费者会话。原地修改 state。
+export async function patrolWorkspace(
+  ws, state, now, leadMs, cur, consumers, scriptProcs = [],
+) {
+  const tasks = deps.readTasks(ws);
+  let ent = state[ws] ?? null;
+
+  if (tasks === null) {
+    // 任务文件读不出：证据太弱，绝不动会话；但不能不吭声——文件还在却读
+    // 不出意味着这个目录的定时任务一个都不会执行。文件已消失则是正常竞
+    // 态（一次性任务执行完被删），不报。
+    if (fs.existsSync(path.join(ws, TASK_REL))) {
+      deps.log(`任务文件读不出 ${ws}：格式损坏或不可读，本轮跳过该目录，`
+        + `其中 ${TASK_REL} 里的定时任务都不会执行`);
+    }
+    return;
+  }
+  if (tasks.length === 0) {
+    // 文件完好但任务清空：一次性任务触发后被删、周期任务过期、或用户手
+    // 删。我们拉起的会话没理由继续留着；用户自己开的会话不在 state 里，
+    // 永不触碰。
+    if (ent !== null) {
+      if (deps.trackedAlive(ent)) {
+        await deps.stopSession(ent);
+        deps.log(`回收 ${ws} pid=${ent.pid}：任务已全部清空，结束保活会话`);
+      }
+      delete state[ws];
+    }
+    return;
+  }
+
+  // 换代：超龄且日志静默（无任务在执行的证据）的会话主动结束，需要时下
+  // 文自然重拉。换代是维护，不计失败。
+  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);
+      deps.log(`换代 ${ws} pid=${ent.pid}：会话已连续运行 `
+        + `${Math.floor(age / 86400)} 天且近期无输出，结束后按需重拉`);
+      delete state[ws];
+      ent = null;
+      mineAlive = false;
+    }
+  }
+
+  // 登记成功即健康证据，当场清零失败计数，不等「有任务想要会话」的轮
+  // 次——健康会话常驻时计数会一直挂着，一次无关死亡就能把陈年计数顶满冷
+  // 却，连一次新尝试都不给。
+  if (ent !== null && mineAlive && consumers.has(ws)) {
+    ent.fails = 0;
+  }
+
+  if (!tasks.some((t) => taskWanted(t, now, leadMs))) return;
+
+  const cooling = Boolean(ent && (ent.cooldownUntil ?? 0) > cur);
+
+  if (consumers.has(ws)) {
+    // 任务正在被消费。区分我们的预热会话与用户的交互会话：前者继续跟踪
+    // （活消费者证明健康 → 计数清零），后者彻底放手。
+    if (ent !== null) {
+      if (mineAlive) {
+        ent.fails = 0;
+        state[ws] = ent;
+      } else if (!cooling) {
+        delete state[ws];
+      }
+    }
+    return;
+  }
+
+  // 活着但没有消费。健康只在真实启动所需的时间内成立；超时就是卡在无人
+  // 应答的提问界面，永不登记——退休它并推进失败计数。
+  if (ent !== null && mineAlive) {
+    const age = cur - (ent.startedAt ?? cur);
+    if (age <= WARMUP_GRACE_SECONDS) return;
+    await deps.stopSession(ent);
+    deps.log(`卡死 ${ws} pid=${ent.pid}：进程已存活 ${age} 秒仍未登记会话，`
+      + '已终止（排查：cron-up logs '
+      + `${path.basename(ws)}）`);
+  }
+
+  if (cooling) return;
+
+  // 没有消费者，我们跟踪的会话（若有）已死或刚作为卡死退休。
+  let fails;
+  if (ent && ent.cooldownUntil) {
+    // 冷却刚结束：给一次干净的缓刑拉起，而不是立刻再次顶满限制。
+    fails = 0;
+  } else {
+    fails = (ent?.fails ?? 0) + (ent ? 1 : 0);
+  }
+
+  if (fails >= FAIL_LIMIT) {
+    state[ws] = {
+      pid: null,
+      fails,
+      cooldownUntil: cur + COOLDOWN_SECONDS,
+    };
+    deps.log(`冷却 ${ws}：仍有任务需要会话，但保活会话连续失败 ${fails} 次，`
+      + `暂停重试 ${COOLDOWN_SECONDS / 60} 分钟`);
+    return;
+  }
+
+  if (ent === null) {
+    // state 里没有记录不等于没有会话：state.json 丢失（手删、purge 时保留
+    // 会话）后进程表里可能还躺着这个工作区的 script 会话，卡在提问界面就
+    // 不会出现在登记里，直接再拉就是同目录双开。认回孤儿，重新纳入正常
+    // 生命周期（卡死的 3 分钟后照退休处理）。
+    const logPath = sessionLogPath(ws);
+    for (const [procPid, procArgs] of scriptProcs) {
+      // alive 复核：快照拍于本轮开头，可能含着刚被换代/回收杀掉的 pid——
+      // 把死人认回来会白记一次失败。
+      if (procArgs.includes(`-q ${logPath} `) && deps.alive(procPid)) {
+        state[ws] = {
+          pid: procPid,
+          startedAt: cur,
+          procStart: deps.procStartedAt(procPid),
+          fails: 0,
+          log: logPath,
+        };
+        deps.log(`接管 ${ws} pid=${procPid}：state 记录缺失，但进程表里仍有`
+          + '本工作区的保活会话，重新纳入跟踪');
+        return;
+      }
+    }
+  }
+
+  const { pid, procStart } = deps.spawnSession(ws);
+  state[ws] = {
+    pid,
+    startedAt: cur,
+    procStart,
+    fails,
+    log: sessionLogPath(ws),
+  };
+  deps.log(`已启动 ${ws} pid=${pid}（连续失败计数 ${fails}）`);
+}
+
+// 跑一轮巡检；抢不到锁返回 false。
+export async function cmdRun(args) {
+  const lock = deps.acquireRunLock();
+  if (lock === null) {
+    deps.log('已有一轮巡检在进行，本轮跳过');
+    return false;
+  }
+  try {
+    deps.rotatePatrolLogs();
+    const cfg = loadConfig(args?.config ?? deps.paths.configPath);
+    if (!isInt(cfg.leadSeconds) || cfg.leadSeconds < 0) {
+      deps.printErr('配置错误：leadSeconds 必须是非负整数秒，当前为 '
+        + `${cfg.leadSeconds}`);
+      throw new ExitError(2);
+    }
+    const now = new Date();
+    const leadMs = cfg.leadSeconds * 1000;
+    const state = loadState();
+    if (cfg.roots.length === 0) {
+      deps.log('警告：扫描目录 roots 为空，巡检不会发现任何工作区；'
+        + '请检查配置文件或用 install --roots 指定');
+    }
+
+    const cur = Math.floor(Date.now() / 1000);
+    // 登记每轮只读一次：否则每个工作区都要 readdir + ps 一遍，自检也归
+    // 属这里。
+    const [consumers, registryAlert] = await deps.scanSessions();
+    if (registryAlert) deps.log(`告警：${registryAlert}`);
+    const scriptProcs = deps.listScriptProcesses();
+
+    for (const [ws, taskfile] of deps.discover(cfg.roots, cfg.maxDepth)) {
+      // 一个工作区读不动不能中断整轮：discover 是生成器，这里抛了会跳过
+      // 后面所有工作区。续期与保活各自独立守卫——续期失败绝不压制该工作
+      // 区的会话保活。
+      if (cfg.autoRenew) {
+        try {
+          const n = renewWorkspace(taskfile);
+          if (n) {
+            deps.log(`已续期 ${ws}：${n} 个周期任务标记为 permanent，`
+              + '不再受 7 天过期限制');
+          }
+        } catch (e) {
+          if (e instanceof TaskFileChanged) {
+            deps.log(`续期暂缓 ${ws}：任务文件刚被 Claude Code 改动，`
+              + '本轮不覆盖，下轮再续');
+          } else {
+            deps.log(`续期错误 ${ws}：${e.constructor.name}：${e.message}`);
+          }
+        }
+      }
+      try {
+        await patrolWorkspace(
+          ws, state, now, leadMs, cur, consumers, scriptProcs);
+      } catch (e) {
+        deps.log(`错误 ${ws}：${e.constructor.name}：${e.message}`);
+      }
+    }
+
+    // 丢掉已死且不处冷却的条目；保留冷却与活会话。
+    const kept = Object.fromEntries(
+      Object.entries(state).filter(([, ent]) =>
+        deps.trackedAlive(ent) || (ent.cooldownUntil ?? 0) > cur),
+    );
+    saveState(kept);
+    return true;
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+// 立即给所有周期任务补 permanent。忽略 cfg.autoRenew——手动跑命令本身就
+// 是显式指令。与巡检共用同一把锁。
+export async function cmdRenew(args) {
+  const lock = deps.acquireRunLock();
+  if (lock === null) {
+    deps.print('已有一轮巡检（或另一次 renew）在进行，请稍后重试');
+    return;
+  }
+  try {
+    const cfg = loadConfig(args?.config ?? deps.paths.configPath);
+    let files = 0;
+    let tagged = 0;
+    let unchanged = 0;
+    const skipped = [];
+    for (const [ws, taskfile] of deps.discover(cfg.roots, cfg.maxDepth)) {
+      files += 1;
+      let n;
+      try {
+        n = renewWorkspace(taskfile);
+      } catch (e) {
+        if (e instanceof TaskFileChanged) {
+          deps.print(`暂缓 ${ws}：任务文件刚被 Claude Code 改动，本次未写入，`
+            + '可再跑一次');
+          skipped.push(ws);
+          continue;
+        }
+        deps.print(`跳过 ${ws}：（${e.constructor.name}：${e.message}）`);
+        skipped.push(ws);
+        continue;
+      }
+      if (n === null) {
+        deps.print(`跳过 ${ws}：任务文件读不出或格式损坏`);
+        skipped.push(ws);
+      } else if (n) {
+        tagged += n;
+        deps.print(`已续期 ${ws}：${n} 个周期任务标记为 permanent`);
+      } else {
+        unchanged += 1;
+        deps.print(`已是最新 ${ws}：周期任务均已 permanent，无需改动`);
+      }
+    }
+    deps.print('');
+    let line = `扫描 ${files} 个任务文件：本次续期 ${tagged} 个任务，`
+      + `${unchanged} 个文件无需改动`;
+    if (skipped.length) line += `，${skipped.length} 个跳过`;
+    deps.print(line);
+    if (tagged) {
+      deps.print('这些周期任务此后不再受 7 天过期限制；为它们保活的后台会话'
+        + '会长期常驻。');
+    }
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+Object.assign(deps, {
+  log,
+  runPatrol: cmdRun,
+  rotatePatrolLogs,
+  acquireRunLock,
+});