cc-viewer 1.9.12 → 1.9.14

package/server/lib/cron.js

@@ -0,0 +1,181 @@
+// Minimal 5-field cron parser + next-run computation, local timezone.
+//
+// Scope (deliberately small — this backs the scheduled-task feature, not a
+// general cron service):
+//   - fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-7, 7=Sunday)
+//   - syntax: `*`, `a`, `a-b`, `*/n`, `a-b/n`, comma lists of those. No names (JAN/MON).
+//   - vixie DOM/DOW OR semantics: when BOTH dom and dow are restricted, a day matches
+//     if either matches; otherwise both must match (an unrestricted side = full range).
+//   - `*/n` counts as RESTRICTED (not a star) for the DOM/DOW OR rule.
+//
+// Invariants nextCronRun MUST keep (review P1-5 — violating any of these causes a
+// claim loop or a double fire):
+//   1. The result is STRICTLY greater than `afterMs` (never equal), so callers that
+//      recompute `next` from the previous occurrence always move forward.
+//   2. Spring-forward: a local wall time that does not exist (e.g. 02:30 on the DST
+//      jump day) is SKIPPED, not "rolled over" — we read back the constructed Date's
+//      fields and reject the candidate when they differ from what we asked for.
+//   3. Fall-back: a repeated wall time resolves (via `new Date`) to its FIRST
+//      occurrence; it fires at most once. When `after` already sits at/after that
+//      first occurrence, the day is not double-counted.
+
+const MIN = 60 * 1000;
+
+const FIELD_DEFS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'dom', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'dow', min: 0, max: 7 }, // 7 normalized to 0 (Sunday)
+];
+
+/** Parse one field into { values:Set<number>, restricted:boolean }. */
+function _parseField(text, def) {
+  const values = new Set();
+  let restricted = false;
+  const add = (v) => {
+    if (v < def.min || v > def.max) throw new Error(`${def.name} out of range: ${v}`);
+    values.add(def.name === 'dow' && v === 7 ? 0 : v); // 7 → Sunday(0)
+  };
+  for (const part of String(text).split(',')) {
+    if (!part) throw new Error(`${def.name}: empty list item`);
+    const stepMatch = /^(.+)\/(\d+)$/.exec(part);
+    const stepBase = stepMatch ? stepMatch[1] : part;
+    const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+    if (!Number.isInteger(step) || step < 1) throw new Error(`${def.name}: bad step ${stepMatch?.[2]}`);
+    if (stepBase === '*') {
+      restricted = restricted || !!stepMatch; // `*` alone = full range; `*/n` = restricted
+      for (let v = def.min; v <= def.max; v += step) add(v);
+      continue;
+    }
+    restricted = true;
+    const rangeMatch = /^(\d+)-(\d+)$/.exec(stepBase);
+    if (rangeMatch) {
+      const lo = parseInt(rangeMatch[1], 10);
+      const hi = parseInt(rangeMatch[2], 10);
+      if (lo > hi) throw new Error(`${def.name}: reversed range ${lo}-${hi}`);
+      for (let v = lo; v <= hi; v += step) add(v);
+      continue;
+    }
+    if (/^\d+$/.test(stepBase)) {
+      const single = parseInt(stepBase, 10);
+      if (stepMatch) {
+        // `a/n`: vixie treats as `a-max/n`.
+        for (let v = single; v <= def.max; v += step) add(v);
+      } else {
+        add(single);
+      }
+      continue;
+    }
+    throw new Error(`${def.name}: unsupported token "${stepBase}"`);
+  }
+  if (values.size === 0) throw new Error(`${def.name}: no values`);
+  return { values, restricted };
+}
+
+/**
+ * Parse a 5-field cron expression.
+ * Returns { ok:true, fields:[{values,restricted}×5], source } or { ok:false, error }.
+ */
+export function parseCron(expr) {
+  if (typeof expr !== 'string') return { ok: false, error: 'not a string' };
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return { ok: false, error: `expected 5 fields, got ${parts.length}` };
+  try {
+    const fields = parts.map((p, i) => _parseField(p, FIELD_DEFS[i]));
+    return { ok: true, fields, source: expr.trim() };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+/**
+ * Does `date` match the parsed expression (local time)? dom/dow use the vixie OR rule.
+ * `fields` is the array from parseCron(...).fields.
+ */
+export function cronMatchesFields(fields, date) {
+  const minute = date.getMinutes();
+  const hour = date.getHours();
+  const dom = date.getDate();
+  const month = date.getMonth() + 1;
+  const dow = date.getDay();
+  if (!fields[0].values.has(minute)) return false;
+  if (!fields[1].values.has(hour)) return false;
+  if (!fields[3].values.has(month)) return false;
+  const domF = fields[2];
+  const dowF = fields[4];
+  const domHit = domF.values.has(dom);
+  const dowHit = dowF.values.has(dow);
+  if (domF.restricted && dowF.restricted) return domHit || dowHit; // vixie OR
+  return domHit && dowHit;
+}
+
+/** Convenience: parse + match. Returns false on parse error. */
+export function cronMatches(expr, date) {
+  const p = parseCron(expr);
+  if (!p.ok) return false;
+  return cronMatchesFields(p.fields, date);
+}
+
+/**
+ * Next fire time STRICTLY after `afterMs` (local time). Returns epoch ms, or null when
+ * no solution within ~5 years. Minute granularity.
+ *
+ * Strategy: iterate day-by-day from the day after `after`'s day when needed, but jump
+ * straight to the next matching time-of-day within a matching day. We never scan
+ * minute-by-minute, so even `* * * * *` over a 30-day sleep is ~30 iterations.
+ */
+export function nextCronRun(expr, afterMs) {
+  const p = typeof expr === 'string' ? parseCron(expr) : expr;
+  if (!p || p.ok === false) return null;
+  const fields = p.fields;
+
+  // Start at the next minute boundary strictly after `afterMs`.
+  let cursor = Math.floor(afterMs / MIN) * MIN + MIN;
+  const limit = cursor + 5 * 366 * 24 * 60 * MIN; // ~5 years of minutes (upper bound)
+
+  // Ordered candidate times-of-day (minutes/hours) for quick within-day search.
+  const minutes = [...fields[0].values].sort((a, b) => a - b);
+  const hours = [...fields[1].values].sort((a, b) => a - b);
+
+  for (let guard = 0; guard < 5 * 366 && cursor < limit; guard++) {
+    const dayStart = new Date(cursor);
+    dayStart.setHours(0, 0, 0, 0);
+    // Does this calendar DAY match month + dom/dow? (Match the day fields only —
+    // probing with a specific time like noon would wrongly reject a day whose only
+    // matching time-of-day is, say, 09:00.) If not, jump a day.
+    const probe = new Date(dayStart.getFullYear(), dayStart.getMonth(), dayStart.getDate(), 12, 0, 0, 0);
+    const monthHit = fields[3].values.has(probe.getMonth() + 1);
+    const domF = fields[2];
+    const dowF = fields[4];
+    const domHit = domF.values.has(probe.getDate());
+    const dowHit = dowF.values.has(probe.getDay());
+    const dayHit = monthHit && (domF.restricted && dowF.restricted ? (domHit || dowHit) : (domHit && dowHit));
+    if (!dayHit) {
+      // Advance by CALENDAR day (setDate+1), not +24h: a DST transition day is 23h
+      // or 25h long, and a fixed +24h can land back on the same day (fall-back,
+      // infinite loop) or skip one (spring-forward).
+      const next = new Date(dayStart.getFullYear(), dayStart.getMonth(), dayStart.getDate() + 1, 0, 0, 0, 0);
+      cursor = next.getTime();
+      continue;
+    }
+    // Within a matching day, find the earliest matching hour:minute strictly > afterMs.
+    let found = null;
+    for (const h of hours) {
+      for (const m of minutes) {
+        const t = new Date(dayStart.getFullYear(), dayStart.getMonth(), dayStart.getDate(), h, m, 0, 0);
+        // Spring-forward guard: a non-existent wall time gets normalized by Date
+        // (02:30 → 03:30). Read the fields back and reject the rollover.
+        if (t.getHours() !== h || t.getMinutes() !== m || t.getDate() !== dayStart.getDate()) continue;
+        const ms = t.getTime();
+        // Strictly greater than `afterMs` AND not before this iteration's floor.
+        if (ms > afterMs && ms >= cursor) { found = ms; break; }
+      }
+      if (found !== null) break;
+    }
+    if (found !== null) return found;
+    const nextDay = new Date(dayStart.getFullYear(), dayStart.getMonth(), dayStart.getDate() + 1, 0, 0, 0, 0);
+    cursor = nextDay.getTime();
+  }
+  return null;
+}

package/server/lib/file-access-policy.js

@@ -13,7 +13,7 @@
 import { realpathSync } from 'node:fs';
 import { resolve, basename, sep, join } from 'node:path';
 import { homedir, platform, tmpdir } from 'node:os';
-import { getClaudeConfigDir, onLogDirChange } from '../../findcc.js';
+import { getClaudeConfigDir, onLogDirChange, LOG_DIR } from '../../findcc.js';
 import { loadWorkspaces } from '../workspace-registry.js';
 import { getBackupRoot } from './config-backup.js';
 
@@ -96,8 +96,37 @@ const SENSITIVE_CLAUDE_FILES = new Set([
   // 也绝不跨网读(master.key 同时被下方 .key 文件名规则覆盖,这里双保险)。
   'credentials.json',
   'master.key',
+  // cc-viewer preferences.json 现在承载定时任务定义(含 prompt,可能带 secret)——默认路径下与
+  // credentials 同级拒绝;LOG_DIR 被 --log-dir 移走时由下方 _logDirSensitiveFiles 按 realpath 拦。
+  'preferences.json',
 ]);
 
+/**
+ * LOG_DIR 下的敏感数据文件名(定时任务运行历史 / 旧版任务存储 / preferences 本身)。
+ * 默认 LOG_DIR = ~/.claude/cc-viewer 在 allowlist 内,这些文件若只按文件名拦会误伤项目内同名
+ * fixture,所以按 realpath 精确等值 + LOG_DIR 前缀拦截;LOG_DIR 被 setLogDir 移走时缓存随
+ * onLogDirChange 失效(沿用既有 roots 缓存失效钩子)。
+ */
+const LOGDIR_SENSITIVE_NAMES = new Set([
+  'preferences.json',
+  'scheduled-task-runs.json',
+  'scheduled-tasks.json',
+]);
+let _logDirSensitiveCache = null;
+function _logDirSensitiveFiles() {
+  if (_logDirSensitiveCache) return _logDirSensitiveCache;
+  let rootReal;
+  try { rootReal = realpathSync(LOG_DIR); } catch { rootReal = LOG_DIR; }
+  const files = new Set();
+  for (const name of LOGDIR_SENSITIVE_NAMES) {
+    files.add(norm(join(LOG_DIR, name)));
+    files.add(norm(join(rootReal, name)));
+  }
+  _logDirSensitiveCache = { root: norm(withSep(LOG_DIR)), rootReal: norm(withSep(rootReal)), files };
+  return _logDirSensitiveCache;
+}
+onLogDirChange(() => { _logDirSensitiveCache = null; });
+
 // ─── allowlist roots 缓存 ──────────────────────────────────────────────────────
 let _rootsCache = null;
 let _workspacesVersion = 0;
@@ -221,6 +250,21 @@ export function isReadAllowed(absPath) {
     }
   } catch { /* backup root missing / not realpath-able → no extra deny */ }
 
+  // 2c) Deny LOG_DIR 内的任务/偏好数据文件(preferences.json 含 auth + 定时任务 prompt、
+  // scheduled-task-runs.json 含 prompt 摘要、scheduled-tasks.json 为旧版任务存储)与内核写
+  // 过程的 tmp/corrupt 残留。这些路径必须绕开所有 HTTP 剥离逻辑之外的裸文件读写。
+  {
+    const sens = _logDirSensitiveFiles();
+    const realNorm = norm(real);
+    if (sens.files.has(realNorm)) {
+      return { ok: false, reason: 'sensitive-ccv-data' };
+    }
+    // .tmp-<rand>（writeJsonAtomic 中间态）与 .corrupt-<ts>（tolerant 自愈备份）同属敏感残留。
+    if ((realNorm.startsWith(sens.root) || realNorm.startsWith(sens.rootReal)) && /\.(tmp|corrupt)-[^/\\]+$/.test(realNorm)) {
+      return { ok: false, reason: 'sensitive-ccv-data' };
+    }
+  }
+
   // 3) 项目内文件豁免 sensitive 文件名(允许 fixtures/test-cert.pem 等合法 fixture)
   const projectRoot = getProjectRoot();
   const isInProj = isInsideRoot(real, projectRoot);

package/server/lib/im-deny.js

@@ -15,18 +15,21 @@ const CRED_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.docker', '.config/gcloud
 // 家目录下的 shell 启动文件：写拒（被改写可植入持久化）。
 const WRITE_HOME_FILES = ['.bashrc', '.zshrc', '.bash_profile', '.zprofile', '.zshenv', '.profile', '.npmrc', '.netrc'];
 // Global settings/hooks: write-deny (protects the deny mechanism itself). Resolved against ~.
-const WRITE_REL_PATHS = ['.claude/settings.json', '.claude/settings.local.json', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key'];
+const WRITE_REL_PATHS = ['.claude/settings.json', '.claude/settings.local.json', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key', '.claude/cc-viewer/scheduled-task-runs.json', '.claude/cc-viewer/scheduled-tasks.json'];
 // Token/secret files under home: read-deny. Resolved against ~.
-const READ_REL_PATHS = ['.npmrc', '.netrc', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key'];
+const READ_REL_PATHS = ['.npmrc', '.netrc', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key', '.claude/cc-viewer/scheduled-task-runs.json', '.claude/cc-viewer/scheduled-tasks.json'];
 
 // Vault file names (bare-name match, any directory): LOG_DIR can be moved by --log-dir /
 // POST /api/preferences {logDir}, so hardcoding ~/.claude/cc-viewer would lose the vault whenever
-// the root moves. Match by file name so it stays denied regardless of root. Case-insensitive and
-// EXACT (does NOT match .bak/.old/.txt suffix variants — those are covered by the Bash-layer /i
-// regex and the backup-dir rule); basename grabs the last segment across POSIX/win32 (pathOf's
-// resolve would make lastIndexOf('/') miss on win32 backslashes).
+// the root moves. Match by file name so it stays denied regardless of root. Case-insensitive.
+// The credential vault (credentials.json/master.key) is EXACT-anchored: suffix variants
+// (.bak/.old/.txt) are deliberately allowed at this layer (covered by the Bash-layer /i regex
+// and the backup-dir rule). preferences.json / scheduled-task*.json additionally tolerate a
+// `.corrupt-*`/`.tmp-*` suffix — those residues hold the same secrets/prompts and are denied.
 const VAULT_FILE_RE = /^(credentials\.json|master\.key)$/i;
+const TASK_DATA_FILE_RE = /^(preferences\.json|scheduled-task-runs\.json|scheduled-tasks\.json)(\.(corrupt|tmp)-.*)?$/i;
 function isVaultFile(abs) { return VAULT_FILE_RE.test(basename(abs)); }
+function isTaskDataFile(abs) { return TASK_DATA_FILE_RE.test(basename(abs)); }
 
 // Bash 命令硬拦截规则。每条 { re, reason }。
 const BASH_DENY_RULES = [
@@ -56,7 +59,7 @@ const BASH_DENY_RULES = [
   // + 凭证 vault(credentials.json/master.key，含 cc-viewer-config-backups 备份目录) + 全局 settings。
   // credentials.json/master.key 用裸文件名匹配(不限 cc-viewer/ 前缀),并含 cred*/master* glob 形式,
   // 防止经备份目录、相对路径或 shell glob(cred*.json master*)绕过——IM 通道宁可拦多。
-  { re: /(id_rsa|id_ed25519|id_ecdsa|authorized_keys|\.ssh\/|\.aws\/|\.gnupg\/|\.kube\/|\.docker\/|\.config\/(gcloud|gh)\/|\.netrc|\.npmrc|cc-viewer\/preferences\.json|credentials\.json|master\.key|cc-viewer-config-backups|\.claude\/settings(\.local)?\.json)\b|(cred\*|master\*)/i, reason: 'access to credential / secret files' },
+  { re: /(id_rsa|id_ed25519|id_ecdsa|authorized_keys|\.ssh\/|\.aws\/|\.gnupg\/|\.kube\/|\.docker\/|\.config\/(gcloud|gh)\/|\.netrc|\.npmrc|cc-viewer\/preferences\.json|scheduled-task-runs\.json|scheduled-tasks\.json|credentials\.json|master\.key|cc-viewer-config-backups|\.claude\/settings(\.local)?\.json)\b|(cred\*|master\*)/i, reason: 'access to credential / secret files' },
 ];
 
 function underAny(absPath, roots) {
@@ -94,7 +97,7 @@ export function evaluateImDeny(toolName, toolInput = {}, opts = {}) {
   if (toolName === 'Read') {
     const abs = pathOf(toolInput, home);
     if (!abs) return { deny: false };
-    if (isVaultFile(abs)) return { deny: true, reason: 'read of the credential vault / master key' };
+    if (isVaultFile(abs) || isTaskDataFile(abs)) return { deny: true, reason: 'read of the credential vault / master key' };
     if (underAny(abs, credRoots)) return { deny: true, reason: 'read of a credential directory' };
     if (READ_REL_PATHS.some((rel) => abs === resolve(home, rel))) return { deny: true, reason: 'read of a secret/credential file' };
     return { deny: false };
@@ -103,7 +106,7 @@ export function evaluateImDeny(toolName, toolInput = {}, opts = {}) {
   if (toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit') {
     const abs = pathOf(toolInput, home);
     if (!abs) return { deny: false };
-    if (isVaultFile(abs)) return { deny: true, reason: 'write to the credential vault / master key' };
+    if (isVaultFile(abs) || isTaskDataFile(abs)) return { deny: true, reason: 'write to the credential vault / master key' };
     if (underAny(abs, credRoots)) return { deny: true, reason: 'write to a credential directory' };
     if (WRITE_HOME_FILES.some((f) => abs === resolve(home, f))) return { deny: true, reason: 'write to a shell startup / credential file' };
     if (WRITE_REL_PATHS.some((rel) => abs === resolve(home, rel))) return { deny: true, reason: 'write to protected global config (settings/hooks or IM secrets)' };

package/server/lib/json-store.js

@@ -19,7 +19,7 @@
 //                       writers (auth.js, im-config.js) that cannot become async without
 //                       cascading signature changes through routes and server startup.
 // Both serialize same-process callers and mutex cross-process on the same `${file}.lock`.
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, openSync, closeSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, openSync, closeSync, statSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { renameSyncWithRetry } from './file-api.js';
@@ -47,6 +47,23 @@ export function readJsonSafe(file, fallback = {}) {
   }
 }
 
+/**
+ * Structured read distinguishing missing / valid / corrupt without any fallback.
+ * Used by stores that must NOT silently recover from corruption (e.g. scheduled tasks in
+ * preferences.json): missing file → seed on first write; corrupt → surface, never overwrite.
+ * Read-only, no lock.
+ */
+export function readJsonStrict(file) {
+  if (!existsSync(file)) return { state: 'missing', data: null };
+  try {
+    const obj = JSON.parse(readFileSync(file, 'utf-8'));
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return { state: 'corrupt', data: null };
+    return { state: 'ok', data: obj };
+  } catch {
+    return { state: 'corrupt', data: null };
+  }
+}
+
 // Sentinel for "file exists but cannot be read/parsed". A MUTATE path can choose how to treat it:
 //   - DEFAULT (tolerant): collapse to `fallback` and write, so a corrupt preferences.json stays
 //     self-healing (the long-standing L66 behavior — a user re-saving recovers the file).
@@ -73,6 +90,15 @@ function _resolveForMutation(data, file, strictCorrupt) {
     reportSwallowed('json-store.corrupt-guard', err);
     throw err;
   }
+  // Tolerant self-heal keeps the long-standing "re-save recovers the file" behavior, but the
+  // corrupt bytes may carry data the caller's fallback would silently erase (e.g. scheduledTasks
+  // inside preferences.json). Preserve them once per file before overwriting so recovery is
+  // possible; best-effort — a failed backup must not block the heal. copyFileSync's third arg
+  // is an integer flag mask, not an options object — the destination inherits the source's
+  // 0600 mode, so no chmod is needed.
+  try {
+    copyFileSync(file, `${file}.corrupt-${Date.now()}`);
+  } catch (err) { reportSwallowed('json-store.corrupt-backup', err); }
   return undefined; // tolerant: signal "use the fallback"
 }
 

package/server/lib/model-system-prompts.js

@@ -263,7 +263,10 @@ const MODEL_ID_ALIASES = {
 // 让 .some 调用炸掉（模型 id 来自外部输入，不能信任）。
 // Expand a model id into every equivalent lowercase spelling.
 function modelIdVariants(id) {
-  return Object.hasOwn(MODEL_ID_ALIASES, id) ? MODEL_ID_ALIASES[id] : [id];
+  // A version/routing suffix identifies the same K3 family, not an unrelated
+  // model. Keep the boundary so k30 and k3pro remain unmatched.
+  const aliasId = /^k3(?:[.-]|$)/.test(id) ? 'k3' : id;
+  return Object.hasOwn(MODEL_ID_ALIASES, aliasId) ? MODEL_ID_ALIASES[aliasId] : [id];
 }
 
 // 供内置预设匹配复用的导出包装：入参任意大小写，先剥 `[1m]` 类方括号后缀

package/server/lib/project-prefs.js

@@ -16,7 +16,7 @@ import { getProjectName } from './project-state.js';
 // SINGLE SOURCE of "what must never live inside a fork": secrets (auth password + IM creds),
 // machine-level paths (logDir/claudeConfigDir), and the internal forks map. snapshotForFork /
 // cleanPatch / the admin list read all funnel through stripSensitive so the rule can't drift.
-const STRIP_KEYS = ['auth', 'authByProject', 'prefsByProject', 'logDir', 'claudeConfigDir'];
+const STRIP_KEYS = ['auth', 'authByProject', 'prefsByProject', 'logDir', 'claudeConfigDir', 'scheduledTasks'];
 
 /** Strip secrets + IM credentials + machine-level keys from a prefs-shaped object in place. */
 export function stripSensitive(obj) {
@@ -83,6 +83,9 @@ export function resolveScoped(globalPrefs, fork) {
   const { approvalModal: gAM, ...gRest } = globalPrefs || {};
   const { approvalModal: fAM, ...fRest } = fork || {};
   const merged = { ...gRest, ...fRest };
+  // 定时任务是全局状态(claim CAS 只在全局 prefs 上进行)——fork 永远不得携带/遮蔽它,
+  // 否则脏 fork 会把任务定义/claim 透给 scoped 客户端读侧。
+  delete merged.scheduledTasks;
   if (gAM || fAM) {
     // 防引用别名：fork 无 approvalModal 时也返回浅拷贝，避免调用方（preferencesGet 的
     // voicePack reconcile）回写到解析出的全局对象（当前每请求新解析虽无害，仍保持"绝不外泄内部引用"）。

package/server/lib/schedule-model.js

@@ -0,0 +1,149 @@
+// Structured schedule model for cc-viewer scheduled tasks.
+//
+// The six schedule kinds the UI offers are normalized here and mapped to cron where
+// applicable, so the cron engine (./cron.js) stays the single source of truth for
+// "when is the next fire". Storage keeps the structured `schedule` (not the cron
+// string) so the UI can round-trip the form and render a localized description.
+//
+//   { kind:'hourly',  minute: 0-59 }
+//   { kind:'daily',   time: 'HH:MM' }
+//   { kind:'weekdays',time: 'HH:MM' }            → Monday..Friday
+//   { kind:'weekly',  day: 1-7 (ISO, 1=Mon..7=Sun), time: 'HH:MM' }
+//   { kind:'cron',    expr: '5-field cron' }
+//   { kind:'once',    at: epochMs }
+//
+// Boundary: L1-lib. Imports only ./cron.js (L1) + node builtins.
+
+import { parseCron, nextCronRun } from './cron.js';
+
+const KINDS = new Set(['hourly', 'daily', 'weekdays', 'weekly', 'cron', 'once']);
+const TIME_RE = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+
+function _err(code, detail) { return { ok: false, error: code, detail }; }
+
+/** Validate + normalize a schedule input. Returns { ok:true, schedule } | { ok:false, error, detail }. */
+export function normalizeSchedule(input, now = Date.now()) {
+  if (!input || typeof input !== 'object') return _err('invalid_schedule', 'not an object');
+  const kind = input.kind;
+  if (!KINDS.has(kind)) return _err('invalid_schedule', `unknown kind ${kind}`);
+
+  if (kind === 'hourly') {
+    const minute = Number(input.minute);
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59) return _err('invalid_schedule', 'minute must be 0-59');
+    return { ok: true, schedule: { kind, minute } };
+  }
+
+  if (kind === 'daily' || kind === 'weekdays') {
+    const m = TIME_RE.exec(String(input.time || ''));
+    if (!m) return _err('invalid_schedule', 'time must be HH:MM');
+    return { ok: true, schedule: { kind, time: `${m[1].padStart(2, '0')}:${m[2]}` } };
+  }
+
+  if (kind === 'weekly') {
+    const day = Number(input.day);
+    if (!Number.isInteger(day) || day < 1 || day > 7) return _err('invalid_schedule', 'day must be 1-7 (ISO)');
+    const m = TIME_RE.exec(String(input.time || ''));
+    if (!m) return _err('invalid_schedule', 'time must be HH:MM');
+    return { ok: true, schedule: { kind, day, time: `${m[1].padStart(2, '0')}:${m[2]}` } };
+  }
+
+  if (kind === 'cron') {
+    const expr = String(input.expr || '').trim();
+    const p = parseCron(expr);
+    if (!p.ok) return _err('invalid_schedule', p.error);
+    if (nextCronRun(expr, now) === null) return _err('invalid_schedule', 'no fire time within 5 years');
+    return { ok: true, schedule: { kind, expr } };
+  }
+
+  // once
+  const at = Number(input.at);
+  if (!Number.isFinite(at)) return _err('invalid_schedule', 'at must be epoch ms');
+  if (at < now + 60_000) return _err('once_in_past', 'once.at must be at least 60s in the future');
+  return { ok: true, schedule: { kind, at } };
+}
+
+/** Map a preset schedule to its cron equivalent. `once` has no cron form → null. */
+export function scheduleToCron(schedule) {
+  if (!schedule || typeof schedule !== 'object') return null;
+  switch (schedule.kind) {
+    case 'hourly': return `${schedule.minute} * * * *`;
+    case 'daily': {
+      const [h, m] = schedule.time.split(':');
+      return `${Number(m)} ${Number(h)} * * *`;
+    }
+    case 'weekdays': {
+      const [h, m] = schedule.time.split(':');
+      return `${Number(m)} ${Number(h)} * * 1-5`;
+    }
+    case 'weekly': {
+      const [h, m] = schedule.time.split(':');
+      return `${Number(m)} ${Number(h)} * * ${schedule.day % 7}`; // ISO 7(Sun) → cron 0
+    }
+    case 'cron': return schedule.expr;
+    default: return null; // once
+  }
+}
+
+/**
+ * Next BASE fire time (before jitter) strictly after `afterMs`. Epoch ms or null.
+ * `once` returns its `at` when still in the future, else null.
+ */
+export function nextBaseFor(schedule, afterMs) {
+  if (!schedule || typeof schedule !== 'object') return null;
+  if (schedule.kind === 'once') return schedule.at > afterMs ? schedule.at : null;
+  const expr = scheduleToCron(schedule);
+  return expr ? nextCronRun(expr, afterMs) : null;
+}
+
+/**
+ * Occurrences in (fromMs, nowMs]. Returns { latest, count } or null when none.
+ *
+ * Review P1-1: "latest" and "count" are decoupled from any enumeration cap. We first
+ * check whether ANY occurrence exists within the 7-day catch-up window; the enumeration
+ * then starts from the max(fromMs, windowStart) so `latest` is the true most-recent fire,
+ * not a truncation point. `count` is therefore exact for the catch-up decision.
+ */
+export function occurrencesAtOrBefore(schedule, fromMs, nowMs, { windowMs = 7 * 24 * 3600 * 1000 } = {}) {
+  if (!schedule || typeof schedule !== 'object') return null;
+  if (schedule.kind === 'once') {
+    const hit = schedule.at > fromMs && schedule.at <= nowMs;
+    return hit ? { latest: schedule.at, count: 1 } : null;
+  }
+  const expr = scheduleToCron(schedule);
+  if (!expr) return null;
+
+  // Cheap existence probe: is there any fire in the last `windowMs` at all? If not,
+  // there's nothing worth enumerating (the caller marks the task missed/stale).
+  const windowStart = nowMs - windowMs;
+  if (nextCronRun(expr, windowStart) === null || nextCronRun(expr, windowStart) > nowMs) {
+    // Still may have fires between fromMs and windowStart — but those are all stale.
+    // Report them as stale via a probe at fromMs.
+    const any = nextCronRun(expr, fromMs);
+    if (any === null || any > nowMs) return null;
+    return { latest: any, count: 1, stale: true };
+  }
+
+  // Enumerate from the later of (fromMs, windowStart) forward to nowMs. `fromMs` is a
+  // scheduled BASE that may itself be due right now, and nextCronRun is strictly-greater,
+  // so seed the cursor one ms BEFORE the start to include a fire exactly at the start.
+  let cursor = Math.max(fromMs, windowStart) - 1;
+  let latest = null;
+  let count = 0;
+  // Bounded: at most windowMs/1min iterations for `* * * * *` (10080) — acceptable.
+  for (let guard = 0; guard < 11000; guard++) {
+    const t = nextCronRun(expr, cursor);
+    if (t === null || t > nowMs) break;
+    latest = t;
+    count += 1;
+    cursor = t;
+  }
+  return latest === null ? null : { latest, count };
+}
+
+/** Deterministic per-task jitter in [0, maxMs] (FNV-1a over the task id). */
+export function jitterForTaskId(id, maxMs = 120_000) {
+  let h = 0x811c9dc5;
+  const s = String(id);
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0) % (maxMs + 1);
+}

package/server/lib/scheduled-task-executor.js

@@ -0,0 +1,97 @@
+// Scheduled-task executor — the L1 glue that turns a claimed task into an actual
+// execution. server.js injects the SDK/PTY/chatQueue accessors (L1 must NOT import
+// the L2 managers directly — see verify-boundaries R5), so this module stays pure
+// and unit-testable with fakes.
+//
+// Three execution paths:
+//   inject (SDK mode)  → sdk.sendUserMessage, with a queue-full precheck (P1-4)
+//   inject (PTY mode)  → chatQueue.enqueue, with a STRICT instanceKey-only precheck (P0-2)
+//   spawn              → sdk.spawnEphemeralSession (SDK mode only)
+//
+// Result contract:
+//   inject → { status:'dispatched' } | { status:'failed', reason }
+//   spawn  → { status:'completed', sessionId, durationMs } | { status:'error', reason, error? }
+
+/**
+ * @param {object} task   the claimed task (has .mode/.prompt/.cwd/.project/.schedule)
+ * @param {object} claim  the claim record
+ * @param {object} io     injected accessors:
+ *   {
+ *     isSdkMode: boolean,
+ *     sdk: { isSdkAvailable, listSdkSessions, getQueueSnapshot, sendUserMessage, spawnEphemeralSession },
+ *     pty: { listLivePtys, getPtyKindFor },
+ *     chatQueue: { enqueue },
+ *     samePath(a, b): boolean,
+ *   }
+ */
+export async function executeScheduledTask(task, claim, io) {
+  if (task.mode === 'spawn') return _spawn(task, claim, io);
+  return io.isSdkMode ? _injectSdk(task, io) : _injectPty(task, io);
+}
+
+async function _injectSdk(task, io) {
+  const sdk = io.sdk;
+  if (!sdk || !sdk.isSdkAvailable()) return { status: 'failed', reason: 'sdk_unavailable' };
+  // The resident session is a per-cwd singleton — find the one for the task's cwd.
+  const target = sdk.listSdkSessions().find(s => io.samePath(s.cwd, task.cwd));
+  if (!target) return { status: 'failed', reason: 'no_live_session' };
+
+  // Queue-full precheck (P1-4): _sendUserMessage resolves normally even when the queue
+  // rejects the message (broadcasts queue-rejected and returns), so a dispatched verdict
+  // would be a lie. Check the queue depth first. NOTE the contract: getQueueSnapshot()
+  // returns an ARRAY (sdk-manager _getQueueSnapshot → _messageQueue.map(...)), not an
+  // {items} object — normalize both shapes defensively.
+  try {
+    const snap = sdk.getQueueSnapshot ? sdk.getQueueSnapshot({ instanceKey: target.instanceKey }) : null;
+    const depth = Array.isArray(snap) ? snap.length : (Array.isArray(snap?.items) ? snap.items.length : 0);
+    if (depth >= 50) return { status: 'failed', reason: 'queue_rejected' };
+  } catch { /* precheck is best-effort; fall through to send */ }
+
+  try {
+    // Fire-and-forget: acceptance = dispatched. The turn's own outcome is presented by
+    // the conversation itself (resident result carries no success/failure to us).
+    await sdk.sendUserMessage(task.prompt, { cwd: task.cwd, project: task.project, instanceKey: target.instanceKey });
+    return { status: 'dispatched' };
+  } catch (err) {
+    return { status: 'failed', reason: 'internal', error: String(err?.message || err) };
+  }
+}
+
+async function _injectPty(task, io) {
+  const pty = io.pty;
+  if (!pty) return { status: 'failed', reason: 'no_live_session' };
+  // Candidate Claude PTYs for the task's cwd.
+  const live = pty.listLivePtys().filter(p => p.ptyKind === 'claude' && io.samePath(p.cwd, task.cwd));
+  if (!live.length) return { status: 'failed', reason: 'no_live_session' };
+  const target = live.find(p => p.isActive) || live[0];
+
+  // STRICT precheck (P0-2): getPtyKindFor with ONLY instanceKey — _resolveKey does NOT
+  // fall back to project/active when no cwd/project is given, so a dead instance yields
+  // null instead of silently resolving to a same-project sibling or the wrong project's
+  // active session.
+  const kind = pty.getPtyKindFor({ instanceKey: target.instanceKey });
+  if (kind !== 'claude') return { status: 'failed', reason: 'no_live_session' };
+
+  // enqueue sanitizes, queues while busy, and injects via the IM bridge's bracketed-paste
+  // path. strictAnchor tells the drain path to stay strict (see chat-queue _injectHead).
+  const item = io.chatQueue.enqueue(task.prompt, { project: task.project, instanceKey: target.instanceKey, strictAnchor: true });
+  if (!item) return { status: 'failed', reason: 'queue_rejected' };
+  return { status: 'dispatched' };
+}
+
+async function _spawn(task, claim, io) {
+  if (!io.isSdkMode) return { status: 'failed', reason: 'spawn_unavailable' };
+  const sdk = io.sdk;
+  if (!sdk || typeof sdk.spawnEphemeralSession !== 'function') return { status: 'failed', reason: 'spawn_unavailable' };
+  const startedAt = Date.now();
+  try {
+    // Permission mode (security P1-3): 'default' (the stored default) forces approval
+    // prompts; 'inherit' passes undefined so the child uses the host session's mode.
+    const permissionMode = task.permissionMode === 'inherit' ? undefined : 'default';
+    const r = await sdk.spawnEphemeralSession(task.prompt, { cwd: task.cwd, project: task.project, signal: claim?.signal, permissionMode });
+    if (r.ok) return { status: 'completed', sessionId: r.sessionId, durationMs: Date.now() - startedAt };
+    return { status: 'error', reason: r.reason || 'internal', error: r.error || null, sessionId: r.sessionId || null, durationMs: Date.now() - startedAt };
+  } catch (err) {
+    return { status: 'error', reason: 'internal', error: String(err?.message || err), durationMs: Date.now() - startedAt };
+  }
+}