dsh-config-manager 0.1.71 → 0.1.72

package/lib/core/disk-usage.js

@@ -9,12 +9,38 @@
  *   ② 对「可回收」子区按各自保留期算出**已超期**的字节数与条目数（与 host 侧清理逻辑同口径，
  *      保留期由调用方注入 —— 本模块不读配置、不猜默认值）。
  *
- * 硬约束：**只读**。任何子路径缺失/不可读都不抛错，如实降级为该子区 0 字节；
- * 扫描期间出现的竞态删除（readdir/stat 失败）只终止那一支，不影响其余统计。
+ * 硬约束：**只读**。任何子路径缺失/不可读都不抛错，如实降级为该子区 0 字节、并把
+ * `unreadable` 置真（界面显示「未统计」而不是 0）；扫描期间出现的竞态删除（readdir/stat
+ * 失败）只终止那一支，不影响其余统计。
+ *
+ * 已补齐两块此前不可见的占用（都**只报告、绝不提供清理**）：
+ *  - 回滚点库 `dataDir/rollback-points`：并进 `DISK_USAGE_AREAS`，`policy: 'protected'`；
+ *  - 「遗留数据」`LEGACY_DATA_DIRS`（当前一条：旧检查点库 `dataDir/checkpoints`）：
+ *    插件**已不再读取**该目录，也**不代删**（删除不可逆，需用户单独授权）。
+ * 本模块与清理动作完全解耦：`IMMEDIATE_CLEAN_CATEGORIES` 只有可重建区，
+ * `POST /disk-usage/cleanup` 的候选白名单也只有 'tmp' | 'expired-exports'。
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-/** 体检子区（顺序即界面展示顺序：先备份产物，再缓存/暂存） */
+/**
+ * 回滚点库目录名（`dataDir/rollback-points`）。
+ *
+ * 为什么不直接 import 引擎的 `ROLLBACK_POINTS_DIR_NAME`：本模块是**只读体检**，也是离线
+ * 救急台（`dcm web` 的磁盘页）的依赖 —— 不该把整个回滚引擎（crypto / zlib / atomic-write /
+ * 会话索引…）拉进它的运行时依赖图；引擎文件一旦有问题，救急台恰恰是最不该跟着挂的那个页面。
+ * 「单一事实源」在这里靠**源码级守卫**而不是 import：`disk-usage.test.ts` 直接读
+ * `src/core/rollback-point.ts` 的声明并与本常量逐字比对（改了那边、或改了这边，测试即红）
+ * —— 与 `tests/packaging-contract.test.ts` 的 V-1（源码级读 `PLUGIN_VERSION`，不 import 宿主入口）
+ * 同一种姿势。
+ */
+const ROLLBACK_POINTS_DIR = 'rollback-points';
+/**
+ * 只报告、**不提供清理**的子区（当前一条：回滚点库 = `dataDir/rollback-points`）。
+ * 它只是「口径清单」：报告/展示一律用完备的 `DISK_USAGE_AREAS`，清理候选另有白名单
+ * （`IMMEDIATE_CLEAN_CATEGORIES` / 清理入口 categories），两者不得混用。
+ */
+export const DISK_USAGE_EXTRA_AREAS = ['rollback-points'];
+/** 体检子区（顺序即报告/展示顺序：先备份产物，再缓存/暂存，末位为只读保护的附加区） */
 export const DISK_USAGE_AREAS = [
     'exports',
     'snapshots',
@@ -28,10 +54,22 @@ export const DISK_USAGE_AREAS = [
     'transactions',
     'locks',
     'vault',
+    ...DISK_USAGE_EXTRA_AREAS,
+];
+/**
+ * 遗留数据目录清单（当前一条：旧检查点库）。
+ *
+ * `checkpoints/` 是回滚点库改名（`rollback-points/`）之前的旧目录：新代码**不再读取**它，
+ * 本插件也**不去删**它（删除是不可逆动作，需用户单独授权）。
+ */
+export const LEGACY_DATA_DIRS = [
+    { id: 'legacy-checkpoints', relPath: 'checkpoints' },
 ];
 /** 可立即整块清理的子区（转成磁盘使用分区 id；供清理路由映射回结果） */
 export const IMMEDIATE_CLEAN_CATEGORIES = ['tmp', 'marketCache', 'marketWork'];
-/** 子区 → 物理目录（单一映射点；展示与统计都不再重复挑目录） */
+/** 子区 → 物理目录（单一映射点；展示与统计都不再重复挑目录）。
+ *  回滚点库不在 `DiskUsageDirs` 里显式传：它的位置 = `dataDir` + `ROLLBACK_POINTS_DIR`
+ *  （与引擎常量逐字一致，有源码级守卫），宿主路由与离线 CLI 两条构造路径因此不可能漂移。 */
 export function diskUsageDirOf(dirs, area) {
     switch (area) {
         case 'exports': return dirs.exportsDir;
@@ -46,6 +84,7 @@ export function diskUsageDirOf(dirs, area) {
         case 'transactions': return dirs.transactionsDir;
         case 'locks': return dirs.locksDir;
         case 'vault': return dirs.vaultDir;
+        case 'rollback-points': return path.join(dirs.dataDir, ROLLBACK_POINTS_DIR);
     }
 }
 /**
@@ -184,6 +223,8 @@ export async function scanDiskUsage(options) {
         transactions: null,
         locks: null,
         vault: null,
+        // 回滚点库没有「保留期」：只报告，绝不自动清理（工作区 + 会话两态的恢复入口）
+        'rollback-points': null,
     };
     const policyOf = {
         exports: 'retained',
@@ -198,6 +239,8 @@ export async function scanDiskUsage(options) {
         transactions: 'protected',
         locks: 'protected',
         vault: 'protected',
+        // 与 snapshots/sync 同语义：用户数据/恢复入口 —— 只报告，绝不提供清理
+        'rollback-points': 'protected',
     };
     const areas = {};
     let totalBytes = 0;
@@ -233,6 +276,25 @@ export async function scanDiskUsage(options) {
         if (entry.policy === 'regenerable')
             reclaimableBytes += walk.sizeBytes;
     }
+    /**
+     * 遗留数据：与子区**同一套**遍历口径（只读、不跟随符号链接、读不到即 unreadable），
+     * 但**不计入 totalBytes**（与 areas 分列），且 policy 恒为 protected —— 本模块不提供
+     * 任何删除动作，也不把它们的路径交给清理入口。
+     */
+    const legacy = [];
+    for (const item of LEGACY_DATA_DIRS) {
+        const dir = path.join(dirs.dataDir, item.relPath);
+        const walk = await walkDirectory(dir, null, nowMs);
+        legacy.push({
+            id: item.id,
+            relPath: item.relPath,
+            path: dir,
+            sizeBytes: walk.sizeBytes,
+            fileCount: walk.fileCount,
+            unreadable: walk.unreadable,
+            policy: 'protected',
+        });
+    }
     return {
         dataDir: dirs.dataDir,
         totalBytes,
@@ -240,6 +302,7 @@ export async function scanDiskUsage(options) {
         reclaimableBytes,
         expiredBytes,
         areas,
+        legacy,
         backupRetention: { keepLast: options.backupKeepLast ?? 10, latestBackupBytes: 0, latestBackupAt: null },
     };
 }

package/lib/core/engine-locale.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 引擎语言运行时（宿主 / 引擎半）——「英文界面零中文」的引擎侧根因修复。
+ *
+ * 语义（唯一要记住的一句话）：**语言必须在「取文案的那一刻」解析，而不是在「装配的那一刻」**。
+ * 改造前的写法是 this.msg = makeMsg(resolveAppLanguage(ctx))：apply() 只在插件加载时执行一次，
+ * 于是宿主产出的报告 / 计划 / 错误文本被冻结成加载时那门语言（用户切到 English 后仍是中文）。
+ *
+ * 本模块提供三件事：
+ *  1. 语言运行时：setEngineLocale / setEngineLanguageSource / getEngineLocale /
+ *     invalidateEngineLocale（函数源按 LANGUAGE_TTL_MS 兜底缓存；取文案时才解析）；
+ *  2. 消息目录注册：registerMessageCatalog（领域模块追加自己的目录，**仅在既有目录未命中时生效**）；
+ *     基础目录（src/core/messages.ts 的 zh/en）由该模块经 registerBaseMessageCatalog 反向注册；
+ *  3. engineMsg：宿主 / 引擎半的活翻译器（MsgFunc 形状），未知键回退 zh → 键名，绝不抛错。
+ *
+ * 纪律：
+ *  - 未设定语言时行为等于 zh（与改造前的缺省逐字一致）；
+ *  - 本模块**不 import src/core/messages.ts**（否则形成循环依赖）：基础目录由 messages.ts 反向注册；
+ *  - 目录查找每次调用现查（目录是常量，成本可忽略）；语言只按 LANGUAGE_TTL_MS 缓存。
+ */
+import type { MsgParams } from './msg-types.ts';
+/** 应用语言（与 DSH settings 的 locale preference 同口径）。 */
+export type LanguageId = 'zh' | 'en';
+/**
+ * 语言源允许的缓存上界（毫秒）。
+ *
+ * 只给**非请求路径**（调度器、后台任务）兜底：请求入口应调用 invalidateEngineLocale()
+ * 让每个请求都拿到最新语言（见 routes/kit.ts 的注册点）。
+ */
+export declare const LANGUAGE_TTL_MS = 1000;
+/** 目录（zh 源 / en 镜像；两本都可选，缺的那本不参与查找）。 */
+export interface MessageCatalog {
+    /** 目录标识（诊断用）。 */
+    readonly id?: string;
+    readonly zh?: Readonly<Record<string, string>>;
+    readonly en?: Readonly<Record<string, string>>;
+}
+/** 语言源：固定值，或「调用期解析」的活源。 */
+export type LanguageSource = LanguageId | (() => LanguageId);
+/** 设定引擎语言（固定值）：构造宿主时按 resolveAppLanguage(ctx) 初始化。 */
+export declare function setEngineLocale(locale: LanguageSource): void;
+/**
+ * 注册「调用期解析」的语言活源（宿主用 () => resolveAppLanguage(ctx)）。
+ *
+ * 与 setEngineLocale 同源：后者给构造期的初值，本函数让**之后**每次取文案都能跟随用户切语言。
+ */
+export declare function setEngineLanguageSource(resolve: () => LanguageId): void;
+/** 强制失效：下一次 getEngineLocale() 必须重新解析（路由入口 / 测试用）。 */
+export declare function invalidateEngineLocale(): void;
+/**
+ * 当前引擎语言（调用期解析）。
+ *
+ * 函数源的结果按 LANGUAGE_TTL_MS 缓存；固定值源缓存无副作用。解析失败一律回落 zh（绝不抛错）。
+ * now 可注入（单测用假时钟验证 TTL 上界）。
+ */
+export declare function getEngineLocale(now?: number): LanguageId;
+/**
+ * 注册基础目录（zh 源 / en 镜像）。
+ *
+ * 由 src/core/messages.ts 在模块初始化时调用一次 —— 这样本模块不必 import 它（避免循环依赖）。
+ * 直接 import engine-locale 而不 import messages.ts 的模块，engineMsg 只能拿到注册目录 + 键名。
+ */
+export declare function registerBaseMessageCatalog(catalogs: {
+    readonly zh: Readonly<Record<string, string>>;
+    readonly en: Readonly<Record<string, string>>;
+}): void;
+/**
+ * 注册一本追加目录（领域模块的键并入既有目录）。
+ *
+ * **只在既有目录未命中时生效**（makeMsg / engineMsg 的查找顺序：既有目录 → 注册目录 → 键名）；
+ * 同一键先注册者优先。en 语言下注册目录未命中时再回退注册目录的 zh（与既有 en → zh 同口径）。
+ */
+export declare function registerMessageCatalog(catalog: MessageCatalog): void;
+/** 已注册的追加目录（只读快照，诊断用）。 */
+export declare function registeredMessageCatalogs(): readonly MessageCatalog[];
+/** 清空追加目录（测试 / 装配隔离用）。 */
+export declare function resetMessageCatalogs(): void;
+/** 注册目录里查一条（未命中 → undefined）。 */
+export declare function registeredMessage(lang: LanguageId, key: string): string | undefined;
+/** 插值：{param} → 形参值；缺参原样保留（便于排查）。与改造前的 messages.ts 逐字同口径。 */
+export declare function interpolate(template: string, params?: MsgParams): string;
+/**
+ * 活翻译器（宿主 / 引擎半的 MsgFunc）：每次调用按 getEngineLocale() 选目录。
+ *
+ * 查找顺序：既有目录（当前语言）→ en 语言下回退既有 zh → 注册目录（同语言 → zh）→ 键名。
+ * 未设定语言时 = zh 目录，行为与改造前逐字一致；未知键回退键名，绝不抛错。
+ */
+export declare function engineMsg(key: string, params?: MsgParams): string;

package/lib/core/engine-locale.js

@@ -0,0 +1,125 @@
+/**
+ * 语言源允许的缓存上界（毫秒）。
+ *
+ * 只给**非请求路径**（调度器、后台任务）兜底：请求入口应调用 invalidateEngineLocale()
+ * 让每个请求都拿到最新语言（见 routes/kit.ts 的注册点）。
+ */
+export const LANGUAGE_TTL_MS = 1000;
+const DEFAULT_LANGUAGE = 'zh';
+let source = DEFAULT_LANGUAGE;
+let cachedLanguage = DEFAULT_LANGUAGE;
+let cachedAt = 0;
+let cachedValid = false;
+function normalize(value) {
+    return value === 'en' ? 'en' : 'zh';
+}
+/** 设定引擎语言（固定值）：构造宿主时按 resolveAppLanguage(ctx) 初始化。 */
+export function setEngineLocale(locale) {
+    source = locale;
+    invalidateEngineLocale();
+}
+/**
+ * 注册「调用期解析」的语言活源（宿主用 () => resolveAppLanguage(ctx)）。
+ *
+ * 与 setEngineLocale 同源：后者给构造期的初值，本函数让**之后**每次取文案都能跟随用户切语言。
+ */
+export function setEngineLanguageSource(resolve) {
+    setEngineLocale(resolve);
+}
+/** 强制失效：下一次 getEngineLocale() 必须重新解析（路由入口 / 测试用）。 */
+export function invalidateEngineLocale() {
+    cachedValid = false;
+    cachedAt = 0;
+}
+/**
+ * 当前引擎语言（调用期解析）。
+ *
+ * 函数源的结果按 LANGUAGE_TTL_MS 缓存；固定值源缓存无副作用。解析失败一律回落 zh（绝不抛错）。
+ * now 可注入（单测用假时钟验证 TTL 上界）。
+ */
+export function getEngineLocale(now = Date.now()) {
+    if (cachedValid && now - cachedAt < LANGUAGE_TTL_MS)
+        return cachedLanguage;
+    let next = DEFAULT_LANGUAGE;
+    try {
+        next = normalize(typeof source === 'function' ? source() : source);
+    }
+    catch {
+        next = cachedValid ? cachedLanguage : DEFAULT_LANGUAGE;
+    }
+    cachedLanguage = next;
+    cachedAt = now;
+    cachedValid = true;
+    return next;
+}
+/* ------------------------------------------------------------- 目录注册 */
+const registry = [];
+let baseZh;
+let baseEn;
+/**
+ * 注册基础目录（zh 源 / en 镜像）。
+ *
+ * 由 src/core/messages.ts 在模块初始化时调用一次 —— 这样本模块不必 import 它（避免循环依赖）。
+ * 直接 import engine-locale 而不 import messages.ts 的模块，engineMsg 只能拿到注册目录 + 键名。
+ */
+export function registerBaseMessageCatalog(catalogs) {
+    baseZh = catalogs.zh;
+    baseEn = catalogs.en;
+}
+/**
+ * 注册一本追加目录（领域模块的键并入既有目录）。
+ *
+ * **只在既有目录未命中时生效**（makeMsg / engineMsg 的查找顺序：既有目录 → 注册目录 → 键名）；
+ * 同一键先注册者优先。en 语言下注册目录未命中时再回退注册目录的 zh（与既有 en → zh 同口径）。
+ */
+export function registerMessageCatalog(catalog) {
+    registry.push(catalog);
+}
+/** 已注册的追加目录（只读快照，诊断用）。 */
+export function registeredMessageCatalogs() {
+    return registry;
+}
+/** 清空追加目录（测试 / 装配隔离用）。 */
+export function resetMessageCatalogs() {
+    registry.length = 0;
+}
+/** 注册目录里查一条（未命中 → undefined）。 */
+export function registeredMessage(lang, key) {
+    for (const catalog of registry) {
+        const hit = catalog[lang]?.[key];
+        if (hit !== undefined)
+            return hit;
+    }
+    if (lang === 'en') {
+        for (const catalog of registry) {
+            const hit = catalog.zh?.[key];
+            if (hit !== undefined)
+                return hit;
+        }
+    }
+    return undefined;
+}
+/* --------------------------------------------------------------- 翻译器 */
+/** 插值：{param} → 形参值；缺参原样保留（便于排查）。与改造前的 messages.ts 逐字同口径。 */
+export function interpolate(template, params) {
+    if (params === undefined)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+        const value = params[key];
+        return value === undefined ? match : String(value);
+    });
+}
+/**
+ * 活翻译器（宿主 / 引擎半的 MsgFunc）：每次调用按 getEngineLocale() 选目录。
+ *
+ * 查找顺序：既有目录（当前语言）→ en 语言下回退既有 zh → 注册目录（同语言 → zh）→ 键名。
+ * 未设定语言时 = zh 目录，行为与改造前逐字一致；未知键回退键名，绝不抛错。
+ */
+export function engineMsg(key, params) {
+    const lang = getEngineLocale();
+    const dict = lang === 'en' ? baseEn : baseZh;
+    const fallback = lang === 'en' ? baseZh : undefined;
+    const template = dict?.[key] ?? fallback?.[key] ?? registeredMessage(lang, key) ?? key;
+    return interpolate(template, params);
+}
+//# sourceMappingURL=engine-locale.js.map

package/lib/core/exporter.js

@@ -18,6 +18,7 @@ import { SECTION_JSON_PATHS, SECTION_FILE_PREFIXES, isFileSection } from '../sch
 import { DEFAULT_SENSITIVE_RELS, refreshVault } from '../security/vault.js';
 import { writeZip } from '../utils/zip.js';
 import { msgOf } from './messages.js';
+import { engineMsg } from './messages-core.js';
 import { declareBundledSessionsInWorkspaces, normalizeSessionLimit, sessionIdKey } from './session-select.js';
 // issue #45 连带匹配的第二判据：工作区 path 的 cwd 目录键（DSH 的 sessionIds 覆盖率很低，见 coupleSessionWorkspaces）
 import { projectKeyOf } from './session-meta.js';
@@ -340,11 +341,10 @@ export class Exporter {
                         warnings.push(this.msg('export.fileSectionSecrets', { section: adapter.id, path: hitPath }));
                     }
                     // 被截断的文件数必须**显式**汇总告警，否则截断本身又变成静默丢失。
-                    // 说明：此处未新增消息键（如 export.fileSectionSecretsTruncated）是为避免与并行任务冲突
-                    // （src/core/messages.ts 属他人改动范围）；故复用 export.fileSectionSecrets，仅 path 传汇总文案。
+                    // 文案在 t4 域目录（src/core/messages-core.ts）：不再借用 export.fileSectionSecrets 传中文 path 值。
                     const truncatedCount = hitPaths.length - warnedPaths.length;
                     if (truncatedCount > 0) {
-                        warnings.push(this.msg('export.fileSectionSecrets', { section: adapter.id, path: `（另有 ${truncatedCount} 个文件命中，详见报告）` }));
+                        warnings.push(engineMsg('core.exporter.fileSectionSecretsTruncated', { section: adapter.id, count: truncatedCount }));
                     }
                 }
             }

package/lib/core/fork-reconcile.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 历史 fork 归位（t17）—— 把「有父会话、但**账内不含它**」的旧子会话收回到它该在的工作区。
+ *
+ * 背景（t10 真机复核）：本机 887 条有父会话的子会话里 58 条是回退 fork，其中能解析到已注册工作区的
+ * 是 **58/58**，但只有 3 条在账内 —— 其余全部停在侧栏「未分组」。t10 的修复只管**新建** fork，
+ * 历史遗留不会自动回收；本模块提供一次**显式触发**的归位动作（不是后台自动跑）。
+ *
+ * 三条纪律（逐条对应验收）：
+ *  ① **判据只有一份**：cwd 解析 / 成员判定 / attach / 复核全部由宿主注入的 seam 提供 ——
+ *     就是 t10 已落地的 `DshSessionStoreFacade.attachChildToParentWorkspace`（成员 / 血缘 / cwd 同目录三档
+ *     + 写后 `list()` 复核）。core **不 import 宿主入口**（架构守卫），也不另写第二套 attach：
+ *     第二套判据迟早与第一套漂移。
+ *  ② **只读盘点 + 逐个归位 + 逐个复核**，逐条回执（attached / already / refused + **具体**理由）；
+ *     任何一条失败都不静默 —— 异常也收成一条 refused（reason=`unexpected-error`）。
+ *  ③ **绝不猜、绝不删、绝不动会话日志字节**：本模块自己不碰文件系统（IO 全在 seam 里），
+ *     候选只认「有 `parentSession` 的子会话」；能不能归位由 seam 按 cwd/成员事实判定。
+ *
+ * 为什么收成「一次动作」而不是后台自动跑：归位是**写**（改工作区成员），必须由用户显式触发；
+ * 而且它只影响侧栏分组观感，不该在后台悄悄改用户数据。
+ */
+/** 一个候选子会话（只读事实；cwd 不在这里 —— 它属于 seam 的判定面）。 */
+export interface ForkReconcileChild {
+    sessionId: string;
+    parentSessionId: string;
+    /**
+     * 该会话自己是不是**子代理会话**（`header.origin === 'subagent'`；宿主经
+     * `sessions.parentRelations()` 的 `SessionParentRelation.subagent` 给）。
+     *
+     * ⚠️ **它不能用来区分「回退 fork 子会话」**（t17 真机实测，务必别顺手加过滤）：
+     * 本机 887 条有父会话的子会话里 58 条是回退 fork（`isSeeded:true`），而这 58 条里
+     * **50 条同样带 `origin='subagent'`**（DSH 的 fork 就是用 `agents.create` 造的，标记就是 subagent）。
+     * 所以「跳过 subagent」会把**目标本身**（50/58）一起跳掉 ⇒ 该口径默认**关闭**，
+     * 只在调用方显式传 {@link ForkReconcileOptions.skipSubagentSessions} 时才生效。
+     */
+    subagent?: boolean;
+}
+/** 归位动作的可选口径（默认 = 合同字面：**全部**有父会话的子会话）。 */
+export interface ForkReconcileOptions {
+    /**
+     * 跳过 `origin='subagent'` 的子会话（默认 false）。
+     *
+     * 为什么默认**关**：真机上 50/58 条回退 fork 自己就带这个标记（见 {@link ForkReconcileChild.subagent}），
+     * 开了它等于把要修的东西跳掉。给这个开关只为让「窄化」这一选择可被显式表达与复核，
+     * 不是默认行为。跳过条数一律记进 {@link ForkReconcileResult.skipped}（不静默）。
+     */
+    skipSubagentSessions?: boolean;
+}
+/** 逐条回执的状态（三态，互斥）。 */
+export type ForkReconcileStatus = 
+/** 本次真的写成功且复核通过（seam 给的 `attached`）。 */
+'attached'
+/** 已经在账内（seam 给的 `already-attached`）——**幂等：不重复写**。 */
+ | 'already'
+/** 没能归位；`reason` 是具体理由码（见 seam 的 WorkspaceAttachFailureReason 同名同义）。 */
+ | 'refused';
+/** seam 对**一条**子会话的归位结果（与 index.ts 的 `WorkspaceAttachOutcome` 同形同义）。 */
+export type ForkReconcileOutcome = {
+    ok: true;
+    status: 'attached' | 'already';
+    workspaceId?: string;
+} | {
+    ok: false;
+    reason: string;
+    detail?: string;
+};
+/** 归位动作的注入面（全部只读或由宿主实现；core 只编排）。 */
+export interface ForkReconcileDeps {
+    /**
+     * 只读：本机**有父会话的子会话**清单。宿主用 `sessions.parentRelations()`（DSH 存储列举，
+     * 解析成本在 DSH 侧已付）；**读不到必须抛错**，绝不用空表冒充「本机没有子会话」。
+     */
+    childSessions: () => Promise<readonly ForkReconcileChild[]>;
+    /** 一条子会话的归位动作（t10 的同一份实现；逐条调用，互不影响）。 */
+    reconcileOne: (child: ForkReconcileChild) => Promise<ForkReconcileOutcome>;
+    /** 逐条留痕（可选；失败必须能被日志看到）。 */
+    log?: (line: string) => void;
+}
+/** 一条回执。 */
+export interface ForkReconcileReceipt {
+    sessionId: string;
+    parentSessionId: string;
+    status: ForkReconcileStatus;
+    /** 机器码：attached/already 时是 seam 的 reason；refused 时是**具体**失败理由。 */
+    reason: string;
+    /** 归位到的工作区 id（拿不到就是 null；只作诊断，不参与判定）。 */
+    workspaceId: string | null;
+    /** 技术细节（errno / 路径 / 形状码）——不是用户文案。 */
+    detail?: string;
+}
+/** 归位动作的结果（计数恒为**精确值**；回执列表有界，截断时如实标记）。 */
+export interface ForkReconcileResult {
+    ok: boolean;
+    /** 扫描到的父子关系条数（含无父/空 id 的噪声项，只作诊断）。 */
+    scanned: number;
+    /** 真正尝试归位的候选数（有父会话的子会话，去重后）。 */
+    candidates: number;
+    attached: number;
+    already: number;
+    refused: number;
+    /** 失败理由分布（只统计 refused；键 = 理由码）。 */
+    reasonCounts: Record<string, number>;
+    /**
+     * **有意跳过**的条数（不是失败，也不是静默丢弃）：只统计「显式窄化」跳过的子代理会话。
+     * 默认口径（{@link ForkReconcileOptions.skipSubagentSessions} 未开）下恒为 0。
+     */
+    skipped: {
+        subagent: number;
+    };
+    receipts: ForkReconcileReceipt[];
+    /** 回执被上限截断（计数仍精确）。 */
+    receiptsTruncated: boolean;
+    /** 盘点阶段就失败（读不到父子关系）时的具体原因；此时 candidates=0 且**不是**「本机没有子会话」。 */
+    error?: string;
+}
+/**
+ * 回执列表上限。
+ *
+ * 为什么有界：候选是「本机全部有父会话的子会话」（真机 887 条），逐条回执全量回传会让响应体
+ * 无谓地大；计数（attached/already/refused 与理由分布）**恒为精确值**，截断只影响明细列表。
+ */
+export declare const FORK_RECONCILE_RECEIPT_LIMIT = 500;
+/**
+ * 一次历史 fork 归位：只读盘点 → 逐个归位 → 逐个复核（复核在 seam 内，写后重读 `list()`）。
+ *
+ * **顺序执行**（不并发）：归位是写动作，且逐条失败理由要能按顺序对上号；候选规模（真机数百条）
+ * 与每条的成本（一次 registry 读 + 一次 attach + 一次复核读）都不值得为并发牺牲可读性。
+ */
+export declare function reconcileForkSessions(deps: ForkReconcileDeps, options?: ForkReconcileOptions): Promise<ForkReconcileResult>;

package/lib/core/fork-reconcile.js

@@ -0,0 +1,150 @@
+/**
+ * 历史 fork 归位（t17）—— 把「有父会话、但**账内不含它**」的旧子会话收回到它该在的工作区。
+ *
+ * 背景（t10 真机复核）：本机 887 条有父会话的子会话里 58 条是回退 fork，其中能解析到已注册工作区的
+ * 是 **58/58**，但只有 3 条在账内 —— 其余全部停在侧栏「未分组」。t10 的修复只管**新建** fork，
+ * 历史遗留不会自动回收；本模块提供一次**显式触发**的归位动作（不是后台自动跑）。
+ *
+ * 三条纪律（逐条对应验收）：
+ *  ① **判据只有一份**：cwd 解析 / 成员判定 / attach / 复核全部由宿主注入的 seam 提供 ——
+ *     就是 t10 已落地的 `DshSessionStoreFacade.attachChildToParentWorkspace`（成员 / 血缘 / cwd 同目录三档
+ *     + 写后 `list()` 复核）。core **不 import 宿主入口**（架构守卫），也不另写第二套 attach：
+ *     第二套判据迟早与第一套漂移。
+ *  ② **只读盘点 + 逐个归位 + 逐个复核**，逐条回执（attached / already / refused + **具体**理由）；
+ *     任何一条失败都不静默 —— 异常也收成一条 refused（reason=`unexpected-error`）。
+ *  ③ **绝不猜、绝不删、绝不动会话日志字节**：本模块自己不碰文件系统（IO 全在 seam 里），
+ *     候选只认「有 `parentSession` 的子会话」；能不能归位由 seam 按 cwd/成员事实判定。
+ *
+ * 为什么收成「一次动作」而不是后台自动跑：归位是**写**（改工作区成员），必须由用户显式触发；
+ * 而且它只影响侧栏分组观感，不该在后台悄悄改用户数据。
+ */
+/**
+ * 回执列表上限。
+ *
+ * 为什么有界：候选是「本机全部有父会话的子会话」（真机 887 条），逐条回执全量回传会让响应体
+ * 无谓地大；计数（attached/already/refused 与理由分布）**恒为精确值**，截断只影响明细列表。
+ */
+export const FORK_RECONCILE_RECEIPT_LIMIT = 500;
+/** 一条候选 → 回执（分类只认 seam 给的事实，绝不从「看起来成功」推断）。 */
+function receiptOf(child, outcome) {
+    if (outcome.ok) {
+        return {
+            sessionId: child.sessionId,
+            parentSessionId: child.parentSessionId,
+            status: outcome.status === 'already' ? 'already' : 'attached',
+            reason: outcome.status === 'already' ? 'already-attached' : 'attached',
+            workspaceId: outcome.workspaceId ?? null,
+        };
+    }
+    const receipt = {
+        sessionId: child.sessionId,
+        parentSessionId: child.parentSessionId,
+        status: 'refused',
+        reason: outcome.reason,
+        workspaceId: null,
+    };
+    if (outcome.detail !== undefined)
+        receipt.detail = outcome.detail;
+    return receipt;
+}
+/**
+ * 一次历史 fork 归位：只读盘点 → 逐个归位 → 逐个复核（复核在 seam 内，写后重读 `list()`）。
+ *
+ * **顺序执行**（不并发）：归位是写动作，且逐条失败理由要能按顺序对上号；候选规模（真机数百条）
+ * 与每条的成本（一次 registry 读 + 一次 attach + 一次复核读）都不值得为并发牺牲可读性。
+ */
+export async function reconcileForkSessions(deps, options = {}) {
+    const empty = {
+        ok: false,
+        scanned: 0,
+        candidates: 0,
+        attached: 0,
+        already: 0,
+        refused: 0,
+        reasonCounts: {},
+        skipped: { subagent: 0 },
+        receipts: [],
+        receiptsTruncated: false,
+    };
+    let listed;
+    try {
+        listed = await deps.childSessions();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        deps.log?.('fork-reconcile: childSessions failed: ' + detail);
+        return { ...empty, error: 'child-sessions-unavailable: ' + detail };
+    }
+    // 候选 = 有父会话的子会话（去重；形状不符的噪声项只计入 scanned）
+    const candidates = [];
+    const seen = new Set();
+    let skippedSubagent = 0;
+    for (const item of listed) {
+        const sessionId = item?.sessionId;
+        const parentSessionId = item?.parentSessionId;
+        if (typeof sessionId !== 'string' || sessionId === '')
+            continue;
+        if (typeof parentSessionId !== 'string' || parentSessionId === '')
+            continue;
+        if (sessionId === parentSessionId)
+            continue;
+        if (seen.has(sessionId))
+            continue;
+        seen.add(sessionId);
+        candidates.push(item.subagent === true
+            ? { sessionId, parentSessionId, subagent: true }
+            : { sessionId, parentSessionId });
+    }
+    const attempted = options.skipSubagentSessions === true
+        ? candidates.filter((child) => child.subagent !== true)
+        : candidates;
+    skippedSubagent = candidates.length - attempted.length;
+    if (skippedSubagent > 0) {
+        deps.log?.('fork-reconcile: skipped ' + String(skippedSubagent) + ' subagent sessions (explicit narrowing)');
+    }
+    const receipts = [];
+    const reasonCounts = {};
+    let attached = 0;
+    let already = 0;
+    let refused = 0;
+    let truncated = false;
+    for (const child of attempted) {
+        let outcome;
+        try {
+            outcome = await deps.reconcileOne(child);
+        }
+        catch (error) {
+            // 一条失败绝不影响其余（逐条互不影响），且**如实记一条 refused**
+            const detail = error instanceof Error ? error.message : String(error);
+            deps.log?.('fork-reconcile: ' + child.sessionId + ' threw: ' + detail);
+            outcome = { ok: false, reason: 'unexpected-error', detail };
+        }
+        const receipt = receiptOf(child, outcome);
+        if (receipt.status === 'attached')
+            attached += 1;
+        else if (receipt.status === 'already')
+            already += 1;
+        else {
+            refused += 1;
+            reasonCounts[receipt.reason] = (reasonCounts[receipt.reason] ?? 0) + 1;
+            deps.log?.('fork-reconcile: ' + child.sessionId + ' refused: ' + receipt.reason + (receipt.detail !== undefined ? ' ' + receipt.detail : ''));
+        }
+        if (receipts.length < FORK_RECONCILE_RECEIPT_LIMIT)
+            receipts.push(receipt);
+        else
+            truncated = true;
+    }
+    return {
+        ok: true,
+        scanned: listed.length,
+        candidates: attempted.length,
+        attached,
+        already,
+        refused,
+        reasonCounts,
+        skipped: { subagent: skippedSubagent },
+        receipts,
+        receiptsTruncated: truncated,
+    };
+}
+//# sourceMappingURL=fork-reconcile.js.map