@logictan/dsh-config-manager 0.1.60

package/lib/index.js

@@ -0,0 +1,2764 @@
+/**
+ * dsh-config-manager — host half.
+ *
+ * Mounts the backup / export / import engine (src/core Exporter + Importer
+ * three-stage flow) behind the `/api/dsh-config-manager/*` route family that
+ * the browser half (`./client`) calls, and wraps the real DSH host services
+ * into the engine's `HostContext` facade (src/core/types.ts):
+ *
+ *   ctx.settings           -> SettingsFacade      (@deepseek-ai/dsh-settings)
+ *   ctx.credentials        -> CredentialsFacade   (@deepseek-ai/dsh-credentials)
+ *   ctx.plugins            -> PluginsFacade       (官方 dsh plugin CLI 通道 + profile 文件，
+ *                                                  见 src/core/plugin-cli.ts)
+ *   ctx.workspaceRegistry  -> WorkspaceFacade     (@deepseek-ai/dsh-workspace)
+ *   ~/.dsh/cordis.patch.yml-> PatchFileFacade     (js-yaml)
+ *   $DSH_HOME files        -> FileSystemFacade    (node:fs, home-relative)
+ *   resolveDshHome()       -> homeDir             (@deepseek-ai/dsh-home-paths)
+ *
+ * Security posture (mirrors the verified @linxin666/dsh-ssh@0.1.12 routes):
+ *  - every route carries the loopback-only + same-origin trust fence
+ *    (isLoopbackRequest); LAN-exposed deployments never serve these endpoints;
+ *  - uploads/exported ZIPs are staged under $DSH_HOME/dsh-config-manager/{tmp,exports}
+ *    and every `path`/`zipPath` reference is confined to those roots;
+ *  - the encryption password is in-memory only: used to derive the AES-256-GCM
+ *    key for secrets.enc, never written to any file, manifest, or log;
+ *  - the import execute endpoint refuses to run without `confirm: true`
+ *    (core ImportNotConfirmedError safety valve).
+ *
+ * Optional services are read with ctx.get() at call time (never injected), so
+ * the engine keeps working in profiles without the web-only workspace
+ * service; hard dependencies are the core `settings`/`credentials` services
+ * present in every profile. Plugin install/list no longer depend on the
+ * web-only pluginMarketplace/pluginInventory services: both go through the
+ * official `dsh plugin --profile <name>` CLI (pnpm forwarder) and read the
+ * profile's package.json / node_modules directly.
+ */
+import { randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { createReadStream, createWriteStream, mkdirSync, readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import * as dshSettings from '@deepseek-ai/dsh-settings';
+import * as dshCredentials from '@deepseek-ai/dsh-credentials';
+import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import * as yaml from 'js-yaml';
+import { Exporter, FileSnapshotStore, Importer, verifySnapshot } from './core/index.js';
+import { APPLY_ORDER, ProfileManager, isValidProfileName } from './profiles/index.js';
+import { cleanupCaches } from './core/cache-cleaner.js';
+import { deleteSnapshot, isValidSnapshotId, listSnapshots, planRestore, setSnapshotPinned, validateSnapshotForRestore } from './core/restore.js';
+import { rollback as performRollback } from './core/rollback.js';
+// Phase 1 P0-1/P0-2：配置生命周期（自动快照 / 撤销 / 重做）与 P0-5 崩溃归因。
+// 监听工厂用真 fs.watch 注入（core 侧只依赖抽象，便于测试驱动时序）。
+import { ConfigLifecycle } from './core/config-lifecycle.js';
+import { deleteConfigSnapshot } from './core/config-snapshot.js';
+import { adviceFor, beginBoot, computeBootAlert, listCandidateLogs, markBootOk, readBootState, readCrashLogTail, writeBootState, } from './core/crash-report.js';
+// Phase 1 P0-3：启动救援模式（备份 patch/package.json → 写最小 patch → 中和 bundles）
+import { enterRescueMode, exitRescueMode, rescueModeStatus } from './core/boot-rescue.js';
+import { watch as fsWatch } from 'node:fs';
+import { recomputeRecoveryDecision, executeRecovery } from './core/reconcile.js';
+import { verifyRecovery, recoveryTerminalState } from './core/verify-recovery.js';
+import { createRecoveryOrchestrator } from './core/recovery-orchestrator.js';
+import { redactJournalText, isValidOperationId, isTerminalState, transitionJournalState, JournalStore } from './core/journal.js';
+import { RunRegistry } from './core/run-registry.js';
+import { registerModelTools } from './core/model-tools.js';
+import { computeConsultReport } from './core/migration-consult.js';
+import { readExportZipSource, buildLocalSnapshotSource, buildProfileSource } from './core/consult-source.js';
+import { makeMsg, msgOf, zhMsg } from './core/messages.js';
+import { cleanupAbortedInstall, hasDshBundlePatch, installErrorFor, installSpecFor, listInstalledPlugins, resolveProfileDir, resolveProfileNameFromArgv, readProfileManifest, runDshPlugin, validateProfileName, } from './core/plugin-cli.js';
+import { ImportNotConfirmedError, ImportUserSkippedError } from './core/types.js';
+import { createAdapters, USER_PATCH_FILE } from './adapters/index.js';
+import { createLocalPluginPackHook } from './core/local-plugin-host.js';
+import { createEncryptionProvider, decryptCredentials, decryptArchive, SecurityError, encryptArchive, isArchiveBlob, verifyEncryptedBlob } from './security/index.js';
+import { createHardenedZipParser } from './security/zip-security.js';
+import { atomicCopyFile, atomicWriteFile } from './utils/atomic-write.js';
+import { EnvironmentLockManager, runWithMutationLock, EnvironmentLockUnavailableError } from './utils/env-lock.js';
+import { activeProxySummary } from './utils/proxy.js';
+import { listRecursiveFollowingLinks } from './utils/recursive-walk.js';
+import { Phase3Recovery, TransactionRecoveryRequiredError, mapLockStateForStartup } from './core/phase3-host.js';
+import { classifyStartup } from './core/startup-barrier.js';
+import { GitTransport } from './sync/git/git-transport.js';
+import { WebDavTransport } from './sync/webdav/webdav-transport.js';
+import { DeviceFlowStore, GitHubAuthClient, GitHubAuthError } from './sync/github-auth.js';
+import { SyncEngine } from './sync/sync-engine.js';
+import { SyncSessionStore } from './sync/sync-session.js';
+import { AutoSyncScheduler } from './sync/autosync-scheduler.js';
+import { readAllAutosyncConfigs, readAutosyncConfig, writeAutosyncConfig } from './sync/autosync-config.js';
+import { appendAutosyncEntry, readSyncHistory } from './sync/sync-history.js';
+import { MigrationStore, queryHistory, summarizeHistory, renderExport, parseHistoryQuery, MIGRATION_HISTORY_DIR, } from './core/migration-history.js';
+import { loadSyncState, saveSyncState } from './sync/sync-state.js';
+import { readSyncConfig, readSyncConfigFor, readFullSyncConfig, writeSyncConfig, validateRepoUrl, validateWebDavUrl, isGitConfig, isWebDavConfig, } from './sync/sync-config.js';
+import { defaultSyncSelection, effectiveSections, readAllSyncSelections, readSyncSelection, writeSyncSelection, SYNC_SELECTION_SCHEMA_VERSION, } from './sync/sync-selection.js';
+import { readUiPrefs, updateUiPrefs } from './sync/ui-prefs.js';
+import { redact } from './security/redaction.js';
+import { createConfiguredSecretScanner } from './security/secret-scanner.js';
+import { sha256Hex } from './utils/hashing.js';
+import { MANIFEST_FILE, parseManifest } from './schema/manifest.js';
+import { isFileSection, SECTION_IDS } from './schema/config.js';
+import { stringifyJsonSafe } from './utils/json.js';
+import { parseZip, zipToBuffer } from './utils/zip.js';
+import { isSameOrChild, normalizePath } from './utils/paths.js';
+import { createLogger } from './utils/logger.js';
+/* ---------------------------------------------------------------- identity */
+/** Stable cordis plugin name — must match the cordis.patch.yml row id. */
+export const name = 'config-manager';
+/** Services required before the engine can mount (present in every profile). */
+export const inject = ['settings', 'credentials'];
+/** Plugin version, kept in sync with package.json ("version"). */
+const PLUGIN_VERSION = '0.1.60';
+/** Plugin own package name — excluded from its own exported plugins list. */
+const PLUGIN_NAME = 'dsh-config-manager';
+/**
+ * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
+ * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照
+ * 「一键上传」目标仓库先例）。仅在 GET /star-prompt 响应中返回，供弹窗按钮跳转。
+ */
+const STAR_PROMPT_REPO_URL = 'https://github.com/xiajiajun516/dsh-config-manager';
+/** 缓存自动清理周期：24 小时（启动即清一次 + 此后每日一次；与 cache-cleaner 保留期独立） */
+const CACHE_CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * 内置 GitHub OAuth App 的 client_id（「使用 GitHub 登录」device flow 缺省值）。
+ * Client ID 是公开标识（GitHub 官方明确非机密）：内置后所有安装者开箱即用，
+ * 无需各自注册/配置 OAuth App；token 仍按用户私有（各自授权、各自存 credentials）。
+ * 插件配置的 githubClientId 优先于本默认值（换自有 App 时覆盖）。
+ */
+export const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liq4i7n8UsylGRfb';
+/* ---------------------------------------------------------------- constants */
+/** Route family — must match the browser half's CONFIG_MANAGER_API exactly. */
+const API = {
+    // P2-⑫：导出前只读预览（不落盘 ZIP；返回各分区 counts + 估算大小）
+    // P1-⑧：快照管理（手动删除 + 置顶豁免自动清理）
+    // m-backup-schedule：定时全量备份（读/存 backup-schedule.json + 立即执行一次）
+    // m-backup-files：导出产物管理（列出 exports/*.zip + 删除；下载复用 /download）
+    // Phase 7：迁移前咨询（只读健康评分 + 建议；POST，loopback fence）
+    // m-sync-ui：远程同步（Git 私有仓库通道）
+    syncStatus: '/api/dsh-config-manager/sync/status',
+    syncPush: '/api/dsh-config-manager/sync/push',
+    syncPull: '/api/dsh-config-manager/sync/pull',
+    // m-github-oauth：GitHub OAuth device flow 登录（start → 展示授权码 → poll → token 入库）
+    syncGithubStart: '/api/dsh-config-manager/sync/github/start',
+    syncGithubPoll: '/api/dsh-config-manager/sync/github/poll',
+    syncGithubCancel: '/api/dsh-config-manager/sync/github/cancel',
+    // m-sync-github-valid：校验已存 token 是否有效（决定「已登录」→ 隐藏登录区块）
+    syncGithubValidate: '/api/dsh-config-manager/sync/github/validate',
+    // P2：同步历史 / 自动应用 / 一键回滚
+    syncHistory: '/api/dsh-config-manager/sync/history',
+    syncRollback: '/api/dsh-config-manager/sync/rollback',
+    // m-sync-v2：一键同步（差异确认会话）+ 自动同步 + 历史快照
+    syncSnapshotsList: '/api/dsh-config-manager/sync/snapshots-list',
+    syncSync: '/api/dsh-config-manager/sync/sync',
+    syncApplyItems: '/api/dsh-config-manager/sync/apply-items',
+    syncCancel: '/api/dsh-config-manager/sync/cancel',
+    syncAutosync: '/api/dsh-config-manager/sync/autosync',
+    // m-sync-selection：同步分区选择持久化（默认/高级模式 + 勾选分区；自动同步共用）
+    syncSelection: '/api/dsh-config-manager/sync/selection',
+    // m-sync-config：同步通道配置保存（UI 表单自动保存 /「保存配置」按钮；凭据写 DSH credentials）
+    syncConfig: '/api/dsh-config-manager/sync/config',
+    // m-self：插件 UI 偏好（如上次选择的同步通道；ui-prefs.json，随 self 分区进备份）
+    syncUiPrefs: '/api/dsh-config-manager/sync/ui-prefs',
+    // m-star-prompt：Star 引导弹窗状态（复用 ui-prefs.json；GET 读 + POST 局部更新）
+    // 版本更新内容弹窗状态（复用 ui-prefs.json；GET 读 + POST 局部更新）
+    // m-market：配置市场（内置单仓库，只读公开仓库：浏览 + 下载 + 安全校验；apply 复用 execute）
+    // m-my-configs：「一键上传 / 我的配置」（目标仓库固定 xiajiajun516/dsh-config-market；
+    // 登录复用 sync/github/start|poll|cancel，不重复实现；/me/items 401 → 未登录）
+    // m-profiles：配置档案（Profile = 一组可切换的配置快照；Save/List/Delete/Rename/Switch/Import）
+    // Phase 5：recovery 编排（prefix 路由，内部按 path 分发：status / <opId>/preview|confirm|execute|verify|retry|dismiss）
+    // Phase 6：迁移历史审计（统一历史引擎；只读 GET + 导出）
+    // Phase 1 P0-1/P0-2：配置生命周期（自动快照 / 撤销 / 重做）与崩溃归因
+    // Phase 1 P0-3：启动救援模式（禁用其它插件使 DSH 能启动）
+};
+/**
+ * 灾备子系统（Phase 1）总开关 —— 临时下线，待相关缺陷修复后再放出。
+ *
+ * 置 false 时整个灾备子系统停摆：
+ *  - 不启动配置变更监听 → 不产生自动快照（也不再刷「配置快照超出上限」告警）
+ *  - 不写 boot-state → 崩溃归因无观测数据（不影响启动）
+ *  - /lifecycle /crash /rescue 三条路由一律 503 feature-disabled
+ *
+ * 与客户端导航入口开关配套：src/client/ConfigManagerSection.tsx 的 SHOW_LIFECYCLE_NAV。
+ * 两者都置 true 才是一套完整的灾备功能。
+ *
+ * 为什么整体下线而不是只停自动快照：自动快照的采集走**全部 adapter**，其中 sessions
+ * 分区（历史会话，本机实测 340 MB）远超快照 64 MiB 上限，必然持续失败并刷告警；
+ * 在该缺陷修好前，撤销/重做/救援也没有可信的快照基线可用。
+ */
+const LIFECYCLE_ENABLED = false;
+/**
+ * 同步 token 的 DSH credentials 引用名（POSIX env-var 形态，满足 CredentialRef 品牌要求）。
+ * token 只经 credentialRef 读写（写入由请求体触发，读取在每次 git 网络操作时 resolve），
+ * 永不进 repoUrl / argv / commit / 同步文件 / 日志。
+ */
+export const SYNC_CREDENTIAL_REF = 'DSH_CONFIG_MANAGER_SYNC_TOKEN';
+/**
+ * WebDAV 通道口令的独立 DSH credentials 引用（与 git token 槽位分离）。
+ * 口令只经 credentialRef 读写（写入由请求体触发，读取在每次 WebDAV 网络操作时
+ * by WebDavTransport 经注入的 getPassword() resolve），永不进 URL / 请求头 / 日志。
+ */
+export const SYNC_WEBDAV_CREDENTIAL_REF = 'DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD';
+/** Cap on JSON request bodies (import plans can be large: 4 MB). */
+const MAX_JSON_BODY_BYTES = 4 * 1024 * 1024;
+/** Cap on raw upload bodies (staged to the controlled tmp dir). */
+const MAX_UPLOAD_BYTES = 256 * 1024 * 1024;
+/* ---------------------------------------------------------- loopback fence */
+/** Loopback literal check plus browser same-origin markers (dsh-ssh's fence). */
+function isLoopbackRequest(request) {
+    const address = request.socket.remoteAddress;
+    if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1')
+        return false;
+    const host = request.headers.host;
+    if (typeof host !== 'string')
+        return false;
+    let hostUrl;
+    try {
+        hostUrl = new URL(`http://${host}`);
+    }
+    catch {
+        return false;
+    }
+    if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]')
+        return false;
+    if (request.headers['sec-fetch-site'] === 'cross-site')
+        return false;
+    const origin = request.headers.origin;
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === hostUrl.host;
+    }
+    catch {
+        return false;
+    }
+}
+/* ---------------------------------------------------------------- responses */
+function writeJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'referrer-policy': 'no-referrer',
+    });
+    res.end(payload);
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > MAX_JSON_BODY_BYTES)
+            return undefined;
+        chunks.push(buffer);
+    }
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** URL query helper (first value, decoded). */
+function queryParam(url, name) {
+    const value = url.searchParams.get(name);
+    return value === null ? undefined : value;
+}
+/** Stream a raw request body to a file, enforcing a byte cap. */
+async function writeRequestBodyToFile(req, dest, maxBytes) {
+    const sink = createWriteStream(dest);
+    let size = 0;
+    await new Promise((resolvePromise, reject) => {
+        req.on('error', reject);
+        sink.on('error', reject);
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                sink.destroy();
+                req.destroy();
+                reject(new Error(`upload body exceeds ${maxBytes} bytes`));
+            }
+        });
+        req.pipe(sink);
+        sink.on('finish', () => resolvePromise());
+    });
+    return size;
+}
+/* -------------------------------------------------------------- dsh version */
+/** 当前 DSH 应用语言（settings `locale` 命名空间的 preference；缺省 zh）。 */
+function resolveAppLanguage(ctx) {
+    try {
+        const descriptors = ctx.settings.describe({ redactSecrets: true });
+        const locale = descriptors.find((d) => String(d.ns) === 'locale');
+        const pref = locale?.value?.preference;
+        return pref === 'en' ? 'en' : 'zh';
+    }
+    catch {
+        return 'zh';
+    }
+}
+/** Resolve the real DSH version from the profile dependency tree (read-only). */
+function resolveDshVersion(home) {
+    const candidates = [
+        join(home, 'profiles', 'node_modules', '@deepseek-ai', 'dsh', 'package.json'),
+        join(home, 'profiles', 'web', 'node_modules', '@deepseek-ai', 'dsh', 'package.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            const parsed = JSON.parse(readFileSync(p, 'utf8'));
+            if (typeof parsed.version === 'string' && parsed.version !== '')
+                return parsed.version;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return 'unknown';
+}
+/* ------------------------------------------------------------ profile name */
+/** 解析管理的 profile：config.profile → 启动参数 --profile → 'web'。 */
+function resolveProfileName(config) {
+    const configured = config?.profile;
+    if (configured !== undefined && configured !== '')
+        return validateProfileName(configured);
+    return resolveProfileNameFromArgv();
+}
+/* ------------------------------------------------------- HostContext facades */
+/** Optional Cordis service reader (never injected → never blocks the fiber). */
+function readService(ctx, serviceName) {
+    const candidate = ctx.get(serviceName);
+    return candidate === null || typeof candidate !== 'object' ? undefined : candidate;
+}
+/** Safe settings namespace converter compatible across DSH 0.1.1 and 0.1.2-alpha.x */
+const SETTINGS_NAMESPACE_REGEX = /^[a-z][a-z0-9-]*$/;
+function safeSettingsNamespace(namespace) {
+    const fn = dshSettings.settingsNamespace;
+    if (typeof fn === 'function') {
+        return fn(namespace);
+    }
+    if (!SETTINGS_NAMESPACE_REGEX.test(namespace)) {
+        throw new TypeError(`settings namespace "${namespace}" must match ${String(SETTINGS_NAMESPACE_REGEX)}`);
+    }
+    return namespace;
+}
+/** Safe credential ref converter compatible across DSH 0.1.1 and 0.1.2-alpha.x */
+const CREDENTIAL_REF_REGEX = /^[A-Z_][A-Z0-9_]*$/;
+function safeCredentialRef(ref) {
+    const fn = dshCredentials.credentialRef;
+    if (typeof fn === 'function') {
+        return fn(ref);
+    }
+    if (!CREDENTIAL_REF_REGEX.test(ref)) {
+        throw new TypeError(`credential ref "${ref}" must match ${String(CREDENTIAL_REF_REGEX)}`);
+    }
+    return ref;
+}
+const credentialRef = safeCredentialRef;
+/** Settings facade over the real ctx.settings (describe() is namespace-less). */
+class DshSettingsFacade {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    provider() {
+        return this.ctx.settings;
+    }
+    async describe(namespace, opts) {
+        const all = this.provider().describe({ redactSecrets: opts?.redactSecrets ?? true });
+        const descriptor = all.find((d) => String(d.ns) === namespace);
+        if (!descriptor)
+            throw new Error(`namespace not found: ${namespace}`);
+        return {
+            value: descriptor.value,
+            base: descriptor.base,
+            revision: descriptor.revision,
+            // Real service reports a single applies value; the core contract is an array.
+            applies: descriptor.applies === undefined ? undefined : [descriptor.applies],
+            secrets: descriptor.secrets ?? [],
+        };
+    }
+    async replace(namespace, value, expectedRevision) {
+        await this.provider().replace(safeSettingsNamespace(namespace), value, expectedRevision);
+    }
+    async update(namespace, patch, expectedRevision) {
+        await this.provider().update(safeSettingsNamespace(namespace), patch, expectedRevision);
+    }
+}
+/** Credentials facade over the real ctx.credentials (values never round-trip). */
+class DshCredentialsFacade {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async describe(ref) {
+        const info = await this.ctx.credentials.describe(safeCredentialRef(ref));
+        return { configured: info.configured, source: info.source, writable: info.writable };
+    }
+    async set(ref, value) {
+        await this.ctx.credentials.set(safeCredentialRef(ref), value);
+    }
+    async unset(ref) {
+        await this.ctx.credentials.unset(safeCredentialRef(ref));
+    }
+}
+/** 包名 → patch 行 id slug（仿 marketplace ensureRow）：去 @、非法字符→-、连续-合并、去首尾-。 */
+export function slugOf(name) {
+    return name.replace(/^@/, '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '');
+}
+/** 某 patch 行（raw）是否激活了指定包名（兼容单行与 insert 块成员）。 */
+export function patchRowActivates(raw, name) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const obj = raw;
+    const entries = Array.isArray(obj['insert']) ? obj['insert'] : [obj];
+    return entries.some((e) => e !== null && typeof e === 'object' && e['name'] === name);
+}
+/**
+ * 非 bundle 插件安装成功后，幂等补 profile cordis.patch.yml 激活行
+ * （{id: pm-<slug>, name: <pkg>}，仿 marketplace ensureRow）。bundle 包不写行
+ * （CLI 的 reconcile 已维护 dsh.profile.bundles）。
+ */
+export async function ensureActivationRow(patchFile, pkgDir, pkg) {
+    if (hasDshBundlePatch(pkgDir))
+        return;
+    const lines = await patchFile.readPatchLines(PROFILE_PATCH_FILE);
+    if (lines.some((l) => patchRowActivates(l.raw, pkg)))
+        return;
+    const id = `pm-${slugOf(pkg)}`;
+    await patchFile.applyPatchChanges(PROFILE_PATCH_FILE, [
+        { lineId: id, raw: { id, name: pkg }, action: 'insert' },
+    ]);
+}
+/**
+ * Plugins facade：官方 dsh plugin CLI 通道（任何 profile 可用）+ profile 文件
+ * 实时清单 + 非 bundle 插件激活行幂等补写。不再依赖 web 专用
+ * pluginMarketplace / pluginInventory 服务。
+ *
+ * 导出 + runner 可注入：M5 单测用 mock runner 验证「无 marketplace 时 install
+ * 走 CLI 通道」的行为契约，不触发真实子进程；生产路径默认参数不变。
+ */
+export class DshPluginsFacade {
+    homeDir;
+    profile;
+    patchFile;
+    msg;
+    runner;
+    constructor(homeDir, profile, patchFile, runner = runDshPlugin, msg = zhMsg) {
+        this.homeDir = homeDir;
+        this.profile = profile;
+        this.patchFile = patchFile;
+        this.runner = runner;
+        this.msg = msg;
+    }
+    async listInstalled() {
+        return listInstalledPlugins(this.homeDir, this.profile);
+    }
+    async install(pkg, spec, signal) {
+        const profileDir = resolveProfileDir(this.homeDir, this.profile);
+        // 非 registry 来源（github:/git+/file: 等）按来源 spec 安装；registry 包按裸包名装
+        // npm 最新版（官方机制）。spec 丢失（旧备份）时退化为裸包名 → pnpm fetch-404，
+        // 由 installErrorFor 给出可操作诊断。
+        const result = await this.runner(profileDir, this.profile, ['add', installSpecFor(pkg, spec)], undefined, signal);
+        // 用户「跳过当前插件」：宿主 kill 了子进程 → 清理半装状态（删依赖行 + 删 node_modules/<pkg>，
+        // 防止「package.json 声明了依赖但没装全」导致 DSH 启动失败），再以跳过语义抛错。
+        if (result.aborted || (signal !== undefined && signal.aborted)) {
+            cleanupAbortedInstall(profileDir, pkg);
+            throw new ImportUserSkippedError(this.msg);
+        }
+        if (result.exitCode !== 0 || result.timedOut)
+            throw installErrorFor(pkg, result);
+        // 非 bundle 插件：CLI 只维护 bundles，需补 profile patch 激活行才能加载。
+        // 补写失败不吞：包已装但未激活，明确报错并允许重试（幂等补行）。
+        try {
+            await ensureActivationRow(this.patchFile, join(profileDir, 'node_modules', pkg), pkg);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(this.msg('host.activationRowFailed', { pkg, reason }));
+        }
+        return { needsRestart: true };
+    }
+}
+/** Workspace facade over the real ctx.workspaceRegistry. */
+class DshWorkspaceFacade {
+    ctx;
+    msg;
+    constructor(ctx, msg = zhMsg) {
+        this.ctx = ctx;
+        this.msg = msg;
+    }
+    registry() {
+        return readService(this.ctx, 'workspaceRegistry');
+    }
+    async listRecords() {
+        const registry = this.registry();
+        if (!registry)
+            return [];
+        return registry.list().map((w) => ({
+            id: String(w.id),
+            path: w.path,
+            title: w.title,
+            sessionIds: [...w.sessionIds].map(String),
+            createdAt: w.createdAt,
+            updatedAt: w.updatedAt,
+        }));
+    }
+    async writeRecord(record) {
+        const registry = this.registry();
+        if (!registry)
+            throw new Error(this.msg('host.workspaceUnavailable'));
+        const existing = registry.get(record.id);
+        if (existing) {
+            // DSH API 没有「整体覆盖」写通道：标题可更新；path/会话由 registry 依真实目录维护
+            if (record.title !== undefined && existing.title !== record.title)
+                await existing.setTitle(record.title);
+            return;
+        }
+        await registry.create(record.path, record.title);
+    }
+    async removeRecord(id) {
+        const registry = this.registry();
+        if (!registry)
+            return;
+        await registry.delete(id);
+    }
+}
+/** Profile 目录内的 patch 文件（非 bundle 插件激活行写入处，marketplace 同款路径）。 */
+const PROFILE_PATCH_FILE = 'cordis.patch.yml';
+/** Patch-file facade：用户 patch 层（$DSH_HOME/cordis.patch.yml）+ profile patch 层
+ * （$DSH_HOME/profiles/<name>/cordis.patch.yml），两者都在 home 根内。 */
+class DshPatchFileFacade {
+    homeDir;
+    profile;
+    msg;
+    constructor(homeDir, profile, msg = zhMsg) {
+        this.homeDir = homeDir;
+        this.profile = profile;
+        this.msg = msg;
+    }
+    patchPath(file) {
+        if (file === USER_PATCH_FILE)
+            return join(this.homeDir, USER_PATCH_FILE);
+        if (file === PROFILE_PATCH_FILE)
+            return join(this.homeDir, 'profiles', this.profile, PROFILE_PATCH_FILE);
+        throw new Error(this.msg('host.patchUnsupported', { user: USER_PATCH_FILE, profile: PROFILE_PATCH_FILE, file }));
+    }
+    async readPatchLines(file) {
+        const p = this.patchPath(file);
+        let text;
+        try {
+            text = await fs.readFile(p, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        let doc;
+        try {
+            doc = yaml.load(text);
+        }
+        catch {
+            return [];
+        }
+        if (!Array.isArray(doc))
+            return [];
+        const lines = [];
+        for (const item of doc) {
+            if (item === null || typeof item !== 'object')
+                continue;
+            const obj = item;
+            const insert = obj['insert'];
+            if (Array.isArray(insert)) {
+                for (const entry of insert) {
+                    if (entry === null || typeof entry !== 'object')
+                        continue;
+                    const id = entry['id'];
+                    if (typeof id === 'string' && id !== '')
+                        lines.push({ lineId: id, raw: entry });
+                }
+                continue;
+            }
+            const id = obj['id'];
+            if (typeof id === 'string' && id !== '')
+                lines.push({ lineId: id, raw: obj });
+        }
+        return lines;
+    }
+    async applyPatchChanges(file, changes) {
+        const p = this.patchPath(file);
+        // 1. Load the current document into an ordered lineId → raw table.
+        const rows = new Map();
+        const order = [];
+        let doc;
+        try {
+            doc = yaml.load(await fs.readFile(p, 'utf8'));
+        }
+        catch {
+            doc = undefined;
+        }
+        if (Array.isArray(doc)) {
+            for (const item of doc) {
+                if (item === null || typeof item !== 'object')
+                    continue;
+                const obj = item;
+                const insert = obj['insert'];
+                if (Array.isArray(insert)) {
+                    for (const entry of insert) {
+                        if (entry === null || typeof entry !== 'object')
+                            continue;
+                        const id = entry['id'];
+                        if (typeof id === 'string' && id !== '' && !rows.has(id)) {
+                            rows.set(id, entry);
+                            order.push(id);
+                        }
+                    }
+                    continue;
+                }
+                const id = obj['id'];
+                if (typeof id === 'string' && id !== '' && !rows.has(id)) {
+                    rows.set(id, obj);
+                    order.push(id);
+                }
+            }
+        }
+        // 2. Apply the changes.
+        for (const change of changes) {
+            if (change.action === 'remove') {
+                if (rows.delete(change.lineId)) {
+                    const at = order.indexOf(change.lineId);
+                    if (at >= 0)
+                        order.splice(at, 1);
+                }
+            }
+            else if (change.action === 'insert' || change.action === 'update') {
+                if (!rows.has(change.lineId))
+                    order.push(change.lineId);
+                rows.set(change.lineId, change.raw);
+            }
+        }
+        // 3. Rebuild: every id row is emitted as a top-level row. The loader treats
+        //    a top-level { id, name } row exactly like an `- insert:` block member
+        //    (dsh-base patch precedent), so the document stays semantically equal.
+        const out = [];
+        for (const id of order) {
+            const raw = rows.get(id);
+            if (raw !== undefined)
+                out.push(raw);
+        }
+        const text = '# rewritten by dsh-config-manager import (original comments not preserved)\n'
+            + yaml.dump(out);
+        await atomicWriteFile(p, text);
+    }
+}
+/** File facade over $DSH_HOME, confined to the home root. */
+class DshFileSystemFacade {
+    homeDir;
+    msg;
+    constructor(homeDir, msg = zhMsg) {
+        this.homeDir = homeDir;
+        this.msg = msg;
+    }
+    abs(relPath) {
+        const target = resolve(isAbsolute(relPath) ? relPath : join(this.homeDir, relPath));
+        if (!isSameOrChild(target, this.homeDir))
+            throw new Error(this.msg('host.fsPathEscape', { path: relPath }));
+        return target;
+    }
+    async readFile(relPath) {
+        return fs.readFile(this.abs(relPath));
+    }
+    async writeFile(relPath, data) {
+        // 原子写（Phase 1）：同目录 tmp + fsync + rename，覆盖所有经 HostContext.fs 的配置写
+        await atomicWriteFile(this.abs(relPath), data);
+    }
+    async exists(relPath) {
+        try {
+            await fs.access(this.abs(relPath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async copy(from, to) {
+        await atomicCopyFile(this.abs(from), this.abs(to));
+    }
+    async remove(relPath) {
+        await fs.rm(this.abs(relPath), { recursive: true, force: true });
+    }
+    /** 仅路径列表（既有契约）：委托 listRecursiveDetailed，丢弃诊断。 */
+    async listRecursive(dir) {
+        return (await this.listRecursiveDetailed(dir)).paths;
+    }
+    /**
+     * 跟随 junction / 符号链接的遍历 + 被跳过链接清单（issue #37）。
+     * 实现下沉到 utils/recursive-walk.ts（可用真实临时目录直接单测）。
+     */
+    async listRecursiveDetailed(dir) {
+        return listRecursiveFollowingLinks(this.abs(dir), this.homeDir);
+    }
+    async mkdir(dir) {
+        await fs.mkdir(this.abs(dir), { recursive: true });
+    }
+}
+/** The engine's HostContext over real DSH services. */
+class ConfigManagerHostContext {
+    platform = process.platform;
+    arch = process.arch;
+    homeDir;
+    dshVersion;
+    profile;
+    log;
+    msg;
+    /** 应用语言（resolveAppLanguage；导出历史报告 locale 用） */
+    language;
+    settings;
+    credentials;
+    plugins;
+    workspace;
+    patchFile;
+    fs;
+    /** Phase 2 跨进程环境锁端口（宿主注入；测试 mock 不注入 → 无锁环境） */
+    mutationLock;
+    /** Phase 3 SAFE MODE：注入同步谓词（读内存标志，供 withMutationLock isBlocked 用；env-lock 不识 policy） */
+    safeModeIsBlocked;
+    /** Phase 3 恢复/事务（JournalStore + reconcile + SAFE MODE + runJournaled）。apply() 注入。 */
+    phase3Recovery;
+    constructor(ctx, homeDir, profile) {
+        this.homeDir = homeDir;
+        this.dshVersion = resolveDshVersion(homeDir);
+        this.profile = profile;
+        this.language = resolveAppLanguage(ctx);
+        this.msg = makeMsg(this.language);
+        const level = process.env.DSH_CONFIG_MANAGER_LOG_LEVEL;
+        this.log = createLogger({
+            level: level === 'debug' || level === 'info' || level === 'warn' || level === 'error' ? level : 'info',
+        });
+        this.settings = new DshSettingsFacade(ctx);
+        this.credentials = new DshCredentialsFacade(ctx);
+        this.patchFile = new DshPatchFileFacade(homeDir, profile, this.msg);
+        this.plugins = new DshPluginsFacade(homeDir, profile, this.patchFile, undefined, this.msg);
+        this.workspace = new DshWorkspaceFacade(ctx, this.msg);
+        this.fs = new DshFileSystemFacade(homeDir, this.msg);
+    }
+}
+/* ---------------------------------------------------------------- routes */
+/** Controlled staging roots guard. */
+function isControlledPath(target, roots) {
+    const t = resolve(target);
+    return roots.some((root) => isSameOrChild(t, resolve(root)));
+}
+function dateStamp(d = new Date()) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+/** Minimal real dependency check (MCP §15): `which`/`where` probe. */
+async function dependencyAvailable(command) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        await promisify(execFile)(probe, [command], { windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 导出/导入执行超时（ms）。正常导出秒级完成；此上限只兜底「宿主卡死」场景，
+ * 让客户端拿到明确错误而不是永远停在进度条。 */
+const ROUTE_TIMEOUT_MS = 5 * 60 * 1000;
+/** WebDAV 单请求超时（ms）：慢速 WebDAV（如坚果云限速）上传大快照/读写索引
+ * 需要比 git 通道更宽裕的窗口；错误消息会带上实际 ms，便于用户判断。 */
+const WEBDAV_TIMEOUT_MS = 120_000;
+/** 带超时的 Promise：超时以明确错误拒绝（promise 自身由调用方负责，此处只计时）。 */
+async function withTimeout(promise, ms, message) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Decrypt an encrypted backup's credentials (in-memory only; undefined when not applicable). */
+async function tryDecryptCredentials(zipPath, password) {
+    if (password === undefined || password === '')
+        return undefined;
+    const raw = await fs.readFile(zipPath);
+    const archive = parseZip(raw);
+    if (!archive.has(MANIFEST_FILE))
+        return undefined;
+    let manifest;
+    try {
+        manifest = parseManifest(archive.readEntryText(MANIFEST_FILE));
+    }
+    catch {
+        return undefined;
+    }
+    if (!manifest.security.encrypted || manifest.security.encryption === null)
+        return undefined;
+    if (!archive.has('security/secrets.enc'))
+        return undefined;
+    const blob = archive.readEntry('security/secrets.enc');
+    const plaintext = await decryptCredentials(blob, manifest.security.encryption, password);
+    let parsed;
+    try {
+        parsed = yaml.load(plaintext);
+    }
+    catch {
+        return undefined;
+    }
+    const map = new Map();
+    if (parsed !== null && typeof parsed === 'object') {
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'string' && v !== '')
+                map.set(k, v);
+        }
+    }
+    return map;
+}
+/** 解密错误 → 用户可读文本：BAD_PASSWORD 只报「密码错误」（不泄内部细节），其余原文 */
+function decryptErrorText(error, msg) {
+    if (error instanceof SecurityError && error.code === 'BAD_PASSWORD') {
+        return msg('import.encryptedPasswordWrong');
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/* -------------------------------------------------- sync 路由（m-sync-ui） */
+/** 同步路由可预期的请求级错误（status 缺省 400；引擎/传输失败走 500） */
+export class SyncRouteError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'SyncRouteError';
+        this.status = status;
+    }
+}
+/** 同步路由错误统一出口：SyncRouteError 用其 status，其余 500（GitTransport 错误消息已脱敏） */
+export function writeSyncRouteError(res, error) {
+    if (error instanceof SyncRouteError) {
+        writeJson(res, error.status, { error: error.message });
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    writeJson(res, 500, { error: message });
+}
+/**
+ * 解析同步请求体，按 transport 分支返回归一化的 SyncConfig（可辨识联合，schemaVersion=2）。
+ * 请求体形状（flat，M4 契约）：
+ * - git:    { transport:'git', repoUrl, token? } —— token 非空写 SYNC_CREDENTIAL_REF；
+ *   git 可执行文件固定使用系统 PATH 中的 git（不再接受自定义 gitBin）。
+ * - webdav: { transport:'webdav', url, username?, password? } —— password 非空写 SYNC_WEBDAV_CREDENTIAL_REF。
+ * 返回值不含任何 secret（password/token 只进 credentials，永不回传/落同步文件）。
+ */
+export async function parseSyncBody(body, deps) {
+    const transport = body['transport'] === 'webdav' ? 'webdav' : 'git';
+    if (transport === 'webdav') {
+        const url = typeof body['url'] === 'string' ? body['url'].trim() : '';
+        if (url === '')
+            throw new SyncRouteError('url is required for webdav');
+        const urlError = validateWebDavUrl(url);
+        if (urlError !== null)
+            throw new SyncRouteError(urlError);
+        const username = typeof body['username'] === 'string' && body['username'] !== '' ? body['username'] : undefined;
+        const password = typeof body['password'] === 'string' && body['password'] !== '' ? body['password'] : undefined;
+        if (password !== undefined) {
+            try {
+                await deps.credentials.set(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF), password);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new SyncRouteError(`WebDAV 口令写入 DSH credentials 失败：${reason}（请在 DSH 凭据管理里配置 ${SYNC_WEBDAV_CREDENTIAL_REF} 后重试）`);
+            }
+        }
+        return {
+            schemaVersion: 2,
+            transport: 'webdav',
+            webdav: { url, ...(username !== undefined ? { username } : {}) },
+        };
+    }
+    // git 通道（沿用现有逻辑）
+    const repoUrl = typeof body['repoUrl'] === 'string' ? body['repoUrl'].trim() : '';
+    if (repoUrl === '')
+        throw new SyncRouteError('repoUrl is required');
+    const urlError = validateRepoUrl(repoUrl);
+    if (urlError !== null)
+        throw new SyncRouteError(urlError);
+    const token = typeof body['token'] === 'string' && body['token'] !== '' ? body['token'] : undefined;
+    if (token !== undefined) {
+        try {
+            await deps.credentials.set(credentialRef(SYNC_CREDENTIAL_REF), token);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new SyncRouteError(`token 写入 DSH credentials 失败：${reason}（请在 DSH 凭据管理里配置 ${SYNC_CREDENTIAL_REF} 后重试）`);
+        }
+    }
+    return {
+        schemaVersion: 2,
+        transport: 'git',
+        git: { repoUrl },
+    };
+}
+/** 由 SyncConfig 合成 WebDAV 通道 baseUrl（webdav.url，尾部规范化带 '/'；git 通道返回 ''）。 */
+export function webdavBaseUrl(cfg) {
+    if (!isWebDavConfig(cfg))
+        return '';
+    return cfg.webdav.url.replace(/\/+$/, '') + '/';
+}
+/**
+ * 补全 webdav 配置缺失的 username（从持久化配置回填；纯函数，不修改入参）。
+ * 语义与 password 一致：请求未带 username（表单留空/挂载自动加载）→ 沿用已保存的值；
+ * 请求显式带 username → 原样保留（用户新输入优先）。非 webdav / 无持久化 → 原样返回。
+ */
+export function mergePersistedWebDavUsername(cfg, persisted) {
+    if (!isWebDavConfig(cfg) || (cfg.webdav.username !== undefined && cfg.webdav.username !== ''))
+        return cfg;
+    if (persisted !== null && isWebDavConfig(persisted)
+        && typeof persisted.webdav.username === 'string' && persisted.webdav.username !== '') {
+        return { ...cfg, webdav: { ...cfg.webdav, username: persisted.webdav.username } };
+    }
+    return cfg;
+}
+/**
+ * 解析 push 请求体的分区选择（sections）——「高级/自定义导出」模式负载。
+ * - 缺省 / 非数组 / 空数组 → undefined（= 全部 portable 推荐分区，即「默认/快速导出」模式）；
+ * - 元素必须是 knownIds（已知 adapter id）中的非空字符串，非法 → SyncRouteError（不静默吞错）；
+ * - 返回去重后的数组（保持原顺序；重复分区不做重复导出）。
+ */
+export function extractSyncSections(body, knownIds) {
+    const raw = body['sections'];
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== 'string' || item === '') {
+            throw new SyncRouteError('sections must be an array of non-empty strings');
+        }
+        if (!knownIds.has(item)) {
+            throw new SyncRouteError(`unknown sync section: ${item}`);
+        }
+        if (!seen.has(item)) {
+            seen.add(item);
+            out.push(item);
+        }
+    }
+    return out;
+}
+/** 需要人工决策的 PlanItemKind（一键同步 needsReview 判定 + 逐项确认标记）。
+ * 注意：'Install'（安装插件）不在此列 —— 同步拉取差异时插件按「自动安装」处理：
+ * 默认采纳、不逐项展示、无需手动选择（product requirement）。
+ * issue #35：'Warning' 必须**可见**——它承载「本次同步会剔除哪些无法满足的声明」这类
+ * 改变配置语义的信息；此前非决策项默认自动采用且不展示，用户只看到「同步成功」。 */
+const REVIEW_KINDS = new Set([
+    'Conflict', 'MissingSecret', 'MissingDependency', 'Error', 'PathMapping', 'Warning',
+]);
+/**
+ * issue #35：会**改变工具链行为**的项 —— 只有 pnpm-workspace.yaml 在本次同步中
+ * 移除了无法满足的 patchedDependencies 声明时，才带 detail。
+ * 这类项此前属「非冲突项 → 自动采用且不展示」，用户即使已知风险也无法否决
+ * （issue #35 正是这条自动采用把目标机 pnpm 弄坏的）。
+ * 现在：进确认列表、可见、可取消；但**默认仍采用**（我们的 sanitize 结果严格更安全，
+ * 默认不采用反而会静默丢掉 allowBuilds / 冷静期配置）。
+ * 注意：与客户端 sync-view.ts 的同名判定必须保持一致（两侧刻意重复，避免跨端 import）。
+ */
+function isToolchainChangeItem(item) {
+    return item.itemId === 'plugins:pnpm-workspace' && item.detail !== undefined && item.detail !== '';
+}
+/** 把 ImportPlan 投影为逐项可确认的差异项（默认采用 Create/Update/Install；人工项默认不采用）。 */
+function planToConfirmItems(plan) {
+    return plan.items.map((item) => {
+        const manual = REVIEW_KINDS.has(item.kind);
+        let conflict;
+        if (item.kind === 'Conflict') {
+            const c = item.conflict;
+            conflict = {
+                path: c?.path ?? '$',
+                kind: c?.kind === 'file' ? 'file' : c?.kind === 'section' ? 'section' : 'key',
+                ...(c?.local !== undefined ? { local: c.local } : {}),
+                ...(c?.remote !== undefined ? { remote: c.remote } : {}),
+                ...(c?.ancestor !== undefined ? { ancestor: c.ancestor } : {}),
+            };
+        }
+        return {
+            itemId: item.id,
+            adapter: item.adapter,
+            kind: item.kind,
+            description: item.description,
+            detail: item.detail,
+            severity: item.severity,
+            defaultAdopt: !manual,
+            adopt: !manual,
+            ...(conflict !== undefined ? { conflict } : {}),
+            ...(item.target !== undefined ? { target: item.target } : {}),
+        };
+    });
+}
+/** autosync interval 类型守卫 */
+function isAutosyncInterval(v) {
+    return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h';
+}
+/** 自动同步状态响应（GET /sync/autosync 与 POST 回填；读盘计算 elapsedMs）。 */
+async function buildAutosyncStatus(dir, channel) {
+    const cfg = await readAutosyncConfig(dir, channel);
+    const elapsedMs = cfg.lastRunAt === undefined || cfg.lastRunAt === ''
+        ? -1
+        : Math.max(0, Date.now() - Date.parse(cfg.lastRunAt));
+    return {
+        enabled: cfg.enabled,
+        interval: cfg.interval,
+        ...(cfg.lastRunAt !== undefined ? { lastRunAt: cfg.lastRunAt } : {}),
+        ...(cfg.lastRunStatus !== undefined ? { lastRunStatus: cfg.lastRunStatus } : {}),
+        ...(cfg.lastRunMessage !== undefined ? { lastRunMessage: cfg.lastRunMessage } : {}),
+        consecutiveFailures: cfg.consecutiveFailures,
+        elapsedMs,
+        ...(cfg.lastRunHistoryId !== undefined ? { lastRunHistoryId: cfg.lastRunHistoryId } : {}),
+    };
+}
+/** 全部通道的自动同步状态（status 路由一次返回；UI 按当前 tab 取对应通道）。 */
+async function buildAutosyncStatusByChannel(dir) {
+    const all = await readAllAutosyncConfigs(dir);
+    const build = async (channel) => {
+        const cfg = all[channel];
+        const elapsedMs = cfg.lastRunAt === undefined || cfg.lastRunAt === ''
+            ? -1
+            : Math.max(0, Date.now() - Date.parse(cfg.lastRunAt));
+        return {
+            enabled: cfg.enabled,
+            interval: cfg.interval,
+            ...(cfg.lastRunAt !== undefined ? { lastRunAt: cfg.lastRunAt } : {}),
+            ...(cfg.lastRunStatus !== undefined ? { lastRunStatus: cfg.lastRunStatus } : {}),
+            ...(cfg.lastRunMessage !== undefined ? { lastRunMessage: cfg.lastRunMessage } : {}),
+            consecutiveFailures: cfg.consecutiveFailures,
+            elapsedMs,
+            ...(cfg.lastRunHistoryId !== undefined ? { lastRunHistoryId: cfg.lastRunHistoryId } : {}),
+        };
+    };
+    return { git: await build('git'), webdav: await build('webdav') };
+}
+export function buildRestoreBody(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return { ok: false, error: 'invalid JSON body' };
+    }
+    const record = body;
+    const snapshotId = record['snapshotId'];
+    if (typeof snapshotId !== 'string' || snapshotId === '') {
+        return { ok: false, error: 'snapshotId is required' };
+    }
+    if (snapshotId === '.' || snapshotId === '..' || snapshotId.includes('/') || snapshotId.includes('\\')) {
+        return { ok: false, error: zhMsg('restore.invalidSnapshotId') };
+    }
+    return { ok: true, value: { snapshotId, dryRun: record['dryRun'] === true } };
+}
+/**
+ * 按计划执行恢复动作（纯执行器；逐项 try/catch 不拖垮其余），
+ * 返回与 CLI 一致的诚实报告。顺序 = 计划顺序（整文件 → 插件 → file 补偿）。
+ * @param onAction - 每项动作执行回调（宿主路由埋点：更新 RunRegistry 进度；
+ *   index/1-based、total=计划动作数、detail=动作描述）
+ */
+export async function executeRestorePlan(plan, exec, onAction) {
+    const report = {
+        snapshotId: plan.snapshotId,
+        restored: [],
+        removedPlugins: [],
+        manualHints: [],
+        failed: [],
+        skipped: [],
+    };
+    const total = plan.actions.length;
+    let index = 0;
+    for (const action of plan.actions) {
+        index += 1;
+        onAction?.({ index, total, detail: action.description });
+        try {
+            switch (action.kind) {
+                case 'hostFileRestore':
+                case 'fileRestore': {
+                    if (action.target === undefined || action.blobPath === undefined) {
+                        throw new Error('恢复动作缺少 target/blobPath');
+                    }
+                    if (await exec.existsHome(action.target))
+                        await exec.savePreRestore(action.target);
+                    await exec.writeHome(action.target, await exec.readBlob(action.blobPath));
+                    report.restored.push(action.target);
+                    break;
+                }
+                case 'hostFileRemove':
+                case 'fileRemove': {
+                    if (action.target === undefined)
+                        throw new Error('恢复动作缺少 target');
+                    if (await exec.existsHome(action.target)) {
+                        await exec.savePreRestore(action.target);
+                        await exec.removeHome(action.target);
+                    }
+                    report.restored.push(action.target);
+                    break;
+                }
+                case 'pluginRemove': {
+                    if (action.pluginName === undefined)
+                        throw new Error('恢复动作缺少插件名');
+                    const result = await exec.uninstallPlugin(action.pluginName);
+                    if (result.ok) {
+                        report.removedPlugins.push(action.pluginName);
+                    }
+                    else {
+                        report.failed.push({ item: `plugin:${action.pluginName}`, reason: result.message ?? '卸载失败' });
+                    }
+                    break;
+                }
+                case 'credentialHint':
+                    report.manualHints.push(action.manualHint ?? action.description);
+                    break;
+                case 'skip':
+                    report.skipped.push(action.description);
+                    break;
+                default:
+                    report.skipped.push(`未知动作 ${String(action.kind)}: ${action.description}`);
+            }
+        }
+        catch (err) {
+            report.failed.push({
+                item: action.target ?? action.pluginName ?? action.description,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return report;
+}
+/** 宿主 restore 执行器装配：ctx.fs（home-relative）+ 快照目录（node fs）+ runDshPlugin。 */
+function makeRestoreExecutor(snapshotDir, host, profile) {
+    const profileDir = resolveProfileDir(host.homeDir, profile);
+    let seq = 0;
+    return {
+        readBlob: async (blobPath) => {
+            const target = resolve(snapshotDir, blobPath);
+            if (!isSameOrChild(target, snapshotDir))
+                throw new Error(msgOf(host)('host.restoreBlobEscape', { blob: blobPath }));
+            return fs.readFile(target);
+        },
+        savePreRestore: async (relPath) => {
+            const data = await host.fs.readFile(relPath);
+            seq += 1;
+            const safe = relPath.replace(/[\\/:*?"<>|]/g, '_');
+            await fs.mkdir(join(snapshotDir, 'pre-restore'), { recursive: true });
+            await fs.writeFile(join(snapshotDir, 'pre-restore', `${String(seq).padStart(4, '0')}-${safe}`), data);
+        },
+        existsHome: (relPath) => host.fs.exists(relPath),
+        writeHome: (relPath, data) => host.fs.writeFile(relPath, data),
+        removeHome: (relPath) => host.fs.remove(relPath),
+        uninstallPlugin: async (name) => {
+            const result = await runDshPlugin(profileDir, profile, ['remove', name]);
+            if (result.exitCode === 0)
+                return { ok: true };
+            const output = `${result.stderr}\n${result.stdout}`.trim();
+            const tail = output.split('\n').slice(-8).join('\n') || msgOf(host)('host.restoreNoOutput');
+            return { ok: false, message: msgOf(host)('host.restoreUninstallFailed', { name, code: String(result.exitCode), tail }) };
+        },
+    };
+}
+/**
+ * 解析「一键上传/我的配置」请求体的 form 字段：仅 { name, description?, categories?, mode? }。
+ * name 必填（非空字符串，trim 后取）；description 可选字符串；categories 可选字符串数组；
+ * mode 可选 'migrate' | 'share'（F6 分享模式，非法值忽略→缺省 migrate）。非法 → null（调用方返回 400）。
+ */
+function parseMeForm(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const name = typeof obj['name'] === 'string' ? obj['name'].trim() : '';
+    if (name === '')
+        return null;
+    const form = { name };
+    // update 模式的可选显式 id（「更新」按钮预填；upload 时省略）
+    const idRaw = obj['id'];
+    if (typeof idRaw === 'string' && idRaw.trim() !== '')
+        form.id = idRaw.trim();
+    const description = obj['description'];
+    if (typeof description === 'string' && description.trim() !== '')
+        form.description = description.trim();
+    const categoriesRaw = obj['categories'];
+    if (Array.isArray(categoriesRaw)) {
+        const categories = categoriesRaw.filter((c) => typeof c === 'string' && c.trim() !== '');
+        if (categories.length > 0)
+            form.categories = categories;
+    }
+    // F6 分享模式：仅接受字面量 'share' / 'migrate'（其余忽略 → 缺省 migrate），随 form 透传 MyRepoService
+    if (obj['mode'] === 'share' || obj['mode'] === 'migrate')
+        form.mode = obj['mode'];
+    return form;
+}
+/**
+ * GitHub 凭据「缺失或失效」判定（issue #29）：`no_token`（credentials 里从未配置 token）与
+ * `unauthorized`（401，token 过期/被撤销）对用户都是同一个「未登录」，必须走同一分支——
+ * 否则 `no_token` 会落到 500，UI 把「未登录」渲染成「登录状态读取失败」的误导性横幅。
+ * 其余分类（network_error / rate_limited / server_error / validation_failed / fork_timeout…）
+ * 是真实故障，仍按 500 暴露，绝不伪装成「未登录」。
+ */
+export function isGitHubAuthMissing(error) {
+    return error instanceof GitHubAuthError && (error.code === 'unauthorized' || error.code === 'no_token');
+}
+/**
+ * 读取插件诊断信息（issue #28）：把「插件到底读了哪个目录 / 哪个 profile / 看到什么」变成
+ * 用户可自查的数据——此前只存在于宿主内部，导致「装了插件却识别不到」无从定位。
+ * best-effort：失败不抛出（诊断位缺失不应拖垮 /status）。
+ */
+async function readPluginDiagnostics(host) {
+    try {
+        const profileDir = resolveProfileDir(host.homeDir, host.profile ?? 'web');
+        const manifest = readProfileManifest(profileDir);
+        const installed = await host.plugins.listInstalled();
+        const bundles = manifest?.dsh?.profile?.bundles;
+        return {
+            homeDir: host.homeDir,
+            profile: host.profile ?? 'web',
+            profileManifestReadable: manifest !== null,
+            installedPluginCount: installed.length,
+            installedPluginNames: installed.map((p) => p.name),
+            bundles: Array.isArray(bundles) ? bundles : [],
+        };
+    }
+    catch (err) {
+        host.log.warn(`plugin diagnostics unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        return {};
+    }
+}
+/** Build the /api/dsh-config-manager route family. */
+function makeRoutes(deps) {
+    const { host, adapters, exportsDir, tmpDir, snapshotsDir, runs, syncDir, dataDir, credentials, githubClientId, githubClientSecret, history } = deps;
+    /**
+     * Phase 1 P0-1/P0-2：配置生命周期服务（自动快照 / 撤销 / 重做）。
+     *
+     * 与既有 `snapshotsDir`（导入前快照，plan 驱动）**分目录**：那里的快照只登记
+     * 「本次导入将写入的目标」，无法回答「配置整体变没变」；本服务的快照是状态驱动，
+     * 供撤销/重做与自动快照使用。两者保留策略与回放方式都不同，混用会产生错误语义。
+     *
+     * watchFactory 用真 fs.watch 注入（core 侧只依赖抽象 → 测试可完全驱动时序）。
+     * 监听不在此处启动：由 apply() 在「启动 recovery 分类完成且 NORMAL」后启动，
+     * 避免恢复进行中就开拍。
+     */
+    const lifecycle = new ConfigLifecycle({
+        dir: join(dataDir, 'config-snapshots'),
+        adapters,
+        ctx: host,
+        profile: host.profile ?? 'web',
+        applyOrder: APPLY_ORDER,
+        onWarn: (message, detail) => {
+            host.log.warn(`[lifecycle] ${message}${detail !== undefined ? `: ${detail instanceof Error ? detail.message : String(detail)}` : ''}`);
+        },
+        watchFactory: (dir, onEvent) => fsWatch(dir, (eventType, filename) => onEvent(eventType, filename)),
+    });
+    const roots = [exportsDir, tmpDir];
+    /**
+     * Phase 6：迁移历史 best-effort 追加（写失败不阻断操作，但记录/降级，不静默丢）。
+     * 所有 destructive/migration 结果确定后调用。历史写盘 ms 级，失败仅日志 + 可选告警字段。
+     */
+    const tryAppendHistory = async (raw) => {
+        try {
+            const res = await history.append(raw);
+            if (!res.ok) {
+                host.log.warn('迁移历史写入失败', { kind: raw.kind, error: res.error });
+                return res.error;
+            }
+            return undefined;
+        }
+        catch (error) {
+            host.log.warn('迁移历史写入异常', { kind: raw.kind, error: error instanceof Error ? error.message : String(error) });
+            return error instanceof Error ? error.message : String(error);
+        }
+    };
+    /**
+     * 从快照目录读取 entries 的 adapter id 集（用于 restore / snapshot-prune 历史 sections）。
+     * 读取失败 → 空数组（best-effort；sections 仅用于审计摘要，不影响功能）。
+     */
+    const snapshotEntrySections = async (snapshotDir) => {
+        try {
+            const raw = await fs.readFile(join(snapshotDir, 'snapshot.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== 'object' || !Array.isArray(parsed.entries))
+                return [];
+            return Array.from(new Set(parsed.entries.map((e) => e.adapter).filter((s) => typeof s === 'string' && s !== '')));
+        }
+        catch {
+            return [];
+        }
+    };
+    /**
+     * Phase 6：自动快照保留清理（snapshot-prune）迁移历史（best-effort）。
+     * 由 FileSnapshotStore.prune 经 onPrune 回调触发；fire-and-forget 不阻塞保存。
+     */
+    const tryAppendSnapshotPrune = async (removedIds) => {
+        if (removedIds.length === 0)
+            return;
+        try {
+            await history.append({
+                kind: 'snapshot-prune',
+                result: 'success',
+                sections: [],
+                source: 'api',
+                summary: `自动保留清理删除 ${removedIds.length} 个旧快照`,
+            });
+        }
+        catch (error) {
+            host.log.warn('快照保留清理历史写入失败（best-effort）', { error: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    /** m-github-oauth：宿主侧设备码登记表 + auth 客户端（进程生命周期；device_code 只存内存） */
+    const githubFlows = new DeviceFlowStore();
+    const githubAuth = new GitHubAuthClient();
+    const msg = host.msg;
+    /** 导入 run 的「当前计划项」中止控制器（/execute 登记，/execute/skip 定位 abort）。
+     * 进程生命周期内存登记；同 kind 并发被 RunRegistry 拒绝，单 run 恒只有一个当前项。 */
+    const runAbortControllers = new Map();
+    /** 已知 adapter id 集合（push 请求体 sections 校验用）。 */
+    const knownSyncSectionIds = new Set(adapters.map((a) => a.id));
+    /** 可同步分区目录（status 回填 UI「高级/自定义导出」勾选列表）。
+     *
+     *  含**全部已挂载分区**（不再按 portability 过滤）：改造一取消了 portability 对同步范围的
+     *  限制，所有分区都可勾选；这里若仍只列 portable，mcp/workspaces/credentialsStatus/
+     *  pluginFiles/sessions 就永远无法被勾选，用户既看不到也同步不了。
+     *  列表顺序即 adapters 顺序；defaultIncluded 由 UI 用于「推荐分区」默认勾选与计数。 */
+    const syncSectionCatalog = adapters
+        .map((a) => ({ id: a.id, displayName: a.displayName, portability: a.portability, defaultIncluded: a.defaultIncluded }));
+    const makeImporter = () => new Importer({
+        ctx: host,
+        adapters,
+        snapshotStore: new FileSnapshotStore({
+            dir: snapshotsDir,
+            // Phase 4 F3：active/quarantine 未收敛 journal 引用的 snapshot 绝不自动 prune
+            referencedSnapshotIds: () => host.phase3Recovery?.store.listReferencedSnapshotIds() ?? Promise.resolve(new Set()),
+            // Phase 6：自动保留清理 → snapshot-prune 迁移历史（best-effort）
+            onPrune: (removedIds) => { void tryAppendSnapshotPrune(removedIds); },
+        }),
+        parseZipOverride: createHardenedZipParser(),
+        dependencyChecker: dependencyAvailable,
+        msg,
+    });
+    /** m-profiles：配置档案管理器（<dataDir>/profiles/<name>/profile.json；切换复用同一快照/回滚管道） */
+    const profiles = new ProfileManager({
+        dataDir,
+        ctx: host,
+        adapters,
+        snapshotStore: new FileSnapshotStore({
+            dir: snapshotsDir,
+            // Phase 4 F3：recovery 引用保护
+            referencedSnapshotIds: () => host.phase3Recovery?.store.listReferencedSnapshotIds() ?? Promise.resolve(new Set()),
+            // Phase 6：自动保留清理 → snapshot-prune 迁移历史（best-effort）
+            onPrune: (removedIds) => { void tryAppendSnapshotPrune(removedIds); },
+        }),
+    });
+    /** Fence + method guard (mirrors dsh-ssh). */
+    const guard = (req, res, method) => {
+        if (!isLoopbackRequest(req)) {
+            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+            return false;
+        }
+        if (req.method !== method) {
+            writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+            return false;
+        }
+        return true;
+    };
+    /**
+     * Phase 2 跨进程锁路由门（destructive 公共入口）。
+     * 包裹一个 mutation handler：进入前 acquire GLOBAL 环境锁（无 lock 配置 → 直接放行），
+     * 被另一进程/操作持有（含同进程另一操作）→ 409/423 拒绝；执行后 finally 释放。
+     * 嵌套调用（rollback / applyItems 内部 executeImportPlan）在外层已持锁区域内运行，绝不 reacquire。
+     * Phase 3 SAFE MODE：isBlocked 注入谓词（host.safeModeIsBlocked）被挡 → 423（不执行 destructive）。
+     */
+    const withMutationGate = (op, handler, opts) => {
+        return async (req, res) => {
+            try {
+                await runWithMutationLock(host.mutationLock, { op, isBlocked: () => host.safeModeIsBlocked?.() ?? false }, async (lockCtx) => {
+                    // Step 3 P0-A：所有被 gate 覆盖的 destructive 路由在已持锁下创建 durable journal
+                    // （runJournaled 不 double-acquire、不 release；锁由本 gate 的 finally 释放）。
+                    if (host.phase3Recovery !== undefined && (opts?.journaled ?? true) && lockCtx !== null) {
+                        await host.phase3Recovery.runJournaled({
+                            operationType: op,
+                            lockCtx,
+                            // Phase 4：生产 snapshot 接线。deferredSnapshot = plan 在 handler 内解析后，
+                            // 引擎创建 op-bound snapshot 并 bindSnapshot + markApplying（首个 destructive side effect 前）。
+                            deferredSnapshot: opts?.deferredSnapshot ?? false,
+                            fn: async (journalCtx) => { await handler(req, res, lockCtx, journalCtx); },
+                        });
+                    }
+                    else {
+                        await handler(req, res, lockCtx ?? undefined, undefined);
+                    }
+                });
+            }
+            catch (error) {
+                if (error instanceof EnvironmentLockUnavailableError) {
+                    // 内部诊断（op/reason）进日志；用户只看到友好文案（error.message 恒为中文友好版，
+                    // 不暴露环境锁/op/路径等技术细节）。
+                    host.log.warn(`mutation lock blocked: op=${error.op} reason=${error.reason}${error.detail !== undefined ? ` detail=${error.detail}` : ''}`);
+                    writeJson(res, 423, { error: error.message, code: 'mutation-locked' });
+                    return;
+                }
+                // 非 423：若已由 runJournaled 置 SAFE MODE/失败，保持既有错误语义（400/500）
+                if (error instanceof TransactionRecoveryRequiredError) {
+                    writeJson(res, 423, { error: error.message, code: 'transaction-recovery-required' });
+                    return;
+                }
+                throw error;
+            }
+        };
+    };
+    // ------------------------------------------------- sync 路由装配（m-sync-ui）
+    // 请求级装配：每次 push/pull 从请求体取 repoUrl，token 非空先写入 DSH
+    // credentials（只存值不落盘同步文件/日志），git 网络操作时经 resolve 现取 ——
+    // 与 GitTransport「token 只从注入 provider 读取」的安全契约完全对齐。
+    /**
+     * 解析同步请求体并补全缺失字段（委托给导出的 parseSyncBody，便于单测）。
+     * username 回退：webdav 请求体未带 username（如挂载时 snapshotsList 自动加载、
+     * 表单留空后直接同步）时，从持久化 sync-config 回填已保存的 username——
+     * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
+     * 语义与 password 一致：留空 = 沿用已保存凭据。
+     */
+    const prepareSync = async (body) => {
+        const cfg = await parseSyncBody(body, { credentials });
+        if (isWebDavConfig(cfg) && (cfg.webdav.username === undefined || cfg.webdav.username === '')) {
+            try {
+                const persisted = await readSyncConfig(syncDir);
+                return mergePersistedWebDavUsername(cfg, persisted);
+            }
+            catch {
+                return cfg; // 读失败保持原值（空 username 由 WebDavTransport 构造校验兜底报错）
+            }
+        }
+        return cfg;
+    };
+    /** 同步分区选择缓存（按通道；sync-selection.json；makeSyncEngine 同步读取用，保存路由更新）。
+     *  缺失通道 = 尚未加载（启动竞态窗口）；读取/使用处兜底 defaultSyncSelection。 */
+    const selectionCache = {};
+    void readAllSyncSelections(syncDir).then((all) => {
+        selectionCache.git = all.git;
+        selectionCache.webdav = all.webdav;
+    }).catch(() => { });
+    /** 确保指定通道缓存已加载（status/save 路由调用；启动竞态兜底）。 */
+    const ensureSelectionLoaded = async (channel) => {
+        const cached = selectionCache[channel];
+        if (cached !== undefined)
+            return cached;
+        try {
+            const sel = await readSyncSelection(syncDir, channel);
+            selectionCache[channel] = sel;
+            return sel;
+        }
+        catch {
+            const fallback = defaultSyncSelection();
+            selectionCache[channel] = fallback;
+            return fallback;
+        }
+    };
+    /** 指定通道的分区选择视图（{ mode, sections }，无 schemaVersion）。 */
+    const selectionView = async (channel) => {
+        const sel = await ensureSelectionLoaded(channel);
+        return { mode: sel.mode, sections: sel.sections };
+    };
+    /** 全部通道的分区选择视图（status 路由一次返回；UI 按当前 tab 取对应通道）。 */
+    const selectionViewByChannel = async () => {
+        const all = await readAllSyncSelections(syncDir);
+        selectionCache.git = all.git;
+        selectionCache.webdav = all.webdav;
+        const view = (sel) => ({ mode: sel.mode, sections: sel.sections });
+        return { git: view(all.git), webdav: view(all.webdav) };
+    };
+    /** 构造 SyncEngine：按 transport 分支构造对应传输（git → GitTransport；webdav → WebDavTransport）。
+     *  同步范围（sections）来自持久化分区选择：advanced 模式 → 只处理勾选分区，
+     *  自动同步（merge/apply/push 全链路）与手动 push 共用此配置。 */
+    const makeSyncEngine = (cfg) => {
+        let transport;
+        if (isWebDavConfig(cfg)) {
+            transport = new WebDavTransport({
+                baseUrl: webdavBaseUrl(cfg),
+                username: cfg.webdav.username ?? '',
+                credentials: {
+                    getPassword: async () => {
+                        const resolved = await credentials.resolve(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF));
+                        return resolved?.value ?? '';
+                    },
+                },
+                // 显式传超时：不依赖默认值，慢速 WebDAV 上传大快照有足够窗口
+                timeoutMs: WEBDAV_TIMEOUT_MS,
+                msg,
+            });
+        }
+        else {
+            transport = new GitTransport({
+                repoUrl: cfg.git.repoUrl,
+                workDir: join(syncDir, 'work'),
+                credentials: {
+                    getToken: async () => {
+                        const resolved = await credentials.resolve(credentialRef(SYNC_CREDENTIAL_REF));
+                        return resolved?.value ?? '';
+                    },
+                },
+                msg,
+            });
+        }
+        const channel = isWebDavConfig(cfg) ? 'webdav' : 'git';
+        const sections = effectiveSections(selectionCache[channel] ?? defaultSyncSelection());
+        return new SyncEngine({
+            ctx: host,
+            transport,
+            stateDir: syncDir,
+            adapters,
+            importer: makeImporter(),
+            localSnapshotsDir: join(syncDir, 'snapshots'),
+            zipDir: tmpDir,
+            msg,
+            ...(sections === undefined ? {} : { sections }),
+        });
+    };
+    /** 一键同步差异确认会话存储（进程内存；/sync/sync 预览 → /sync/apply-items 逐项执行解耦） */
+    const syncSessions = new SyncSessionStore();
+    /** 自动同步后台调度器（宿主进程生命周期，不依赖浏览器） */
+    const scheduler = new AutoSyncScheduler({
+        syncDir,
+        host,
+        makeSyncEngine,
+        msg,
+        runs,
+        mutationLock: host.mutationLock,
+        isBlocked: () => host.safeModeIsBlocked?.() ?? false,
+        phase3Recovery: host.phase3Recovery,
+        // Phase 6：autosync 既写 sync-history.json（既有语义），也写统一迁移历史（COMPLETE 不变量）。
+        appendHistoryFn: async (entry) => {
+            await appendAutosyncEntry(syncDir, entry).catch(() => undefined);
+            await history.append({
+                kind: 'autosync',
+                result: entry.status === 'success' ? 'success' : entry.status === 'skipped' ? 'skipped' : 'failed',
+                sections: entry.appliedSections ?? [],
+                source: 'autosync',
+                summary: `自动同步 ${entry.direction}${entry.transport !== undefined ? `（${entry.transport}）` : ''}`,
+                error: entry.status === 'failed' ? (entry.error ?? entry.skipReason) : undefined,
+            }).catch(() => undefined);
+        },
+    });
+    // P1-B：调度器不再在 makeRoutes 内同步 start —— 由 apply() 在「启动 recovery 分类完成后、仅 NORMAL」时启动。
+    // ============================================================ Phase 5 recovery orchestration
+    // Recovery 路由**禁用 withMutationGate**（避免 double-journal：recovery 复用被恢复 operation 的
+    // 现有 journal，不新建）。mutation 路由只经 withMutationLock（Phase 2 GLOBAL 锁）+ loopback fence，
+    // **不传 isBlocked**（recovery 是解决 SAFE MODE 的机制，若被 SAFE MODE 阻断会死锁）。
+    // 只读路由（status/preview）不持锁。权威 snapshotId 只来自 j.snapshotId（不接受请求体覆盖）。
+    // 编排逻辑在 src/core/recovery-orchestrator.ts（可测纯编排层）。
+    const recoveryOrchestrator = createRecoveryOrchestrator({
+        store: host.phase3Recovery?.store ?? new JournalStore({ transactionsDir: join(dataDir, 'transactions') }),
+        runs,
+        snapshotsDir,
+        host,
+        msg,
+        snapshotExists: async (snapshotId, binding) => {
+            if (host.phase3Recovery === undefined)
+                return false;
+            return host.phase3Recovery.recoveryHooks.snapshotExists(snapshotId, binding);
+        },
+        // 动态 getter：环境指纹在 fire-and-forget 启动分类块（initFingerprint）完成后才就绪，
+        // 创建期捕获会拿到 'unknown' 初值 → 后续 recovery API 误判 WRONG_ENVIRONMENT。
+        // 改动态读取保证 API 调用时取到真实指纹（recovery-orchestrator 已改为 getter 语义）。
+        getEnvironmentFingerprint: () => host.phase3Recovery?.recoveryEnvFingerprint ?? 'unknown',
+        // 清除 SAFE MODE：同时重置内存标志（isBlocked 读它）与 durable 标记。
+        // 仅当 recovery 成功且无其他未解决 incident 时由编排器调用（§5.3 / §10.2）。
+        clearSafeMode: async () => {
+            if (host.phase3Recovery !== undefined)
+                await host.phase3Recovery.clearSafeMode();
+        },
+        // issue #31：环境锁只读探测 + 显式回收，供「事故恢复」面板显示/处理**残留锁**。
+        // 残留锁不是 journal（journalId 恒 null、transactions/active 为空），旧面板因此恒空。
+        inspectLockState: async () => {
+            const port = host.mutationLock;
+            if (port === undefined)
+                return { state: 'FREE' };
+            const insp = await port.inspectLockState();
+            return { state: insp.state, ...(insp.detail !== undefined ? { detail: insp.detail } : {}) };
+        },
+        recoverStaleLock: async () => {
+            const port = host.mutationLock;
+            // 无锁端口（测试/未接线）→ 无可回收对象，诚实拒绝而非谎称成功
+            if (port === undefined)
+                return { ok: false, removed: false, state: 'FREE', detail: 'no lock port configured' };
+            return port.recoverStaleLock();
+        },
+    });
+    /** 构造 recovery 执行器（restore / rollback），供 execute/retry 注入（runId 用于进度埋点）。 */
+    const makeRecoveryExecutors = (runId) => ({
+        performRestore: async (snapshotId) => {
+            const dir = join(snapshotsDir, snapshotId);
+            const restoreOpts = {
+                snapshotDir: dir, homeDir: host.homeDir, profile: host.profile, settingsPath: undefined, msg,
+                snapshotsRoot: snapshotsDir, environmentFingerprint: host.phase3Recovery?.recoveryEnvFingerprint ?? 'unknown', requireOperationBound: true,
+            };
+            const plan = await planRestore(restoreOpts);
+            const report = await executeRestorePlan(plan, makeRestoreExecutor(dir, host, host.profile), (info) => {
+                runs.update(runId, { section: 'recovery', item: info.index, itemTotal: info.total, detail: info.detail });
+            });
+            return { full: report.failed.length === 0, failed: report.failed.map((f) => f.item) };
+        },
+        performRollback: async (snapshotId) => {
+            const store = new FileSnapshotStore({ dir: snapshotsDir });
+            const snap = await store.load(snapshotId);
+            const report = await performRollback({ ctx: host, snapshot: snap, store, adapters });
+            return { full: report.full, failed: report.failed.map((f) => f.item) };
+        },
+    });
+    const routesList = [
+        // ------------------------------------------------------------- status
+        // ------------------------------------------------------------- export
+        // ---------------------------------------------------- export-preview
+        // P2-⑫：导出前只读预览（不落盘 ZIP）：对选中分区逐个 adapter.export 收集 counts
+        // （与真实导出一致的 secret 剥离，不导出任何值），估算 JSON 载荷大小，返回可展示摘要。
+        // 零写入；loopback fence 必备。
+        // ------------------------------------------------------------ download
+        // -------------------------------------------------------------- upload
+        // ------------------------------------------------------ decrypt-archive
+        // 整体加密备份容器的解锁（只读，零写入到任何配置）：用备份密码解密上传的加密容器，
+        // 得到明文 ZIP 写入受控临时目录并返回新 zipPath，供 analyze/plan/execute 引用。
+        // 导出时容器密码与内部 secrets.enc 密码同源（同一 password 派生两层加密），
+        // 因此顺带在明文 ZIP 上解出内部凭据覆盖清单（refs，非值）一并返回——
+        // 导入全程只需输入这一次密码，无需第二个密码校验页面。
+        // 密码仅内存随请求体传入，绝不落盘/落日志；解出的明文 ZIP 亦为临时文件，导入结束后清理。
+        // ------------------------------------------------------------- analyze
+        // ---------------------------------------------------------------- plan
+        // ------------------------------------------------------------ progress
+        // m1：查询单个 run 的实时状态（轮询 / 刷新恢复用；runId 不可猜，走 loopback-only 守卫）
+        // ----------------------------------------------------------------- runs
+        // m1：列出当前活跃（running）的 run（刷新恢复时重新订阅进度用）
+        // ------------------------------------------------------------- execute
+        // -------------------------------------------------- execute/skip
+        // 用户跳过当前计划项（导入中，目前仅插件安装）：abort 当前项的中止控制器 → 引擎
+        // 捕获 ImportUserSkippedError 记为 user-skipped，导入继续执行其余项。
+        // ---------------------------------------------------------- snapshots
+        // M4：列出快照元信息（id/createdAt/sourceZip/status/计数，createdAt 倒序）
+        // ------------------------------------------------------------ restore
+        // M4：快照恢复。dryRun=true 只返回动作计划（planRestore，零写入）；
+        // 真实执行 = 计划 → 宿主执行器（ctx.fs 整文件/文件还原 + runDshPlugin 卸载插件）
+        // → 与 CLI 一致的诚实报告 { restored/removedPlugins/manualHints/failed/skipped }。
+        //
+        // **并发防护（P1-1）**：真实执行（dryRun=false）经 runs.register('restore') 登记——
+        // 同 kind 已有 running 时抛 RunConflictError → 409 拒绝。这是宿主侧的权威防重
+        // （前端 loading 只是 UX）：即使两个 tab / 刷新后重复点击，同一时刻至多一个
+        // restore 在执行（不同快照并发恢复会交错写文件，同快照并发会互相覆盖
+        // pre-restore 双保险备份，都是真实数据风险）。进度经 onAction 埋点更新
+        // RunRegistry（/progress 轮询 + /runs 刷新恢复可见）；响应含 runId。
+        // ------------------------------------------- snapshots/delete（P1-⑧）
+        // 手动删除单个快照（危险操作：该导入前回滚点不可恢复）。loopback fence（guard）；
+        // 只接受合法快照 id（deleteSnapshot 内防穿越）。与自动保留清理不同：置顶快照
+        // 只能在这里被用户手动删除。
+        // --------------------------------------------- snapshots/pin（P1-⑧）
+        // 置顶/取消置顶快照：置顶快照豁免「最多保留 N 个」的自动清理（只能手动删除）。
+        // 纯元数据写（重写 snapshot.json 的 pinned 字段）；loopback fence 必备。
+        // -------------------------------------------------- m-profiles
+        // 配置档案（Profile）：保存当前 DSH 配置为多套可切换快照（Work/Personal…）。
+        // 安全：Profile 名严格校验（ProfileManager 内部 isValidProfileName 防穿越）；
+        // 切换走「预览 → confirm → 快照 → 分阶段 apply → 失败回滚」与导入同一语义；
+        // Save 复用 adapter.export（天然不含秘密值）；全部路由 loopback fence。
+        // -------------------------------------------------- backup-schedule
+        // 定时全量备份设置（GET 读 / PUT 存 sync/backup-schedule.json；无敏感字段）：
+        // 保存后重排调度器（reload）；恒不含 secret、不加密（与自动同步同语义）。
+        // 与全仓一致：每个方法分支都过 loopback fence（guard）——其他 /api/dsh-config-manager/*
+        // 路由全部首行 guard，新增路由不得遗漏（安全不变量：仅 loopback + 同源可访问）。
+        // ------------------------------------------------- backup-schedule/run
+        // 返回执行结果（status/zip/skipReason/error）+ 最新配置（含 lastRun 状态）。
+        // 同全仓：loopback fence（guard）——远程调用方不得触发宿主写盘操作。
+        // ------------------------------------------------------ backup-files
+        // 导出产物管理（m-backup-files）：列出 exports/*.zip（名称/大小/时间/来源，
+        // 时间倒序）+ 删除单个备份文件。下载复用 /download（roots 已含 exportsDir）。
+        // 安全：删除只接受文件名（服务端 basename 校验防路径穿越）；恒 loopback guard。
+        // ------------------------------------------------------ consult
+        // Phase 7：迁移前咨询（只读健康评分 + 建议）。POST，loopback fence。
+        // 对 4 种可迁移源（export-zip / local-snapshot / remote-snapshot / profile）生成
+        // 统一咨询报告。**只读**：不写配置/快照/journal；临时 ZIP 用 try/finally 立即清理。
+        // ------------------------------------------------------ sync/status
+        // m-sync-ui：同步状态（通道配置 / 凭据状态 / 上次同步 / 分区数）。只读，无 secret 值。
+        {
+            kind: 'exact',
+            path: API.syncStatus,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'GET'))
+                    return;
+                try {
+                    // 完整双命名空间配置：repoUrl / webdav.url 无论当前通道都回填，
+                    // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失
+                    const full = await readFullSyncConfig(syncDir);
+                    const state = await loadSyncState(syncDir);
+                    const [cred, webdavCred] = await Promise.all([
+                        credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
+                        credentials.describe(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF)),
+                    ]);
+                    const transport = full !== null && full.transport === 'webdav' ? 'webdav' : 'git';
+                    // m-self：插件 UI 偏好（上次选择的同步通道；ui-prefs.json，随 self 分区进备份）
+                    const uiPrefs = await readUiPrefs(syncDir);
+                    // webdav 配置视图（配置过即返回，与当前通道无关：供表单在 git ↔ webdav 切换时回填）
+                    const webdav = full?.webdav !== undefined
+                        ? {
+                            url: full.webdav.url,
+                            // username 非敏感可回显，供表单回填
+                            username: full.webdav.username,
+                            usernameConfigured: typeof full.webdav.username === 'string' && full.webdav.username !== '',
+                            passwordConfigured: webdavCred.configured,
+                        }
+                        : undefined;
+                    writeJson(res, 200, {
+                        ok: true,
+                        configured: full !== null,
+                        transport,
+                        repoUrl: full?.git?.repoUrl,
+                        credentialConfigured: cred.configured,
+                        credentialWritable: cred.writable === true,
+                        // webdav 配置状态（无 secret 值：口令用 passwordConfigured 布尔标记）
+                        ...(webdav !== undefined ? { webdav } : {}),
+                        lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
+                        sectionCount: Object.keys(state.sections).length,
+                        lastTransport: state.transport,
+                        // 上次选择的同步通道（磁盘 ui-prefs；UI 回填优先于此，localStorage 仅兜底）
+                        lastSyncChannel: uiPrefs.lastSyncChannel,
+                        // 可同步分区目录（「高级/自定义导出」勾选列表；只含 portable，无 secret 值）
+                        syncSections: syncSectionCatalog,
+                        // 当前分区选择（默认/高级模式 + 勾选分区；当前激活通道；UI 回填用，自动同步共用）
+                        syncSelection: await selectionView(transport),
+                        // 全部通道的分区选择（git/webdav 各自独立；UI 按当前 tab 取对应通道）
+                        syncSelectionByChannel: await selectionViewByChannel(),
+                        // 自动同步当前状态（当前激活通道；供 UI 顶部开关回填；§3.9）
+                        autosync: await buildAutosyncStatus(syncDir, transport),
+                        // 全部通道的自动同步状态（git/webdav 各自独立；UI 按当前 tab 取对应通道）
+                        autosyncByChannel: await buildAutosyncStatusByChannel(syncDir),
+                    });
+                }
+                catch (error) {
+                    writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/config
+        // m-sync-config：保存同步通道配置（parseSyncBody 校验 + password/token 写 DSH credentials +
+        // writeSyncConfig 落盘）。UI 表单自动保存 /「保存配置」按钮调用；响应为轻量状态视图
+        // （仅凭据布尔，无 secret 值），供 UI 直接刷新徽章而不必重拉 status 覆盖正在编辑的表单。
+        {
+            kind: 'exact',
+            path: API.syncConfig,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncCfg = await prepareSync(body);
+                    await writeSyncConfig(syncDir, syncCfg);
+                    const [cred, webdavCred] = await Promise.all([
+                        credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
+                        credentials.describe(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF)),
+                    ]);
+                    writeJson(res, 200, {
+                        ok: true,
+                        configured: true,
+                        transport: syncCfg.transport,
+                        credentialConfigured: cred.configured,
+                        webdav: isWebDavConfig(syncCfg)
+                            ? {
+                                usernameConfigured: typeof syncCfg.webdav.username === 'string' && syncCfg.webdav.username !== '',
+                                passwordConfigured: webdavCred.configured,
+                            }
+                            : undefined,
+                    });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/ui-prefs
+        // m-self：保存插件 UI 偏好（当前为上次选择的同步通道；ui-prefs.json，随 self 分区进备份）。
+        // 纯偏好、无 secret；失败仅提示，不阻断同步主流程。
+        // 经 updateUiPrefs 局部合并写：不覆盖其他端点（star-prompt）刚写入的字段。
+        {
+            kind: 'exact',
+            path: API.syncUiPrefs,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const channel = body['lastSyncChannel'] === 'webdav' ? 'webdav' : body['lastSyncChannel'] === 'git' ? 'git' : undefined;
+                    await updateUiPrefs(syncDir, { ...(channel !== undefined ? { lastSyncChannel: channel } : {}) });
+                    writeJson(res, 200, { ok: true, lastSyncChannel: channel });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ star-prompt
+        // m-star-prompt：Star 引导弹窗状态（复用 ui-prefs.json；随 self 分区进备份）。
+        // GET → 返回仓库地址 + 弹窗状态（UI 挂载时判定是否展示 / 是否补记首次使用时间）；
+        // POST → 局部更新（firstSeenAt / dismissed / clicked 白名单），经 updateUiPrefs
+        // 合并写，不覆盖 sync/ui-prefs 的 lastSyncChannel。纯偏好、无 secret。
+        // ------------------------------------------------------ release-notes-prompt
+        // 版本更新内容弹窗状态（复用 ui-prefs.json；随 self 分区进备份）。
+        // GET → 返回当前插件版本 + 上次已读版本 + 是否永不提示；
+        // POST → 局部更新（lastSeenVersion / dismissed 白名单），经 updateUiPrefs 合并写。
+        // ------------------------------------------------------ sync/push
+        // m-sync-ui：推送（导出 portable 分区 → 提交私有仓库 → 更新 sync-state）。
+        // token 可选：非空先写入 DSH credentials；成功则记忆仓库配置（回填表单用）。
+        // sections 可选（高级/自定义导出）：只推送勾选的分区；缺省 = 默认模式全部推荐分区。
+        {
+            kind: 'exact',
+            path: API.syncPush,
+            handler: withMutationGate('sync-push', async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncCfg = await prepareSync(body);
+                    const engine = makeSyncEngine(syncCfg);
+                    const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined;
+                    const sections = extractSyncSections(body, knownSyncSectionIds);
+                    // P0-②：push 前只读预览（body.preview === true → 不写远端，只返回「将推送什么」）
+                    const preview = body['preview'] === true;
+                    // 分支调用以保证 withTimeout 的泛型结果类型正确（SyncPushReport | SyncPushPreview）
+                    const report = preview
+                        ? await withTimeout(engine.previewPush({ ...(sections === undefined ? {} : { sections }) }), ROUTE_TIMEOUT_MS, msg('host.syncPushTimeout'))
+                        : await withTimeout(engine.push({
+                            ...(snapshotId === undefined ? {} : { snapshotId }),
+                            ...(sections === undefined ? {} : { sections }),
+                        }), ROUTE_TIMEOUT_MS, msg('host.syncPushTimeout'));
+                    await writeSyncConfig(syncDir, syncCfg);
+                    writeJson(res, 200, report);
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            }),
+        },
+        // ------------------------------------------------------ sync/pull
+        // m-sync-ui：拉取差异预览（只读：list/download → 转临时 ZIP → Importer 分析出计划摘要）。
+        // 绝不直接写配置、绝不执行导入（executeImportPlan 由上层按用户确认驱动）。
+        {
+            kind: 'exact',
+            path: API.syncPull,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncCfg = await prepareSync(body);
+                    const engine = makeSyncEngine(syncCfg);
+                    // 缺省 replace：明文同步的产品语义是「远端值覆盖本地」，不做 diff/合并
+                    const strategy = body['strategy'] === 'merge' || body['strategy'] === 'skipExisting' ? body['strategy'] : 'replace';
+                    const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined;
+                    const report = await withTimeout(engine.pull({
+                        strategy,
+                        ...(snapshotId === undefined ? {} : { snapshotId }),
+                    }), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
+                    await writeSyncConfig(syncDir, syncCfg);
+                    writeJson(res, 200, report);
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // -------------------------------------------------- sync/github/start
+        // m-github-oauth：发起 GitHub OAuth device flow。请求 GitHub 取设备码，宿主登记
+        // （flowId → device_code 只存内存），返回 UI 展示用的 user_code + 授权页 URL。
+        // client_id 来自插件配置；未配置时给出可操作指引（不会凭空认证）。
+        {
+            kind: 'exact',
+            path: API.syncGithubStart,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                if (githubClientId === undefined || githubClientId === '') {
+                    writeJson(res, 400, {
+                        error: msg('host.githubMissingClientId'),
+                    });
+                    return;
+                }
+                try {
+                    const started = await githubAuth.startDeviceFlow(githubClientId);
+                    const flowId = DeviceFlowStore.newFlowId();
+                    githubFlows.set(flowId, {
+                        deviceCode: started.deviceCode,
+                        clientId: githubClientId,
+                        clientSecret: githubClientSecret,
+                        interval: started.interval,
+                        expiresAt: Date.now() + started.expiresIn * 1000,
+                    });
+                    // device_code 绝不回传；只回 UI 需要的展示信息
+                    writeJson(res, 200, {
+                        flowId,
+                        userCode: started.userCode,
+                        verificationUri: started.verificationUri,
+                        expiresIn: started.expiresIn,
+                        interval: started.interval,
+                    });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // -------------------------------------------------- sync/github/poll
+        // m-github-oauth：轮询授权结果。凭 flowId 取回宿主登记的 device_code → GitHub 换 token
+        // → 成功则立即写入 DSH credentials（SYNC_CREDENTIAL_REF，与手动 token 同槽），
+        // token 绝不回传浏览器；pending 返回下次轮询延迟；终止态（denied/expired/error）清理登记。
+        {
+            kind: 'exact',
+            path: API.syncGithubPoll,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                const flowId = typeof body?.['flowId'] === 'string' ? body['flowId'] : '';
+                if (flowId === '') {
+                    writeJson(res, 400, { error: 'flowId is required' });
+                    return;
+                }
+                const flow = githubFlows.get(flowId);
+                if (flow === undefined) {
+                    writeJson(res, 400, { error: msg('host.githubFlowGone') });
+                    return;
+                }
+                try {
+                    const result = await githubAuth.pollForToken({
+                        clientId: flow.clientId,
+                        deviceCode: flow.deviceCode,
+                        clientSecret: flow.clientSecret,
+                        interval: flow.interval,
+                    });
+                    if (result.status === 'success' && result.accessToken !== undefined) {
+                        await credentials.set(credentialRef(SYNC_CREDENTIAL_REF), result.accessToken);
+                        githubFlows.delete(flowId);
+                        host.log.info('GitHub OAuth 登录成功（token 已写入 DSH credentials）');
+                        writeJson(res, 200, { status: 'success', credentialConfigured: true });
+                        return;
+                    }
+                    if (result.status === 'pending') {
+                        writeJson(res, 200, { status: 'pending', pollDelayMs: result.pollDelayMs });
+                        return;
+                    }
+                    // 终止态：清理登记，把状态 + 可展示消息回给 UI（不含任何秘密）
+                    githubFlows.delete(flowId);
+                    writeJson(res, 200, {
+                        status: result.status,
+                        ...(result.message !== undefined ? { message: result.message } : {}),
+                        ...(result.errorCode !== undefined ? { errorCode: result.errorCode } : {}),
+                    });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // -------------------------------------------------- sync/github/cancel
+        // m-github-oauth：取消登录流程（丢弃宿主侧 device_code 登记，零副作用）。
+        {
+            kind: 'exact',
+            path: API.syncGithubCancel,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                const flowId = typeof body?.['flowId'] === 'string' ? body['flowId'] : '';
+                if (flowId === '') {
+                    writeJson(res, 400, { error: 'flowId is required' });
+                    return;
+                }
+                githubFlows.delete(flowId);
+                writeJson(res, 200, { ok: true });
+            },
+        },
+        // -------------------------------------------------- sync/github/validate
+        // m-sync-github-valid：校验 SYNC_CREDENTIAL_REF 中已存 token 是否有效（GET /user），
+        // 供 UI 判定「是否已登录」→ 已登录隐藏 GitHub 登录区块、token 失效则重新展示。
+        // 只回布尔 + 登录名（非敏感），token 值绝不回传；仅 401（无效/过期）→ valid:false，
+        // 其余错误（网络/限流）向上抛，由 UI 兜底（不误判登出）。
+        {
+            kind: 'exact',
+            path: API.syncGithubValidate,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                try {
+                    let configured = false;
+                    let valid = false;
+                    let login;
+                    const resolved = await credentials.resolve(credentialRef(SYNC_CREDENTIAL_REF));
+                    const token = resolved?.value ?? '';
+                    configured = token !== '';
+                    if (configured) {
+                        try {
+                            const user = await githubAuth.getUser(token);
+                            valid = true;
+                            login = user.login;
+                        }
+                        catch (error) {
+                            // 仅 401（token 无效/过期）→ 视为未登录；其余错误（网络/限流）向上抛
+                            if (!(error instanceof GitHubAuthError && error.code === 'unauthorized'))
+                                throw error;
+                        }
+                    }
+                    writeJson(res, 200, {
+                        ok: true,
+                        configured,
+                        valid,
+                        ...(login !== undefined ? { login } : {}),
+                    });
+                }
+                catch (error) {
+                    writeJson(res, 500, { error: redact(error instanceof Error ? error.message : String(error)) });
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/history
+        // 列出本地快照目录的 manifest.json（id/createdAt/sectionHashes/transport）。
+        {
+            kind: 'exact',
+            path: API.syncHistory,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'GET'))
+                    return;
+                try {
+                    const localDir = join(syncDir, 'snapshots');
+                    const entries = await fs.readdir(localDir).catch(() => []);
+                    const rows = [];
+                    for (const name of entries) {
+                        const dir = join(localDir, name);
+                        const stat = await fs.stat(dir).catch(() => null);
+                        if (!stat?.isDirectory())
+                            continue;
+                        const manifestPath = join(dir, 'manifest.json');
+                        const raw = await fs.readFile(manifestPath, 'utf8').catch(() => null);
+                        if (raw === null)
+                            continue;
+                        try {
+                            const m = JSON.parse(raw);
+                            if (typeof m.id !== 'string' || typeof m.createdAt !== 'string')
+                                continue;
+                            const sectionCount = m.sectionHashes && typeof m.sectionHashes === 'object'
+                                ? Object.keys(m.sectionHashes).length
+                                : 0;
+                            // 触发通道（push/apply 落盘时写入各快照 manifest.transport；旧快照为 undefined）
+                            const transport = m.manifest && typeof m.manifest === 'object' && typeof m.manifest.transport === 'string'
+                                ? m.manifest.transport
+                                : undefined;
+                            rows.push({ id: m.id, createdAt: m.createdAt, sectionCount, reviewCount: 0, ...(transport !== undefined ? { transport } : {}) });
+                        }
+                        catch { /* skip malformed */ }
+                    }
+                    // reviewCount 恒 0：待审队列（sync-review-queue.json）已随合并逻辑一并删除，
+                    // 保留该字段仅为与客户端契约兼容。
+                    rows.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+                    // 合并自动同步执行记录（sync-history.json）
+                    const hist = await readSyncHistory(syncDir);
+                    const merged = [
+                        ...rows.map((r) => ({ ...r, kind: 'apply' })),
+                        ...hist.autosyncEntries.map((e) => ({
+                            id: e.createdAt,
+                            createdAt: e.createdAt,
+                            kind: 'autosync',
+                            autosync: e,
+                        })),
+                    ].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+                    writeJson(res, 200, { entries: merged });
+                }
+                catch (error) {
+                    writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/snapshots-list
+        // m-sync-v2：远端历史快照列表（供「选择历史快照」下拉）。
+        {
+            kind: 'exact',
+            path: API.syncSnapshotsList,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncCfg = await prepareSync(body);
+                    const engine = makeSyncEngine(syncCfg);
+                    const metas = await withTimeout(engine.listSnapshots(), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
+                    const snapshots = [...metas]
+                        .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+                        .map((m) => ({
+                        id: m.id,
+                        createdAt: m.createdAt,
+                        sectionCount: m.manifest.sectionIds.length,
+                        platform: m.manifest.platform,
+                        dshVersion: m.manifest.dshVersion,
+                    }));
+                    const state = await loadSyncState(syncDir);
+                    writeJson(res, 200, { ok: true, snapshots, currentSnapshotId: state.lastSnapshotId === '' ? undefined : state.lastSnapshotId });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/sync
+        // m-sync-v2：一键同步第一步 —— 拉取 → 差异确认会话（内存登记临时 ZIP + ImportPlan）。
+        {
+            kind: 'exact',
+            path: API.syncSync,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncCfg = await prepareSync(body);
+                    const engine = makeSyncEngine(syncCfg);
+                    const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined;
+                    const preview = await withTimeout(engine.preview({ ...(snapshotId === undefined ? {} : { snapshotId }) }), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
+                    if (!preview.ok || preview.plan === null || preview.analysis === null) {
+                        writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? '同步预览失败' });
+                        return;
+                    }
+                    const syncSessionId = syncSessions.set({
+                        zipPath: preview.zipPath,
+                        plan: preview.plan,
+                        analysis: preview.analysis,
+                        snapshotId: preview.snapshotId,
+                        config: syncCfg,
+                    });
+                    const items = planToConfirmItems(preview.plan);
+                    const needsReview = items.some((i) => REVIEW_KINDS.has(i.kind) || isToolchainChangeItem(i))
+                        || preview.analysis.pathIssues.length > 0;
+                    writeJson(res, 200, {
+                        ok: true,
+                        syncSessionId,
+                        snapshotId: preview.snapshotId,
+                        items,
+                        needsReview,
+                        compatibility: preview.analysis.compatibility,
+                    });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/apply-items
+        // m-sync-v2：一键同步第二步 —— 按用户对差异项的逐项决策执行导入。
+        {
+            kind: 'exact',
+            path: API.syncApplyItems,
+            handler: withMutationGate('sync-apply', async (req, res, lockCtx, journalCtx) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : '';
+                    const session = syncSessions.get(syncSessionId);
+                    if (session === undefined) {
+                        writeJson(res, 400, { error: '同步会话不存在或已过期，请重新拉取预览' });
+                        return;
+                    }
+                    const adoptions = Array.isArray(body['adoptions']) ? body['adoptions'] : [];
+                    // 构造子计划（仅含采纳项）
+                    const byId = new Map();
+                    for (const a of adoptions) {
+                        if (typeof a?.['itemId'] !== 'string')
+                            continue;
+                        byId.set(a['itemId'], { adopt: a['adopt'] === true, resolution: typeof a['resolution'] === 'string' ? a['resolution'] : undefined });
+                    }
+                    // 构造子计划（仅含采纳项）。同步冲突决策 useRemote → 核心 importer 的
+                    // useImported（item 转成 Update，applyOne 才会真正写远端值），
+                    // keepLocal/skip 从子计划剔除（keepCurrent/skip 语义：不写）。
+                    // 与导入恢复向导（ConflictList keepCurrent/useImported）的决策语义完全一致。
+                    const subItems = session.plan.items.flatMap((item) => {
+                        const d = byId.get(item.id);
+                        if (d === undefined || !d.adopt)
+                            return [];
+                        // Conflict 项必须有 resolution；keepLocal/skip 不写入本地 → 剔除
+                        if (item.kind === 'Conflict') {
+                            if (d.resolution === undefined)
+                                throw new SyncRouteError(`冲突项 ${item.id} 必须提供 resolution（useRemote/keepLocal/skip）`);
+                            if (d.resolution === 'keepLocal' || d.resolution === 'skip')
+                                return [];
+                            // useRemote → 转成 Update 计划项（镜像 analyzer.applyItemResolution 的
+                            // useImported 分支），applyOne 才会把远端值真正写进本地。
+                            const c = item.conflict;
+                            return [{
+                                    ...item,
+                                    kind: 'Update',
+                                    severity: 'info',
+                                    conflict: { itemId: c?.itemId ?? item.id, resolution: 'useImported' },
+                                }];
+                        }
+                        return [item];
+                    });
+                    const subPlan = {
+                        ...session.plan,
+                        items: subItems,
+                    };
+                    // 消费会话（同一 session 只允许一次 apply-items）
+                    syncSessions.delete(syncSessionId);
+                    let engine;
+                    let report;
+                    try {
+                        engine = makeSyncEngine(session.config);
+                        report = await engine.applyItems(session.zipPath, subPlan, {
+                            onItem: (info) => { },
+                            snapshotBinding: journalCtx,
+                        });
+                    }
+                    finally {
+                        // 用完再清理临时 ZIP（此前在 applyItems 读取前就删除 → ENOENT：无法读取备份文件）
+                        await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { });
+                    }
+                    const historyError = await tryAppendHistory({
+                        kind: 'sync-apply',
+                        result: report.ok ? 'success' : 'failed',
+                        sections: Array.isArray(report.applied) ? report.applied.filter((s) => typeof s === 'string') : subItems.map((i) => i.adapter).filter((s) => typeof s === 'string' && s !== ''),
+                        operationId: journalCtx?.operationId,
+                        snapshotId: report.restoreId ?? undefined,
+                        source: 'api',
+                        summary: `一键同步应用：${(Array.isArray(report.applied) ? report.applied.length : subItems.length)} 项${report.rolledBack === true ? '（已回滚）' : ''}`,
+                        error: report.ok ? undefined : '同步应用未完全成功',
+                    });
+                    writeJson(res, 200, historyError === undefined ? {
+                        ok: report.ok,
+                        applied: report.applied,
+                        skipped: subItems.map((i) => i.id),
+                        needsRestart: report.needsRestart === true,
+                        warnings: report.warnings,
+                        restoreId: report.restoreId,
+                        rolledBack: report.rolledBack,
+                        failed: report.failed,
+                        result: report.result,
+                    } : {
+                        ok: report.ok,
+                        applied: report.applied,
+                        skipped: subItems.map((i) => i.id),
+                        needsRestart: report.needsRestart === true,
+                        warnings: report.warnings,
+                        restoreId: report.restoreId,
+                        rolledBack: report.rolledBack,
+                        failed: report.failed,
+                        result: report.result,
+                        historyWriteError: historyError,
+                    });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            }, { deferredSnapshot: true }),
+        },
+        // ------------------------------------------------------ sync/cancel
+        // m-sync-v2：取消 / 清理差异确认会话（丢弃临时 ZIP，零副作用）。
+        {
+            kind: 'exact',
+            path: API.syncCancel,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : '';
+                    if (syncSessionId !== '') {
+                        const session = syncSessions.get(syncSessionId);
+                        if (session !== undefined) {
+                            await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { });
+                        }
+                        syncSessions.delete(syncSessionId);
+                    }
+                    writeJson(res, 200, { ok: true });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/autosync
+        // m-sync-v2：自动同步配置读写（按通道：git/webdav 各自的开关 + 间隔 + 启动阈值 + 状态）。
+        // GET = 读全部通道状态（{ git, webdav }）；POST = 写指定通道（body.transport，缺省 git）。
+        // 同一路径注册为一个 exact 路由（方法内部分发），避免 webserver 对重复 exact 路径报错。
+        {
+            kind: 'exact',
+            path: API.syncAutosync,
+            handler: async (req, res) => {
+                if (req.method === 'GET') {
+                    if (!guard(req, res, 'GET'))
+                        return;
+                    try {
+                        writeJson(res, 200, await buildAutosyncStatusByChannel(syncDir));
+                    }
+                    catch (error) {
+                        writeSyncRouteError(res, error);
+                    }
+                    return;
+                }
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    // 按通道读写：git/webdav 各自的自动同步配置与运行状态独立（缺省 git 兜底）
+                    const channel = body['transport'] === 'webdav' ? 'webdav' : 'git';
+                    const cfg = await readAutosyncConfig(syncDir, channel);
+                    if (typeof body['enabled'] === 'boolean')
+                        cfg.enabled = body['enabled'];
+                    if (typeof body['interval'] === 'string' && isAutosyncInterval(body['interval']))
+                        cfg.interval = body['interval'];
+                    if (typeof body['startupMinIntervalMs'] === 'number' && Number.isFinite(body['startupMinIntervalMs']) && body['startupMinIntervalMs'] > 0) {
+                        cfg.startupMinIntervalMs = body['startupMinIntervalMs'];
+                    }
+                    await writeAutosyncConfig(syncDir, channel, cfg);
+                    if (scheduler)
+                        scheduler.reload().catch(() => { });
+                    writeJson(res, 200, await buildAutosyncStatus(syncDir, channel));
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/selection
+        // m-sync-selection：保存同步分区选择（按通道：git/webdav 各自的模式 + 勾选分区）。
+        // 持久化到 sync-selection.json；自动同步调度器与手动 push 共用（makeSyncEngine 注入）。
+        // sections 元素必须是可同步（portable）分区 id；mode 非法 → 回退 default。
+        {
+            kind: 'exact',
+            path: API.syncSelection,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    // 按通道读写：git/webdav 各自的模式与分区勾选独立（缺省 git 兜底）
+                    const channel = body['transport'] === 'webdav' ? 'webdav' : 'git';
+                    const mode = body['mode'] === 'advanced' ? 'advanced' : 'default';
+                    const rawSections = Array.isArray(body['sections']) ? body['sections'] : [];
+                    // 目录已含全部分区（不再按 portability 过滤），变量名不沿用 portable*
+                    const catalogSectionIds = new Set(syncSectionCatalog.map((s) => s.id));
+                    for (const s of rawSections) {
+                        if (typeof s !== 'string' || s === '') {
+                            writeJson(res, 400, { error: 'sections must be an array of non-empty strings' });
+                            return;
+                        }
+                        if (!catalogSectionIds.has(s)) {
+                            writeJson(res, 400, { error: `unknown sync section: ${s}` });
+                            return;
+                        }
+                    }
+                    const next = {
+                        schemaVersion: SYNC_SELECTION_SCHEMA_VERSION,
+                        mode,
+                        sections: [...new Set(rawSections)],
+                    };
+                    await writeSyncSelection(syncDir, channel, next);
+                    selectionCache[channel] = next;
+                    writeJson(res, 200, { ok: true, transport: channel, mode: next.mode, sections: next.sections });
+                }
+                catch (error) {
+                    writeSyncRouteError(res, error);
+                }
+            },
+        },
+        // ------------------------------------------------------ sync/rollback
+        // P2：UI 一键回滚入口（按 apply 返回的 restoreId 调用 backup→rollback）。
+        {
+            kind: 'exact',
+            path: API.syncRollback,
+            handler: withMutationGate('sync-rollback', async (req, res) => {
+                if (!guard(req, res, 'POST'))
+                    return;
+                const body = await readJsonBody(req);
+                if (body === undefined) {
+                    writeJson(res, 400, { error: 'invalid JSON body' });
+                    return;
+                }
+                try {
+                    const restoreId = typeof body['restoreId'] === 'string' ? body['restoreId'] : '';
+                    if (restoreId === '') {
+                        writeJson(res, 400, { error: 'restoreId required' });
+                        return;
+                    }
+                    const store = new FileSnapshotStore({ dir: join(syncDir, 'snapshots') });
+                    const snap = await store.load(restoreId);
+                    const report = await performRollback({ ctx: host, snapshot: snap, store, adapters });
+                    const historyError = await tryAppendHistory({
+                        kind: 'rollback',
+                        result: 'success',
+                        sections: [],
+                        snapshotId: restoreId,
+                        source: 'api',
+                        summary: `一键同步回滚（${restoreId}）`,
+                    });
+                    writeJson(res, 200, historyError === undefined ? { ok: true, full: report.full } : { ok: true, full: report.full, historyWriteError: historyError });
+                }
+                catch (error) {
+                    writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            }),
+        },
+        // ---------------------------------------------------- market/status
+        // 内置单市场（只读、不可编辑）：恒返回内置仓库摘要。无 add/remove —— 市场绑定内置仓库。
+        // ---------------------------------------------------- market/refresh
+        // ---------------------------------------------------- market/browse
+        // ---------------------------------------------------- market/download
+        // 拉取 manifest + config.zip → 安全校验（§6）→ valid 则落受控临时区 + dry-run 分析/计划。
+        // 真正落盘由用户确认后走既有 POST /execute（zipPath + plan）。零写入到确认。
+        // ---------------------------------------------------- market/prepare
+        // 发布向导：由「用户上传的配置 zip + 用户填写元数据」生成市场条目包
+        // （L2 manifest + config.zip SHA-256 + sections），供 UI 展示/复制与引导推送。
+        // 零写入配置：只在受控临时区生成发布目录；插件不做任何 git 写操作、不持有凭据。
+        // ---------------------------------------------------- me/status
+        // 「一键上传 / 我的配置」登录状态：resolve SYNC_CREDENTIAL_REF token → GET /user。
+        // 401 → loggedIn:false（未登录）；token 值不出模块外，只回传 login 用户名。
+        // ---------------------------------------------------- me/upload
+        // 一键上传：zipPath 必须来自受控上传临时区（复用 /market/prepare 规则）；
+        // form 仅 { name, description?, categories? }（name 必填）；元数据全自动由 MyRepoService 生成。
+        // ---------------------------------------------------- me/items
+        // 查看已上传：读用户仓库 index.json + 收录状态（未收录 / PR 待审核 / 已收录）。
+        // 401（token 过期）→ 401 + 脱敏错误，UI 引导重新登录。
+        // ---------------------------------------------------- me/update
+        // 一键更新：同 upload 时序；version 纯自动 +1、id 不变；PR 未合并 force push 更新 / 已合并基于最新 main 重开。
+        // ---------------------------------------------------- me/listing
+        // 查询收录/下架任务状态（结果卡轮询）：任务表命中 → 直接返回；未命中 → 回退 GitHub 实况推导；
+        // 无任务且无实况 → 200 null。401（token 过期）→ 401，UI 引导重新登录。
+        // ---------------------------------------------------- me/relist
+        // 重新提交收录（收录失败 / 进程重启丢失后的一键重试）：幂等复用已存在 fork/open PR。
+        // ---------------------------------------------------- me/delete
+        // 删除条目：同步删用户仓库索引 + items/<id>/ 文件；已收录 → 后台异步提下架 PR；待审核 → 关闭收录 PR。
+        // ------------------------------------------------------------ history
+        // Phase 6：迁移历史审计（统一历史引擎）。只读 GET：列表（过滤）+ 导出。
+        // loopback fence（guard）与全仓一致——仅同源 + loopback 可访问。
+        // ------------------------------------------------------------ recovery
+        // Phase 5：recovery 编排（prefix 路由，内部按 path 分发）。
+        // 禁用 withMutationGate（避免 double-journal）；mutation 路由经 withMutationLock + loopback fence。
+        // ------------------------------------------------------------ Phase 1 P0
+        // 配置生命周期（自动快照 / 撤销 / 重做）：prefix 路由，内部按 path 分发。
+        // mutation 动作经 withMutationGate（GLOBAL 锁 + SAFE MODE 闸门）；status 只读不加锁。
+        // 崩溃归因（P0-5）：只读。上次启动是否异常 + 归因 + 建议动作 + last-good 快照。
+        // 启动救援模式（P0-3）：on = 备份三处原件后，把 profile patch 改写成只挂载本插件的最小内容、
+        // 置空 home patch，并把 dsh.profile.bundles 收窄为 DSH 核心（@deepseek-ai/*）与本插件自身
+        // —— 其余用户插件本次启动不挂载（这才是「禁用其它插件」，只中和 patch 层救不了
+        // 「插件代码自己把 DSH 搞挂」）；off = 从备份完整还原。两侧都只动
+        // cordis.patch.yml / package.json / state.json，可完全回退。
+    ];
+    return { routes: routesList, scheduler, makeSyncEngine, lifecycle };
+}
+/* ------------------------------------------------------------------ apply */
+/**
+ * Mount the config-manager engine: host context, adapters, and the
+ * /api/dsh-config-manager routes (when a webServer is present).
+ * @param ctx - host plugin context carrying settings/credentials/webServer.
+ * @param config - resolved plugin config.
+ */
+export function apply(ctx, config) {
+    if (config?.enabled === false)
+        return;
+    const homeDir = resolveDshHome();
+    const dataDir = config?.dataDir !== undefined && config.dataDir !== ''
+        ? resolve(config.dataDir)
+        : dshHomePath('dsh-config-manager');
+    const exportsDir = join(dataDir, 'exports');
+    const tmpDir = join(dataDir, 'tmp');
+    const snapshotsDir = join(dataDir, 'snapshots');
+    const syncDir = join(dataDir, 'sync');
+    // Phase 6：迁移历史审计目录（统一历史引擎；加入 RESERVED_INTERNAL_PREFIXES 防 F23 投毒链）
+    const historyDir = join(dataDir, MIGRATION_HISTORY_DIR);
+    mkdirSync(exportsDir, { recursive: true });
+    /**
+     * Phase 1 P0-5 崩溃归因：启动即写 boot-state（ok:false），待启动分类完成后翻 ok:true。
+     * 崩溃瞬间不写文件 —— 靠「下一次启动发现上次 ok!==true」归因。上次若有崩溃且尚无归因，
+     * 此处扫一次日志尾部并把 crashReason 持久化（日志会被滚动覆盖，错过就没了）。
+     * best-effort：任何失败都不得影响插件挂载。
+     */
+    const bootStateDir = join(dataDir, 'config-snapshots');
+    const bootBegin = async () => {
+        try {
+            const prev = await readBootState(bootStateDir);
+            const next = beginBoot(process.pid, prev);
+            if (prev !== null && prev.ok !== true && next.crashReason === null) {
+                try {
+                    const alert = computeBootAlert(prev, await readCrashLogTail(await listCandidateLogs(homeDir)));
+                    if (alert.crashReason !== null)
+                        next.crashReason = alert.crashReason;
+                }
+                catch { /* 归因失败不影响启动 */ }
+            }
+            await writeBootState(bootStateDir, next);
+        }
+        catch (error) {
+            host.log.warn('boot-state 写入失败（不影响挂载）', { error: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    // 灾备总开关关闭时不写 boot-state（崩溃归因整体下线，也不留观测残留）。
+    if (LIFECYCLE_ENABLED)
+        void bootBegin();
+    mkdirSync(tmpDir, { recursive: true });
+    mkdirSync(snapshotsDir, { recursive: true });
+    mkdirSync(syncDir, { recursive: true });
+    mkdirSync(historyDir, { recursive: true });
+    const host = new ConfigManagerHostContext(ctx, homeDir, resolveProfileName(config));
+    // issue #30：出站代理（插件私有，不改全局）。仅在检测到 HTTP(S)_PROXY 时生效；未配置则完全直连。
+    // 打一条脱敏日志，便于用户确认「插件当前到底走没走代理」（凭据不进日志）。
+    const proxySummary = activeProxySummary();
+    if (proxySummary !== null) {
+        host.log.info(`出站请求经代理 / outbound requests via proxy: http=${proxySummary.http ?? '(none)'} https=${proxySummary.https ?? '(none)'} noProxyEntries=${proxySummary.noProxyEntries}`);
+    }
+    // Phase 2 跨进程环境锁：全局唯一 GLOBAL EXCLUSIVE MUTATION LOCK（<dataDir>/locks/environment.lock）。
+    // 所有 destructive mutation 入口经 runWithMutationLock(host.mutationLock, …) 获取；跨进程/跨 kind 互斥。
+    // 随插件生命周期停止：停止 heartbeat 并清除本进程持有（release 由各入口 finally 保证；这里无需额外清理）。
+    host.mutationLock = new EnvironmentLockManager({
+        dataDir,
+        op: 'config-manager',
+        target: 'global-mutation',
+        lockVersion: PLUGIN_VERSION,
+    });
+    const envLockManager = host.mutationLock;
+    // Phase 3：启动 reconcile（只读）+ SAFE MODE。宿主 apply() 为同步 →
+    // ① 先同步探测 durable SAFE MODE 标记（scheduler.start() 前即被阻断），
+    // ② 再异步跑完整只读 reconcile，刷新标志与 durable 标记。不自动 recover stale lock（Rev 3 P1-NEW-2）。
+    // Phase 4 F21/F11：注入真实 snapshotExists 正向校验——journal 引用的 snapshot 存在 + READY +
+    // verified（manifest/blob hash）+ op/env/owner binding 匹配 journal，才视为可回滚的有效 recovery 证据。
+    const phase3Recovery = new Phase3Recovery({
+        dataDir,
+        packageVersion: PLUGIN_VERSION,
+        snapshotExists: async (snapshotId, binding) => {
+            if (snapshotId === null || snapshotId === '')
+                return false;
+            if (!isValidSnapshotId(snapshotId))
+                return false;
+            const v = await verifySnapshot(snapshotsDir, snapshotId);
+            if (!v.ok)
+                return false;
+            // binding 校验：journal 引用必须与快照双向一致（operationId/ownerInstanceId/environmentFingerprint）
+            const snap = await new FileSnapshotStore({ dir: snapshotsDir }).load(snapshotId).catch(() => null);
+            if (snap === null)
+                return false;
+            if (snap.readiness !== 'READY')
+                return false;
+            if (binding?.operationId !== undefined && snap.operationId !== binding.operationId)
+                return false;
+            if (binding?.ownerInstanceId !== undefined && snap.ownerInstanceId !== binding.ownerInstanceId)
+                return false;
+            if (binding?.environmentFingerprint !== undefined && snap.environmentFingerprint !== binding.environmentFingerprint)
+                return false;
+            return true;
+        },
+    });
+    host.safeModeIsBlocked = () => phase3Recovery.safeModeActive;
+    host.phase3Recovery = phase3Recovery;
+    phase3Recovery.probeSafeModeSync();
+    if (phase3Recovery.safeModeActive) {
+        host.log.warn('Phase 3 SAFE MODE 激活：存在未恢复的 transaction，destructive 操作被阻断（如需恢复请先显式处理）');
+    }
+    // P1-B：启动 recovery 分类 barrier。调度器（AutoSync/Backup）只在分类完成且 state=NORMAL 时启动。
+    // schedulerGate.start 由 makeRoutes 返回 scheduler 后赋值；apply 为同步，
+    // 故在该异步分类块 await 完成前，schedulerGate.start 通常已就绪。fail-closed：分类抛错 → 不启动调度器。
+    const schedulerGate = { start: null };
+    let startupStateResolved = false;
+    let shouldStartSchedulers = false;
+    void (async () => {
+        try {
+            await phase3Recovery.initFingerprint();
+            const lockInsp = await envLockManager.inspectLockState();
+            // P1-A：启动 barrier 前捕获 crashed stale ownership 证据（environment.lock owner.instanceId），
+            // 并将其作为 expectedOwnershipInstanceId 传入分类 env → 激活 journal↔ownership binding 校验。
+            const staleOwnerId = lockInsp.state === 'STALE_LOCK_DETECTED' || lockInsp.state === 'UNKNOWN_STATE'
+                ? await phase3Recovery.captureStaleOwnershipInstanceId()
+                : null;
+            const startupState = classifyStartup({
+                store: phase3Recovery.store,
+                hooks: phase3Recovery.recoveryHooks,
+                env: {
+                    environmentFingerprint: phase3Recovery.recoveryEnvFingerprint,
+                    isLiveOwner: async () => false,
+                    ...(staleOwnerId ? { expectedOwnershipInstanceId: staleOwnerId } : {}),
+                },
+                lockState: mapLockStateForStartup(lockInsp.state),
+            });
+            const { state } = await startupState.classify();
+            startupStateResolved = true;
+            phase3Recovery.safeModeActive = phase3Recovery.safeModeActive || ['RECOVERY_REQUIRED', 'NEEDS_ATTENTION', 'UNKNOWN_STATE'].includes(state.kind);
+            shouldStartSchedulers = (state.kind === 'NORMAL');
+            if (state.kind === 'RECOVERY_REQUIRED' || state.kind === 'NEEDS_ATTENTION') {
+                host.log.warn(`Phase 3 ${state.kind}：上次 destructive operation 崩溃残留，需显式恢复；destructive 调度器未启动（read-only host 存活）`);
+            }
+            else if (shouldStartSchedulers && schedulerGate.start !== null) {
+                schedulerGate.start();
+            }
+            // Phase 1 P0-5：启动分类已得出结论 → 本次启动判定为成功（推进 lastGoodAt）。
+            // 灾备总开关关闭时不写 boot-state。
+            if (LIFECYCLE_ENABLED) {
+                try {
+                    await writeBootState(bootStateDir, markBootOk((await readBootState(bootStateDir)) ?? beginBoot(process.pid, null)));
+                }
+                catch (error) {
+                    host.log.warn('boot-state 标记成功失败', { error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        }
+        catch (err) {
+            // fail-closed：inspectStartup 抛错不默认 NORMAL → 不启动调度器（read-only host 存活）
+            startupStateResolved = true;
+            shouldStartSchedulers = false;
+            // fail-closed 也是「本次启动成功了」：host 存活（read-only），不该被判为崩溃。
+            if (LIFECYCLE_ENABLED) {
+                try {
+                    await writeBootState(bootStateDir, markBootOk((await readBootState(bootStateDir)) ?? beginBoot(process.pid, null)));
+                }
+                catch { /* best-effort */ }
+            }
+            host.log.warn('Phase 3 启动 reconcile 失败（fail-closed：destructive 调度器不启动）', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    })();
+    // 缓存自动清理：启动即清一次 + 每 24h 定时清一次。
+    // 只清「可重建/一次性」缓存与临时文件（tmp 暂存、exports 导出副本、market cache/work），
+    // 保留期内的文件不删（供刷新恢复导入/下载等窗口继续消费）；snapshots 与 sync 属用户数据/安全网不动。
+    // 尽力而为：任何失败仅记日志，不影响插件挂载与其他功能。
+    const runCacheCleanup = () => {
+        void cleanupCaches({
+            tmpDir,
+            exportsDir,
+        })
+            .then((report) => {
+            if (report.removed > 0) {
+                host.log.info('缓存自动清理完成', { removed: report.removed, freedBytes: report.freedBytes });
+            }
+        })
+            .catch((error) => {
+            host.log.warn('缓存自动清理失败', { error: error instanceof Error ? error.message : String(error) });
+        });
+    };
+    runCacheCleanup();
+    const cacheCleanupTimer = setInterval(runCacheCleanup, CACHE_CLEANUP_INTERVAL_MS);
+    ctx.effect(() => () => clearInterval(cacheCleanupTimer), 'config-manager: cache cleanup scheduler');
+    // self 分区目录（相对 ~/.dsh 根）：dataDir 在 homeDir 下 → 用相对路径挂载 self adapter；
+    // 自定义 dataDir 位于 ~/.dsh 之外时 Host fs 门面无法覆盖（confined to home root），
+    // 不挂 self 分区并告警（其余分区不受影响）。
+    const selfRel = relative(homeDir, dataDir);
+    const selfDir = !selfRel.startsWith('..') && !isAbsolute(selfRel) && selfRel !== '' ? selfRel : '';
+    if (selfDir === '') {
+        host.log.warn(`dataDir 不在 ~/.dsh 之下（${dataDir}），self 分区（插件自身配置备份）不挂载`);
+    }
+    const adapters = createAdapters({
+        // Namespace list = everything the settings service has registered.
+        namespaces: async () => (await ctx.settings.describe({ redactSecrets: true })).map((d) => String(d.ns)),
+        // Sessions 分区默认关（含敏感内容）：挂载 adapter 供 Custom Export 显式勾选（§3.3/§15）。
+        includeSessions: true,
+        // 导出 plugins 分区时不列本插件自身，避免备份中的自引用条目。
+        selfPluginName: PLUGIN_NAME,
+        // pluginFiles 扩展：额外白名单文件 + 约定配置目录（都相对 ~/.dsh 根），支持导出更多插件配置。
+        pluginFiles: config?.pluginFiles,
+        pluginFilesDir: config?.pluginFilesDir,
+        // self 分区：插件自身配置（sync-*.json / market-config.json / ui-prefs.json）；'' = 不挂载
+        selfDir,
+        // T1：本地源（link:/file:）插件打包 —— 这些 spec 指向本机路径，换机后必然不可达，
+        // 曾导致插件被静默丢失。导出时用 npm pack 把源码包一并放进备份，
+        // 导入时用解包出的绝对路径重写 spec（见 adapters/plugins.ts 的 applyItem）。
+        localPluginPack: createLocalPluginPackHook({ homeDir, dataDir }),
+    });
+    host.log.info('config-manager 已挂载', {
+        homeDir,
+        dataDir,
+        dshVersion: host.dshVersion,
+        adapters: adapters.map((a) => a.id),
+    });
+    // Phase 6：迁移历史引擎（统一审计史；per-file append-only 存储于 <dataDir>/migration-history）
+    const historyStore = new MigrationStore({ dir: historyDir });
+    const runs = new RunRegistry({ msg: host.msg });
+    const secretScanner = createConfiguredSecretScanner(config?.personalPatterns);
+    const { routes, scheduler, makeSyncEngine, lifecycle } = makeRoutes({
+        host,
+        adapters,
+        exportsDir,
+        tmpDir,
+        snapshotsDir,
+        runs,
+        syncDir,
+        dataDir,
+        // F2：部署者 personalPatterns → 强化 secret 扫描器（未配置 = 默认行为）。
+        // 该扫描器实现了 scanText（文件类分区文本级扫描，G-09 只告警不改写）——
+        // 换成任何没有 scanText 的扫描器都会静默关闭 G-09，改这里务必先看 exporter.ts 的 scanFileSectionText。
+        scanner: secretScanner, // M1：与同步路径共用同一实例（见上方 secretScanner 构造）
+        credentials: ctx.credentials,
+        githubClientId: config?.githubClientId ?? DEFAULT_GITHUB_CLIENT_ID,
+        githubClientSecret: config?.githubClientSecret,
+        history: historyStore,
+    });
+    // Agent 可调用的模型工具（P0-1）：复用 src/core 引擎与同一 makeSyncEngine 来源。
+    // 不依赖 webServer：host 侧能力在无 Web 部署时仍可用；tools 服务未组合时内部守卫跳过。
+    registerModelTools(ctx, {
+        host,
+        adapters,
+        syncDir,
+        makeSyncEngine,
+    });
+    // P1-B：调度器不同步 start —— 由启动 recovery 分类完成后（仅 NORMAL）启动。
+    schedulerGate.start = () => {
+        scheduler.start();
+        // Phase 1 P0-1：配置变更自动快照。放在同一闸门内，确保恢复/事务进行中不开拍。
+        // 灾备总开关关闭时不启动监听（否则后台持续采集全部分区并刷「超出上限」告警）。
+        if (LIFECYCLE_ENABLED)
+            lifecycle.startAutoSnapshot();
+    };
+    // 若启动分类已在此构造完成前解析为 NORMAL（罕见竞态），立即补启动。
+    if (startupStateResolved && shouldStartSchedulers && schedulerGate.start !== null) {
+        schedulerGate.start();
+    }
+    // 自动同步调度器随插件生命周期停止：插件重载/卸载时清理定时器，
+    // 避免旧调度器残留导致重复后台同步。
+    ctx.effect(() => () => scheduler.stop(), 'config-manager: autosync scheduler');
+    // Phase 1 P0-1：停止配置变更监听（dispose 后不再产生自动快照）。
+    ctx.effect(() => () => lifecycle.dispose(), 'config-manager: config lifecycle watcher');
+    const webServer = readService(ctx, 'webServer');
+    if (webServer === undefined) {
+        host.log.warn('webServer 服务不可用：跳过 /api/dsh-config-manager 路由注册（引擎能力仍可用）');
+        return;
+    }
+    ctx.effect(() => {
+        const disposers = routes.map((route) => webServer.register(route));
+        return () => {
+            for (const dispose of disposers)
+                dispose();
+        };
+    }, 'config-manager: routes');
+}
+//# sourceMappingURL=index.js.map