cron-up 26.9.1

package/src/constants.mjs

@@ -0,0 +1,57 @@
+// 全部调参常量集中一处，改动时便于通盘核对。
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  // 默认扫家目录（两层深覆盖 ~/<root>/<workspace>）；安装时可用 roots 收窄。
+  roots: ['~'],
+  maxDepth: 2,
+  intervalSeconds: 300,
+  leadSeconds: 600,
+  // 每轮巡检给周期任务补 permanent 标记，绕开 Claude Code 的 7 天周期任务
+  // 过期。loadConfig 会用默认值补缺键，所以安装或升级后的首轮会把旧任务
+  // 全部补标。配置里 autoRenew:false 可关（下轮生效），或安装时
+  // --no-auto-renew。
+  autoRenew: true,
+};
+
+// 预热会话连续三次启动后死亡，大概率是环境坏了（缺信任、env 不对），退避
+// 而不是每 5 分钟无限重拉。
+export const FAIL_LIMIT = 3;
+export const COOLDOWN_SECONDS = 1800;
+// pid 合法值域。state.json 与会话登记两个外部来源都在入口处按它校验：
+// 超大整数能穿过类型转换，直到 process.kill 才抛，所以必须入口卡范围。
+export const PID_T_MAX = 2 ** 31 - 1;
+// 健康会话约 10 秒内完成登记。超时仍存活却没登记，是卡在无人应答的提问
+// 界面（目录信任、工具授权）；只看存活会把它当健康，只有这个时限兜得住。
+export const WARMUP_GRACE_SECONDS = 180;
+// 预热会话是缓存不是宠物：「永久」任务让它无限常驻会把它钉死在启动当天的
+// claude 版本和不断增长的 typescript 上。超龄会话仅在日志静默一段时间后
+// 才退役——日志安静是没有任务在执行的证据，运行中的任务绝不会被切掉。
+export const SESSION_MAX_AGE_SECONDS = 7 * 86400;
+export const SESSION_IDLE_SECONDS = 3600;
+// TUI typescript 是全屏渲染流，长驻时无限增长，拉起时轮转（script(1) 打开
+// 即截断，所以轮转粒度是一个预热会话的生命周期）。
+export const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+// 巡检日志每轮几行，但跑几年的机器也该有上限。launchd 每次按路径重开，
+// 轮初改名是安全的：本轮 fd 继续写改名后的 inode，下轮开新文件。
+export const PATROL_LOG_ROTATE_BYTES = 1024 * 1024;
+
+// 不进入这些目录：VCS/依赖内部与 macOS 家目录系统文件夹——agent 工作区不
+// 会在里面，光一个 ~/Library 就足以让家目录扫描爆炸。
+export const PRUNE_DIRS = new Set([
+  '.git', 'node_modules',
+  'Library', 'Applications', 'Desktop', 'Documents', 'Downloads',
+  'Movies', 'Music', 'Pictures', 'Public', '.Trash',
+  '.cache', '.npm', '.local', '.config',
+]);
+
+// 定时任务 7 天过期（周期任务被调度器删除，一次性任务早就触发过），巡检
+// 不需要看得更远。展示页另算。
+export const SEARCH_DAYS = 7;
+// list/总览回答「下次何时触发」，要看到一年后：年度任务必须显示真实日期，
+// 不能误报成「无安排」。nextAfter 的日历快进让长窗口依然便宜。
+export const DISPLAY_SEARCH_DAYS = 366;
+// 补执行检测从任务创建时间向前搜，需要独立的上界。
+export const MISSED_LOOKBACK_DAYS = 30;
+// list 问「一次性任务是否被错过」，与巡检同一个补执行判定，只是不带前瞻。
+export const ZERO_LEAD_MS = 0;

package/src/cron.mjs

@@ -0,0 +1,186 @@
+// 分钟级 cron 解析与下一次触发计算。字段全是别的程序写的，畸形表达式在
+// 边界处返回 null/不可满足，绝不抛进巡检循环。
+
+import { SEARCH_DAYS, MISSED_LOOKBACK_DAYS } from './constants.mjs';
+
+const MS_DAY = 86400_000;
+const MS_MINUTE = 60_000;
+
+// 严格十进制整数：parseInt("5x") 会静默返回 5，必须自己卡。仅接受可选负号
+// 加纯数字。
+function strictInt(s) {
+  if (!/^-?\d+$/.test(s)) throw new Error(`不是整数：${s}`);
+  return parseInt(s, 10);
+}
+
+// 解析一个 cron 字段为它命名的合法值域集合。
+// 越界值丢弃而非报错：typo "99" 读作「该字段不匹配任何值」（由
+// satisfiable 浮出），而不是炸掉解析或静默匹配到不该匹配的分钟。
+export function parseCronField(expr, lo, hi) {
+  const values = new Set();
+  for (const token of expr.split(',')) {
+    let rng;
+    let step;
+    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');
+    } else {
+      rng = token;
+      step = 1;
+    }
+    let start;
+    let end;
+    if (rng === '*') {
+      start = lo;
+      end = hi;
+    } else if (rng.includes('-')) {
+      const [a, b] = rng.split('-');
+      start = strictInt(a);
+      end = strictInt(b);
+    } else {
+      start = end = strictInt(rng);
+      if (slash >= 0) end = hi; // vixie："5/10" 表示 5,15,25,… 直到 hi
+    }
+    for (let v = start; v <= end; v += step) {
+      if (v >= lo && v <= hi) values.add(v);
+    }
+  }
+  return values;
+}
+
+export class Cron {
+  constructor(expr) {
+    if (typeof expr !== 'string') throw new Error('cron 表达式必须是字符串');
+    const parts = expr.trim().split(/\s+/); // 折叠任意空白
+    if (parts.length !== 5) throw new Error(`cron 字段数应为 5：${expr}`);
+    const [m, h, dom, mon, dow] = parts;
+    this.minutes = parseCronField(m, 0, 59);
+    this.hours = parseCronField(h, 0, 23);
+    this.doms = parseCronField(dom, 1, 31);
+    this.months = parseCronField(mon, 1, 12);
+    // 先在 0..7 范围解析（0 和 7 都表示周日）再折叠。折叠必须发生在集合
+    // 展开之后：文本上把 "7" 替成 "0" 会把正常区间 "1-7" 变成反向的
+    // "1-0"，解析为空集后任务静默永不触发。
+    this.dows = new Set([...parseCronField(dow, 0, 7)].map((v) => v % 7));
+    this.domRestricted = dom !== '*';
+    this.dowRestricted = dow !== '*';
+    // 每字段非空只是必要条件（2 月 30 日依旧永不匹配）；这个标记只识别
+    // 任何一分钟都不可能匹配的表达式，它们值得一句响亮的「cron 无效」，
+    // 而不是看起来像「没有安排」。
+    this.satisfiable = Boolean(
+      this.minutes.size && this.hours.size && this.doms.size
+        && this.months.size && this.dows.size,
+    );
+  }
+
+  // Date 的 getDay() 本身就是周日=0，与 cron 同构，无需额外换算。
+  matches(t) {
+    if (!this.minutes.has(t.getMinutes()) || !this.hours.has(t.getHours())) {
+      return false;
+    }
+    if (!this.months.has(t.getMonth() + 1)) return false;
+    if (this.domRestricted && this.dowRestricted) {
+      // DoM 与 DoW 同时受限时是 vixie 的 OR 语义：命中其一即可。
+      return this.doms.has(t.getDate()) || this.dows.has(t.getDay());
+    }
+    return this.doms.has(t.getDate()) && this.dows.has(t.getDay());
+  }
+
+  // 严格晚于 after 的下一次触发；withinDays 内没有则 null。不可满足的表达
+  // 式也返回 null。
+  nextAfter(after, withinDays = SEARCH_DAYS) {
+    if (!this.satisfiable) return null;
+    const t = new Date(after.getTime());
+    t.setSeconds(0, 0);
+    t.setMinutes(t.getMinutes() + 1);
+    const deadline = after.getTime() + withinDays * MS_DAY;
+    while (t.getTime() <= deadline) {
+      // 日历快进：跳过不可能匹配的整月、整小时，再逐分钟扫描。跳过的都
+      // 是 matches 会拒绝的时刻，结果与朴素扫描完全一致；一年窗口从约
+      // 5·10⁵ 次迭代降到 ~10⁴，DISPLAY_SEARCH_DAYS 因此可行。
+      if (!this.months.has(t.getMonth() + 1)) {
+        t.setTime(new Date(t.getFullYear(), t.getMonth() + 1, 1).getTime());
+        continue;
+      }
+      if (!this.hours.has(t.getHours())) {
+        t.setHours(t.getHours() + 1, 0, 0, 0);
+        continue;
+      }
+      if (this.matches(t)) return t;
+      t.setMinutes(t.getMinutes() + 1);
+    }
+    return null;
+  }
+}
+
+// CronCreate 产生的一次性任务形状像 'M H DoM Mon *'，作为没有 recurring
+// 标志时的兜底识别法。
+export function cronLooksOneshot(expr) {
+  const parts = expr.split(/\s+/);
+  return parts.length === 5 && parts[4] === '*'
+    && parts.slice(0, 4).every((p) => /^\d+$/.test(p));
+}
+
+export function taskIsOneshot(task) {
+  // 调度器会写显式 recurring 标志，优先信它；手写任务文件才退回形状识别。
+  if ('recurring' in task) return !Boolean(task.recurring);
+  try {
+    return cronLooksOneshot(task.cron);
+  } catch {
+    return false;
+  }
+}
+
+// 解析 cron；任何畸形都返回 null，不把异常抛给调用方。展示页与巡检共用
+// 这一个入口，两边不必各自抄一遍异常元组。
+export function parseCronOrNone(expr) {
+  try {
+    return new Cron(expr);
+  } catch {
+    return null;
+  }
+}
+
+function createdAtDate(task) {
+  const v = task.createdAt;
+  if (!v || typeof v !== 'number') return null;
+  const d = new Date(v); // 字段是毫秒时间戳
+  return Number.isFinite(d.getTime()) ? d : null;
+}
+
+// 在已解析的 cron 上判定：这个任务现在是否需要一个已预热的会话。
+function wanted(cron, task, now, leadMs) {
+  const nxt = cron.nextAfter(now);
+  if (nxt && nxt.getTime() <= now.getTime() + leadMs) return true;
+  // 首次触发已过却仍在文件里：一次性任务意味着没有 REPL 运行时被错过
+  // （重启/睡眠）。原生机制会在会话启动时补执行一次再删除它。
+  if (taskIsOneshot(task)) {
+    const created = createdAtDate(task);
+    if (!created) return false;
+    // 从创建时间向前搜，而不是从现在。跨度要封顶：表达式永不匹配的陈旧
+    // 条目否则会逐分钟扫到创建之初。一次性任务都在触发前不久创建，封顶
+    // 不会漏掉真实条目，超过上界的早就死透了。
+    const span = Math.min(
+      Math.floor((now.getTime() - created.getTime()) / MS_DAY) + 1,
+      MISSED_LOOKBACK_DAYS,
+    );
+    const first = cron.nextAfter(
+      new Date(created.getTime() - MS_MINUTE),
+      span,
+    );
+    if (first && first.getTime() <= now.getTime()) return true;
+  }
+  return false;
+}
+
+// 任务是否需要已预热的会话。任务字段全是别的程序写的，畸形条目读作「不
+// 需要」，绝不能让一个坏条目中断整轮巡检。
+export function taskWanted(task, now, leadMs) {
+  const cron = parseCronOrNone(task?.cron);
+  return cron !== null && wanted(cron, task, now, leadMs);
+}
+
+// wanted 供展示视图复用（同一个已解析 cron 顺带回答巡检问题）。
+export { wanted };

package/src/display.mjs

@@ -0,0 +1,103 @@
+// 等宽终端展示原语与任务的展示视图。
+
+import { isWide } from './east-asian-width.mjs';
+import { parseCronOrNone, taskIsOneshot, wanted } from './cron.mjs';
+import { DISPLAY_SEARCH_DAYS, ZERO_LEAD_MS } from './constants.mjs';
+
+// 等宽终端里的显示宽度：东亚宽字符（中文、全角标点）占两列。
+export function dispWidth(s) {
+  let n = 0;
+  for (const ch of String(s)) n += isWide(ch.codePointAt(0)) ? 2 : 1;
+  return n;
+}
+
+// 按显示宽度截断，尾部用省略号 … 占位。
+export function clip(s, width) {
+  width = Math.max(0, width);
+  s = String(s);
+  if (dispWidth(s) <= width) return s;
+  // 省略号 U+2026 在多数终端占 1 列（Ambiguous），按 2 列预留只是更保守，
+  // 结果总宽保证不超过 width。
+  const keep = width - 2;
+  let out = '';
+  let used = 0;
+  for (const ch of s) {
+    const w = isWide(ch.codePointAt(0)) ? 2 : 1;
+    if (used + w > keep) break;
+    out += ch;
+    used += w;
+  }
+  return `${out}…`;
+}
+
+export function pad(s, width) {
+  return s + ' '.repeat(Math.max(0, width - dispWidth(s)));
+}
+
+// 倒计时的粗略中文说法，只用于总览页。ms 为非负毫秒差。
+export function humanDelta(ms) {
+  const secs = Math.max(0, Math.floor(ms / 1000));
+  if (secs < 60) return '不到 1 分钟';
+  if (secs < 3600) return `${Math.floor(secs / 60)} 分钟后`;
+  if (secs < 86400) return `${Math.floor(secs / 3600)} 小时后`;
+  return `${Math.floor(secs / 86400)} 天后`;
+}
+
+// list/总览上代表任务身份的一句话：prompt 的首个非空行。真实任务第一行
+// 通常自带标题；取不到时如实标注，不留空白格。
+export 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) ?? '';
+  return first.replace(/\s+/g, ' ');
+}
+
+// 把一个任务整理成展示数据。字段来自别的程序写的文件，畸形也不抛。
+// 传 leadMs 时顺带在同一个已解析 cron 上回答「现在是否需要预热会话」
+// （wanted），总览页就不必为同一任务再解析一遍 cron。
+export function taskView(task, now, leadMs = undefined) {
+  const expr = task?.cron;
+  const cron = parseCronOrNone(expr);
+  if (cron === null || !cron.satisfiable) {
+    // 解析失败，或字段越界/反向区间导致集合为空：任何分钟都不可能匹配。
+    // 区别于「合法但展示窗口内没有触发点」（如 2 月 30 日，解析正常却
+    // 永不触发）。
+    return {
+      valid: false,
+      expr,
+      summary: taskSummary(task),
+      permanent: false,
+      wanted: 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);
+  return {
+    valid: true,
+    nxt,
+    missed,
+    kind: oneshot ? '一次性' : '周期',
+    permanent: Boolean(task.permanent) && !oneshot,
+    cadence: typeof expr === 'string' ? expr : String(expr),
+    summary: taskSummary(task),
+    // wanted 恒为 null 或布尔：没传 leadMs（不问）与 cron 无效（问不了）
+    // 都是 null，键的形状不随参数变化。
+    wanted: leadMs !== undefined ? wanted(cron, task, now, leadMs) : null,
+  };
+}
+
+// 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())}`;
+}
+
+// 会话年龄的粗粒度中文：长驻按天计，否则按分钟。
+export function sessionAgeZh(startedAt, cur) {
+  const secs = Math.max(0, cur - startedAt);
+  if (secs >= 86400) return `${Math.floor(secs / 86400)} 天`;
+  return `${Math.floor(secs / 60)} 分钟`;
+}

package/src/east-asian-width.mjs

@@ -0,0 +1,40 @@
+// 本文件由 scripts/gen-east-asian-width.mjs 生成，请勿手改。
+// 数据：Unicode East_Asian_Width 的 W/F 码点区间（Unicode 18.0.0，2026-06-29, 15:25:05 GMT）。
+// Ambiguous 字符（如 U+2026 省略号）不在表中，按 1 列计。
+// 共 126 个连续区间，二分查找。
+
+const WIDE_RANGES = [
+  [4352,4447],[8986,8987],[9001,9002],[9193,9196],[9200],[9203],
+  [9725,9726],[9748,9749],[9776,9783],[9800,9811],[9855],[9866,9871],
+  [9875],[9889],[9898,9899],[9917,9918],[9924,9925],[9934],
+  [9940],[9962],[9970,9971],[9973],[9978],[9981],
+  [9989],[9994,9995],[10024],[10060],[10062],[10067,10069],
+  [10071],[10133,10135],[10160],[10175],[11035,11036],[11088],
+  [11093],[11904,11929],[11931,12019],[12032,12245],[12272,12350],[12353,12438],
+  [12441,12543],[12549,12591],[12593,12686],[12688,12773],[12783,12830],[12832,12871],
+  [12880,42124],[42128,42182],[43360,43388],[44032,55203],[63744,64255],[65040,65049],
+  [65072,65106],[65108,65126],[65128,65131],[65281,65376],[65504,65510],[94176,94180],
+  [94192,94198],[94208,101594],[101631,101664],[101760,101874],[101888,102801],[102816,102866],
+  [110576,110579],[110581,110587],[110589,110590],[110592,110888],[110898],[110928,110930],
+  [110933],[110948,110952],[110960,111355],[119552,119638],[119648,119670],[126980],
+  [127183],[127374],[127377,127386],[127406],[127488,127490],[127504,127547],
+  [127552,127560],[127568,127569],[127584,127589],[127744,127776],[127789,127797],[127799,127868],
+  [127870,127891],[127904,127946],[127951,127955],[127968,127984],[127988],[127992,128062],
+  [128064],[128066,128252],[128255,128317],[128331,128334],[128336,128359],[128378],
+  [128405,128406],[128420],[128507,128591],[128640,128709],[128716],[128720,128722],
+  [128725,128729],[128732,128735],[128747,128748],[128756,128764],[128986],[128992,129003],
+  [129008],[129292,129338],[129340,129349],[129351,129535],[129648,129660],[129664,129734],
+  [129736],[129740,129757],[129759,129771],[129775,129786],[131072,196605],[196608,262141]
+];
+
+export function isWide(cp) {
+  let lo = 0, hi = WIDE_RANGES.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const [a, b] = WIDE_RANGES[mid];
+    if (cp < a) hi = mid - 1;
+    else if (cp > (b ?? a)) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}

package/src/index.mjs

@@ -0,0 +1,13 @@
+// 全量副作用入口：import 全部业务模块，触发它们向 deps 容器自注册。CLI 与
+// 测试都先 import 这里，保证 deps 上的可替换函数一个不缺（internals 不反向
+// 依赖业务模块，单独 import 某个模块时其同侪可能尚未注册）。
+
+import './tasks.mjs';
+import './config.mjs';
+import './sessions.mjs';
+import './registry.mjs';
+import './patrol.mjs';
+import './service.mjs';
+import './logs.mjs';
+import './overview.mjs';
+import './list.mjs';

package/src/internals.mjs

@@ -0,0 +1,64 @@
+// 可替换依赖容器：ESM 命名导出不可改，测试无法事后打桩，因此把所有要替换
+// 的外部依赖集中到 deps。业务模块在文件末尾 Object.assign(deps, {...})
+// 自注册（internals 不反向 import 业务模块，避免循环依赖）；cli 先 import
+// 全量入口保证注册完成后再 dispatch。
+//
+// 纯系统叶子的默认实现放这里；业务函数（discover、spawnSession…）由各自
+// 模块注册。
+
+import { spawn, spawnSync, execFileSync } from 'node:child_process';
+import { paths } from './paths.mjs';
+
+export class ExitError extends Error {
+  // CLI 入口捕获后按 code 退出。
+  constructor(code, message) {
+    super(message);
+    this.name = 'ExitError';
+    this.code = code;
+  }
+}
+
+// 非 0 退出不抛：调用 ps/launchctl 的地方只关心 status 与输出，抛了反而
+// 要在每个调用点 catch。返回 {status, stdout, stderr}。
+function execFile(file, args, opts = {}) {
+  try {
+    const stdout = execFileSync(file, args, {
+      // execFileSync 的默认 stdio 会让非零退出子进程的 stderr 继承父进程
+      // （launchctl print 未加载服务时错误会直接糊到终端），显式 pipe 住。
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+      encoding: 'utf-8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    return { status: 0, stdout: stdout ?? '', stderr: '' };
+  } catch (e) {
+    // launchctl bootout 找不到服务等：exit 非零但输出在 stderr。
+    if (e && typeof e === 'object' && 'status' in e) {
+      return {
+        status: e.status ?? 1,
+        stdout: typeof e.stdout === 'string' ? e.stdout : '',
+        stderr: typeof e.stderr === 'string' ? e.stderr : '',
+      };
+    }
+    if (e && typeof e === 'object' && (e.code === 'ENOENT' || e.code === 'EACCES'
+        || e.code === 'ETIMEDOUT')) {
+      return { status: 1, stdout: '', stderr: e.message ?? String(e) };
+    }
+    throw e;
+  }
+}
+
+function terminalWidth() {
+  return Math.max(60, process.stdout.columns ?? 100);
+}
+
+export const deps = {
+  paths,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  print: (...args) => process.stdout.write(`${args.join(' ')}\n`),
+  printErr: (...args) => process.stderr.write(`${args.join(' ')}\n`),
+  terminalWidth,
+  execFile,
+  spawn,
+  spawnSync,
+};

package/src/list.mjs

@@ -0,0 +1,100 @@
+// `cron-up list`：逐工作区列出任务的下次触发、节奏、类型与摘要，标注
+// 该目录当前有没有交互会话。
+
+import { deps } from './internals.mjs';
+import { loadConfig } from './config.mjs';
+import {
+  clip,
+  pad,
+  dispWidth,
+  taskView,
+  fmtMDHM,
+} from './display.mjs';
+
+function rank(v) {
+  if (!v.valid) return 3;
+  if (v.missed) return 0;
+  return v.nxt ? 1 : 2;
+}
+
+export async function cmdList(args) {
+  const cfg = loadConfig(args?.config ?? deps.paths.configPath);
+  const now = new Date();
+  const cols = deps.terminalWidth();
+  const blocks = [];
+  let total = 0;
+  let filesSeen = 0;
+  let unreadable = 0;
+  const [consumers] = await deps.scanSessions();
+  for (const [ws] of deps.discover(cfg.roots, cfg.maxDepth)) {
+    filesSeen += 1;
+    const tasks = deps.readTasks(ws);
+    if (tasks === null) {
+      // 读不出不等于空：损坏时如实说任务不会执行。
+      unreadable += 1;
+      continue;
+    }
+    if (tasks.length === 0) continue;
+    const views = tasks.map((t) => taskView(t, now));
+    // 错过待补执行排最前，然后按下次时间升序，一年内无安排的垫底，无效
+    // 的最后。
+    views.sort((a, b) => rank(a) - rank(b)
+      || ((a.nxt?.getTime() ?? Infinity) - (b.nxt?.getTime() ?? Infinity)));
+    blocks.push([ws, consumers.has(ws), views]);
+    total += tasks.length;
+  }
+
+  if (blocks.length === 0) {
+    if (filesSeen === 0) {
+      deps.print('配置的扫描目录下没有发现定时任务文件');
+    } else if (unreadable === filesSeen) {
+      deps.print(`发现 ${filesSeen} 个任务文件，全部读不出：其中的定时任务一个`
+        + '都不会执行');
+    } else {
+      const tail = unreadable ? `，其中 ${unreadable} 个读不出` : '';
+      deps.print(`发现 ${filesSeen} 个任务文件${tail}，其余的任务列表均为空`);
+    }
+    return;
+  }
+
+  blocks.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  deps.print(`共 ${blocks.length} 个工作区、${total} 个定时任务`);
+
+  // 列宽从全部候选文案动态算（时间戳 "09-25 08:30" 恒为 11 列），改文案
+  // 不会静默错位；cadence 是截断列，取固定上限。
+  const statusW = Math.max(11,
+    ...['cron 无效', '已错过', '一年内无'].map(dispWidth));
+  const kindW = Math.max(...['一次性', '周期', '周期·永久'].map(dispWidth)) + 1;
+  const cadW = 16;
+  // "  " + status + "  " + kind + "  " + cadence + "  " + summary
+  const summaryW = Math.max(12,
+    cols - (2 + statusW + 2 + kindW + 2 + cadW + 2));
+  for (const [ws, consumer, views] of blocks) {
+    deps.print('');
+    const label = consumer ? '交互会话：有' : '交互会话：无';
+    const pathW = cols - dispWidth(label) - 1;
+    deps.print(`${pad(clip(ws, pathW), pathW)} ${label}`);
+    for (const v of views) {
+      let status;
+      let kind;
+      let cadence;
+      let summary;
+      if (!v.valid) {
+        status = 'cron 无效';
+        kind = '—';
+        cadence = '—';
+        summary = `原字段值：${JSON.stringify(v.expr)}；${v.summary}`;
+      } else {
+        // 已错过：一次性任务触发点已过，下次会话启动时补执行。missed 时
+        // permanent 恒为 false（taskView 对一次性任务剔除了该标记）。
+        status = v.missed ? '已错过'
+          : (v.nxt ? fmtMDHM(v.nxt) : '一年内无');
+        kind = v.permanent ? '周期·永久' : v.kind;
+        cadence = v.cadence;
+        summary = v.summary;
+      }
+      deps.print('  ' + pad(status, statusW) + '  ' + pad(kind, kindW) + '  '
+        + pad(clip(cadence, cadW), cadW) + '  ' + clip(summary, summaryW));
+    }
+  }
+}

package/src/logs.mjs

@@ -0,0 +1,75 @@
+// `cron-up logs`：选日志文件并交给 tail。默认看巡检日志（它回答「最
+// 近怎么样」），stderr 只是崩溃收集处，不能因为一次旧故障盖住此后所有健
+// 康的巡检轮次。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { deps, ExitError } from './internals.mjs';
+import { onDiskCase } from './tasks.mjs';
+import { sessionLogPath } from './sessions.mjs';
+
+export function resolveLogPath(workspace, announce) {
+  const say = announce ?? ((m) => deps.printErr(m));
+  if (workspace) {
+    if (path.isAbsolute(workspace)) {
+      // 日志名由工作区路径折成，而 spawn 记的是 discover 规范化后的真实
+      // 大小写：敲错大小写的绝对路径必须认回同一个文件。
+      let real;
+      try {
+        real = fs.realpathSync(workspace);
+      } catch {
+        real = workspace;
+      }
+      const file = sessionLogPath(onDiskCase(real));
+      return fs.existsSync(file) ? file : null;
+    }
+    // 只匹配当前日志（*.log）：.log.1 若参与匹配，轮转过一次的工作区会永
+    // 远被报成「匹配到多个」。
+    let matches = [];
+    try {
+      matches = fs.readdirSync(deps.paths.sessionLogDir)
+        .filter((f) => f.endsWith('.log'))
+        .map((f) => path.join(deps.paths.sessionLogDir, f))
+        .filter((f) => path.basename(f).includes(workspace));
+    } catch {
+      matches = [];
+    }
+    if (matches.length > 1) {
+      say(`'${workspace}' 匹配到多个会话日志，请给出更长的片段：`);
+      for (const f of matches.sort()) say(`  ${path.basename(f)}`);
+      throw new ExitError(1);
+    }
+    return matches[0] ?? null;
+  }
+
+  const out = path.join(deps.paths.logDir, 'launchd.out.log');
+  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}），巡检若异常先看它`);
+    }
+  } catch {
+    // err 不存在：无事。
+  }
+  return out;
+}
+
+export function cmdLogs(args) {
+  const file = resolveLogPath(args.workspace);
+  if (!file) {
+    deps.printErr(`在 ${deps.paths.sessionLogDir} 中找不到与`
+      + `「${args.workspace}」匹配的会话日志`);
+    throw new ExitError(1);
+  }
+  const tailArgs = args.follow ? ['-f'] : ['-n', '100'];
+  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);
+}