dsh-later 1.1.0 → 1.3.0

package/lib/index.js

@@ -65,6 +65,19 @@ export const Config = s.object({
      * - `classic`：强制使用旧版点阵风格（10×10 fill 方块 crispEdges）。
      */
     clockIconStyle: s.union([s.const('auto'), s.const('modern'), s.const('classic')]).default('auto'),
+    /**
+     * 高级语法（**Beta**，默认开启）：`/later` 与 `/schedule` 的多次写法。
+     *
+     * 覆盖三种写法：等间隔重复 `+1h*3`、相对链式序列 `+1h+1h+0.5h`、绝对锚点序列
+     * `15:32+16:32` / `9:00+1d`。标 Beta 的理由不是"没测"（38 个单测已覆盖），而是
+     * **展开语义还没被真实使用验证过**：一次命令写 10 条任务会不会刷屏 dock、
+     * 60 秒地板与 10 条上限的尺度是否合适，都需要一段观察期。
+     *
+     * 关闭后这些写法被**明确拒绝**并提示来设置页开启——不会退回"静默建成一条乱码"
+     * 的旧行为：那是 bug，不属于可回退的功能面。残片守卫（`15:32*3`、`+1h..3h`）
+     * 与本开关无关，始终生效。
+     */
+    advancedSyntax: s.boolean().default(true),
 }).volatile();
 /**
  * 0.1.5 时代 settings namespace 注册所用的 schema。
@@ -119,7 +132,8 @@ function registerUserScheduleTools(rootCtx, toolCtx, agent, getSettings, onUserC
                 name: 'user_schedule_create',
                 // description 在每次 register 时按当前 settings 生成：
                 // 模型看到的字符上限始终与宿主实际校验一致，避免描述与实现脱节。
-                description: '为用户创建一条当前会话内的定时提醒。必须提供非空提示与恰好一个选择器：after_seconds（正整数延时秒）、at（显式偏移时间或 {date,time,time_zone} 本地时间）、every_seconds（≥300 的固定间隔秒）。time_zone 可选，缺省用会话检测时区。创建来源被标记为用户工具，GUI 面板会展示。',
+                description: '为用户创建一条当前会话内的定时提醒。必须提供非空提示与恰好一个选择器：after_seconds（正整数延时秒）、at（显式偏移时间或 {date,time,time_zone} 本地时间）、every_seconds（≥300 的固定间隔秒）。time_zone 可选，缺省用会话检测时区。创建来源被标记为用户工具，GUI 面板会展示。' +
+                    'every_seconds 是**无结束条件**的固定间隔（会一直发下去，直到用户删除）；用户说了次数上限（如「每小时提醒我一次，持续 3 次」）时不要用 every_seconds，改为**逐条调用本工具 N 次**、每次用 at 给出对应的绝对时刻（t+1h、t+2h、t+3h）。',
                 parameters: {
                     prompt: {
                         type: 'string',
@@ -127,7 +141,7 @@ function registerUserScheduleTools(rootCtx, toolCtx, agent, getSettings, onUserC
                         description: `提醒内容（trim 后非空，≤${resolveSchedulerPromptLimits(getSettings()).maxChars} 字符；超过会返回 invalid_prompt）。`,
                     },
                     after_seconds: { type: 'number', description: '正整数延时秒数。' },
-                    every_seconds: { type: 'number', description: '固定间隔秒数，至少 300。' },
+                    every_seconds: { type: 'number', description: '固定间隔秒数，至少 300；无结束条件（有次数上限请改为逐条创建 at）。' },
                     at: {
                         description: '绝对目标：显式偏移的 RFC 3339 字符串，或 {date, time, time_zone} 本地日历对象。',
                         oneOf: [
@@ -263,6 +277,8 @@ export function apply(ctx, config) {
         confirmDelivery: true,
         onUnconfirmed: 'keep',
         clockIconStyle: 'auto',
+        // Beta 功能默认开：语法已经过 38 个单测，关闭它只会把用户推向报错。
+        advancedSyntax: true,
     };
     let getSettings = () => startSettings;
     ctx.inject(['settings'], (settingsCtx) => {
@@ -300,6 +316,8 @@ export function apply(ctx, config) {
             clockIconStyle: value?.clockIconStyle === 'modern' || value?.clockIconStyle === 'classic'
                 ? value.clockIconStyle
                 : 'auto',
+            // 仅显式 false 关闭；缺失/非法一律按默认开（与 schema 的 default(true) 同源）
+            advancedSyntax: value?.advancedSyntax !== false,
         });
         // ── 轨道 1：0.2.0（settings rewrite 第二版）─────────────────────────────
         //

package/lib/ownership-store.js

@@ -26,6 +26,33 @@
 import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync, existsSync, unlinkSync, readdirSync, copyFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+/**
+ * 校验并收窄任意来源（含磁盘 JSON）的附件块数组。
+ *
+ * sidecar 是本地文件，可能被外部改写或被旧版本写入半成品；而附件块最终会
+ * 拼进**以用户身份代发**的消息 content，故读路径必须视为不可信输入：
+ * 只放行 `{type:'image'|'file', attachment:{attachmentId: string}}` 形状的块，
+ * 其余一律丢弃（不抛错——单块损坏不应让整份 sidecar 不可读）。
+ */
+export function sanitizeAttachments(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    const blocks = [];
+    for (const item of value) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const block = item;
+        if (block.type !== 'image' && block.type !== 'file')
+            continue;
+        const ref = block.attachment;
+        if (typeof ref !== 'object' || ref === null)
+            continue;
+        if (typeof ref.attachmentId !== 'string')
+            continue;
+        blocks.push(item);
+    }
+    return blocks.length > 0 ? blocks : undefined;
+}
 /**
  * 显式状态目录覆盖（测试 / 便携场景）。
  *
@@ -140,10 +167,23 @@ function readFresh(sessionId) {
             throw new Error('unexpected shape');
         }
         // v1 → v2：补空 paused，写回时统一升到 2
+        //
+        // 附件块在**读路径**收窄（sidecar 是本地文件，视同不可信输入）：旧版本
+        // 写入的半成品或外部改写在此被滤掉，下游（代发拼 content）只见到合法块。
+        const entries = {};
+        for (const [id, entry] of Object.entries(parsed.entries)) {
+            const attachments = sanitizeAttachments(entry.attachments);
+            entries[id] = attachments === undefined ? entry : { ...entry, attachments };
+        }
+        const paused = {};
+        for (const [uid, entry] of Object.entries(parsed.paused ?? {})) {
+            const attachments = sanitizeAttachments(entry.attachments);
+            paused[uid] = attachments === undefined ? entry : { ...entry, attachments };
+        }
         const file = {
             version: 2,
-            entries: parsed.entries,
-            paused: parsed.paused ?? {},
+            entries,
+            paused,
         };
         cache.set(sessionId, { mtimeMs: stat.mtimeMs, size: stat.size, file });
         return file;
@@ -216,13 +256,15 @@ export function newTaskUid() {
     return globalThis.crypto?.randomUUID?.() ?? `uid-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 /** 记录（新增或覆盖）一条所有权；幂等。仅显式传入 `uid` 时写入稳定身份。 */
-export function recordOwnership(sessionId, id, delivery, uid, windowSeconds) {
+export function recordOwnership(sessionId, id, delivery, uid, windowSeconds, attachments) {
+    const safeAttachments = sanitizeAttachments(attachments);
     if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof id !== 'string' || id.length === 0) {
         const bare = {
             delivery,
             createdAt: Date.now(),
             ...(uid !== undefined ? { uid } : {}),
             ...(typeof windowSeconds === 'number' ? { windowSeconds } : {}),
+            ...(safeAttachments !== undefined ? { attachments: safeAttachments } : {}),
         };
         return bare;
     }
@@ -230,11 +272,16 @@ export function recordOwnership(sessionId, id, delivery, uid, windowSeconds) {
     const entries = { ...file.entries };
     const nextUid = uid ?? entries[id]?.uid;
     const nextWindow = windowSeconds ?? entries[id]?.windowSeconds;
+    // 附件与 uid/window 同语义：未显式传入时保留旧条目值，保证「pause 回填 uid」
+    // 与「flush 失败回滚」等覆盖写不丢附件；显式传入（含 undefined 清空语义由
+    // 调用方用 previousEntry?.attachments 表达）以传入值为准。
+    const nextAttachments = attachments !== undefined ? safeAttachments : entries[id]?.attachments;
     const entry = {
         delivery,
         createdAt: Date.now(),
         ...(nextUid !== undefined ? { uid: nextUid } : {}),
         ...(typeof nextWindow === 'number' ? { windowSeconds: nextWindow } : {}),
+        ...(nextAttachments !== undefined ? { attachments: nextAttachments } : {}),
     };
     entries[id] = entry;
     writeThrough(sessionId, { version: 2, entries, paused: file.paused ?? {} });

package/lib/presence.js

@@ -30,6 +30,7 @@ export const PRESENCE_URGENT_WINDOW_MS = 5 * 60_000;
  */
 export function summarizeSchedules(schedules) {
     let nextAt;
+    let progressFrom;
     let count = 0;
     let pausedCount = 0;
     for (const item of schedules ?? []) {
@@ -44,12 +45,81 @@ export function summarizeSchedules(schedules) {
             pausedCount += 1;
             continue; // 冻结项没有排定的触发时刻，不参与 nextAt
         }
-        if (nextAt === undefined || epoch < nextAt)
+        if (nextAt === undefined || epoch < nextAt) {
             nextAt = epoch;
+            // 窗口起点只跟随被选中的那一条；并列最早时保留先出现者的窗口。
+            progressFrom = windowStartOf(item, epoch);
+        }
     }
     if (count === 0)
         return { count: 0, pausedCount: 0 };
-    return nextAt === undefined ? { count, pausedCount } : { count, nextAt, pausedCount };
+    // 字段用条件展开：无进度时不产生 `progressFrom: undefined`，保持既有
+    // deepEqual 测试与 wire 形状不变。
+    return nextAt === undefined
+        ? { count, pausedCount }
+        : { count, nextAt, pausedCount, ...(progressFrom !== undefined ? { progressFrom } : {}) };
+}
+/**
+ * 推导进度窗口的起点时刻（epoch ms）；无从推导时返回 `undefined`。
+ *
+ * 口径按优先级：
+ *  1. `window_seconds` —— 宿主/投影直接给的总窗口，最权威（暂停项的 wire 正是
+ *     用它携带"原 after 间隔"，见 projection.ts 的 `pausedWireItemOf`）。
+ *  2. 按 `kind` 推：`after` 用 `after_seconds`，`every` 用 `every_seconds`。
+ *     两者都是"从触发时刻往回推一整个窗口"，天然得到本周期起点。
+ *  3. `created_at` —— `at` 类型没有周期，只能拿任务创建时刻当起点。
+ *
+ * **推不出就返回 `undefined`**，绝不拿 `scheduledAt` 兜底：那会让 span 为 0，
+ * 进度恒为 100%，把"算不出来"伪装成"已经走完"。
+ */
+function windowStartOf(item, scheduledEpoch) {
+    const explicit = toFiniteSeconds(item.window_seconds ?? item.windowSeconds);
+    if (explicit !== undefined)
+        return scheduledEpoch - explicit * 1000;
+    const afterSec = toFiniteSeconds(item.after_seconds ?? item.afterSeconds);
+    const everySec = toFiniteSeconds(item.every_seconds ?? item.everySeconds);
+    const span = item.kind === 'every' ? everySec : (afterSec ?? everySec);
+    if (span !== undefined)
+        return scheduledEpoch - span * 1000;
+    const created = toEpochMs(item.created_at) ?? toEpochMs(item.createdAt);
+    if (created !== null)
+        return created;
+    return undefined;
+}
+/** 秒数归一：只接受有限正数（0 / 负数 / NaN 一律视为"没给"）。 */
+function toFiniteSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** epoch ms（number）或 ISO 字符串统一成 epoch ms；无法解析返回 `null`。 */
+function toEpochMs(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * 进度环比例（0–1）：`now` 在 `[progressFrom, nextAt]` 中的位置。
+ *
+ * 返回 `undefined` 表示**无从算起**（缺窗口起点，或窗口已退化），调用方此时应
+ * 退回「恒定整环」的旧表现，而不是画一个 0% 的空环 —— 后者是错误信息：
+ * 0% 是"刚开始"，`undefined` 是"算不出来"。
+ *
+ * 两端夹住：`overdue` 时 `now > nextAt`，环停在满环而不是绕出去。
+ */
+export function progressOf(entry, now) {
+    const { nextAt, progressFrom } = entry;
+    if (nextAt === undefined || progressFrom === undefined)
+        return undefined;
+    const span = nextAt - progressFrom;
+    if (!(span > 0))
+        return undefined;
+    const ratio = (now - progressFrom) / span;
+    if (!Number.isFinite(ratio))
+        return undefined;
+    return ratio <= 0 ? 0 : ratio >= 1 ? 1 : ratio;
 }
 /** 由当前时刻判定 badge 状态。 */
 export function badgeStateFor(nextAt, now) {

package/lib/runtime.js

@@ -2,7 +2,7 @@ import { createUserMessage, boundContextSummary } from '@deepseek-ai/dsh-llm';
 import { foldScheduleEvents, renderReminderFraming, resolveEveryOccurrence, ScheduleId, } from '@deepseek-ai/dsh-schedule';
 import { renderRecurringBatchFraming as renderEveryReminderBatchFraming, scheduleMessageSource, } from './schedule-compat.js';
 import { OWNED_EVENT } from './domain.js';
-import { findScheduleIdByUid, getPaused, removePaused } from './ownership-store.js';
+import { findScheduleIdByUid, getOwnership, getPaused, removePaused } from './ownership-store.js';
 import { foldUserState } from './user-tools.js';
 import { confirmDelivery, messageIdOf } from './delivery.js';
 import { detectTimeZone, formatHhmm } from './time-utils.js';
@@ -453,9 +453,14 @@ export class UserScheduleRuntime {
         if (paused === undefined)
             return undefined;
         const asUser = paused.delivery === 'user';
+        // 附件随留档冻结（pause 时带出），代发/插话时原样拼回，与 buildMessage 同形。
+        const attachmentBlocks = paused.attachments ?? [];
         const message = asUser
             ? createUserMessage({
-                content: [{ type: 'text', text: paused.prompt }],
+                content: [
+                    { type: 'text', text: paused.prompt },
+                    ...attachmentBlocks,
+                ],
                 source: { kind: 'user' },
             })
             : createUserMessage({
@@ -494,7 +499,9 @@ export class UserScheduleRuntime {
      * 构造注入的消息，按投递形态分流：
      *  - `user`（`/later` 显式请求的延迟发送）：原样内容 + `source.kind='user'`，
      *    让 GUI 呈现为「我」发出的普通气泡（产品取舍：用户明确要求以本人身份）。
-     *    跳过 framing 防护 —— 这是「代发」语义，不是注入。
+     *    跳过 framing 防护 —— 这是「代发」语义，不是注入。随命令提交的附件
+     *    （图片/文件耐久引用，存于 sidecar）按记录顺序拼在文本块之后，
+     *    与用户自己发「文字+图」的消息形状一致。
      *  - `context`（默认）：复用 dsh-schedule 的注入防护 framing + notice 表单，
      *    保持「上下文注入」的可信审计线；多条一次性到期合并为批次 framing（P1-5），
      *    形状与 dsh-schedule 的固定间隔批次一致。
@@ -506,8 +513,13 @@ export class UserScheduleRuntime {
             // 兜底：任一条带 user 标记即按代发处理，与旧语义一致。
             const asUser = decision.delivery === 'user' || records.some((record) => delivery.get(record.id) === 'user');
             if (asUser) {
+                const content = [
+                    { type: 'text', text: records.map((record) => record.prompt).join('\n') },
+                ];
+                for (const record of records)
+                    content.push(...this.attachmentsOf(record.id));
                 return createUserMessage({
-                    content: [{ type: 'text', text: records.map((record) => record.prompt).join('\n') }],
+                    content,
                     source: { kind: 'user' },
                 });
             }
@@ -522,8 +534,13 @@ export class UserScheduleRuntime {
         const records = decision.reminders.map((reminder) => reminder.record);
         // 固定间隔批次里任一条以「代发」为准（当前入口不会产生该组合，防御性保留）
         if (records.some((record) => delivery.get(record.id) === 'user')) {
+            const content = [
+                { type: 'text', text: records.map((record) => record.prompt).join('\n') },
+            ];
+            for (const record of records)
+                content.push(...this.attachmentsOf(record.id));
             return createUserMessage({
-                content: [{ type: 'text', text: records.map((record) => record.prompt).join('\n') }],
+                content,
                 source: { kind: 'user' },
             });
         }
@@ -532,6 +549,23 @@ export class UserScheduleRuntime {
             source: scheduleMessageSource(boundContextSummary(noticeSummary(records))),
         });
     }
+    /**
+     * 读某条提醒随命令提交的附件（sidecar 权威；无会话 id / 无条目时为空）。
+     *
+     * 只在 `user` 代发路径调用——context 注入通道从未声明接受附件（见 commands.ts），
+     * 不会把图片拼进防护 framing。sidecar 读路径已做块级收窄（sanitizeAttachments）。
+     */
+    attachmentsOf(scheduleId) {
+        const sessionId = this.agent.session.header?.id;
+        if (typeof sessionId !== 'string' || sessionId.length === 0)
+            return [];
+        try {
+            return getOwnership(sessionId, scheduleId)?.attachments ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
 }
 /** notice 摘要：每条 `HH:mm · 内容`，最多列 3 条，余者以计数收尾。 */
 function noticeSummary(records) {

package/lib/schedule-summary-store.js

@@ -0,0 +1,160 @@
+/**
+ * 定时摘要 store：把 {@link buildScheduleSummary} 的纯计算接到宿主 `sessions`
+ * 服务上，得到一个**可订阅的公共数据源**。
+ *
+ * 为什么需要它（issue #17）：dsh-later 自己的侧栏 badge 与外部插件（如
+ * dsh-group-status）都需要「全会话定时任务摘要」。两条独立通路会各自订阅
+ * `sessions.list`、各自周期 `refresh()`，既浪费 RPC 又容易漂移。本 store 是
+ * **唯一**的数据权威：内部负责列表订阅、状态 tick（scheduled→urgent→overdue）
+ * 与 `session.list` 读 RPC 补时效；外部只读 {@link ScheduleSummaryStore.getSnapshot}
+ * 或订阅变更。
+ *
+ * 跨插件使用方式（消费方声明 `dsh.client.external: ["dsh-later"]` 后）：
+ * ```js
+ * const later = require('dsh-later/client')
+ * const store = later.getScheduleSummaryStore()
+ * ```
+ *
+ * 本模块零 DOM / 零 React 依赖（`document` / `window` 一律经 `globalThis`
+ * 结构化探测），宿主 tsc 与浏览器 esbuild 都能编译，`node --test` 也能直接跑。
+ * @module dsh-later/schedule-summary-store
+ */
+import { buildScheduleSummary, sameScheduleSummary } from './schedule-summary.js';
+/** 摘要状态重算周期（本地时钟，零网络）。 */
+export const SUMMARY_STATE_TICK_MS = 30_000;
+/** `session.list` 重拉周期（读 RPC；仅页面可见时执行）。 */
+export const SUMMARY_REFRESH_INTERVAL_MS = 60_000;
+/** 取 `globalThis.document`（不引 DOM 类型，宿主编译期无 document 也能通过）。 */
+function documentOf() {
+    const doc = globalThis.document;
+    return typeof doc === 'object' && doc !== null ? doc : undefined;
+}
+/**
+ * 创建定时摘要 store（宿主 `apply` 内创建一次，全插件共享）。
+ * @param sessions - 宿主 `sessions` 服务。
+ * @param options - 周期/时钟/刷新策略覆盖（单测用）。
+ * @returns 可订阅 store。
+ */
+export function createScheduleSummaryStore(sessions, options = {}) {
+    const now = options.now ?? Date.now;
+    const stateTickMs = options.stateTickMs ?? SUMMARY_STATE_TICK_MS;
+    const refreshIntervalMs = options.refreshIntervalMs ?? SUMMARY_REFRESH_INTERVAL_MS;
+    const autoRefresh = options.autoRefresh ?? true;
+    const canRefresh = options.canRefresh ??
+        (() => {
+            const doc = documentOf();
+            return doc?.visibilityState === undefined || doc.visibilityState === 'visible';
+        });
+    const listeners = new Set();
+    let snapshot = new Map();
+    let disposed = false;
+    const notify = () => {
+        // 快照一份再遍历：订阅者可能在回调里退订。
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                /* 单个订阅者异常不影响其余订阅者与主流程 */
+            }
+        }
+    };
+    const reload = () => {
+        if (disposed)
+            return;
+        const next = buildScheduleSummary(sessions.list.getSnapshot(), now());
+        if (sameScheduleSummary(snapshot, next))
+            return;
+        snapshot = next;
+        notify();
+    };
+    const unsubscribeList = sessions.list.subscribe(reload);
+    const stateTick = setInterval(reload, stateTickMs);
+    let refreshTick;
+    let onVisible;
+    const doc = documentOf();
+    const target = globalThis;
+    const refreshNow = () => {
+        if (disposed || !canRefresh())
+            return;
+        try {
+            void sessions.refresh().catch(() => undefined);
+        }
+        catch {
+            /* 刷新失败不影响既有摘要 */
+        }
+    };
+    if (autoRefresh) {
+        onVisible = () => {
+            if (!disposed && canRefresh()) {
+                refreshNow();
+                reload();
+            }
+        };
+        refreshTick = setInterval(() => {
+            if (canRefresh())
+                refreshNow();
+        }, refreshIntervalMs);
+        doc?.addEventListener?.('visibilitychange', onVisible);
+        target.addEventListener?.('online', onVisible);
+        refreshNow();
+    }
+    reload();
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearInterval(stateTick);
+        if (refreshTick !== undefined)
+            clearInterval(refreshTick);
+        if (onVisible !== undefined) {
+            doc?.removeEventListener?.('visibilitychange', onVisible);
+            target.removeEventListener?.('online', onVisible);
+        }
+        unsubscribeList();
+        listeners.clear();
+    };
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        reload,
+        dispose,
+    };
+}
+/** 当前生效的 store（client 插件 `apply` 挂载时登记；跨插件只读入口）。 */
+let activeStore;
+/** store 登记变化的订阅者（消费方可能在 store 就绪前先渲染）。 */
+const registryListeners = new Set();
+/**
+ * 登记/撤销当前 store（由 dsh-later 自身 `apply` 调用；外部插件不要调用）。
+ * @param store - 生效的 store；undefined 表示撤销。
+ */
+export function setActiveScheduleSummaryStore(store) {
+    if (activeStore === store)
+        return;
+    activeStore = store;
+    for (const listener of [...registryListeners]) {
+        try {
+            listener();
+        }
+        catch {
+            /* 忽略单个订阅者异常 */
+        }
+    }
+}
+/** 读取当前生效的 store；dsh-later 未加载时为 undefined。 */
+export function getScheduleSummaryStore() {
+    return activeStore;
+}
+/** 订阅 store 登记变化（供 React hook 在 store 迟到时仍能重渲染）。 */
+export function subscribeScheduleSummaryStore(listener) {
+    registryListeners.add(listener);
+    return () => {
+        registryListeners.delete(listener);
+    };
+}

package/lib/schedule-summary.js

@@ -0,0 +1,113 @@
+/**
+ * 定时任务摘要：dsh-later 对外暴露的**公共数据面**（跨会话 / 跨插件）。
+ *
+ * 关键事实（本插件「路线 B」的数据源）：`userSchedules` 是 client-visible 投影，
+ * 宿主在 `session.list` 基线里为**每个**会话携带 projections 块（live 会话走注册
+ * 表现值、冷会话走持久化投影缓存），客户端把它合入
+ * `SessionSummary.projectionValues`。因此**任何**持有 `sessions` 服务的客户端插件
+ * 都能读到全会话的定时任务，本模块只负责把它折叠成稳定形状。
+ *
+ * 契约形状（issue #17）：`Map<SessionId, { count, nextAt, state }>`——即
+ * {@link ScheduleSummaryMap}。dsh-later 通过 `dsh-later/client` 导出
+ * {@link buildScheduleSummary}（纯函数）、`createScheduleSummaryStore`（可订阅
+ * store）与 `useScheduleSummary`（React hook），消费方按需选用。
+ *
+ * 本模块零 DOM / 零 React 依赖：宿主、浏览器与 `node --test` 都能直接跑。
+ * @module dsh-later/schedule-summary
+ */
+import { badgeStateFor, summarizeSchedules, } from './presence.js';
+/** `userSchedules` 投影值在 `projectionValues` 里的键名。 */
+export const SCHEDULE_PROJECTION_KEY = 'userSchedules';
+/**
+ * 从 `projectionValues` 里取出任务数组（容错：形状不对一律当作无任务）。
+ * @param projectionValues - 会话行的投影现值集合。
+ * @returns 任务数组；缺失或形状非法时 undefined。
+ */
+export function schedulesOfProjection(projectionValues) {
+    const value = projectionValues?.[SCHEDULE_PROJECTION_KEY];
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const schedules = value.schedules;
+    return Array.isArray(schedules) ? schedules : undefined;
+}
+/**
+ * 全会话归纳：把会话列表快照折叠成 {@link ScheduleSummaryMap}。
+ * @param source - 会话列表快照（`sessions.list.getSnapshot()`）。
+ * @param now - 判定 `state` 的当前时刻（epoch ms）。
+ * @returns 会话 id → 摘要；无任务的会话不出现在 map 里。
+ */
+export function buildScheduleSummary(source, now) {
+    const summary = new Map();
+    for (const [sessionId, row] of Object.entries(source.byId)) {
+        if (row === undefined)
+            continue;
+        const entry = summarizeSchedules(schedulesOfProjection(row.projectionValues));
+        if (entry.count === 0)
+            continue;
+        summary.set(sessionId, { ...entry, state: badgeStateFor(entry.nextAt, now) });
+    }
+    return summary;
+}
+/**
+ * 两份摘要是否等价（逐条比对五个字段）。store 用它决定是否需要通知订阅者，
+ * 避免每次重算都产生新的 Map 引用导致 React 无谓重渲染。
+ *
+ * `progressFrom` 一并比对：它虽然通常随 `nextAt` 同进同退，但暂停→恢复会让
+ * 同一条任务重新拥有窗口起点，此时 `nextAt` 可能未变而窗口已换 —— 漏比会
+ * 让进度环停在上一个窗口的比例上。
+ * @param a - 旧摘要。
+ * @param b - 新摘要。
+ * @returns 键集合与每条内容都相同时为 true。
+ */
+export function sameScheduleSummary(a, b) {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [sessionId, left] of a) {
+        const right = b.get(sessionId);
+        if (right === undefined)
+            return false;
+        if (left.count !== right.count ||
+            left.pausedCount !== right.pausedCount ||
+            left.nextAt !== right.nextAt ||
+            left.progressFrom !== right.progressFrom ||
+            left.state !== right.state) {
+            return false;
+        }
+    }
+    return true;
+}
+/** 状态优先级（越大越紧急）。 */
+const STATE_RANK = { scheduled: 0, urgent: 1, overdue: 2 };
+/**
+ * 按**分组**聚合摘要：给定组内会话 id，折叠出可直接渲染的分组事实。
+ *
+ * 消费方（如 dsh-group-status 的 `GroupLiveStatus`）只需把组内会话 id 传进来，
+ * 无需理解 `nextAt`/暂停语义。
+ * @param summary - {@link ScheduleSummaryMap}。
+ * @param sessionIds - 组内会话 id（顺序无关；不在摘要里的会被忽略）。
+ * @returns 分组级摘要；组内无任务时 `sessions`/`count` 为 0、`state` 缺省。
+ */
+export function summarizeScheduleGroup(summary, sessionIds) {
+    let sessions = 0;
+    let count = 0;
+    let pausedCount = 0;
+    let nextAt;
+    let state;
+    for (const sessionId of sessionIds) {
+        const entry = summary.get(sessionId);
+        if (entry === undefined)
+            continue;
+        sessions += 1;
+        count += entry.count;
+        pausedCount += entry.pausedCount;
+        if (entry.nextAt !== undefined && (nextAt === undefined || entry.nextAt < nextAt))
+            nextAt = entry.nextAt;
+        if (state === undefined || STATE_RANK[entry.state] > STATE_RANK[state])
+            state = entry.state;
+    }
+    return nextAt === undefined
+        ? { sessions, count, pausedCount, state }
+        : { sessions, count, pausedCount, nextAt, state };
+}

package/lib/smart-window.js

@@ -226,9 +226,34 @@ export function epochFromLocal(date, time, timeZone) {
         day > 31) {
         return undefined;
     }
-    // 以纯 UTC 构造「当日近似 epoch」作为锚点，再用偏移校正解析真实墙钟时刻。
-    const approx = Date.UTC(year, month - 1, day, 0, 0, 0, 0);
-    return resolveWallClock(approx, timeZone, hour, minute, second);
+    // 「哪一天」必须由**请求的日历日期**决定，不能从某个探测瞬点反推：
+    // 旧实现传 `Date.UTC(y,m-1,d)`（UTC 零点）给 resolveWallClock，它再用
+    // localFieldsOf 读「当天」——在 UTC 负偏移时区（America/Los_Angeles 等）那个
+    // 瞬间读出来的是**前一天**，于是 `2026-11-01 09:00 @LA` 解成 10-31 09:00，
+    // 面板自定义日期与 `/later 明天9点` 整体错一天（正偏移 ≤ +11 的时区恰好看不出）。
+    // 这里改为直接以请求日期为判据，在候选偏移里挑字段完全吻合的最小瞬点。
+    const localEpoch = Date.UTC(year, month - 1, day, hour, minute, second, 0);
+    const offsets = new Set();
+    for (let delta = -2; delta <= 2; delta += 1) {
+        offsets.add(offsetOf(localEpoch + delta * DAY_MS, timeZone));
+    }
+    const candidates = [];
+    for (const offset of offsets) {
+        const candidate = localEpoch - offset;
+        const f = localFieldsOf(candidate, timeZone);
+        if (f.year === year &&
+            f.month === month &&
+            f.day === day &&
+            f.hour === hour &&
+            f.minute === minute &&
+            f.second === second) {
+            candidates.push(candidate);
+        }
+    }
+    // 回拨日同一墙钟出现两次 → 取较早的一次（与 dsh-schedule 的 weekly/daily 口径一致）；
+    // 前拨跳过的墙钟 → 无候选 → undefined，由调用方给出「该时刻不存在」的提示。
+    candidates.sort((a, b) => a - b);
+    return candidates[0];
 }
 /**
  * 智能模式的一站式目标构造：返回可直接作为 `at` 对象使用的本地日历字段。