dsh-config-manager 0.1.71 → 0.1.73

package/lib/core/backup.js

@@ -5,7 +5,9 @@
  * 快照不保存 credential 值（DSH 永不回读值）——credential 条目只记 existed 标志，
  * 回滚时 existed=true 的条目如实标记「值需人工补录」。
  */
+import { engineMsg } from './messages-core.js';
 import fs from 'node:fs/promises';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { parseJsonSafe } from '../utils/json.js';
@@ -60,8 +62,11 @@ async function backupHostFiles(ctx, blobs) {
             existed = await ctx.fs.exists(relPath);
         }
         catch (err) {
+            // 探测自身失败 = 存在性判不出来：按「存在但不可读」登记。**绝不写 existed:false** ——
+            // 那会被恢复侧读成「当时确实不存在」，进而删掉用户真实的文件。
             ctx.log.warn(`快照探测宿主文件失败 ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
-            existed = false;
+            backups.push({ relPath, blobPath: '', existed: true, unreadable: true });
+            continue;
         }
         if (!existed) {
             backups.push({ relPath, blobPath: '', existed: false });
@@ -73,8 +78,10 @@ async function backupHostFiles(ctx, blobs) {
             backups.push({ relPath, blobPath, existed: true });
         }
         catch (err) {
+            // 文件确实存在、只是这次读不出来（占用/权限/IO）：登记 existed=true + unreadable，
+            // 恢复侧据此只跳过并告警，绝不进入「删除」分支（见 HostFileBackup.unreadable）。
             ctx.log.warn(`快照读取宿主文件失败 ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
-            backups.push({ relPath, blobPath: '', existed: false });
+            backups.push({ relPath, blobPath: '', existed: true, unreadable: true });
         }
     }
     return backups;
@@ -90,6 +97,10 @@ const FILE_BASES = {
     agentPresets: '.agent-presets',
     agentInstructions: '', // homeDir 根（~/.dsh/AGENTS.md）
     pluginFiles: '',
+    // 第三方插件数据：baseDir '' = home 根，ref 是**完整的 home 相对路径**
+    // （.dsh-wallpaper-engine/config.json / .mnemon/data/x.db）
+    pluginData: '',
+    pluginAssets: '',
     sessions: 'sessions',
     self: 'dsh-config-manager',
 };
@@ -98,7 +109,7 @@ const FILE_BASES = {
 // 其它分区语义处理」同类缺陷）。注册表新增文件类分区时若忘了在这里补，进程启动即失败。
 for (const id of SECTION_IDS) {
     if (isFileSection(id) && FILE_BASES[id] === undefined) {
-        throw new Error(`分区 ${id} 是文件类分区，但 core/backup.ts 的 FILE_BASES 未给基准目录（拒绝静默退回 homeDir 根）`);
+        throw new Error(engineMsg('core.backup.fileSectionBaseMissing', { section: id }));
     }
 }
 /**
@@ -112,8 +123,41 @@ function profileDirOf(ctx) {
     const profile = ctx.profile !== undefined && ctx.profile !== '' ? ctx.profile : 'web';
     return path.join(ctx.homeDir, 'profiles', profile);
 }
+/**
+ * 以**系统 home 为根**的文件类分区（ref 是系统 home 相对路径）。
+ *
+ * 为什么单独一组：`FileSystemFacade` 被限制在 $DSH_HOME 内，而第三方插件的数据常在 $DSH_HOME 之外
+ * （`~/.dsh-wallpaper-engine/`、`~/.mnemon/` …）。这两个分区的路径解析与 I/O 门面都换根，
+ * 其余分区一字不动 —— 单根不变量只在**这两个分区**上被显式放宽，且仍然只允许白名单区域。
+ */
+export const OS_HOME_FILE_SECTIONS = new Set(['pluginData', 'pluginAssets']);
+/** 该分区文件目标的根（`dsh` = $DSH_HOME；`osHome` = 系统 home） */
+export function sectionFileRoot(adapter) {
+    return OS_HOME_FILE_SECTIONS.has(adapter) ? 'osHome' : 'dsh';
+}
+/** 系统 home：宿主显式给就用它，否则进程 `homedir()`（`~` 的定义，不是猜） */
+export function osHomeDirOf(ctx) {
+    return ctx.osHomeDir !== undefined && ctx.osHomeDir !== '' ? ctx.osHomeDir : homedir();
+}
+/**
+ * 该分区文件 I/O 应使用的门面。
+ *
+ * `osHome` 分区必须用 `homeFs`：缺了它**显式抛错**，绝不退回 `ctx.fs` —— 那会把
+ * `~/.mnemon/x.db` 写成 `$DSH_HOME/.mnemon/x.db`（看起来成功、实际写错位置）。
+ */
+export function fsForSection(ctx, adapter) {
+    if (sectionFileRoot(adapter) === 'dsh')
+        return ctx.fs;
+    if (ctx.homeFs === undefined)
+        throw new Error(engineMsg('core.backup.osHomeUnavailable', { section: adapter }));
+    return ctx.homeFs;
+}
 /** 解析文件类目标的绝对路径（引擎通用快照与回滚共用） */
 export function resolveFileTarget(ctx, adapter, ref) {
+    // 系统 home 根的分区：整体换根（plugins 的两个 profile 特例与它们互不相干）
+    if (sectionFileRoot(adapter) === 'osHome') {
+        return path.join(osHomeDirOf(ctx), FILE_BASES[adapter] ?? '', ref);
+    }
     // plugins 分区的 pnpm-workspace.yaml：位于 profiles/<profile>/ 下（非 FILE_BASES 静态基准）
     if (adapter === 'plugins' && ref === 'pnpm-workspace.yaml') {
         return path.join(profileDirOf(ctx), 'pnpm-workspace.yaml');
@@ -137,6 +181,9 @@ export function resolveFileTarget(ctx, adapter, ref) {
  * 指纹恒为 null，crash 后 reconcile 无法证明该项是否已应用（保守但可避免的精度损失）。
  */
 export function resolveFileTargetRel(adapter, ref, profile) {
+    // 系统 home 根的分区：ref 本身就是「根相对路径」，原样归一即可
+    if (sectionFileRoot(adapter) === 'osHome')
+        return normalizePath(ref);
     if (adapter === 'plugins') {
         const profileDir = `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}`;
         if (ref === 'pnpm-workspace.yaml')
@@ -237,13 +284,17 @@ async function engineSnapshotEntry(ctx, target) {
         case 'agentPresets':
         case 'agentInstructions':
         case 'pluginFiles':
+        case 'pluginData':
+        case 'pluginAssets':
         case 'sessions':
         case 'self': {
+            // 门面按分区选：pluginData / pluginAssets 在系统 home 根（见 fsForSection 的说明）
+            const fsFacade = fsForSection(ctx, target.adapter);
             const abs = resolveFileTarget(ctx, target.adapter, target.ref);
-            if (!(await ctx.fs.exists(abs))) {
+            if (!(await fsFacade.exists(abs))) {
                 return { kind: 'file', adapter: target.adapter, ref: target.ref, before: null, existed: false };
             }
-            const data = await ctx.fs.readFile(abs);
+            const data = await fsFacade.readFile(abs);
             // 文件字节不放进 SnapshotEntry（契约纯净），由 createSnapshot 收集进 blobs Map 统一落盘
             return {
                 kind: 'file',
@@ -257,7 +308,7 @@ async function engineSnapshotEntry(ctx, target) {
         case 'secrets':
             // secrets 已注册但**没有 adapter、也没有 ZIP 内分区 JSON**（凭据值走独立加密容器 secrets.enc）。
             // 任何计划项都不应以它为快照目标 —— 显式报错，而不是落到 default 分支。
-            throw new Error('secrets 分区没有 adapter / 无分区载荷，不应作为快照目标（凭据值走独立加密容器，绝不进快照）');
+            throw new Error(engineMsg('core.backup.secretsSectionNotSnapshotTarget'));
         default: {
             // 编译期穷举断言：SectionId 的每一项都已被上面的 case 处理 → 此处 target.adapter 收窄为 never。
             // 新增分区若忘了在这里实现快照语义，tsc 会直接报错（不再依赖人肉核对清单）。
@@ -265,8 +316,7 @@ async function engineSnapshotEntry(ctx, target) {
             // 运行期（只可能来自运行期强转：被篡改的 plan / 旧 journal 反序列化）：**显式报错**。
             // 旧实现在这里静默返回 settingsNamespace 条目（连 existed 都没有）→ 回滚把该目标当「原本不存在」
             // 而不做任何补偿：该分区的写入永远撤不掉，报告却仍说「已快照、可回滚」（审计 core-flow#F-10）。
-            throw new Error(`快照不支持分区「${String(unhandled)}」：它未在 schema/section-registry.ts 注册（或缺少快照实现）；`
-                + '拒绝按其它分区语义静默记录（那会让该分区的写入无法回滚）');
+            throw new Error(engineMsg('core.backup.sectionUnsupported', { section: String(unhandled) }));
         }
     }
 }
@@ -330,7 +380,7 @@ export async function createSnapshot(opts) {
             if (entry.kind === 'file' && entry.copiedTo && entry.existed) {
                 const abs = resolveFileTarget(ctx, adapterId, target.ref);
                 // 与改动前**完全相同的读调用**，只是延后到被消费时执行（路径语义与异常传播不变）
-                lazyBlobSources.push({ blobPath: entry.copiedTo, read: () => ctx.fs.readFile(abs) });
+                lazyBlobSources.push({ blobPath: entry.copiedTo, read: () => fsForSection(ctx, adapterId).readFile(abs) });
             }
             entries.push(entry);
         }
@@ -405,7 +455,7 @@ export class FileSnapshotStore {
     async writeBlob(dir, blobPath, data, hashes) {
         const target = path.join(dir, blobPath);
         if (!target.startsWith(dir))
-            throw new Error(`快照 blob 路径越界: ${blobPath}`);
+            throw new Error(engineMsg('core.backup.blobPathEscaped', { path: blobPath }));
         await fs.mkdir(path.dirname(target), { recursive: true });
         await atomicWriteFile(target, data);
         hashes[blobPath] = sha256Hex(data);
@@ -429,7 +479,7 @@ export class FileSnapshotStore {
         // 4) 验证（从磁盘重读，不信任内存对象）
         const verified = await verifySnapshot(this.options.dir, snapshot.id);
         if (!verified.ok) {
-            throw new Error(`快照 ${snapshot.id} 验证失败: ${verified.reason}`);
+            throw new Error(engineMsg('core.backup.snapshotVerifyFailed', { id: snapshot.id, reason: verified.reason ?? '' }));
         }
         // 5) 原子发布 READY（重写 snapshot.json readiness='READY'；metadataHash 稳定不受影响）
         const ready = { ...snapshot, readiness: 'READY' };
@@ -439,7 +489,9 @@ export class FileSnapshotStore {
             await this.prune();
         }
         catch (err) {
-            // 快照已 READY + verified；prune 失败（EBUSY/EPERM）不应把刚成功的快照判为 unusable
+            // 快照已 READY + verified；prune 失败（EBUSY/EPERM）不应把刚成功的快照判为 unusable ——
+            // 但必须留痕：保留清理长期失败会让快照无限堆积，用户与日志都看不到线索。
+            this.options.onWarn?.(engineMsg('core.backup.pruneFailed', { reason: err instanceof Error ? err.message : String(err) }));
         }
         return snapshot.id;
     }
@@ -480,7 +532,19 @@ export class FileSnapshotStore {
     async prune() {
         const dir = this.options.dir;
         const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-        const referenced = await this.options.referencedSnapshotIds?.().catch(() => new Set()) ?? new Set();
+        // F3：被未收敛 journal 引用的快照**绝不自动清理**。判据是「读不到 ≠ 没有引用」——
+        // 引用提供者抛错时**放弃本轮清理**，绝不按空集合继续删：一次瞬时 IO 错就可能删掉
+        // 事故恢复唯一的回滚点（那是 SAFE MODE 的唯一证据）。此前这里是 `.catch(() => new Set())`。
+        let referenced = new Set();
+        if (this.options.referencedSnapshotIds !== undefined) {
+            try {
+                referenced = await this.options.referencedSnapshotIds();
+            }
+            catch (err) {
+                this.options.onWarn?.(engineMsg('core.backup.pruneAbandoned', { reason: err instanceof Error ? err.message : String(err) }));
+                return;
+            }
+        }
         // m-retention：策略读取失败 → 回退缺省（绝不因策略提供者异常而误删/崩溃）
         const policy = await Promise.resolve()
             .then(() => this.options.retentionPolicy?.() ?? defaultRetentionPolicyLike())
@@ -494,11 +558,18 @@ export class FileSnapshotStore {
                 const parsed = parseJsonSafe(await fs.readFile(path.join(dir, entry.name, 'snapshot.json'), 'utf8'));
                 if (typeof parsed.id !== 'string' || parsed.id === '' || typeof parsed.createdAt !== 'string')
                     continue;
+                // 删除目标只能是**目录名**（下面 path.join(dir, id) 就是按它删的）。目录名与内部 id 不一致时
+                // **绝不猜**：pinned/被引用的判断是对着这份 snapshot.json 做的，删除却会打在另一个目录上 ——
+                // 跳过并留痕（手工改名/半截拷贝残留会出现这种形态）。
+                if (parsed.id !== entry.name) {
+                    this.options.onWarn?.(engineMsg('core.backup.dirNameIdMismatch', { dir: entry.name, id: parsed.id }));
+                    continue;
+                }
                 if (parsed.pinned === true)
                     continue; // 置顶快照豁免自动清理
-                if (referenced.has(parsed.id))
+                if (referenced.has(entry.name))
                     continue; // Phase 4 F3：recovery 引用豁免
-                metas.push({ id: parsed.id, createdAt: parsed.createdAt });
+                metas.push({ id: entry.name, createdAt: parsed.createdAt });
             }
             catch {
                 // 损坏 / 非快照目录：跳过（与 listSnapshots 语义一致）
@@ -528,7 +599,7 @@ export class FileSnapshotStore {
         const target = path.join(this.snapshotDir(id), blobPath);
         const dir = this.options.dir;
         if (!target.startsWith(dir))
-            throw new Error(`快照 blob 路径越界: ${blobPath}`);
+            throw new Error(engineMsg('core.backup.blobPathEscaped', { path: blobPath }));
         return fs.readFile(target);
     }
     /** 标记快照生命周期状态：重写 <dir>/<id>/snapshot.json（保留其余字段）。 */
@@ -559,55 +630,55 @@ export function computeMetadataHash(snapshot) {
 export async function verifySnapshot(snapshotsDir, id) {
     const dir = path.join(snapshotsDir, id);
     if (!dir.startsWith(path.resolve(snapshotsDir) + path.sep)) {
-        return { ok: false, reason: '快照路径越界' };
+        return { ok: false, reason: engineMsg('core.backup.snapshotPathEscaped') };
     }
     let raw;
     try {
         raw = await fs.readFile(path.join(dir, 'snapshot.json'), 'utf8');
     }
     catch {
-        return { ok: false, reason: 'snapshot.json 缺失' };
+        return { ok: false, reason: engineMsg('core.backup.snapshotJsonMissing') };
     }
     const snapshot = parseJsonSafe(raw);
     if (snapshot === null || typeof snapshot !== 'object' || typeof snapshot.id !== 'string' || snapshot.id === '') {
-        return { ok: false, reason: 'snapshot.json 非法' };
+        return { ok: false, reason: engineMsg('core.backup.snapshotJsonInvalid') };
     }
     if (snapshot.id !== id) {
-        return { ok: false, reason: 'snapshot.id 与目录不匹配' };
+        return { ok: false, reason: engineMsg('core.backup.snapshotIdDirMismatch') };
     }
     let manifestRaw;
     try {
         manifestRaw = await fs.readFile(path.join(dir, 'manifest.json'), 'utf8');
     }
     catch {
-        return { ok: false, reason: 'manifest.json 缺失' };
+        return { ok: false, reason: engineMsg('core.backup.manifestMissing') };
     }
     const manifest = parseJsonSafe(manifestRaw);
     if (manifest === null || typeof manifest !== 'object' || manifest.snapshotId !== id) {
-        return { ok: false, reason: 'manifest 非法或 snapshotId 不匹配' };
+        return { ok: false, reason: engineMsg('core.backup.manifestInvalid') };
     }
     // entryCount 匹配（manifest 声明条目数与实际一致，防计数篡改）
     if (typeof manifest.entryCount !== 'number' || manifest.entryCount !== snapshot.entries.length) {
-        return { ok: false, reason: 'manifest.entryCount 与 snapshot.entries 不一致（篡改）' };
+        return { ok: false, reason: engineMsg('core.backup.entryCountMismatch') };
     }
     // metadataHash 匹配（破坏性内容）
     if (computeMetadataHash(snapshot) !== manifest.metadataHash) {
-        return { ok: false, reason: 'metadataHash 不匹配（破坏性内容被篡改）' };
+        return { ok: false, reason: engineMsg('core.backup.metadataHashMismatch') };
     }
     // blob hashes 匹配 + 存在
     for (const [blobPath, expectedHash] of Object.entries(manifest.blobHashes)) {
         const target = path.join(dir, blobPath);
         if (!target.startsWith(dir))
-            return { ok: false, reason: `blob 路径越界: ${blobPath}` };
+            return { ok: false, reason: engineMsg('core.backup.blobPathEscaped', { path: blobPath }) };
         let data;
         try {
             data = await fs.readFile(target);
         }
         catch {
-            return { ok: false, reason: `blob 缺失: ${blobPath}` };
+            return { ok: false, reason: engineMsg('core.backup.blobMissing', { path: blobPath }) };
         }
         if (sha256Hex(data) !== expectedHash) {
-            return { ok: false, reason: `blob hash 不匹配: ${blobPath}` };
+            return { ok: false, reason: engineMsg('core.backup.blobHashMismatch', { path: blobPath }) };
         }
     }
     // Review C P2：snapshot.json 引用的每个 blob（entries.copiedTo / hostFileBackups.blobPath）都必须被 manifest 覆盖，
@@ -623,7 +694,7 @@ export async function verifySnapshot(snapshotsDir, id) {
     }
     for (const relBlob of referencedBlobs) {
         if (!(relBlob in manifest.blobHashes)) {
-            return { ok: false, reason: `snapshot 引用的 blob 未在 manifest 中: ${relBlob}` };
+            return { ok: false, reason: engineMsg('core.backup.blobNotInManifest', { blob: relBlob }) };
         }
     }
     return { ok: true };

package/lib/core/boot-rescue.js

@@ -34,6 +34,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { sha256Hex } from '../utils/hashing.js';
+import { engineMsg } from './messages-core.js';
 /* ---------------------------------------------------------------- 常量 */
 /** 默认备份目录（相对 homeDir 的 posix 路径；backupDir 缺省时使用） */
 const DEFAULT_BACKUP_DIR_REL = 'dsh-config-manager/transactions/rescue-backups';
@@ -340,13 +341,13 @@ async function readRescueState(backupDir) {
 /** 救援模式 profile patch 的头注释（说明本文件被谁接管、bundle 层的实际状态）。 */
 const RESCUE_PATCH_HEADER_LINES = [
     '# dsh-config-manager RESCUE MODE',
-    '# 本文件（profile patch 层）已被救援模式接管；home patch 同时被置空。',
+    engineMsg('core.bootRescue.patchTakenOver'),
 ];
 /** 救援模式 profile patch 的头注释（按 bundle 处理方式给出准确说明，不得夸大能力）。 */
 function rescuePatchHeader(bundlesDisabled) {
     const note = bundlesDisabled
-        ? '# dsh.profile.bundles 已被收窄为 DSH 核心与救援插件自身，被禁用的包同时已从 dependencies 临时摘除：其余用户插件本次启动不挂载。'
-        : '# 注意：dsh.profile.bundles 里的插件仍由 bundle 层挂载（本次只裁剪了不可解析的 bundle）。';
+        ? engineMsg('core.bootRescue.bundlesNarrowed')
+        : engineMsg('core.bootRescue.bundlesNote');
     return [...RESCUE_PATCH_HEADER_LINES, note, ''].join('\n');
 }
 /** 单引号 YAML 标量（按 YAML 规则把 `'` 转义为 `''`）。 */

package/lib/core/boot-safety.js

@@ -21,6 +21,7 @@
 import { RESCUE_KEEP_BUNDLE_PREFIXES, computeSafeBundles } from './boot-rescue.js';
 import { BOOT_CRITICAL_RELS, profileCriticalRels } from './boot-paths.js';
 import { zhMsg } from './messages.js';
+import { engineMsg } from './messages-core.js';
 /** 可解析性检查的目标（.json → JSON.parse；.yaml/.yml → 注入的 parseYaml）。 */
 function parseKind(rel) {
     if (rel.endsWith('.json'))
@@ -118,7 +119,7 @@ export async function auditBootSafety(deps) {
                     const drop = new Set(prunable.map((p) => p.name));
                     const next = (Array.isArray(bundles) ? bundles : []).filter((b) => !(typeof b === 'string' && drop.has(b)));
                     if (!writeBundles(pkg, next))
-                        throw new Error('dsh.profile.bundles 不是数组或结构异常');
+                        throw new Error(engineMsg('core.bootSafety.bundlesNotArray'));
                     await deps.writeText(pkgRel, JSON.stringify(pkg, null, 2) + '\n');
                     written = true;
                 }

package/lib/core/command-rollback.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 宿主斜杠命令 /rollback（别名 /rw）—— 不打开设置面板也能回退（对齐 dsh-rewind 的 /rewind、/undo）。
+ *
+ * 语义（用户 2026-10-12 确认方案 A）：
+ *   /rollback            → 当前**会话**的可回退点列表（回合号 / 时间 / 类型 / 状态 / 可回退性）
+ *   /rollback <id>       → 回退到该点，走**与 HTTP 路由同源**的那道写入门：
+ *                          runWithMutationLock（= SAFE MODE 门 + 跨进程/跨 kind 环境锁）
+ *                          → 引擎 preview（零写入）→ 引擎 rewind（userConfirmed=true）
+ *   引擎回的 confirmation-required / protected-point / record-incomplete 一律翻成可读错误结果，
+ *   **绝不绕过**（命令入口没有「确认按钮」，用户敲下 id 就是那次确认；其余门照旧全量生效）。
+ *
+ * 纪律（与 src/core/model-tools.ts 的 registerModelTools 同口径）：
+ *  · 命令服务**惰取**：一律 ctx.get('commands')，绝不属性访问 ctx.commands、绝不放进 inject ——
+ *    未组合该服务的部署必须照常启动（命令是可选能力，不是硬依赖）；
+ *    **读的时机是装配期一次**（见 registerRollbackCommand）：Cordis 的 ctx.get 在 apply 期只能拿到
+ *    **已 apply** 的服务，所以 `commands` 行晚于本插件时 `/rollback` 不会注册（只 warn 一行、无重试入口）。
+ *    DSH 内置插件与本插件的实际 apply 顺序**未坐实**（asar 不可直接读、本机 profile 无相关行）；
+ *    要彻底消除这个窗口需要 `ctx.inject(['commands'])` 式的「服务就绪再注册」回调 —— 未做，如实记在这里。
+ *  · 注册失败只 warn：命令挂不上不得影响其它装配（宿主启动 = blocker）；
+ *  · 用户可见文案一律走宿主字典 engineMsg（key: command.rollback.*），**取文案那一刻**解析语言；
+ *  · 本模块不 import @deepseek-ai/dsh-commands 的运行时值（只做结构化窄化），core 保持与 DSH 解耦。
+ */
+import type { MutationLockPort } from '../utils/env-lock.ts';
+import type { RollbackPointSummary, RollbackRewindResult } from './rollback-point.ts';
+/**
+ * 命令结果（与 @deepseek-ai/dsh-commands 的 `CommandResult` **逐字同形**）。
+ *
+ * 为什么在这里自己声明而不是 import 那门包的类型：`src/core/**` 的架构边界（tests/architecture-boundaries.test.ts
+ * 的 core allow 表）只允许 node 内置 / core 内部 / schema / utils / security / migrations / js-yaml ——
+ * `@deepseek-ai/*` 仅允许出现在 `src/index.ts` 与 `src/client/`。core 必须保持与 DSH 解耦，
+ * 所以这里做**结构化窄化**；两边一旦漂移，`command-rollback.test.ts` 的编译期断言会红。
+ */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+    readonly sourceEventSeq?: number;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** 命令名（无前导斜杠）与别名。 */
+export declare const ROLLBACK_COMMAND_NAME = "rollback";
+export declare const ROLLBACK_COMMAND_ALIAS = "rw";
+/**
+ * 命令定义 id：/rw 别名是**第二条定义** —— 同一个 definitionId（客户端按 definitionId 做身份化行为，
+ * 别名与主名必须被视作同一条命令）。
+ */
+export declare const ROLLBACK_COMMAND_DEFINITION_ID = "dsh-config-manager/rollback";
+/** 命令服务惰取回调（调用期读 ctx.get('commands')；未组合返回 undefined）。 */
+export type CommandServiceReader = () => CommandServiceLike | undefined | null;
+/** 一条已注册命令的最小形状（避免把 DSH 类型变成本插件的硬依赖）。 */
+export interface CommandDefinitionLike {
+    readonly name: string;
+    readonly description: string;
+    readonly definitionId?: string;
+    readonly input?: {
+        readonly hint: string;
+        readonly attachments?: boolean;
+    };
+    readonly handler: (invocation: CommandInvocationLike) => CommandResult | Promise<CommandResult>;
+}
+/** 一次命令调用的最小形状（只读用到的字段）。 */
+export interface CommandInvocationLike {
+    readonly agent: unknown;
+    /** 命令名之后的原文（含分隔空白）。 */
+    readonly rawInput: string;
+    /** 派发 UI 持有的取消信号（透传给回退执行）。 */
+    readonly signal?: AbortSignal;
+}
+/** 命令服务的最小形状（ctx.get('commands') 的结构化窄化）。 */
+export interface CommandServiceLike {
+    register(definition: CommandDefinitionLike): unknown;
+}
+/** 宿主提供的回退能力（由 src/index.ts 装配；测试用假的实现即可）。 */
+export interface RollbackCommandHost {
+    /** 当前 agent 所属会话（拿不准则 ok:false —— 绝不猜）。 */
+    agentSession(agent: unknown): AgentSessionFacts;
+    /** 列出该会话的回退点（含存储栈状态；只读）。 */
+    list(sessionId: string): Promise<RollbackCommandListResult>;
+    /**
+     * 执行回退：runWithMutationLock → SAFE MODE → 引擎 preview → 引擎 rewind。
+     *
+     * 被 SAFE MODE / 环境锁挡住时**抛 EnvironmentLockUnavailableError**（与 HTTP 路由同口径），
+     * 由本模块翻成可读错误结果。
+     */
+    rewind(input: RollbackRewindExecution): Promise<RollbackRewindResult>;
+}
+/**
+ * 回退执行入参。
+ *
+ * 只带 id + 取消信号：引擎 `rewind({ id, userConfirmed: true })` 的**写入面**已经由该点的记录
+ * 决定（不是调用方临时指定路径），多传会话/分块只会制造「两处口径」；会话事实只供只读列表过滤用。
+ */
+export interface RollbackRewindExecution {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+/** 列表结果（引擎 RollbackListResult 的可测子集）。 */
+export interface RollbackCommandListResult {
+    ok: boolean;
+    storage: {
+        available: boolean;
+        root: string;
+        detail?: string;
+    };
+    points: readonly RollbackPointSummary[];
+    error?: string;
+}
+/** 当前 agent 的会话事实（宽进严出：形状不符即 ok:false）。 */
+export type AgentSessionFacts = {
+    ok: true;
+    sessionId: string;
+    chunks: readonly string[];
+} | {
+    ok: false;
+    detail: string;
+};
+/** 绝对路径判定（win32 盘符 + POSIX 前缀 + UNC；纯函数，不引 node:path）。 */
+export declare function isAbsolutePath(value: string): boolean;
+/**
+ * 从 agent 窄化会话事实。
+ *
+ * **不猜**：agent.session.id 读不出来就退回 agent.id（DSH 的 Agent.id 就是会话 id）；
+ * 两者都读不出 → ok:false（命令如实报「拿不到当前会话」，而不是列全网的点）。
+ * 工作区分块只认**绝对路径**的 cwd（与 rollbackSessionBindingOf 同一口径）。
+ */
+export declare function agentSessionFactsOf(agent: unknown): AgentSessionFacts;
+/** 解析结果：空输入 = 只读列表；单个 token = 目标点 id；其余 = invalid。 */
+export type RollbackCommandInput = {
+    kind: 'list';
+} | {
+    kind: 'rewind';
+    id: string;
+} | {
+    kind: 'invalid';
+    detail: string;
+};
+/**
+ * 解析 rawInput（命令名之后的原文，含分隔空白）。
+ * 语法只有两种：空 = 列表；单个非空 token = 目标 id。多 token 一律 invalid。
+ */
+export declare function parseRollbackCommand(rawInput: string): RollbackCommandInput;
+/** 渲染只读列表（本会话没有点时给「本会话没有」，绝不冒充「全库为空」）。 */
+export declare function renderRollbackList(result: RollbackCommandListResult, sessionId: string): CommandResult;
+/** 把引擎结果翻成命令结果（失败一律带机器码 + 技术细节；processed 的段事实不隐藏）。 */
+export declare function renderRewindResult(result: RollbackRewindResult, id: string): CommandResult;
+/** 命令依赖（index.ts 装配；测试直接构造）。 */
+export interface RollbackCommandDeps {
+    readonly host: RollbackCommandHost;
+    /** mutation lock 端口（index.ts 传 host.mutationLock；测试可传 undefined 或假端口）。 */
+    readonly mutationLock?: MutationLockPort;
+    /** SAFE MODE 同步谓词（与 HTTP 路由同一份 host.safeModeIsBlocked）。 */
+    readonly isBlocked?: () => boolean;
+}
+/**
+ * 构造命令处理器（**纯编排**：不注册、不读 ctx）。
+ *
+ * 带参数时：parser → agentSession（只用于「这次是不是列表」的会话判定）→ host.rewind。
+ * host.rewind 内部才是那道门：runWithMutationLock → SAFE MODE → 引擎 preview → 引擎 rewind
+ * EnvironmentLockUnavailableError（SAFE MODE / 环境锁被挡）在此翻成可读错误结果。
+ * 任何未预期异常也翻成错误结果 —— 命令处理器抛异常会让整条命令生命周期报泛化失败，
+ * UI 只看到一句「失败」；这里如实把原因说清楚。
+ */
+export declare function makeRollbackCommandHandler(deps: RollbackCommandDeps): (invocation: CommandInvocationLike) => Promise<CommandResult>;
+/** 注册所需的依赖面（命令服务惰取回调 + 宿主日志 + 命令依赖）。 */
+export interface RollbackCommandRegistrationOptions {
+    /** 惰取命令服务：实现必须是「调用期」的 ctx.get('commands')（绝不属性访问、绝不进 inject）。 */
+    readonly readCommands: CommandServiceReader;
+    readonly deps: RollbackCommandDeps;
+    /** 只 warn：注册失败/服务缺失不得影响其它装配。 */
+    readonly log?: {
+        warn(message: string, meta?: unknown): void;
+    };
+}
+/**
+ * 注册 /rollback 与 /rw（两条定义 = 同一 definitionId）。
+ *
+ * 服务缺失 → warn 后**安静返回**（未组合 commands 的部署照常启动、不抛错）；
+ * 服务存在但 register 抛错 → warn（其余装配不受影响）。
+ * @returns 反注册函数（重复调用安全）。
+ */
+export declare function registerRollbackCommand(options: RollbackCommandRegistrationOptions): () => void;