dsh-later 1.0.0

package/lib/index.js

@@ -0,0 +1,298 @@
+import s from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+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 { registerOwnedSessionEventType } from './owned-event-registration.js';
+/** 插件配置 schema（全可选，默认开箱即用；经 cordis config 覆盖）。 */
+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),
+});
+/** 所需服务（延后激活，缺失时插件不加载）。 */
+export const inject = ['agents', 'sessions', 'tools', 'commands', 'settings'];
+/** 解析配置（容错非法值回落默认）。 */
+function resolveMaxSchedules(value) {
+    if (typeof value !== 'number' || value < 1)
+        return DEFAULT_MAX_SCHEDULES;
+    return Math.floor(value);
+}
+/** 根据 settings 计算当前生效的提示字符上限（与 user-tools.resolvePromptLimits 同源）。 */
+function resolveSchedulerPromptLimits(settings) {
+    return resolvePromptLimits({
+        allowLongPrompts: settings.allowLongPrompts,
+        maxPromptChars: settings.maxPromptChars,
+    });
+}
+/** 纯泛化等待卡片（GenericCallView）。 */
+function present(title, kind, rawInput) {
+    return {
+        card: 'generic',
+        title,
+        kind,
+        ...(rawInput === undefined ? {} : { rawInput }),
+    };
+}
+/** 渲染工具结果：JSON 文本。 */
+function renderText(_args, value) {
+    return [{ type: 'text', text: value }];
+}
+/** 为单个 root agent 注册 `user_schedule_*` 工具。 */
+function registerUserScheduleTools(rootCtx, toolCtx, agent, getSettings, onUserChange) {
+    const dispose = () => undefined;
+    try {
+        const disposers = [
+            toolCtx.tools.register(defineTool({
+                name: 'user_schedule_create',
+                // description 在每次 register 时按当前 settings 生成：
+                // 模型看到的字符上限始终与宿主实际校验一致，避免描述与实现脱节。
+                description: '为用户创建一条当前会话内的定时提醒。必须提供非空提示与恰好一个选择器：after_seconds（正整数延时秒）、at（显式偏移时间或 {date,time,time_zone} 本地时间）、every_seconds（≥300 的固定间隔秒）。time_zone 可选，缺省用会话检测时区。创建来源被标记为用户工具，GUI 面板会展示。',
+                parameters: {
+                    prompt: {
+                        type: 'string',
+                        required: true,
+                        description: `提醒内容（trim 后非空，≤${resolveSchedulerPromptLimits(getSettings()).maxChars} 字符；超过会返回 invalid_prompt）。`,
+                    },
+                    after_seconds: { type: 'number', description: '正整数延时秒数。' },
+                    every_seconds: { type: 'number', description: '固定间隔秒数，至少 300。' },
+                    at: {
+                        description: '绝对目标：显式偏移的 RFC 3339 字符串，或 {date, time, time_zone} 本地日历对象。',
+                        oneOf: [
+                            { type: 'string' },
+                            {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    date: { type: 'string', required: true },
+                                    time: { type: 'string', required: true },
+                                    time_zone: { type: 'string', required: true },
+                                },
+                            },
+                        ],
+                    },
+                    time_zone: { type: 'string', description: 'IANA 时区（如 Asia/Shanghai）；可选，缺省用会话检测时区。' },
+                },
+                output: {
+                    schema: { type: 'string' },
+                    render: renderText,
+                },
+                async execute(args, exec) {
+                    if (exec.agent !== agent)
+                        return JSON.stringify({ ok: false, code: 'internal_error', message: '操作失败。' });
+                    const settings = getSettings();
+                    const result = await userScheduleCreate(args, agent, rootCtx, settings.maxSchedules, undefined, resolveSchedulerPromptLimits(settings));
+                    if (result.ok) {
+                        try {
+                            onUserChange(agent);
+                        }
+                        catch {
+                            /* 通知失败不影响结果 */
+                        }
+                    }
+                    return JSON.stringify(result);
+                },
+                presentCall: (args) => present('创建定时提醒', 'other', args?.prompt),
+            })),
+            toolCtx.tools.register(defineTool({
+                name: 'user_schedule_list',
+                description: '列出当前会话内用户创建的活动定时提醒（含 id、UTC 目标、scheduled/overdue 状态、投递模式）。',
+                parameters: {},
+                output: {
+                    schema: { type: 'string' },
+                    render: renderText,
+                },
+                async execute(_args, exec) {
+                    if (exec.agent !== agent)
+                        return JSON.stringify({ ok: false, code: 'internal_error', message: '操作失败。' });
+                    const result = await userScheduleList(agent, rootCtx);
+                    return JSON.stringify(result);
+                },
+                presentCall: () => present('列出定时提醒', 'read'),
+            })),
+            toolCtx.tools.register(defineTool({
+                name: 'user_schedule_delete',
+                description: '按 user_schedule_create / user_schedule_list 返回的精确 id 删除一条活动提醒；未知或已结束返回 deleted:false。',
+                parameters: {
+                    id: { type: 'string', required: true, description: '精确会话内 schedule id。' },
+                },
+                output: {
+                    schema: { type: 'string' },
+                    render: renderText,
+                },
+                async execute(args, exec) {
+                    if (exec.agent !== agent)
+                        return JSON.stringify({ ok: false, code: 'internal_error', message: '操作失败。' });
+                    const result = await userScheduleDelete(args.id, agent, rootCtx);
+                    if (result.ok && result.deleted) {
+                        try {
+                            onUserChange(agent);
+                        }
+                        catch {
+                            /* 通知失败不影响结果 */
+                        }
+                    }
+                    return JSON.stringify(result);
+                },
+                presentCall: (args) => present('删除定时提醒', 'other', args?.id),
+            })),
+        ];
+        return () => {
+            for (const disposeOne of disposers.reverse())
+                disposeOne();
+        };
+    }
+    catch (error) {
+        dispose();
+        rootCtx.logger.warn(`later: user tools 注册失败: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}
+/**
+ * Cordis 函数插件主体。
+ * @param ctx - 全局服务上下文。
+ * @param config - 可选配置（maxSchedules）。
+ */
+/** 插件卸载中的标记（避免继续接受新 agent 挂载）。 */
+let stopping = false;
+export function apply(ctx, config) {
+    // P0-2：cordis 在配置变更/重载时会 teardown 后再次 apply。stopping 是模块级
+    // 标志，若不复位，第二次 apply 起所有 agent 都会在 agent/created 处早退，
+    // 用户工具与调度器静默不挂载（GUI 无按钮、提醒永不触发）。
+    stopping = false;
+    // yml 启动配置仅在首次解析时生效（与运行时用户设置正交，参见
+    // dsh-smooth-stream 等同款做法）：用户在设置页保存的值走自己的 user 层，
+    // 不与 yml base 混合。命令/工具每次调用通过 getSettings() 按需读取设置层的
+    // maxSchedules（设置未保存则回退 yml/默认）。
+    const startMaxSchedules = resolveMaxSchedules(config?.maxSchedules);
+    // 0. 注册自有事件类型（进程级、幂等）：否则含 `session-scheduler/user-schedule`
+    //    的日志会被任何加载了本插件的读者以 SessionFormatUnsupportedError 拒读
+    //    （GUI 表现为「历史加载失败」）。详见 domain.ts 中的说明。
+    registerOwnedSessionEventType();
+    // 1. `userSchedules` 会话投影（GUI 读状态）。
+    // `as never`：本插件 dev 依赖解析到的 @deepseek-ai/dsh-session-projection
+    // 可能是旧版（rc.1，契约 `schema`+顶层 `view`），而宿主运行时是 rc.2
+    // （契约 `stateSchema`+`wire{viewSchema,view}`）。两者在类型层冲突，
+    // 直接类型化注册会被旧版契约拒掉；运行时又必须按 rc.2 传。故此处保留
+    // `as never` 显式声明「运行时契约以宿主为准」，并用
+    // `tests/projection-unit.test.mjs` 在运行时锁定 rc.2 形状，防止回归。
+    ctx.inject(['sessionProjections'], (projectionCtx) => {
+        projectionCtx.sessionProjections.register(userSchedulesProjectionUnit);
+    });
+    // 2. 注册 settings namespace（设置 - 插件 配置 UI）。
+    // 拿住 owner scope：`applies: 'live'` 声明改动即时生效。工具/命令 handler
+    // 每次调用通过 getSettings() 按需读取——避免主动 watch 引入的一致性边界与
+    // 误同步（对齐 dsh-smooth-stream / dsh-auto-collapse 的写法）。
+    const startSettings = {
+        maxSchedules: startMaxSchedules,
+        allowLongPrompts: false,
+        maxPromptChars: DEFAULT_MAX_PROMPT_CHARS,
+    };
+    let getSettings = () => startSettings;
+    ctx.inject(['settings'], (settingsCtx) => {
+        const scope = settingsCtx.settings.register(
+        // 断言而非 settingsNamespace()：0.1.1 要求 branded 类型，0.1.2 已删除该 helper。
+        'dsh-later', 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,
+                };
+            }
+            catch {
+                return startSettings;
+            }
+        };
+    });
+    // 每个 root agent 一个「用户提醒调度器」：负责确保命令/工具创建的提醒会武装 timer 并触发。
+    const runtimes = new Map();
+    /** 用户创建/删除成功 → 重驱该 agent 的用户调度器（也让 dsh-schedule 感知后续 idle）。 */
+    const notifyUserChange = (agent) => {
+        try {
+            runtimes.get(agent)?.requestDrive();
+        }
+        catch {
+            /* 调度失败不影响工具/命令的结果 */
+        }
+    };
+    /** 用户主动插话（GUI「插话发送」按钮）：路由到该 agent 的 runtime。 */
+    const notifyUserSteer = async (agent, id) => {
+        const runtime = runtimes.get(agent);
+        if (runtime === undefined) {
+            return { ok: false, code: 'no_runtime', message: '该会话尚未挂载用户调度器。' };
+        }
+        return runtime.steerById(id);
+    };
+    // 2. slash 命令（客户端变更通道），全局注册一次。
+    ctx.effect(() => registerUserScheduleCommands(ctx, getSettings, notifyUserChange, notifyUserSteer), 'later.commands()');
+    // 3. 每个 root agent：注册用户工具 + 用户调度器生命周期。
+    ctx.effect(() => {
+        const stopCreated = ctx.on('agent/created', ({ agent }) => {
+            if (stopping || runtimes.has(agent) || !ctx.agents.roots().includes(agent))
+                return;
+            const runtime = new UserScheduleRuntime(ctx, agent);
+            let cleanup = () => undefined;
+            try {
+                cleanup = agent.ctx.effect(() => {
+                    const disposeTools = registerUserScheduleTools(ctx, agent.ctx, agent, getSettings, notifyUserChange);
+                    const stopStatus = agent.ctx.on('agent/status', ({ status }) => {
+                        // 自愈：agent 转 idle 时重算（与 dsh-schedule 同构），覆盖被遗漏的重驱。
+                        if (status === 'idle')
+                            runtime.requestDrive();
+                    });
+                    runtime.requestDrive();
+                    return async () => {
+                        stopStatus();
+                        disposeTools();
+                        try {
+                            await runtime.dispose();
+                        }
+                        finally {
+                            if (runtimes.get(agent) === runtime)
+                                runtimes.delete(agent);
+                        }
+                    };
+                }, 'later.userTools()');
+                runtimes.set(agent, runtime);
+            }
+            catch (error) {
+                ctx.logger.warn(`later: agent "${agent.id}" 用户工具/调度器挂载失败: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+        return async () => {
+            stopping = true;
+            stopCreated();
+            const runtimesToDispose = [...runtimes.values()];
+            runtimes.clear();
+            await Promise.allSettled(runtimesToDispose.map((runtime) => runtime.dispose()));
+        };
+    }, 'later.userToolsLifecycle()');
+}
+export { name };

package/lib/owned-event-registration.js

@@ -0,0 +1,46 @@
+/**
+ * 宿主端专属：把本插件自有会话事件类型登记进宿主已知事件集合。
+ *
+ * ⚠️ 本模块只能被 host 端入口（index.ts）引用——它对
+ * `@deepseek-ai/dsh-session` 有**运行时值依赖**；client 端浏览器 bundle 若经
+ * 共享模块（如 domain.ts，被 `src/client/index.tsx` 引用）间接引入本模块，
+ * esbuild 会尝试把宿主包（依赖 node:path/node:module）打进浏览器产物而失败。
+ *
+ * @module dsh-later/owned-event-registration
+ */
+import { KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session';
+import { name, OWNED_EVENT } from './domain.js';
+/**
+ * 把 `OWNED_EVENT` 注册进宿主的已知会话事件类型集合（进程级、幂等）。
+ *
+ * 2026-09 起插件**不再写入**该事件（所有权改存 sidecar，见 ownership-store.ts），
+ * 本注册保留为**读兼容**：早期版本写入的历史日志（含当前 format 的日志）仍含
+ * 此事件类型，未注册时宿主读路径会以「unknown event type not marked ignorable」
+ * 拒读整份日志。
+ *
+ * 历史教训（为什么当初需要它 + 为什么现在不再写入）：当前构建的
+ * `Session.append(type, data)` 不暴露 envelope 的 `ignorable` 字段，插件无法
+ * 在写入侧自保；持久化层在特定时序下会「seq 已消费但行未落盘」，在日志里留下
+ * 永久 seq 缺口，任何读方（含 v0→v3 格式迁移）都会拒读整份历史（GUI 表现为
+ * 「历史加载失败」）。唯一根治 = 不往会话日志写宿主词汇表之外的事件。
+ *
+ * 安全性：该事件是纯信息性的所有权记录，`{version, operation, id}` 自描述；
+ * dsh-schedule 的 fold 天然跳过它，本插件投影按严格解码消费，把它当作
+ * 「已知必需」不会让任何读者误解释日志其余部分。
+ *
+ * TODO(上游)：待 dsh-session 暴露 append 侧的 `ignorable` 标记后，改为写入
+ * 时标记（更符合 envelope 契约），并移除本注册。
+ */
+export function registerOwnedSessionEventType() {
+    try {
+        // 本地 typings（dsh-session@0.1.0-rc.8）把它声明为 ReadonlySet，但运行时
+        // 实现是普通可变 Set（lib/index.js 中 `new Set([...])`，未冻结），
+        // 且核心文档明示插件注册面暂缓提供——此处收窄为可变引用完成登记。
+        KNOWN_SESSION_EVENT_TYPES.add(OWNED_EVENT);
+    }
+    catch (error) {
+        // 未来核心若冻结该集合，此处降级为告警：插件功能不受影响，
+        // 只是含本插件事件的旧日志仍会被无本插件上下文的读者拒绝。
+        console.warn(`[${name}] register owned session event type failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/lib/ownership-store.js

@@ -0,0 +1,214 @@
+/**
+ * 用户任务所有权的 sidecar 存储层。
+ *
+ * 为什么存在（2026-09 缺口事故的根治）：此前所有权经伴生会话事件
+ * `session-scheduler/user-schedule` 写进会话日志——但该类型不在宿主事件
+ * 词汇表内，持久化层在特定时序下会「seq 已消费但行未落盘」，在日志里留下
+ * 永久 seq 缺口，任何读方（含格式迁移）都会拒读整份历史。根治 = 所有权
+ * 完全移出会话日志，存到插件自己的 sidecar 文件：
+ *
+ *   <DSH_HOME>/plugin-state/later/<sessionId>.json
+ *
+ * 改名迁移：插件旧名 `session-scheduler` 的 sidecar 目录在首次启动时自动
+ * 迁移（整个目录 rename；rename 失败则逐文件复制）。不写「一次性迁移
+ * 标记」——重复执行天然幂等，且不引入新的丢失路径。
+ *
+ * - 原子写：临时文件 + rename；
+ * - 容错读：JSON 损坏时把坏文件改名保留（.corrupt-<ts>），按空表继续；
+ * - 进程内缓存：按 (mtimeMs, size) 校验，避免热路径反复读盘；
+ * - 路径解析：`DSH_LATER_STATE_DIR`（测试/便携）> 旧名
+ *   `DSH_LATER_STATE_DIR`（升级过渡）> `$DSH_HOME` > `~/.dsh`
+ *   （与 dsh-home-paths 的默认解析一致）。
+ *
+ * 注意：本模块只被 host 端引用；client bundle 不得引入（依赖 node:fs）。
+ * @module dsh-later/ownership-store
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync, existsSync, unlinkSync, readdirSync, copyFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 解析状态目录（优先级见模块注释）。 */
+function resolveStateDir() {
+    const override = process.env['DSH_LATER_STATE_DIR'] ?? process.env['DSH_LATER_STATE_DIR'];
+    if (override !== undefined && override.trim().length > 0)
+        return override;
+    const dshHomeEnv = process.env['DSH_HOME'];
+    const home = dshHomeEnv !== undefined && dshHomeEnv.trim().length > 0 ? dshHomeEnv : join(homedir(), '.dsh');
+    return join(home, 'plugin-state', 'later');
+}
+/**
+ * 旧名 sidecar 目录（仅 `$DSH_HOME` 路径下存在；env 覆盖视为测试/便携场景，
+ * 不做迁移以免污染调用方给定的目录语义）。
+ */
+function legacyStateDir() {
+    const override = process.env['DSH_LATER_STATE_DIR'] ?? process.env['DSH_LATER_STATE_DIR'];
+    if (override !== undefined && override.trim().length > 0)
+        return undefined;
+    const dshHomeEnv = process.env['DSH_HOME'];
+    const home = dshHomeEnv !== undefined && dshHomeEnv.trim().length > 0 ? dshHomeEnv : join(homedir(), '.dsh');
+    return join(home, 'plugin-state', 'session-scheduler');
+}
+/** 把旧名目录的 sidecar 文件搬到新目录（目录 rename 优先，失败逐文件复制；幂等）。 */
+function migrateLegacyState(newDir) {
+    const oldDir = legacyStateDir();
+    if (oldDir === undefined || !existsSync(oldDir))
+        return;
+    try {
+        renameSync(oldDir, newDir);
+        return;
+    }
+    catch {
+        /* 目标已存在等：退化为逐文件复制 */
+    }
+    try {
+        for (const entry of readdirSync(oldDir)) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const target = join(newDir, entry);
+            if (!existsSync(target))
+                copyFileSync(join(oldDir, entry), target);
+        }
+    }
+    catch (error) {
+        console.warn(`[dsh-later] 旧 sidecar 目录迁移失败（旧目录保留，可手动搬移）: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+let cachedDir;
+/** 状态目录（懒创建；目录创建失败时返回原路径，由调用方容错）。 */
+function stateDir() {
+    if (cachedDir === undefined) {
+        cachedDir = resolveStateDir();
+        try {
+            mkdirSync(cachedDir, { recursive: true });
+            migrateLegacyState(cachedDir);
+        }
+        catch {
+            /* 读写时再报错 */
+        }
+    }
+    return cachedDir;
+}
+function fileOf(sessionId) {
+    // sessionId 形如 session-<uuid>，字符安全；仍做一次兜底清洗。
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return join(stateDir(), `${safe}.json`);
+}
+function emptyFile() {
+    return { version: 1, entries: {} };
+}
+/** 进程内缓存：sessionId → (mtime, size, file)。写路径同步更新缓存。 */
+const cache = new Map();
+function readFresh(sessionId) {
+    const path = fileOf(sessionId);
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        cache.delete(sessionId);
+        return emptyFile();
+    }
+    const cached = cache.get(sessionId);
+    if (cached !== undefined && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        return cached.file;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.version !== 1 ||
+            typeof parsed.entries !== 'object' ||
+            parsed.entries === null) {
+            throw new Error('unexpected shape');
+        }
+        const file = parsed;
+        cache.set(sessionId, { mtimeMs: stat.mtimeMs, size: stat.size, file });
+        return file;
+    }
+    catch (error) {
+        // 损坏文件：改名保留现场，按空表继续（不静默删除，方便离线排查）。
+        try {
+            renameSync(path, `${path}.corrupt-${Date.now()}`);
+        }
+        catch {
+            /* 改名失败也按空表继续 */
+        }
+        cache.delete(sessionId);
+        try {
+            // eslint 由库外保证；这里用 console 而非宿主 logger（本层无 ctx 依赖）。
+            console.warn(`[dsh-later] 所有权 sidecar 解析失败，已按空表继续: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        catch {
+            /* 通知失败不影响语义 */
+        }
+        return emptyFile();
+    }
+}
+/** 读取某会话的全部所有权记录（缓存优先；返回副本语义，调用方不得变更）。 */
+export function allOwnership(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return {};
+    return readFresh(sessionId).entries;
+}
+/** 某 schedule id 是否由用户工具创建。 */
+export function hasOwnership(sessionId, id) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof id !== 'string')
+        return false;
+    return Object.prototype.hasOwnProperty.call(readFresh(sessionId).entries, id);
+}
+/** 某条所有权记录（缺失返回 undefined）。 */
+export function getOwnership(sessionId, id) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof id !== 'string')
+        return undefined;
+    return readFresh(sessionId).entries[id];
+}
+function writeThrough(sessionId, file) {
+    const path = fileOf(sessionId);
+    const dir = stateDir();
+    const tmp = join(dir, `.${safeName(sessionId)}.${process.pid}.${Date.now()}.tmp`);
+    const payload = `${JSON.stringify(file, null, 2)}\n`;
+    writeFileSync(tmp, payload, 'utf8');
+    try {
+        renameSync(tmp, path);
+    }
+    catch {
+        // 极端场景（跨设备等）：退化为直接写目标文件。
+        writeFileSync(path, payload, 'utf8');
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch {
+            /* 清理失败不影响语义 */
+        }
+    }
+    const stat = statSync(path);
+    cache.set(sessionId, { mtimeMs: stat.mtimeMs, size: stat.size, 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;
+    const file = readFresh(sessionId);
+    const entries = { ...file.entries };
+    entries[id] = { delivery, createdAt: Date.now() };
+    writeThrough(sessionId, { version: 1, entries });
+}
+/** 撤销一条所有权；幂等（不存在时无操作）。 */
+export function removeOwnership(sessionId, id) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0 || typeof id !== 'string' || id.length === 0)
+        return;
+    const file = readFresh(sessionId);
+    if (!Object.prototype.hasOwnProperty.call(file.entries, id))
+        return;
+    const entries = { ...file.entries };
+    delete entries[id];
+    writeThrough(sessionId, { version: 1, entries });
+}
+/** 测试辅助：清空进程内缓存（不删文件）。 */
+export function resetCacheForTests() {
+    cache.clear();
+    cachedDir = undefined;
+}

package/lib/presence.js

@@ -0,0 +1,71 @@
+/**
+ * 侧栏「定时状态」badge 的纯逻辑（宿主与客户端共享）。
+ *
+ * 数据源说明（路线 B 的关键事实）：本插件的 `userSchedules` 投影是
+ * client-visible 单元，宿主在 `session.list` 基线里为**每个**会话携带
+ * projections 块（live 会话走注册表现值，冷会话走持久化投影缓存，零日志
+ * 加载）；客户端把每行的块喂进 per-session 投影 store，并合入
+ * `SessionSummary.projectionValues`。因此客户端从 `sessions.list` 就能拿到
+ * 跨会话的任务概要，**无需宿主新增任何数据通道**。
+ *
+ * 本模块不触碰 DOM / React，全部函数可在 node --test 下运行。
+ * @module dsh-later/presence
+ */
+/** 紧急窗口：下次触发在该窗口内时，badge 从 scheduled 升级为 urgent。 */
+export const PRESENCE_URGENT_WINDOW_MS = 5 * 60_000;
+/**
+ * 归纳：取最早触发时刻 + 可解析数量。`every` 类任务在投影里携带推进后的
+ * `scheduledAt`（下次触发点），与一次性任务同构参与排序。
+ */
+export function summarizeSchedules(schedules) {
+    let nextAt;
+    let count = 0;
+    for (const item of schedules ?? []) {
+        const raw = item.scheduled_at ?? item.scheduledAt;
+        if (raw === undefined)
+            continue;
+        const epoch = Date.parse(raw);
+        if (!Number.isFinite(epoch))
+            continue;
+        count += 1;
+        if (nextAt === undefined || epoch < nextAt)
+            nextAt = epoch;
+    }
+    return nextAt === undefined ? { count: 0 } : { count, nextAt };
+}
+/** 由当前时刻判定 badge 状态。 */
+export function badgeStateFor(nextAt, now) {
+    if (nextAt === undefined)
+        return 'scheduled';
+    const diff = nextAt - now;
+    if (diff <= 0)
+        return 'overdue';
+    if (diff <= PRESENCE_URGENT_WINDOW_MS)
+        return 'urgent';
+    return 'scheduled';
+}
+function startOfDay(epoch) {
+    const d = new Date(epoch);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+/**
+ * 下次触发的相对时间标签。已到期（≤0）返回绝对时钟面（overdue 态文案由
+ * 调用方另行处理），≤1min 返回「即将发送」，其余按 分/小时/明天/日期 分档。
+ */
+export function relativeFireLabel(nextAt, now, labels, formatHhmm, formatDate) {
+    const diff = nextAt - now;
+    if (diff <= 0)
+        return labels.clock(formatHhmm(nextAt));
+    if (diff <= 60_000)
+        return labels.imminent;
+    if (diff < 3_600_000)
+        return labels.minutes(Math.max(1, Math.round(diff / 60_000)));
+    const dayDiff = Math.round((startOfDay(nextAt) - startOfDay(now)) / 86_400_000);
+    const time = formatHhmm(nextAt);
+    if (dayDiff <= 0)
+        return labels.hours(Math.max(1, Math.round(diff / 3_600_000)));
+    if (dayDiff === 1)
+        return labels.tomorrow(time);
+    return labels.date(formatDate(nextAt), time);
+}