dsh-later 1.0.0 → 1.1.0

package/lib/command-outcome.js

@@ -0,0 +1,15 @@
+/**
+ * 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 {};

package/lib/commands.js

@@ -1,4 +1,4 @@
-import { userScheduleCreate, userScheduleDelete, userScheduleEditPrompt, userScheduleList, resolvePromptLimits, } from './user-tools.js';
+import { userScheduleCreate, userScheduleDelete, userScheduleEditPrompt, userScheduleList, userSchedulePause, userScheduleResume, resolvePromptLimits, } from './user-tools.js';
 import { DEFAULT_MAX_SCHEDULES } from './user-tools.js';
 import { epochFromLocal, localFieldsOf } from './smart-window.js';
 import { detectTimeZone, formatAbsolute, formatRelative } from './time-utils.js';
@@ -27,7 +27,7 @@ function parsePayload(rawInput) {
 /** 中文数字 → 数值（支持 十/两/半 由调用方特判）。 */
 const CN_DIGIT = { 零: 0, 一: 1, 二: 2, 两: 2, 三: 3, 四: 4, 五: 5, 六: 6, 七: 7, 八: 8, 九: 9 };
 function cnToNumber(text) {
-    if (/^\d+$/.test(text))
+    if (/^\d+(?:\.\d+)?$/.test(text))
         return Number(text);
     const tenIdx = text.indexOf('十');
     if (tenIdx >= 0) {
@@ -68,11 +68,11 @@ const CN_UNIT_SECONDS = {
 };
 /** 在归一化文本开头尝试匹配一个时间表达式；失败返回 undefined。 */
 function matchTimeExpr(s) {
-    // 1. 拉丁相对时长：+30m / +1h30m / +90s / +1w（后面可跟内容）
-    const latinRel = /^\+\s*((?:\d+\s*(?:s|m|h|d|w)\s*)+)(?![0-9a-z])/i.exec(s);
+    // 1. 拉丁相对时长：+30m / +1h30m / +90s / +1w / +2.5h（后面可跟内容）
+    const latinRel = /^\+\s*((?:\d+(?:\.\d+)?\s*(?:s|m|h|d|w)\s*)+)(?![0-9a-z])/i.exec(s);
     if (latinRel !== null) {
         let total = 0;
-        const unitRe = /(\d+)\s*(s|m|h|d|w)/gi;
+        const unitRe = /(\d+(?:\.\d+)?)\s*(s|m|h|d|w)/gi;
         for (const match of (latinRel[1] ?? '').matchAll(unitRe)) {
             const n = Number(match[1]);
             const u = (match[2] ?? 'm').toLowerCase();
@@ -82,8 +82,8 @@ function matchTimeExpr(s) {
             return undefined;
         return { consumed: latinRel[0].length, target: { kind: 'after', afterSeconds: total } };
     }
-    // 2. 中文相对时长：30分钟后 / 半小时后 / 两小时后 / 1天以后
-    const cnRel = /^(半|\d+|[零一二两三四五六七八九十]+)\s*(个\s*小时|秒钟?|分钟?|小时|钟头|天|日|周)\s*(?:之)?后?/.exec(s);
+    // 2. 中文相对时长：30分钟后 / 半小时后 / 两小时后 / 1天以后 / 2.5小时后
+    const cnRel = /^(半|\d+(?:\.\d+)?|[零一二两三四五六七八九十]+)\s*(个\s*小时|秒钟?|分钟?|小时|钟头|天|日|周)\s*(?:之)?后?/.exec(s);
     if (cnRel !== null) {
         const value = cnRel[1] === '半' ? 0.5 : cnToNumber(cnRel[1] ?? '');
         const unitKey = (cnRel[2] ?? '').replace(/\s+/g, '');
@@ -419,6 +419,54 @@ export function userScheduleCommands(ctx, getSettings = DEFAULT_MAX_SCHEDULES, o
             return { kind: 'success', text: JSON.stringify(result) };
         },
     };
+    /** 暂停 after 提醒：sidecar 留档 + 日志 delete（GUI ⏸）。 */
+    const pause = {
+        name: `${PREFIX}-pause`,
+        description: '暂停一条 after 类定时提醒（仅 GUI 内部通道；已到点不可暂停）。',
+        recordInput: false,
+        handler: async (invocation) => {
+            const parsed = parsePayload(invocation.rawInput);
+            if (!parsed.ok)
+                return renderError(parsed.text);
+            const id = parsed.value['id'];
+            const result = await userSchedulePause(id, invocation.agent, ctx);
+            if (!result.ok) {
+                return { kind: 'error', text: `${result.code}: ${result.message}` };
+            }
+            try {
+                onUserChange?.(invocation.agent);
+            }
+            catch {
+                /* 通知失败不影响命令成功结果 */
+            }
+            return { kind: 'success', text: JSON.stringify(result) };
+        },
+    };
+    /** 恢复暂停项：after_seconds=remaining 重建；uid 不变、日志 id 会变。 */
+    const resume = {
+        name: `${PREFIX}-resume`,
+        description: '恢复一条已暂停的 after 提醒（仅 GUI 内部通道）。',
+        recordInput: false,
+        handler: async (invocation) => {
+            const parsed = parsePayload(invocation.rawInput);
+            if (!parsed.ok)
+                return renderError(parsed.text);
+            const uid = parsed.value['uid']
+                ?? parsed.value['id'];
+            const { maxSchedules } = resolveSettings();
+            const result = await userScheduleResume(uid, invocation.agent, ctx, maxSchedules);
+            if (!result.ok) {
+                return { kind: 'error', text: `${result.code}: ${result.message}` };
+            }
+            try {
+                onUserChange?.(invocation.agent);
+            }
+            catch {
+                /* 通知失败不影响命令成功结果 */
+            }
+            return { kind: 'success', text: JSON.stringify(result) };
+        },
+    };
     // 用户主动插话（GUI「插话发送」按钮）：把已到点的 reminder 立即 steer 进 agent。
     // 仅 one-shot 支持；every 类提醒因 batch framing 需要更多 plumbing 暂未开放。
     const steer = {
@@ -511,7 +559,7 @@ export function userScheduleCommands(ctx, getSettings = DEFAULT_MAX_SCHEDULES, o
         recordInput: false,
         handler: buildQuickHandler('user'),
     };
-    return [create, list, del, edit, steer, quick, later];
+    return [create, list, del, edit, pause, resume, steer, quick, later];
 }
 /** 注册三个命令，返回统一 disposer。 */
 export function registerUserScheduleCommands(ctx, getSettings = DEFAULT_MAX_SCHEDULES, onUserChange, onUserSteer) {

package/lib/delivery.js

@@ -0,0 +1,66 @@
+import { readOwnEvents } from './upstream-compat.js';
+/**
+ * 投递确认的超时预算。
+ *
+ * 正常核对在**毫秒级**完成（消息 append 后同一次宏任务内即可读到）；2s 是留给
+ * 极端调度延迟的宽裕上限，超时即判「未确认」——宁可让用户看到可重试的提示，
+ * 也不要静默当成成功。
+ */
+export const DELIVERY_CONFIRM_TIMEOUT_MS = 2000;
+/** 投递确认轮询间隔（远小于超时预算，保证正常情况一两轮即命中）。 */
+const CONFIRM_POLL_INTERVAL_MS = 25;
+/**
+ * 日志中是否出现该 message id。
+ *
+ * 判据是消息**真的进了会话日志**。这里刻意不进一步区分「进了 surface」与
+ * 「进了实际请求」：`agent.followup` 路径下二者由核心保证一致（消息成为独立一轮
+ * 的唯一条消息）；而 `steer` 路径的丢失发生在**插入后同毫秒被 claim 移除**，
+ * 那种情况下连 `user/message` 都不会留下，本判据足以识别。
+ */
+export function hasMessageInLog(session, messageId) {
+    try {
+        for (const event of readOwnEvents(session)) {
+            const data = event.data;
+            if (data === null || typeof data !== 'object')
+                continue;
+            const record = data;
+            // user/message 形态：{ content, source, role, id }
+            if (record.id === messageId)
+                return true;
+            // assistant/step 等包裹形态：{ message: { id, ... } }
+            const nested = record.message;
+            if (nested !== null && typeof nested === 'object' && nested.id === messageId) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // 读日志失败一律按「未确认」处理：不确认就不敢写 dispatch。
+        return false;
+    }
+    return false;
+}
+/** 等待投递被日志确认；超时返回 false。 */
+export async function confirmDelivery(session, messageId, timeoutMs = DELIVERY_CONFIRM_TIMEOUT_MS) {
+    if (hasMessageInLog(session, messageId))
+        return true;
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => {
+            setTimeout(resolve, CONFIRM_POLL_INTERVAL_MS);
+        });
+        if (hasMessageInLog(session, messageId))
+            return true;
+    }
+    return false;
+}
+/**
+ * 取消息 id（`createUserMessage` 会生成 uuid）。
+ *
+ * `UserMessage.id` 在类型上是必填，但运行时若某代内核未填则这里回落空串，
+ * 调用方的确认逻辑对空 id 一律判「无法确认」。
+ */
+export function messageIdOf(message) {
+    const id = message.id;
+    return typeof id === 'string' ? id : '';
+}

package/lib/domain.js

@@ -1,5 +1,11 @@
 /** 插件名（与 cordis 条目 id / manifest 一致）。 */
 export const name = 'dsh-later';
+/**
+ * settings 命名空间。0.1.1 要求 branded `SettingsNamespace`、0.1.2 已删除
+ * `settingsNamespace()` helper——调用处以 `'dsh-later' as SettingsNamespace`
+ * 断言注册（见 index.ts），字面量只在这里维护一份。
+ */
+export const SETTINGS_NAMESPACE = 'dsh-later';
 /** 会话投影键：GUI 通过 `useProjection` / `faceOf` 读取用户任务列表。 */
 export const PROJECTION_KEY = 'userSchedules';
 /**

package/lib/index.js

@@ -4,34 +4,76 @@ import { userSchedulesProjectionUnit } from './projection.js';
 import { registerUserScheduleCommands } from './commands.js';
 import { UserScheduleRuntime } from './runtime.js';
 import { DEFAULT_MAX_PROMPT_CHARS, DEFAULT_MAX_SCHEDULES, resolvePromptLimits, userScheduleCreate, userScheduleDelete, userScheduleList, } from './user-tools.js';
-import { name } from './domain.js';
+import { name, SETTINGS_NAMESPACE } from './domain.js';
 import { registerOwnedSessionEventType } from './owned-event-registration.js';
 /** 插件配置 schema（全可选，默认开箱即用；经 cordis config 覆盖）。 */
+/**
+ * 插件配置 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 const Config = s.object({
     /** 单 session 用户任务上限。 */
     maxSchedules: s.number().step(1).min(1).default(DEFAULT_MAX_SCHEDULES),
-});
-/** Settings namespace schema（设置 - 插件 配置 UI）。 */
-const SchedulerSettingsSchema = s.object({
-    /** 单 session 用户任务上限。 */
-    maxSchedules: s.number().step(1).min(1).default(DEFAULT_MAX_SCHEDULES),
     /** 是否解除提示字符的默认下限（1000）；关闭时 maxPromptChars 不生效。 */
     allowLongPrompts: s.boolean().default(false),
     /** 提示字符上限（≥1 整数）；仅在 allowLongPrompts=true 时生效。 */
     maxPromptChars: s.number().step(1).min(1).default(DEFAULT_MAX_PROMPT_CHARS),
-    /** 智能时段：工作时间开始（HH:mm）。 */
-    workStart: s.string().default('09:00'),
-    /** 智能时段：工作时间结束（HH:mm）。 */
-    workEnd: s.string().default('18:00'),
-    /** 智能时段：午休开始（HH:mm）。 */
-    lunchStart: s.string().default('12:00'),
-    /** 智能时段：午休结束（HH:mm）。 */
-    lunchEnd: s.string().default('14:00'),
-    /** 智能时段：晚间结束（HH:mm）。 */
-    eveningEnd: s.string().default('22:00'),
     /** 是否显示输入框右侧的定时按钮（仅 GUI 显隐；提醒触发与 dock 不受影响）。 */
     showButton: s.boolean().default(true),
-});
+    /**
+     * 插话投递方式（「插话发送」把提醒内容推给 agent 时进哪个队列）。
+     *
+     * - `followup`：入 `next-turn`，**独立成一轮**（等价于「正常发送」）。`next-turn`
+     *   与 `next-step` 是两条独立队列，核心的 `claim('next-step', …)` 不触碰它，
+     *   因此**不存在**与 `turn/start` 竞争而被吞的窗口。默认。
+     * - `steer`：入 `next-step`，在下一个 step 边界消费，更快；但若插话恰好撞上
+     *   `turn/start`，核心的 `claim` 会把整批 `next-step` 取走并交给一个**请求上下文
+     *   已定**的 step，消息会落进 surface 却不进实际请求 —— 静默丢失（实测复现见
+     *   runtime.steerById 注释）。
+     */
+    steerDelivery: s.union([s.const('followup'), s.const('steer')]).default('followup'),
+    /**
+     * 投递确认：投递后核对会话日志中是否出现该 message id。
+     *
+     * 关闭则恢复 fire-and-forget（不读日志、不保证送达）。
+     */
+    confirmDelivery: s.boolean().default(true),
+    /**
+     * 投递未确认时的处理。
+     *
+     * - `keep`：**不写 dispatch**，条目留在 active 可重试（配合确认默认开启，使
+     *   `steer` 由「会丢」降级为「需重试」）。默认。
+     * - `discard`：按旧语义写 dispatch 出列 —— 注意这会让静默丢失重新变得可能，
+     *   仅供明确需要旧行为的场景。
+     */
+    onUnconfirmed: s.union([s.const('keep'), s.const('discard')]).default('keep'),
+    /**
+     * 时钟图标风格。
+     *
+     * - `auto`：按 DSH 内核版本自动选择（0.2.0+ 用新版官方描边风格，0.1.x 用旧版点阵风格）。默认。
+     * - `modern`：强制使用新版官方描边风格（24×24 stroke 圆头线帽）。
+     * - `classic`：强制使用旧版点阵风格（10×10 fill 方块 crispEdges）。
+     */
+    clockIconStyle: s.union([s.const('auto'), s.const('modern'), s.const('classic')]).default('auto'),
+}).volatile();
+/**
+ * 0.1.5 时代 settings namespace 注册所用的 schema。
+ *
+ * 与 {@link Config} 同源（同一 schema 对象）：0.1.5 的
+ * `settingsProvider.register()` 需要显式传入，而 0.2.0 的 `describe()` 只认
+ * `Config`。保留此别名让两代共用一份定义，避免两份 schema 漂移。
+ */
+const SchedulerSettingsSchema = Config;
 /** 所需服务（延后激活，缺失时插件不加载）。 */
 export const inject = ['agents', 'sessions', 'tools', 'commands', 'settings'];
 /** 解析配置（容错非法值回落默认）。 */
@@ -40,6 +82,14 @@ function resolveMaxSchedules(value) {
         return DEFAULT_MAX_SCHEDULES;
     return Math.floor(value);
 }
+/**
+ * 本插件在 profile 里的**条目 id**。
+ *
+ * 必须与 `cordis.patch.yml` 的 `id:` 一致：0.2.0 的 `configForms.get(entryId)`
+ * 与 `SettingsForms.describe()` 的 `ns` 都用条目 id 寻址，用错会静默拿不到
+ * 表单/值（设置页空白，无报错）。
+ */
+const ENTRY_ID = 'later';
 /** 根据 settings 计算当前生效的提示字符上限（与 user-tools.resolvePromptLimits 同源）。 */
 function resolveSchedulerPromptLimits(settings) {
     return resolvePromptLimits({
@@ -209,22 +259,92 @@ export function apply(ctx, config) {
         maxSchedules: startMaxSchedules,
         allowLongPrompts: false,
         maxPromptChars: DEFAULT_MAX_PROMPT_CHARS,
+        steerDelivery: 'followup',
+        confirmDelivery: true,
+        onUnconfirmed: 'keep',
+        clockIconStyle: 'auto',
     };
     let getSettings = () => startSettings;
     ctx.inject(['settings'], (settingsCtx) => {
-        const scope = settingsCtx.settings.register(
+        // 0.1.7 移除了整个 `settings.yaml` 体系：`SettingsProvider.register()` 不复存在，
+        // `ctx.settings` 变成 `SettingsForms`（只有 configure/describe/prepareDocument），
+        // 命名空间 schema 改为**由 profile 声明驱动**（见 0.1.7 dsh-settings 的类型注释
+        // “Move the sections of the removed settings.yaml into the active profile”）。
+        //
+        // 照旧调用会抛错并让整个 settings 注入失败，因此这里做代次探测：拿不到
+        // `register` 就保持 `startSettings`（即 profile yml 的 `base` 值），
+        // 插件功能不受影响，只是不再支持运行时热改设置。
+        //
+        // TODO(0.1.7 配置迁移)：把 SchedulerSettingsSchema 迁到 profile 声明式配置，
+        // 恢复 GUI 设置页与 live 生效。这是跨 15 个插件的架构课题，单独排期。
+        //
+        // 类型收窄：0.1.5 的 `SettingsProvider` 有 `register`，0.1.7 的 `SettingsForms`
+        // 没有——直接用联合类型会让两代都无法通过编译，故按「本插件所需的最小面」
+        // 声明本地接口，再对运行时对象做一次存在性判断。
+        const provider = settingsCtx.settings;
+        /**
+         * 把「settings 原始值」规整为运行时设置（容错非法值回落默认）。
+         * 三条代次轨道共用，避免各处重复解析逻辑。
+         */
+        const readSettings = (value) => ({
+            maxSchedules: resolveMaxSchedules(value?.maxSchedules ?? startSettings.maxSchedules),
+            allowLongPrompts: value?.allowLongPrompts === true,
+            maxPromptChars: typeof value?.maxPromptChars === 'number' && value.maxPromptChars >= 1
+                ? Math.floor(value.maxPromptChars)
+                : startSettings.maxPromptChars,
+            // 非法/缺失回落默认：投递方式默认 followup（安全侧），确认默认开，
+            // 未确认默认保留（不丢消息）。
+            steerDelivery: value?.steerDelivery === 'steer' ? 'steer' : 'followup',
+            confirmDelivery: value?.confirmDelivery !== false,
+            onUnconfirmed: value?.onUnconfirmed === 'discard' ? 'discard' : 'keep',
+            clockIconStyle: value?.clockIconStyle === 'modern' || value?.clockIconStyle === 'classic'
+                ? value.clockIconStyle
+                : 'auto',
+        });
+        // ── 轨道 1：0.2.0（settings rewrite 第二版）─────────────────────────────
+        //
+        // 0.2.0 的 `ctx.settings` 是 `SettingsForms`，**没有 `register()`**；表单由
+        // `describe()` 从 `entry.fiber.runtime.Config`（即本插件导出的 `Config`）
+        // 自动生成，值来自该 profile 条目已合并的 `config`。
+        //
+        // 因此这一代**无需注册**：字段已在 `Config` 上声明，宿主自会渲染设置页。
+        // 插件侧只需读取「当前生效配置」。但 `Config` 的默认值由 cordis 在构造时
+        // 填充，运行中热改需从 describe() 快照取——故这里订阅 document 更新事件，
+        // 把最新值同步进 getSettings，实现与 0.1.5 相同的 `applies: 'live'` 语义。
+        const forms = settingsCtx.settings;
+        if (typeof provider.register !== 'function' && typeof forms.describe === 'function') {
+            const describeValue = () => {
+                try {
+                    // entry id = profile 条目 id（`cordis.patch.yml` 的 `id: later`），
+                    // **不是** settings namespace（'dsh-later'）——见 dsh-settings
+                    // describe()：`ns: entry.options.id`。
+                    const row = forms
+                        .describe?.({ redactSecrets: true })
+                        .find((candidate) => candidate.ns === ENTRY_ID);
+                    return row?.value;
+                }
+                catch {
+                    return undefined;
+                }
+            };
+            getSettings = () => readSettings(describeValue());
+            // 文档更新 → 重新取值（宿主在 describe 检测到变化时发该事件）。
+            settingsCtx.on('settings/document-updated', (ns) => {
+                if (ns !== ENTRY_ID && ns !== SETTINGS_NAMESPACE)
+                    return;
+                getSettings = () => readSettings(describeValue());
+            });
+            return;
+        }
+        // ── 轨道 2：0.1.5 及更早（settings.yaml 体系）──────────────────────────
+        if (typeof provider.register !== 'function')
+            return;
+        const scope = provider.register(
         // 断言而非 settingsNamespace()：0.1.1 要求 branded 类型，0.1.2 已删除该 helper。
-        'dsh-later', SchedulerSettingsSchema, { applies: 'live' });
+        SETTINGS_NAMESPACE, SchedulerSettingsSchema, { applies: 'live' });
         getSettings = () => {
             try {
-                const value = scope.get();
-                return {
-                    maxSchedules: resolveMaxSchedules(value?.maxSchedules ?? startSettings.maxSchedules),
-                    allowLongPrompts: value?.allowLongPrompts === true,
-                    maxPromptChars: typeof value?.maxPromptChars === 'number' && value.maxPromptChars >= 1
-                        ? Math.floor(value.maxPromptChars)
-                        : startSettings.maxPromptChars,
-                };
+                return readSettings(scope.get());
             }
             catch {
                 return startSettings;
@@ -254,10 +374,13 @@ export function apply(ctx, config) {
     ctx.effect(() => registerUserScheduleCommands(ctx, getSettings, notifyUserChange, notifyUserSteer), 'later.commands()');
     // 3. 每个 root agent：注册用户工具 + 用户调度器生命周期。
     ctx.effect(() => {
-        const stopCreated = ctx.on('agent/created', ({ agent }) => {
+        // 0.1.7 起 `agent/created` 是**异步串行**事件：回调须返回 Promise，且首次
+        // 模型请求会等待初始化完成。0.1.5/0.1.2 的同步回调签名在 0.1.7 下会因
+        // 返回 void 而不匹配，故显式 async。
+        const stopCreated = ctx.on('agent/created', async ({ agent }) => {
             if (stopping || runtimes.has(agent) || !ctx.agents.roots().includes(agent))
                 return;
-            const runtime = new UserScheduleRuntime(ctx, agent);
+            const runtime = new UserScheduleRuntime(ctx, agent, getSettings);
             let cleanup = () => undefined;
             try {
                 cleanup = agent.ctx.effect(() => {

package/lib/ownership-store.js

@@ -17,7 +17,7 @@
  * - 容错读：JSON 损坏时把坏文件改名保留（.corrupt-<ts>），按空表继续；
  * - 进程内缓存：按 (mtimeMs, size) 校验，避免热路径反复读盘；
  * - 路径解析：`DSH_LATER_STATE_DIR`（测试/便携）> 旧名
- *   `DSH_LATER_STATE_DIR`（升级过渡）> `$DSH_HOME` > `~/.dsh`
+ *   `DSH_SESSION_SCHEDULER_STATE_DIR`（升级过渡）> `$DSH_HOME` > `~/.dsh`
  *   （与 dsh-home-paths 的默认解析一致）。
  *
  * 注意：本模块只被 host 端引用；client bundle 不得引入（依赖 node:fs）。
@@ -26,10 +26,29 @@
 import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync, existsSync, unlinkSync, readdirSync, copyFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+/**
+ * 显式状态目录覆盖（测试 / 便携场景）。
+ *
+ * 两个变量名等价：`DSH_LATER_STATE_DIR` 是当前名，`DSH_SESSION_SCHEDULER_STATE_DIR`
+ * 是插件改名前（`session-scheduler`）的旧名，保留以兼容既有脚本与文档。
+ *
+ * 修复记录：此前两处都写成 `DSH_LATER_STATE_DIR ?? DSH_LATER_STATE_DIR`——
+ * 同一个变量自比较，旧名回退实际从未生效。旧名用户会静默落到 `$DSH_HOME`
+ * 默认目录，而 `legacyStateDir()` 又因"有 override"直接返回 undefined，
+ * 迁移也不会发生。
+ */
+function stateDirOverride() {
+    for (const name of ['DSH_LATER_STATE_DIR', 'DSH_SESSION_SCHEDULER_STATE_DIR']) {
+        const value = process.env[name];
+        if (value !== undefined && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
 /** 解析状态目录（优先级见模块注释）。 */
 function resolveStateDir() {
-    const override = process.env['DSH_LATER_STATE_DIR'] ?? process.env['DSH_LATER_STATE_DIR'];
-    if (override !== undefined && override.trim().length > 0)
+    const override = stateDirOverride();
+    if (override !== undefined)
         return override;
     const dshHomeEnv = process.env['DSH_HOME'];
     const home = dshHomeEnv !== undefined && dshHomeEnv.trim().length > 0 ? dshHomeEnv : join(homedir(), '.dsh');
@@ -40,8 +59,7 @@ function resolveStateDir() {
  * 不做迁移以免污染调用方给定的目录语义）。
  */
 function legacyStateDir() {
-    const override = process.env['DSH_LATER_STATE_DIR'] ?? process.env['DSH_LATER_STATE_DIR'];
-    if (override !== undefined && override.trim().length > 0)
+    if (stateDirOverride() !== undefined)
         return undefined;
     const dshHomeEnv = process.env['DSH_HOME'];
     const home = dshHomeEnv !== undefined && dshHomeEnv.trim().length > 0 ? dshHomeEnv : join(homedir(), '.dsh');
@@ -93,7 +111,7 @@ function fileOf(sessionId) {
     return join(stateDir(), `${safe}.json`);
 }
 function emptyFile() {
-    return { version: 1, entries: {} };
+    return { version: 2, entries: {}, paused: {} };
 }
 /** 进程内缓存：sessionId → (mtime, size, file)。写路径同步更新缓存。 */
 const cache = new Map();
@@ -115,12 +133,18 @@ function readFresh(sessionId) {
         const parsed = JSON.parse(readFileSync(path, 'utf8'));
         if (typeof parsed !== 'object' ||
             parsed === null ||
-            parsed.version !== 1 ||
+            (parsed.version !== 1 &&
+                parsed.version !== 2) ||
             typeof parsed.entries !== 'object' ||
             parsed.entries === null) {
             throw new Error('unexpected shape');
         }
-        const file = parsed;
+        // v1 → v2：补空 paused，写回时统一升到 2
+        const file = {
+            version: 2,
+            entries: parsed.entries,
+            paused: parsed.paused ?? {},
+        };
         cache.set(sessionId, { mtimeMs: stat.mtimeMs, size: stat.size, file });
         return file;
     }
@@ -187,14 +211,34 @@ function writeThrough(sessionId, file) {
 function safeName(sessionId) {
     return sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
 }
-/** 记录（新增或覆盖）一条所有权；幂等。 */
-export function recordOwnership(sessionId, id, delivery) {
-    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof id !== 'string' || id.length === 0)
-        return;
+/** 生成稳定插件 uid（pause/resume 跨日志 id 变更）。 */
+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) {
+    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 } : {}),
+        };
+        return bare;
+    }
     const file = readFresh(sessionId);
     const entries = { ...file.entries };
-    entries[id] = { delivery, createdAt: Date.now() };
-    writeThrough(sessionId, { version: 1, entries });
+    const nextUid = uid ?? entries[id]?.uid;
+    const nextWindow = windowSeconds ?? entries[id]?.windowSeconds;
+    const entry = {
+        delivery,
+        createdAt: Date.now(),
+        ...(nextUid !== undefined ? { uid: nextUid } : {}),
+        ...(typeof nextWindow === 'number' ? { windowSeconds: nextWindow } : {}),
+    };
+    entries[id] = entry;
+    writeThrough(sessionId, { version: 2, entries, paused: file.paused ?? {} });
+    return entry;
 }
 /** 撤销一条所有权；幂等（不存在时无操作）。 */
 export function removeOwnership(sessionId, id) {
@@ -205,7 +249,61 @@ export function removeOwnership(sessionId, id) {
         return;
     const entries = { ...file.entries };
     delete entries[id];
-    writeThrough(sessionId, { version: 1, entries });
+    writeThrough(sessionId, { version: 2, entries, paused: file.paused ?? {} });
+}
+/** 按 uid 找当前仍 active 的 schedule id（缺失 undefined）。 */
+export function findScheduleIdByUid(sessionId, uid) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof uid !== 'string')
+        return undefined;
+    for (const [id, entry] of Object.entries(readFresh(sessionId).entries)) {
+        if (entry.uid === uid)
+            return id;
+    }
+    return undefined;
+}
+/** 全部暂停留档（uid → entry）。 */
+export function allPaused(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return {};
+    return readFresh(sessionId).paused ?? {};
+}
+/** 一条暂停留档。 */
+export function getPaused(sessionId, uid) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof uid !== 'string')
+        return undefined;
+    return (readFresh(sessionId).paused ?? {})[uid];
+}
+/** 按暂停前 schedule id 找留档（pause 刚写完、投影 fold 见 delete 时用）。 */
+export function findPausedByScheduleId(sessionId, scheduleId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof scheduleId !== 'string')
+        return undefined;
+    for (const entry of Object.values(readFresh(sessionId).paused ?? {})) {
+        if (entry.lastScheduleId === scheduleId)
+            return entry;
+    }
+    return undefined;
+}
+/** 写入/覆盖一条暂停留档。 */
+export function recordPaused(sessionId, entry) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof entry.uid !== 'string')
+        return;
+    const file = readFresh(sessionId);
+    writeThrough(sessionId, {
+        version: 2,
+        entries: file.entries,
+        paused: { ...(file.paused ?? {}), [entry.uid]: entry },
+    });
+}
+/** 移除一条暂停留档；幂等。 */
+export function removePaused(sessionId, uid) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof uid !== 'string')
+        return;
+    const file = readFresh(sessionId);
+    const paused = { ...(file.paused ?? {}) };
+    if (!Object.prototype.hasOwnProperty.call(paused, uid))
+        return;
+    delete paused[uid];
+    writeThrough(sessionId, { version: 2, entries: file.entries, paused });
 }
 /** 测试辅助：清空进程内缓存（不删文件）。 */
 export function resetCacheForTests() {