dsh-config-manager 0.1.71 → 0.1.73

package/lib/core/rollback.js

@@ -7,7 +7,7 @@
  *    如实标记 failed + manualHint（人工补录）；
  *  - settings 回滚仍走 expectedRevision 乐观锁，避免覆盖导入后用户的新修改。
  */
-import { resolveFileTarget } from './backup.js';
+import { fsForSection, resolveFileTarget } from './backup.js';
 import { isPatchLayerRel, USER_PATCH_FILE } from './patch-layers.js';
 import { msgOf } from './messages.js';
 /** 逆序补偿单条快照条目；返回 null=成功，否则为失败原因 */
@@ -75,15 +75,17 @@ async function compensateOne(entry, ctx, store) {
         }
         case 'file': {
             try {
+                // 门面按分区选（pluginData / pluginAssets 在系统 home 根；见 backup.ts 的 fsForSection）
+                const fsFacade = fsForSection(ctx, entry.adapter);
                 const abs = resolveFileTarget(ctx, entry.adapter, entry.ref);
                 if (entry.existed && entry.copiedTo && store) {
                     const data = await store.readBlob(entry.snapshotId ?? '', entry.copiedTo);
-                    await ctx.fs.writeFile(abs, data);
+                    await fsFacade.writeFile(abs, data);
                 }
                 else if (!entry.existed) {
                     // 原文件不存在 → 删除导入写入的文件
-                    if (await ctx.fs.exists(abs))
-                        await ctx.fs.remove(abs);
+                    if (await fsFacade.exists(abs))
+                        await fsFacade.remove(abs);
                 }
                 return null;
             }

package/lib/core/run-registry.js

@@ -20,6 +20,7 @@
  */
 import { randomBytes } from 'node:crypto';
 import { zhMsg } from './messages.js';
+import { engineMsg } from './messages-core.js';
 /** 单个 run 执行日志的行数上限（防无限增长；截断时保留最新行）。 */
 export const MAX_RUN_LOG_LINES = 500;
 /** 进行中同 kind 已有 run 时注册被拒（宿主路由 → 409）。 */
@@ -30,15 +31,15 @@ export class RunConflictError extends Error {
         super(kind === 'export'
             ? msg('run.conflict.export', { runId })
             : kind === 'autosync'
-                ? '自动同步已在进行中'
+                ? engineMsg('core.run.autosyncBusy')
                 : kind === 'sync-apply'
-                    ? '一键同步已在进行中'
+                    ? engineMsg('core.run.syncApplyBusy')
                     : kind === 'backup-schedule'
-                        ? '定时备份已在进行中'
+                        ? engineMsg('core.run.backupScheduleBusy')
                         : kind === 'restore'
-                            ? '快照恢复已在进行中（请等待当前恢复完成）'
+                            ? engineMsg('core.run.restoreBusy')
                             : kind === 'recovery'
-                                ? '恢复/回滚已在进行中（请等待当前恢复完成）'
+                                ? engineMsg('core.run.recoveryBusy')
                                 : msg('run.conflict.import', { runId }));
         this.name = 'RunConflictError';
         this.runId = runId;

package/lib/core/session-health.d.ts

@@ -141,12 +141,27 @@ export interface SessionHealthContext {
 export interface SessionHealthRow {
     unitId: string;
     sessionId: string;
+    /**
+     * 界面标题（**宿主侧补**，不是分类判定的一部分）。
+     *
+     * 来源 = DSH 会话缓存 `storages/session_projcache.json` 的 `rows.title.val`，由宿主在扫描后用
+     * `core/session-meta.ts` 的 `applySessionTitles` 统一补上（本模块零 IO，自己不读盘）。
+     * 读不到 = 缺省 → 界面回落显示会话目录名（绝不编造标题）。
+     */
+    title?: string;
     projectKey: string;
     severity: SessionHealthSeverity;
     issues: SessionHealthIssue[];
     version?: number;
     cwd?: string;
     origin?: string;
+    /**
+     * 空白会话（从未提问过；宿主侧从会话投影补的**事实**）。
+     *
+     * 用途：这类会话在 DSH 自己那里也没有标题（显示本地化的「新会话」）—— 界面据此显示同样的
+     * 占位名，而不是把 `session-<uuid>` 当标题。只下发事实，文案由界面按当前语言解析。
+     */
+    blank?: boolean;
     sizeBytes?: number;
     mtimeMs?: number;
 }

package/lib/core/session-meta.d.ts

@@ -37,7 +37,7 @@ export interface SessionMetaIndex {
 }
 /** 空索引（读不到任何缓存时的安全返回值）。 */
 export declare function emptySessionMeta(): SessionMetaIndex;
-/** 清空索引缓存（测试用；宿主在收到「DSH 存储已重载」信号时也可调用）。 */
+/** 清空索引与逐会话投影缓存（测试用；宿主在收到「DSH 存储已重载」信号时也可调用）。 */
 export declare function clearSessionMetaCache(): void;
 /**
  * 读取会话标题与工作区注册表（带 mtime 失效的进程内缓存，见 `metaCache`）。
@@ -46,6 +46,27 @@ export declare function clearSessionMetaCache(): void;
  * 返回的索引视为**只读**（调用方 `applySessionMeta*` 不改它）——缓存会把同一份 Map 再发出去。
  */
 export declare function readSessionMeta(ctx: HostContext): Promise<SessionMetaIndex>;
+/**
+ * 会话单元 id（`sessions:<项目键>/<目录名>`）或裸目录名 → **归一化裸键**（`sessionIdKey`）。
+ *
+ * 为什么要有：调用方手上是单元 id / 计划项 id（末段才是目录名），而索引与投影文件都按**裸键**存。
+ */
+export declare function sessionBareKeyOf(ref: string): string;
+/**
+ * 「界面标题」的**全量**解析：聚合缓存优先，缺的按需读**逐会话投影文件**。
+ *
+ * 用户要求（2026-10-12）：「历史对话的文本**始终**用对话标题，而不是只取缓存里的标题」。
+ * 只读聚合缓存（`session_projcache.json`）时，本机 1347 条会话里有 902 条拿不到标题 → 界面退化成
+ * `session-<uuid>`，用户在同屏十几条里认不出哪条是自己的对话。
+ *
+ * 成本：只读「聚合缓存里没有标题」的那些（本机约 900 条小文件；实测全量顺序读 1349 份 = 361 ms），
+ * 32 路并发 + mtime 缓存 —— 同一批会话重复查询（打开选择器 / 勾选 / 联动补跑）不再重复读盘。
+ *
+ * 语义：**只增不改** —— 已缓存的标题与 blank 一律保留；实在读不到的会话原样返回（界面回落目录名）。
+ *
+ * @param refs 会话单元 id（`sessions:<项目键>/<目录名>`）或裸目录名，混着传也行
+ */
+export declare function readSessionMetaWithTitles(ctx: HostContext, refs: readonly string[]): Promise<SessionMetaIndex>;
 /**
  * 给 **导入计划项**（sessions 分区）补上「界面标题 + 工作区分组」。
  *
@@ -62,7 +83,9 @@ export declare function applySessionMetaToPlanItems<T extends {
     adapter: string;
     label?: string;
     group?: string;
-}>(items: readonly T[], index: SessionMetaIndex, sectionId?: string): T[];
+}>(items: readonly T[], index: SessionMetaIndex, sectionId?: string): (T & {
+    blank?: boolean;
+})[];
 /**
  * 「子代理会话 → 父对话」映射（**裸键**）：DSH 会话存储的父子关系 → `Map<子会话裸键, 父对话裸键>`。
  *
@@ -80,6 +103,23 @@ export declare function applySessionParentLinks<T extends {
     id: string;
     parentSessionId?: string;
 }>(units: readonly T[], parentOf: ReadonlyMap<string, string> | undefined, sectionId?: string): T[];
+/**
+ * 给**会话体检行**补上「界面标题」（行上的 `sessionId` = 会话目录名，索引键是裸键 → 查表前必须归一化）。
+ *
+ * 为什么需要：体检列表此前只显示目录名（`session-20d2722c-…`），用户在同一屏十几条里认不出哪条是自己的
+ * 对话（2026-10-12 用户反馈截图实证）。标题的唯一可靠来源就是 DSH 自己的会话缓存
+ * （`storages/session_projcache.json` 的 `rows.title.val`）—— 与导出选择器**同一份索引、同一套
+ * `sessionIdKey` 归一化口径**，绝不另写一套查表规则。
+ *
+ * 只读、纯函数、**绝不编造**：索引里没有这条会话 / 没有标题 → 原样返回（界面回落显示目录名）。
+ * 索引本身由 `readSessionMetaWithTitles()` 产出（聚合缓存 + **逐会话投影文件**兜底，见那里）。
+ */
+export declare function applySessionTitles<T extends {
+    sessionId?: string | null;
+}>(rows: readonly T[], index: SessionMetaIndex): (T & {
+    title?: string;
+    blank?: boolean;
+})[];
 /**
  * 给 sessions 分区的单元补上「界面标题 + 工作区分组」，并按「工作区 → 最近在前」排序。
  *

package/lib/core/session-meta.js

@@ -1,5 +1,13 @@
 const SESSION_PROJCACHE = 'storages/session_projcache.json';
 const WORKSPACE_STORE = 'storages/workspace.json';
+/**
+ * **逐会话**投影存储目录（`storages/session_projcache/sessions/<会话目录名>.json`）。
+ *
+ * 与 `session_projcache.json` 的关系：那个是**会淘汰的近期聚合**（本机实测只覆盖 445/1347 条会话），
+ * 这个目录才是 DSH 为**每条会话**留下的投影（本机 1349 份，其中 1150 份带标题）。只读聚合缓存会让
+ * 其余会话在选择器 / 体检列表里退化成 uuid 目录名 —— 用户认不出哪条是哪条。
+ */
+const SESSION_PROJECTION_DIR = 'storages/session_projcache/sessions';
 // projectKeyOf 已下移到**零依赖**模块 `session-select.ts`（客户端勾选联动要按 cwd 目录键认领工作区，
 // 而本模块会用 Buffer 读 DSH 存储缓存，不能进浏览器 bundle）。这里 re-export，既有导入路径逐字不变。
 import { projectKeyOf, sessionIdKey } from './session-select.js';
@@ -35,9 +43,18 @@ function asRecord(value) {
  * 键含 `homeDir`（同进程可能服务多份 home）。
  */
 const metaCache = new Map();
-/** 清空索引缓存（测试用；宿主在收到「DSH 存储已重载」信号时也可调用）。 */
+/**
+ * 逐会话投影文件的**进程内缓存**（键含 homeDir + 相对路径，失效判据 = 该文件 mtime）。
+ *
+ * 为什么需要：导出选择器一次要补上千条会话的标题，而同一批会话在一次交互里会被反复查询
+ * （打开选择器 → 勾选 → 会话↔工作区联动补跑）。每次重读 1300 个小文件会把「打开弹窗」拖成秒级。
+ * 与 `metaCache` 同一条纪律：**读不到 mtime 就不缓存**（宁可贵一点，也绝不拿陈旧标题骗用户）。
+ */
+const projectionCache = new Map();
+/** 清空索引与逐会话投影缓存（测试用；宿主在收到「DSH 存储已重载」信号时也可调用）。 */
 export function clearSessionMetaCache() {
     metaCache.clear();
+    projectionCache.clear();
 }
 /** 文件 mtime（毫秒；门面未实现 / 读不到 → null = 无法判定新鲜度，调用方不得缓存）。 */
 async function mtimeOf(ctx, rel) {
@@ -115,6 +132,97 @@ async function loadSessionMeta(ctx) {
     }
     return index;
 }
+/**
+ * 会话单元 id（`sessions:<项目键>/<目录名>`）或裸目录名 → **归一化裸键**（`sessionIdKey`）。
+ *
+ * 为什么要有：调用方手上是单元 id / 计划项 id（末段才是目录名），而索引与投影文件都按**裸键**存。
+ */
+export function sessionBareKeyOf(ref) {
+    const slash = ref.lastIndexOf('/');
+    return sessionIdKey(slash >= 0 ? ref.slice(slash + 1) : ref);
+}
+/** 逐会话投影文件的候选名（DSH 实测两种目录名形态并存：`session-<uuid>.json` 与 `<uuid>.json`）。 */
+function projectionFileNames(bare) {
+    return ['session-' + bare + '.json', bare + '.json'];
+}
+/**
+ * 读一条会话的**逐会话投影文件**（`storages/session_projcache/sessions/<会话目录名>.json`）。
+ *
+ * 形状与聚合缓存略有差异：文件里是 `{ version, record: { identity, rows } }`，聚合里是 `{ identity, rows }`
+ * —— 两种都认（`record` 缺省即顶层）。**只读、尽力而为、绝不抛错**：读不到 / 形状不认 → undefined。
+ */
+async function readProjectedSession(ctx, bare) {
+    for (const name of projectionFileNames(bare)) {
+        const rel = SESSION_PROJECTION_DIR + '/' + name;
+        const cacheId = ctx.homeDir + '\u0000' + rel;
+        const mtime = await mtimeOf(ctx, rel);
+        if (mtime !== null) {
+            const hit = projectionCache.get(cacheId);
+            if (hit !== undefined && hit.key === String(mtime))
+                return hit.facts;
+        }
+        let facts;
+        const raw = asRecord(await readJsonSafe(ctx, rel));
+        if (raw !== null) {
+            const rec = asRecord(raw['record']) ?? raw;
+            const rows = asRecord(rec['rows']);
+            const title = asRecord(rows?.['title'])?.['val'];
+            const listMeta = asRecord(asRecord(rows?.['sessionListMetadata'])?.['val']);
+            const out = {};
+            if (typeof title === 'string' && title.trim() !== '')
+                out.title = title.trim();
+            if (listMeta?.['blank'] === true)
+                out.blank = true;
+            facts = out;
+        }
+        if (mtime === null)
+            projectionCache.delete(cacheId);
+        else
+            projectionCache.set(cacheId, { key: String(mtime), facts });
+        if (facts !== undefined)
+            return facts;
+    }
+    return undefined;
+}
+/** 一次并发读多少份投影文件（小文件；32 路实测把 1300 条压到百毫秒级）。 */
+const PROJECTION_CONCURRENCY = 32;
+/**
+ * 「界面标题」的**全量**解析：聚合缓存优先，缺的按需读**逐会话投影文件**。
+ *
+ * 用户要求（2026-10-12）：「历史对话的文本**始终**用对话标题，而不是只取缓存里的标题」。
+ * 只读聚合缓存（`session_projcache.json`）时，本机 1347 条会话里有 902 条拿不到标题 → 界面退化成
+ * `session-<uuid>`，用户在同屏十几条里认不出哪条是自己的对话。
+ *
+ * 成本：只读「聚合缓存里没有标题」的那些（本机约 900 条小文件；实测全量顺序读 1349 份 = 361 ms），
+ * 32 路并发 + mtime 缓存 —— 同一批会话重复查询（打开选择器 / 勾选 / 联动补跑）不再重复读盘。
+ *
+ * 语义：**只增不改** —— 已缓存的标题与 blank 一律保留；实在读不到的会话原样返回（界面回落目录名）。
+ *
+ * @param refs 会话单元 id（`sessions:<项目键>/<目录名>`）或裸目录名，混着传也行
+ */
+export async function readSessionMetaWithTitles(ctx, refs) {
+    const index = await readSessionMeta(ctx);
+    const need = [...new Set(refs.map((ref) => sessionBareKeyOf(ref)).filter((bare) => bare !== ''))]
+        .filter((bare) => index.bySessionId.get(bare)?.title === undefined);
+    if (need.length === 0)
+        return index;
+    const bySessionId = new Map(index.bySessionId);
+    for (let i = 0; i < need.length; i += PROJECTION_CONCURRENCY) {
+        const chunk = need.slice(i, i + PROJECTION_CONCURRENCY);
+        const found = await Promise.all(chunk.map(async (bare) => [bare, await readProjectedSession(ctx, bare)]));
+        for (const [bare, facts] of found) {
+            if (facts === undefined)
+                continue;
+            const existing = bySessionId.get(bare) ?? {};
+            bySessionId.set(bare, {
+                ...existing,
+                ...(facts.title !== undefined ? { title: facts.title } : {}),
+                ...(facts.blank !== undefined ? { blank: facts.blank } : {}),
+            });
+        }
+    }
+    return { ...index, bySessionId };
+}
 /** 单元 id（`sessions:<项目键>/<会话目录名>`）→ 会话目录名；形状不符 → null。 */
 function sessionIdOfUnit(sectionId, unitId) {
     const prefix = sectionId + ':';
@@ -150,6 +258,8 @@ export function applySessionMetaToPlanItems(items, index, sectionId = 'sessions'
         return {
             ...item,
             ...(meta?.title !== undefined ? { label: meta.title } : {}),
+            // 空白会话（从未提问）：DSH 自己显示「新会话」而不是 uuid；标记随计划项下发，由界面本地化
+            ...(meta?.blank === true ? { blank: true } : {}),
             group,
         };
     });
@@ -192,6 +302,33 @@ export function applySessionParentLinks(units, parentOf, sectionId = 'sessions')
         return parent === undefined ? unit : { ...unit, parentSessionId: parent };
     });
 }
+/**
+ * 给**会话体检行**补上「界面标题」（行上的 `sessionId` = 会话目录名，索引键是裸键 → 查表前必须归一化）。
+ *
+ * 为什么需要：体检列表此前只显示目录名（`session-20d2722c-…`），用户在同一屏十几条里认不出哪条是自己的
+ * 对话（2026-10-12 用户反馈截图实证）。标题的唯一可靠来源就是 DSH 自己的会话缓存
+ * （`storages/session_projcache.json` 的 `rows.title.val`）—— 与导出选择器**同一份索引、同一套
+ * `sessionIdKey` 归一化口径**，绝不另写一套查表规则。
+ *
+ * 只读、纯函数、**绝不编造**：索引里没有这条会话 / 没有标题 → 原样返回（界面回落显示目录名）。
+ * 索引本身由 `readSessionMetaWithTitles()` 产出（聚合缓存 + **逐会话投影文件**兜底，见那里）。
+ */
+export function applySessionTitles(rows, index) {
+    return rows.map((row) => {
+        // 会话 id 缺失 / 空串的记录**一个字段都不加**（回滚台账里有这类历史记录：绝不猜它属于哪条对话）
+        if (typeof row.sessionId !== 'string' || row.sessionId === '')
+            return row;
+        const meta = index.bySessionId.get(sessionIdKey(row.sessionId));
+        if (meta === undefined)
+            return row;
+        return {
+            ...row,
+            ...(meta.title !== undefined ? { title: meta.title } : {}),
+            // 空白会话（从未提问）：没有标题，界面据此显示本地化的「新会话」（与 DSH 的 session.new 同口径）
+            ...(meta.blank === true ? { blank: true } : {}),
+        };
+    });
+}
 /**
  * 给 sessions 分区的单元补上「界面标题 + 工作区分组」，并按「工作区 → 最近在前」排序。
  *
@@ -221,6 +358,8 @@ export function applySessionMeta(units, index, sectionId = 'sessions', activityA
             label: meta?.title ?? unit.label,
             ...(detail !== undefined ? { detail } : {}),
             group: workspaceTitle ?? parsed.projectKey,
+            // 空白会话（从未提问）：没有标题可显示，标记出来让界面显示本地化的「新会话」（与 DSH 同口径）
+            ...(meta?.blank === true ? { blank: true } : {}),
         };
     });
     // 排序：先按工作区（保持首次出现顺序），组内最近活跃的在前；无时间的排在组内末尾。

package/lib/core/session-title.d.ts

@@ -0,0 +1,28 @@
+/** 只扫日志前这么多字节（标题通常在开头几回合内写入；更大的日志只扫前缀，读不到就回落 id）。 */
+export declare const SESSION_TITLE_SCAN_BYTES: number;
+/** 一次请求最多为几个会话做日志兜底（按 unitId 去重之后）。 */
+export declare const SESSION_TITLE_MAX_READS = 24;
+/** 清空缓存（单测用；宿主进程内长期有效是刻意的）。 */
+export declare function clearSessionTitleCache(): void;
+/**
+ * 从会话日志里读这条会话自己的名字（`session/title` 事件）。
+ *
+ * @param sessionsDir 会话根目录（`<homeDir>/sessions`）。
+ * @param unitId 台账里的会话单元 id（`<projectKey>/<sessionId>`；缺了就返回 null）。
+ * @returns 标题；读不到 / 没有标题事件 / 形状不符 → null（界面回落显示会话 id）。
+ */
+export declare function readSessionTitleFromLog(sessionsDir: string, unitId: string): Promise<string | null>;
+/**
+ * 给一批台账行补标题：**已有标题的不动**，缺标题的按 `unitId` 去重后走日志兜底。
+ *
+ * 只读、有界（见 {@link SESSION_TITLE_MAX_READS}）、失败一律原样返回（界面回落显示会话 id）。
+ */
+export declare function applySessionLogTitles<T extends {
+    sessionId?: string | null;
+    unitId?: string | null;
+    title?: string;
+}>(rows: readonly T[], sessionsDir: string, options?: {
+    maxReads?: number;
+}): Promise<(T & {
+    title?: string;
+})[]>;

package/lib/core/session-title.js

@@ -0,0 +1,185 @@
+/**
+ * 「会话标题」的**日志兜底**（2026-10-12 用户要求：缓存里没有这条会话，就自动读这条会话自己的名字）。
+ *
+ * 两条来源，优先级固定：
+ *  ① `storages/session_projcache.json` 的 `rows.title.val`（`core/session-meta.ts` 的索引，快、覆盖常态）；
+ *  ② **会话日志里的 `session/title` 事件**（本模块）—— DSH 自己写的标题事件，
+ *     `data = { title, messageSeqs, source }`；`source = 'user'` 表示用户显式改过名（它压过自动生成的那条）。
+ *     缓存里没有这条会话（旧会话 / 别的档案写的 / 子代理会话）时，这是**唯一不猜**的名字来源。
+ *
+ * 只读 + 有界 + 诚实：
+ *  · 只读日志**前** {@link SESSION_TITLE_SCAN_BYTES}（1 MiB，覆盖「标题在开头几回合内生成」的常态）；
+ *    超出这个窗口的标题事件读不到 → 返回 null，界面回落显示会话 id（**绝不从首条消息编造标题**）；
+ *  · 同一个会话出现多条标题事件时取**最后一条**（用户改名压过自动标题）；
+ *  · 同一条日志按 `mtime + size` 缓存在进程内：日志增长（新标题落盘）后自动重读，不吃陈旧结论；
+ *  · 一次请求最多补 {@link SESSION_TITLE_MAX_READS} 个会话（台账里几十条缺标题时不把盘读穿）。
+ */
+import { open, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isSessionLogName } from '../utils/session-log.js';
+import { decodeZstdFrame, scanZstdFrames, zstdAvailable } from '../utils/zstd-frame.js';
+/** 只扫日志前这么多字节（标题通常在开头几回合内写入；更大的日志只扫前缀，读不到就回落 id）。 */
+export const SESSION_TITLE_SCAN_BYTES = 1024 * 1024;
+/** 一次请求最多为几个会话做日志兜底（按 unitId 去重之后）。 */
+export const SESSION_TITLE_MAX_READS = 24;
+/** 进程内缓存：绝对路径 → （mtime + size + 结论）。日志一增长就失效（不吃陈旧结论）。 */
+const titleCache = new Map();
+/** 清空缓存（单测用；宿主进程内长期有效是刻意的）。 */
+export function clearSessionTitleCache() {
+    titleCache.clear();
+}
+/** `session/title` 事件行 → 标题（形状不对 / 空标题一律 null，绝不猜）。 */
+function titleOfRow(row) {
+    if (row === null || typeof row !== 'object' || Array.isArray(row))
+        return null;
+    const rec = row;
+    if (rec['type'] !== 'session/title')
+        return null;
+    const data = rec['data'];
+    if (data === null || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const title = data['title'];
+    return typeof title === 'string' && title.trim() !== '' ? title.trim() : null;
+}
+/** 只读日志**前缀**（最多 `max` 字节；读不出回 null，绝不抛）。 */
+async function readPrefix(absPath, max) {
+    let handle;
+    try {
+        handle = await open(absPath, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buffer = Buffer.allocUnsafe(max);
+        const { bytesRead } = await handle.read(buffer, 0, max, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/**
+ * 从会话日志字节里取标题：解出每个**完整**帧，逐行先做 `session/title` 子串预筛（省掉整篇 JSON.parse），
+ * 命中才解析该行；多条命中取最后一条。容器损坏 / 无 zstd 能力 → null。
+ */
+function titleFromBytes(bytes) {
+    let frames;
+    try {
+        frames = scanZstdFrames(bytes).frames;
+    }
+    catch {
+        return null;
+    }
+    let found = null;
+    for (const frame of frames) {
+        let text;
+        try {
+            text = decodeZstdFrame(bytes.subarray(frame.start, frame.end)).toString('utf8');
+        }
+        catch {
+            return found;
+        }
+        for (const line of text.split('\n')) {
+            if (line === '' || !line.includes('session/title'))
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const title = titleOfRow(parsed);
+            if (title !== null)
+                found = title;
+        }
+    }
+    return found;
+}
+/** 读单个日志文件的标题（带 mtime+size 缓存）。 */
+async function readTitleFromLogFile(absPath) {
+    if (!zstdAvailable())
+        return null;
+    const info = await stat(absPath).catch(() => null);
+    if (info === null)
+        return null;
+    const cached = titleCache.get(absPath);
+    if (cached !== undefined && cached.mtimeMs === info.mtimeMs && cached.size === info.size)
+        return cached.title;
+    const prefix = await readPrefix(absPath, SESSION_TITLE_SCAN_BYTES);
+    const title = prefix === null ? null : titleFromBytes(prefix);
+    titleCache.set(absPath, { mtimeMs: info.mtimeMs, size: info.size, title });
+    return title;
+}
+/** `unitId`（`<projectKey>/<sessionId>`）→ 目录段；越界 / 形状不符一律 null（绝不拼可疑路径）。 */
+function unitSegments(unitId) {
+    const parts = unitId.split('/').filter((part) => part !== '');
+    if (parts.length < 2)
+        return null;
+    for (const part of parts) {
+        if (part === '.' || part === '..' || part.includes('\\') || part.includes(':'))
+            return null;
+    }
+    return parts;
+}
+/**
+ * 从会话日志里读这条会话自己的名字（`session/title` 事件）。
+ *
+ * @param sessionsDir 会话根目录（`<homeDir>/sessions`）。
+ * @param unitId 台账里的会话单元 id（`<projectKey>/<sessionId>`；缺了就返回 null）。
+ * @returns 标题；读不到 / 没有标题事件 / 形状不符 → null（界面回落显示会话 id）。
+ */
+export async function readSessionTitleFromLog(sessionsDir, unitId) {
+    const parts = unitSegments(unitId);
+    if (parts === null)
+        return null;
+    const dir = join(sessionsDir, ...parts);
+    const names = await readdir(dir).catch(() => []);
+    const logs = names.filter((name) => isSessionLogName(name)).sort();
+    if (logs.length === 0)
+        return null;
+    // 与体检同口径：同一会话有多份 generation 时以**最新的一份**（字典序最后）为准
+    const picked = logs[logs.length - 1];
+    if (picked === undefined)
+        return null;
+    return readTitleFromLogFile(join(dir, picked));
+}
+/**
+ * 给一批台账行补标题：**已有标题的不动**，缺标题的按 `unitId` 去重后走日志兜底。
+ *
+ * 只读、有界（见 {@link SESSION_TITLE_MAX_READS}）、失败一律原样返回（界面回落显示会话 id）。
+ */
+export async function applySessionLogTitles(rows, sessionsDir, options = {}) {
+    const maxReads = Math.max(0, options.maxReads ?? SESSION_TITLE_MAX_READS);
+    const resolved = new Map();
+    const out = [];
+    let reads = 0;
+    for (const row of rows) {
+        if (typeof row.title === 'string' && row.title.trim() !== '') {
+            out.push(row);
+            continue;
+        }
+        const unitId = typeof row.unitId === 'string' && row.unitId !== '' ? row.unitId : null;
+        if (unitId === null) {
+            out.push(row);
+            continue;
+        }
+        let title = resolved.get(unitId);
+        if (title === undefined) {
+            if (reads >= maxReads) {
+                out.push(row);
+                continue;
+            }
+            reads += 1;
+            title = await readSessionTitleFromLog(sessionsDir, unitId);
+            resolved.set(unitId, title);
+        }
+        out.push(title === null || title === '' ? row : { ...row, title });
+    }
+    return out;
+}
+//# sourceMappingURL=session-title.js.map

package/lib/core/startup-barrier.d.ts

@@ -30,6 +30,30 @@ export declare function classifyStartup(opts: {
     options?: ReconcileOptions;
     lockState: 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE';
 }): StartupClassifier;
+/**
+ * 启动分类结束后如何处置 SAFE MODE（issue #87，单一判据，便于单测；宿主 apply() 只消费结论）。
+ *
+ * 为什么需要它：`probeSafeModeSync()` 读的是**上一轮**留下的 durable 标记，而分类结论才是本轮权威。
+ * 分类判 `NORMAL` ⇒ 没有任何未决 journal 能解释那个标记 ⇒ 它是陈旧标记，必须**同时**复位内存标志与
+ * durable 标记 —— 只复位内存会让本会话的写操作继续被 423 挡着（界面却说「无待处理事项」），只复位标记
+ * 又会在下一次 probe 时重新置起（标记跨重启生效）。
+ *
+ * 为什么要求 `lockState === 'FREE'`：`LOCKED` 且无未决 journal 时分类同样返回 NORMAL，但那只说明
+ * **另一个存活实例**正在持有环境锁 —— 此刻清标记等于替别人解除保护。**只有确认没有活锁者才清。**
+ *
+ * 为什么要求 `currentlyBlocked`（即 probe 读到 durable 标记确实是 'blocked'）：标记为 `'unknown'`
+ * （存在但读不出/布局不可信）时不在这里清 —— 那属于无法判定，既不假装已解除，也不假装没看见；
+ * 它本会话不阻断的语义由 `probeSafeModeSync` 的既有约定承担。
+ */
+export declare function resolveStartupSafeMode(input: {
+    kind: StartupRecoveryState['kind'];
+    lockState: 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE';
+    /** 本轮 probe 之前的内存标志（probeSafeModeSync 的结论） */
+    currentlyBlocked: boolean;
+}): {
+    blocked: boolean;
+    clearStaleMarker: boolean;
+};
 export interface StartupSchedulers {
     start(): void;
 }

package/lib/core/startup-barrier.js

@@ -40,6 +40,28 @@ export function classifyStartup(opts) {
         },
     };
 }
+/**
+ * 启动分类结束后如何处置 SAFE MODE（issue #87，单一判据，便于单测；宿主 apply() 只消费结论）。
+ *
+ * 为什么需要它：`probeSafeModeSync()` 读的是**上一轮**留下的 durable 标记，而分类结论才是本轮权威。
+ * 分类判 `NORMAL` ⇒ 没有任何未决 journal 能解释那个标记 ⇒ 它是陈旧标记，必须**同时**复位内存标志与
+ * durable 标记 —— 只复位内存会让本会话的写操作继续被 423 挡着（界面却说「无待处理事项」），只复位标记
+ * 又会在下一次 probe 时重新置起（标记跨重启生效）。
+ *
+ * 为什么要求 `lockState === 'FREE'`：`LOCKED` 且无未决 journal 时分类同样返回 NORMAL，但那只说明
+ * **另一个存活实例**正在持有环境锁 —— 此刻清标记等于替别人解除保护。**只有确认没有活锁者才清。**
+ *
+ * 为什么要求 `currentlyBlocked`（即 probe 读到 durable 标记确实是 'blocked'）：标记为 `'unknown'`
+ * （存在但读不出/布局不可信）时不在这里清 —— 那属于无法判定，既不假装已解除，也不假装没看见；
+ * 它本会话不阻断的语义由 `probeSafeModeSync` 的既有约定承担。
+ */
+export function resolveStartupSafeMode(input) {
+    const staleMarker = input.kind === 'NORMAL' && input.lockState === 'FREE' && input.currentlyBlocked;
+    if (staleMarker)
+        return { blocked: false, clearStaleMarker: true };
+    const forceBlocked = input.kind === 'RECOVERY_REQUIRED' || input.kind === 'NEEDS_ATTENTION' || input.kind === 'UNKNOWN_STATE';
+    return { blocked: input.currentlyBlocked || forceBlocked, clearStaleMarker: false };
+}
 /**
  * 启动分类/探测**抛错**时的 fail-closed 结论（单一来源，勿再各写一份）：
  *  - `state`：绝不默认 NORMAL，归为 RECOVERY_REQUIRED；

package/lib/core/transaction-coordinator.js

@@ -15,6 +15,7 @@
  * SAFE MODE 门禁经注入谓词（isBlocked）由 Coordinator 传入 lock helper（见 env-lock 改造）。
  */
 import { JournalStore, createJournalEntry, transitionJournalState, isTerminalState, generateOperationId, redactJournalText, } from './journal.js';
+import { engineMsg } from './messages-core.js';
 // ---------- Coordinator ----------
 export class MutationTransactionCoordinator {
     deps;
@@ -36,9 +37,9 @@ export class MutationTransactionCoordinator {
                 : 'needs-attention';
             if (recovered === 'recovered' || recovered === 'rolled-back') {
                 // 残留已收敛 → 可继续；但本函数语义：先返回，调用方重试 run
-                return { outcome: 'RECOVERY_REQUIRED', operationId: activeCheck.residue, reason: `残留 active transaction ${activeCheck.residue} 待处理，请重试` };
+                return { outcome: 'RECOVERY_REQUIRED', operationId: activeCheck.residue, reason: engineMsg('core.txn.residuePending', { residue: activeCheck.residue }) };
             }
-            return { outcome: 'RECOVERY_REQUIRED', operationId: activeCheck.residue, reason: `存在 unresolved active transaction ${activeCheck.residue}` };
+            return { outcome: 'RECOVERY_REQUIRED', operationId: activeCheck.residue, reason: engineMsg('core.txn.unresolvedActive', { residue: activeCheck.residue }) };
         }
         // 3. 创建 journal
         const operationId = generateOperationId();
@@ -149,7 +150,7 @@ export class MutationTransactionCoordinator {
             if (current !== null && isTerminalState(current.state)) {
                 // 已 terminal（如 COMMITTED 后 move 抛错 → 保持 terminal，不回滚）
                 const opId = operationId;
-                return { outcome: 'NEEDS_ATTENTION', operationId: opId, reason: `tail/commit 后异常：${msg}`, snapshotId };
+                return { outcome: 'NEEDS_ATTENTION', operationId: opId, reason: engineMsg('core.txn.tailCommitFailed', { message: msg }), snapshotId };
             }
             return await this.finalizeAttention(operationId, msg, snapshotId, context);
         }