msdevflow 0.7.6 → 0.7.8

package/README.md

@@ -58,6 +58,25 @@ Claude Code + Codex         -> 两套受管副本
 
 每个物理目标都包含完整套件，薄路由器不复制核心业务规则。已有 entry 只有在 manifest 精确匹配自身名称时才允许更新；由旧版包管理的 `msdevflow` 目录会在新套件全部验证后安全迁移，来源不明的目录、文件或符号链接会阻断安装。
 
+### WSL 与 Windows Agent
+
+setup 以 **Agent 可执行文件实际所在环境** 决定安装侧，而不是只看命令从哪个 shell 发起：
+
+- Agent 只安装在 Windows：可以从 WSL 调用 Windows `npx.cmd`，setup 会标记 `Runtime mode: windows-bridge-from-wsl`，并把 Skill、Python venv 和 GitCode CLI 安装在 Windows 用户环境。
+- Agent 只安装在 WSL：必须使用 WSL 内的 Linux Node.js/npm；若误用了 Windows Node，setup 会在写入任何 Python、npm 或 Skill 文件前停止。
+- 同名 Agent 同时存在于 Windows 与 WSL：setup 不猜目标；请从目标环境的终端重新运行。
+
+准备 WSL 原生 Agent 时先确认以下命令全部解析为 Linux 路径，而不是 `/mnt/<drive>/...` 或 `.cmd`：
+
+```bash
+type -a node npm npx opencode
+npx msdevflow@latest setup
+```
+
+示例使用 OpenCode；使用 Claude Code 或 Codex 时把 `opencode` 替换为实际 Agent 命令。
+
+Windows bridge 模式应从 WSL 中解析到 Windows Agent；也可直接在 Windows Terminal/PowerShell 中运行 setup。此前失败后可直接重跑，setup 会安全复用或修复带受管 marker 的 runtime，不需要手动删除。
+
 自定义目录：
 
 ```bash

package/lib/bootstrap.js

@@ -764,11 +764,13 @@ function outputLines(output) {
   return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
 }
 
-export function resolveExecutable(name, run, platform) {
-  const invocation = platform === "win32"
+function executableLookup(name, platform) {
+  return platform === "win32"
     ? { command: "where.exe", args: [name] }
     : { command: "sh", args: ["-c", "command -v -- \"$1\"", "sh", name] };
-  const result = runOptional(run, invocation);
+}
+
+function executableFromLookup(result, platform) {
   if (result.status !== 0) {
     return "";
   }
@@ -779,10 +781,237 @@ export function resolveExecutable(name, run, platform) {
   return candidates[0] || "";
 }
 
+export function resolveExecutable(name, run, platform) {
+  return executableFromLookup(
+    runOptional(run, executableLookup(name, platform)),
+    platform,
+  );
+}
+
+async function resolveExecutableAsync(name, run, platform) {
+  return executableFromLookup(
+    await runOptionalAsync(run, executableLookup(name, platform)),
+    platform,
+  );
+}
+
 export function detectClients(run, platform) {
   return SUPPORTED_CLIENTS.filter((client) => Boolean(resolveExecutable(client, run, platform)));
 }
 
+function wslDistroFromUnc(value) {
+  return typeof value === "string"
+    ? value.match(/^\\\\wsl(?:\.localhost|\$)\\([^\\]+)/i)?.[1] || ""
+    : "";
+}
+
+function windowsNodeFromWsl(environment, platform) {
+  // Windows Node keeps process.platform=win32 when a WSL shell launches npx.cmd.
+  if (platform !== "win32") {
+    return null;
+  }
+  const distro = environment.WSL_DISTRO_NAME
+    || wslDistroFromUnc(environment.INIT_CWD)
+    || wslDistroFromUnc(environment.PWD);
+  if (!distro && !environment.WSL_INTEROP) {
+    return null;
+  }
+  return { distro: distro || "" };
+}
+
+async function detectClientExecutables(run, platform) {
+  const entries = await Promise.all(SUPPORTED_CLIENTS.map(async (client) => [
+    client,
+    await resolveExecutableAsync(client, run, platform),
+  ]));
+  return Object.fromEntries(entries.filter(([, executable]) => executable));
+}
+
+function wslClientLookup(distro) {
+  const args = [];
+  if (distro) {
+    args.push("--distribution", distro);
+  }
+  const script = [
+    "for name do",
+    "  old_ifs=$IFS",
+    "  IFS=: ",
+    "  for dir in $PATH; do",
+    "    IFS=$old_ifs",
+    "    [ -n \"$dir\" ] || dir=.",
+    "    for candidate in \"$dir/$name\" \"$dir/$name.cmd\" \"$dir/$name.exe\" \"$dir/$name.bat\"; do",
+    "      [ -f \"$candidate\" ] || continue",
+    "      case \"$candidate\" in",
+    "        /mnt/[a-zA-Z]/*)",
+    "          [ -f \"${candidate}.cmd\" ] && candidate=\"${candidate}.cmd\"",
+    "          windows=$(wslpath -w -- \"$candidate\" 2>/dev/null) || continue",
+    "          printf '%s\\twindows\\t%s\\n' \"$name\" \"$windows\"",
+    "          ;;",
+    "        *)",
+    "          [ -x \"$candidate\" ] || continue",
+    "          native=$(readlink -f -- \"$candidate\" 2>/dev/null || printf '%s' \"$candidate\")",
+    "          case \"$native\" in",
+    "            /mnt/[a-zA-Z]/*)",
+    "              [ -f \"${native}.cmd\" ] && native=\"${native}.cmd\"",
+    "              windows=$(wslpath -w -- \"$native\" 2>/dev/null) || continue",
+    "              printf '%s\\twindows\\t%s\\n' \"$name\" \"$windows\"",
+    "              ;;",
+    "            *) printf '%s\\twsl\\t%s\\n' \"$name\" \"$native\" ;;",
+    "          esac",
+    "          ;;",
+    "      esac",
+    "      break",
+    "    done",
+    "    IFS=: ",
+    "  done",
+    "  IFS=$old_ifs",
+    "done",
+  ].join("\n");
+  args.push("--exec", "sh", "-lc", script, "sh", ...SUPPORTED_CLIENTS);
+  return { command: "wsl.exe", args };
+}
+
+async function detectWslClientExecutables(run, distro) {
+  const result = await runOptionalAsync(run, wslClientLookup(distro));
+  if (result.status !== 0) {
+    return { wsl: {}, windows: {} };
+  }
+  const clients = { wsl: {}, windows: {} };
+  for (const line of result.stdout.split(/\r?\n/)) {
+    const [name, side, executable] = line.split("\t", 3);
+    if (
+      SUPPORTED_CLIENTS.includes(name)
+      && (side === "wsl" || side === "windows")
+      && executable
+      && !clients[side][name]
+    ) {
+      clients[side][name] = executable;
+    }
+  }
+  return clients;
+}
+
+async function inspectMixedWslClients(run, context) {
+  const [windowsPath, wslLookup] = await Promise.all([
+    detectClientExecutables(run, "win32"),
+    detectWslClientExecutables(run, context.distro),
+  ]);
+  return {
+    ...context,
+    windows: { ...wslLookup.windows, ...windowsPath },
+    wsl: wslLookup.wsl,
+  };
+}
+
+function clientLocations(inspection, clients) {
+  return clients.map((client) => ({
+    client,
+    windows: inspection.windows[client] || "",
+    wsl: inspection.wsl[client] || "",
+  }));
+}
+
+function mixedClientError(inspection, clients, reason) {
+  const locations = clientLocations(inspection, clients);
+  const details = locations.map(({ client, windows, wsl }) => [
+    `${client}:`,
+    windows ? `Windows=${windows}` : "Windows=not-found",
+    wsl ? `WSL=${wsl}` : "WSL=not-found",
+  ].join(" ")).join("; ");
+  const guidance = `Use Node.js >=18 and npm installed inside WSL, verify "type -a node npm npx ${clients.join(" ")}" resolves to Linux paths, then rerun "npx msdevflow@latest setup" from WSL. To configure a Windows agent instead, run setup from a Windows terminal. No changes were applied.`;
+  return new BootstrapError(`${reason} ${details}. ${guidance}`, 2);
+}
+
+function resolveMixedWslTargets(inspection, clients) {
+  const locations = clientLocations(inspection, clients);
+  const ambiguous = locations.filter(({ windows, wsl }) => windows && wsl);
+  if (ambiguous.length) {
+    throw mixedClientError(
+      inspection,
+      ambiguous.map(({ client }) => client),
+      "The selected agent exists in both Windows and WSL, so setup cannot safely choose which environment owns it.",
+    );
+  }
+  const wslOnly = locations.filter(({ windows, wsl }) => !windows && wsl);
+  if (wslOnly.length) {
+    throw mixedClientError(
+      inspection,
+      wslOnly.map(({ client }) => client),
+      "The selected agent exists only inside WSL, but msdevflow is running with Windows Node.js.",
+    );
+  }
+  const missing = locations.filter(({ windows, wsl }) => !windows && !wsl);
+  if (missing.length) {
+    throw mixedClientError(
+      inspection,
+      missing.map(({ client }) => client),
+      "The selected agent was not found in either Windows or WSL.",
+    );
+  }
+  return {
+    mode: "windows-bridge-from-wsl",
+    agentExecutables: Object.fromEntries(
+      locations.map(({ client, windows }) => [client, windows]),
+    ),
+  };
+}
+
+async function resolveSetupContext(
+  options,
+  environment,
+  platform,
+  run,
+  runLong,
+  selectClients,
+  progress,
+) {
+  const context = windowsNodeFromWsl(environment, platform);
+  if (!context) {
+    return {
+      targetSelection: await resolveClientTargets(
+        options,
+        run,
+        platform,
+        selectClients,
+      ),
+      runtime: {
+        mode: platform === "win32" ? "windows-native" : "posix-native",
+        agentExecutables: {},
+      },
+    };
+  }
+
+  const inspection = await progress.run(
+    "Inspecting Windows and WSL agent installations",
+    () => inspectMixedWslClients(runLong, context),
+  );
+  let targetSelection;
+  if (options.targetsSpecified) {
+    targetSelection = {
+      clients: options.targets,
+      source: "explicit",
+      detected: [],
+    };
+  } else if (options.skillsDir) {
+    targetSelection = {
+      clients: ["claude"],
+      source: "legacy-skills-dir",
+      detected: [],
+    };
+  } else {
+    const detected = SUPPORTED_CLIENTS.filter(
+      (client) => inspection.windows[client] || inspection.wsl[client],
+    );
+    targetSelection = detected.length
+      ? { clients: detected, source: "detected", detected }
+      : { clients: await selectClients(), source: "selected", detected: [] };
+  }
+  return {
+    targetSelection,
+    runtime: resolveMixedWslTargets(inspection, targetSelection.clients),
+  };
+}
+
 async function selectClientTargets(input, output, promptOutput = output) {
   if (!input.isTTY || !output.isTTY) {
     throw new BootstrapError(
@@ -849,60 +1078,95 @@ function hasPythonShebang(file) {
   }
 }
 
-function pythonScriptDirectories(run, platform) {
-  const candidates = platform === "win32"
+function pythonCandidates(platform) {
+  return platform === "win32"
     ? [{ command: "py", prefix: ["-3"] }, { command: "python", prefix: [] }, { command: "python3", prefix: [] }]
     : [{ command: "python3", prefix: [] }, { command: "python", prefix: [] }];
+}
+
+function parsePythonScriptDirectory(result) {
+  if (result.status !== 0) {
+    return "";
+  }
+  try {
+    const directory = JSON.parse(result.stdout.trim());
+    return typeof directory === "string" ? directory : "";
+  } catch {
+    return "";
+  }
+}
+
+function pythonScriptDirectories(run, platform) {
+  const probe = "import json,sysconfig; print(json.dumps(sysconfig.get_path('scripts')))";
+  return pythonCandidates(platform)
+    .map((candidate) => parsePythonScriptDirectory(runOptional(run, {
+      command: candidate.command,
+      args: [...candidate.prefix, "-c", probe],
+    })))
+    .filter(Boolean);
+}
+
+async function pythonScriptDirectoriesAsync(run, platform) {
   const probe = "import json,sysconfig; print(json.dumps(sysconfig.get_path('scripts')))";
   const directories = [];
-  for (const candidate of candidates) {
-    const result = runOptional(run, {
+  for (const candidate of pythonCandidates(platform)) {
+    const directory = parsePythonScriptDirectory(await runOptionalAsync(run, {
       command: candidate.command,
       args: [...candidate.prefix, "-c", probe],
-    });
-    if (result.status !== 0) {
-      continue;
-    }
-    try {
-      const directory = JSON.parse(result.stdout.trim());
-      if (typeof directory === "string" && directory) {
-        directories.push(directory);
-      }
-    } catch {
-      continue;
+    }));
+    if (directory) {
+      directories.push(directory);
     }
   }
   return directories;
 }
 
-function isPythonGitcode(executable, run, platform) {
-  if (/[\\/]Python[^\\/]*[\\/]Scripts[\\/]gitcode(?:\.exe)?$/i.test(executable)
-      || /[\\/]pipx[\\/]/i.test(executable)
-      || hasPythonShebang(executable)) {
-    return true;
-  }
+function isKnownPythonGitcodePath(executable) {
+  return /[\\/]Python[^\\/]*[\\/]Scripts[\\/]gitcode(?:\.exe)?$/i.test(executable)
+    || /[\\/]pipx[\\/]/i.test(executable)
+    || hasPythonShebang(executable);
+}
+
+function executableMatchesPythonScripts(executable, directories, platform) {
   const directory = normalizedPath(executableDirectory(executable, platform), platform);
-  return pythonScriptDirectories(run, platform)
-    .some((candidate) => normalizedPath(candidate, platform) === directory);
+  return directories.some((candidate) => normalizedPath(candidate, platform) === directory);
 }
 
-export function diagnoseGitcode(run, platform) {
-  const executable = resolveExecutable("gitcode", run, platform);
-  if (!executable) {
-    return {
-      classification: "absent",
-      existingExecutable: null,
-      workflowCommand: "gitcode",
-    };
-  }
-  if (isPythonGitcode(executable, run, platform)) {
-    return {
-      classification: "python",
-      existingExecutable: executable,
-      workflowCommand: "gitcode-npm",
-    };
-  }
-  const doctor = runOptional(run, executableCommand(executable, ["doctor", "install", "--json"], platform));
+function isPythonGitcode(executable, run, platform) {
+  return isKnownPythonGitcodePath(executable)
+    || executableMatchesPythonScripts(
+      executable,
+      pythonScriptDirectories(run, platform),
+      platform,
+    );
+}
+
+async function isPythonGitcodeAsync(executable, run, platform) {
+  return isKnownPythonGitcodePath(executable)
+    || executableMatchesPythonScripts(
+      executable,
+      await pythonScriptDirectoriesAsync(run, platform),
+      platform,
+    );
+}
+
+function absentGitcodeDiagnosis() {
+  return {
+    classification: "absent",
+    existingExecutable: null,
+    workflowCommand: "gitcode",
+  };
+}
+
+function pythonGitcodeDiagnosis(executable) {
+  return {
+    classification: "python",
+    existingExecutable: executable,
+    workflowCommand: "gitcode-npm",
+  };
+}
+
+function npmGitcodeDiagnosis(executable, doctor) {
   if (doctor.status === 0) {
     try {
       const metadata = JSON.parse(doctor.stdout);
@@ -920,23 +1184,74 @@ export function diagnoseGitcode(run, platform) {
   throw new BootstrapError(`Existing gitcode has unknown ownership: ${executable}. Refusing to overwrite it.`, 3);
 }
 
-function detectPython(run, platform) {
-  const candidates = platform === "win32"
-    ? [{ command: "py", prefix: ["-3"] }, { command: "python", prefix: [] }, { command: "python3", prefix: [] }]
-    : [{ command: "python3", prefix: [] }, { command: "python", prefix: [] }];
+export function diagnoseGitcode(run, platform) {
+  const executable = resolveExecutable("gitcode", run, platform);
+  if (!executable) {
+    return absentGitcodeDiagnosis();
+  }
+  if (isPythonGitcode(executable, run, platform)) {
+    return pythonGitcodeDiagnosis(executable);
+  }
+  return npmGitcodeDiagnosis(
+    executable,
+    runOptional(run, executableCommand(executable, ["doctor", "install", "--json"], platform)),
+  );
+}
+
+async function diagnoseGitcodeAsync(run, platform) {
+  const executable = await resolveExecutableAsync("gitcode", run, platform);
+  if (!executable) {
+    return absentGitcodeDiagnosis();
+  }
+  if (await isPythonGitcodeAsync(executable, run, platform)) {
+    return pythonGitcodeDiagnosis(executable);
+  }
+  return npmGitcodeDiagnosis(
+    executable,
+    await runOptionalAsync(
+      run,
+      executableCommand(executable, ["doctor", "install", "--json"], platform),
+    ),
+  );
+}
+
+function parsePythonProbe(result) {
+  if (result.status !== 0) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(result.stdout.trim());
+    if (data.version[0] > 3 || (data.version[0] === 3 && data.version[1] >= 10)) {
+      return data;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function pythonProbe(candidate) {
   const probe = "import json,sys; print(json.dumps({'executable':sys.executable,'version':list(sys.version_info[:3])}))";
-  for (const candidate of candidates) {
-    const result = runOptional(run, { command: candidate.command, args: [...candidate.prefix, "-c", probe] });
-    if (result.status !== 0) {
-      continue;
+  return { command: candidate.command, args: [...candidate.prefix, "-c", probe] };
+}
+
+function detectPython(run, platform) {
+  for (const candidate of pythonCandidates(platform)) {
+    const data = parsePythonProbe(runOptional(run, pythonProbe(candidate)));
+    if (data) {
+      return data;
     }
-    try {
-      const data = JSON.parse(result.stdout.trim());
-      if (data.version[0] > 3 || (data.version[0] === 3 && data.version[1] >= 10)) {
-        return data;
-      }
-    } catch {
-      continue;
+  }
+  throw new BootstrapError("Python >=3.10 is required for workflow scripts.", 2);
+}
+
+async function detectPythonAsync(run, platform) {
+  for (const candidate of pythonCandidates(platform)) {
+    const python = parsePythonProbe(
+      await runOptionalAsync(run, pythonProbe(candidate)),
+    );
+    if (python) {
+      return python;
     }
   }
   throw new BootstrapError("Python >=3.10 is required for workflow scripts.", 2);
@@ -1004,7 +1319,7 @@ export function pythonRuntimeDetails(
   return pythonRuntimeAt(directory, python, platform);
 }
 
-function validatePythonRuntime(runtime, run) {
+async function validatePythonRuntime(runtime, run) {
   let marker;
   try {
     const metadata = lstatSync(runtime.directory);
@@ -1043,10 +1358,10 @@ function validatePythonRuntime(runtime, run) {
       closeSync(descriptor);
     }
   }
-  if (runOptional(run, {
+  if ((await runOptionalAsync(run, {
     command: runtime.executable,
     args: ["-m", "pip", "--version"],
-  }).status !== 0) {
+  })).status !== 0) {
     return "repair";
   }
   return "current";
@@ -1069,8 +1384,8 @@ function writePythonRuntimeMarker(runtime) {
   writeFileSync(runtime.marker, PYTHON_RUNTIME_MARKER_CONTENT, { encoding: "utf8", flag: "wx" });
 }
 
-async function ensurePythonRuntime(runtime, status, runLong, run) {
-  if (validatePythonRuntime(runtime, run) !== status) {
+async function ensurePythonRuntime(runtime, status, runLong) {
+  if ((await validatePythonRuntime(runtime, runLong)) !== status) {
     throw new BootstrapError(
       `Managed Python runtime changed after confirmation: ${runtime.directory}`,
       3,
@@ -1155,11 +1470,15 @@ export function gitcodeInstallDetails(
       npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, "--prefix", installPrefix, `--registry=${REGISTRY}`],
     };
   }
+  const installPrefix = npmPrefix || "<npm-global-prefix>";
   return {
     mode: classification === "npm-official" ? "upgrade-npm" : "standard",
     workflowCommand: "gitcode",
-    target: npmPrefix || "<npm-global-prefix>",
-    cliTarget: null,
+    target: installPrefix,
+    cliTarget: pathApi.join(
+      installPrefix,
+      ...(platform === "win32" ? ["gitcode.cmd"] : ["bin", "gitcode"]),
+    ),
     wrapperDir: null,
     wrapper: null,
     npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, `--registry=${REGISTRY}`],
@@ -1255,12 +1574,20 @@ async function installGitcode(plan, runLong, run, platform) {
     };
   }
   const executable = resolveExecutable("gitcode", run, platform);
-  if (!executable) {
-    throw new BootstrapError("GitCode npm CLI was installed but the gitcode executable is not available on PATH.");
+  if (executable) {
+    return {
+      command: plan.gitcodeInstall.workflowCommand,
+      executable,
+    };
   }
+  // The parent process keeps its original PATH after npm creates a global shim.
+  verifyFile(
+    plan.gitcodeInstall.cliTarget,
+    `GitCode npm CLI was installed but its executable was not found on PATH or at ${plan.gitcodeInstall.cliTarget}.`,
+  );
   return {
     command: plan.gitcodeInstall.workflowCommand,
-    executable,
+    executable: plan.gitcodeInstall.cliTarget,
   };
 }
 
@@ -1286,6 +1613,10 @@ function safeAuthStatus(output) {
 function printPlan(plan, write) {
   write("Setup plan (no changes made yet):");
   write(`  Client targets: ${plan.clientTargets.clients.join(", ")} (${plan.clientTargets.source})`);
+  write(`  Runtime mode: ${plan.clientTargets.runtimeMode}`);
+  for (const [client, executable] of Object.entries(plan.clientTargets.agentExecutables)) {
+    write(`  Agent executable (${client}): ${executable}`);
+  }
   write(`  Bundled skill suite: ${plan.skillInstalls[0].details.source}`);
   for (const { layout, details } of plan.skillInstalls) {
     write(`  Skill root: ${details.target}`);
@@ -1422,6 +1753,7 @@ async function authenticateGitcode(
 function textResult(result, write) {
   write("Setup completed:");
   write(`  Client targets: ${result.clients.join(", ")}`);
+  write(`  Runtime mode: ${result.runtimeMode}`);
   for (const skill of result.skills) {
     write(`  Skill suite: ${skill.status} at ${skill.target} (${skill.clients.join(", ")})`);
     write(`    Entries: ${skill.entries.map((entry) => entry.name).join(", ")}`);
@@ -1456,16 +1788,20 @@ export async function runSetup(options, dependencies = {}) {
     writeProgress,
     dependencies.timers,
   );
-  const targetSelection = await resolveClientTargets(
+  const setupContext = await resolveSetupContext(
     options,
-    run,
+    environment,
     platform,
+    run,
+    runLong,
     dependencies.selectClients || (() => selectClientTargets(
       process.stdin,
       process.stdout,
       options.json ? process.stderr : process.stdout,
     )),
+    progress,
   );
+  const targetSelection = setupContext.targetSelection;
   const layouts = resolveLayouts(
     options,
     targetSelection.clients,
@@ -1482,6 +1818,8 @@ export async function runSetup(options, dependencies = {}) {
   }));
   const clientTargets = {
     ...targetSelection,
+    runtimeMode: setupContext.runtime.mode,
+    agentExecutables: setupContext.runtime.agentExecutables,
     warnings: clientTargetWarnings(targetSelection.clients, layouts),
   };
 
@@ -1499,7 +1837,42 @@ export async function runSetup(options, dependencies = {}) {
       platform,
     )),
   );
-  const diagnosis = diagnoseGitcode(run, platform);
+  const { diagnosis, python, pythonRuntime } = await progress.run(
+    "Inspecting local GitCode and Python environment",
+    async () => {
+      const [diagnosisResult, pythonResult] = await Promise.all([
+        diagnoseGitcodeAsync(runLong, platform),
+        detectPythonAsync(runLong, platform),
+      ]);
+      const configuredPythonRuntime = pythonRuntimeDetails(
+        pythonResult,
+        environment,
+        platform,
+      );
+      const runtime = dependencies.pythonRuntimeDir
+        ? pythonRuntimeAt(dependencies.pythonRuntimeDir, pythonResult, platform)
+        : configuredPythonRuntime;
+      const [venvCapability, runtimeStatus] = await Promise.all([
+        runOptionalAsync(runLong, {
+          command: pythonResult.executable,
+          args: ["-m", "venv", "--help"],
+        }),
+        validatePythonRuntime(runtime, runLong),
+      ]);
+      if (venvCapability.status !== 0) {
+        throw new BootstrapError(
+          `Python venv is unavailable for ${pythonResult.executable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup.`,
+          2,
+        );
+      }
+      runtime.status = runtimeStatus;
+      return {
+        diagnosis: diagnosisResult,
+        python: pythonResult,
+        pythonRuntime: runtime,
+      };
+    },
+  );
   diagnosis.officialLatest = latestResult.status === 0 ? latestResult.stdout.trim() || null : null;
   const gitcodeInstall = gitcodeInstallDetails(diagnosis.classification, environment, platform, npmPrefix);
   if (gitcodeInstall.wrapper) {
@@ -1511,22 +1884,6 @@ export async function runSetup(options, dependencies = {}) {
     platform,
   );
 
-  const python = detectPython(run, platform);
-  const venvCapability = runOptional(run, {
-    command: python.executable,
-    args: ["-m", "venv", "--help"],
-  });
-  if (venvCapability.status !== 0) {
-    throw new BootstrapError(
-      `Python venv is unavailable for ${python.executable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup.`,
-      2,
-    );
-  }
-  const configuredPythonRuntime = pythonRuntimeDetails(python, environment, platform);
-  const pythonRuntime = dependencies.pythonRuntimeDir
-    ? pythonRuntimeAt(dependencies.pythonRuntimeDir, python, platform)
-    : configuredPythonRuntime;
-  pythonRuntime.status = validatePythonRuntime(pythonRuntime, run);
   const venvInvocation = {
     command: python.executable,
     args: ["-m", "venv", pythonRuntime.directory],
@@ -1554,14 +1911,29 @@ export async function runSetup(options, dependencies = {}) {
   if (!options.yes && !(await (dependencies.confirm || confirmPlan)(process.stdin, process.stdout))) {
     throw new BootstrapError("Setup cancelled; no changes were applied.", 2);
   }
-  const currentDiagnosis = diagnoseGitcode(run, platform);
-  if (currentDiagnosis.classification !== diagnosis.classification
-      || currentDiagnosis.existingExecutable !== diagnosis.existingExecutable) {
-    throw new BootstrapError("GitCode command ownership changed after confirmation; refusing to install.", 3);
-  }
-  if (gitcodeInstall.wrapper) {
-    validateWrapper(gitcodeInstall, platform);
-  }
+  await progress.run("Revalidating environment ownership", async () => {
+    const runtimeContext = windowsNodeFromWsl(environment, platform);
+    if (clientTargets.runtimeMode === "windows-bridge-from-wsl") {
+      const currentRuntime = resolveMixedWslTargets(
+        await inspectMixedWslClients(runLong, runtimeContext),
+        clientTargets.clients,
+      );
+      if (JSON.stringify(currentRuntime) !== JSON.stringify(setupContext.runtime)) {
+        throw new BootstrapError(
+          "Agent installation locations changed after confirmation; refusing to install.",
+          3,
+        );
+      }
+    }
+    const currentDiagnosis = await diagnoseGitcodeAsync(runLong, platform);
+    if (currentDiagnosis.classification !== diagnosis.classification
+        || currentDiagnosis.existingExecutable !== diagnosis.existingExecutable) {
+      throw new BootstrapError("GitCode command ownership changed after confirmation; refusing to install.", 3);
+    }
+    if (gitcodeInstall.wrapper) {
+      validateWrapper(gitcodeInstall, platform);
+    }
+  });
 
   await progress.run(
     pythonRuntime.status === "absent"
@@ -1569,7 +1941,7 @@ export async function runSetup(options, dependencies = {}) {
       : pythonRuntime.status === "repair"
         ? "Repairing the managed Python runtime"
         : "Validating the managed Python runtime",
-    () => ensurePythonRuntime(pythonRuntime, pythonRuntime.status, runLong, run),
+    () => ensurePythonRuntime(pythonRuntime, pythonRuntime.status, runLong),
   );
   await progress.run("Installing reviewed Python dependencies", () => runLong(pipInvocation));
   await progress.run(
@@ -1613,6 +1985,8 @@ export async function runSetup(options, dependencies = {}) {
     git: gitVersion,
     clients: clientTargets.clients,
     targetSource: clientTargets.source,
+    runtimeMode: clientTargets.runtimeMode,
+    agentExecutables: clientTargets.agentExecutables,
     warnings: clientTargets.warnings,
     skills,
     gitcode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msd/README.md

@@ -273,6 +273,8 @@ Claude Code + Codex    -> 两套受管副本
 
 每个物理目标都包含一个 `msd` 核心和十个 `msd-<action>` 路由器；业务规则仍只有一份。
 
+WSL 中的安装侧按 Agent 可执行文件实际所在环境决定：Agent 只在 Windows 时允许通过 Windows Node bridge 安装到 Windows 用户环境；Agent 只在 WSL 时必须使用 WSL 内 Linux Node/npm；同名 Agent 同时存在于两侧时停止而不猜测。WSL 原生模式先用 `type -a node npm npx opencode`（以实际选中的 Agent 命令替换 `opencode`） 确认所选命令解析为 Linux 路径，而不是 `/mnt/<drive>/...` 或 `.cmd`。此前失败后可直接按正确模式重跑，受管 runtime 会被复用或修复，无需手动删除。
+
 显式选择客户端、只读预检或自定义目录：
 
 ```bash