dsh-config-manager 0.1.69 → 0.1.71

package/lib/utils/session-health-scan.js

@@ -14,8 +14,48 @@
  *     所以还必须证明「收尾块之后、下一个 turn/start 之前，同一个 turn 还在继续」。
  *
  * 「绝不猜」：任何读不出的东西一律记成事实缺省（`unreadable` / 计数字段），既不当作「没问题」，
- * 也不编造具体原因。需要 DSH codec 才能判定的类（缺 message id / 悬空 tool-call / settlement
- * 非法）本轮**不产出** —— 没有真凭实据就不下结论（详见本文件末尾的说明）。
+ * 也不编造具体原因。
+ *
+ * 工具生命周期判定（T4）全部**只从行文本证明**，不引入 DSH codec：
+ *  ① 缺 message id（user/message 的 data.id、assistant/message 与 tool/result 的 data.message.id）；
+ *  ② 空 tool-call id（tool/call.callId 或 assistant/message 内容里 tool-call 块的 id）；
+ *  ③ 已关闭 step 里的悬空 tool-call —— **两种声明载体合并判定**：tool/call 行，以及只由
+ *     assistant/message 内容块（type:`tool-call`）声明、没有对应 tool/call 行的调用
+ *     （官方 ToolCallRecovery 的待恢复集合正是以 assistant 内容块为入口）；尾部仍开着的 step
+ *     是正常崩溃形状，不报；
+ *  ④ 同一步内重复通告的 tool-call id；
+ *  ⑤ tool/result 的 toolCallId 与 message.source.callId 不配对。
+ *
+ * 严重级**不是注释断言，是真 codec 实测**（2026-10-06，真机日志 + 官方读取路径；t13/t16 口径订正后）：
+ *  - v4（headerVersion === 4）：tool/result 缺 message.id / toolCallId 不配对 → decodeRow 当场拒读；
+ *    user/message 缺 data.id、assistant/message 缺 message.id、tool/call.callId 空、内容块 id 空、
+ *    **同一步重复通告同一 advertised tool call** → 被**已安装 Session 的 seed/restore 闸门**拒读。
+ *    以上一律 **unloadable**。
+ *    真机原始输出（v4 日志 + `validation:'current'` = 安装版 Session 的校验层，即上面的 ②③④）：
+ *      `finish: seed user/message at index 9 lacks an identified message`
+ *      `finish: tool call id requires a nonempty string`
+ *      `finish: assistant/message repeats advertised tool call call_00_rCbEBWsfXGrfOhog9cud3396`
+ *  - pre-v4（headerVersion < 4）：三类消息缺 id / 空 tool-call id / 重复通告同一 callId 走 v0→v1、v3→v4
+ *    迁移并被迁移器拒绝 → unloadable。
+ *  - 版本读不出：按较轻的 nextRequestFails 报，detail 记 codec-uncalibrated（不谎称已验证）。
+ *
+ * **前台管线的分层必须写准**（官方源码 `@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`），
+ * 否则容易误读成「transformed 容忍 ⇒ 也许还能打开」。官方当前代际（v4）读盘是**四层串行**的：
+ *  ① `parseHeaderRecord` 的 `sessionFormatCatalog.createRestore(parsed, { recovery:'strict',
+ *     validation:'transformed' })`：**既解首帧 header，也被 `readZstdPrefix` / `SessionLogScanner`
+ *     用来逐行 `decodeRow`** —— 也就是说 strict+transformed 同样是 v4 前台的**行解码器**，
+ *     而不是一次性的首帧校验；
+ *  ② `assertV4RowAdmission` / `assertReleasedV4Relationships`：行准入与关系（引用/工具生命周期）校验；
+ *  ③ `adoptSessionEvent`（内部如 `assertMessageEventShape`）：收编成事件时的形状校验；
+ *  ④ `Session.fromRestore(generation.meta.id, generation.events, generation.meta,
+ *     generation.inheritedEventCount, 'detached', currentSessionMessageProjections)` +
+ *     `assertCurrentAssistantStreams(generation.events)`。
+ *  **只有 ① 的 `decodeRow` / `finish` 那一层**会对「user/assistant 缺 message.id」「空 tool-call id」
+ *  放行；②③④ 任何一层都会拒整份日志 —— 用户真实撞到的是后者（上面的原始输出即来自完整前台管线）。
+ *  历史代际（version <= 3）走 `historicalSessionFormatCatalog.createRestore(header,
+ *  { recovery:'recoverable', validation:'current' })` 加同一套 v0→v1 / v3→v4 迁移器。
+ *  结论不变：本模块按**完整前台管线**定严重级（unloadable）；① 那一层的容忍不得用于降级，
+ *  也不得据此推测「也许能打开」。
  */
 import fs from 'node:fs/promises';
 import { join } from 'node:path';
@@ -35,9 +75,264 @@ export const DEFAULT_MAX_UNITS = 2000;
 function parseRow(line) {
     return parseSessionRowFacts(line);
 }
+/* ---------------- 工具生命周期：只从行文本证明的本地解析（T4） ---------------- */
+/**
+ * 只看这些行类型（其余事件不解第二次 JSON）—— `session-row-facts` 是另一任务的写作用域，
+ * 需要的新行级事实在本模块本地解析，绝不改动它。
+ */
+const LIFECYCLE_ROW_TYPES = new Set([
+    'user/message', 'assistant/message', 'tool/result', 'tool/call',
+    'step/start', 'step/end', 'turn/start', 'turn/end',
+]);
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/** 本地解析（只做生命周期判定所需的字段；JSON 解析失败 = undefined，调用方已按不可解析行计数）。 */
+function parseLifecycleRow(line, type) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const rec = asRecord(parsed);
+    if (rec === undefined)
+        return undefined;
+    const data = asRecord(rec['data']);
+    const row = { type };
+    const turn = readCount(data?.['turn']);
+    const step = readCount(data?.['step']);
+    if (turn !== undefined)
+        row.turn = turn;
+    if (step !== undefined)
+        row.step = step;
+    if (type === 'user/message') {
+        // user/message 的 data **本身即 message**，id 在 data.id
+        row.messageIdOk = isNonEmptyString(data?.['id']);
+    }
+    else if (type === 'assistant/message') {
+        const message = asRecord(data?.['message']);
+        row.messageIdOk = isNonEmptyString(message?.['id']);
+        const content = message?.['content'];
+        if (Array.isArray(content)) {
+            const ids = [];
+            for (const block of content) {
+                const blockRec = asRecord(block);
+                if (blockRec?.['type'] === 'tool-call')
+                    ids.push(blockRec['id']);
+            }
+            if (ids.length > 0)
+                row.blockIds = ids;
+        }
+    }
+    else if (type === 'tool/result') {
+        const message = asRecord(data?.['message']);
+        row.messageIdOk = isNonEmptyString(message?.['id']);
+        const sourceCallId = asRecord(message?.['source'])?.['callId'];
+        // 代际差异（真机实测）：v4 行把 toolCallId 放在 message 上（content[0] 是文本块）；
+        // v0/v3 行沿用 content[0].toolCallId（block 形状）。两处都读，取实际存在的那一个。
+        let toolCallId;
+        if (message !== undefined && Object.prototype.hasOwnProperty.call(message, 'toolCallId')) {
+            toolCallId = message['toolCallId'];
+        }
+        else {
+            const content = message?.['content'];
+            const first = Array.isArray(content) ? asRecord(content[0]) : undefined;
+            if (first !== undefined && Object.prototype.hasOwnProperty.call(first, 'toolCallId')) {
+                toolCallId = first['toolCallId'];
+            }
+        }
+        row.result = { sourceCallId, toolCallId };
+    }
+    else if (type === 'tool/call') {
+        row.rawCallId = data?.['callId'];
+    }
+    return row;
+}
+function createLifecycleScan() {
+    return {
+        facts: {
+            missingMessageId: 0,
+            missingMessageIdToolResult: 0,
+            emptyToolCallId: 0,
+            toolResultIdMismatch: 0,
+            danglingClosedStep: 0,
+            duplicateToolCallId: 0,
+        },
+        openSteps: new Set(),
+        closedSteps: new Set(),
+        calls: [],
+        queuedCalls: new Map(),
+        resultIds: new Set(),
+        declarations: new Map(),
+    };
+}
+function stepKeyOf(row) {
+    return row.turn !== undefined && row.step !== undefined ? row.turn + '/' + row.step : undefined;
+}
+function closeStep(scan, key) {
+    scan.openSteps.delete(key);
+    scan.closedSteps.add(key);
+}
+function bumpDeclaration(scan, key, callId, kind) {
+    let perStep = scan.declarations.get(key);
+    if (perStep === undefined) {
+        perStep = new Map();
+        scan.declarations.set(key, perStep);
+    }
+    const counts = perStep.get(callId) ?? { blocks: 0, rows: 0 };
+    counts[kind] += 1;
+    perStep.set(callId, counts);
+}
+/**
+ * 把一个调用放进悬空判定队列（去重）。
+ *
+ * 两种声明载体都走这里：`tool/call` 行与 `assistant/message` 内容块。健康日志里同一个 callId
+ * 两个载体都有，不去重就会把**同一次调用**数成两处悬空。
+ */
+function queueCall(scan, key, callId) {
+    let ids = scan.queuedCalls.get(key);
+    if (ids === undefined) {
+        ids = new Set();
+        scan.queuedCalls.set(key, ids);
+    }
+    if (ids.has(callId))
+        return;
+    ids.add(callId);
+    scan.calls.push({ key, callId });
+}
+/** 应用一行（顺序即日志顺序；边界按 step/start→step/end、turn/start→turn/end 收窄）。 */
+function applyLifecycleRow(scan, row) {
+    const key = stepKeyOf(row);
+    switch (row.type) {
+        case 'step/start':
+            if (key !== undefined) {
+                scan.openSteps.add(key);
+                scan.closedSteps.delete(key);
+            }
+            break;
+        case 'step/end':
+            if (key !== undefined)
+                closeStep(scan, key);
+            break;
+        case 'turn/end': {
+            // 回合已结束 → 该回合里仍开着的 step 不可能再有续写（崩溃恢复补写的 closer 也走这条边界）
+            if (row.turn === undefined)
+                break;
+            const prefix = row.turn + '/';
+            for (const open of [...scan.openSteps])
+                if (open.startsWith(prefix))
+                    closeStep(scan, open);
+            break;
+        }
+        case 'tool/call': {
+            // 空 / 非字符串 callId 只进 ②（能否配对已不可判定），不进悬空判定
+            if (!isNonEmptyString(row.rawCallId)) {
+                scan.facts.emptyToolCallId += 1;
+                break;
+            }
+            // 定位不到 step（turn/step 读不出）→ 无法证明「step 已关闭」→ 不报悬空
+            if (key !== undefined) {
+                queueCall(scan, key, row.rawCallId);
+                bumpDeclaration(scan, key, row.rawCallId, 'rows');
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    if (row.messageIdOk === false) {
+        scan.facts.missingMessageId += 1;
+        if (row.type === 'tool/result')
+            scan.facts.missingMessageIdToolResult += 1;
+    }
+    if (row.blockIds !== undefined) {
+        for (const id of row.blockIds) {
+            if (!isNonEmptyString(id)) {
+                scan.facts.emptyToolCallId += 1;
+                continue;
+            }
+            // 与 tool/call 行走**同一份** calls → 同一 closedSteps / resultIds 判定（绝不另起一套）
+            if (key !== undefined) {
+                queueCall(scan, key, id);
+                bumpDeclaration(scan, key, id, 'blocks');
+            }
+        }
+    }
+    if (row.result !== undefined) {
+        if (isNonEmptyString(row.result.sourceCallId))
+            scan.resultIds.add(row.result.sourceCallId);
+        // toolCallId 缺失 / 非字符串 / 与 source.callId 不一致 → 真 codec 直接拒读（v4 decodeRow；pre-v4 迁移同样拒）
+        if (!isNonEmptyString(row.result.toolCallId)
+            || !isNonEmptyString(row.result.sourceCallId)
+            || row.result.toolCallId !== row.result.sourceCallId) {
+            scan.facts.toolResultIdMismatch += 1;
+        }
+    }
+}
+function finalizeLifecycleScan(scan) {
+    for (const call of scan.calls) {
+        // 只报「所属 step 已经关闭」的悬空调用（无论它是由 tool/call 行还是 assistant 内容块声明）：
+        // 日志尾部还开着的 step 是正常崩溃形状（引擎的 interruptedTurnClosers 会补），报它就是误报。
+        if (scan.closedSteps.has(call.key) && !scan.resultIds.has(call.callId))
+            scan.facts.danglingClosedStep += 1;
+    }
+    let duplicate = 0;
+    for (const perStep of scan.declarations.values()) {
+        for (const counts of perStep.values())
+            if (counts.blocks >= 2 || counts.rows >= 2)
+                duplicate += 1;
+    }
+    scan.facts.duplicateToolCallId = duplicate;
+    return scan.facts;
+}
+/**
+ * 缺 message id 的严重级（t13 口径订正）。
+ *
+ * v4：安装版 Session 的 seed/restore 闸门（`Session.fromRestore`）拒读整份日志 → unloadable
+ *     （真机原始输出：`seed user/message at index 9 lacks an identified message`）；
+ * pre-v4：迁移器（v0→v1 / v3→v4）同样拒 → unloadable；
+ * 只有**版本读不出**才取较轻的 nextRequestFails 并在 detail 注明未校准。
+ * tool/result 载体与代际无关（三种口径下都拒读），单独短路。
+ */
+function missingMessageIdSeverity(facts, headerVersion) {
+    if (facts.missingMessageIdToolResult > 0)
+        return 'unloadable';
+    return headerVersion === undefined ? 'nextRequestFails' : 'unloadable';
+}
+/**
+ * 空 tool-call id 的严重级（t13 口径订正）。
+ *
+ * v4：`Session.fromRestore` 闸门拒读（原始输出：`tool call id requires a nonempty string`）→ unloadable；
+ * pre-v4：迁移器拒 → unloadable；只有版本读不出才取较轻值。
+ */
+function emptyToolCallIdSeverity(headerVersion) {
+    return headerVersion === undefined ? 'nextRequestFails' : 'unloadable';
+}
+/**
+ * 重复通告同一 advertised tool call 的严重级（t16 口径订正）。
+ *
+ * v4：`Session.fromRestore` 闸门拒读（真机原始输出：
+ *     `assistant/message repeats advertised tool call call_00_rCbEBWsfXGrfOhog9cud3396`）→ unloadable；
+ * pre-v4：v0→v1 迁移同样拒读（生态矩阵 #5909 记录同一结论）→ unloadable；
+ * 只有**版本读不出**才取较轻的 nextRequestFails 并在 detail 注明未校准。
+ */
+function duplicateToolCallIdSeverity(headerVersion) {
+    return headerVersion === undefined ? 'nextRequestFails' : 'unloadable';
+}
 /** 行档：解压各帧 → 逐行判定（只做能从字节证明的判定）。 */
 function scanRows(frames, bytes) {
     const rows = [];
+    const lifecycle = createLifecycleScan();
     let unparsable = 0;
     for (const frame of frames) {
         let text;
@@ -64,6 +359,12 @@ function scanRows(frames, bytes) {
             if (facts.turn !== undefined)
                 entry.turn = facts.turn;
             rows.push(entry);
+            const type = facts.type;
+            if (type !== undefined && LIFECYCLE_ROW_TYPES.has(type)) {
+                const lifecycleRow = parseLifecycleRow(line, type);
+                if (lifecycleRow !== undefined)
+                    applyLifecycleRow(lifecycle, lifecycleRow);
+            }
         }
     }
     // ① 字节相同且 seq 相同 → 重放族（同一 seq 被重写，重复的那份可零损失丢弃）
@@ -88,7 +389,7 @@ function scanRows(frames, bytes) {
     }
     // ③ 合成 closer 块：整块都是收尾类型且含 turn/end，且**后面还有行**（真实续写）
     const syntheticCloser = detectSyntheticCloser(rows);
-    return { unparsable, duplicateRows, seqGaps, syntheticCloser };
+    return { unparsable, duplicateRows, seqGaps, syntheticCloser, lifecycle: finalizeLifecycleScan(lifecycle) };
 }
 /** 合成 closer 块探测 —— 委托 `session-row-facts.findSyntheticCloserRun` 的唯一实现（判据见其文件头）。 */
 function detectSyntheticCloser(rows) {
@@ -172,16 +473,41 @@ async function scanUnit(sessionsDir, projectKey, sessionId, withRows) {
     const structural = picked?.structural ?? { ok: false, headerUnreadable: true };
     const rows = picked?.rows;
     // 行档结论 → 深度校验事实（**只标 verified=true 当真的逐行解析过**）
-    const deepIssueCodes = [];
+    const deepIssues = [];
     if (rows !== undefined) {
         if (rows.unparsable > 0)
-            deepIssueCodes.push({ code: 'unparsable-event', detail: String(rows.unparsable) + ' line(s)' });
+            deepIssues.push({ code: 'unparsable-event', detail: String(rows.unparsable) + ' line(s)' });
         if (rows.duplicateRows > 0)
-            deepIssueCodes.push({ code: 'replay-duplicate-rows', detail: String(rows.duplicateRows) });
+            deepIssues.push({ code: 'replay-duplicate-rows', detail: String(rows.duplicateRows) });
         if (rows.seqGaps > 0)
-            deepIssueCodes.push({ code: 'seq-gap', detail: String(rows.seqGaps) });
+            deepIssues.push({ code: 'seq-gap', detail: String(rows.seqGaps) });
         if (rows.syntheticCloser)
-            deepIssueCodes.push({ code: 'synthetic-closer' });
+            deepIssues.push({ code: 'synthetic-closer' });
+        // ---- T4：工具生命周期（只报不修；严重级 = 真 codec 实测口径，见文件头）----
+        const lifecycle = rows.lifecycle;
+        const version = header?.version;
+        if (lifecycle.missingMessageId > 0) {
+            const severity = missingMessageIdSeverity(lifecycle, version);
+            // 只有「版本读不出 → 取较轻值」需要注明未校准；v4/pre-v4 都已实测拒读。
+            const note = version === undefined ? '; codec-uncalibrated' : '';
+            deepIssues.push({ code: 'missing-message-id', severity, detail: String(lifecycle.missingMessageId) + ' row(s)' + note });
+        }
+        if (lifecycle.toolResultIdMismatch > 0) {
+            deepIssues.push({ code: 'tool-result-id-mismatch', severity: 'unloadable', detail: String(lifecycle.toolResultIdMismatch) });
+        }
+        if (lifecycle.emptyToolCallId > 0) {
+            const severity = emptyToolCallIdSeverity(version);
+            const note = version === undefined ? '; codec-uncalibrated' : '';
+            deepIssues.push({ code: 'empty-tool-call-id', severity, detail: String(lifecycle.emptyToolCallId) + note });
+        }
+        if (lifecycle.danglingClosedStep > 0) {
+            deepIssues.push({ code: 'dangling-tool-call', severity: 'unloadable', detail: String(lifecycle.danglingClosedStep) + ' unresolved' });
+        }
+        if (lifecycle.duplicateToolCallId > 0) {
+            const severity = duplicateToolCallIdSeverity(version);
+            const note = version === undefined ? '; codec-uncalibrated' : '';
+            deepIssues.push({ code: 'duplicate-tool-call-id', severity, detail: String(lifecycle.duplicateToolCallId) + note });
+        }
     }
     const input = {
         unitId: projectKey + '/' + sessionId,
@@ -195,10 +521,15 @@ async function scanUnit(sessionsDir, projectKey, sessionId, withRows) {
         ...(header?.version !== undefined ? { headerVersion: header.version } : {}),
         ...(names.length > 0 ? { sizeBytes: totalBytes } : {}),
         ...(rows !== undefined
-            ? { deep: { verified: true, ...(deepIssueCodes.length > 0 ? { issues: deepIssueCodes } : {}) } }
+            ? { deep: { verified: true, ...(deepIssues.length > 0 ? { issues: deepIssues } : {}) } }
             : { deep: { verified: false, unverifiedReason: 'row-scan-not-run' } }),
     };
-    return { input, unreadable };
+    // 首帧 header 的 id 是这一条会话的**真身份**（目录名可能是 `session-<uuid>`，也可能被手工改过）；
+    // 采集器自证时优先用它，取不到才回落到目录名。
+    const out = { input, unreadable };
+    if (header?.id !== undefined)
+        out.headerSessionId = header.id;
+    return out;
 }
 /**
  * 扫描本机会话库（只读；**绝不写任何字节**，绝不抛错）。
@@ -236,6 +567,22 @@ export async function scanSessionHealth(options) {
     const projectKeys = projectDirs.filter((name) => PROJECT_KEY_RE.test(name));
     const inputs = [];
     const duplicates = new Set();
+    /**
+     * **采集器自证**用的已知会话 id 集合（调用方不提供 `knownSessionIds` 时用它）。
+     *
+     * 为什么需要：调用方（CLI / 救急台）不提供 `knownSessionIds` 时，旧实现用 `?? new Set()`
+     * 把「未知」伪造成「确知为空集」，于是「父对话存在性」判据对**每一条**子代理会话都成立 ——
+     * 真机实测 1199 条里 800 条被误报 `subagent-without-parent`（bySeverity.invisible=800）。
+     *
+     * **真实覆盖（两个来源，边界不同，别读成「一律含全部单元」）**：
+     *  · **目录名**（第一趟，`sessionIdKey(sessionId)`）：覆盖本机**全部**单元目录，不受 `maxUnits` 约束 ——
+     *    这是集合的主干，DSH 的目录名就是会话 id（`session-<uuid>` 与裸 `<uuid>` 由 `sessionIdKey` 归一）；
+     *  · **首帧 header.id**：只在**被扫到**的单元上补（`scanned < maxUnits` 的循环里）—— 它只多给出
+     *    「目录名被手工改过、header id 才是真身份」这种窄情况，**不覆盖**超出限额而未扫的单元。
+     * 两个来源都只**加**不进「未知」：集合越全 ⇒ 越少报「缺父」，所以这个窄边界只会让**超限那批单元**
+     * 的父对话在极端情形下被多报一次（保守方向），绝不会把「确知为空集」重新伪造成未知。
+     */
+    const knownIdsFromTraversal = new Set();
     // 第一趟：只数「同一会话 id 出现在几个 projectKey 目录」（重复 id 是启动级故障）
     const idLocations = new Map();
     for (const projectKey of projectKeys) {
@@ -250,6 +597,7 @@ export async function scanSessionHealth(options) {
         }
         for (const sessionId of dirs) {
             const key = sessionIdKey(sessionId);
+            knownIdsFromTraversal.add(key);
             const set = idLocations.get(key) ?? new Set();
             set.add(projectKey);
             idLocations.set(key, set);
@@ -302,14 +650,23 @@ export async function scanSessionHealth(options) {
         const withRows = deepLimit > 0 && deepUsed < deepLimit;
         if (withRows)
             deepUsed += 1;
-        const { input, unreadable } = await scanUnit(sessionsDir, unit.projectKey, unit.sessionId, withRows);
+        const { input, unreadable, headerSessionId } = await scanUnit(sessionsDir, unit.projectKey, unit.sessionId, withRows);
         result.unreadableEntries += unreadable;
+        // 补一个 header.id 的归一键（只覆盖**被扫到**的单元，见 knownIdsFromTraversal 的覆盖说明）：
+        // 目录名被手工改过时，header id 才是这条会话的真身份；取不到 header 就不补，绝不用目录名冒充。
+        if (headerSessionId !== undefined)
+            knownIdsFromTraversal.add(sessionIdKey(headerSessionId));
         inputs.push(input);
     }
     const analyzed = analyzeSessionHealth(inputs, {
         ...(options.targetFormatVersion !== undefined ? { targetFormatVersion: options.targetFormatVersion } : {}),
+        // workspaceKeys 维持「size > 0 才判未登记」：调用方读不到注册表与「注册表为空」不可区分，
+        // 把空集当确知会让每一条会话都报未登记（另一种误报）。这一点与 knownSessionIds 不同 —— 那里
+        // 「未知」由调用方用 undefined 显式表达。
         workspaceKeys: options.workspaceKeys ?? new Set(),
-        knownSessionIds: options.knownSessionIds ?? new Set(),
+        // 「未知」绝不伪造成「确知为空集」：调用方提供了就用它的（UI 的 parentRelations 更权威）；
+        // 没提供 → 用本次遍历到的全部单元 id 自证。
+        knownSessionIds: options.knownSessionIds ?? knownIdsFromTraversal,
         duplicateSessionIds: options.duplicateSessionIds ?? duplicates,
     });
     result.rows = analyzed.rows;

package/lib/utils/session-layout-repair-service.d.ts

@@ -0,0 +1,98 @@
+import type { SessionRepairActionKind, SessionRepairReason, SessionRepairSummary } from '../core/session-repair.ts';
+import type { PathMappingRule } from '../core/path-mapping.ts';
+/** 计划里的一个动作（**不含绝对路径**：身份用 `<fromProjectKey>/<sessionId>`）。 */
+export interface SessionLayoutPlanItem {
+    unitId: string;
+    sessionId: string;
+    kind: SessionRepairActionKind;
+    fromProjectKey: string;
+    toProjectKey?: string;
+    /** 需要改写首帧 cwd（面板入口不支持映射 ⇒ 恒缺席；字段与 core 同形，留给以后） */
+    rewrite?: {
+        from: string;
+        to: string;
+    };
+    reason: SessionRepairReason;
+    /** 是否真的落盘（false = 只报告：缺 cwd / 加锁 / 未点名 keep 的重复项） */
+    applies: boolean;
+}
+export interface SessionLayoutPlan {
+    ok: boolean;
+    /** 只读计划：`POST /sessions/layout` 在 apply!==true 时只调这里，**零写入** */
+    readOnly: true;
+    /** 会话根读不出来（机器码；不含绝对路径） */
+    reason?: 'sessions-root-unreadable';
+    summary: SessionRepairSummary;
+    actions: SessionLayoutPlanItem[];
+    /** 与 core `sessionRepairNeedsAttention` 同源；另把「keep 被拒」也算作需要介入 */
+    needsAttention: boolean;
+    /** 有重复 id 但调用方未点名（或 keep 指向非候选副本）的 sessionId —— 面板据此要求用户选保留哪一份 */
+    needsKeep: string[];
+}
+/** 逐条失败/拒绝的机器可读原因。 */
+export type SessionLayoutApplyReason = 'locked' | 'busy' | 'no-cwd' | 'inconsistent-generations' | 'missing-keep' | 'keep-not-a-candidate' | 'target-exists' | 'quarantine-exists' | 'rewrite-failed' | 'missing-target-key' | 'move-failed' | 'reindex-failed' | 'not-found' | 'io-error';
+export interface SessionLayoutApplyItem {
+    unitId: string;
+    sessionId: string;
+    action: SessionRepairActionKind;
+    ok: boolean;
+    reason?: SessionLayoutApplyReason;
+    /** 隔离去向（**相对 `<home>/sessions`**；不含绝对路径） */
+    quarantineDir?: string;
+    /** 归位后的新身份 `<toProjectKey>/<sessionId>` */
+    movedUnitId?: string;
+    /** 失败后是否已成功回滚（回到原状态） */
+    rolledBack?: boolean;
+    /** 该条需要用户介入（被门拒绝 / 无法判定 / 失败） */
+    needsAttention?: boolean;
+}
+export interface SessionLayoutApplyResult {
+    ok: boolean;
+    applied: number;
+    failed: number;
+    skipped: number;
+    results: SessionLayoutApplyItem[];
+    /** 整体未执行的机器码（没有刷新端口 / 会话根读不出来） */
+    reason?: 'reindex-unavailable' | 'sessions-root-unreadable';
+}
+export interface SessionLayoutPlanOptions {
+    homeDir: string;
+    /** sessionId → 要保留的副本 unitId（`<projectKey>/<sessionId>`）；缺 = 该 id 的重复项一律拒绝执行 */
+    keep?: Record<string, string>;
+    /**
+     * 可选路径映射（CLI `--map` 语义，逐条交给 core 规划器）。**面板入口暂不暴露** ⇒ 缺省无映射、
+     * `rewrite` 恒缺席（响应因此不含任何绝对路径）；留给以后需要「跨机重定基后归位」的调用方。
+     */
+    mappings?: readonly PathMappingRule[];
+}
+export interface SessionLayoutApplyOptions extends SessionLayoutPlanOptions {
+    /** 只处理这些 unitId（缺省 = 计划里全部可执行项） */
+    unitIds?: readonly string[];
+    /**
+     * 宿主注入的索引刷新（`SessionStoreFacade.reindexSessionHeader`）。
+     * **缺省 = 一条也不执行**（如实拒绝：没有刷新能力就不动盘，否则运行中的 DSH 会看到错位状态）。
+     */
+    reindex?: (sessionId: string) => Promise<boolean>;
+    /** 注入当前时间（静止期判定；测试固定用） */
+    now?: () => Date;
+    /** 测试注入隔离目录时间戳；缺省 = ISO 时间戳（与 CLI 同形：`:`/`.` 换成 `-`） */
+    stamp?: string;
+    /**
+     * 改写原语（缺省 = `utils/session-log.ts` 的 `rewriteSessionLogDir`）。
+     * 只为**故障注入测试**存在（「改写失败 → 不搬目录 / 回滚」这条路径否则无法覆盖）。
+     */
+    rewriteDir?: (dir: string, newCwd: string) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+/** 计划视图（剥离绝对路径）：`POST /sessions/layout` 的 `apply!==true` 分支只调它。 */
+export declare function planSessionLayoutRepair(options: SessionLayoutPlanOptions): Promise<SessionLayoutPlan>;
+/**
+ * 应用（逐条执行；失败逐条回滚）。
+ *
+ * 计数口径（与 CLI 的退出码同源）：`applied` = 真的写成/搬动的条数；`failed` = 被门拒绝 / 被护栏拒绝 /
+ * 写失败（含回滚）的条数；`skipped` = 规划器判定「只报告」的条数（缺 cwd / 加锁 / 多 generation 不一致）。
+ * `ok = failed === 0`。
+ */
+export declare function applySessionLayoutRepair(options: SessionLayoutApplyOptions): Promise<SessionLayoutApplyResult>;