@ljwei-stak/dsh-model-router 0.17.1 → 0.18.1

package/.dsh-plugin/index.mjs

@@ -1434,11 +1434,25 @@ export function routerRemoteServices(ctx, config, { terminals = null } = {}) {
 /** Register model-facing tools and the human /router command. */
 export function apply(ctx, config = {}) {
   // Install addresses (directory, npm source, per-tool method and script source)
-  // live in volatile config, so re-apply picks up whatever the user last saved.
-  // A malformed value is reported here rather than at the first click.
+  // are volatile refs: Loader changes them without re-applying the plugin.
+  // Read them after the owning fiber's live update, before a saved view is sent.
   let installPreferenceError = null
-  try { setInstallPreferences(parseInstallPreferences(config, { tools: OFFICIAL_TOOLS })) }
-  catch (error) { installPreferenceError = errorText(error) }
+  const syncInstallPreferences = () => {
+    try {
+      const next = parseInstallPreferences(config, { tools: OFFICIAL_TOOLS, ...currentInstallOptions() })
+      setInstallPreferences(next)
+      installPreferenceError = null
+    } catch (error) { installPreferenceError = errorText(error) }
+  }
+  const installFields = new Set(['toolInstallDir', 'toolNpmRegistry', 'toolInstallMethodsJson', 'toolScriptUrlsJson', 'toolAllowScriptInstall'])
+  syncInstallPreferences()
+  // Loader scopes this event to the fiber whose refs were committed.
+  ctx.on('loader/volatile-update', paths => {
+    if (Array.isArray(paths) && paths.some(path => installFields.has(path?.[0]))) syncInstallPreferences()
+  })
+  const assertInstallPreferences = () => {
+    if (installPreferenceError) throw new Error(`官方工具安装设置无效：${installPreferenceError}`)
+  }
   // The official Host injects typert; direct lightweight uses of apply may
   // supply only the model/command services and do not expose the Desktop RPC.
   if (ctx.typert) {
@@ -1449,7 +1463,11 @@ export function apply(ctx, config = {}) {
       process.once('exit', onExit)
       return () => { process.off('exit', onExit); terminals.disposeAll('dispose') }
     }, 'model-router-galgame: interactive terminals')
-    registerOfficialToolsRemote(ctx, routerRemoteServices(ctx, config, { terminals }))
+    registerOfficialToolsRemote(ctx, {
+      ...routerRemoteServices(ctx, config, { terminals }),
+      installSettingsError: () => installPreferenceError,
+      installRequestedDirectory: () => valueOf(config, 'toolInstallDir', ''),
+    })
   }
   ctx.on('tools/pre-execute', async (exec, next) => {
     const decision = await next()
@@ -1498,7 +1516,7 @@ export function apply(ctx, config = {}) {
     if (reasons.length) return combinedAsk(reasons)
     return decision
   })
-  registerOfficialToolModels(ctx, config)
+  registerOfficialToolModels(ctx, config, assertInstallPreferences)
   ctx.tools.register(defineTool({
     name: 'model_router_routes',
     description: 'List provider/model routes registered in the official DeepSeek Harness model directory. Credential and network availability are not verified. No API keys or endpoints are returned.',
@@ -1611,6 +1629,7 @@ export function apply(ctx, config = {}) {
       const toolId = matched[2]
       const method = matched[3]
       try {
+        assertInstallPreferences()
         const job = action === 'uninstall' ? startUninstall(toolId, { method })
           : action === 'repair' ? startRepair(toolId, { method })
             : startInstall(toolId, { method })
@@ -1649,7 +1668,7 @@ async function waitForInstall(toolId, signal) {
 }
 
 /** Register the model-facing official-tool probes and installer. */
-function registerOfficialToolModels(ctx, config) {
+function registerOfficialToolModels(ctx, config, assertInstallPreferences) {
   ctx.tools.register(defineTool({
     name: 'model_router_tools',
     description: 'Probe the fixed registry of official model tools (Kimi Code, Claude Code, Codex, MiniMax Code, MiMo Code, Grok Build, Gemini CLI, OpenCode, Step Code, ZCode) and report which are installed with their versions, plus each tool\'s available install methods and the effective install directory and npm source. Never reads credentials.',
@@ -1680,6 +1699,7 @@ function registerOfficialToolModels(ctx, config) {
     },
     output: JSON_OUTPUT,
     async execute(args, exec) {
+      assertInstallPreferences()
       const job = startInstall(args.tool, { method: text(args.method) || undefined })
       const settled = await waitForInstall(job.tool, exec.signal)
       const tool = getOfficialTool(args.tool)
@@ -1704,6 +1724,7 @@ function registerOfficialToolModels(ctx, config) {
     },
     output: JSON_OUTPUT,
     async execute(args, exec) {
+      assertInstallPreferences()
       const job = startRepair(args.tool, { method: text(args.method) || undefined })
       const settled = await waitForInstall(job.tool, exec.signal)
       const tool = getOfficialTool(args.tool)
@@ -1726,6 +1747,7 @@ function registerOfficialToolModels(ctx, config) {
     },
     output: JSON_OUTPUT,
     async execute(args, exec) {
+      assertInstallPreferences()
       const job = startUninstall(args.tool, { method: text(args.method) || undefined })
       const settled = await waitForInstall(job.tool, exec.signal)
       const tool = getOfficialTool(args.tool)

package/.dsh-plugin/official-tools-remote-service.mjs

@@ -1,8 +1,8 @@
 /** Host receiver for the official desktop's typed one-click installer RPC. */
 import { readFileSync } from 'node:fs'
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
-import { getOfficialTool, installMethodBlockReason, OFFICIAL_TOOLS } from './shared/official-tool-registry.mjs'
-import { resolveInstallPlan, resolveUninstallPlan } from './shared/tool-install-preferences.mjs'
+import { getOfficialTool, installCommandLine, installMethodBlockReason, OFFICIAL_TOOLS } from './shared/official-tool-registry.mjs'
+import { resolveInstallLocation, resolveInstallPlan, resolveUninstallPlan } from './shared/tool-install-preferences.mjs'
 import { officialToolExecutionCapabilities, officialToolReadiness } from './shared/official-tool-executor.mjs'
 import {
   cancelInstall,
@@ -41,8 +41,7 @@ const unavailable = () => { throw new Error('模型路由工作台服务尚未
  * command line that would actually run. The panel shows this before the user
  * clicks, so an install is never a surprise command.
  */
-function installSummary() {
-  const preferences = installPreferences()
+export function installSummary(preferences = installPreferences(), options = currentInstallOptions()) {
   return {
     installDir: preferences.installDir ?? '',
     registry: preferences.registry ?? '',
@@ -56,22 +55,59 @@ function installSummary() {
         command: null,
         uninstallCommand: null,
         methodId: null,
-        // What the user pinned, which may differ from the effective method when
-        // the pinned one does not run on this platform.
+        // A pinned unavailable method stays selected and reports its reason.
         savedMethodId: preferences.methods?.[tool.id] ?? null,
         notices: [],
       }
+      if (tool.manager === 'signed-windows-installer') {
+        entry.methodId = 'signed-windows-installer'
+        if (options.platform === 'win32') {
+          entry.command = installCommandLine(tool)
+          entry.updateCommand = entry.command
+          entry.notices = [preferences.installDir
+            ? `请在官方安装窗口手动选择 ${preferences.installDir}，完成后重新体检。`
+            : '请在官方安装窗口选择目录并完成安装，然后重新体检。']
+        } else entry.installError = entry.error = 'ZCode 签名安装器仅支持 Windows。'
+        entry.uninstallError = 'ZCode 是桌面安装版，请在系统“应用”中卸载它。'
+        return entry
+      }
       for (const method of tool.installMethods ?? []) {
-        entry.methods.push({ id: method.id, label: method.label, kind: method.kind, blocked: installMethodBlockReason(method) })
+        const item = { id: method.id, label: method.label, kind: method.kind,
+          supportsInstallDir: method.supportsInstallDir === true,
+          blocked: installMethodBlockReason(method, options.platform) }
+        try {
+          const plan = resolveInstallPlan(tool, method.id, preferences, options)
+          item.command = planCommandLine(plan)
+          item.installDir = resolveInstallLocation(tool, method, preferences, options)?.dir ?? ''
+          item.notices = plan.notices ?? []
+        } catch (error) {
+          item.blocked = errorText(error).slice(0, 200)
+        }
+        try {
+          const removal = resolveUninstallPlan(tool, method.id, preferences, options)
+          item.uninstallCommand = planCommandLine(removal, 'uninstall')
+        } catch (error) { item.uninstallError = errorText(error).slice(0, 200) }
+        entry.methods.push(item)
       }
       try {
-        const plan = resolveInstallPlan(tool, undefined, preferences, currentInstallOptions())
+        const plan = resolveInstallPlan(tool, undefined, preferences, options)
         entry.methodId = plan.methodId
         entry.command = planCommandLine(plan)
+        entry.installDir = resolveInstallLocation(tool, plan.method, preferences, options)?.dir ?? ''
+        entry.updateMethodId = plan.methodId
+        entry.updateCommand = entry.command
+        entry.updateInstallDir = entry.installDir
         entry.notices = plan.notices ?? []
-        entry.uninstallCommand = planCommandLine(resolveUninstallPlan(tool, plan.methodId, preferences, currentInstallOptions()), 'uninstall')
       } catch (error) {
-        entry.error = errorText(error).slice(0, 200)
+        entry.installError = entry.error = errorText(error).slice(0, 200)
+      }
+      try {
+        const removal = resolveUninstallPlan(tool, undefined, preferences, options)
+        entry.methodId ??= removal.methodId
+        entry.installDir ??= resolveInstallLocation(tool, removal.method, preferences, options)?.dir ?? ''
+        entry.uninstallCommand = planCommandLine(removal, 'uninstall')
+      } catch (error) {
+        entry.uninstallError = errorText(error).slice(0, 200)
       }
       return entry
     }),
@@ -143,13 +179,25 @@ export class OfficialToolsRemoteService extends TypertRemoteService {
       executionCapabilities: officialToolExecutionCapabilities(),
       executionReadiness,
       hostVersion: HOST_PLUGIN_VERSION,
-      install: installSummary(),
+      install: this.installSettings().install,
     }
   }
 
+  /** Refresh saved methods and commands without spawning CLIs or checking downloads. */
+  installSettings() {
+    const error = this.services?.installSettingsError?.()
+    if (error) throw new Error(`官方工具安装设置无效：${error}`)
+    const install = installSummary()
+    // The saved input can contain Host-only home/environment expansions. Keep
+    // it separate from the resolved directory used by the actual command.
+    install.requestedInstallDir = this.services?.installRequestedDirectory?.() ?? install.installDir
+    return { install, hostVersion: HOST_PLUGIN_VERSION }
+  }
+
   /** Start one serialized fixed-registry install; return immediately for UI polling. */
   async installTool(request) {
     return settled(async () => {
+      this.installSettings()
       await ensureNpmPrefixOnPath()
       return { accepted: true, job: startInstall(request.tool, { method: request.method }) }
     })
@@ -161,6 +209,7 @@ export class OfficialToolsRemoteService extends TypertRemoteService {
    */
   async uninstallTool(request) {
     return settled(async () => {
+      this.installSettings()
       await ensureNpmPrefixOnPath()
       return { accepted: true, job: startUninstall(request.tool, { method: request.method }) }
     })
@@ -169,6 +218,7 @@ export class OfficialToolsRemoteService extends TypertRemoteService {
   /** Reinstall the tool even when it already reports the latest version. */
   async repairTool(request) {
     return settled(async () => {
+      this.installSettings()
       await ensureNpmPrefixOnPath()
       return { accepted: true, job: startRepair(request.tool, { method: request.method }) }
     })

package/.dsh-plugin/shared/official-tool-executor.mjs

@@ -18,13 +18,14 @@ import { access, readFile, realpath, stat } from 'node:fs/promises'
 import { constants } from 'node:fs'
 import { StringDecoder } from 'node:string_decoder'
 import { basename, delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { getOfficialTool, OFFICIAL_TOOLS } from './official-tool-registry.mjs'
-import { ensureNpmPrefixOnPath } from './official-tools-runtime.mjs'
+import { getOfficialTool, installMethodFor, OFFICIAL_TOOLS } from './official-tool-registry.mjs'
+import { currentInstallOptions, ensureNpmPrefixOnPath, installPreferences, preferredToolDirectories, usesConfiguredInstallPlan } from './official-tools-runtime.mjs'
+import { resolveInstallPlan } from './tool-install-preferences.mjs'
 import { buildMiniMaxInvocation, createMiniMaxStreamParser } from './vendor-minimax-adapter.mjs'
 import { discoverZCodeBundle } from './zcode-bundle.mjs'
 import { npmAttestor } from './npm-attestation.mjs'
 import { compareReleaseVersions, isReleaseVersion } from './latest-versions.mjs'
-import { resolveMiMoGrokLaunch, createMiMoGrokParser } from './vendor-mimo-grok-adapter.mjs'
+import { resolveMiMoGrokLaunch, createMiMoGrokParser, installedModuleRoots } from './vendor-mimo-grok-adapter.mjs'
 import { emptyOutputError, outputIsEmpty, usageFromEvents, usageFromOutput } from './task-executors.mjs'
 
 const IS_WINDOWS = process.platform === 'win32'
@@ -169,6 +170,22 @@ function pathDirectories() {
   return [...new Set(value.split(delimiter).map(part => part.trim().replace(/^"|"$/g, '')).filter(Boolean))]
 }
 
+/** The configured install location is authoritative even if another copy is newer. */
+export function officialToolEntrySelection(toolId, { preferences = installPreferences(), plan: selectedPlan, preferredDirs } = {}) {
+  const tool = getOfficialTool(toolId)
+  if (!tool || tool.manager === 'signed-windows-installer') return { directories: pathDirectories(), plan: null, configured: false }
+  // A saved script choice stays usable after future script installs are
+  // disabled. Automatic selection still follows the same switch as installation.
+  const selectedScript = installMethodFor(tool, preferences.methods?.[toolId])?.kind === 'script'
+  const discoveryPreferences = selectedScript ? { ...preferences, allowScriptInstall: true } : preferences
+  const plan = selectedPlan ?? resolveInstallPlan(tool, undefined, discoveryPreferences, currentInstallOptions())
+  const preferred = preferredDirs ?? (selectedPlan ? (selectedPlan.binDir ? [selectedPlan.binDir] : [])
+    : preferredToolDirectories(toolId, discoveryPreferences))
+  return { directories: Array.isArray(preferredDirs) || preferred.length ? [...preferred] : pathDirectories(), plan,
+    configured: Boolean(selectedPlan) || usesConfiguredInstallPlan(toolId, preferences),
+    preferred: Array.isArray(preferredDirs) || preferred.length > 0, directoryOverride: Array.isArray(preferredDirs) }
+}
+
 function versionAtLeast(value, minimum) {
   const found = /^(\d+)\.(\d+)\.(\d+)(?:$|-)/.exec(String(value ?? ''))
   if (!found) return false
@@ -216,27 +233,35 @@ async function readPackageEntry(packageDirectory, packageName, binName, expected
 }
 
 /** Resolve the package's real `bin` file, never its Windows .cmd shim. */
-async function findGlobalPackageEntries(packageName, binName, expectedBin, workspace) {
-  await ensureNpmPrefixOnPath()
+export async function findGlobalPackageEntries(packageName, binName, expectedBin, workspace, { directories, manager = null, moduleRoots, selection: selectedSelection } = {}) {
+  const tool = OFFICIAL_TOOLS.find(item => item.package === packageName)
+  const selection = selectedSelection ?? (directories || Array.isArray(moduleRoots) ? null : officialToolEntrySelection(tool?.id))
+  const exactRoots = Array.isArray(moduleRoots) ? moduleRoots : selection?.plan?.packageModuleRoots
+  if (!Array.isArray(exactRoots) && !directories && !selection?.preferred) await ensureNpmPrefixOnPath()
+  const targets = directories ?? (selection?.preferred ? selection.directories : pathDirectories())
+  const selectedManager = manager ?? selection?.plan?.manager ?? null
   const packageParts = packageName.split('/')
   const found = []
   const seen = new Set()
-  for (const directory of pathDirectories()) {
-    const moduleParents = [join(directory, 'node_modules')]
-    if (basename(directory).toLowerCase() === '.bin') moduleParents.push(resolve(directory, '..'))
-    if (!IS_WINDOWS) moduleParents.push(resolve(directory, '..', 'lib', 'node_modules'))
-    const candidates = moduleParents.map(modules => join(modules, ...packageParts))
-    // Native installs put the exe in `<package>/bin` and that directory on PATH
-    // (for example D:\Program Files\Claude\node_modules\@anthropic-ai\claude-code\bin).
-    candidates.push(directory, resolve(directory, '..'))
-    for (const packageDirectory of candidates) {
-      const entry = await readPackageEntry(packageDirectory, packageName, binName, expectedBin, workspace, seen)
-      if (entry) found.push(entry)
-    }
+  const roots = Array.isArray(exactRoots) ? exactRoots : await installedModuleRoots(targets, { manager: selectedManager })
+  const candidates = roots.map(modules => join(modules, ...packageParts))
+  // Native npm installs can put their package/bin directory directly on PATH.
+  if (!Array.isArray(exactRoots) && selectedManager !== 'pnpm') candidates.push(...targets.flatMap(directory => [directory, resolve(directory, '..')]))
+  for (const packageDirectory of candidates) {
+    const entry = await readPackageEntry(packageDirectory, packageName, binName, expectedBin, workspace, seen)
+    if (entry) found.push(entry)
   }
   return found
 }
 
+/** Official Windows repairs use a distinct directory key for the same npm version. */
+export function miniMaxReleaseVersion(releaseKey) {
+  const repair = /^(\d{1,6}\.\d{1,6}\.\d{1,6})-repair-[1-9]\d{0,9}-[0-9a-f]{32}$/i.exec(String(releaseKey ?? ''))
+  if (repair) return repair[1]
+  if (String(releaseKey ?? '').includes('-repair-')) return null
+  return isReleaseVersion(releaseKey) ? releaseKey : null
+}
+
 /**
  * The official MiniMax Windows installer uses a versioned releases tree rather
  * than npm -g. Any release named by its `current` file is accepted, but every
@@ -252,10 +277,13 @@ export async function findManagedMiniMaxEntry(workspace,
       const root = await realpath(directory)
       if (root === workspace || inside(workspace, root)) continue
       if (!(await stat(join(root, 'mcode.cmd'))).isFile()) continue
-      const version = (await readFile(join(root, 'current'), 'utf8')).trim()
-      if (!isReleaseVersion(version)) continue
-      const releaseRoot = await realpath(join(root, 'releases', version))
-      if (!inside(root, releaseRoot)) continue
+      const releaseKey = (await readFile(join(root, 'current'), 'utf8')).trim()
+      const version = miniMaxReleaseVersion(releaseKey)
+      if (!version) continue
+      const releasesRoot = await realpath(join(root, 'releases'))
+      if (!inside(root, releasesRoot)) continue
+      const releaseRoot = await realpath(join(releasesRoot, releaseKey))
+      if (!inside(releasesRoot, releaseRoot)) continue
       const packageRoot = await realpath(join(releaseRoot, 'node_modules', '@minimax-ai', 'code'))
       if (!inside(releaseRoot, packageRoot)) continue
       const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
@@ -268,7 +296,7 @@ export async function findManagedMiniMaxEntry(workspace,
       const native = await realpath(join(packageRoot, 'node_modules', 'better-sqlite3',
         'build', 'Release', 'better_sqlite3.node'))
       if (!inside(packageRoot, native) || !(await stat(native)).isFile()) continue
-      return { entry, packageRoot, version, source: 'official-windows-installer-npm-attested' }
+      return { entry, packageRoot, version, installDir: root, binDir: root, source: 'official-windows-installer-npm-attested' }
     } catch { /* inspect the next PATH directory */ }
   }
   return null
@@ -279,24 +307,25 @@ function newestFirst(entries) {
   return [...entries].sort((left, right) => (compareReleaseVersions(right.version, left.version) ?? 0))
 }
 
-async function findCodexExecutable(workspace) {
-  await ensureNpmPrefixOnPath()
-  const filename = IS_WINDOWS ? 'codex.exe' : 'codex'
-  for (const directory of pathDirectories()) {
+async function findSignedNativeExecutable(toolId, workspace, signer, selection = officialToolEntrySelection(toolId)) {
+  if (!selection.preferred) await ensureNpmPrefixOnPath()
+  const command = toolId === 'claude-code' ? 'claude' : toolId
+  const filename = IS_WINDOWS ? `${command}.exe` : command
+  for (const directory of selection.preferred ? selection.directories : pathDirectories()) {
     try {
       const pathRoot = await realpath(directory)
       if (pathRoot === workspace || inside(workspace, pathRoot)) continue
       const entry = await realpath(join(directory, filename))
       if (inside(workspace, entry) || !(await stat(entry)).isFile()) continue
       await access(entry, IS_WINDOWS ? constants.F_OK : constants.X_OK)
-      if (IS_WINDOWS && !(await hasOfficialWindowsSignature(entry, CODEX_SIGNER))) continue
+      if (IS_WINDOWS && !(await hasOfficialWindowsSignature(entry, signer))) continue
       return { entry, source: IS_WINDOWS ? 'signed-native-executable' : 'path-native-executable' }
     } catch { /* try the next PATH entry */ }
   }
   return null
 }
 
-function nodeVersion(entry) {
+function nodeVersion(entry, pattern = /^v(\d+\.\d+\.\d+)/) {
   return new Promise(resolveVersion => {
     let child
     try { child = spawn(entry, ['--version'], { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }) }
@@ -312,7 +341,7 @@ function nodeVersion(entry) {
     const timer = setTimeout(() => { child.kill('SIGTERM'); finish(null) }, 4_000)
     child.stdout.on('data', bytes => { output = tail(output, String(bytes)) })
     child.on('error', () => finish(null))
-    child.on('close', code => finish(code === 0 ? /^v(\d+\.\d+\.\d+)/.exec(output.trim())?.[1] ?? null : null))
+    child.on('close', code => finish(code === 0 ? pattern.exec(output.trim())?.[1] ?? null : null))
   })
 }
 
@@ -335,17 +364,53 @@ async function findNodeExecutable(workspace, minimum = [22, 19, 0], acceptedVers
 }
 
 /** Resolve the signed native binary carried by the official npm wrapper. */
-async function findSignedPackagedCodex(packageRoot, workspace) {
+export async function findSignedPackagedCodex(packageRoot, workspace, {
+  installDir = '', manager = null, moduleRoots = [], verifySignature = hasOfficialWindowsSignature,
+} = {}) {
   if (!IS_WINDOWS) return null
   const target = process.arch === 'arm64' ? ['codex-win32-arm64', 'aarch64-pc-windows-msvc']
     : process.arch === 'x64' ? ['codex-win32-x64', 'x86_64-pc-windows-msvc'] : null
   if (!target) return null
-  const candidate = join(packageRoot, 'node_modules', '@openai', target[0], 'vendor', target[1], 'bin', 'codex.exe')
   try {
-    const entry = await realpath(candidate)
-    if (!inside(packageRoot, entry) || inside(workspace, entry) || !(await stat(entry)).isFile()) return null
-    if (!(await hasOfficialWindowsSignature(entry, CODEX_SIGNER))) return null
-    return { entry, source: 'signed-official-npm-native' }
+    const wrapperRoot = await realpath(packageRoot)
+    if (wrapperRoot === workspace || inside(workspace, wrapperRoot)) return null
+    const wrapper = JSON.parse(await readFile(join(wrapperRoot, 'package.json'), 'utf8'))
+    const nativeName = `@openai/${target[0]}`
+    const dependency = wrapper.optionalDependencies?.[nativeName]
+    const alias = /^npm:(@openai\/[A-Za-z0-9-]+)@(.+)$/.exec(String(dependency ?? ''))
+    const expectedName = alias ? alias[1] : nativeName
+    const expectedVersion = alias ? alias[2] : dependency
+    if (wrapper.name !== '@openai/codex' || !isReleaseVersion(wrapper.version)
+      || !['@openai/codex', nativeName].includes(expectedName) || !isReleaseVersion(expectedVersion)) return null
+    let virtualStore = null
+    for (let directory = wrapperRoot; directory !== resolve(directory, '..'); directory = resolve(directory, '..')) {
+      if (basename(directory) === '.pnpm') { virtualStore = directory; break }
+    }
+    // pnpm's optional platform package is a sibling symlink in its virtual
+    // store. A configured prefix confines both wrapper and native package to
+    // that prefix's global tree, never another store or arbitrary directory.
+    const boundary = manager === 'pnpm' && installDir
+      ? await realpath(join(installDir, '.pnpm', 'global'))
+      : virtualStore ?? await realpath(resolve(wrapperRoot, '..', '..'))
+    if (!inside(boundary, wrapperRoot)) return null
+    const nativePackages = [
+      join(wrapperRoot, 'node_modules', '@openai', target[0]),
+      resolve(wrapperRoot, '..', target[0]),
+      ...moduleRoots.map(modules => join(modules, '@openai', target[0])),
+    ]
+    for (const nativePackage of nativePackages) {
+      try {
+        const nativeRoot = await realpath(nativePackage)
+        if (!inside(boundary, nativeRoot) || inside(workspace, nativeRoot)) continue
+        const manifest = JSON.parse(await readFile(join(nativeRoot, 'package.json'), 'utf8'))
+        if (manifest.name !== expectedName || manifest.version !== expectedVersion) continue
+        const entry = await realpath(join(nativeRoot, 'vendor', target[1], 'bin', 'codex.exe'))
+        if (!inside(nativeRoot, entry) || inside(workspace, entry) || !(await stat(entry)).isFile()) continue
+        if (!(await verifySignature(entry, CODEX_SIGNER))) continue
+        return { entry, source: 'signed-official-npm-native' }
+      } catch { /* try the wrapper's other official optional-package location */ }
+    }
+    return null
   } catch { return null }
 }
 
@@ -404,13 +469,18 @@ function hasOfficialWindowsSignature(entry, expectedSigner) {
   })
 }
 
-async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readiness.') {
+async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readiness.', selectionOptions = {}) {
   if (toolId === 'claude-code') {
-    const entries = await findGlobalPackageEntries('@anthropic-ai/claude-code', 'claude', 'bin/claude.exe', workspace)
+    const selection = officialToolEntrySelection(toolId, selectionOptions)
+    const native = selection.plan.kind === 'script'
+      ? await findSignedNativeExecutable(toolId, workspace, CLAUDE_SIGNER, selection) : null
+    if (native) native.version = await nodeVersion(native.entry, /(?:^|\s)(\d+\.\d+\.\d+(?:-[\w.-]+)?)/)
+    const entries = selection.plan.kind === 'script' ? (native ? [native] : [])
+      : await findGlobalPackageEntries('@anthropic-ai/claude-code', 'claude', 'bin/claude.exe', workspace, { selection })
     const compatible = entries.filter(entry => versionAtLeast(entry.version, CLAUDE_MIN_RESTRICTED_VERSION))
     let found = null
     for (const entry of compatible) {
-      if (!IS_WINDOWS || await hasOfficialWindowsSignature(entry.entry, CLAUDE_SIGNER)) {
+      if (entry === native || !IS_WINDOWS || await hasOfficialWindowsSignature(entry.entry, CLAUDE_SIGNER)) {
         found = entry
         break
       }
@@ -440,13 +510,20 @@ async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readin
   }
   if (toolId === 'codex') {
     if (!IS_WINDOWS) return { unsupported: CAPABILITIES.codex.reason }
-    const packages = await findGlobalPackageEntries('@openai/codex', 'codex', 'bin/codex.js', workspace)
+    const selection = officialToolEntrySelection(toolId, selectionOptions)
+    const packages = selection.plan.kind === 'script' ? []
+      : await findGlobalPackageEntries('@openai/codex', 'codex', 'bin/codex.js', workspace, { selection })
+    const moduleRoots = selection.plan.packageModuleRoots ?? (packages.length
+      ? await installedModuleRoots(selection.preferred ? selection.directories : pathDirectories(), { manager: selection.plan.manager }) : [])
     let found = null
     for (const entry of packages) {
-      found = await findSignedPackagedCodex(entry.packageRoot, workspace)
+      found = await findSignedPackagedCodex(entry.packageRoot, workspace,
+        { installDir: selection.plan.installDir, manager: selection.plan.manager, moduleRoots })
       if (found) break
     }
-    found ??= await findCodexExecutable(workspace)
+    if (!found && selection.plan.kind === 'script') {
+      found = await findSignedNativeExecutable(toolId, workspace, CODEX_SIGNER, selection)
+    }
     if (!found) return { unsupported: '未找到具有 OpenAI 有效签名的 codex.exe。' }
     return {
       file: found.entry,
@@ -456,8 +533,10 @@ async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readin
     }
   }
   if (toolId === 'kimi-code') {
+    const selection = officialToolEntrySelection(toolId, selectionOptions)
+    if (selection.plan.kind === 'script') return { unsupported: '所选 Kimi 原生脚本安装没有可核验的 npm 执行入口；不会改用其他安装目录中的 Kimi。' }
     const tool = getOfficialTool(toolId)
-    const entries = await findGlobalPackageEntries(tool.package, 'kimi', 'dist/main.mjs', workspace)
+    const entries = await findGlobalPackageEntries(tool.package, 'kimi', 'dist/main.mjs', workspace, { selection })
     const found = newestFirst(entries)[0]
     if (!found) return { unsupported: `未找到官方 npm 包 ${tool.package} 的 kimi 入口（dist/main.mjs）。` }
     const nodeExecutable = await findNodeExecutable(workspace)
@@ -474,8 +553,12 @@ async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readin
   }
   if (toolId === 'minimax-code') {
     const tool = getOfficialTool(toolId)
-    const entries = await findGlobalPackageEntries(tool.package, 'mcode', 'cli.js', workspace)
-    const found = newestFirst(entries)[0] ?? await findManagedMiniMaxEntry(workspace)
+    const selection = officialToolEntrySelection(toolId, selectionOptions)
+    const managed = selection.plan.kind === 'script' || selection.directoryOverride
+      ? await findManagedMiniMaxEntry(workspace, selection.directories)
+      : !selection.configured ? await findManagedMiniMaxEntry(workspace) : null
+    const entries = selection.plan.kind === 'script' ? [] : await findGlobalPackageEntries(tool.package, 'mcode', 'cli.js', workspace, { selection })
+    const found = managed ?? newestFirst(entries)[0]
     if (!found) return { unsupported: `未找到官方 npm 包 ${tool.package} 的 mcode 入口（cli.js）。` }
     const nodeExecutable = await findNodeExecutable(workspace, [22, 19, 0], version => {
       const major = Number(String(version).split('.')[0])
@@ -492,7 +575,12 @@ async function launchSpec(toolId, workspace, mode, modelId, task = 'Check readin
   }
   if (toolId === 'mimo-code' || toolId === 'grok-build') {
     try {
-      return await resolveMiMoGrokLaunch({ toolId, workspace, mode, modelId, task })
+      const selection = officialToolEntrySelection(toolId, selectionOptions)
+      if (selection.plan.kind === 'script') return { unsupported: `所选 ${getOfficialTool(toolId).label} 原生脚本安装没有可核验的 npm 元数据；不会改用其他安装目录中的工具。` }
+      return await resolveMiMoGrokLaunch({ toolId, workspace, mode, modelId, task,
+        directories: selection.preferred ? selection.directories : undefined,
+        moduleRoots: selection.plan.packageModuleRoots,
+        manager: selection.plan.manager })
     } catch (error) {
       return { unsupported: `官方原生入口校验失败：${String(error?.message ?? error).slice(0, 240)}` }
     }
@@ -586,14 +674,14 @@ export function harnessSandboxBlocker(toolId, platform = process.platform) {
 }
 
 /** Check the actual trusted launch entry without starting an account call. */
-export async function officialToolReadiness(toolId, workspace = process.cwd()) {
+export async function officialToolReadiness(toolId, workspace = process.cwd(), selectionOptions = {}) {
   const tool = getOfficialTool(toolId)
   if (!tool) return { id: String(toolId), ready: false, reason: '工具不在固定官方注册表中。' }
   const capability = CAPABILITIES[tool.id]
   if (!capability?.supported) return { id: tool.id, ready: false, reason: capability?.reason ?? '当前平台不支持托管执行。' }
   try {
     const directory = await checkedWorkspace(workspace)
-    const spec = await launchSpec(tool.id, directory, capability.modes[0], null)
+    const spec = await launchSpec(tool.id, directory, capability.modes[0], null, undefined, selectionOptions)
     return spec.unsupported
       ? { id: tool.id, ready: false, reason: spec.unsupported }
       : { id: tool.id, ready: true, source: spec.source, modes: capability.modes }