dsh-later 1.0.0 → 1.2.0

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/types/bar-geometry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 进度条几何：活动期与暂停冻结期**共用同一套时间基准**。
+ *
+ * 为什么要单独成模块并写清楚：进度条在「活动 ↔ 暂停 ↔ 恢复」之间切换时，
+ * 稍有不一致就会让用户看到条长跳变。历史上有两类真实缺陷：
+ *
+ *  1. 两套基准：冻结比曾由 `remaining_seconds`（整数秒、ceil）反推，与活动期
+ *     精确 ms 的 `now` 恒差一个取整 → 非整秒暂停必然变长。
+ *  2. 两个时刻：`paused_at` 是**宿主**处理暂停命令的时刻，比用户点下暂停时最后
+ *     渲染的那一帧晚（命令通道往返，实测约 0.3–0.5s）。直接用它做冻结帧，条长
+ *     会比前一帧更长 → 「点暂停，条忽然变长」。
+ *
+ * 现在统一为：`barWindow()` 求窗口，冻结帧只把 `now` 换成冻结时刻，并把冻结
+ * 时刻**钳到 ≤ 客户端已渲染时刻**。因此暂停瞬间条长与点击前严格一致。
+ *
+ * 本模块被 host 与 client 两侧共用（与 command-outcome / smart-window /
+ * time-utils 同款：同时列出在 tsconfig.json 与 tsconfig.client.json 的 include 中）。
+ *
+ * @module dsh-later/bar-geometry
+ */
+/** 每根进度条代表的时长（1 小时 = 一根满管）。 */
+export declare const BAR_UNIT_MS = 3600000;
+/** 参与几何计算的 schedule 最小视图（与 client `ClientSchedule` 结构兼容）。 */
+export interface BarScheduleView {
+    readonly id: string;
+    readonly kind: 'after' | 'at' | 'every';
+    readonly scheduled_at: string;
+    readonly after_seconds?: number;
+    readonly every_seconds?: number;
+    readonly created_at?: string;
+    /** 进度条总窗口（秒）；resume 后 after_seconds 只是剩余，此字段保留原间隔。 */
+    readonly window_seconds?: number;
+    readonly paused_at?: string;
+}
+/**
+ * 推导进度条起点与总窗口（暂停/活动期共用同一套时间基准）。
+ * - `after`：`window_seconds`（resume 后保留的原间隔）→ `after_seconds` → `created_at` → 首见时刻
+ * - `every`：`every_seconds` 反推
+ * - 其余：`created_at` → 首见时刻
+ */
+export declare function barWindow(item: BarScheduleView, end: number, now: number, firstSeen: ReadonlyMap<string, number>): {
+    readonly start: number;
+    readonly totalMs: number;
+};
+/** 活动期进度比：elapsed / total。 */
+export declare function barSegments(item: BarScheduleView, now: number, firstSeen: ReadonlyMap<string, number>): {
+    readonly totalRatio: number;
+    readonly count: number;
+};
+/**
+ * 暂停冻结进度比。
+ *
+ * ⚠️ 关键：**不能用 `scheduled_at` 反推**。暂停后 wire 的 `scheduled_at` 会从
+ * 「resume 后的新目标」换成 `originalScheduledAt`（原目标），而 `window_seconds`
+ * 始终是原窗口。若沿用活动期那套 `end - window` 的算法，暂停瞬间窗口基准整体
+ * 跳变，条长会剧烈塌缩（实测 25.7% → 3.3%）。
+ *
+ * 因此冻结帧改成**自洽的纯算术**，不依赖任何可能变义的字段：
+ *   ratio = (window - remaining) / window
+ * 其中 window 取 `window_seconds ?? after_seconds`，remaining 取
+ * `max(0, frozenLeftMs)`（即 `remaining_seconds * 1000`）。
+ *
+ * 这样冻结比例天然等于「暂停那一刻已经过掉的部分」，与暂停前后用的是同一个
+ * 窗口；`paused_at` 只用于可选的上界钳制（见 `renderedAt`）。
+ *
+ * @param frozenLeftMs - 冻结剩余毫秒（`remaining_seconds * 1000`）。
+ * @param renderedAt - 可选：客户端已渲染过的最新时刻上界；提供且早于暂停时刻时，
+ *   按该上界折算，保证冻结帧不超过用户已看到的进度。
+ */
+export declare function frozenBarSegments(item: BarScheduleView, frozenLeftMs: number, firstSeen: ReadonlyMap<string, number>, renderedAt?: number): {
+    readonly totalRatio: number;
+    readonly count: number;
+};
+/**
+ * 活动期「CSS 动画」计划：把进度条的推进交给 CSS，而不是每秒一次 JS 重渲染。
+ *
+ * 为什么需要：旧实现由 `useNow(1000)` 每秒更新一次 `now`，宽度随之每秒跳一次，
+ * 再用 `transition: width 1s linear` 补间。1 分钟任务的轨道上每秒要跳约 8px，
+ * 形成肉眼可见的锯齿/顿挫（长条上尤其明显）。
+ *
+ * ⚠️ 关键约束一：参数必须**只依赖任务自身的时间轴**（`start` / `end`），
+ * 不能依赖「当前渲染时刻」。否则每次 tick 重渲染都会改变参数 → 浏览器重启动画
+ * → 每秒一次固定跳变（实测 deltas 呈 `1.7×5, 10.2` 周期尖峰）。
+ *
+ * ⚠️ 关键约束二：**CSS 动画在元素被重建时会从头播放**。切到别的会话再切回来，
+ * dock 会卸载并重新挂载，动画 `currentTime` 归零——若只靠"动画自己走"，进度条
+ * 会退回 0% 附近（实测：真实已过 184s/600s 应为 30.7%，切回后却显示 2.55%，
+ * 恰好等于「重挂载后流逝的 15.3s / 600s」）。因此必须用**负 `animation-delay`**
+ * 在挂载瞬间就把播放头**定位到正确的绝对相位**：
+ *
+ *   delay = -(已过去时长)   →   一上屏就处在 elapsed/total 处
+ *
+ * 这样无论挂载多少次、间隔多久，画面都落在任务真实时间轴的正确位置。
+ *
+ * 由于负 delay 只由 `start`/`end`/`now` 决定，而这三者都是绝对时间，
+ * 「切走再切回」与「一直看着」得到的相位完全一致。
+ */
+export interface BarAnimationPlan {
+    /** 动画总时长（ms）＝ 完整窗口，保证播放头按绝对进度线性推进。 */
+    readonly durationMs: number;
+    /** 负延迟（ms）：把播放头定位到「已过去」处，抵消重挂载导致的归零。 */
+    readonly delayMs: number;
+}
+/**
+ * 依据窗口与当前时刻推导动画计划。
+ *
+ * @param totalMs - 总窗口毫秒（> 0）。
+ * @param elapsedMs - 已过去毫秒（钳到 [0, totalMs]）。
+ * @returns 计划；`totalMs <= 0`、非有限值、或已到点（剩余为 0）时返回 `undefined`。
+ */
+export declare function planBarAnimation(totalMs: number, elapsedMs: number): BarAnimationPlan | undefined;

package/lib/types/command-outcome.d.ts

@@ -0,0 +1,19 @@
+/**
+ * slash 命令的执行结果：**只表达「是否被受理」**。
+ *
+ * 为什么单独成模块并写清楚：`dsh-commands` 的 admission 语义只回
+ * `RemoteResult<{matched}>`，handler 的业务结果不从这里返回（它落在会话记录 /
+ * 投影里）。因此客户端**不得**用本类型判断「业务是否真的发生了」——例如删除
+ * 暂停项时 host 可能返回 `deleted:false`，而这里照样是 `matched: true`。
+ * 需要业务事实时以 `userSchedules` 投影为准（见 ScheduleDock 的观察窗对账）。
+ *
+ * 本模块被 host 与 client 两侧共用（与 smart-window / time-utils 同款：
+ * 同时列出在 tsconfig.json 与 tsconfig.client.json 的 include 中）。
+ *
+ * @module dsh-later/command-outcome
+ */
+/** 一条命令的执行结果。 */
+export interface CommandOutcome {
+    /** 命令是否被受理（matched）。false 表示未受理（无会话面 / 网络异常 / 无此命令）。 */
+    readonly matched: boolean;
+}

package/lib/types/delivery.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 插话投递的「投递 + 送达确认」原语。
+ *
+ * 为什么需要：`agent.steer()` 把消息放进 `next-step`，语义是「下一个 step 边界
+ * 消费」。若插话恰好撞上 `turn/start`，核心的 `inbox.claim('next-step', …)` 会把
+ * **整批** `next-step` 取走交给一个**请求上下文已定**的 step —— 消息落进 surface
+ * （日志里确有一条 `user/message`）却不进实际请求，即**静默丢失**。实测时序：
+ *
+ *   t+0ms   agent/inbox/spliced  → 插入 next-step
+ *   t+1ms   turn/start           → turn 17 开始（同一毫秒）
+ *   t+1ms   agent/inbox/spliced  → removedCount:1, inserted:[]  ← 被 claim 吞掉
+ *   t+17ms  request/header       → 请求已按旧上下文构造
+ *
+ * `agent.followup()` 入 `next-turn`，与 `next-step` 是两条独立队列，
+ * `claim('next-step', …)` 不触碰它，**结构上不存在**这个竞态 —— 故默认用它。
+ *
+ * 送达确认**只读会话日志**，不监听 `inbox/claimed` / `request/header` 等运行时
+ * 事件：那些事件的顺序是核心内部实现细节，监听它们等于把插件耦合到核心时序上，
+ * 核心一改就静默失效。日志格式是插件已经在依赖的稳定面（`foldUserState` 同源）。
+ * @module dsh-later/delivery
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+/** 投递方式（与 settings 的 steerDelivery 同源，避免循环依赖故在此重述）。 */
+export type DeliveryMode = 'followup' | 'steer';
+/**
+ * 投递确认的超时预算。
+ *
+ * 正常核对在**毫秒级**完成（消息 append 后同一次宏任务内即可读到）；2s 是留给
+ * 极端调度延迟的宽裕上限，超时即判「未确认」——宁可让用户看到可重试的提示，
+ * 也不要静默当成成功。
+ */
+export declare const DELIVERY_CONFIRM_TIMEOUT_MS = 2000;
+/**
+ * 日志中是否出现该 message id。
+ *
+ * 判据是消息**真的进了会话日志**。这里刻意不进一步区分「进了 surface」与
+ * 「进了实际请求」：`agent.followup` 路径下二者由核心保证一致（消息成为独立一轮
+ * 的唯一条消息）；而 `steer` 路径的丢失发生在**插入后同毫秒被 claim 移除**，
+ * 那种情况下连 `user/message` 都不会留下，本判据足以识别。
+ */
+export declare function hasMessageInLog(session: Session, messageId: string): boolean;
+/** 等待投递被日志确认；超时返回 false。 */
+export declare function confirmDelivery(session: Session, messageId: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * 取消息 id（`createUserMessage` 会生成 uuid）。
+ *
+ * `UserMessage.id` 在类型上是必填，但运行时若某代内核未填则这里回落空串，
+ * 调用方的确认逻辑对空 id 一律判「无法确认」。
+ */
+export declare function messageIdOf(message: UserMessage): string;

package/lib/types/domain.d.ts

@@ -16,6 +16,12 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 /** 插件名（与 cordis 条目 id / manifest 一致）。 */
 export declare const name = "dsh-later";
+/**
+ * settings 命名空间。0.1.1 要求 branded `SettingsNamespace`、0.1.2 已删除
+ * `settingsNamespace()` helper——调用处以 `'dsh-later' as SettingsNamespace`
+ * 断言注册（见 index.ts），字面量只在这里维护一份。
+ */
+export declare const SETTINGS_NAMESPACE = "dsh-later";
 /** 会话投影键：GUI 通过 `useProjection` / `faceOf` 读取用户任务列表。 */
 export declare const PROJECTION_KEY = "userSchedules";
 /**
@@ -49,6 +55,7 @@ export type UserScheduleDelivery = 'context' | 'user';
  * 字段用 snake_case，与 `user_schedule_list` 工具响应保持一致。
  */
 export interface UserScheduleWireItem {
+    /** 稳定身份：active 优先 ownership.uid，否则 scheduleId；paused 恒为 uid。 */
     readonly id: string;
     readonly kind: 'after' | 'at' | 'every';
     readonly prompt: string;
@@ -58,6 +65,19 @@ export interface UserScheduleWireItem {
     /** 创建时刻（来自 create 事件的 time；旧日志/未知时缺省）。 */
     readonly created_at?: string;
     readonly delivery_mode: 'session-local';
+    /** active 可省略（旧客户端）；paused 必带。 */
+    readonly status?: 'active' | 'paused';
+    /** 暂停冻结的剩余秒数（整数秒，仅用于倒计时文案）。 */
+    readonly remaining_seconds?: number;
+    /** 暂停时刻（ISO；客户端据此冻结进度条，避免整数秒取整造成的长度跳变）。 */
+    readonly paused_at?: string;
+    /** 日志 schedule id（pause 前 / active 当前）。 */
+    readonly schedule_id?: string;
+    /**
+     * 进度条总窗口（秒）。resume 后 `after_seconds` 只是剩余时长；
+     * 此字段保留原 after 间隔，使进度条从冻结处继续而不是从 0 重跑。
+     */
+    readonly window_seconds?: number;
 }
 /** 投影输出值。 */
 export interface UserScheduleProjectionValue {
@@ -102,6 +122,18 @@ export interface UserScheduleProjectionState {
         createdAt?: number;
     }[];
     readonly seedSeq: number;
+    /** sidecar 暂停留档的 plain-JSON 镜像（init/事件后刷新）。 */
+    readonly paused: readonly {
+        uid: string;
+        prompt: string;
+        delivery: UserScheduleDelivery;
+        kind: 'after';
+        remainingSeconds: number;
+        originalScheduledAt: string;
+        originalAfterSeconds?: number;
+        lastScheduleId: string;
+        pausedAt: number;
+    }[];
 }
 /** 判断事件是否属于本插件所有权流。 */
 export declare function isOwnedEvent(event: SessionEvent): event is SessionEvent & {

package/lib/types/index.d.ts

@@ -12,16 +12,24 @@
  * @module dsh-later
  */
 import type { Context } from '@deepseek-ai/cordis';
-import s from '@deepseek-ai/schemastery';
+import type z from '@deepseek-ai/schemastery';
 import { name } from './domain.js';
 /** 插件配置 schema（全可选，默认开箱即用；经 cordis config 覆盖）。 */
-export declare const Config: s<Schemastery.ObjectS<{
-    /** 单 session 用户任务上限。 */
-    maxSchedules: s<number, number>;
-}>, Schemastery.ObjectT<{
-    /** 单 session 用户任务上限。 */
-    maxSchedules: s<number, number>;
-}>>;
+/**
+ * 插件配置 schema（**单一事实来源**）。
+ *
+ * 0.2.0 起 `ctx.settings.describe()` 直接读 `entry.fiber.runtime.Config`
+ * （见 dsh-settings `schema(entry)`：「`entry.fiber?.runtime?.Config`，且需有
+ * `toJSON`」），据此生成该插件设置页的表单。因此**可编辑字段必须全部声明在
+ * `Config` 上**——只放在 `SchedulerSettingsSchema` 里的字段在 0.2.0 下不会
+ * 出现在设置 UI 中。
+ *
+ * 历史：0.1.5 用 `settingsProvider.register(ns, schema, …)` 注册一个**独立于
+ * Config 的** schema（即 `SchedulerSettingsSchema`），0.1.7 删除了该 API。
+ * 两代并存期间两份 schema 内容一致，现统一为 `Config` 一份，`SchedulerSettingsSchema`
+ * 保留为别名以免大范围改动调用点。
+ */
+export declare const Config: z;
 /** 所需服务（延后激活，缺失时插件不加载）。 */
 export declare const inject: string[];
 /** 宿主持有的 settings 形状（settings getter 返回值与 register* 接受入参）。 */
@@ -29,7 +37,19 @@ export interface SchedulerSettings {
     readonly maxSchedules: number;
     readonly allowLongPrompts: boolean;
     readonly maxPromptChars: number;
+    /** 插话投递方式（见 Config.steerDelivery）。 */
+    readonly steerDelivery: UserScheduleSteerDelivery;
+    /** 是否核对投递是否真正送达。 */
+    readonly confirmDelivery: boolean;
+    /** 投递未确认时：保留可重试 / 丢弃。 */
+    readonly onUnconfirmed: UserScheduleOnUnconfirmed;
+    /** 时钟图标风格（auto / modern / classic）。 */
+    readonly clockIconStyle: 'auto' | 'modern' | 'classic';
 }
+/** 插话投递方式。 */
+export type UserScheduleSteerDelivery = 'followup' | 'steer';
+/** 投递未确认时的处理。 */
+export type UserScheduleOnUnconfirmed = 'keep' | 'discard';
 export declare function apply(ctx: Context, config?: {
     maxSchedules?: number;
 }): void;

package/lib/types/ownership-store.d.ts

@@ -5,6 +5,32 @@ export interface OwnedEntry {
     readonly delivery: UserScheduleDelivery;
     /** 创建时刻（epoch ms，诊断用）。 */
     readonly createdAt: number;
+    /**
+     * 稳定插件身份（跨 pause/resume/日志 id 变更）。创建时生成；
+     * 旧条目可缺省（wire 回退用 scheduleId）。
+     */
+    readonly uid?: string;
+    /**
+     * 进度条总窗口（秒）。resume 后日志里的 `afterSeconds` 只是剩余时长，
+     * 若直接当窗口会从 0 重跑；此处保留原 after 间隔供 wire/进度条使用。
+     */
+    readonly windowSeconds?: number;
+}
+/** 暂停留档（仅 kind==='after'；不进会话日志）。 */
+export interface PausedEntry {
+    /** 稳定身份；resume 后仍用此 uid。 */
+    readonly uid: string;
+    readonly prompt: string;
+    readonly delivery: UserScheduleDelivery;
+    readonly kind: 'after';
+    /** 暂停瞬间的剩余秒数（resume 时 after_seconds）。 */
+    readonly remainingSeconds: number;
+    /** 原目标时刻（仅展示「原点 HH:MM」）。 */
+    readonly originalScheduledAt: string;
+    readonly originalAfterSeconds?: number;
+    /** 暂停前的日志 schedule id（审计/关联）。 */
+    readonly lastScheduleId: string;
+    readonly pausedAt: number;
 }
 /** 读取某会话的全部所有权记录（缓存优先；返回副本语义，调用方不得变更）。 */
 export declare function allOwnership(sessionId: string): Readonly<Record<string, OwnedEntry>>;
@@ -12,9 +38,23 @@ export declare function allOwnership(sessionId: string): Readonly<Record<string,
 export declare function hasOwnership(sessionId: string, id: string): boolean;
 /** 某条所有权记录（缺失返回 undefined）。 */
 export declare function getOwnership(sessionId: string, id: string): OwnedEntry | undefined;
-/** 记录（新增或覆盖）一条所有权；幂等。 */
-export declare function recordOwnership(sessionId: string, id: string, delivery: UserScheduleDelivery): void;
+/** 生成稳定插件 uid（pause/resume 跨日志 id 变更）。 */
+export declare function newTaskUid(): string;
+/** 记录（新增或覆盖）一条所有权；幂等。仅显式传入 `uid` 时写入稳定身份。 */
+export declare function recordOwnership(sessionId: string, id: string, delivery: UserScheduleDelivery, uid?: string, windowSeconds?: number): OwnedEntry;
 /** 撤销一条所有权；幂等（不存在时无操作）。 */
 export declare function removeOwnership(sessionId: string, id: string): void;
+/** 按 uid 找当前仍 active 的 schedule id（缺失 undefined）。 */
+export declare function findScheduleIdByUid(sessionId: string, uid: string): string | undefined;
+/** 全部暂停留档（uid → entry）。 */
+export declare function allPaused(sessionId: string): Readonly<Record<string, PausedEntry>>;
+/** 一条暂停留档。 */
+export declare function getPaused(sessionId: string, uid: string): PausedEntry | undefined;
+/** 按暂停前 schedule id 找留档（pause 刚写完、投影 fold 见 delete 时用）。 */
+export declare function findPausedByScheduleId(sessionId: string, scheduleId: string): PausedEntry | undefined;
+/** 写入/覆盖一条暂停留档。 */
+export declare function recordPaused(sessionId: string, entry: PausedEntry): void;
+/** 移除一条暂停留档；幂等。 */
+export declare function removePaused(sessionId: string, uid: string): void;
 /** 测试辅助：清空进程内缓存（不删文件）。 */
 export declare function resetCacheForTests(): void;

package/lib/types/presence.d.ts

@@ -19,21 +19,92 @@ export declare const PRESENCE_URGENT_WINDOW_MS: number;
 export interface PresenceScheduleLike {
     readonly scheduled_at?: string;
     readonly scheduledAt?: string;
+    /** `'paused'` 时该任务**没有排定的触发时刻**（冻结剩余秒数，等待恢复）。 */
+    readonly status?: string;
+    /** 暂停冻结的剩余秒数；仅在 `status === 'paused'` 时有意义。 */
+    readonly remaining_seconds?: number;
+    /** 任务类型。决定进度窗口起点按哪个口径推导（见 {@link windowStartOf}）。 */
+    readonly kind?: string;
+    /** `after` 类型的总倒计时秒数（进度起点 = 触发时刻 − 该值）。 */
+    readonly after_seconds?: number;
+    readonly afterSeconds?: number;
+    /** `every` 类型的周期间隔秒数（进度起点 = 触发时刻 − 该值，即本周期起点）。 */
+    readonly every_seconds?: number;
+    readonly everySeconds?: number;
+    /** 宿主/投影直接给的显式总窗口秒数；给了就优先于按 kind 推导。 */
+    readonly window_seconds?: number;
+    readonly windowSeconds?: number;
+    /** `at` 类型的进度起点（任务创建时刻，ISO）。`at` 没有天然周期，只能用它。 */
+    readonly created_at?: string;
+    readonly createdAt?: number;
 }
 /** 由一组活动任务归纳的 badge 概要。 */
 export interface PresenceSummary {
-    /** 可解析触发时刻的活动任务数量。 */
+    /** 计入提醒数量的任务数（**含**暂停项）。 */
     readonly count: number;
-    /** 最早触发时刻（epoch ms）；全部不可解析时缺省。 */
+    /** 最早触发时刻（epoch ms）；没有任何"会触发"的任务时缺省。 */
     readonly nextAt?: number;
+    /** 暂停中的任务数（用于文案区分「已冻结」与「等待发送」）。 */
+    readonly pausedCount: number;
+    /**
+     * 进度环起点（epoch ms）：`nextAt` 那条任务的窗口开始时刻。
+     *
+     * **只跟随 `nextAt` 那条**：环表达的是"距离最近一次触发还剩多少"，若取别条
+     * 任务的窗口就与 `nextAt` 对不上了。无从推导时缺省，此时调用方应退回恒定
+     * 整环（{@link progressOf} 返回 `undefined`）。
+     */
+    readonly progressFrom?: number;
 }
 /**
- * 归纳：取最早触发时刻 + 可解析数量。`every` 类任务在投影里携带推进后的
- * `scheduledAt`（下次触发点），与一次性任务同构参与排序。
+ * 归纳：取最早触发时刻 + 任务数量。
+ *
+ * ⚠️ **暂停项不得参与 `nextAt`**（这是一个真实缺陷的根因）。暂停 = 日志 delete +
+ * sidecar 留档；wire 里的 `scheduled_at` 是 `originalScheduledAt`（**原目标时刻**），
+ * 而该时刻在暂停时通常已成过去。若照常参与取最小值，侧栏会算出 `nextAt <= now`
+ * → 显示「有 N 条定时提醒已到期，等待发送」，但这其实是一条**已冻结、不会触发**的
+ * 提醒，用户看到的是自相矛盾的状态（实测复现）。
+ *
+ * 正确语义：暂停项**计入 `count`**（它确实是待办提醒），但**不参与 `nextAt`**
+ * ——它没有排定的触发时刻，只在恢复后才重新拥有。
+ *
+ * 全部都是暂停项时 `nextAt` 为 undefined：调用方据此显示中性的「已暂停」而非
+ * 「已到期」或"下次 X 分后"。
  */
 export declare function summarizeSchedules(schedules: readonly PresenceScheduleLike[] | undefined): PresenceSummary;
+/**
+ * 进度环比例（0–1）：`now` 在 `[progressFrom, nextAt]` 中的位置。
+ *
+ * 返回 `undefined` 表示**无从算起**（缺窗口起点，或窗口已退化），调用方此时应
+ * 退回「恒定整环」的旧表现，而不是画一个 0% 的空环 —— 后者是错误信息：
+ * 0% 是"刚开始"，`undefined` 是"算不出来"。
+ *
+ * 两端夹住：`overdue` 时 `now > nextAt`，环停在满环而不是绕出去。
+ */
+export declare function progressOf(entry: PresenceSummary, now: number): number | undefined;
 /** 由当前时刻判定 badge 状态。 */
 export declare function badgeStateFor(nextAt: number | undefined, now: number): PresenceBadgeState;
+/**
+ * 悬浮卡片状态行的完整文案（与宿主 `.hoverStatus` 行同构：一个状态点 + 一句
+ * 描述）。宿主的状态链对定时任务无感知，本插件**只追加**这样一行，不改写也
+ * 不替换宿主已有的 `空闲` / `进行中` 等行，因此既有状态优先级天然不变。
+ *
+ * @param entry - 该会话的定时概要（调用方保证 count > 0）。
+ * @param now - 当前时刻（epoch ms），用于判定 overdue 与相对时间。
+ * @param labels - 相对时间文案槽位。
+ * @param strings - 当前语言的字典。
+ * @param formatHhmm - 时钟面格式化（注入以便单测）。
+ * @param formatDate - 日期面格式化（注入以便单测）。
+ * @returns 状态文案 + 视觉状态（`done` 为中性信息态，与宿主同款状态点）。
+ */
+export declare function hoverScheduleStatus(entry: PresenceSummary, now: number, labels: RelativeFireLabels, strings: {
+    readonly hoverScheduleStatus: string;
+    readonly hoverScheduleOverdue: string;
+    /** 全部任务暂停时的文案；缺省回退到 overdue 文案，保持向后兼容。 */
+    readonly hoverSchedulePaused?: string;
+}, formatHhmm: (epoch: number) => string, formatDate: (epoch: number) => string): {
+    readonly label: string;
+    readonly tone: PresenceBadgeState;
+};
 /** 相对触发时间的文案槽位（由调用方按语言准备；时间串经 formatHhmm 注入）。 */
 export interface RelativeFireLabels {
     /** ≤1 分钟：即将发送。 */