dsh-session-rollover 0.0.0-stage → 1.2.0

package/src/client/toast-client.js

@@ -0,0 +1,342 @@
+// dsh-session-rollover · 浏览器半边（B6 一次性提示）。
+// 通道：server 半把「该提示什么」落盘，这里同源 GET /api-dsh-session-rollover/pending 取走渲染。
+// 不碰宿主 Toast 实现、不建 React hooks 面（D-36：bindInjectSources 会剥掉 hooks 字段），纯 DOM。
+// 形态/时长按 UI 定稿：底部居中、距输入框上沿 12px、max-width 420px、
+// 12.5px/18px、常规 5s、rollback-failed 8s、补显延迟 300ms、去重 (会话,原因)。
+(function () {
+    if (typeof window === 'undefined' || !window.__ModuleLoader__) return;
+    window.__ModuleLoader__.load({
+        // 必须与 dsh.client 条目的 id 逐字一致，使用公开包名。
+        id: 'dsh-session-rollover',
+        factory: function (require) {
+            var module = {exports: {}};
+            var NS = 'dsh-session-rollover';
+            var API = '/api-dsh-session-rollover/pending';
+            var POLL_MS = 1000;
+            var REPLAY_DELAY_MS = 300;
+            var FADE_MS = 120;
+            var MAX_SHOWN = 500;
+
+            function debug(e) {
+                try {
+                    if (window.console && console.debug) console.debug('[' + NS + '] toast skipped:', e);
+                } catch (_) { /* 静默 */
+                }
+            }
+
+            function durationFor(reason) {
+                return reason === 'rollback-failed' ? 8000 : 5000;
+            }
+
+            var CSS = [
+                '.dsr-toast-layer{position:fixed;left:50%;transform:translateX(-50%);bottom:96px;z-index:2147483000;display:flex;flex-direction:column;align-items:center;gap:8px;max-width:min(420px,calc(100vw - 32px));pointer-events:none;}',
+                '.dsr-toast{box-sizing:border-box;max-width:420px;padding:10px 14px;border-radius:8px;background:#FFFFFF;border:1px solid rgba(0,0,0,.08);box-shadow:0 6px 24px rgba(0,0,0,.12);color:#4B5563;font-size:12.5px;line-height:18px;text-align:left;white-space:pre-wrap;overflow-wrap:anywhere;opacity:0;transform:translateY(4px);transition:opacity 120ms ease,transform 120ms ease;}',
+                '.dsr-toast.is-in{opacity:1;transform:translateY(0);}',
+                '.dsr-toast.is-out{opacity:0;transform:translateY(4px);}',
+                'html[data-theme="dark"] .dsr-toast,html.dark .dsr-toast{background:#1F2430;color:#D1D5DB;border-color:rgba(255,255,255,.10);box-shadow:0 6px 24px rgba(0,0,0,.5);}',
+                '@media (prefers-color-scheme: dark){.dsr-toast{background:#1F2430;color:#D1D5DB;border-color:rgba(255,255,255,.10);box-shadow:0 6px 24px rgba(0,0,0,.5);}}',
+                '@media (prefers-reduced-motion: reduce){.dsr-toast{transition:opacity 120ms ease;transform:none;}.dsr-toast.is-in,.dsr-toast.is-out{transform:none;}}',
+            ].join('\n');
+
+            function timersOf(env) {
+                var win = env.win || window;
+                return env.timers || {
+                    setTimeout: function (fn, ms) {
+                        return win.setTimeout(fn, ms);
+                    },
+                    clearTimeout: function (id) {
+                        return win.clearTimeout(id);
+                    },
+                };
+            }
+
+            /** 轻量 toaster：单例容器、每条一个 role=status 节点、到时自动摘除。 */
+            function createToaster(env) {
+                env = env || {};
+                var doc = env.doc || document;
+                var win = env.win || window;
+                var timers = timersOf(env);
+                var layer = null;
+                var items = [];
+                var cssInjected = false;
+
+                function injectCss() {
+                    if (cssInjected || !doc.head) return;
+                    try {
+                        var style = doc.createElement('style');
+                        style.setAttribute('data-dsh-plugin', NS);
+                        style.textContent = CSS;
+                        doc.head.appendChild(style);
+                        cssInjected = true;
+                    } catch (e) {
+                        debug(e);
+                    }
+                }
+
+                function ensureLayer() {
+                    if (layer && layer.parentNode) return layer;
+                    layer = doc.createElement('div');
+                    layer.className = 'dsr-toast-layer';
+                    doc.body.appendChild(layer);
+                    return layer;
+                }
+
+                function place() {
+                    try {
+                        var ed = doc.querySelector('div[contenteditable="true"]');
+                        var rect = ed && ed.getBoundingClientRect ? ed.getBoundingClientRect() : null;
+                        if (rect && rect.top > 0) {
+                            layer.style.bottom = Math.max(12, Math.round(win.innerHeight - rect.top + 12)) + 'px';
+                        }
+                    } catch (e) {
+                        debug(e);
+                    }
+                }
+
+                function remove(rec) {
+                    for (var i = 0; i < rec.timers.length; i += 1) {
+                        try {
+                            timers.clearTimeout(rec.timers[i]);
+                        } catch (_) { /* 已触发 */
+                        }
+                    }
+                    try {
+                        if (rec.el.parentNode) rec.el.parentNode.removeChild(rec.el);
+                    } catch (_) { /* 已摘除 */
+                    }
+                    var at = items.indexOf(rec);
+                    if (at >= 0) items.splice(at, 1);
+                    if (layer && !layer.childNodes.length && layer.parentNode) {
+                        try {
+                            layer.parentNode.removeChild(layer);
+                        } catch (_) { /* 已摘除 */
+                        }
+                        layer = null;
+                    }
+                }
+
+                function show(notice) {
+                    injectCss();
+                    ensureLayer();
+                    place();
+                    var el = doc.createElement('div');
+                    el.className = 'dsr-toast';
+                    el.setAttribute('role', 'status');
+                    el.setAttribute('aria-live', 'polite');
+                    el.setAttribute('aria-atomic', 'true');
+                    el.textContent = String((notice && notice.text) || '');
+                    layer.appendChild(el);
+                    var rec = {el: el, timers: []};
+                    items.push(rec);
+                    var duration = durationFor(notice && notice.reason);
+                    rec.timers.push(timers.setTimeout(function () {
+                        try {
+                            el.className = 'dsr-toast is-in';
+                        } catch (_) { /* 已摘除 */
+                        }
+                    }, 0));
+                    rec.timers.push(timers.setTimeout(function () {
+                        try {
+                            el.className = 'dsr-toast is-out';
+                        } catch (_) { /* 已摘除 */
+                        }
+                    }, Math.max(0, duration - FADE_MS)));
+                    rec.timers.push(timers.setTimeout(function () {
+                        remove(rec);
+                    }, duration));
+                    return el;
+                }
+
+                function destroy() {
+                    items.slice().forEach(remove);
+                    if (layer && layer.parentNode) {
+                        try {
+                            layer.parentNode.removeChild(layer);
+                        } catch (_) { /* 已摘除 */
+                        }
+                    }
+                    layer = null;
+                }
+
+                return {
+                    show: show, destroy: destroy, count: function () {
+                        return items.length;
+                    }, _items: items
+                };
+            }
+
+            /** 当前会话：宿主 localStorage 的 dsh.sessions.current（{sessionId}），URL ?session= 兜底。 */
+            function currentSessionId(env) {
+                var win = (env && env.win) || window;
+                try {
+                    var raw = win.localStorage && win.localStorage.getItem('dsh.sessions.current');
+                    if (raw) {
+                        var parsed = JSON.parse(raw);
+                        if (parsed && typeof parsed === 'object') {
+                            if (parsed.sessionId) return String(parsed.sessionId);
+                            if (parsed.id) return String(parsed.id);
+                        } else if (typeof parsed === 'string' && parsed) return parsed;
+                    }
+                } catch (e) {
+                    debug(e);
+                }
+                try {
+                    var m = /(?:^|[?&])session=([^&]+)/.exec((win.location && win.location.search) || '');
+                    if (m) return decodeURIComponent(m[1]);
+                } catch (e) {
+                    debug(e);
+                }
+                return '';
+            }
+
+            /** 轮询取件。会话切换后先等 300ms（补显不与首屏抢帧）；页面隐藏不取，回来立即取。 */
+            function start(env, toaster) {
+                env = env || {};
+                var doc = env.doc || document;
+                var win = env.win || window;
+                var timers = timersOf(env);
+                var stopped = false;
+                var timer = null;
+                var session = '';
+                var shown = {};
+                var shownCount = 0;
+
+                function schedule(ms) {
+                    if (stopped) return;
+                    timer = timers.setTimeout(tick, ms);
+                }
+
+                function fetchPending(sid) {
+                    var doFetch = env.fetch || (win && win.fetch);
+                    if (typeof doFetch !== 'function') return;
+                    var p;
+                    try {
+                        p = doFetch(API + '?session=' + encodeURIComponent(sid), {
+                            cache: 'no-store',
+                            credentials: 'same-origin'
+                        });
+                    } catch (e) {
+                        debug(e);
+                        return;
+                    }
+                    Promise.resolve(p).then(function (res) {
+                        if (!res || !res.ok) return null;
+                        return res.json();
+                    }).then(function (body) {
+                        if (stopped || !body || !Array.isArray(body.notices)) return;
+                        body.notices.forEach(function (n) {
+                            if (!n || !n.id || shown[n.id]) return;
+                            shown[n.id] = 1;
+                            shownCount += 1;
+                            if (shownCount > MAX_SHOWN) {
+                                shown = {};
+                                shown[n.id] = 1;
+                                shownCount = 1;
+                            }
+                            try {
+                                toaster.show(n);
+                            } catch (e) {
+                                debug(e);
+                            }
+                        });
+                    }).catch(function (e) {
+                        debug(e);
+                    });
+                }
+
+                function tick() {
+                    timer = null;
+                    if (stopped) return;
+                    try {
+                        if (doc.visibilityState === 'hidden') {
+                            schedule(POLL_MS);
+                            return;
+                        }
+                        var sid = currentSessionId(env);
+                        if (!sid) {
+                            schedule(POLL_MS);
+                            return;
+                        }
+                        if (sid !== session) {
+                            session = sid;
+                            schedule(REPLAY_DELAY_MS);
+                            return;
+                        }
+                        fetchPending(sid);
+                    } catch (e) {
+                        debug(e);
+                    }
+                    schedule(POLL_MS);
+                }
+
+                function onVisibility() {
+                    if (!stopped && doc.visibilityState !== 'hidden') {
+                        try {
+                            tick();
+                        } catch (e) {
+                            debug(e);
+                        }
+                    }
+                }
+
+                function stop() {
+                    stopped = true;
+                    if (timer != null) {
+                        try {
+                            timers.clearTimeout(timer);
+                        } catch (_) { /* 已触发 */
+                        }
+                        timer = null;
+                    }
+                    try {
+                        doc.removeEventListener && doc.removeEventListener('visibilitychange', onVisibility);
+                    } catch (_) { /* 无监听面 */
+                    }
+                }
+
+                try {
+                    doc.addEventListener && doc.addEventListener('visibilitychange', onVisibility);
+                } catch (e) {
+                    debug(e);
+                }
+                tick();
+                return stop;
+            }
+
+            function apply(ctx) {
+                try {
+                    var env = {doc: document, win: window};
+                    var toaster = createToaster(env);
+                    var stop = start(env, toaster);
+                    var dispose = function () {
+                        try {
+                            stop();
+                        } catch (_) { /* 已停 */
+                        }
+                        try {
+                            toaster.destroy();
+                        } catch (_) { /* 已清 */
+                        }
+                    };
+                    if (ctx && typeof ctx.effect === 'function') ctx.effect(function () {
+                        return dispose;
+                    }, NS + ': toast');
+                    else if (typeof window.addEventListener === 'function') window.addEventListener('pagehide', dispose);
+                } catch (e) {
+                    debug(e);
+                }
+            }
+
+            module.exports = {
+                name: NS,
+                inject: [],
+                apply: apply,
+                __test: {
+                    durationFor: durationFor, createToaster: createToaster, currentSessionId: currentSessionId,
+                    start: start, API: API, REPLAY_DELAY_MS: REPLAY_DELAY_MS, POLL_MS: POLL_MS,
+                },
+            };
+            return module.exports;
+        },
+    });
+})();

package/src/cluster.mjs

@@ -0,0 +1,3 @@
+// 兼容旧索引入口；纯内存规则与磁盘存储分层维护。
+export {FIELDS, createClusterIndex, rebuildFromTitles} from './domain/cluster-index.mjs';
+export {resolveDataDir, attachFilePersistence} from './storage/index-store.mjs';

package/src/domain/cluster-index.mjs

@@ -0,0 +1,65 @@
+// 会话簇索引与标题对账：只操作内存，不访问宿主或磁盘。
+import {parseVolume} from './naming.mjs';
+
+export const FIELDS = ['cluster_id', 'parent_session_id', 'vol_no', 'name_suffix', 'rollover_state', 'readonly_by_rollover', 'summary_retry'];
+
+/** 纯内存索引；serialize 输出由 storage 层负责持久化。 */
+export function createClusterIndex(init = {}) {
+    /** sessions: { [sessionId]: {cluster_id, parent_session_id, vol_no, name_suffix, rollover_state, readonly_by_rollover, summary_retry} } */
+    const db = {sessions: {}, ...init};
+    return {
+        record({
+                   sessionId,
+                   clusterId,
+                   parentSessionId,
+                   volNo,
+                   nameSuffix,
+                   rolloverState = 'active',
+                   readonlyByRollover = false,
+                   summaryRetry = 0
+               }) {
+            if (!sessionId || !clusterId) throw new Error('cluster-index: sessionId & clusterId required');
+            const rec = {
+                cluster_id: clusterId, parent_session_id: parentSessionId ?? null, vol_no: volNo,
+                name_suffix: nameSuffix, rollover_state: rolloverState,
+                readonly_by_rollover: !!readonlyByRollover, summary_retry: summaryRetry,
+            };
+            for (const k of FIELDS) if (!(k in rec)) throw new Error('missing field ' + k);
+            db.sessions[sessionId] = rec; // 幂等：同 sessionId 覆盖
+            return rec;
+        },
+        get: (sessionId) => db.sessions[sessionId] ?? null,
+        cluster: (clusterId) => Object.entries(db.sessions).filter(([, r]) => r.cluster_id === clusterId).map(([id, r]) => ({sessionId: id, ...r})),
+        /** Q3 定稿：turn_counts 与簇索引同文件同原子提交（一个 JSON 一次 rename） */
+        setTurnCounts(map = {}) {
+            db.turn_counts = {...map};
+            return db.turn_counts;
+        },
+        turnCounts: () => db.turn_counts ?? {},
+        serialize: () => JSON.stringify(db, null, 2),
+    };
+}
+
+/** 对账重建（索引=缓存的兑现）：从标题 -N 后缀 + 交接消息 cluster: 标记重建七字段记录。
+ *  entries: [{sessionId,title}]；markers: {sessionId: {clusterId,parentSessionId}}（交接正文⑦项解析所得，可缺） */
+export function rebuildFromTitles(entries, markers = {}) {
+    const idx = createClusterIndex();
+    const groups = {}; // baseTitle -> {clusterId, members:[{sessionId,vol}]}
+    for (const {sessionId, title} of entries) {
+        const p = parseVolume(title); // 恒返回 {base, k}，无后缀 k=0
+        (groups[p.base] ??= {members: []}).members.push({sessionId, vol: p.k});
+    }
+    for (const [base, g] of Object.entries(groups)) {
+        const marked = g.members.map((m) => markers[m.sessionId]).find(Boolean);
+        const clusterId = marked?.clusterId ?? `recon:${base}`;
+        const parent = marked?.parentSessionId ?? null;
+        for (const m of g.members) {
+            idx.record({
+                sessionId: m.sessionId, clusterId, parentSessionId: parent,
+                volNo: m.vol, nameSuffix: m.vol ? `-${m.vol}` : '',
+                rolloverState: 'reconstructed',
+            });
+        }
+    }
+    return idx;
+}

package/src/domain/handoff.mjs

@@ -0,0 +1,67 @@
+// dsh-session-rollover · 交接七件套（接口契约 §3.2；v1.2 表 15 取数 + 八段排版，段名数组由调用方定，兼容 4/8 段裁定）
+export const MAX_BYTES = 16 * 1024; // 16KB 硬预算（ralph 同款上限）
+
+const encoder = new TextEncoder();
+
+/** 摘要重试状态机（B5）：生成失败→不分卷，记 summary-error，下轮重试 ≤2，超限只提醒不动作 */
+export function createSummaryRetry(maxRetries = 2) {
+    let attempts = 0;
+    return {
+        get attempts() {
+            return attempts;
+        },
+        reset() {
+            attempts = 0;
+        },
+        recordFailure() {
+            attempts++;
+            return attempts <= maxRetries ? {action: 'retry', attempts} : {action: 'remind-only', attempts};
+        },
+    };
+}
+
+/**
+ * 组七项交接。summarySegments: [[段名, 文本]]（四段/八段皆可，裁定后传对应表）。
+ * B4 无待办→「无结构化待办」；B3 active 多项逐项列；⑤ 抓不到约束→「未识别到显式约束」。
+ * @returns {{ok:true, payload:object, bytes:number} | {ok:false, reason:string, bytes?:number}}
+ */
+export function buildHandoff(input) {
+    const {
+        summarySegments, todos, activeIndexes = [], currentStepIndex = null,
+        openJobs = [], constraints = [], changedFiles = [],
+        cluster, fromSession, toSessionTitle,
+    } = input;
+    if (!Array.isArray(summarySegments) || summarySegments.length === 0) return {ok: false, reason: 'summary-missing'}; // B5 前置：调用方失败即不分卷
+    const todoItems = Array.isArray(todos) ? todos : null;
+    const payload = {
+        rollover: 'v1',
+        from_session_id: input.fromSessionId ?? null,
+        cluster: cluster ?? {degraded_link: `from:${input.fromSessionId ?? 'unknown'}`}, // ⑦ 缺失降级单向链接
+        summary: Object.fromEntries(summarySegments),
+        todos: todoItems ?? '无结构化待办', // ② 双份之二（JSON 全表）
+        current_step: currentStepIndex == null ? '尚未开始' : {index: currentStepIndex, active_items: activeIndexes}, // ③
+        open_jobs: openJobs.map((j) => ({
+            id: j.id,
+            command: j.command,
+            status: j.status,
+            recoverable: j.recoverable !== false
+        })), // ④ 不可恢复标「需重跑」
+        constraints: constraints.length ? constraints : ['未识别到显式约束'], // ⑤ 原文摘录不总结
+        changed_files: changedFiles.map((f) => ({path: f.path, note: f.note, deleted: !!f.deleted})), // ⑥
+        to_session_title: toSessionTitle ?? null,
+    };
+    const json = JSON.stringify(payload);
+    const bytes = encoder.encode(json).length;
+    if (bytes > MAX_BYTES) return {ok: false, reason: 'oversize', bytes};
+    // 四段正文不含路径、代码与机器快照；关键内容超限时拒绝分卷，不能静默截断。
+    const prose = summarySegments.map(([, text]) => String(text).replace(/```[\s\S]*?```/g, '').replace(/(?:[\w.@-]+[\\/])+[\w.@-]+/g, '')).join('');
+    if ([...prose].length > 1500) return {ok: false, reason: 'summary-too-long', bytes};
+    return {ok: true, payload, bytes};
+}
+
+/** 人读列表（②双份之一）：注入首条消息用的 Markdown 段 */
+export function todosMarkdown(todos) {
+    if (!Array.isArray(todos) || todos.length === 0) return '无结构化待办';
+    const mark = {completed: '[x]', in_progress: '[~]', pending: '[ ]'};
+    return todos.map((t, i) => `${i + 1}. ${mark[t.status]} ${t.content}`).join('\n');
+}

package/src/domain/inflight.mjs

@@ -0,0 +1,25 @@
+// 切点安全闸 S1：会话里仍在跑的工具调用 = 有 tool/call 但没有对应 tool/result。
+// 事件形状（session.v4 实测，2026-11-05）：
+//   tool/call   -> data.callId
+//   tool/result -> data.toolCallId（并镜像在 data.message.toolCallId / data.message.source.callId）
+// 只认 data.callId 会把已完成的调用全部算成 in-flight，第 10 轮触发时误判 unsafe-cut-point。
+
+function typeOf(e) {
+    return e?.type ?? e?.kind;
+}
+
+export function callIdOf(e) {
+    return e?.data?.callId ?? e?.data?.toolCallId
+        ?? e?.data?.message?.toolCallId ?? e?.data?.message?.source?.callId
+        ?? e?.data?.message?.callId;
+}
+
+export function openToolCalls(events = []) {
+    const open = new Map();
+    for (const e of events) {
+        const callId = callIdOf(e);
+        if (typeOf(e) === 'tool/call') open.set(callId, {callId, name: e.data?.name});
+        else if (typeOf(e) === 'tool/result' && callId) open.delete(callId);
+    }
+    return [...open.values()];
+}

package/src/domain/mode.mjs

@@ -0,0 +1,34 @@
+// dsh-session-rollover · 模式降级（AC-R3-8）：auto 检测到外部分段特征自动降 manual，配置可强制
+// 检测对象 = 会话内出现的「[Checkpoint N]」/「[Handoff · part N]」类外部压缩-换段标记（billion-context 代理层产物）
+export const SEGMENT_MARKER = /\[(?:Checkpoint \d+|Handoff(?: · part)? \d+)\]/;
+
+export function markersFound(messages) {
+    return messages.some((m) => m && !m.internal && m.type !== 'system/message' && typeof m.text === 'string' && SEGMENT_MARKER.test(m.text));
+}
+
+/** 压缩正在执行时不并发建卷；forceAuto 只豁免标记降级，不豁免安全切点。 */
+export function transitionInFlight(events) {
+    const open = new Map();
+    for (const e of events) {
+        const type = e.type ?? e.kind;
+        if (!/^(compaction|part)\/(start|end)$/.test(type)) continue;
+        const [kind, phase] = type.split('/');
+        const key = `${kind}:${e.data?.id ?? e.data?.turn ?? ''}`;
+        if (phase === 'start') open.set(key, true);
+        else open.delete(key);
+    }
+    return open.size > 0;
+}
+
+/**
+ * @param configured 'auto' | 'manual' | 'off'（rollover.mode）
+ * @param opts.forceAuto 配置强制 auto（不豁免外部分段告警展示，仅不降级）
+ * @returns {{mode:'auto'|'manual'|'off', downgraded:boolean}}
+ */
+export function effectiveRolloverMode(configured = 'auto', opts = {}) {
+    if (configured === 'off') return {mode: 'off', downgraded: false};
+    if (configured === 'manual') return {mode: 'manual', downgraded: false};
+    if (opts.forceAuto) return {mode: 'auto', downgraded: false};
+    if (opts.hasMarkers) return {mode: 'manual', downgraded: true}; // 自动降 manual
+    return {mode: 'auto', downgraded: false};
+}

package/src/domain/naming.mjs

@@ -0,0 +1,78 @@
+// dsh-session-rollover · -N 命名与簇规则（接口契约 §3.2 第3步；纯逻辑）
+// 规则：原标题+`-1`；已带 `-k` 则 k+1 不嵌套；重名序号递增到第一空位；同簇 -1..-9 封顶（B11）；用户手动改名不覆盖（B8）
+export const VOLUME_CAP = 9;
+const SUFFIX = /^(.+)-(\d{1})$/; // 仅个位数视为卷号；"Q3-26" 这类两位数尾巴不当卷号，防误咬
+
+export function parseVolume(title) {
+    const m = SUFFIX.exec(title ?? '');
+    if (!m) return {base: title, k: 0};
+    return {base: m[1], k: Number(m[2])};
+}
+
+/**
+ * @param currentTitle 现名
+ * @param existingTitles 同簇/全局已占用标题（Set 或数组）
+ * @param opts.userRenamed 本会话被用户手动改过名 → 不覆盖（B8）
+ * @returns {{ok:boolean, next?:string, k?:number, base?:string, reason?:string}}
+ */
+export function nextVolumeTitle(currentTitle, existingTitles = [], opts = {}) {
+    if (opts.userRenamed) return {ok: false, reason: 'user-renamed'};
+    const {base, k: cur} = parseVolume(currentTitle);
+    let k = cur === 0 ? 1 : cur + 1;
+    if (k > VOLUME_CAP) return {ok: false, reason: 'cluster-cap'};
+    const taken = new Set(existingTitles);
+    while (k <= VOLUME_CAP && taken.has(`${base}-${k}`)) k++; // 重名递增到第一空位并写日志（B7）
+    if (k > VOLUME_CAP) return {ok: false, reason: 'cluster-cap'}; // B11：停自动、提示手动
+    return {ok: true, base, k, next: `${base}-${k}`};
+}
+
+/**
+ * 分卷事务的「一对名字」：旧卷改 `base-c`（c=第一空位）、新卷接 `base-nextK`。
+ * 已是卷（k>0）的旧会话不再改名（S6：连跑三次 -1/-2 标题不得被改写），只给新卷找 k+1 的第一空位。
+ * @returns {{ok:true, base:string, oldK:number, oldTarget:string|null, newK:number, newTarget:string, bumped:boolean} | {ok:false, reason:string}}
+ */
+export function planVolumeTitles(currentTitle, existingTitles = [], opts = {}) {
+    if (opts.userRenamed) return {ok: false, reason: 'user-renamed'}; // B8：用户手动改名不覆盖
+    // 重名可使显示后缀超过 9；仅使用索引记录确认该后缀，避免把 Q3-26 等普通标题误拆。
+    const known = /^-\d+$/.test(opts.nameSuffix ?? '') && currentTitle.endsWith(opts.nameSuffix);
+    const {base, k: oldK} = known
+        ? {base: currentTitle.slice(0, -opts.nameSuffix.length), k: Number(opts.nameSuffix.slice(1))}
+        : parseVolume(currentTitle);
+    const taken = new Set(existingTitles);
+    const nameLimit = opts.volumeNo != null ? 100000 : VOLUME_CAP;
+    if (opts.volumeNo >= VOLUME_CAP) return {ok: false, reason: 'cluster-cap'};
+    taken.delete(currentTitle); // 自己的现名不算被占用
+    let oldTarget = null;
+    let bumped = false;
+    let cursor;
+    if (opts.preserveTitle) {
+        cursor = 1;
+    } else if (oldK === 0) {
+        let c = 1;
+        while (c <= nameLimit && taken.has(`${base}-${c}`)) {
+            c++;
+            bumped = true;
+        } // B7：重名递增到第一空位并记日志
+        if (c > nameLimit) return {ok: false, reason: 'cluster-cap'}; // B11
+        oldTarget = `${base}-${c}`;
+        taken.add(oldTarget);
+        cursor = c + 1;
+    } else {
+        cursor = oldK + 1;
+    }
+    while (cursor <= nameLimit && taken.has(`${base}-${cursor}`)) {
+        cursor++;
+        bumped = true;
+    }
+    if (cursor > nameLimit) return {ok: false, reason: 'cluster-cap'};
+    return {ok: true, base, oldK, oldTarget, newK: cursor, newTarget: `${base}-${cursor}`, bumped};
+}
+
+/** 簇内已有卷数（-1..k），供「-9 封顶」前置判断；手动换会话不计入簇上限由调用方走 force */
+export function clusterVolumeCount(currentTitle, existingTitles) {
+    const {base} = parseVolume(currentTitle);
+    const taken = new Set(existingTitles);
+    let n = 0;
+    for (let k = 1; k <= VOLUME_CAP; k++) if (taken.has(`${base}-${k}`)) n++;
+    return n;
+}