From 1b62eb6bc2d2feb538ccbe7d26b57dc6706c0f09 Mon Sep 17 00:00:00 2001
From: lick <2188718831@qq.com>
Date: Sun, 25 Oct 2026 03:31:57 -0700
Subject: [PATCH 1/2] =?UTF-8?q?fix(macos):=20=E8=BF=90=E8=A1=8C=20Node=20?=
 =?UTF-8?q?=E8=84=9A=E6=9C=AC=E6=97=B6=E8=A1=A5=E9=BD=90=E5=90=AF=E5=8A=A8?=
 =?UTF-8?q?=20PATH=20(#1455)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

从 Finder 启动的 Lithe 只继承 launchd 的最小 PATH，pnpm/npm/yarn/tsx 的
#!/usr/bin/env node 找不到解释器，运行 package.json 脚本直接报
env: node: No such file or directory。

- RunLaunchEnvironment：启动前把发现到的 node 目录和解析出的可执行文件目录
  前置到子进程 PATH，按小写去重；项目内 node 与项目根目录不注入，避免仓库
  文件劫持后续系统命令。
- RunExecutableResolver：.toolchain 与 .command 共用同一条环境组合路径，
  覆盖主进程和预启动步骤。
- RunLaunchEnvironmentTests：6 个用例覆盖补齐、项目内排除、wrapper 排除、
  去重与顺序、缺失 PATH、resolver 实际接线。
- 新增 Agent Note 与平台特性矩阵 run-node-launch-path 记录。
---
 ...0-25-run-launch-path-for-node-launchers.md | 112 +++++++++++
 .../Services/Java/RunExecutableResolver.swift |  21 +-
 .../Services/Java/RunLaunchEnvironment.swift  |  70 +++++++
 .../RunLaunchEnvironmentTests.swift           | 189 ++++++++++++++++++
 .../features/run-node-launch-path.json        |  25 +++
 5 files changed, 412 insertions(+), 5 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
 create mode 100644 macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
 create mode 100644 macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
 create mode 100644 shared/platform-feature-matrix/features/run-node-launch-path.json

diff --git a/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md b/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
new file mode 100644
index 0000000000..1c51a4bb83
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
@@ -0,0 +1,112 @@
+# Agent 笔记：从 Finder 启动的 Lithe 运行 Node 脚本时补齐启动 PATH
+
+状态：已实现
+
+## 先说结论
+
+从 Finder / Dock 启动的 Lithe 继承 launchd 的最小环境，`PATH` 只有
+`/usr/bin:/bin:/usr/sbin:/sbin`。Lithe 自己能通过 Homebrew、fnm、nvm 找到
+`pnpm`，但 `pnpm` 这类启动器用 `#!/usr/bin/env node` 找解释器，子进程按自己的
+`PATH` 找不到 `node`，于是 `pnpm run <script>` 直接报
+`env: node: No such file or directory`（#1455）。
+
+现在运行入口会在启动前把两类目录补到子进程 `PATH` 前面：Lithe 发现到的 `node`
+解释器目录，以及解析出的可执行文件目录；项目内的 `node` 和项目根目录永远不加。
+终端、调试适配器和语言服务器不走这条路径，行为不变。
+
+## 问题
+
+用户从 Finder 启动 0.6.2 发行包，打开 pnpm 管理的项目，点 package.json 里的
+`clean` 脚本。输出窗口先显示 `$ pnpm run clean`，紧接着就是
+`env: node: No such file or directory`，进程没有真正运行。终端里执行同样的命令
+正常，因为交互 shell 的启动脚本把 fnm / Homebrew 目录加进了 `PATH`。
+
+代码侧的链路是：
+
+- `MacRuntimeLocator.environment()` 直接返回 `ProcessInfo.processInfo.environment`，
+  也就是 Lithe 自己被启动时拿到的环境。
+- `ProjectRuntimeService.processEnvironment(overrides:)` 只在这份环境上叠加调用方
+  传来的值，不补任何“我已经找到的工具”目录。
+- `RunExecutableResolver` 把这份环境原样交给 `RunService`，`RunService` 再交给
+  `Process.start`。
+
+所以“Lithe 能找到 pnpm”靠的是 `MacRuntimeToolDiscovery` 对 PATH、Homebrew 和
+Node 版本管理器目录的额外探测；这份探测结果从来没有进入子进程环境。
+
+术语：
+
+- launchd：macOS 的进程启动器。Finder 启动的 app 只继承它给出的最小环境，不会
+  读取用户 shell 的启动脚本。
+- shebang `#!/usr/bin/env node`：脚本第一行让内核用 `env` 去当前进程的 `PATH`
+  里查找 `node`。用绝对路径启动脚本并不能替它准备好 `PATH`。
+
+## 决策
+
+- 组合点放在 `RunExecutableResolver.resolve`：`.toolchain` 和 `.command` 两条
+  分支都会经过它。只补运行启动环境，不改 `ProjectRuntimeService.processEnvironment`
+  本身，避免终端、调试适配器、语言服务器被顺带改掉。
+- 目录顺序：`node` 目录在最前，其次是被解析出的可执行文件目录，之后才是原有
+  `PATH`。这样 `env node` 拿到的是 Lithe 实际选中的解释器；按小写比较去重，因为
+  默认的 APFS 卷大小写不敏感。
+- 安全边界：`RuntimeToolCandidate.source == .project` 的 `node` 不注入；可执行
+  文件位于项目根内时（例如 `mvnw`、`gradlew`），它所在的目录也不注入。仓库内容
+  不可信，把项目根放到 `PATH` 前部会让仓库里的同名文件劫持脚本后续调用的系统
+  命令。这与语言服务器侧 `languageToolProcessEnvironment` 的既有规则一致。
+- Windows 的运行入口 `prepend_runtime_paths` 早就在做“运行时目录 + 可执行文件
+  目录前置”。macOS 这次补上同类行为，两个产品的启动环境语义对齐。
+
+正确做法：
+
+```text
+pnpm 在 /opt/homebrew/bin，node 在 fnm 的 multishell 目录
+子进程 PATH = <fnm 的 node 目录>:<pnpm 目录>:<原有 PATH>
+```
+
+不要这样做：
+
+```text
+子进程 PATH = <项目根>:<项目 .lithe/bin>:<原有 PATH>
+```
+
+后者会让仓库自带的 `node`、`git` 或任何同名文件覆盖系统工具。
+
+## 考虑过的备选方案
+
+- 只把“解析出的可执行文件所在目录”加入 `PATH`（issue 报告里的建议）：不够。
+  Homebrew 安装的 `pnpm` 和 fnm 管理的 `node` 经常不在一处，`env node` 仍然
+  找不到解释器。
+- 在 `ProjectRuntimeService.processEnvironment` 里统一补：少一处分叉，但同一份
+  环境也被调试适配器和语言工具使用，副作用范围比“运行”大得多，而且这些路径
+  各自已经有 `LITHE_NODE_PATH` 之类的专门规则。
+- 像终端一样先启动一次登录 shell 取得用户 `PATH`：依赖用户 rc 文件、每次多起
+  一个进程、结果不确定，还会把 shell 初始化副作用带进运行。
+- 把项目自带的 `node` 也注入（沿用发现顺序里的“项目工具优先”）：会让不可信
+  仓库控制用户点击运行的每个脚本的解释器，收益小于风险。
+
+## 后果
+
+- 收益：从 Finder 启动也能运行 `pnpm` / `npm` / `yarn` / `tsx` 等脚本；脚本内部
+  再调用 `node` / `npm` 也能解析到同一套工具；与 Windows 行为一致。
+- 代价：每次运行解析多一次 `node` 候选发现（PATH 和各版本管理器目录的只读
+  探测），单次毫秒级；子进程 `PATH` 的内容和顺序与 0.6.2 不同。
+- 例外：系统里完全没有 `node` 时不注入任何目录，失败表现与修复前相同；项目里
+  只有自带 `node` 时也不注入，仍然按系统环境处理。
+
+## 验证
+
+- `./.agents/skills/write-stable-tests/scripts/verify-test-stability.sh`
+- `./.agents/skills/write-stable-tests/scripts/test-stability-macos.sh -- --filter RunLaunchEnvironmentTests`
+  覆盖六个场景：GUI 最小 PATH 下补齐 node 与启动器目录、项目内 node 被排除、
+  项目 wrapper 不把仓库根放进 PATH、已有目录去重且保持顺序、缺失 PATH 时新建、
+  resolver 对 `.command` 的实际接线。
+- `./scripts/verify-service-boundaries.sh`
+- 失败形态的手工复现：`env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin /usr/bin/env node --version`
+  返回 `env: node: No such file or directory`；把 node 目录加进 `PATH` 后恢复。
+  发行包上的 GUI 端到端运行未在本机复验。
+
+## 适用范围
+
+- `macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift`
+- `macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift`
+- `macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift`
+- 对照实现：`windows/tauri/src-tauri/src/run.rs` 中的 `prepend_runtime_paths`
diff --git a/macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift b/macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift
index bf0f16f6a7..141834da16 100644
--- a/macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift
+++ b/macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift
@@ -24,20 +24,21 @@ final class RunExecutableResolver: RunExecutableResolving {
     ) throws -> ResolvedRunExecutable {
         let planEnvironment = plan.environment.merging(options.environment) { _, userValue in userValue }
 
+        let resolved: ResolvedRunExecutable
         switch plan.executable {
         case .toolchain(let id):
             let toolchainProjectURL = id == "project-maven" && plan.workingDirectory != "."
                 ? projectURL.appending(path: plan.workingDirectory, directoryHint: .isDirectory)
                 : projectURL
-            let resolved = try toolchainRegistry.resolve(
+            let toolchain = try toolchainRegistry.resolve(
                 identifier: id,
                 projectURL: toolchainProjectURL.standardizedFileURL,
                 options: options,
                 runtimeService: runtimeService
             )
-            return ResolvedRunExecutable(
-                executableURL: resolved.executableURL,
-                environment: resolved.environment.merging(planEnvironment) { _, override in override }
+            resolved = ResolvedRunExecutable(
+                executableURL: toolchain.executableURL,
+                environment: toolchain.environment.merging(planEnvironment) { _, override in override }
             )
 
         case .command(let command):
@@ -46,11 +47,21 @@ final class RunExecutableResolver: RunExecutableResolving {
                     message: runtimeService.missingToolMessage(command)
                 )
             }
-            return ResolvedRunExecutable(
+            resolved = ResolvedRunExecutable(
                 executableURL: executable,
                 environment: runtimeService.processEnvironment(overrides: planEnvironment)
             )
         }
+
+        return ResolvedRunExecutable(
+            executableURL: resolved.executableURL,
+            environment: RunLaunchEnvironment.augmenting(
+                resolved.environment,
+                executableURL: resolved.executableURL,
+                nodeCandidates: runtimeService.executableCandidates("node"),
+                projectURL: projectURL
+            )
+        )
     }
 
     func refreshCandidates(projectURL: URL) async {
diff --git a/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift b/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
new file mode 100644
index 0000000000..0fb7386c22
--- /dev/null
+++ b/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
@@ -0,0 +1,70 @@
+import Foundation
+import LitheCoreContracts
+
+// Note: 运行启动 PATH 的取舍见 .agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
+
+/// Composes the environment for a run process that Lithe starts by absolute
+/// path.
+///
+/// A Lithe opened from Finder inherits launchd's minimal `PATH`, while the
+/// tools Lithe resolves can live in Homebrew or a Node version manager
+/// directory. Package managers and `node_modules/.bin` launchers start their
+/// interpreter through an `env`-based shebang, so the child still needs the
+/// interpreter directory on `PATH` even though the launcher itself is started
+/// by absolute path.
+///
+/// Windows already prepends the selected runtime directories and the resolved
+/// executable's directory in `windows/tauri/src-tauri/src/run.rs`; this keeps
+/// both products' launch environments equivalent.
+enum RunLaunchEnvironment {
+    /// Prepends the discovered interpreter directory and the resolved
+    /// executable's directory, keeping the remaining entries in their original
+    /// order. Entries are deduplicated case-insensitively because the default
+    /// macOS volume is case-insensitive.
+    ///
+    /// Project-owned interpreters and launchers are never promoted: an
+    /// untrusted repository must not capture the interpreter of every script
+    /// the user launches, and putting a project root on `PATH` would let
+    /// repository files shadow system tools.
+    static func augmenting(
+        _ environment: [String: String],
+        executableURL: URL,
+        nodeCandidates: [RuntimeToolCandidate],
+        projectURL: URL
+    ) -> [String: String] {
+        var leadingDirectories: [String] = []
+        if let node = nodeCandidates.first(where: {
+            $0.source != .project && !isInsideProject($0.executableURL, projectURL: projectURL)
+        }) {
+            leadingDirectories.append(node.executableURL.deletingLastPathComponent().path)
+        }
+        if !isInsideProject(executableURL, projectURL: projectURL) {
+            leadingDirectories.append(executableURL.deletingLastPathComponent().path)
+        }
+        guard !leadingDirectories.isEmpty else { return environment }
+
+        let existingDirectories = (environment["PATH"] ?? "")
+            .split(separator: ":")
+            .map(String.init)
+            .filter { !$0.isEmpty }
+        var seen = Set<String>()
+        let directories = (leadingDirectories + existingDirectories).filter {
+            seen.insert($0.lowercased()).inserted
+        }
+
+        var result = environment
+        result["PATH"] = directories.joined(separator: ":")
+        return result
+    }
+
+    private static func isInsideProject(_ url: URL, projectURL: URL) -> Bool {
+        let root = projectURL.standardizedFileURL.path
+        let path = url.standardizedFileURL.path
+        // A project of `/` would make every absolute path project-owned; no
+        // product flow opens that as a workspace, but the guard keeps the
+        // containment check total.
+        guard root != "/" else { return true }
+        let prefix = root.hasSuffix("/") ? root : root + "/"
+        return path == root || path.hasPrefix(prefix)
+    }
+}
diff --git a/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift b/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
new file mode 100644
index 0000000000..85da9d5c3d
--- /dev/null
+++ b/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
@@ -0,0 +1,189 @@
+import Foundation
+import LitheCoreContracts
+import Testing
+@testable import Lithe
+
+/// A Lithe opened from Finder inherits launchd's minimal `PATH`, while the
+/// tools it resolved may live in Homebrew or a Node version manager directory.
+/// These tests protect the launch environment that makes `#!/usr/bin/env node`
+/// launchers start the interpreter Lithe found.
+@Suite("Run launch environment")
+struct RunLaunchEnvironmentTests {
+    private let projectURL = URL(fileURLWithPath: "/fixture-project", isDirectory: true)
+
+    @Test
+    func guiLaunchPathReachesTheDiscoveredNodeInterpreter() {
+        let environment = RunLaunchEnvironment.augmenting(
+            ["PATH": "/usr/bin:/bin"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [
+                RuntimeToolCandidate(
+                    command: "node",
+                    executableURL: URL(fileURLWithPath: "/Users/fixture/.local/state/fnm_multishells/1/bin/node"),
+                    source: .environment
+                )
+            ],
+            projectURL: projectURL
+        )
+
+        #expect(environment["PATH"] == "/Users/fixture/.local/state/fnm_multishells/1/bin:/opt/homebrew/bin:/usr/bin:/bin")
+    }
+
+    @Test
+    func projectProvidedNodeCannotCaptureTheLaunchedScript() {
+        let projectNode = RuntimeToolCandidate(
+            command: "node",
+            executableURL: projectURL.appendingPathComponent(".lithe/bin/node"),
+            source: .project
+        )
+        let homebrewNode = RuntimeToolCandidate(
+            command: "node",
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/node"),
+            source: .homebrew
+        )
+
+        let withFallback = RunLaunchEnvironment.augmenting(
+            ["PATH": "/usr/bin:/bin"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [projectNode, homebrewNode],
+            projectURL: projectURL
+        )
+        let projectNodeOnly = RunLaunchEnvironment.augmenting(
+            ["PATH": "/usr/bin:/bin"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [projectNode],
+            projectURL: projectURL
+        )
+
+        #expect(withFallback["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
+        #expect(projectNodeOnly["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
+    }
+
+    @Test
+    func projectWrapperDoesNotPutTheRepositoryOnTheLaunchPath() {
+        let environment = RunLaunchEnvironment.augmenting(
+            ["PATH": "/usr/bin:/bin"],
+            executableURL: projectURL.appendingPathComponent("mvnw"),
+            nodeCandidates: [],
+            projectURL: projectURL
+        )
+
+        #expect(environment["PATH"] == "/usr/bin:/bin")
+    }
+
+    @Test
+    func existingEntriesKeepTheirOrderAndAreNotDuplicated() {
+        let environment = RunLaunchEnvironment.augmenting(
+            ["PATH": "/opt/homebrew/bin:/usr/bin:/bin"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [
+                RuntimeToolCandidate(
+                    command: "node",
+                    executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/node"),
+                    source: .homebrew
+                )
+            ],
+            projectURL: projectURL
+        )
+
+        #expect(environment["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
+    }
+
+    @Test
+    func missingPathIsCreatedFromTheResolvedDirectories() {
+        let environment = RunLaunchEnvironment.augmenting(
+            ["HOME": "/Users/fixture"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [],
+            projectURL: projectURL
+        )
+
+        #expect(environment["PATH"] == "/opt/homebrew/bin")
+        #expect(environment["HOME"] == "/Users/fixture")
+    }
+
+    @Test
+    @MainActor
+    func resolverAppliesTheLaunchDirectoriesToCommandsResolvedFromPath() throws {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("lithe-run-launch-path-\(UUID().uuidString)", isDirectory: true)
+        let project = root.appendingPathComponent("project", isDirectory: true)
+        let tools = root.appendingPathComponent("tools/bin", isDirectory: true)
+        try FileManager.default.createDirectory(at: project, withIntermediateDirectories: true)
+        try FileManager.default.createDirectory(at: tools, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+
+        let pnpm = tools.appendingPathComponent("pnpm")
+        try Data("#!/bin/sh\n".utf8).write(to: pnpm)
+        try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: pnpm.path)
+
+        let service = ProjectRuntimeService(
+            runtimeLocator: RunLaunchPathRuntimeLocator(
+                environmentValues: ["PATH": "\(tools.path):/usr/bin:/bin"],
+                executablePath: pnpm.path
+            ),
+            store: RunLaunchPathStore(),
+            toolDiscovery: RunLaunchPathToolDiscovery(node: URL(fileURLWithPath: "/fixture-node/bin/node"))
+        )
+        let plan = SharedLaunchPlan(
+            executable: .command("pnpm"),
+            arguments: ["run", "clean"],
+            workingDirectory: "."
+        )
+
+        let resolved = try RunExecutableResolver(runtimeService: service)
+            .resolve(plan, projectURL: project, options: RunOptions())
+
+        #expect(resolved.executableURL == pnpm)
+        #expect(resolved.environment["PATH"] == "/fixture-node/bin:\(tools.path):/usr/bin:/bin")
+    }
+}
+
+private struct RunLaunchPathRuntimeLocator: RuntimeLocator {
+    let environmentValues: [String: String]
+    let executablePath: String
+
+    func environment() -> [String: String] { environmentValues }
+    func discover() -> RuntimeDiscoveryResult {
+        RuntimeDiscoveryResult(javaRuntimes: [], mavenRuntimes: [])
+    }
+    func validJavaHome(path: String) -> URL? { nil }
+    func javaRuntime(at homeURL: URL) -> JavaRuntimeCandidate? { nil }
+    func isExecutable(at url: URL) -> Bool { url.standardizedFileURL.path == executablePath }
+    func systemMavenExecutable() -> URL? { nil }
+    func mavenExecutable(forHomePath path: String) -> URL? { nil }
+    func mavenRuntime(at executableURL: URL) -> MavenRuntimeCandidate? { nil }
+}
+
+private final class RunLaunchPathStore: KeyValueStore {
+    private var values: [String: Any] = [:]
+
+    func data(forKey key: String) -> Data? { values[key] as? Data }
+    func object(forKey key: String) -> Any? { values[key] }
+    func string(forKey key: String) -> String? { values[key] as? String }
+    func stringArray(forKey key: String) -> [String]? { values[key] as? [String] }
+    func set(_ value: Any?, forKey key: String) { values[key] = value }
+}
+
+private struct RunLaunchPathToolDiscovery: RuntimeToolDiscovery {
+    let node: URL
+
+    func candidates(for command: String, projectURL: URL?, environment: [String: String]) -> [RuntimeToolCandidate] {
+        guard command == "node" else { return [] }
+        return [
+            RuntimeToolCandidate(command: "node", executableURL: node, source: .environment)
+        ]
+    }
+
+    func guidance(
+        for command: String,
+        projectURL: URL?,
+        environment: [String: String]
+    ) -> RuntimeToolGuidance {
+        DefaultRuntimeToolDiscovery().guidance(
+            for: command,
+            projectURL: projectURL,
+            environment: environment
+        )
+    }
+}
diff --git a/shared/platform-feature-matrix/features/run-node-launch-path.json b/shared/platform-feature-matrix/features/run-node-launch-path.json
new file mode 100644
index 0000000000..281c34ec15
--- /dev/null
+++ b/shared/platform-feature-matrix/features/run-node-launch-path.json
@@ -0,0 +1,25 @@
+{
+  "id": "run-node-launch-path",
+  "area": "运行与调试",
+  "group": "运行配置",
+  "capability": "Node 生态运行脚本的启动 PATH",
+  "macos": {
+    "evidence": [
+      "macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift",
+      "macos/Sources/Lithe/Services/Java/RunExecutableResolver.swift",
+      "macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift"
+    ],
+    "implementationStatus": "implemented",
+    "verificationStatus": "pending"
+  },
+  "windows": {
+    "evidence": [
+      "windows/tauri/src-tauri/src/run.rs"
+    ],
+    "implementationStatus": "implemented",
+    "verificationStatus": "pending"
+  },
+  "owner": "Run",
+  "verification": "从 Finder 启动的 Lithe 打开 pnpm 或 npm 项目，在运行工具窗口执行 package.json 脚本（例如 `pnpm run clean`），确认不再出现 `env: node: No such file or directory`，脚本内部再调用 node 或 npm 仍解析到同一套工具；项目 `.lithe` 自带的 node 不会进入子进程 PATH。macOS 由 RunLaunchEnvironmentTests 覆盖补齐、去重、顺序与项目内排除；Windows 由 run.rs 的 prepend_runtime_paths 路径覆盖。",
+  "notes": "两端都在启动前把已选运行时目录和解析出的可执行文件目录放到 PATH 前部；项目根目录与项目内解释器不参与，避免仓库文件劫持后续系统命令。"
+}

From f0bda00c1b58009b3ee67fd60a1a401fdec73264 Mon Sep 17 00:00:00 2001
From: lick <2188718831@qq.com>
Date: Sun, 25 Oct 2026 04:07:19 -0700
Subject: [PATCH 2/2] =?UTF-8?q?fix(macos):=20=E4=BF=9D=E7=95=99=E8=BF=90?=
 =?UTF-8?q?=E8=A1=8C=E9=85=8D=E7=BD=AE=E6=98=BE=E5=BC=8F=20PATH=20?=
 =?UTF-8?q?=E4=BC=98=E5=85=88=E7=BA=A7=EF=BC=8C=E8=A1=A5=E9=BD=90=20Node?=
 =?UTF-8?q?=20=E5=B7=A5=E5=85=B7=E9=93=BE=E8=A6=86=E7=9B=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 启动 PATH 改为追加：原有条目（含运行配置显式 PATH）保持优先级，自动发现
  的 node 与启动器目录追加在后；Finder 启动时 PATH 本就没有 node，追加同样生效。
- 新增「显式 PATH 保持优先级」与 .toolchain("project-node") 接线测试，共 8 例。
- 修正 Agent Note 与特性矩阵中「两端都排除项目目录」「与 Windows 一致」的不准确
  表述，补充 fnm multishell 等发现范围限制与 Windows 排序差异。
---
 ...0-25-run-launch-path-for-node-launchers.md | 34 +++++++-----
 .../Services/Java/RunLaunchEnvironment.swift  | 21 ++++----
 .../RunLaunchEnvironmentTests.swift           | 52 +++++++++++++++++--
 .../features/run-node-launch-path.json        |  2 +-
 4 files changed, 81 insertions(+), 28 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md b/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
index 1c51a4bb83..57f36d7799 100644
--- a/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
+++ b/.agents/notes/implemented/bug-fix/2026-10-25-run-launch-path-for-node-launchers.md
@@ -45,21 +45,24 @@ Node 版本管理器目录的额外探测；这份探测结果从来没有进入
 - 组合点放在 `RunExecutableResolver.resolve`：`.toolchain` 和 `.command` 两条
   分支都会经过它。只补运行启动环境，不改 `ProjectRuntimeService.processEnvironment`
   本身，避免终端、调试适配器、语言服务器被顺带改掉。
-- 目录顺序：`node` 目录在最前，其次是被解析出的可执行文件目录，之后才是原有
-  `PATH`。这样 `env node` 拿到的是 Lithe 实际选中的解释器；按小写比较去重，因为
-  默认的 APFS 卷大小写不敏感。
+- 目录顺序：原有 `PATH` 条目保持原位置和优先级，`node` 目录与被解析出的可执行
+  文件目录补在后面，按小写比较去重（默认的 APFS 卷大小写不敏感）。运行配置允许
+  用户显式设置 `PATH` 来固定自己的工具链，追加而不是前置才能尊重这份配置；从
+  Finder 启动时 `PATH` 里本来没有 `node`，追加同样能被 `env` 找到。
 - 安全边界：`RuntimeToolCandidate.source == .project` 的 `node` 不注入；可执行
   文件位于项目根内时（例如 `mvnw`、`gradlew`），它所在的目录也不注入。仓库内容
   不可信，把项目根放到 `PATH` 前部会让仓库里的同名文件劫持脚本后续调用的系统
   命令。这与语言服务器侧 `languageToolProcessEnvironment` 的既有规则一致。
-- Windows 的运行入口 `prepend_runtime_paths` 早就在做“运行时目录 + 可执行文件
-  目录前置”。macOS 这次补上同类行为，两个产品的启动环境语义对齐。
+- Windows 的运行入口 `prepend_runtime_paths` 早就在把“运行时目录 + 可执行文件
+  目录”加进 `PATH`（Windows 是前置）。macOS 这次补上同类能力，但使用追加顺序，
+  因为当前实现里没有和 Windows 运行时映射等价的可信来源，追加更不容易覆盖用户
+  的显式配置。
 
 正确做法：
 
 ```text
-pnpm 在 /opt/homebrew/bin，node 在 fnm 的 multishell 目录
-子进程 PATH = <fnm 的 node 目录>:<pnpm 目录>:<原有 PATH>
+pnpm 在 /opt/homebrew/bin，node 在 fnm 的默认别名目录
+子进程 PATH = <原有 PATH>:<fnm 的 node 目录>:<pnpm 目录>
 ```
 
 不要这样做：
@@ -86,19 +89,24 @@ pnpm 在 /opt/homebrew/bin，node 在 fnm 的 multishell 目录
 ## 后果
 
 - 收益：从 Finder 启动也能运行 `pnpm` / `npm` / `yarn` / `tsx` 等脚本；脚本内部
-  再调用 `node` / `npm` 也能解析到同一套工具；与 Windows 行为一致。
+  再调用 `node` / `npm` 也能解析到同一套工具；与 Windows 的启动环境方向一致。
 - 代价：每次运行解析多一次 `node` 候选发现（PATH 和各版本管理器目录的只读
-  探测），单次毫秒级；子进程 `PATH` 的内容和顺序与 0.6.2 不同。
+  探测），单次毫秒级；子进程 `PATH` 的内容和顺序与 0.6.2 不同。macOS 与 Windows
+  的排序不同：Windows 前置，macOS 追加；macOS 还会排除项目内的 wrapper 目录，
+  Windows 不排除。
 - 例外：系统里完全没有 `node` 时不注入任何目录，失败表现与修复前相同；项目里
-  只有自带 `node` 时也不注入，仍然按系统环境处理。
+  只有自带 `node` 时也不注入，仍然按系统环境处理。只能覆盖 Lithe 发现器已知的
+  安装位置（PATH、Homebrew、volta、fnm 默认别名、nvm 版本目录）；fnm 为单个
+  shell 创建的临时 multishell 目录不在发现范围内，用户没有默认别名时仍会缺
+  `node`。
 
 ## 验证
 
 - `./.agents/skills/write-stable-tests/scripts/verify-test-stability.sh`
 - `./.agents/skills/write-stable-tests/scripts/test-stability-macos.sh -- --filter RunLaunchEnvironmentTests`
-  覆盖六个场景：GUI 最小 PATH 下补齐 node 与启动器目录、项目内 node 被排除、
-  项目 wrapper 不把仓库根放进 PATH、已有目录去重且保持顺序、缺失 PATH 时新建、
-  resolver 对 `.command` 的实际接线。
+  覆盖八个场景：GUI 最小 PATH 下补齐 node 与启动器目录、项目内 node 被排除、
+  项目 wrapper 不把仓库根放进 PATH、已有目录去重且保持顺序、显式 PATH 保持优先级、
+  缺失 PATH 时新建、resolver 对 `.command` 与 `.toolchain("project-node")` 的接线。
 - `./scripts/verify-service-boundaries.sh`
 - 失败形态的手工复现：`env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin /usr/bin/env node --version`
   返回 `env: node: No such file or directory`；把 node 目录加进 `PATH` 后恢复。
diff --git a/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift b/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
index 0fb7386c22..81957a7deb 100644
--- a/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
+++ b/macos/Sources/Lithe/Services/Java/RunLaunchEnvironment.swift
@@ -17,10 +17,13 @@ import LitheCoreContracts
 /// executable's directory in `windows/tauri/src-tauri/src/run.rs`; this keeps
 /// both products' launch environments equivalent.
 enum RunLaunchEnvironment {
-    /// Prepends the discovered interpreter directory and the resolved
-    /// executable's directory, keeping the remaining entries in their original
-    /// order. Entries are deduplicated case-insensitively because the default
-    /// macOS volume is case-insensitive.
+    /// Appends the discovered interpreter directory and the resolved
+    /// executable's directory to the existing entries, which keep their
+    /// priority: a run configuration that sets `PATH` may pin its own
+    /// toolchain, and the default Finder environment contains no `node`, so
+    /// the appended directories are reached in both cases. Entries are
+    /// deduplicated case-insensitively because the default macOS volume is
+    /// case-insensitive.
     ///
     /// Project-owned interpreters and launchers are never promoted: an
     /// untrusted repository must not capture the interpreter of every script
@@ -32,23 +35,23 @@ enum RunLaunchEnvironment {
         nodeCandidates: [RuntimeToolCandidate],
         projectURL: URL
     ) -> [String: String] {
-        var leadingDirectories: [String] = []
+        var resolvedDirectories: [String] = []
         if let node = nodeCandidates.first(where: {
             $0.source != .project && !isInsideProject($0.executableURL, projectURL: projectURL)
         }) {
-            leadingDirectories.append(node.executableURL.deletingLastPathComponent().path)
+            resolvedDirectories.append(node.executableURL.deletingLastPathComponent().path)
         }
         if !isInsideProject(executableURL, projectURL: projectURL) {
-            leadingDirectories.append(executableURL.deletingLastPathComponent().path)
+            resolvedDirectories.append(executableURL.deletingLastPathComponent().path)
         }
-        guard !leadingDirectories.isEmpty else { return environment }
+        guard !resolvedDirectories.isEmpty else { return environment }
 
         let existingDirectories = (environment["PATH"] ?? "")
             .split(separator: ":")
             .map(String.init)
             .filter { !$0.isEmpty }
         var seen = Set<String>()
-        let directories = (leadingDirectories + existingDirectories).filter {
+        let directories = (existingDirectories + resolvedDirectories).filter {
             seen.insert($0.lowercased()).inserted
         }
 
diff --git a/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift b/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
index 85da9d5c3d..ff587142b7 100644
--- a/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
+++ b/macos/Tests/LitheTests/RunLaunchEnvironmentTests.swift
@@ -19,14 +19,14 @@ struct RunLaunchEnvironmentTests {
             nodeCandidates: [
                 RuntimeToolCandidate(
                     command: "node",
-                    executableURL: URL(fileURLWithPath: "/Users/fixture/.local/state/fnm_multishells/1/bin/node"),
+                    executableURL: URL(fileURLWithPath: "/Users/fixture/.local/share/fnm/aliases/default/bin/node"),
                     source: .environment
                 )
             ],
             projectURL: projectURL
         )
 
-        #expect(environment["PATH"] == "/Users/fixture/.local/state/fnm_multishells/1/bin:/opt/homebrew/bin:/usr/bin:/bin")
+        #expect(environment["PATH"] == "/usr/bin:/bin:/Users/fixture/.local/share/fnm/aliases/default/bin:/opt/homebrew/bin")
     }
 
     @Test
@@ -55,8 +55,8 @@ struct RunLaunchEnvironmentTests {
             projectURL: projectURL
         )
 
-        #expect(withFallback["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
-        #expect(projectNodeOnly["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
+        #expect(withFallback["PATH"] == "/usr/bin:/bin:/opt/homebrew/bin")
+        #expect(projectNodeOnly["PATH"] == "/usr/bin:/bin:/opt/homebrew/bin")
     }
 
     @Test
@@ -89,6 +89,24 @@ struct RunLaunchEnvironmentTests {
         #expect(environment["PATH"] == "/opt/homebrew/bin:/usr/bin:/bin")
     }
 
+    @Test
+    func explicitPathEntriesKeepTheirPriority() {
+        let environment = RunLaunchEnvironment.augmenting(
+            ["PATH": "/custom/node/bin:/usr/bin:/bin"],
+            executableURL: URL(fileURLWithPath: "/opt/homebrew/bin/pnpm"),
+            nodeCandidates: [
+                RuntimeToolCandidate(
+                    command: "node",
+                    executableURL: URL(fileURLWithPath: "/fixture-node/bin/node"),
+                    source: .environment
+                )
+            ],
+            projectURL: projectURL
+        )
+
+        #expect(environment["PATH"] == "/custom/node/bin:/usr/bin:/bin:/fixture-node/bin:/opt/homebrew/bin")
+    }
+
     @Test
     func missingPathIsCreatedFromTheResolvedDirectories() {
         let environment = RunLaunchEnvironment.augmenting(
@@ -135,7 +153,31 @@ struct RunLaunchEnvironmentTests {
             .resolve(plan, projectURL: project, options: RunOptions())
 
         #expect(resolved.executableURL == pnpm)
-        #expect(resolved.environment["PATH"] == "/fixture-node/bin:\(tools.path):/usr/bin:/bin")
+        #expect(resolved.environment["PATH"] == "\(tools.path):/usr/bin:/bin:/fixture-node/bin")
+    }
+
+    @Test
+    @MainActor
+    func resolverAppliesTheInterpreterDirectoryToNodeToolchains() throws {
+        let service = ProjectRuntimeService(
+            runtimeLocator: RunLaunchPathRuntimeLocator(
+                environmentValues: ["PATH": "/usr/bin:/bin"],
+                executablePath: "/unused"
+            ),
+            store: RunLaunchPathStore(),
+            toolDiscovery: RunLaunchPathToolDiscovery(node: URL(fileURLWithPath: "/fixture-node/bin/node"))
+        )
+        let plan = SharedLaunchPlan(
+            executable: .toolchain("project-node"),
+            arguments: ["script.js"],
+            workingDirectory: "."
+        )
+
+        let resolved = try RunExecutableResolver(runtimeService: service)
+            .resolve(plan, projectURL: projectURL, options: RunOptions())
+
+        #expect(resolved.executableURL.path == "/fixture-node/bin/node")
+        #expect(resolved.environment["PATH"] == "/usr/bin:/bin:/fixture-node/bin")
     }
 }
 
diff --git a/shared/platform-feature-matrix/features/run-node-launch-path.json b/shared/platform-feature-matrix/features/run-node-launch-path.json
index 281c34ec15..4882ea3782 100644
--- a/shared/platform-feature-matrix/features/run-node-launch-path.json
+++ b/shared/platform-feature-matrix/features/run-node-launch-path.json
@@ -21,5 +21,5 @@
   },
   "owner": "Run",
   "verification": "从 Finder 启动的 Lithe 打开 pnpm 或 npm 项目，在运行工具窗口执行 package.json 脚本（例如 `pnpm run clean`），确认不再出现 `env: node: No such file or directory`，脚本内部再调用 node 或 npm 仍解析到同一套工具；项目 `.lithe` 自带的 node 不会进入子进程 PATH。macOS 由 RunLaunchEnvironmentTests 覆盖补齐、去重、顺序与项目内排除；Windows 由 run.rs 的 prepend_runtime_paths 路径覆盖。",
-  "notes": "两端都在启动前把已选运行时目录和解析出的可执行文件目录放到 PATH 前部；项目根目录与项目内解释器不参与，避免仓库文件劫持后续系统命令。"
+  "notes": "两端都会把已选运行时目录和解析出的可执行文件目录加入 PATH；Windows 前置，macOS 追加以保留运行配置里的显式 PATH 优先级，并排除项目根目录与项目内解释器。"
 }