@@ -113,7 +113,7 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 - **禁止破坏真实用户配置**：`auth logout` 和 `config set` 默认只用 `--dry-run`；只有验证持久化契约时，才允许通过
   `BAILIAN_CONFIG_DIR` 指向每个用例独占的临时目录实际落盘，并必须在 `finally` 中清理；禁止写入或复用真实 `~/.bailian`
-- **默认测试隔离**：`runNodeMain` / `runCommandE2e` / `runCli` / `runKscli` 默认走 `e2e/isolation`（HOME 与 `XDG_CONFIG_HOME` 隔离、强制 `language: en-US`、关闭 HOME 外的系统/项目目录探测、清空 Agent 覆盖 env）。DashScope / OpenAPI 凭证继续走环境变量；Console live 用例用 `runConsoleCommandE2e` / `runConsoleCli` 带上 `access_token`。进程内单测用 `withIsolatedHome` / `enterIsolatedHome`，**禁止**各文件自写 `inFakeHome`。完整约定见 [test-isolation.md](test-isolation.md)。
+- **默认测试隔离**：`runNodeMain` / `runCommandE2e` / `runCommandInProcess` / `runCli` / `runKscli` 默认走 `e2e/isolation`（HOME 与 `XDG_CONFIG_HOME` 隔离、强制 `language: en-US`、关闭 HOME 外的系统/项目目录探测、清空 Agent 覆盖 env）。`runCommandInProcess` 经 `buildIsolatedCliEnv` 后把完整 env 快照交给 `runInProcess`（与子进程 `env` 同语义）。DashScope / OpenAPI 凭证继续走环境变量；Console live 用例用 `runConsoleCommandE2e` / `runConsoleCli` 带上 `access_token`。进程内单测用 `withIsolatedHome` / `enterIsolatedHome`，**禁止**各文件自写 `inFakeHome`。完整约定见 [test-isolation.md](test-isolation.md)。
 - **不加 dry-run**：`dryRun` 在 `resolveFileUrl` / `resolveCredential` / 上传**之后**的命令（如 `image edit`、`speech recognize` 带 `--url`）
 - **`--list-voices` 等旁路**：先于 `--text` 校验的 flag，缺参用例勿带该 flag
 - 新增 required option → 至少一条缺参用例；改 dry-run 输出 → 更新对应断言
 
@@ -16,8 +16,9 @@
         │
         ▼
   e2e/isolation（统一入口）
-        ├─ 进程内：withIsolatedHome / enterIsolatedHome
-        └─ 子进程：runNodeMain → buildIsolatedCliEnv
+        ├─ 进程内单测：withIsolatedHome / enterIsolatedHome
+        ├─ 离线 in-process E2E：runCommandInProcess → buildIsolatedCliEnv → runInProcess(完整 env 快照)
+        └─ 子进程 E2E：runNodeMain → buildIsolatedCliEnv
               │
               ├─ 调用方 HOME，否则临时 HOME；XDG 始终改写到该 HOME
               ├─ 未传 BAILIAN_CONFIG_DIR：空 HOME 写 $HOME/.bailian；已有 config 则用自有临时目录（不覆盖）
@@ -26,7 +27,7 @@
               ├─ Console access_token 仅 seedCredentials: true 时拷贝
               ├─ 清空 AGENT_ENV_KEYS（含 OPENCLAW / ZCODE / LOCALAPPDATA）
               ├─ BL_SKIP_HOST_AGENTS=1
-              └─ runNodeMain 结束时删除自己创建的临时目录
+              └─ 结束后 dispose / restore 删除自己创建的临时目录
 
   Session 父目录（仅扫尾归堆，不承载隔离语义）：
   globalSetup createIsolationSessionRoot → provide → setupFiles 写 BL_ISO_ROOT
@@ -42,6 +43,7 @@
 - [ ] **commands / runtime 进程内单测**（agent writer 等）：`import { withIsolatedHome, enterIsolatedHome } from "e2e/isolation"`
 - [ ] 禁止本地再写 `inFakeHome` / 直接 `process.env.HOME =`
 - [ ] **CLI 子进程 E2E**：走 `runCommandE2e` / `runCli` / `runKscli` → 底层 `runNodeMain` **默认已隔离**；用例只需在需要时传自己的 `BAILIAN_CONFIG_DIR` / `HOME`
+- [ ] **离线 in-process E2E**：走 `runCommandInProcess` → 同样 `buildIsolatedCliEnv`；`runInProcess` 的 `env` 是完整快照（非增量 merge）
 - [ ] 只传 `HOME` 且该 HOME 下**已有** `config.json` 时，基建**不会覆盖**，改用自有临时 `BAILIAN_CONFIG_DIR`；空 HOME 才写 `$HOME/.bailian`
 - [ ] 隔离关键键的 `undefined` / 空串会被忽略，不能拆掉隔离；其它键传 `undefined` 会删除继承凭证（如 `DASHSCOPE_API_KEY: undefined`）
 - [ ] **必须继承真实用户配置**的极少数用例：`runNodeMain(..., { isolate: false })`，并在注释里写明原因
 
@@ -10,8 +10,9 @@ import {
 } from "e2e/output";
 import { captureRegistryHelp } from "e2e/registry-smoke";
 import { runNodeMain, type RunCliResult } from "e2e/runner";
-import { CommandRegistry, createCli, resolve } from "bailian-cli-runtime";
+import { buildIsolatedCliEnv } from "e2e/isolation";
 import { runInProcess } from "e2e/in-process";
+import { CommandRegistry, createCli, resolve } from "bailian-cli-runtime";
 import { loadRouteCommands } from "./harness/routes.ts";
 import { E2E_HARNESS_IDENTITY } from "./harness/identity.ts";
 import { withHarnessUpdateFixture } from "./harness/update-fixture.ts";
@@ -50,10 +51,8 @@ const e2eDir = dirname(fileURLToPath(import.meta.url));
 const harnessMainTs = join(e2eDir, "harness", "main.ts");
 const registryCache = new WeakMap<E2eRouteExports, Promise<CommandRegistry>>();
 
-/** `packages/commands` 根目录 */
 export const commandsPackageRoot = join(e2eDir, "..", "..");
 
-/** E2E fixtures 目录 */
 export const e2eFixturesDir = join(e2eDir, "fixtures");
 
 function serializeRoutes(routes: E2eRouteExports): string {
@@ -73,7 +72,7 @@ function getCommandRegistry(routes: E2eRouteExports): Promise<CommandRegistry> {
   return registryPromise;
 }
 
-/** 使用 topic 最小路由在当前 Vitest worker 中渲染命令 help，不启动 CLI 子进程。 */
+/** In-worker help via topic routes (no CLI subprocess). */
 export async function captureCommandHelp(
   routes: E2eRouteExports,
   commandPath: string[],
@@ -86,7 +85,7 @@ export async function captureCommandHelp(
   return captureRegistryHelp(registry, commandPath);
 }
 
-/** 与 runCommandE2e 的结果结构兼容，但 help 在当前 Vitest worker 中渲染。 */
+/** Same result shape as runCommandE2e; help is rendered in-worker. */
 export async function runCommandHelp(
   routes: E2eRouteExports,
   args: string[],
@@ -99,14 +98,11 @@ export async function runCommandHelp(
 }
 
 export interface CommandE2eRunOptions {
-  /** 把本机 config 里的 console access_token 写入隔离配置。 */
+  /** Copy host console access_token into the isolated config. */
   seedCredentials?: boolean;
 }
 
-/**
- * 通过 harness 子进程执行命令 E2E。
- * `routes` 为本用例所需的最小 path → export 映射，不维护全量产品 map。
- */
+/** Harness subprocess E2E; `routes` is the minimal path → export map for this topic. */
 export async function runCommandE2e(
   routes: E2eRouteExports,
   args: string[],
@@ -123,7 +119,7 @@ export async function runCommandE2e(
   });
 }
 
-/** Console live 用例：隔离环境里带上本机 access_token。 */
+/** Console live: isolate and seed host access_token. */
 export async function runConsoleCommandE2e(
   routes: E2eRouteExports,
   args: string[],
@@ -132,7 +128,10 @@ export async function runConsoleCommandE2e(
   return runCommandE2e(routes, args, envOverrides, { seedCredentials: true });
 }
 
-/** Opt-in for offline cases; process preloads and proxy configuration retain real subprocesses. */
+/**
+ * Offline opt-in: real createCli in-process with e2e/isolation.
+ * Falls back to a subprocess when NODE_OPTIONS or HTTP(S)_PROXY is set.
+ */
 export async function runCommandInProcess(
   routes: E2eRouteExports,
   args: string[],
@@ -145,12 +144,18 @@ export async function runCommandInProcess(
     environment.HTTPS_PROXY ||
     environment.http_proxy ||
     environment.https_proxy
-  )
+  ) {
     return runCommandE2e(routes, args, envOverrides);
-  const commands = await loadRouteCommands(routes);
-  return runInProcess(
-    () => withHarnessUpdateFixture(() => createCli(commands, E2E_HARNESS_IDENTITY).run(args)),
-    args,
-    { cwd: commandsPackageRoot, env: envOverrides, entrypoint: harnessMainTs },
-  );
+  }
+  const isolated = buildIsolatedCliEnv({ overrides: envOverrides });
+  try {
+    const commands = await loadRouteCommands(routes);
+    return await runInProcess(
+      () => withHarnessUpdateFixture(() => createCli(commands, E2E_HARNESS_IDENTITY).run(args)),
+      args,
+      { cwd: commandsPackageRoot, env: isolated.env, entrypoint: harnessMainTs },
+    );
+  } finally {
+    isolated.dispose();
+  }
 }
@@ -1,6 +1,6 @@
 /**
- * Vitest setupFiles：把 globalSetup provide 的本轮隔离父目录写入 BL_ISO_ROOT，
- * 供 mkIsolationTemp 挂载临时子目录。只依赖 iso-root-keys，不拉 isolation/core。
+ * Vitest setupFiles: copy provided isolation parent into BL_ISO_ROOT.
+ * Depends only on iso-root-keys (not isolation/core).
  */
 import { inject } from "vite-plus/test";
 import { ISO_ROOT_ENV, ISO_ROOT_KEY } from "./iso-root-keys.ts";
@@ -12,5 +12,5 @@ try {
     process.env[ISO_ROOT_ENV] = sessionRoot;
   }
 } catch {
-  // 无 globalSetup/provide 时不写 BL_ISO_ROOT，getIsolationSessionRoot 回退到 os.tmpdir()。
+  // No provide: leave BL_ISO_ROOT unset; getIsolationSessionRoot falls back to os.tmpdir().
 }
@@ -32,30 +32,21 @@ const CRITICAL_ENVS = new Set([
   SKIP_HOST_AGENTS_ENV,
 ]);
 
-/**
- * 本轮隔离父目录（仅供 Vitest globalSetup 调用一次）。
- * 返回值必须由 teardown 闭包捕获后删除；worker 通过 provide → BL_ISO_ROOT 复用，不宣称所有权。
- */
+/** Create this run's isolation parent (globalSetup once). Teardown must delete the returned path. */
 export function createIsolationSessionRoot(): string {
   const sessionRoot = mkdtempSync(join(tmpdir(), "bl-e2e-session-"));
   process.env[ISO_ROOT_ENV] = sessionRoot;
   return sessionRoot;
 }
 
-/**
- * 临时目录父路径：优先 globalSetup 注入的 `BL_ISO_ROOT`，否则 `os.tmpdir()`。
- * 不惰性创建 session、不挂信号、不维护进程所有权。
- */
+/** Temp parent: `BL_ISO_ROOT` from globalSetup, else `os.tmpdir()`. */
 export function getIsolationSessionRoot(): string {
   const fromEnv = process.env[ISO_ROOT_ENV]?.trim();
   if (fromEnv && existsSync(fromEnv)) return fromEnv;
   return tmpdir();
 }
 
-/**
- * 删除指定 session 根。幂等（force）；只删传入路径。
- * globalSetup teardown 必须传入自己闭包里的 root。
- */
+/** Delete the given session root (idempotent). Teardown must pass its closed-over path. */
 export function cleanupIsolationSessionRootAt(sessionRoot: string): void {
   if (!sessionRoot) return;
   if (process.env[ISO_ROOT_ENV] === sessionRoot) {
@@ -64,7 +55,6 @@ export function cleanupIsolationSessionRootAt(sessionRoot: string): void {
   rmSync(sessionRoot, { recursive: true, force: true });
 }
 
-/** 在 session 根（或 os.tmpdir）下创建临时子目录。 */
 function mkIsolationTemp(prefix: string): string {
   return mkdtempSync(join(getIsolationSessionRoot(), prefix));
 }
 
@@ -6,6 +6,7 @@ let captureQueue: Promise<unknown> = Promise.resolve();
 
 interface CaptureOptions {
   cwd?: string;
+  /** Full child env (execFile-style replace). Omit to inherit process.env. */
   env?: NodeJS.ProcessEnv;
   entrypoint?: string;
 }
@@ -21,6 +22,13 @@ function restoreListeners(
   for (const listener of listeners) emitter.on(event, listener);
 }
 
+function replaceProcessEnv(next: NodeJS.ProcessEnv): void {
+  for (const name of Object.keys(process.env)) delete process.env[name];
+  for (const [name, value] of Object.entries(next)) {
+    if (value !== undefined) process.env[name] = value;
+  }
+}
+
 async function capture(
   run: () => void | Promise<void>,
   args: string[],
@@ -72,11 +80,8 @@ async function capture(
 
   try {
     if (options.cwd) process.chdir(options.cwd);
+    if (options.env) replaceProcessEnv(options.env);
     Object.assign(process.env, { NODE_NO_WARNINGS: "1", DO_NOT_TRACK: "1" });
-    for (const [name, value] of Object.entries(options.env ?? {})) {
-      if (value === undefined) delete process.env[name];
-      else process.env[name] = value;
-    }
     process.argv = [process.execPath, options.entrypoint ?? "commands-e2e", ...args];
     process.exitCode = 0;
     for (const { stream, property } of terminalProperties)
@@ -103,9 +108,7 @@ async function capture(
     process.exit = originalExit;
     process.exitCode = originalExitCode;
     process.argv = originalArgv;
-    for (const name of Object.keys(process.env))
-      if (!(name in originalEnvironment)) delete process.env[name];
-    Object.assign(process.env, originalEnvironment);
+    replaceProcessEnv(originalEnvironment);
     for (const { stream, property, descriptor } of terminalProperties) {
       if (descriptor) Object.defineProperty(stream, property, descriptor);
       else Reflect.deleteProperty(stream, property);
 
@@ -16,26 +16,19 @@ export interface RunCliResult {
 export interface RunNodeMainOptions {
   cwd: string;
   env?: NodeJS.ProcessEnv;
-  /**
-   * 默认 true：子进程使用隔离 HOME/config（强制 en-US、关闭系统 Agent 探测）。
-   * 仅当用例必须完整继承宿主 `~/.bailian` 时设为 false。
-   */
+  /** Default true. Set false only when the case must inherit the host `~/.bailian`. */
   isolate?: boolean;
-  /**
-   * 为 true 时把本机 config 里的 console access_token 写入隔离配置。
-   * 默认 false。DashScope / OpenAPI 继续使用环境变量。
-   */
+  /** Opt-in: copy host console access_token into isolated config. */
   seedCredentials?: boolean;
 }
 
-/** monorepo 根目录下的 tsx 可执行文件 */
 export function resolveTsxBin(): string {
   const root = monorepoRoot();
   const name = process.platform === "win32" ? "tsx.cmd" : "tsx";
   return join(root, "node_modules", ".bin", name);
 }
 
-/** 子进程通过 Node 的 tsx loader 执行指定 main.ts 入口，不启动 tsx CLI 的 IPC server。 */
+/** Run main.ts via Node's tsx loader (no tsx CLI IPC server). */
 export async function runNodeMain(
   mainTs: string,
   args: string[],
 
@@ -44,7 +44,6 @@ test("withIsolatedHome 关闭系统 detectDirs，空 HOME 下不探测主机路
     expect(process.env.CLAUDE_CONFIG_DIR).toBeUndefined();
     expect(process.env.LOCALAPPDATA).toBeUndefined();
 
-    // 未创建任何 agent 目录时，列表应为空（不受 /etc/codex 等主机路径影响）
     expect(detectInstalledAgents()).toEqual([]);
 
     mkdirSync(join(home, ".claude"), { recursive: true });
@@ -241,7 +240,6 @@ test("undefined / 空串 overrides 不会取消 HOME 与 config 隔离", () => {
     expect(isolated.env.BAILIAN_CONFIG_DIR).toBeTruthy();
     expect(isolated.env.XDG_CONFIG_HOME).toBe(join(isolated.env.HOME!, ".config"));
     expect(isolated.env[SKIP_HOST_AGENTS_ENV]).toBe("1");
-    // 非隔离关键键仍允许空串（测试故意清凭证）
     expect(isolated.env.DASHSCOPE_API_KEY).toBe("");
     expect(existsSync(join(isolated.env.BAILIAN_CONFIG_DIR!, "config.json"))).toBe(true);
   } finally {