dsh-plugin-manager-companion 0.1.0

package/dist/envManager.d.ts

@@ -0,0 +1,1047 @@
+/**
+ * 环境管理引擎 — 列出/启停/创建/重命名/删除本地 DSH 环境，跨环境写插件，备份导出/差异/恢复。
+ *
+ * 归属：A 类·重写（旧仓库 src/profiles.ts 与 src/index.ts 的 createProfile /
+ *   renameProfile / removeProfile / copyPlugins / backupExport / backupDiff /
+ *   backupRestore 仅作意图参考，未复制代码）。
+ * 旧实现参考：旧 src/profiles.ts（进程扫描、终端窗口、端口探测的意图）、
+ *   旧 src/index.ts:227-1210（环境生命周期与备份四分类差异的意图）。
+ * 官方复用：@deepseek-ai/dsh-app-boot（initProfile / PROFILE_TEMPLATES /
+ *   DEFAULT_PROFILE_BUNDLES / readProfileManifest / writeProfileBundles）、
+ *   @deepseek-ai/dsh-plugin-manager/operations（runPluginCommand —— 跨环境 pnpm 通道）、
+ *   @deepseek-ai/dsh-atomic-write（withFileLock）、./paths.ts（路径、manifest、互斥队列）、
+ *   ./official.ts（当前环境事实）。
+ * 前提检查：旧实现的三条前提都已消失或已证伪 ——
+ *   1. 「必须自己拼 bundle 模板 / 自己调 pnpm」：官方 PROFILE_TEMPLATES 与
+ *      runPluginCommand 已覆盖，本模块不写 bundle 清单、不调 pnpm 二进制；
+ *   2. 「当前环境靠 argv 猜」（旧 issue #1）：官方 profileContext 是权威事实，
+ *      本模块只读它，拿不到就如实报告「未知」；
+ *   3. 「pkill -f 'dsh --profile' 收尾」：会误杀命令行里恰好出现同一字符串的无关
+ *      进程。本模块只按 pid 精确 kill，且在 kill 前用 /proc（或 ps）复核该 pid
+ *      的命令行仍属于同名环境。
+ *
+ * 同一套引擎、作用域可切换：当前环境的写操作走官方 pluginManager 服务，其它环境走
+ * 官方 operations —— 差别只是传给 runPluginCommand 的 profile 参数，不是两套实现。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PackageOperationContext, PackageOperationOptions } from '@deepseek-ai/dsh-plugin-manager/operations';
+import type { PackageResult } from '@deepseek-ai/dsh-plugin-manager/types';
+import { type OfficialCapabilities } from './official.ts';
+import type { BackupFormat, BackupMissingEntry, EnvironmentBackup, EnvironmentBackupDiff, EnvironmentInfo, EnvironmentResult, EnvironmentRun } from './types.ts';
+/**
+ * 进程扫描结果的缓存有效期。
+ *
+ * 一次页面加载会连续触发列表与详情，每次都做一次全表扫描（Windows 上是
+ * powershell CIM 查询，可达数秒）。运行状态变化频率低，3s 内共享一份扫描对读
+ * 路径不可感知；启停的判定用 scanRunsNow 拿即时事实。
+ */
+export declare const SCAN_RUNS_TTL_MS = 3000;
+/** 启动后等待端口就绪的上限。官方 web 面冷启动要解析整棵插件树，给足 30s。 */
+export declare const START_READY_TIMEOUT_MS = 30000;
+/** 收到 SIGTERM 后等待进程退出的上限。 */
+export declare const STOP_TIMEOUT_MS = 5000;
+/** 自动选端口时的起点（官方 web 默认端口的上方）。 */
+export declare const DEFAULT_WEB_PORT = 3090;
+/**
+ * 创建环境时的默认模板名。
+ *
+ * 官方 DEFAULT_PROFILE_BUNDLES 只有 @deepseek-ai/dsh-base（官方语义：故意最小，没有
+ * 任何 app），用它建出来的环境**必然没有 web 服务**：实测 startEnvironment 拉起后
+ * 干等 30s 报 timeout。官方 PROFILE_TEMPLATES.web 才是「建一个能访问的环境」的语义。
+ * 取名字时按官方键校验，官方常量里没有这个键就 fail loud（不悄悄退化成 base-only）。
+ */
+export declare const DEFAULT_ENVIRONMENT_TEMPLATE = "web";
+/**
+ * 环境操作的稳定错误码。取值同时出现在 EnvironmentResult.code 与
+ * EnvironmentError.code 上，UI 依此做本地化与按钮分派。
+ */
+export type EnvironmentErrorCode = 
+/** 环境名不合法（路径穿越、Windows 保留名等）。 */
+'invalid-name'
+/** 环境不存在。 */
+ | 'not-found'
+/** 环境已存在。 */
+ | 'already-exists'
+/** 官方内置环境（web/headless），只读。 */
+ | 'builtin'
+/** 当前进程正在运行的环境，不可停止/删除/重命名。 */
+ | 'current'
+/** 环境已有运行实例。 */
+ | 'running'
+/** 环境没有运行实例。 */
+ | 'not-running'
+/** 环境的层栈里没有任何能提供 web 服务的层，启动它不会有网页可访问。 */
+ | 'no-web-layer'
+/** 调用方显式指定的端口已经被监听：不猜「应答来自谁」，直接拒绝、不发起启动。 */
+ | 'port-in-use'
+/** 进程事实读不到（powershell/ps 不可用等）：运行状态未知，拒绝在未知状态下做破坏性操作。 */
+ | 'facts-unavailable'
+/** 未知的 bundle 模板名。 */
+ | 'unknown-template'
+/** 不是由 dsh 以 profile 方式启动，官方跨环境通道拿不到 installAnchor。 */
+ | 'no-profile-context'
+/** 官方 @deepseek-ai/dsh-plugin-manager/operations 子路径不可用。 */
+ | 'official-unavailable'
+/** 官方包操作返回非零退出码。 */
+ | 'package-operation-failed'
+/** 启动失败（含没有可用终端且后台启动也失败）。 */
+ | 'launch-failed'
+/** 端口在超时上限内没有就绪。 */
+ | 'timeout'
+/** SIGTERM 后进程仍在。 */
+ | 'kill-timeout'
+/** 备份文档结构不合法。 */
+ | 'unsafe-backup'
+/** 备份中存在不可恢复的条目（本地路径来源已消失）。 */
+ | 'unrestorable'
+/** 参数为空（例如没有选中任何插件）。 */
+ | 'empty-selection'
+/** 快照做不到"只含源环境现在的清单"（删不掉上一次物化留下的 node_modules 等）。 */
+ | 'snapshot-not-shallow'
+/** 文件系统操作失败。 */
+ | 'io-failed';
+/** 带稳定错误码的环境操作异常。 */
+export declare class EnvironmentError extends Error {
+    readonly code: EnvironmentErrorCode;
+    /**
+     * @param code - 稳定错误码，见 EnvironmentErrorCode。
+     * @param message - 面向用户的原因说明。
+     */
+    constructor(code: EnvironmentErrorCode, message: string);
+}
+/** 读进程表的注入点，供测试替换（生产路径见 defaultProcessLines）。 */
+export type ProcessLineReader = () => readonly string[];
+/** scanRuns 的选项。 */
+export interface ScanRunsOptions {
+    /** 缓存有效期；默认 SCAN_RUNS_TTL_MS。 */
+    readonly ttlMs?: number;
+    /** 时钟注入（测试）。 */
+    readonly now?: () => number;
+    /** 进程表读取器注入（测试）。默认按平台选择 /proc、ps 或 powershell。 */
+    readonly reader?: ProcessLineReader;
+    /** 绕过缓存强制重新扫描。 */
+    readonly fresh?: boolean;
+}
+/** 丢弃进程扫描缓存。启停成功后调用，让下一次读取立刻看到变化。 */
+export declare function resetRunCache(): void;
+/**
+ * 扫描进程表，找出每个环境的运行实例与端口（带缓存）。
+ *
+ * @param options - 缓存与注入选项。
+ * @returns 环境名到运行实例列表的映射；未运行的环境不出现在 map 里。
+ */
+export declare function scanRuns(options?: ScanRunsOptions): ReadonlyMap<string, readonly EnvironmentRun[]>;
+/**
+ * 立即扫描进程表，不经缓存。
+ *
+ * 启停的就绪与存活判定必须看到即时变化，否则刚起的实例会被 3s 陈旧缓存判成
+ * 「没起」，stop 也会对着一个已经退出的 pid 空转。调用方在状态变化后用
+ * resetRunCache 让读路径跟上。
+ *
+ * @param options - 注入选项。
+ * @returns 环境名到运行实例列表的映射。
+ */
+/**
+ * 一次进程事实读取的结果。
+ *
+ * `readable: false` 与「读到了、但一个实例都没在跑」是**两件事**（审计 W-19）：
+ * 旧实现把失败折叠成空表，调用方只能看到「这台机器上没有实例」，于是把不知道说成了知道。
+ * 不可读时调用方必须如实说「运行状态未知」，破坏性操作必须拒绝。
+ */
+export interface ProcessFacts {
+    /** 环境名 → 运行实例；不可读时为空 Map（**不要据此判断「没在运行」**）。 */
+    readonly runs: ReadonlyMap<string, readonly EnvironmentRun[]>;
+    /** 进程事实是否读到。 */
+    readonly readable: boolean;
+    /** 不可读的原因（面向用户）。 */
+    readonly reason?: string;
+}
+/**
+ * 立即读取进程事实（含「读不到」这个状态），并写入缓存。
+ *
+ * @param options - 注入选项。
+ * @returns 事实与可读性。
+ */
+export declare function processFactsNow(options?: ScanRunsOptions): ProcessFacts;
+/**
+ * 读取进程事实（带缓存）。
+ *
+ * @param options - 缓存与注入选项。
+ * @returns 事实与可读性。
+ */
+export declare function processFacts(options?: ScanRunsOptions): ProcessFacts;
+/**
+ * 立即扫描进程表，不经缓存（只要实例映射；可读性请用 processFactsNow）。
+ *
+ * @param options - 注入选项。
+ * @returns 环境名到运行实例列表的映射。
+ */
+export declare function scanRunsNow(options?: ScanRunsOptions): Map<string, readonly EnvironmentRun[]>;
+/**
+ * 读某个 pid 的命令行。
+ *
+ * kill 前的复核用它：pid 可能已被回收，必须重新证明它仍是同名环境的实例。读不
+ * 到时返回 null —— 调用方必须据此放弃 kill，而不是照杀不误。
+ *
+ * @param pid - 目标进程。
+ * @returns 命令行原文；不可读时为 null。
+ */
+export declare function readProcessCommand(pid: number): string | null;
+/**
+ * 廉价存活探针：signal 0 只在进程消失时抛 ESRCH；EPERM 说明进程还在（别人持有）。
+ *
+ * @param pid - 目标进程。
+ * @returns 是否存活。
+ */
+export declare function pidAlive(pid: number): boolean;
+/** 需要「当前环境」事实的操作的共享选项。 */
+export interface CurrentEnvironmentOptions {
+    /** host 上下文：当前环境从 ctx.profileContext 读（权威事实）。 */
+    readonly ctx?: Context;
+    /** 覆盖当前环境判定（测试注入）。 */
+    readonly current?: string | null;
+    /** 覆盖官方能力探测（测试注入）。 */
+    readonly capabilities?: OfficialCapabilities;
+}
+/**
+ * 当前环境名（UI 与其它模块复用）。
+ *
+ * @param ctx - host 上下文。
+ * @returns 环境名；未知时 null。
+ */
+export declare function currentEnvironment(ctx?: Context): string | null;
+/** listEnvironments 的选项。 */
+export interface ListEnvironmentsOptions extends CurrentEnvironmentOptions {
+    /** 复用的进程扫描结果；省略时走 scanRuns 的缓存扫描。 */
+    readonly runs?: ReadonlyMap<string, readonly EnvironmentRun[]>;
+    /** 复用的进程事实（带可读性）；省略时自行读取。 */
+    readonly facts?: ProcessFacts;
+}
+/**
+ * 列出 $DSH_HOME/profiles 下的环境及其只读事实。
+ *
+ * @param ctx - host 上下文；用于取官方认定的「当前环境」。
+ * @param options - 注入选项。
+ * @returns 按名称排序的环境列表。
+ */
+export declare function listEnvironments(ctx?: Context, options?: ListEnvironmentsOptions): EnvironmentInfo[];
+/** 官方 bundle 模板（创建环境时可选），直接来自官方 PROFILE_TEMPLATES。 */
+export interface EnvironmentTemplate {
+    readonly name: string;
+    readonly bundles: readonly string[];
+}
+/**
+ * 可用的环境模板。
+ *
+ * @returns 官方模板名与它们的 bundle 清单（本仓库不维护任何 bundle 名单）。
+ */
+export declare function environmentTemplates(): readonly EnvironmentTemplate[];
+/**
+ * 官方 web 模板相对官方默认层栈多出来的那几层 —— 也就是「能提供 web 面」的包。
+ *
+ * 派生自官方常量（PROFILE_TEMPLATES / DEFAULT_PROFILE_BUNDLES）：官方改了模板，
+ * 这里跟着变，不需要改代码，也不需要我们维护一份会漂移的名字表。
+ *
+ * @returns 官方 web app 层的包名；官方常量里没有该模板时返回空数组。
+ */
+export declare function officialWebAppBundles(): readonly string[];
+/** 一个环境的 web 层判定。 */
+export type WebLayerPresence = 'present' | 'absent' | 'unknown';
+/**
+ * 判断一个环境的层栈里有没有能提供 web 服务的层。
+ *
+ * 两条官方事实，先静态后动态：
+ *   1. 层名出现在官方 web 模板的 app 层里（官方常量派生，覆盖官方模板建的层栈）；
+ *   2. 逐层用官方 resolveBundleDir 找到包目录、读它的 manifest：依赖或 peer 里出现
+ *      WEB_SERVER_PACKAGE 的层就是 web 层（这条能认出官方模板之外的 web bundle）。
+ *
+ * 只有「每一层都能解析、且都不满足上面两条」才敢说 absent —— 任何一层的事实拿不到
+ * 就返回 unknown，调用方据此降级为「无法预判，仍按就绪探测等待」，绝不预判成 absent
+ * 去拒绝一个可能能跑的环境。
+ *
+ * @param dir - 环境目录。
+ * @param bundles - 该环境的 bundle 层栈。
+ * @param installAnchor - 官方安装锚点；省略时用该环境自己的 manifest 作解析锚点（官方第二锚点）。
+ * @returns 判定结果。
+ */
+export declare function environmentWebLayer(dir: string, bundles: readonly string[], installAnchor?: string): WebLayerPresence;
+/**
+ * 环境名的完整校验（含平台的额外约束）。
+ *
+ * @param name - 待校验的环境名。
+ * @returns 拒绝原因；合法时为 null。
+ */
+export declare function environmentNameProblem(name: string): string | null;
+/**
+ * 创建一个环境（骨架由官方 initProfile 写：manifest、空 patch 层、pnpm 设置）。
+ *
+ * 模板只接受官方 PROFILE_TEMPLATES 的名字；不存在的模板名是配置错误，直接失败，
+ * 而不是悄悄换成别的 bundle 列表。
+ *
+ * 省略模板时用 DEFAULT_ENVIRONMENT_TEMPLATE（官方 web 模板），**不是**官方
+ * DEFAULT_PROFILE_BUNDLES：后者只有 base、没有任何 app，建出来的环境必然起不来
+ * （实测 startEnvironment 干等 30s 超时）。
+ *
+ * @param name - 新环境名。
+ * @param template - 官方模板名；省略时用官方 web 模板。
+ * @returns 操作结果。
+ */
+export declare function createEnvironment(name: string, template?: string): Promise<EnvironmentResult>;
+/** renameEnvironment 的选项。 */
+export type RenameEnvironmentOptions = CurrentEnvironmentOptions;
+/**
+ * 重命名一个环境目录。拒绝内置环境、当前环境与运行中的环境。
+ *
+ * @param from - 原名。
+ * @param to - 新名。
+ * @param options - 当前环境事实。
+ * @returns 操作结果。
+ */
+export declare function renameEnvironment(from: string, to: string, options?: RenameEnvironmentOptions): Promise<EnvironmentResult>;
+/** removeEnvironment 的选项。 */
+export type RemoveEnvironmentOptions = CurrentEnvironmentOptions;
+/**
+ * 删除一个环境目录。拒绝内置环境、当前环境与运行中的环境。
+ *
+ * @param name - 环境名。
+ * @param options - 当前环境事实。
+ * @returns 操作结果。
+ */
+export declare function removeEnvironment(name: string, options?: RemoveEnvironmentOptions): Promise<EnvironmentResult>;
+/** 一次启动的目标描述。 */
+export interface LaunchSpec {
+    readonly profile: string;
+    readonly port: number;
+    readonly mode: 'terminal' | 'background';
+    /** 要执行的可执行文件。 */
+    readonly command: string;
+    readonly args: readonly string[];
+    /** dsh 入口脚本绝对路径；走 PATH shim 时为 null。 */
+    readonly entry: string | null;
+    /**
+     * 是否需要经 shell 启动。
+     *
+     * Windows 上 PATH shim 是 `dsh.cmd`：Node ≥20.12 起 `spawn('x.cmd')` 不带 shell 会**抛 EINVAL**
+     * （审计 W-07 已在真 win32 Node 上实测），所以这条回退路径必须显式声明要 shell；
+     * 首选路径（process.execPath + bin.js）保持无 shell 的官方启动纪律。
+     */
+    readonly shell: boolean;
+    /** 环境目录。 */
+    readonly dir: string;
+    /** 面向用户的等价命令行（原样展示，不执行）。 */
+    readonly display: string;
+}
+/** 启动结果。 */
+export interface LaunchOutcome {
+    readonly ok: boolean;
+    readonly detail: string;
+    /** 实际采用的启动方式；没有可用终端时会从 terminal 降级为 background。 */
+    readonly mode: 'terminal' | 'background';
+    /** 终端模式实际用的终端名。 */
+    readonly terminal?: string;
+    /** 后台模式捕获官方输出到的日志路径（里面有官方打印的带 token 地址）。 */
+    readonly logPath?: string;
+    /**
+     * 为什么最终是这个启动方式（降级原因）。
+     *
+     * 独立复验 N-03：`wt` 缺失 → 降级后台时，成功与失败两条文案都只说「启动方式：后台」，
+     * 用户不知道**为什么**不是终端窗口。这是「用户即将做的动作的后果」类信息（DESIGN §12.2
+     * 的保留清单），必须下发。
+     */
+    readonly reason?: string;
+}
+/** startEnvironment 的选项。 */
+export interface StartEnvironmentOptions {
+    /** 启动方式；terminal 在当前平台没有可用终端时自动降级为后台。 */
+    readonly mode?: 'terminal' | 'background';
+    /** 指定端口；省略时从 portStart 起找一个空闲端口。 */
+    readonly port?: number;
+    /** 自动选端口的起点；默认 DEFAULT_WEB_PORT。 */
+    readonly portStart?: number;
+    /** 就绪上限；默认 START_READY_TIMEOUT_MS。 */
+    readonly readyTimeoutMs?: number;
+    /** 追加给被启动应用的参数。 */
+    readonly extraArgs?: readonly string[];
+    /** host 上下文：用于取官方 installAnchor 判定 web 层。 */
+    readonly ctx?: Context;
+    /** installAnchor 覆盖；省略时取 ctx.profileContext.installAnchor，再退到该环境自己的 manifest。 */
+    readonly installAnchor?: string;
+    /** 启动器注入（测试）：替换终端/后台启动。 */
+    readonly launch?: (spec: LaunchSpec) => Promise<LaunchOutcome>;
+    /** HTTP 就绪探测注入（测试）：返回状态码；null 表示没有应答。 */
+    readonly probe?: (port: number) => Promise<number | null>;
+    /** 时钟注入（测试）。 */
+    readonly now?: () => number;
+    /** 等待注入（测试）。 */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * 启动一个环境的实例。
+ *
+ * 四道关，越靠前越便宜：
+ *   1. 环境存在、不在运行中；
+ *   2. **web 层预检**：层栈里没有任何 web 服务层就立刻拒绝（实测 base-only 环境要干等
+ *      30s 才超时，用户拿到的是「端口未就绪」这种没法行动的信息）；
+ *   3. 选空闲端口，按 mode 在终端窗口或后台启动；
+ *   4. 等**官方 HTTP 端点应答**（不是等 TCP 可连接 —— 实测 TCP 通了那一刻 GET / 还是
+ *      404，1000ms 后才是 401，提前报成功会把不可用的 url 交出去）。
+ *
+ * @param name - 环境名。
+ * @param options - 启动选项。
+ * @returns 操作结果；成功时 output 含实际启动方式与可用地址（带 token，见 startedMessage）。
+ */
+export declare function startEnvironment(name: string, options?: StartEnvironmentOptions): Promise<EnvironmentResult>;
+/**
+ * 被启动实例的入口。
+ *
+ * 优先复用本进程自己所属的安装：process.argv[1] 就是当前 dsh 的入口脚本，node 是
+ * process.execPath —— 同一个安装、同一个版本，不依赖 PATH（旧实现靠 PATH 找 dsh，
+ * 在 nvm 未加载的终端里会失败）。
+ *
+ * @returns 命令、前置参数与入口脚本路径。
+ */
+/**
+ * 被启动实例的入口（可注入 argv/platform，供测试）。
+ *
+ * @param argv - 进程参数；默认 process.argv。
+ * @param platform - 平台；默认 process.platform。
+ * @returns 命令、前置参数、入口脚本与是否需要 shell。
+ */
+export declare function dshEntryPoint(argv?: readonly string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: readonly string[];
+    entry: string | null;
+    shell: boolean;
+};
+/**
+ * .cmd/.bat shim 的启动形态（显式 cmd、argv 直传、参数先校验）。
+ *
+ * @param spec - 启动描述（shell 为 true 时才有意义）。
+ * @returns 命令与参数。
+ * @throws 参数含 cmd 不安全字符时（绝不静默交给 cmd 拆错）。
+ */
+export declare function windowsShimInvocation(spec: LaunchSpec): {
+    command: string;
+    args: readonly string[];
+};
+/**
+ * Windows 可见终端窗口的启动形态（Windows Terminal，官方 open-in-app 目录的 Win 终端项就是 wt：
+ * packages/host/open-in-app/src/catalog.ts:361）。
+ *
+ * 为什么不用 `cmd /c start "" cmd /k <命令行>`：那条串是裸拼接的展示文本，交给 cmd 会**重新
+ * 分词**；官方安装包默认在 `C:\Program Files\nodejs`，含空格时新窗口里只有「找不到命令」，
+ * 而失败要等 30s 就绪超时才暴露（审计 W-08）。wt 收的是 argv，程序与每个参数各自成段，
+ * 不再经过 shell 分词。
+ *
+ * @param spec - 启动描述。
+ * @returns 要执行的命令与参数（argv 形态）。
+ */
+export declare function windowsTerminalInvocation(spec: LaunchSpec): {
+    command: string;
+    args: readonly string[];
+};
+/** stopEnvironment 的选项。 */
+export interface StopEnvironmentOptions extends CurrentEnvironmentOptions {
+    /** 等待退出的上限；默认 STOP_TIMEOUT_MS。 */
+    readonly timeoutMs?: number;
+    /** 注入时钟（测试）。 */
+    readonly now?: () => number;
+    /** 注入等待（测试）。 */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * 注入「读某个 pid 的命令行」（测试）。
+     *
+     * 为什么需要它：kill 前的复核在 Windows 上走 powershell，POSIX 上读 /proc —— 在 Linux 上
+     * 伪装 process.platform='win32' 会让复核必然读不到（找不到 powershell），于是整条 Windows
+     * 分支无法在 Linux 回归里覆盖。这是与 probe/launch/sleep 同风格的测试接缝。
+     */
+    readonly readCommand?: (pid: number) => string | null;
+}
+/**
+ * 停止一个环境的实例 —— 只按 pid 精确 kill。
+ *
+ * 绝不 pkill -f "dsh --profile NAME"：那会连带杀掉命令行里恰好出现同一字符串的
+ * 无关进程，也会杀掉同名的 pnpm 与一次性命令。这里的流程是：扫描，取同名环境的
+ * pid，逐个用 readProcessCommand 复核该 pid 仍然是同一环境的实例，再终止（POSIX
+ * SIGTERM；Windows taskkill /T /F 结束进程树，见 terminateInstance），最后轮询存活。
+ * 结果文案如实说明是哪种终止方式 —— Windows 上不存在「优雅停止」这回事。
+ *
+ * @param name - 环境名。
+ * @param options - 停止选项。
+ * @returns 操作结果。
+ */
+export declare function stopEnvironment(name: string, options?: StopEnvironmentOptions): Promise<EnvironmentResult>;
+/** 官方包操作运行器。默认动态 import 官方子路径；测试可注入。 */
+export type PluginCommandRunner = (context: PackageOperationContext, args: readonly string[], options: PackageOperationOptions) => Promise<PackageResult>;
+/** 跨环境写操作的共享选项。 */
+export interface CrossEnvironmentOptions {
+    /** host 上下文：installAnchor 从 ctx.profileContext 取。 */
+    readonly ctx?: Context;
+    /** installAnchor 覆盖（测试，或应用自有 profile）。官方事实拿不到时必须显式给出。 */
+    readonly installAnchor?: string;
+    /** 官方 operations 运行器覆盖（测试注入，避免真的跑 pnpm）。 */
+    readonly runCommand?: PluginCommandRunner;
+    /** 输出回调（逐块）。 */
+    readonly onOutput?: (text: string, stream: 'stdout' | 'stderr') => void;
+    /** 输出上限；默认 64KiB。 */
+    readonly outputBytes?: number;
+    /** 官方 operations 的锁等待上限；默认 120s。 */
+    readonly lockWaitMs?: number;
+}
+/**
+ * 修复安装：把当前 profile **已声明**的依赖真正装进 node_modules。
+ *
+ * 为什么不能走 add：官方 inspect 把「已声明」当作「已安装」（already-installed 是官方
+ * PluginInspectProblem 闭集里的取值），于是对「声明了但没装」的包走 add 必被拒绝，
+ * 修复输出「拒绝安装：already-installed」——与诊断结论直接矛盾，用户点多少次都不会成功
+ * （write-auditor 真机验证发现，见 docs/private/write-path-audit.md §3·P3）。
+ *
+ * 官方 `dsh plugin --profile X install` 就是把参数转发给 pnpm 的官方通道（apps/cli/src/plugin.ts
+ * 也走同一个 runPluginCommand），修复安装用它。
+ *
+ * @param target - 包名（只用于文案；官方 install 按 package.json 全量收敛）。
+ * @param options - 共享选项。
+ * @returns 结果；官方通道不可用或 pnpm 非零退出时如实报失败，不静默降级。
+ */
+export declare function repairDependencies(target: string, options?: CrossEnvironmentOptions): Promise<EnvironmentResult>;
+/**
+ * 把源环境里已装的插件装到目标环境。
+ *
+ * 与当前环境的写操作走官方 pluginManager 服务不同，这里是同一套官方 pnpm 通道加换
+ * 一个 profile 参数：runPluginCommand({ profile, dir, installAnchor, cwd, home },
+ * ['add', spec])。整批只占一次进程内互斥（分批会让并发的安装/删除插进条目之间，
+ * 互相覆盖 manifest）。
+ *
+ * @param from - 源环境名。
+ * @param to - 目标环境名。
+ * @param names - 要复制的包名（按源 manifest 里记录的来源重装）。
+ * @param options - 共享选项。
+ * @returns 操作结果。
+ */
+export declare function copyPlugins(from: string, to: string, names: readonly string[], options?: CrossEnvironmentOptions): Promise<EnvironmentResult>;
+/** 测试环境名的后缀。一个真实环境对应一个测试环境（保真需要，§5.4 命名与归属）。 */
+export declare const TRIAL_ENVIRONMENT_SUFFIX = "-dpmc";
+/**
+ * 某个真实环境对应的测试环境名。
+ *
+ * @param realName - 真实环境名。
+ * @returns 测试环境名。
+ */
+export declare function trialEnvironmentName(realName: string): string;
+/**
+ * 是不是我们创建的测试环境（只看名字形态）。
+ *
+ * 删除路径先用它筛，再核对归属（§5.4 清理）：不靠台账，台账会过期。
+ *
+ * @param name - 环境名。
+ * @returns 是否形如测试环境。
+ */
+export declare function isTrialEnvironmentName(name: string): boolean;
+/**
+ * 测试环境名对应的真实环境名；不是测试环境时 null。
+ *
+ * @param name - 环境名。
+ * @returns 真实环境名或 null。
+ */
+export declare function trialEnvironmentOwner(name: string): string | null;
+/**
+ * 环境指纹（DESIGN §5.4）：五元组，**全部读盘**，不读我们的内存台账。
+ *
+ * 为什么不读台账：用户可能在终端里跑官方 dsh plugin add、或直接改文件，那些改动不会经过我们，
+ * 台账必然过期。所以每次要用测试环境之前重算一次、与记录比对。
+ */
+export interface EnvironmentFingerprint {
+    /** package.json 内容 hash；缺失时 null（缺失与空文件是两件事）。 */
+    readonly manifestHash: string | null;
+    /** pnpm-lock.yaml 内容 hash；缺失时 null。 */
+    readonly lockfileHash: string | null;
+    /** cordis.patch.yml 内容 hash；缺失时 null。 */
+    readonly patchHash: string | null;
+    /** bundle 层栈。 */
+    readonly bundles: readonly string[];
+    /** 层栈来源：官方 listBundles() 还是本地 manifest（**口径不同，必须标**）。 */
+    readonly bundlesSource: 'official' | 'manifest';
+    /** 直接依赖名（排序）。 */
+    readonly dependencies: readonly string[];
+    /** 五元组的整体 hash（比对用）。 */
+    readonly hash: string;
+}
+/** environmentFingerprint 的选项。 */
+export interface FingerprintOptions {
+    /** 官方层栈事实：ctx.pluginManager.listBundles()（只在测当前环境时可用）。 */
+    readonly listBundles?: () => Promise<readonly string[]>;
+}
+/**
+ * 算一个环境当前的指纹（读盘）。
+ *
+ * @param name - 环境名。
+ * @param options - 官方层栈来源（可注入；拿不到时退回 manifest 并如实标注口径）。
+ * @returns 指纹。
+ */
+export declare function environmentFingerprint(name: string, options?: FingerprintOptions): Promise<EnvironmentFingerprint>;
+/**
+ * 两份指纹是否同一环境状态。
+ *
+ * @param a - 之一。
+ * @param b - 之二。
+ * @returns 是否一致。
+ */
+export declare function sameFingerprint(a: EnvironmentFingerprint, b: EnvironmentFingerprint): boolean;
+/** 一次挂载验证的判定（三态；DESIGN §5.2：**退出码不参与判定**）。 */
+export type BootVerdict = 
+/** 树挂载成功（stderr 只有官方的「缺任务」用法提示）。 */
+{
+    readonly kind: 'mounted';
+}
+/** 挂载失败，带根因链。 */
+ | {
+    readonly kind: 'failed';
+    readonly reason: string;
+    readonly chain: readonly string[];
+}
+/** 判不出来（没有可识别特征、进程没起来、被超时杀掉等）。 */
+ | {
+    readonly kind: 'undetermined';
+    readonly reason: string;
+};
+/**
+ * 从 stderr 文本判定挂载结果（纯函数，可注入文本测试）。
+ *
+ * 判据（§5.2 实测）：健康环境 stderr 只有一行 dsh: a task is required…，而**退出码仍是 1**，
+ * 所以退出码不能用作判据；失败是 plugin tree failed to load + cause 链。两者都没有 → 无法判定。
+ *
+ * @param stderr - 子进程的 stderr 文本。
+ * @returns 三态判定。
+ */
+export declare function judgeBootStderr(stderr: string): BootVerdict;
+/**
+ * 一次验证启动的超时上限。
+ *
+ * 官方 smoke 用 90s 是在等一个真实服务；我们只等**就绪行**（实测报文 <1s），
+ * 所以收在 15s：既是 20 倍余量，也把"判不出来"的等待从 30s 砍到 15s。
+ */
+export declare const VERIFY_TIMEOUT_MS = 15000;
+/**
+ * 验证启动的参数：**按层栈决定形态**（未知参数不能盲加——headless 类环境不认 --port）。
+ *
+ * @param prefixArgs - 启动器入口自己的参数（`dshEntryPoint().args`）。
+ * @param name - 环境名。
+ * @param webLayer - 该环境的 web 层判定（environmentWebLayer）。
+ * @returns 完整参数表。
+ */
+export declare function verificationArgs(prefixArgs: readonly string[], name: string, webLayer: WebLayerPresence): readonly string[];
+/** 一次验证启动收集到的原始信号（判定只看它，退出码不参与）。 */
+export interface BootSignals {
+    /** 子进程 stderr 原文。 */
+    readonly stderr: string;
+    /** 子进程 stdout 原文（服务形态的就绪行在这里）。 */
+    readonly stdout?: string;
+    /** 就绪行里的地址（`dsh web: http://…`）；没有信号时 null。 */
+    readonly readyUrl?: string | null;
+    /** 退出码；**仅供展示与排查，不参与判定**（§5.2）。 */
+    readonly exitCode: number | null;
+    /** 是否读到就绪行后主动杀了子进程（服务形态常驻，必须收工）。 */
+    readonly killedAfterReady?: boolean;
+}
+/**
+ * 从一次启动的原始信号给判定（纯函数，可注入文本测试）。
+ *
+ * 两类环境各用各的就绪信号，**谁先出现算谁**（谁先出现由启动器决定，见 defaultHeadlessRun）：
+ *   · 服务形态：stdout 的官方就绪行 → mounted；
+ *   · headless 形态：stderr 的 `dsh: a task is required…` → mounted（走 judgeBootStderr）。
+ * 失败一律读 stderr（`plugin tree failed to load` / `cannot resolve profile bundle` + cause 链）；
+ * 什么信号都没有 → undetermined（**不许当通过**）。
+ *
+ * @param signals - 原始信号。
+ * @returns 三态判定。
+ */
+export declare function judgeBootSignals(signals: BootSignals): BootVerdict;
+/** 试装的三种结论（§5.2：各有措辞、不得混；无法试装**不算通过**）。 */
+export type TrialConclusion = 
+/** 基线起得来、装完候选包也起得来 → 通过。 */
+'passed'
+/** 快照基线本身就起不来：不是候选包的问题。 */
+ | 'baseline-broken'
+/** 基线好、装完候选包起不来：候选包导致的。 */
+ | 'candidate-broken'
+/** 无法试装（例如禁用联网且本地 store 没有该包）：**不能算通过**。 */
+ | 'cannot-trial';
+/**
+ * 按受控对照四步给结论（§5.2）。
+ *
+ * 判定顺序刻意如此：先看基线，再看候选 —— 基线失败时不许赖候选包。
+ *
+ * @param baseline - 物化快照后的挂载判定；没做基线启动时 null。
+ * @param candidate - 装完候选包后的挂载判定；没走到这一步 null。
+ * @param cannotTrialReason - 提前失败的原因（如无法下载候选包）；给了就只报「无法试装」。
+ * @returns 结论。
+ */
+export declare function judgeTrialOutcome(baseline: BootVerdict | null, candidate: BootVerdict | null, cannotTrialReason?: string): TrialConclusion;
+/** 快照深度（§5.2/§5.3）：自动判定，可强制。 */
+export type SnapshotDepth = 'shallow' | 'full';
+/**
+ * 自动判定快照深度：层栈是否**全部由安装锚点提供**。
+ *
+ * 判据复用同一套事实（与指纹的 bundlesSource 同源：都是「层从哪里来」），不另起一套：
+ *   · 某一层出现在 <dir>/node_modules 里 → 它是 profile 自己装的（第三方 bundle），
+ *     浅快照（只复制清单）复现不出来 → full；
+ *   · 否则试官方解析 resolveBundleDir：能从安装锚点解析到 → 浅快照够用 → shallow。
+ * 拿不到锚点、或解析失败 → 一律 full（写多不写少）。
+ *
+ * @param dir - 真实环境目录。
+ * @param bundles - 该环境的层栈。
+ * @param installAnchor - 官方安装锚点（package.json 路径）。
+ * @returns 深度。
+ */
+export declare function snapshotDepthFor(dir: string, bundles: readonly string[], installAnchor?: string): SnapshotDepth;
+/** 快照物化的结果。 */
+export interface SnapshotMaterialization {
+    readonly depth: SnapshotDepth;
+    /** 从真实环境复制过来的文件名。 */
+    readonly copied: readonly string[];
+    /** 物化前清掉的**上一次物化残留**（例如 node_modules）：快照不能带着旧依赖。 */
+    readonly cleared: readonly string[];
+    /** 是否跑了官方 pnpm 通道（full 深度时）。 */
+    readonly installed: boolean;
+    /** 面向用户的说明。 */
+    readonly output: string;
+}
+/** materializeSnapshot 的选项。 */
+export interface MaterializeSnapshotOptions extends CrossEnvironmentOptions {
+    /** 强制深度；省略 = 自动判定。 */
+    readonly depth?: SnapshotDepth;
+    /** 层栈来源（官方 listBundles()）；拿不到就用源环境的清单，够自动判定用。 */
+    readonly bundlesOf?: (name: string) => Promise<readonly string[]>;
+}
+/**
+ * 把真实环境物化成测试环境（§5.4 同步原则：不订阅变化，用时即时物化）。
+ *
+ * 浅快照只复制清单文件；full 深度再走**官方 runPluginCommand** 装依赖（绝不自己调 pnpm 二进制）。
+ * 官方通道不可用或失败时如实抛出 —— 调用方据此报「无法试装」，不许静默当成功。
+ *
+ * @param sourceName - 真实环境名。
+ * @param targetName - 测试环境名（应等于 trialEnvironmentName(sourceName)）。
+ * @param options - 深度、层栈来源与官方通道注入。
+ * @returns 物化结果。
+ */
+export declare function materializeSnapshot(sourceName: string, targetName: string, options?: MaterializeSnapshotOptions): Promise<SnapshotMaterialization>;
+/** createTrialEnvironment 的选项。 */
+export interface CreateTrialEnvironmentOptions {
+    /** 建立后是否立即物化快照（默认 true）。 */
+    readonly materialize?: boolean;
+    /** 物化选项。 */
+    readonly snapshot?: MaterializeSnapshotOptions;
+}
+/**
+ * 建立/复用某个真实环境的测试环境（§5.4：一个真实环境一个测试环境）。
+ *
+ * @param realName - 真实环境名。
+ * @param options - 物化选项。
+ * @returns 结果（output 含快照深度与文件清单）。
+ */
+export declare function createTrialEnvironment(realName: string, options?: CreateTrialEnvironmentOptions): Promise<EnvironmentResult>;
+/** removeTrialEnvironment 的选项。 */
+export interface RemoveTrialEnvironmentOptions extends CurrentEnvironmentOptions {
+    /** 注入进程事实（测试）；省略时自行读取（fresh）。 */
+    readonly facts?: ProcessFacts;
+}
+/**
+ * 删除一个测试环境（§5.4：**删除必须安全**）。
+ *
+ * 三重纪律：
+ *  1. 只删形如 <真实名>-dpmc 的环境（裸后缀不算：没有归属的目录不能进删除路径）；
+ *  2. 运行中先拒 —— 不做「先停后删」的隐式动作，停是用户的显式决定；
+ *  3. 进程事实不可读 → 拒绝（**未知状态下绝不动磁盘**，与 stop/remove 同一条纪律）。
+ * 孤儿（真实环境已改名或删除）**可以删**：归属核对的是「名字形态 + 这是我们建的测试环境」，
+ * 不是「真实环境还在」。
+ *
+ * @param name - 测试环境名。
+ * @param options - 当前环境事实与进程事实注入。
+ * @returns 操作结果。
+ */
+export declare function removeTrialEnvironment(name: string, options?: RemoveTrialEnvironmentOptions): Promise<EnvironmentResult>;
+/** 清理候选：全部读盘得来（mtime 取目录自身）。 */
+export interface TrialCleanupCandidate {
+    readonly name: string;
+    /** 归属的真实环境名（名字形态推出）。 */
+    readonly owner: string;
+    /** 目录 mtime（毫秒）。 */
+    readonly modifiedAt: number;
+    readonly running: boolean;
+}
+/** 默认保留天数（§5.3：默认开 / 14 天，可关可配）。 */
+export declare const DEFAULT_TRIAL_RETENTION_DAYS = 14;
+/** planTrialCleanup 的选项。 */
+export interface TrialCleanupPlanOptions {
+    /** 当前时间（毫秒）；注入供测试。 */
+    readonly now?: number;
+    /** 保留天数；null 表示用户关掉了自动清理。 */
+    readonly retainDays?: number | null;
+}
+/** 一份清理计划：删什么、留什么，各自带原因。 */
+export interface TrialCleanupPlan {
+    readonly remove: readonly {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+    readonly keep: readonly {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * 算一份测试环境清理计划（纯函数，便于正反用例测试）。
+ *
+ * 只按「到没到保留期」与「是否在跑」两个事实判；运行中的永远保留（删除安全优先）。
+ * `retainDays: null` = 用户关掉了自动清理：什么都不删，但仍把候选列出来给界面显示。
+ *
+ * @param candidates - 候选（读盘事实）。
+ * @param options - 时间与保留期。
+ * @returns 计划。
+ */
+export declare function planTrialCleanup(candidates: readonly TrialCleanupCandidate[], options?: TrialCleanupPlanOptions): TrialCleanupPlan;
+/**
+ * 列出所有测试环境候选（读盘；进程事实不可读时按「未知」处理 → 全部保留）。
+ *
+ * @param options - 进程事实注入（测试）。
+ * @returns 候选列表与进程事实的可读性。
+ */
+export declare function listTrialEnvironments(options?: {
+    readonly facts?: ProcessFacts;
+}): {
+    readonly candidates: readonly TrialCleanupCandidate[];
+    readonly factsReadable: boolean;
+    readonly reason?: string;
+};
+/**
+ * 执行清理（§5.4：删除动作**记日志**）。
+ *
+ * @param options - 计划选项 + 日志回调。
+ * @returns 结果（删了哪些、留了哪些）。
+ */
+export declare function cleanupTrialEnvironments(options?: TrialCleanupPlanOptions & {
+    readonly facts?: ProcessFacts;
+    readonly log?: (line: string) => void;
+}): Promise<EnvironmentResult & {
+    readonly removed: readonly string[];
+}>;
+/**
+ * 构建指纹（CODE-POLICY §7.8 / DEVELOPMENT §87）：真机结论必须钉在一次具体构建上。
+ *
+ * 产物 md5 取本模块被打进的那份文件（安装到用户环境里也能算），git HEAD 只在能读到仓库时带上，
+ * 读不到就 null —— 如实标「不知道这份构建对应哪个 commit」，不编。
+ */
+export interface BuildIdentity {
+    /** 本模块产物的 md5（dist/<file>.js）。 */
+    readonly artifactMd5: string | null;
+    /** 产物文件 mtime（ISO）。 */
+    readonly artifactMtime: string | null;
+    /** git HEAD；读不到仓库时为 null。 */
+    readonly gitHead: string | null;
+}
+/**
+ * 算当前构建的指纹。
+ *
+ * @returns 构建指纹。
+ */
+export declare function buildIdentity(): BuildIdentity;
+/** 一次无头验证的结果（判定 + 证据）。 */
+export interface BootVerification {
+    readonly verdict: BootVerdict;
+    /** 实测耗时（毫秒）。 */
+    readonly elapsedMs: number;
+    /** 子进程 stderr 原文（截断到 8KiB，供展示与判定复核）。 */
+    readonly stderr: string;
+    /** 子进程 stdout 原文（截断到 8KiB）；服务形态的就绪行在这里。老调用点可省略。 */
+    readonly stdout?: string;
+    /** 就绪行里的地址（服务形态）；没有信号时 null。 */
+    readonly readyUrl?: string | null;
+    /** 是否读到就绪行后主动杀了子进程（服务形态常驻，必须收工）。 */
+    readonly killedAfterReady?: boolean;
+    /** 退出码；**仅供展示与排查，不参与判定**（§5.2）。 */
+    readonly exitCode: number | null;
+    /** 本次验证所在的构建指纹。 */
+    readonly build: BuildIdentity;
+}
+/** runHeadlessVerification 的选项。 */
+export interface HeadlessVerificationOptions {
+    /** 超时上限；默认 VERIFY_TIMEOUT_MS（15s）。 */
+    readonly timeoutMs?: number;
+    /**
+     * 启动器注入（测试）：省略时真起进程。
+     * stdout / readyUrl / killedAfterReady 是服务形态那一路的证据，可以省略（headless 形态用不到）。
+     */
+    readonly run?: (name: string) => Promise<{
+        readonly stderr: string;
+        readonly exitCode: number | null;
+        readonly stdout?: string;
+        readonly readyUrl?: string | null;
+        readonly killedAfterReady?: boolean;
+    }>;
+}
+/**
+ * 无头验证一个环境（§5.2 的形态，不得偏离）。
+ *
+ * 形态：`<dsh> --profile <name>`，**不给任何任务文本**（给了就是真跑一轮 agent，花用户的钱），
+ * stdin=/dev/null，捕获 stderr；判定只读 stderr 特征（退出码不参与）。
+ *
+ * @param name - 环境名。
+ * @param options - 超时与启动器注入。
+ * @returns 验证结果。
+ */
+export declare function runHeadlessVerification(name: string, options?: HeadlessVerificationOptions): Promise<BootVerification>;
+/** 边收边判的启动信号收集器（纯逻辑，可按 chunk 驱动测试）。 */
+export interface BootSignalCollector {
+    /** 收一段 stderr。 */
+    pushStderr(chunk: string): void;
+    /**
+     * 收一段 stdout；返回**本次是否新认出就绪行**（调用方据此收工）。
+     *
+     * 两条纪律：
+     *   · 就绪行可能跨 chunk（官方一行也是一个 write，但流式读取不保证对齐）→ 每次都在累积文本里找；
+     *   · stderr 里已经出现失败特征时，**不再认**后来的就绪行（谁先出现算谁）。
+     */
+    pushStdout(chunk: string): boolean;
+    readonly readyUrl: string | null;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/**
+ * 造一个启动信号收集器。
+ *
+ * 为什么把它抽出来：就绪行的识别是"跨 chunk"和"顺序"两件事，真机跑一次证明不了边界，
+ * 而这两条边界恰恰是最容易写错的（先来的失败被后来的就绪行盖掉、半行就绪行被漏掉）。
+ *
+ * @returns 收集器。
+ */
+export declare function createBootSignalCollector(): BootSignalCollector;
+/** runTrialInstall 的选项。 */
+export interface TrialInstallOptions extends Omit<MaterializeSnapshotOptions, 'depth'> {
+    /**
+     * 深度策略：auto（默认，先浅快照、基线明确失败再升级 full）/ shallow / full。
+     *
+     * 为什么 auto 不再先问「锚点能否解析」：实测这条谓词对**原装环境一律返回 full**
+     * （官方层由安装锚点供给，但 resolveBundleDir 在这台机器上解析不到它们），
+     * 于是 shallow 成了走不到的分支，而 shallow 真机又能挂载（526ms）。
+     * 改成**以启动为判据**（Lead 授权）：先 shallow；基线**明确 failed** 才升级 full，
+     * 升级后仍不 mounted 才报 baseline-broken（文案写明两种快照都试过）。
+     * undetermined（超时/无可识别特征）**不升级** —— 那是「判不出来」，如实报。
+     */
+    readonly depth?: 'auto' | 'shallow' | 'full';
+    /** 官方层栈事实（算指纹用）；只在测当前环境时可用。 */
+    readonly listBundles?: () => Promise<readonly string[]>;
+    /** 是否做基线启动（§5.2 四步的②）；默认 true —— 关掉省 ~558ms，但失败时说不清是谁的问题。 */
+    readonly baseline?: boolean;
+    /** 是否允许联网拉取候选包（§5.3）；false 时只用本地 store，冷包直接判「无法试装」。 */
+    readonly allowNetwork?: boolean;
+    /** 无头验证注入（测试）。 */
+    readonly verify?: (name: string) => Promise<BootVerification>;
+    /** 时钟注入（测试）。 */
+    readonly now?: () => number;
+}
+/** 试装结果：结论 + 证据 + 构建指纹（§7.8 真机结论必须钉在一次具体构建上）。 */
+export interface TrialInstallResult {
+    readonly conclusion: TrialConclusion;
+    readonly output: string;
+    /** 本次结论对应的构建（产物 md5 + mtime + 能读到时的 git HEAD）。 */
+    readonly build: BuildIdentity;
+    /** 试装前的源环境指纹。 */
+    readonly sourceFingerprint: EnvironmentFingerprint;
+    /** 试装后再算的源环境指纹（§5.4 第 4 步）。 */
+    readonly sourceFingerprintAfter: EnvironmentFingerprint | null;
+    /** 试装期间源环境又变过（结论可能不适用）。 */
+    readonly changedDuringTrial: boolean;
+    readonly baseline: BootVerdict | null;
+    readonly candidate: BootVerdict | null;
+    readonly elapsedMs: number;
+    /** 结论实际基于哪种快照深度。 */
+    readonly depth: SnapshotDepth;
+    /** 是否发生过 shallow → full 的升级（只在基线明确失败时）。 */
+    readonly escalated: boolean;
+    /** 浅快照不给力的原因（升级时给出，取失败判定的第一行）。 */
+    readonly escalationReason?: string;
+    /** 卸包那一步的说明（task-84：让候选成为"新装"，做了/没做/失败都如实写）。 */
+    readonly detached?: string;
+    /**
+     * 候选的激活事实（进没进层栈）。拿到就带上，供调用方与界面判断"这次到底验证到了没有"。
+     */
+    readonly activation?: TrialActivationFact;
+}
+/**
+ * 候选在试装环境里的激活事实（"装上了"不等于"验证到了"的判据，可下发给界面）。
+ */
+export interface TrialActivationFact {
+    /** 候选包名；认不出来时 undefined。 */
+    readonly name: string | undefined;
+    /** 装完之后测试环境的层栈（dsh.profile.bundles）。 */
+    readonly bundles: readonly string[];
+    /** 候选是否真的进了层栈（false = 挂载期不会加载它，这次验证不作数）。 */
+    readonly activated: boolean;
+    /** 是否为了让候选成为"新装"而先走了官方 remove。 */
+    readonly removedFirst: boolean;
+    /** 卸包那一步的说明（做了/没做/失败，都如实写）。 */
+    readonly detachNote: string;
+}
+/**
+ * 受控对照四步（§5.2）：物化快照 → 基线启动 → 装候选包 → 二次启动。
+ *
+ * 缺一步结论就站不住，所以：基线失败一律报 baseline-broken（**不赖候选包**）；
+ * 装不上候选包报 cannot-trial（**不算通过**）；只有基线好、装完也好的才是 passed。
+ * 装候选包走**官方 runPluginCommand**（绝不自己调 pnpm）；allowNetwork=false 时加 --offline，
+ * 冷包失败如实报「无法试装」。
+ *
+ * @param spec - 候选包 spec。
+ * @param realName - 真实环境名（测试环境由它派生）。
+ * @param options - 四步选项与注入。
+ * @returns 结果（含证据与构建指纹）。
+ */
+export declare function runTrialInstall(spec: string, realName: string, options?: TrialInstallOptions): Promise<TrialInstallResult>;
+/**
+ * 备份文档格式标识（运行期常量）。
+ *
+ * 类型声明在 types.ts 的 BackupFormat（单一事实来源）；这里用类型断言把运行期值
+ * 绑到那个字面量上 —— 改一处漏另一处会编译失败。
+ */
+export declare const BACKUP_FORMAT: BackupFormat;
+/** 备份契约的再导出：类型唯一事实来源是 types.ts，本模块不重复定义。 */
+export type { BackupMissingEntry, EnvironmentBackup, EnvironmentBackupDiff };
+/**
+ * 导出环境备份。
+ *
+ * @param name - 环境名。
+ * @returns 备份文档。
+ * @throws {EnvironmentError} 名称不合法或环境不存在时（code 为 invalid-name / not-found）。
+ */
+export declare function backupExport(name: string): EnvironmentBackup;
+/**
+ * 对比备份与目标环境，分四类：缺失、已装、目标环境不存在、不可恢复。
+ *
+ * 恢复前必须先跑这一遍：差异既是用户确认的依据，也是恢复的输入（只装 missing）。
+ *
+ * @param backup - 备份文档。
+ * @param target - 目标环境名。
+ * @returns 差异。
+ * @throws {EnvironmentError} 备份结构不合法（code 为 unsafe-backup）或目标名不合法时。
+ */
+export declare function backupDiff(backup: EnvironmentBackup, target: string): EnvironmentBackupDiff;
+/** backupRestore 的选项。 */
+export interface RestoreEnvironmentOptions extends CrossEnvironmentOptions {
+    /** 只算差异、不写入。 */
+    readonly dryRun?: boolean;
+}
+/**
+ * 按备份恢复一个环境。
+ *
+ * 三步：先算差异（缺失/已装/目标不存在/不可恢复），再用官方 operations 逐条重装
+ * 缺失依赖，最后在官方文件锁下补回备份的 bundle 层栈。整批只占一次进程内互斥。
+ *
+ * 锁的用法按官方意图：装包由 runPluginCommand 自己持锁（我们再套一层会自锁 —— 同一
+ * 把 package.json.lock）；bundle 层栈的读-改-写由我们用 withFileLock 独占，避免与
+ * 并发的安装互相覆盖。
+ *
+ * @param backup - 备份文档。
+ * @param target - 目标环境名。
+ * @param options - 恢复选项。
+ * @returns 操作结果。
+ */
+export declare function backupRestore(backup: EnvironmentBackup, target: string, options?: RestoreEnvironmentOptions): Promise<EnvironmentResult>;