dsh-config-manager 0.1.80 → 0.1.82

package/README.md

@@ -778,7 +778,7 @@ Found a bug, a misaligned panel, a button that does nothing — or just have an
   read per layer and written back to their own layer, and skills are collected through the shell's `skills` service.
   All three shipped with unit tests and route / source-level guards.
 
-> Maintainers & developers: see [DEVELOPERS.md](DEVELOPERS.md) for build, testing, auto-publishing and full technical notes.
+> Maintainers & developers: start at the [documentation index](docs/index.md) — architecture, module docs, ADRs and known tech debt; [DEVELOPERS.md](DEVELOPERS.md) covers build, testing, auto-publishing and full technical notes.
 
 ---
 

package/README.zh-CN.md

@@ -776,7 +776,7 @@ $env:HTTPS_PROXY='http://127.0.0.1:7897'; dsh web
   全量预览 27.6 s）。③ 修 issue #71「外壳里配好的 MCP 与 Skills 备份不到」：patch 行按层读取、写回原层，技能改经
   外壳的 `skills` 服务收编。三个 PR 均带单测与路由 / 源码级守卫。
 
-> 维护者与开发者：构建、测试、自动发布与完整技术说明见 [DEVELOPERS.md](DEVELOPERS.md)。
+> 维护者与开发者：从[文档总索引](docs/index.md)开始（架构、模块文档、ADR、已知技术债）；构建、测试、自动发布与完整技术说明见 [DEVELOPERS.md](DEVELOPERS.md)。
 
 ---
 

package/lib/cli/actions.d.ts

@@ -142,6 +142,11 @@ export interface RescueStatus {
 /** 首页聚合：每一项各自 try/catch，缺一项不影响其余（但失败必须在 errors 里可见）。 */
 export declare function readRescueStatus(paths: RescuePaths, now?: () => Date): Promise<RescueStatus>;
 export type WriteRefusalCode = 'safe-mode' | 'stale-lock' | 'dsh-running' | 'nothing-to-do' | 'io-error';
+/**
+ * SAFE MODE 拒因码的**单点常量**：`src/cli/index.ts` 的源码守卫（P0-11-07）禁止
+ * CLI 自带 `'safe-mode'` 字面量，判据必须复用本常量（否则改一处漏一处）。
+ */
+export declare const SAFE_MODE_REFUSAL_CODE: WriteRefusalCode;
 export interface WriteGateRefusal {
     ok: false;
     code: WriteRefusalCode;

package/lib/cli/actions.js

@@ -279,6 +279,11 @@ export async function readRescueStatus(paths, now = () => new Date()) {
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * SAFE MODE 拒因码的**单点常量**：`src/cli/index.ts` 的源码守卫（P0-11-07）禁止
+ * CLI 自带 `'safe-mode'` 字面量，判据必须复用本常量（否则改一处漏一处）。
+ */
+export const SAFE_MODE_REFUSAL_CODE = 'safe-mode';
 /**
  * 写动作的前置门（与 CLI `sessions repair --fix` 同一判据）。
  *

package/lib/cli/index.js

@@ -23,14 +23,15 @@ import { pathToFileURL } from 'node:url';
 import { execFile } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin as processStdin, stdout as processStdout } from 'node:process';
-import { listSnapshots, planRestore, restore, } from '../core/restore.js';
+import { listSnapshots, planRestore, } from '../core/restore.js';
 import { REINSTALL_ITEMS, buildReinstallPlan, isWindows, detectInstalledDshVersion, writeReinstallRecoveryPoint, } from '../core/reinstall.js';
 import { EnvironmentLockManager, runWithMutationLock, EnvironmentLockUnavailableError, OWNERSHIP_FILE } from '../utils/env-lock.js';
 import { runSessionsRepair } from './sessions-repair.js';
 import { runSessionsInspect } from './sessions-inspect.js';
 import { runImportSource } from './import-source.js';
+import { probeCliRestoreResume, runCliRestore } from './restore-resume.js';
 import { renderCommandHelp, renderOverview } from './help.js';
-import { collectVerifyResults, readRunningInstances } from './actions.js';
+import { checkWriteGates, collectVerifyResults, readRunningInstances, SAFE_MODE_REFUSAL_CODE } from './actions.js';
 import { Phase3Recovery, readSafeModeMarkerSync, safeModeMarkerPath } from '../core/phase3-host.js';
 import { verifyBackupZip, } from '../core/backup-verify.js';
 import { collectBackupEntries, buildSectionFlags, parseSectionsArg, OFFLINE_UNAVAILABLE_SECTIONS, } from '../core/backup-plan.js';
@@ -853,19 +854,33 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
         }, io, env);
     }
     if (options.command === 'sessions') {
-        // 离线修复：不碰 $DSH_HOME 的其它部分、不需要环境锁（只读写会话目录，且默认 dry-run）
+        // 离线修复：只读写会话目录，默认 dry-run（零写入）。list/doctor 纯只读，连「DSH 在跑」都不用管。
+        // **--fix 走与救急台完全相同的写入门**（actions.ts 的 checkWriteGates，顺序 SAFE MODE → 残留环境锁 → DSH 未运行）：
+        // 此前这里只查「DSH 在跑」，于是 SAFE MODE 激活 / 残留环境锁时 CLI 仍能改写会话字节 —— 与救急台判据分叉（审计 P1）。
         const home = options.home ?? resolveDshHome(env);
         const action = options.positionals[0] ?? 'repair';
         // T6：list / doctor 是**只读**动作 —— 不检查「DSH 是否在跑」，因为读永远不会伤害运行中的实例。
         if (action === 'list' || action === 'doctor') {
             return runSessionsInspect({ home, action: action === 'doctor' ? 'doctor' : 'list', json: options.json }, io);
         }
-        // T6：repair（含 --fix/--apply）先跑安全修复计划；**写操作前必须确认 DSH 没在跑**。
+        // T6：repair（含 --fix/--apply）先跑安全修复计划；写操作前三道门与救急台逐条同源。
         if (options.fix === true) {
-            const running = (await readRunningInstances(resolveControlRoots({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env))).map((instance) => instance.name);
-            if (running.length > 0) {
-                io.error('检测到 DSH 正在运行（' + running.join(', ') + '）：请先关闭 DSH 再执行修复。');
-                io.error('DSH running (' + running.join(', ') + '): close DSH before repairing session bytes.');
+            const controlOpts = { dataRoot: options.dataRoot, dataDir: options.dataDir };
+            const gate = await checkWriteGates(resolveControlRoots(controlOpts, env), {
+                needsDshStopped: true,
+                locksDir: resolveRecoverLocksDir(controlOpts, env),
+            });
+            if (!gate.ok) {
+                io.error('拒绝执行：' + gate.reason);
+                if (gate.code === 'dsh-running') {
+                    io.error('DSH running: close DSH before repairing session bytes.');
+                }
+                else if (gate.code === SAFE_MODE_REFUSAL_CODE) {
+                    io.error('SAFE MODE is active: resolve the pending transaction before writing session bytes.');
+                }
+                else if (gate.code === 'stale-lock') {
+                    io.error('A stale environment lock is present: run "dsh-config-manager recover-stale-lock" first.');
+                }
                 return 1;
             }
         }
@@ -955,9 +970,12 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
     // Phase 3 SAFE MODE：存在未恢复 transaction → 拒绝 destructive（CLI 不旁路 SAFE MODE）。
     // 候选根与真实 restore 的锁目录/journal 根同源（均为 <root> = dirname(快照目录) 的那一族）。
     const controlRoots = resolveControlRoots({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env);
+    // Phase 3 P0-A：CLI restore 也建 durable journal；顺带做续跑探测（只读）——「同一个恢复崩在中途」正是 SAFE MODE 在等的结论。
+    const recovery = new Phase3Recovery({ dataDir: path.dirname(dataDir), packageVersion: '0.1.0', fingerprintDataDir: path.dirname(dataDir) });
+    const resumeProbe = await probeCliRestoreResume(recovery, restoreOptions);
     const safeMsg2 = checkSafeModeBlocked(controlRoots);
-    if (safeMsg2 !== null) {
-        io.error(`拒绝执行：${safeMsg2}`);
+    if (safeMsg2 !== null && !resumeProbe.resumable) {
+        io.error(`拒绝执行：${safeMsg2}${resumeProbe.reason === null ? '' : `（无法自动续跑：${resumeProbe.reason}）`}`);
         return 1;
     }
     // Phase 2 锁：真实 restore 是 destructive（覆盖/删除 $DSH_HOME + 卸载插件），必须成功获取
@@ -970,7 +988,6 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
     });
     try {
         // Phase 3 P0-A：CLI restore 也创建 durable journal（关闭 bypass）。
-        const recovery = new Phase3Recovery({ dataDir: path.dirname(dataDir), packageVersion: '0.1.0', fingerprintDataDir: path.dirname(dataDir) });
         await recovery.initFingerprint().catch(() => undefined);
         const outcome = await runWithMutationLock(lock, { op: 'cli-restore', target: id }, async (lockCtx) => {
             // 第三道门（与救急台 actions.ts 的 checkWriteGates 同源、同序：SAFE MODE → 残留锁 → DSH 未运行）：
@@ -978,12 +995,11 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
             const running = await readRunningInstances(controlRoots);
             if (running.length > 0)
                 return { kind: 'dsh-running', running };
-            return {
-                kind: 'restore',
-                report: lockCtx !== null
-                    ? (await recovery.runJournaled({ operationType: 'cli-restore', lockCtx, fn: () => restore(restoreOptions) })).result
-                    : await restore(restoreOptions),
-            };
+            // 锁内统一入口：能续跑 → resumeJournaled（接着做），否则 → runJournaled（照常新建）
+            const out = await runCliRestore(recovery, restoreOptions, lockCtx);
+            if (out.resumed !== null)
+                io.log(`自动续跑：已完成 ${String(out.resumed.done)} 项、待做 ${String(out.resumed.todo)} 项；SAFE MODE ${out.safeModeCleared === true ? '已解除' : '仍保持'}`);
+            return { kind: 'restore', report: out.report };
         });
         if (outcome.kind === 'dsh-running') {
             io.error('检测到 DSH 正在运行（' + outcome.running.map((i) => i.name + ' pid=' + String(i.pid)).join('、')

package/lib/cli/restore-resume.d.ts

@@ -0,0 +1,25 @@
+import type { RestoreOptions, RestoreReport } from '../core/restore.ts';
+import type { Phase3Recovery } from '../core/phase3-host.ts';
+import type { MutationLockContext } from '../utils/env-lock.ts';
+/** 锁前探测结果（只用于「能否放过 SAFE MODE 门」与给用户的提示）。 */
+export interface CliRestoreResumeProbe {
+    resumable: boolean;
+    /** 不可续跑时的人话原因（resumable=false 且没有可续记录时也为 null 之外的短句） */
+    reason: string | null;
+    done: number;
+    todo: number;
+}
+/** 锁前探测：只读，不写 journal、不碰目标文件。 */
+export declare function probeCliRestoreResume(recovery: Phase3Recovery, restoreOpts: RestoreOptions): Promise<CliRestoreResumeProbe>;
+/** 锁内执行：能续跑就接着做，否则照常新建 journal。 */
+export interface CliRestoreRunOutcome {
+    report: RestoreReport;
+    resumed: {
+        operationId: string;
+        done: number;
+        todo: number;
+    } | null;
+    /** 续跑成功且 SAFE MODE 已按判据解除（null = 本次不是续跑，未尝试） */
+    safeModeCleared: boolean | null;
+}
+export declare function runCliRestore(recovery: Phase3Recovery, restoreOpts: RestoreOptions, lockCtx: MutationLockContext | null): Promise<CliRestoreRunOutcome>;

package/lib/cli/restore-resume.js

@@ -0,0 +1,49 @@
+/**
+ * 离线 CLI 恢复的**自动续跑**薄封装（判定与执行都在 core，这里只做「CLI 口子」的三件事）。
+ *
+ * 为什么单独一层：
+ *  1. `src/cli/index.ts` 卡在 1461 行棘轮上限，装配代码必须外提；
+ *  2. 续跑有三处必须与宿主/GUI 保持同一口径 —— 锁前探测（决定能否放过 SAFE MODE 门）、
+ *     锁内再判一次（决定 runJournaled 还是 resumeJournaled）、成功后按**同一个**
+ *     resolveSafeModeMarker 解除 SAFE MODE。口径写在这里就不必在两处各写一遍。
+ *
+ * 注意：CLI 只续跑 `cli-restore` 自己创建的 journal。别的入口（GUI restore / model-restore）
+ * 崩掉的记录在这里仍是「需要恢复面板处理」的事故 —— 三者的执行器与参数来源不同，
+ * 跨入口续跑没有证据支撑（详见 docs/decisions/0004）。
+ */
+import { resolveSafeModeMarker } from '../core/recovery-orchestrator.js';
+import { probeRestoreResume, runRestoreWithResume } from '../core/restore-resume.js';
+/** 锁前探测：只读，不写 journal、不碰目标文件。 */
+export async function probeCliRestoreResume(recovery, restoreOpts) {
+    const judged = await probeRestoreResume({
+        store: recovery.store,
+        restoreOpts,
+        allowedOperationTypes: ['cli-restore'],
+    });
+    if (judged.ok) {
+        return { resumable: true, reason: null, done: judged.resume.done, todo: judged.resume.todo };
+    }
+    // no-active-journal = 本来就没有事故，不算「拒绝」
+    return {
+        resumable: false,
+        reason: judged.code === 'no-active-journal' ? null : judged.detail,
+        done: 0,
+        todo: 0,
+    };
+}
+export async function runCliRestore(recovery, restoreOpts, lockCtx) {
+    const out = await runRestoreWithResume({
+        store: recovery.store,
+        restoreOpts,
+        operationType: 'cli-restore',
+        allowedOperationTypes: ['cli-restore'],
+        lockCtx,
+        phase3: recovery,
+    });
+    if (out.resumed === null)
+        return { report: out.report, resumed: null, safeModeCleared: null };
+    // 续跑成功：按**同一个**判据解除 SAFE MODE（还有别的未解决 incident 时保持，返回 false）
+    const cleared = await resolveSafeModeMarker(recovery.store, () => recovery.clearSafeMode(), false);
+    return { report: out.report, resumed: out.resumed, safeModeCleared: cleared };
+}
+//# sourceMappingURL=restore-resume.js.map

package/lib/client.d.ts

@@ -669,6 +669,12 @@ interface RestoreReport {
   }[];
   /** 跳过项（无动作 / 离线无法处理） */
   skipped: string[];
+  /**
+   * 本次执行真正写入的 pre-restore 反悔副本目录（`<snapshotDir>/pre-restore/<attemptDir>/`）。
+   * 每次 restore() 新建一个 attempt 目录（D5）⇒ 崩溃后重跑**不会覆盖**上一次的反悔副本；
+   * 没有任何文件需要备份时缺省（不建空目录）。
+   */
+  preRestoreDir?: string;
   /**
    * 幽灵会话（F5 失效归档清理）：快照记录的 sessions 分区会话在磁盘 sessions 目录
    * 已无任何文件（备份有记录、磁盘无文件）。DSH 官方无归档会话 API，降级本地校验，