dsh-session-rollover 0.0.0-stage → 1.2.0

package/src/domain/summary.mjs

@@ -0,0 +1,68 @@
+// dsh-session-rollover · 八段摘要（无模型依赖的确定性版本；后续可换成模型生成的同结构输入，接口不变）
+// 裁定依据：AC-R3-2 要求八段全非空；把「有据可查」的段从日志/投影直接摘出来，比让模型自由发挥更可复核。
+import {eventType, isUserMessage} from './turns.mjs';
+
+const FILE_HINT = /(?:^|[\s"'`(（])([A-Za-z]:[\\/][^\s"'`]+|(?:\.{0,2}[\\/])?(?:[\w.@-]+[\\/])+[\w.@-]+\.[A-Za-z0-9]{1,8})/g;
+const CONSTRAINT_HINT = /(不许|不要|禁止|必须|不得|硬约束|一票否决|不能|只能)/;
+
+/** 一条消息事件的正文：宿主落盘形状是 data.content=[{type:'text',text}]，不是 data.text
+ *  application/handoff-message.mjs 复用此处，避免正文解析口径不一致。 */
+export function textOf(e) {
+    const d = e?.data ?? {};
+    const c = d.content ?? e?.content;
+    if (typeof c === 'string') return c;
+    if (Array.isArray(c)) return c.map((p) => (typeof p === 'string' ? p : p?.text ?? '')).filter(Boolean).join('\n');
+    return String(e?.text ?? d.text ?? '');
+}
+
+function textsOf(events, kind) {
+    return events.filter((e) => kind === 'user/message' ? isUserMessage(e) : eventType(e) === kind).map(textOf).filter((t) => t.trim());
+}
+
+/** 从 tool/call 的 arguments 里捞文件路径（⑥ 改动文件；只报「碰过」不判改没改） */
+export function changedFilesFrom(events) {
+    const seen = new Map();
+    for (const e of events) {
+        if (eventType(e) !== 'tool/call') continue;
+        const raw = typeof e.data?.arguments === 'string' ? e.data.arguments : JSON.stringify(e.data?.arguments ?? {});
+        for (const m of raw.matchAll(FILE_HINT)) {
+            const path = m[1].replace(/^[（(]|["'`]$/g, '');
+            if (path.length < 3 || path.startsWith('http')) continue;
+            seen.set(path, {path, note: e.data?.name ?? 'tool', deleted: false});
+        }
+    }
+    return [...seen.values()];
+}
+
+export function constraintsFrom(events) {
+    const out = [];
+    for (const t of textsOf(events, 'user/message')) {
+        for (const line of t.split(/\r?\n/)) {
+            if (CONSTRAINT_HINT.test(line)) out.push(line.trim());
+        }
+    }
+    return [...new Set(out)];
+}
+
+/**
+ * 八段：[任务目标, 已完成, 进行中, 下一步, 约束, 已知问题, 在跑任务, 改动文件]
+ * @returns {Array<[string,string]>} 段名与文本，八段皆非空
+ */
+export function buildSummarySegments({events = [], todos = [], jobs = [], currentStepIndex = null} = {}) {
+    const userMsgs = textsOf(events, 'user/message');
+    const goal = (userMsgs[0] ?? '').split(/\r?\n/)[0].slice(0, 300) || '未记录（旧卷无用户消息）';
+    const done = todos.filter((t) => t.status === 'completed').map((t) => t.content);
+    const doing = todos.filter((t) => t.status === 'in_progress').map((t) => t.content);
+    const pending = todos.filter((t) => t.status === 'pending').map((t) => t.content);
+    const failed = todos.filter((t) => t.status === 'failed').map((t) => t.content); // 数据态四态里的「中断」
+    const cur = currentStepIndex != null ? todos[currentStepIndex - 1] : null;
+    const files = changedFilesFrom(events);
+    const constraints = constraintsFrom(events);
+    const list = (a, empty) => (a.length ? a.map((x, i) => `${i + 1}. ${x}`).join('\n') : empty);
+    return [
+        ['上轮工作摘要', `${goal}\n已完成：\n${list(done, '尚无已完成项')}`],
+        ['当前进度与关键约束', `${currentStepIndex ? `第 ${currentStepIndex} 步进行中` : '尚未开始'}\n${list(doing, '无进行中项')}\n关键约束（原文）：\n${list(constraints, '本轮未提供')}\n中断项：\n${list(failed, '无')}`],
+        ['文件、代码与未竟事项', `文件：\n${list(files.map(f => f.path), '本轮未提供')}\n未竟后台任务：\n${list(jobs.map(j => `${j.id} ${j.command ?? ''} status=${j.status}${j.recoverable === false ? '（需重跑）' : ''}`), '无后台任务')}`],
+        ['下一步与待办快照', list(pending, '本轮未提供')],
+    ];
+}

package/src/domain/todos.mjs

@@ -0,0 +1,23 @@
+// 旧卷待办快照：取日志里最后一次 todo/write。
+// 不能读实时投影：宿主 todos 投影在 turn/start 归零（tool-todo: apply 遇 turn/start 返回 null），
+// 而分卷判定恰好发生在第 N+1 轮 pre-step（turn/start 之后），此刻 stateOf 必为 null。
+// 判定/交接要的是「上一轮结束时的清单」，日志最后一条 todo/write 才是它。
+
+function typeOf(e) {
+    return e?.type ?? e?.kind;
+}
+
+export function lastTodos(events = []) {
+    let last = null;
+    for (const e of events) {
+        if (typeOf(e) !== 'todo/write') continue;
+        const todos = e?.data?.todos;
+        if (Array.isArray(todos)) last = todos;
+    }
+    return last ?? [];
+}
+
+export function activeIndex(todos = []) {
+    const i = todos.findIndex((t) => t?.status === 'in_progress');
+    return i < 0 ? null : i + 1;
+}

package/src/domain/turns.mjs

@@ -0,0 +1,43 @@
+// dsh-session-rollover · 轮次计数与触发（接口契约 §3.1；纯逻辑）
+// 一条用户消息=一轮；内部 turn/step 不计。安全切点由 hasOpenTurn 独立判断。
+// 事件判别字段：session.v4 落盘事件用 `type`，内存/夹具事件历史上用 `kind` —— 两种都认（实机踩坑：只认 kind 会数成 0）
+export const DEFAULT_THRESHOLD = 10;
+export const eventType = (e) => e?.type ?? e?.kind;
+
+/** 宿主也用 user/message 记录时间、技能目录等上下文；它们不是用户发言。 */
+export function isUserMessage(e) {
+    const source = e?.data?.source ?? e?.source;
+    return eventType(e) === 'user/message' && (!source?.kind || source.kind === 'user') &&
+        !e?.data?.rollover && !String(e?.data?.content?.[0]?.text ?? e?.text ?? '').startsWith('【分卷交接】');
+}
+
+/** 从完整日志重建用户轮次；插件生成的交接消息不计入。 */
+export function countTurns(events) {
+    // B1：内部 turn/start、turn/end 的数量不代表用户发言轮数。
+    // 交接首条消息由插件生成，不占用新卷的用户轮次。
+    return events.filter(isUserMessage).length;
+}
+
+export function hasOpenTurn(events) {
+    return events.findLastIndex(e => eventType(e) === 'turn/start') >
+        events.findLastIndex(e => eventType(e) === 'turn/end');
+}
+
+/**
+ * 触发判定（agent/pre-step 旁挂调用）。
+ * @param turnCount 全 log 轮数
+ * @param opts { threshold, hasInFlightTool, isSubagent, clusterCapReached, rolloverPending }
+ * 后台 job 在跑不阻断（B2：job 句柄写入交接，不开新会话拆 job）
+ */
+export function shouldTriggerRollover(turnCount, opts = {}) {
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    if (opts.isSubagent) return {trigger: false, reason: 'subagent-never'}; // B10
+    if (turnCount < threshold) return {trigger: false, reason: 'below-threshold'};
+    if (opts.hasInFlightTool) return {trigger: false, reason: 'unsafe-cut-point'}; // 安全切分点
+    if (opts.clusterCapReached) return {trigger: false, reason: 'cluster-cap'}; // B11 停自动
+    if (opts.rolloverPending) return {trigger: false, reason: 'pending'};
+    return {trigger: true, reason: 'threshold-reached'};
+}
+
+/** 从日志重建计数（重启一致性，AC-R3-8）：纯函数天然满足，给出显式入口供接线层用 */
+export const rebuildTurnCount = countTurns;

package/src/handoff.mjs

@@ -0,0 +1,2 @@
+// 兼容旧导入路径；新代码请直接使用 src/domain/handoff.mjs。
+export * from './domain/handoff.mjs';

package/src/inflight.mjs

@@ -0,0 +1,2 @@
+// 兼容旧导入路径；新代码请直接使用 src/domain/inflight.mjs。
+export * from './domain/inflight.mjs';

package/src/mode.mjs

@@ -0,0 +1,2 @@
+// 兼容旧导入路径；新代码请直接使用 src/domain/mode.mjs。
+export * from './domain/mode.mjs';

package/src/naming.mjs

@@ -0,0 +1,2 @@
+// 兼容旧导入路径；新代码请直接使用 src/domain/naming.mjs。
+export * from './domain/naming.mjs';

package/src/notices.mjs

@@ -0,0 +1,2 @@
+// 兼容旧导入路径；新代码请直接使用 src/storage/notices.mjs。
+export * from './storage/notices.mjs';

package/src/server/compatibility.mjs

@@ -0,0 +1,84 @@
+// 只探测已声明的宿主服务；不根据版本号猜测方法签名，也不在探测时写会话。
+const REQUIRED = {
+    sessions: ['get', 'list'],
+    sessionTitle: ['get', 'rename'],
+    sessionController: ['create', 'prompt', 'selectModel'],
+    sessionProjections: ['stateOf'],
+    workspaceRegistry: ['list'],
+};
+
+export const INCOMPATIBLE_MESSAGE = '当前 DSH 的会话接口与插件不兼容，已暂停分卷。原会话与归档数据保留，请更新插件后重试。';
+
+/** 方法存在只代表能力探测通过；事件语义、权限和界面仍需逐版本验收。 */
+export function inspectHost(ctx, session) {
+    const missing = [];
+    for (const [service, methods] of Object.entries(REQUIRED)) {
+        for (const method of methods) {
+            try { if (typeof ctx[service]?.[method] !== 'function') missing.push(`${service}.${method}`); }
+            catch { missing.push(`${service}.${method}`); }
+        }
+    }
+    if (session && typeof session.snapshotEvents !== 'function') missing.push('session.snapshotEvents');
+    return {contractVersion: 1, compatible: missing.length === 0, missing,
+        message: missing.length ? INCOMPATIBLE_MESSAGE : null};
+}
+
+/** 在创建新卷之前检查同步读取面的形状；遇到变化时停止，不用空数据继续交接。 */
+export function preflightHost(ctx, session, services = ctx) {
+    const report = inspectHost(ctx, session);
+    if (!report.compatible) return report;
+    try {
+        if (!Array.isArray(session.snapshotEvents())) throw new Error('session.snapshotEvents:array-required');
+        const sessions = ctx.sessions.list();
+        if (!Array.isArray(sessions) || sessions.some(s => !s || typeof s.id !== 'string' || !s.id)) {
+            throw new Error('sessions.list:session-id-required');
+        }
+        const workspaces = ctx.workspaceRegistry.list();
+        if (!Array.isArray(workspaces) || workspaces.some(w => !w || typeof w.id !== 'string' || !w.id ||
+            !Array.isArray(w.sessionIds) || w.sessionIds.some(id => typeof id !== 'string'))) {
+            throw new Error('workspaceRegistry.list:sessionIds-required');
+        }
+        const title = ctx.sessionTitle.get(session);
+        if (title != null && (typeof title !== 'object' || typeof title.title !== 'string')) {
+            throw new Error('sessionTitle.get:title-required');
+        }
+        const cwd = readWorkingDirectory(ctx, services, session);
+        if (cwd != null && typeof cwd !== 'string') throw new Error('workingDirectory:string-required');
+        readModelSelection(ctx, services, session);
+    } catch (error) {
+        return {...report, compatible: false, missing: [String(error?.message ?? error)], message: INCOMPATIBLE_MESSAGE};
+    }
+    return report;
+}
+
+/** 新版优先使用领域服务；旧宿主回退到已验证的公开投影入口。 */
+export function readWorkingDirectory(ctx, services, session) {
+    return typeof services.workingDirectory?.get === 'function'
+        ? services.workingDirectory.get(session)
+        : ctx.sessionProjections.stateOf(session, 'workingDirectory');
+}
+
+function validateModel(selection) {
+    if (selection != null && (typeof selection.provider !== 'string' || typeof selection.model !== 'string' ||
+        !selection.provider || !selection.model ||
+        (selection.reasoningEffort != null && typeof selection.reasoningEffort !== 'string'))) {
+        throw new Error('modelSelection:provider-model-required');
+    }
+    return selection;
+}
+
+export function readModelSelection(ctx, services, session) {
+    const agent = services.agents?.get?.(session.id);
+    // 旧宿主也可能提供 agents，但尚无 model.current；此时仍走经过结构校验的投影入口。
+    if (typeof agent?.model?.current === 'function') {
+        const current = validateModel(agent.model.current());
+        if (current != null) return current;
+    }
+    const selection = ctx.sessionProjections.stateOf(session, 'modelSelection');
+    if (selection == null) return undefined;
+    if (typeof selection !== 'object' || Array.isArray(selection) ||
+        !('pending' in selection || 'lastUsed' in selection)) throw new Error('modelSelection:projection-shape-required');
+    validateModel(selection.pending);
+    validateModel(selection.lastUsed);
+    return selection.pending ?? selection.lastUsed;
+}

package/src/server/host-adapter.mjs

@@ -0,0 +1,146 @@
+// 将宿主公开服务转换为分卷事务接口；事件计数与正文等纯解析规则委托给 domain。
+import {eventType} from '../domain/turns.mjs';
+import {openToolCalls} from '../domain/inflight.mjs';
+import {lastTodos} from '../domain/todos.mjs';
+import {preflightHost, readWorkingDirectory, readModelSelection} from './compatibility.mjs';
+
+/**
+ * 为一个来源会话创建适配器。新卷继承其工作区和模型选择。
+ * @param {object} deps
+ * @param {object} deps.ctx 宿主公开服务容器
+ * @param {object} deps.session 来源会话（id、snapshotEvents、header）
+ * @param {object} deps.state 插件旁路状态存储
+ * @param {(id: string) => object|null} deps.sessionOf 查询当前存活会话
+ * @param {(event: string, data?: object) => void} deps.log 诊断日志回调
+ * @returns {object} performRollover 所需的异步宿主接口
+ */
+export function createHostAdapter({ctx, session, state, sessionOf, log, services = ctx}) {
+    const compatibility = preflightHost(ctx, session, services);
+    if (!compatibility.compatible) throw new Error(`host-incompatible: ${compatibility.missing.join(', ')}`);
+    const id = session.id;
+    const sourceEvents = session.snapshotEvents().slice();
+    const registry = services.jobs;
+    const registryJobs = registry?.list ? registry.list(id) : [];
+    const eventsOf = (sid) => {
+        const s = sid === id ? session : sessionOf(sid);
+        try {
+            return sid === id ? sourceEvents : s?.snapshotEvents?.() ?? [];
+        } catch {
+            return [];
+        }
+    };
+    return {
+        listEvents: async (sid) => eventsOf(sid),
+        getTitle: async (sid) => {
+            const s = sid === id ? session : sessionOf(sid);
+            try {
+                return ctx.sessionTitle.get(s)?.title ?? '';
+            } catch {
+                return '';
+            }
+        },
+        isUserRenamed: async (sid) => {
+            const target = sid === id ? session : sessionOf(sid);
+            const title = ctx.sessionTitle.get(target);
+            const inherited = state.handoffGet(sid);
+            return (title?.source?.kind === 'user' || title?.source === 'user') &&
+                title.title !== inherited?.to_session_title;
+        },
+        listTitles: async () => {
+            const out = [];
+            for (const s of ctx.sessions.list()) {
+                try {
+                    out.push({sessionId: s.id, title: ctx.sessionTitle.get(s)?.title ?? ''});
+                } catch { /* 单条坏不影响整表 */
+                }
+            }
+            return out;
+        },
+        getTodos: async (sid) => {
+            const events = eventsOf(sid);
+            // 出现过实时待办事件即以日志为准；只有完全没有该事件时才继承交接快照。
+            // 空数组是用户清空清单，不能用继承值把它重新填回去。
+            if (events.some(e => eventType(e) === 'todo/write')) return lastTodos(events);
+            const inherited = state.handoffGet(sid)?.todos;
+            return Array.isArray(inherited) ? inherited : [];
+        },
+        inFlightTools: async (sid) => openToolCalls(eventsOf(sid)),
+        isSubagent: async (sid) => {
+            const s = sid === id ? session : sessionOf(sid);
+            try {
+                return s?.header?.parentSession !== undefined && s?.header?.parentSession !== null;
+            } catch {
+                return false;
+            }
+        },
+        listRunningJobs: async (sid) => {
+            const open = new Map();
+            for (const e of eventsOf(sid)) {
+                const runId = e?.data?.runId ?? e?.data?.id ?? e?.seq;
+                if (eventType(e) === 'tool-workflow/run-start') open.set(runId, {
+                    id: String(runId),
+                    command: e.data?.command ?? e.data?.name ?? 'workflow',
+                    status: 'running',
+                    recoverable: true
+                });
+                else if (eventType(e) === 'tool-workflow/run-end') open.delete(e.data?.runId ?? e.data?.id ?? e.seq);
+                else if (eventType(e) === 'job/registered' && e.data?.jobId) open.set(String(e.data.jobId), {
+                    id: String(e.data.jobId), command: e.data.label ?? e.data.kind ?? '', status: 'running', recoverable: true,
+                });
+                else if (eventType(e) === 'job/settled') open.delete(String(e.data?.jobId));
+            }
+            // live registry 能识别重启后已结算但日志尚未补齐的任务。
+            if (registry?.list) {
+                for (const job of await registryJobs) {
+                    if (job.owner && job.owner !== sid) continue;
+                    if (['running', 'stopping', 'pending', 'starting'].includes(job.status)) open.set(String(job.id), {
+                        id: String(job.id), command: job.label ?? job.command ?? job.kind ?? '',
+                        status: job.status, recoverable: job.recoverable !== false,
+                    });
+                    else open.delete(String(job.id));
+                }
+            }
+            return [...open.values()]; // 同刻全量；切点后新起的 run 不在快照里
+        },
+        createSession: async () => {
+            // 优先归入来源工作区；来源不属于工作区时才按其 cwd 建会话。
+            const cwd = readWorkingDirectory(ctx, services, session);
+            const workspace = ctx.workspaceRegistry.list().find(w => w.sessionIds.includes(session.id));
+            const created = await ctx.sessionController.create(workspace ? {workspaceId: workspace.id} : typeof cwd === 'string' ? {cwd} : {});
+            if (!/^[\w-]{1,160}$/.test(created?.sessionId ?? '')) throw new Error('host-incompatible: create.sessionId');
+            return created;
+        },
+        injectFirstMessage: async (sessionId, text) => {
+            // 宿主 create() 建的是空壳会话，没有 model selection，会落到默认 provider
+            // （实测 "deepseek-official" 无 key → MISSING_CREDENTIAL）。先继承旧卷的模型，再注入。
+            try {
+                const pick = readModelSelection(ctx, services, session);
+                if (pick?.provider && pick?.model) {
+                    await ctx.sessionController.selectModel({
+                        sessionId, provider: pick.provider, model: pick.model,
+                        ...(pick.reasoningEffort ? {reasoningEffort: pick.reasoningEffort} : {}),
+                    });
+                }
+            } catch (e) {
+                log('model-inherit-failed', {sessionId, error: String(e?.message ?? e)});
+                const defaults = services.agentDefaultModel;
+                const fallback = await defaults?.currentSelection?.();
+                if (!fallback?.provider || !fallback?.model) throw e;
+                await ctx.sessionController.selectModel({sessionId, ...fallback});
+                state.modelFallback?.(sessionId);
+                log('model-fallback', {sessionId});
+            }
+            // 宿主 prompt(request, signal)：signal.throwIfAborted() 是第一行，必须给 AbortSignal
+            await ctx.sessionController.prompt({
+                requestId: `rollover-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                sessionId, mode: 'queue', content: [{type: 'text', text}],
+            }, new AbortController().signal);
+        },
+        renameSession: async (sessionId, title) => {
+            const target = sessionOf(sessionId);
+            if (!target) throw new Error(`session "${sessionId}" is not live in this store`);
+            ctx.sessionTitle.rename(target, title); // ds-bot roster 用的同一个调用
+        },
+        log: (event, data) => log(event, data),
+    };
+}

package/src/server/notice-route.mjs

@@ -0,0 +1,104 @@
+// 一次性提示的同源 HTTP 入口；认证由宿主 webServer 统一处理。
+/** client 半取件口：同源 GET，宿主 webServer 统一过登录校验（dsh-pick 同款）。
+ *  取走即删＝「未发显」标记的投递；渲染由 client 半负责，server 不碰 DOM。 */
+export function attachNoticeRoutes(ctx, {handlePending, log, plugin}) {
+    if (typeof ctx.inject !== 'function') return;
+    try {
+        ctx.inject(['webServer'], (scope) => {
+            const ws = scope.webServer ?? scope.get?.('webServer');
+            if (!ws || typeof ws.register !== 'function') {
+                log('route-unavailable');
+                return undefined;
+            }
+            const dispose = ws.register({
+                kind: 'exact',
+                path: '/api-dsh-session-rollover/pending',
+                handler: (req, res) => handlePending(req, res),
+            });
+            const control = plugin && ws.register({kind: 'exact', path: '/api-dsh-session-rollover/session',
+                handler: (req, res) => handleSessionRequest(plugin, req, res)});
+            log('route-registered', {path: '/api-dsh-session-rollover/pending'});
+            scope.effect?.(() => () => {
+                try {
+                    dispose?.();
+                    control?.();
+                } catch { /* 卸载容错 */
+                }
+            }, 'rollover: pending route');
+            return undefined;
+        });
+    } catch (e) {
+        log('route-failed', {error: String(e?.message ?? e)});
+    }
+}
+
+/** 与 R2 桥接相同的 owner 认证和同源约束；不接收浏览器传来的快照正文。 */
+export async function handleSessionRequest(plugin, req, res) {
+    const send = (code, value) => { res.writeHead(code, {'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store'}); res.end(JSON.stringify(value)); };
+    try {
+        const admission = plugin.ctx.connection?.admit(req);
+        if (!admission || 'rejection' in admission) return send(admission?.rejection ?? 401, {error: 'unauthorized'});
+        if (admission.peer.principal?.kind !== 'owner') return send(403, {error: 'owner-required'});
+        if (req.method === 'GET') {
+            const id = new URL(req.url, 'http://localhost').searchParams.get('session');
+            if (!/^[\w-]{1,160}$/.test(id ?? '')) return send(400, {error: 'invalid-session'});
+            if (!plugin.sessionOf(id)) return send(404, {error: 'session-unavailable'});
+            return send(200, {...plugin.handoffInfo(id), completedSessionId: plugin.lastCompleted?.get(id) ?? null});
+        }
+        if (req.method !== 'POST') return send(405, {error: 'method-not-allowed'});
+        if (!/^application\/json(?:;|$)/i.test(req.headers?.['content-type'] ?? '')) return send(415, {error: 'json-required'});
+        if (req.headers.origin && new URL(req.headers.origin).host !== req.headers.host) return send(403, {error: 'origin-mismatch'});
+        let body = '';
+        for await (const chunk of req) { body += chunk; if (Buffer.byteLength(body) > 4096) return send(413, {error: 'too-large'}); }
+        let input;
+        try { input = JSON.parse(body); } catch { return send(400, {error: 'invalid-json'}); }
+        if (!/^[\w-]{1,160}$/.test(input?.sessionId ?? '')) return send(400, {error: 'invalid-session'});
+        if (!plugin.sessionOf(input.sessionId)) return send(404, {error: 'session-unavailable'});
+        if (['rollover', 'new'].includes(input.action)) {
+            const compatibility = plugin.handoffInfo(input.sessionId).compatibility;
+            if (compatibility && !compatibility.compatible) {
+                return send(503, {error: 'host-incompatible', message: compatibility.message, compatibility});
+            }
+        }
+        if (input.action === 'readonly' && typeof input.readonly === 'boolean') {
+            if (!plugin.handoffInfo(input.sessionId).sealed) return send(409, {error: 'session-not-archived'});
+            return send(200, plugin.setReadonly(input.sessionId, input.readonly));
+        }
+        if (input.action === 'rollover') {
+            const result = await plugin.rolloverNow(input.sessionId);
+            return send(result.status === 'rolled-over' ? 200 : 409, result);
+        }
+        if (input.action === 'new') {
+            const result = await plugin.hostFor(plugin.sessionOf(input.sessionId)).createSession();
+            return send(200, {...result, status: 'created', independent: true});
+        }
+        return send(400, {error: 'invalid-action'});
+    } catch (e) { return send(500, {error: 'operation-failed', message: String(e.message)}); }
+}
+
+/** 按会话取走提示，成功取件后即从存储队列删除；此接口不确认浏览器已完成渲染。 */
+export function handlePendingNotices({notices: store, log}, req, res) {
+    const send = (code, body) => {
+        try {
+            res.writeHead(code, {'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store'});
+            res.end(JSON.stringify(body));
+        } catch { /* 连接已断不阻断 */
+        }
+    };
+    try {
+        if (req.method !== 'GET') return send(405, {error: 'method-not-allowed'});
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const sessionId = url.searchParams.get('session');
+        if (!sessionId) return send(400, {error: 'missing-session'});
+        const notices = store.takePending(sessionId);
+        if (notices.length) log('notice-delivered', {
+            sessionId,
+            count: notices.length,
+            reasons: notices.map((n) => n.reason)
+        });
+        return send(200, {version: 1, notices});
+    } catch (e) {
+        log('notice-deliver-failed', {error: String(e?.message ?? e)});
+        return send(500, {error: 'internal'});
+    }
+}