dsh-config-manager 0.1.69 → 0.1.71

package/lib/utils/session-layout-repair-service.js

@@ -0,0 +1,457 @@
+/**
+ * 面板侧「布局归位 / 重复 id 隔离」写入口（宿主服务，E1）。
+ *
+ * 为什么需要：`location-mismatch` / `duplicate-id` 是**最严重**的一档（DSH 会直接拒绝启动：
+ * `corrupt session log` / `duplicate JSONL session id`），而在此之前只有离线 CLI
+ * `dcm sessions repair --fix` 与离线救急台能做 —— 面板只能检出、没有修复入口。
+ *
+ * ── 复用纪律（不得重写，这是本模块的全部价值）────────────────────────────────
+ *  · 规划器 = `core/session-repair.ts` 的 `planSessionRepair`（动作种类 / 摘要 / `applies` / `reason` 逐条照用）；
+ *  · 写入原语 = `utils/session-log.ts` 的 `rewriteSessionLogDir` / `readLogFileCwd` / `PROJECT_KEY_RE`
+ *    / `sessionLogNames`（宿主适配器与 CLI 的唯一实现）；
+ *  · 语义与 CLI `runSessionsRepair`（src/cli/sessions-repair.ts）逐条一致：quarantine 目标
+ *    `<home>/sessions/.cm-repair-quarantine-<stamp>/<fromProjectKey>/<sessionId>`、`keep` 语义、
+ *    「改写失败就不搬目录」、失败逐条计数并**回滚**（改写回原值 + 搬回原位）；
+ *  · **本模块禁止 import src/cli/**（CLI 是离线通道，宿主侧不复用它的 IO 与文案）。
+ *
+ * ── 安全模型（与 CLI 的差异必须写清，不许让用户以为两者相同）──────────────────
+ *  CLI 要求「**DSH 已停止**」；面板**不可能**满足（面板就跑在 DSH 里）。因此面板入口采用与
+ * 「应用内字节级修复」（`utils/session-repair-service.ts`）**同一套门模型**：
+ *  ① 路由层过 SAFE MODE + mutation lock（与导入/恢复互斥）；
+ *  ② **逐目标**前置：unit 目录内无 `session.lock`、日志不在 30s 静止期内（同一常量
+ *     `SESSION_REPAIR_QUIESCENT_MS`，与字节级门同口径）；
+ *  ③ 每次移动/改写后**必须** `reindexSessionHeader` 成功（否则运行中的 DSH 看到陈旧/错位状态，
+ *     历史事故就是 `corrupt session log` / 同 id 出现在两个 projectKey）；
+ *  ④ 刷新失败 / 搬不动 / 目标已存在 → **该条回滚**并如实汇报（绝不静默成功）。
+ *  依据：导入链（`SessionsAdapter.finalizeApply`）本来就在 DSH 运行时做同类「改写首帧 + 归位 + 刷新」操作。
+ *
+ * ── 面板侧额外护栏（合法输入下仍与 CLI 逐字等价）────────────────────────────
+ *  · 重复 id 的 `keep` 必须由调用方**显式给出**，且必须指向该 id 的**已扫描副本**之一；
+ *    否则该 id 一律拒绝执行（CLI 里 `--keep` 指错路径会把**所有**副本都隔离 —— 面板不能继承这个脚坑）；
+ *  · 被 `keep` 点名保留的那一份本轮**不动**（core 的语义：只报 `keep`，与 CLI 同）；
+ *  · 入口不支持路径映射（CLI 的 `--map` 仍可用）⇒ `rewrite` 恒缺席，响应不含任何绝对路径；
+ *    `quarantineDir` / `movedUnitId` 都是**相对**身份（相对 `<home>/sessions`）。
+ */
+import fs from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { planSessionRepair, sessionRepairNeedsAttention } from '../core/session-repair.js';
+import { PROJECT_KEY_RE, readLogFileCwd, rewriteSessionLogDir, sessionLogNames } from './session-log.js';
+import { SESSION_REPAIR_QUIESCENT_MS } from './session-repair-service.js';
+/* --------------------------------------------------------------- 只读扫描 */
+async function exists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 扫描 `<home>/sessions`：projectKey 段 → 会话目录 → 首帧 cwd（与 CLI `scanSessions` 同款判据）。 */
+async function scanSessions(sessionsRoot) {
+    const out = [];
+    let projectDirs;
+    try {
+        projectDirs = await fs.readdir(sessionsRoot, { withFileTypes: true });
+    }
+    catch {
+        // 读不出来（不存在 / 不是目录 / EACCES）→ 调用方按「无法判定」处理，绝不猜
+        return undefined;
+    }
+    for (const entry of projectDirs) {
+        if (!entry.isDirectory())
+            continue;
+        const projectKey = entry.name;
+        if (!PROJECT_KEY_RE.test(projectKey))
+            continue; // 隔离目录等非 projectKey 形状一律跳过
+        const projectDir = join(sessionsRoot, projectKey);
+        let sessionDirs;
+        try {
+            sessionDirs = await fs.readdir(projectDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const sessionEntry of sessionDirs) {
+            if (!sessionEntry.isDirectory())
+                continue;
+            const dir = join(projectDir, sessionEntry.name);
+            let names;
+            try {
+                names = sessionLogNames(await fs.readdir(dir));
+            }
+            catch {
+                continue;
+            }
+            if (names.length === 0)
+                continue;
+            const cwds = [];
+            for (const name of names) {
+                const cwd = await readLogFileCwd(join(dir, name));
+                if (cwd !== undefined && !cwds.includes(cwd))
+                    cwds.push(cwd);
+            }
+            const locked = await exists(join(dir, 'session.lock'));
+            out.push({
+                sessionId: sessionEntry.name,
+                fromProjectKey: projectKey,
+                dir,
+                ...(cwds.length > 0 ? { cwd: cwds[0] } : {}),
+                consistent: cwds.length <= 1,
+                ...(locked ? { locked: true } : {}),
+            });
+        }
+    }
+    return out;
+}
+function zeroSummary() {
+    return { scanned: 0, ok: 0, move: 0, rewriteMove: 0, skip: 0, keep: 0, quarantine: 0, duplicates: 0 };
+}
+function mergeSummary(into, from) {
+    into.scanned += from.scanned;
+    into.ok += from.ok;
+    into.move += from.move;
+    into.rewriteMove += from.rewriteMove;
+    into.skip += from.skip;
+    into.keep += from.keep;
+    into.quarantine += from.quarantine;
+    into.duplicates += from.duplicates;
+}
+/** `<projectKey>/<sessionId>` → 绝对目录；形状不合法 / 越界 → undefined（绝不拼出会话根之外的路径）。 */
+function unitIdToDir(sessionsRoot, unitId) {
+    const at = unitId.indexOf('/');
+    if (at <= 0 || at === unitId.length - 1)
+        return undefined;
+    const projectKey = unitId.slice(0, at);
+    const sessionId = unitId.slice(at + 1);
+    if (!PROJECT_KEY_RE.test(projectKey))
+        return undefined;
+    if (sessionId.includes('/') || sessionId.includes(String.fromCharCode(92)))
+        return undefined;
+    if (sessionId === '.' || sessionId === '..')
+        return undefined;
+    return join(sessionsRoot, projectKey, sessionId);
+}
+const EMPTY_INTERNAL = {
+    ok: false,
+    reason: 'sessions-root-unreadable',
+    summary: zeroSummary(),
+    actions: [],
+    duplicateIds: new Set(),
+    keptIds: new Set(),
+    keepRejected: new Map(),
+};
+/** 解析 keep（sessionId → 要保留的副本）→ 绝对目录；指向非候选副本的一律拒绝。 */
+function resolveKeeps(sessionsRoot, scanned, keep) {
+    const keepDirs = new Map();
+    if (keep === undefined)
+        return keepDirs;
+    const candidatesById = new Map();
+    for (const session of scanned) {
+        const set = candidatesById.get(session.sessionId) ?? new Set();
+        set.add(session.dir);
+        candidatesById.set(session.sessionId, set);
+    }
+    for (const [sessionId, unitId] of Object.entries(keep)) {
+        const dir = unitIdToDir(sessionsRoot, unitId);
+        if (dir === undefined)
+            continue;
+        const candidates = candidatesById.get(sessionId);
+        // keep 指错位置：CLI 会把**所有**副本都隔离；面板侧宁可不动（该 id 在视图里进 needsKeep）
+        if (candidates === undefined || !candidates.has(dir))
+            continue;
+        keepDirs.set(sessionId, dir);
+    }
+    return keepDirs;
+}
+/**
+ * 规划（**只读**，零写入）：扫描 + `planSessionRepair`。
+ *
+ * 关于 keep 的多条：core 的 `options.keep` 是**单值**（CLI `--keep <dir>` 语义），面板可能同时处理
+ * 多个重复 id ⇒ 按 sessionId 分组调用（有 keep 的组单独规划），再合并 actions/summary
+ * （计数可加；每个重复组只计一次 duplicates，与单趟等价），最后按扫描顺序稳定排序。
+ */
+async function planInternal(options) {
+    const sessionsRoot = join(options.homeDir, 'sessions');
+    const scanned = await scanSessions(sessionsRoot);
+    if (scanned === undefined)
+        return EMPTY_INTERNAL;
+    const keepDirs = resolveKeeps(sessionsRoot, scanned, options.keep);
+    const order = new Map();
+    scanned.forEach((session, index) => { if (!order.has(session.dir))
+        order.set(session.dir, index); });
+    const groups = new Map();
+    for (const session of scanned) {
+        const list = groups.get(session.sessionId);
+        if (list === undefined)
+            groups.set(session.sessionId, [session]);
+        else
+            list.push(session);
+    }
+    const duplicateIds = new Set();
+    for (const [sessionId, list] of groups) {
+        if (list.length > 1)
+            duplicateIds.add(sessionId);
+    }
+    const merged = { actions: [], summary: zeroSummary() };
+    const handled = new Set();
+    const keptIds = new Set();
+    for (const [sessionId, list] of groups) {
+        if (!duplicateIds.has(sessionId))
+            continue;
+        const keepDir = keepDirs.get(sessionId);
+        if (keepDir === undefined)
+            continue; // 未点名 keep：并入主规划（quarantine 项 applies:false）
+        const sub = planSessionRepair(list, { keep: keepDir, ...(options.mappings !== undefined ? { mappings: options.mappings } : {}) });
+        mergeSummary(merged.summary, sub.summary);
+        merged.actions.push(...sub.actions);
+        handled.add(sessionId);
+        keptIds.add(sessionId);
+    }
+    const rest = scanned.filter((session) => !handled.has(session.sessionId));
+    const main = planSessionRepair(rest, options.mappings !== undefined ? { mappings: options.mappings } : {});
+    mergeSummary(merged.summary, main.summary);
+    merged.actions.push(...main.actions);
+    merged.actions.sort((a, b) => (order.get(a.dir) ?? 0) - (order.get(b.dir) ?? 0));
+    // keep 被拒（指向非候选副本 / 形状非法）且该 id 确实有重复 → 该 id 拒绝执行并说明
+    const keepRejected = new Map();
+    if (options.keep !== undefined) {
+        for (const sessionId of Object.keys(options.keep)) {
+            if (!duplicateIds.has(sessionId) || keptIds.has(sessionId))
+                continue;
+            keepRejected.set(sessionId, 'keep-not-a-candidate');
+        }
+    }
+    return { ok: true, summary: merged.summary, actions: merged.actions, duplicateIds, keptIds, keepRejected };
+}
+/** 计划视图（剥离绝对路径）：`POST /sessions/layout` 的 `apply!==true` 分支只调它。 */
+export async function planSessionLayoutRepair(options) {
+    const internal = await planInternal(options);
+    if (!internal.ok) {
+        return { ok: false, readOnly: true, reason: 'sessions-root-unreadable', summary: internal.summary, actions: [], needsAttention: false, needsKeep: [] };
+    }
+    const actions = internal.actions.map((action) => ({
+        unitId: action.fromProjectKey + '/' + action.sessionId,
+        sessionId: action.sessionId,
+        kind: action.kind,
+        fromProjectKey: action.fromProjectKey,
+        ...(action.toProjectKey !== undefined ? { toProjectKey: action.toProjectKey } : {}),
+        ...(action.rewrite !== undefined ? { rewrite: { from: action.rewrite.from, to: action.rewrite.to } } : {}),
+        reason: action.reason,
+        applies: action.applies,
+    }));
+    const needsKeep = [...internal.duplicateIds]
+        .filter((sessionId) => !internal.keptIds.has(sessionId))
+        .sort();
+    const plan = { actions: internal.actions, summary: internal.summary };
+    return {
+        ok: true,
+        readOnly: true,
+        summary: internal.summary,
+        actions,
+        needsAttention: sessionRepairNeedsAttention(plan) || internal.keepRejected.size > 0,
+        needsKeep,
+    };
+}
+/* ------------------------------------------------------------------- 应用 */
+function defaultStamp() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+/** 逐目标前置门（与字节级门同一口径）：目录无 session.lock + 日志不在静止期内。 */
+async function gateForTarget(dir, nowMs) {
+    if (await exists(join(dir, 'session.lock')))
+        return 'locked';
+    let names;
+    try {
+        names = sessionLogNames(await fs.readdir(dir));
+    }
+    catch {
+        return 'not-found';
+    }
+    let newest;
+    for (const name of names) {
+        try {
+            const st = await fs.stat(join(dir, name));
+            if (!st.isFile())
+                continue;
+            if (newest === undefined || st.mtimeMs > newest)
+                newest = st.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (newest === undefined)
+        return 'not-found';
+    if (nowMs - newest < SESSION_REPAIR_QUIESCENT_MS)
+        return 'busy';
+    return 'ok';
+}
+/** 尽力搬回（回滚用）；原位置空出来才算成功。 */
+async function moveIfPossible(from, to) {
+    try {
+        if (!(await exists(from)) || await exists(to))
+            return false;
+        await fs.mkdir(dirname(to), { recursive: true });
+        await fs.rename(from, to);
+        return (await exists(to)) && !(await exists(from));
+    }
+    catch {
+        return false;
+    }
+}
+function itemOf(action) {
+    return { unitId: action.fromProjectKey + '/' + action.sessionId, sessionId: action.sessionId, action: action.kind, ok: false };
+}
+async function quarantineOne(action, sessionsRoot, stamp, nowMs, reindex) {
+    const item = itemOf(action);
+    const gate = await gateForTarget(action.dir, nowMs);
+    if (gate !== 'ok')
+        return { ...item, reason: gate, needsAttention: true };
+    const rel = '.cm-repair-quarantine-' + stamp + '/' + action.fromProjectKey + '/' + action.sessionId;
+    const target = join(sessionsRoot, '.cm-repair-quarantine-' + stamp, action.fromProjectKey, action.sessionId);
+    try {
+        if (await exists(target))
+            return { ...item, reason: 'quarantine-exists', needsAttention: true };
+        await fs.mkdir(dirname(target), { recursive: true });
+        await fs.rename(action.dir, target);
+        if (!(await exists(target)) || await exists(action.dir)) {
+            const back = await moveIfPossible(target, action.dir);
+            return { ...item, reason: 'move-failed', rolledBack: back, needsAttention: true };
+        }
+        const refreshed = await reindex(action.sessionId).catch(() => false);
+        if (!refreshed) {
+            const back = await moveIfPossible(target, action.dir);
+            return { ...item, reason: 'reindex-failed', rolledBack: back, needsAttention: true };
+        }
+        return { ...item, ok: true, quarantineDir: rel };
+    }
+    catch {
+        const back = await moveIfPossible(target, action.dir);
+        return { ...item, reason: 'io-error', ...(back ? { rolledBack: true } : {}), needsAttention: true };
+    }
+}
+async function moveOne(action, sessionsRoot, nowMs, reindex, rewriteDir) {
+    const item = itemOf(action);
+    const gate = await gateForTarget(action.dir, nowMs);
+    if (gate !== 'ok')
+        return { ...item, reason: gate, needsAttention: true };
+    let rewritten = false;
+    const rollbackRewrite = async () => {
+        if (!rewritten || action.rewrite === undefined)
+            return true;
+        const back = await rewriteDir(action.dir, action.rewrite.from);
+        return back.ok;
+    };
+    if (action.rewrite !== undefined) {
+        const r = await rewriteDir(action.dir, action.rewrite.to);
+        if (!r.ok)
+            return { ...item, reason: 'rewrite-failed', needsAttention: true };
+        rewritten = true;
+    }
+    if (action.toProjectKey === undefined) {
+        const back = await rollbackRewrite();
+        return { ...item, reason: 'missing-target-key', ...(rewritten ? { rolledBack: back } : {}), needsAttention: true };
+    }
+    const targetDir = join(sessionsRoot, action.toProjectKey, action.sessionId);
+    try {
+        if (await exists(targetDir)) {
+            const back = await rollbackRewrite();
+            return { ...item, reason: 'target-exists', ...(rewritten ? { rolledBack: back } : {}), needsAttention: true };
+        }
+        await fs.mkdir(dirname(targetDir), { recursive: true });
+        await fs.rename(action.dir, targetDir);
+        if (!(await exists(targetDir)) || await exists(action.dir)) {
+            const backMove = await moveIfPossible(targetDir, action.dir);
+            const backRewrite = await rollbackRewrite();
+            return { ...item, reason: 'move-failed', rolledBack: backMove && backRewrite, needsAttention: true };
+        }
+        const refreshed = await reindex(action.sessionId).catch(() => false);
+        if (!refreshed) {
+            const backMove = await moveIfPossible(targetDir, action.dir);
+            const backRewrite = await rollbackRewrite();
+            return { ...item, reason: 'reindex-failed', rolledBack: backMove && backRewrite, needsAttention: true };
+        }
+        return { ...item, ok: true, movedUnitId: action.toProjectKey + '/' + action.sessionId };
+    }
+    catch {
+        const backMove = await moveIfPossible(targetDir, action.dir);
+        const backRewrite = await rollbackRewrite();
+        return { ...item, reason: 'io-error', rolledBack: backMove && backRewrite, needsAttention: true };
+    }
+}
+/**
+ * 应用（逐条执行；失败逐条回滚）。
+ *
+ * 计数口径（与 CLI 的退出码同源）：`applied` = 真的写成/搬动的条数；`failed` = 被门拒绝 / 被护栏拒绝 /
+ * 写失败（含回滚）的条数；`skipped` = 规划器判定「只报告」的条数（缺 cwd / 加锁 / 多 generation 不一致）。
+ * `ok = failed === 0`。
+ */
+export async function applySessionLayoutRepair(options) {
+    if (options.reindex === undefined) {
+        // 没有刷新能力就不动盘：宁可如实拒绝，也不让运行中的 DSH 看到错位状态
+        return { ok: false, applied: 0, failed: 0, skipped: 0, results: [], reason: 'reindex-unavailable' };
+    }
+    const reindex = options.reindex;
+    const internal = await planInternal(options);
+    if (!internal.ok)
+        return { ok: false, applied: 0, failed: 0, skipped: 0, results: [], reason: 'sessions-root-unreadable' };
+    const sessionsRoot = join(options.homeDir, 'sessions');
+    const wanted = options.unitIds !== undefined ? new Set(options.unitIds) : undefined;
+    const nowMs = (options.now ?? (() => new Date()))().getTime();
+    const stamp = options.stamp ?? defaultStamp();
+    const results = [];
+    let applied = 0;
+    let failed = 0;
+    let skipped = 0;
+    // keep 被拒（指向非候选副本）且该 id 有重复：补一条**显式拒绝**（core 不知道 keep 解析失败），绝不静默
+    for (const [sessionId, reason] of internal.keepRejected) {
+        const requested = options.keep?.[sessionId];
+        results.push({
+            unitId: requested !== undefined ? requested : sessionId,
+            sessionId,
+            action: 'quarantine',
+            ok: false,
+            reason,
+            needsAttention: true,
+        });
+        failed += 1;
+    }
+    for (const action of internal.actions) {
+        const unitId = action.fromProjectKey + '/' + action.sessionId;
+        if (action.kind === 'ok' || action.kind === 'keep')
+            continue;
+        if (wanted !== undefined && !wanted.has(unitId))
+            continue;
+        if (action.kind === 'skip') {
+            const item = itemOf(action);
+            results.push({ ...item, reason: action.reason, needsAttention: true });
+            skipped += 1;
+            continue;
+        }
+        if (action.kind === 'quarantine') {
+            if (!action.applies) {
+                // 重复 id 未点名 keep（或 keep 指向非候选副本）：**拒绝执行并说明**（CLI 只是跳过它）
+                const item = itemOf(action);
+                results.push({ ...item, reason: 'missing-keep', needsAttention: true });
+                failed += 1;
+                continue;
+            }
+            const done = await quarantineOne(action, sessionsRoot, stamp, nowMs, reindex);
+            results.push(done);
+            if (done.ok)
+                applied += 1;
+            else
+                failed += 1;
+            continue;
+        }
+        const done = await moveOne(action, sessionsRoot, nowMs, reindex, options.rewriteDir ?? rewriteSessionLogDir);
+        results.push(done);
+        if (done.ok)
+            applied += 1;
+        else
+            failed += 1;
+    }
+    return { ok: failed === 0, applied, failed, skipped, results };
+}
+//# sourceMappingURL=session-layout-repair-service.js.map

package/lib/utils/session-log-repair.d.ts

@@ -12,6 +12,10 @@ export type SessionRepairFailure =
  | 'invalid-header'
 /** 没有发现任何可零损失修复的问题 */
  | 'nothing-to-fix'
+/** 行跨度**不可判定**（packed 行形状不合法 / 无 seq 且非 packed 行）—— refuse 而不是猜 */
+ | 'undecidable'
+/** 引用完整性：本次动作会让保留行引用到的 seq 失去承载行或被改指（fail-closed） */
+ | 'dropped-ref'
 /** 只有有损修复可用（截断），但调用方没有显式放行 */
  | 'lossy-required'
 /** 写前校验不过（**拒绝修复**） */
@@ -50,6 +54,8 @@ export interface SessionLogRepairOutcome {
     actions?: SessionRepairAction[];
     /** 计划里有有损动作（应用期必须显式 allowLossy） */
     lossy?: boolean;
+    /** 可见告警（例如先前就存在的悬空引用）——**不影响 ok**，只是让调用方如实汇报 */
+    warnings?: string[];
 }
 /**
  * 写前校验：**连续性 + 引用完整性**（设计稿 §10.3 第 1 条）—— 严格档，用作**写后复验**。
@@ -88,10 +94,31 @@ export interface SessionLogRepairPlan {
     headerText?: string;
     droppedRows?: number;
     keptRows?: number;
+    /** 可见告警（先前就存在的悬空引用等）—— 不影响 ok */
+    warnings?: string[];
+    /** 帧级最小写计划（ok=true 才有）—— 未触及帧按原字节区间逐字节复用 */
+    frames?: SessionRepairFramePlan[];
+}
+/**
+ * 一帧的写入计划（**帧级最小写**）。
+ *
+ * header 帧永不重写；未被本次改动触及（帧内无被丢弃行）的帧 `reuse=true`，调用方直接拷贝
+ * 原容器里的 `[start, end)` 字节；其余帧用 `chunks`（每项 ≤ SESSION_REPAIR_MAX_ROWS_PER_FRAME 行）重编码。
+ */
+export interface SessionRepairFramePlan {
+    /** 原容器内的帧字节区间（半开）；reuse=true 时逐字节拷贝这段 */
+    start: number;
+    end: number;
+    /** true = 逐字节复用原帧字节；false = 用 chunks 重新编码 */
+    reuse: boolean;
+    /** reuse=false 时：每个元素一帧（行文本按 ≤ 常量 行分组） */
+    chunks: string[][];
 }
 export declare function planSessionLogRepair(bytes: Uint8Array, opts?: {
     allowLossy?: boolean;
 }): SessionLogRepairPlan;
+/** 重新编码时的**单帧事件行上限**（超过就分批；任何情况下都不得产生「单帧承载全量事件」）。 */
+export declare const SESSION_REPAIR_MAX_ROWS_PER_FRAME = 200;
 /** 修复备份的扩展名（**唯一事实源**：回滚只接受本模块产生的备份名）。 */
 export declare const SESSION_REPAIR_BACKUP_SUFFIX = ".cm-backup-";
 /**