fix(core): align stepped day fields with Vixie cron semantics

[destire-mio]

What this PR does

Aligns day-of-month and day-of-week wildcard detection with Vixie cron's leading-character rule. Expressions such as */2 now select AND semantics when paired with the other day field, while expressions such as 1,* remain restricted and select the OR rule. Regression coverage exercises parsing, direct date matching, and next-fire calculation for both day fields.

Why it's needed

The scheduler previously considered only a lone * to be a wildcard day field. As a result, schedules using */N in one day field and a constraint in the other could fire when only the constrained field matched. This restores the documented Vixie behavior and prevents extra or premature task executions.

Reviewer Test Plan

How to verify

1. Starting after 2024-12-31 23:59, evaluate 0 0 */2 * 1; the next fire time should be 2025-01-13 00:00, when both the stepped day-of-month and Monday match, rather than 2025-01-01 00:00.
2. Starting after the same time, evaluate 0 0 15 * */3; the next fire time should be 2025-01-15 00:00, when both the fifteenth day and the stepped day-of-week match.
3. Run cd packages/core && npx vitest run src/utils/cronParser.test.ts (31 tests passed), the full core test suite (17,121 tests passed and 9 skipped), npm run build, and npm run typecheck.

Evidence (Before & After)

N/A — this is a non-UI scheduler semantics fix; the automated before/after cases are covered by the regression tests above.

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested locally
🐧 Linux	⚠️ not tested locally

Environment (optional)

macOS with Node.js v26.5.0 and the npm workspace toolchain.

Risk & Scope

• Main risk or tradeoff: Schedules whose day field begins with * now intentionally use the documented Vixie AND rule, so their fire dates change from the previous incorrect behavior.
• Not validated / out of scope: Windows and Linux were not tested locally. Repository-wide npm run preflight reached the test phase but exited on unrelated CLI dialog/workspace-agent failures and Web Shell localStorage failures under Node.js 26; the touched full core suite passed, and the workspace-agent failure passed when rerun in isolation.
• Breaking changes / migration notes: None; this is a compatibility correction for the documented cron semantics.

Linked Issues

Fixes #7452

中文说明

本 PR 做了什么

将月中日期和星期日期字段的通配符判断与 Vixie cron 的“首字符”规则对齐。像 */2 这样的表达式与另一个日期字段配合时，现在会选择 AND 语义；像 1,* 这样的表达式仍视为受约束字段并选择 OR 语义。回归测试覆盖了两个日期字段的解析、直接日期匹配和下次触发时间计算。

为什么需要这个改动

调度器此前只有在日期字段恰好为单独的 * 时才将其视为通配字段。因此，当一个日期字段使用 */N、另一个日期字段带约束时，只要受约束字段匹配，任务就可能错误触发。此改动恢复了代码所记录的 Vixie 行为，避免任务额外或过早执行。

审阅者测试计划

验证方法

1. 从 2024-12-31 23:59 之后计算 0 0 */2 * 1；下次触发时间应为 2025-01-13 00:00，此时步进的月中日期与星期一同时匹配，而不应是 2025-01-01 00:00。
2. 从同一时间之后计算 0 0 15 * */3；下次触发时间应为 2025-01-15 00:00，此时每月十五日与步进的星期日期同时匹配。
3. 运行 cd packages/core && npx vitest run src/utils/cronParser.test.ts（31 个测试通过）、完整 core 测试套件（17,121 个测试通过、9 个跳过）、npm run build 和 npm run typecheck。

证据（修改前后）

不适用——这是非 UI 的调度语义修复；自动化回归测试已覆盖上述修改前后用例。

测试平台

操作系统	状态
🍏 macOS	✅ 已测试
🪟 Windows	⚠️ 未在本地测试
🐧 Linux	⚠️ 未在本地测试

环境（可选）

macOS、Node.js v26.5.0 和 npm workspace 工具链。

风险与范围

• 主要风险或权衡：日期字段以 * 开头的调度现在会按文档所述使用 Vixie AND 规则，因此其触发日期会从此前的错误行为变为正确行为。
• 未验证 / 不在范围内：未在本地测试 Windows 和 Linux。仓库级 npm run preflight 进入测试阶段后，因与本修复无关的 CLI 对话框/workspace-agent 失败以及 Node.js 26 下 Web Shell 的 localStorage 失败而退出；本次涉及的完整 core 测试套件已通过，workspace-agent 失败单独重跑也已通过。
• 破坏性变更 / 迁移说明：无；这是针对已记录 cron 语义的兼容性修正。

关联 Issue

Fixes #7452

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: observed bug with a clear reproduction in #7452 — matches("0 0 */2 * 1", Wed Jan 1 2025) returns true when Vixie semantics say false. The issue was already triaged and confirmed against the real matches() and parseCron().

Direction: the code explicitly documents "Follows vixie-cron day semantics" but only treats a lone * as wildcard, diverging from Vixie's leading-character rule. Aligning the implementation with the documented contract is the right call. CHANGELOG shows cron scheduling is an established feature (CronCreate, CronList, /loop), so correctness here matters.

Size: 20 production lines (10 added, 10 deleted in cronParser.ts), 25 test lines. Well under all thresholds.

Approach: the scope is exactly right — a two-line semantic fix in parseCron() (inherited by both matches() and nextFireTime()), with comment updates to match, and regression tests covering parsing, matching, and next-fire calculation. No unrelated changes, no scope creep. This is the minimal fix the issue proposed.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已观测到的 bug，#7452 中有明确复现——matches("0 0 */2 * 1", 2025-01-01 周三) 返回 true，而 Vixie 语义应为 false。该 issue 已经过 triage 并对真实的 matches() 和 parseCron() 进行了确认。

方向：代码注释明确写着 "Follows vixie-cron day semantics"，但只将单独的 * 视为通配符，与 Vixie 的首字符规则不一致。将实现与文档约定对齐是正确的。CHANGELOG 显示 cron 调度是已建立的功能（CronCreate、CronList、/loop），因此其正确性很重要。

规模：20 行生产代码（cronParser.ts 中 10 行新增、10 行删除），25 行测试代码。远低于所有阈值。

方案：范围恰到好处——在 parseCron() 中修改两行语义（由 matches() 和 nextFireTime() 继承），更新注释以匹配新语义，回归测试覆盖解析、匹配和下次触发时间计算。无无关改动，无范围蔓延。这是 issue 所提议的最小修复。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

_{Reviewed at 972beaa27b684b3e2b5ad606ad34fa4273bab6c2 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code Review

Independent proposal: change domIsWild/dowIsWild from === '*' to .startsWith('*') in parseCron(), update the docstrings and inline comments to reflect the leading-character rule, and add regression tests for all three public functions. That's exactly what this PR does — no simpler path exists, and nothing is missing.

The implementation is clean. The two-line semantic change in parseCron() is inherited by both matches() and nextFireTime(), so there's no duplication. Comment updates accurately describe the new behavior. Tests cover parsing (flag values for */N, *,N, N,*), direct matching (AND logic on a Wednesday), and next-fire calculation (stepping forward to the correct AND-match date). All 31 tests pass, typecheck is clean.

No blockers, no convention violations.

Real-Scenario Testing

Ran the real parseCron(), matches(), and nextFireTime() from the source tree, before and after the fix:

Before (main branch code)

=== BEFORE (main branch code) ===
=== Vixie cron day-field wildcard test ===

parseCron("0 0 */2 * 1").domIsWild = false  (vixie: true)
parseCron("0 0 15 * */3").dowIsWild = false  (vixie: true)
parseCron("0 0 1,* * 1").domIsWild = false  (vixie: false)

Date: Wed Jan 1 2025 00:00
matches("0 0 */2 * 1", wed) = true  (vixie: false, Jan 1 is Wed not Mon)
matches("0 0 15 * */3", wed) = true  (vixie: false, Jan 1 is not the 15th)

nextFireTime("0 0 */2 * 1", after Dec 31 23:59) = 2024-12-31T16:00:00.000Z  (vixie: Jan 13 = Mon + odd day)
nextFireTime("0 0 15 * */3", after Dec 31 23:59) = 2024-12-31T16:00:00.000Z  (vixie: Jan 15 = Wed + 15th)

After (PR #7464 code)

=== AFTER (PR #7464 code) ===
=== Vixie cron day-field wildcard test ===

parseCron("0 0 */2 * 1").domIsWild = true  (vixie: true)
parseCron("0 0 15 * */3").dowIsWild = true  (vixie: true)
parseCron("0 0 1,* * 1").domIsWild = false  (vixie: false)

Date: Wed Jan 1 2025 00:00
matches("0 0 */2 * 1", wed) = false  (vixie: false, Jan 1 is Wed not Mon)
matches("0 0 15 * */3", wed) = false  (vixie: false, Jan 1 is not the 15th)

nextFireTime("0 0 */2 * 1", after Dec 31 23:59) = 2025-01-12T16:00:00.000Z  (vixie: Jan 13 = Mon + odd day)
nextFireTime("0 0 15 * */3", after Dec 31 23:59) = 2025-01-14T16:00:00.000Z  (vixie: Jan 15 = Wed + 15th)

(UTC timestamps — the server is UTC+8, so 2025-01-12T16:00:00.000Z = Jan 13 00:00 local, 2025-01-14T16:00:00.000Z = Jan 15 00:00 local.)

Before: */2 is not recognized as wildcard → OR branch → fires Jan 1 (wrong). After: */2 starts with * → AND branch → fires Jan 13 (Mon + odd day, correct). Unit tests: 31/31 pass. Typecheck: clean.

中文说明

代码审查

独立方案：将 parseCron() 中的 domIsWild/dowIsWild 从 === '*' 改为 .startsWith('*')，更新文档字符串和行内注释以反映首字符规则，并为三个公共函数添加回归测试。这正是本 PR 所做的——没有更简单的路径，也没有遗漏。

实现干净。parseCron() 中两行语义修改由 matches() 和 nextFireTime() 继承，无重复。注释更新准确描述了新行为。测试覆盖解析（*/N、*,N、N,* 的标志值）、直接匹配（周三的 AND 逻辑）和下次触发时间计算（前进到正确的 AND 匹配日期）。31 个测试全部通过，类型检查干净。

无阻塞问题，无规范违反。

真实场景测试

直接从源码树运行了真实的 parseCron()、matches() 和 nextFireTime()，修复前后对比：

修复前：*/2 未被识别为通配符 → 走 OR 分支 → 1 月 1 日触发（错误）。修复后：*/2 以 * 开头 → 走 AND 分支 → 1 月 13 日触发（周一 + 奇数日，正确）。单元测试：31/31 通过。类型检查：干净。

— Qwen Code · qwen3.7-max

_{Reviewed at 972beaa27b684b3e2b5ad606ad34fa4273bab6c2 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — confirmed bug, minimal correct fix, verified before/after.

This is what a good fix looks like. The issue was reported with a precise reproduction against Vixie's actual behavior, the author picked it up and delivered exactly the right two-line change — === '*' → .startsWith('*') — with comment updates that match and tests that cover parsing, matching, and next-fire calculation. The before/after run confirms the behavior change is correct: */2 now triggers AND semantics as Vixie intends, and 1,* correctly stays in the OR branch.

Nothing to second-guess here. Ships the fix cleanly, no scope creep, no over-engineering.

中文说明

置信度：5/5 — 已确认的 bug，最小化正确修复，已验证前后行为。

这是一个好的修复应有的样子。issue 报告时附带了针对 Vixie 实际行为的精确复现，作者接手后交付了恰到好处的两行修改——=== '*' → .startsWith('*')——注释更新与新语义一致，测试覆盖了解析、匹配和下次触发时间计算。前后运行确认行为变化正确：*/2 现在按 Vixie 预期触发 AND 语义，1,* 正确保持在 OR 分支。

无需犹豫。修复干净，无范围蔓延，无过度工程。

— Qwen Code · qwen3.7-max

_{Reviewed at 972beaa27b684b3e2b5ad606ad34fa4273bab6c2 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

No issues found. LGTM! ✅

— qwen3.7-max via Qwen Code /review

[wenshao]

✅ Local verification (maintainer) — LGTM

I built and verified this locally as a merge reference. Instead of only re-running the added unit tests, I drove the real parseCron / matches / nextFireTime from two modules: this PR's cronParser.ts, and a reconstruction of the pre-PR logic that I diffed against 972beaa27^ and confirmed byte-identical except for comments. So the before/after below is the actual code, apples-to-apples.

Environment: Debian 13 (Linux 6.12, x64), Node v22.22.2 — this adds the 🐧 Linux coverage the PR marked "not tested locally".

Before / After — real functions (issue #7452 repro + your test plan)

call	BEFORE (pre-PR)	FIXED (#7464)	Vixie
parseCron('0 0 */2 * 1').domIsWild	false	true	✓
parseCron('0 0 *,10 * 1').domIsWild	false	true	✓
parseCron('0 0 1,* * 1').domIsWild	false	false	✓ (not a star)
matches('0 0 */2 * 1', Wed 2025-01-01)	true — fires early	false	false ✓
matches('0 0 15 * */3', Wed 2025-01-01)	true — fires early	false	false ✓
nextFireTime('0 0 */2 * 1') after 2024-12-31 23:59	2025-01-01	2025-01-13 (Mon)	✓
nextFireTime('0 0 15 * */3') after 2024-12-31 23:59	2025-01-01	2025-01-15 (Wed)	✓

The pre-PR build takes the OR branch because */N !== '*', so it fires on the wrong day. The fix's .startsWith('*') faithfully mirrors Vixie's leading-character DOM_STAR/DOW_STAR rule and switches to AND. Both nextFireTime results match your test plan (2025-01-13, 2025-01-15) exactly, and every weekday above was independently confirmed with GNU date.

Negative control: 0 0 13 * 1 (DOM=13, DOW=Mon; neither starts with *) still fires 2025-01-06 (Mon) in both builds — the genuine Vixie OR case is untouched, so the fix does not over-broaden AND.

Automated checks

• cronParser.test.ts — 31 / 31 passed ✓
• All consumers — cronScheduler + cron-create / cron-delete / cron-list + loop-wakeup — 203 / 203 passed ✓
• Full core suite — 17,032 passed, 13 skipped. The only 2 failures are in the unrelated session-writer-lease.test.ts (chmod 0o000 / 0o500 permission assertions) and are expected when the suite runs as root — root bypasses Unix DAC, so the "unreadable/unwritable" expectations can't trigger. Not introduced by this PR.
• tsc --noEmit (packages/core) — clean ✓

Evidence

Conclusion: the change faithfully implements the documented Vixie leading-character rule, reproduces the issue #7452 fix and the stated fire-times against the real functions, and introduces no regressions in the parser or any of its consumers (incl. on Linux). LGTM. 👍

中文报告

✅ 本地验证（维护者）— LGTM

我在本地构建并验证了本 PR，作为合并参考。我没有只重跑新增的单测，而是用两个模块分别驱动了真实的 parseCron / matches / nextFireTime：一个是本 PR 的 cronParser.ts，另一个是我对改动前逻辑的还原版本——我已将其与 972beaa27^ 逐字节对比，确认除注释外完全一致。因此下面的「修改前 / 修改后」跑的都是真实代码，是同口径对比。

环境： Debian 13（Linux 6.12，x64），Node v22.22.2 —— 这补上了 PR 中标记为「未在本地测试」的 🐧 Linux 覆盖。

修改前 / 修改后 —— 真实函数（issue #7452 复现 + 你的测试计划）

调用	修改前（pre-PR）	修复后（#7464）	Vixie
parseCron('0 0 */2 * 1').domIsWild	false	true	✓
parseCron('0 0 *,10 * 1').domIsWild	false	true	✓
parseCron('0 0 1,* * 1').domIsWild	false	false	✓（非星号）
matches('0 0 */2 * 1', 周三 2025-01-01)	true —— 提前触发	false	false ✓
matches('0 0 15 * */3', 周三 2025-01-01)	true —— 提前触发	false	false ✓
nextFireTime('0 0 */2 * 1')（2024-12-31 23:59 之后）	2025-01-01	2025-01-13（周一）	✓
nextFireTime('0 0 15 * */3')（2024-12-31 23:59 之后）	2025-01-01	2025-01-15（周三）	✓

改动前因为 */N !== '*' 落入了 OR 分支，从而在错误的日期触发。修复用 .startsWith('*') 忠实还原了 Vixie 的「首字符」DOM_STAR/DOW_STAR 规则，改为 AND。两个 nextFireTime 结果与你的测试计划（2025-01-13、2025-01-15）完全一致，且上表中每个星期几都用 GNU date 独立核对过。

反向对照（负控）： 0 0 13 * 1（DOM=13、DOW=周一；两个日期字段都不以 * 开头）在两个版本中都仍触发于 2025-01-06（周一）—— 真正的 Vixie OR 场景未受影响，说明修复没有把 AND 语义扩大化。

自动化检查

• cronParser.test.ts —— 31 / 31 通过 ✓
• 全部下游消费方 —— cronScheduler + cron-create / cron-delete / cron-list + loop-wakeup —— 203 / 203 通过 ✓
• 完整 core 测试套件 —— 17,032 通过，13 跳过。仅有的 2 个失败位于与本改动无关的 session-writer-lease.test.ts（chmod 0o000 / 0o500 权限断言），这是以 root 运行测试套件时的预期现象 —— root 会绕过 Unix DAC 权限检查，导致「不可读 / 不可写」的断言无法触发。并非本 PR 引入。
• tsc --noEmit（packages/core）—— 干净通过 ✓

证据截图

结论： 本改动忠实实现了代码中所记录的 Vixie「首字符」规则，用真实函数复现了 issue #7452 的修复及所述触发时间，且未在解析器或任何下游消费方引入回归（包括 Linux 平台）。LGTM。👍

_{🤖 Verified locally with Claude Code (Opus 4.8, 1M context). This is a maintainer merge-reference report, not a replacement for CI.}