magic-agent 2.6.0 → 2.6.3

package/internal/agent/dsh_caps_cache_test.go

@@ -0,0 +1,184 @@
+package agent
+
+// dsh_caps_cache_test.go - dsh 能力探测的**磁盘**缓存（2026-10-26）。
+//
+// 为什么单测必须钉住这件事：dshCapsCache 是进程内 sync.Map，而 magic-agent
+// 每轮 ask 都是新进程 —— 没有磁盘那层，「一进程一次」实际是「一轮一次」，
+// 每轮续接白等 7~9 秒（实测 dsh 0.2.0-rc.2 的 --profile headless --help）。
+// 这类「看着有缓存、其实每轮都在重探」的回归用眼睛看不出来，只能靠计数。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeDshCapsBin 造一个假 dsh：把每次被调用的参数记进 calls 文件，并回 help 文本。
+//
+// helpPatch=false 模拟老版本（顶层 --help 里没有 --patch）。
+func fakeDshCapsBin(t *testing.T, helpPatch bool) (bin, callsPath string) {
+	t.Helper()
+	dir := t.TempDir()
+	bin = filepath.Join(dir, "dsh")
+	callsPath = filepath.Join(dir, "calls.txt")
+	patchLine := ""
+	if helpPatch {
+		patchLine = `echo "  --patch <path>   apply a patch file"`
+	}
+	script := `#!/bin/sh
+echo "$@" >> ` + callsPath + `
+case "$1" in
+  --help)
+    echo "Usage: dsh [--profile <name>] [--patch <path>] <prompt>"
+    ` + patchLine + `
+    ;;
+  --profile)
+    echo "Usage: dsh-headless [--session-id <id>] [--json] <prompt>"
+    ;;
+esac
+exit 0
+`
+	if err := os.WriteFile(bin, []byte(script), 0o755); err != nil {
+		t.Fatalf("write fake dsh: %v", err)
+	}
+	return bin, callsPath
+}
+
+// countCalls 读假 dsh 被调用的次数。
+func countCalls(t *testing.T, callsPath string) int {
+	t.Helper()
+	b, err := os.ReadFile(callsPath)
+	if err != nil {
+		return 0
+	}
+	return len(strings.Split(strings.TrimSpace(string(b)), "\n"))
+}
+
+// resetDshCapsCache 清掉进程内缓存（每个用例都从「冷进程」起）。
+func resetDshCapsCache() {
+	dshCapsCache = sync.Map{}
+}
+
+// TestDshCapsDiskCacheAvoidsSecondProbe 第二轮（新进程语义）不该再起子进程。
+//
+// 这是本改动的**核心断言**：把进程内缓存清掉再问一次，如果还是去起进程，
+// 说明磁盘那层没生效 —— 用户侧表现就是每轮续接多等 7~9 秒。
+func TestDshCapsDiskCacheAvoidsSecondProbe(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	bin, callsPath := fakeDshCapsBin(t, true)
+	resetDshCapsCache()
+
+	ctx := context.Background()
+	first := dshHeadlessCapabilities(ctx, bin)
+	if got := countCalls(t, callsPath); got != 2 {
+		t.Fatalf("首轮应探测 2 次（headless help + 顶层 help），实际 %d 次", got)
+	}
+	if !first.SessionID || !first.JSON || !first.Patch {
+		t.Fatalf("首轮 caps = %+v，期望三项都为 true", first)
+	}
+
+	// 模拟「下一个 core 进程」：进程内缓存全清，只剩磁盘。
+	resetDshCapsCache()
+	second := dshHeadlessCapabilities(ctx, bin)
+	if got := countCalls(t, callsPath); got != 2 {
+		t.Errorf("第二轮不该再起子进程，调用次数仍是 %d（磁盘缓存没命中）", got)
+	}
+	if second != first {
+		t.Errorf("磁盘缓存读回 %+v，与首次探测 %+v 不一致", second, first)
+	}
+}
+
+// TestDshCapsDiskCacheInvalidatedByBinChange dsh 换了二进制（指纹变）就必须重探。
+//
+// 反过来的风险更严重：升级 dsh 后还拿老结论，续接会被判成「不支持 --session-id」
+// 而直接报错，或者更糟 —— 静默按老形态拼参数。
+func TestDshCapsDiskCacheInvalidatedByBinChange(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	// 第一版：顶层 --help 里有 --patch。
+	bin, callsPath := fakeDshCapsBin(t, true)
+	resetDshCapsCache()
+	if !dshHeadlessCapabilities(context.Background(), bin).Patch {
+		t.Fatal("第一版应探测到 --patch")
+	}
+
+	// 换内容并确保 mtime 确实变化（同一纳秒内重写会让指纹看不出差别）。
+	time.Sleep(20 * time.Millisecond)
+	if err := os.WriteFile(bin, []byte(`#!/bin/sh
+echo "$@" >> `+callsPath+`
+case "$1" in
+  --help) echo "Usage: dsh [--profile <name>] <prompt>" ;;
+  --profile) echo "Usage: dsh-headless [--session-id <id>] [--json] <prompt>" ;;
+esac
+exit 0
+`), 0o755); err != nil {
+		t.Fatalf("rewrite fake dsh: %v", err)
+	}
+	before := countCalls(t, callsPath)
+	resetDshCapsCache()
+
+	caps := dshHeadlessCapabilities(context.Background(), bin)
+	if countCalls(t, callsPath) == before {
+		t.Error("二进制变了却没重探（指纹判据失效）")
+	}
+	if caps.Patch {
+		t.Error("新版本没有 --patch，重探后不该还是 true")
+	}
+	if !caps.SessionID || !caps.JSON {
+		t.Errorf("caps = %+v，--session-id / --json 应仍为 true", caps)
+	}
+}
+
+// TestDshCapsCanceledProbeNotCached 探测被取消时不落盘。
+//
+// 为什么值得一条用例：探测中途超时只拿到半截输出，按「探测不到不等于不支持」
+// 的约定会保留乐观默认值。那本来是对的 —— 但**不能把它写进磁盘**，否则
+// 一次抖动会让后续每一轮都跳过真正的探测。
+func TestDshCapsCanceledProbeNotCached(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	dir := t.TempDir()
+	bin := filepath.Join(dir, "dsh-slow")
+	// 故意慢：探测的 ctx 已经取消了，这个脚本还在睡。
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\nsleep 5\nexit 0\n"), 0o755); err != nil {
+		t.Fatalf("write slow fake dsh: %v", err)
+	}
+	resetDshCapsCache()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // 进函数时就是取消态
+	_ = dshHeadlessCapabilities(ctx, bin)
+
+	if b, err := os.ReadFile(cachePath); err == nil && len(b) > 0 {
+		t.Errorf("取消态下不该落盘，却写入了：%s", string(b))
+	}
+}
+
+// TestDshBinFingerprintChangesWithSize 指纹同时看 mtime 和大小。
+func TestDshBinFingerprintChangesWithSize(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "f")
+	if err := os.WriteFile(p, []byte("a"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	fp1 := dshBinFingerprint(p)
+	if fp1 == "" {
+		t.Fatal("指纹为空")
+	}
+	if err := os.WriteFile(p, []byte("abcdef"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if fp2 := dshBinFingerprint(p); fp2 == fp1 {
+		t.Error("文件大小变了，指纹却没变")
+	}
+	if got := dshBinFingerprint(filepath.Join(t.TempDir(), "missing")); got != "" {
+		t.Errorf("不存在的文件指纹应为空，得到 %q", got)
+	}
+}

package/internal/agent/dsh_resume.go

@@ -164,21 +164,154 @@ type dshHeadlessCaps struct {
 	Patch bool
 }
 
-var dshCapsCache sync.Map // bin → dshHeadlessCaps
+var dshCapsCache sync.Map // 缓存 key → dshHeadlessCaps
 
-// dshHeadlessCapabilities 探测这台 dsh 支持哪些 headless flag（按 bin 路径缓存）。
+// dshCapsCachePath 能力探测结果的**磁盘**缓存（2026-10-26）。
+//
+// 为什么必须有磁盘这一层：dshCapsCache 是进程内的 sync.Map，而 magic-agent 每次
+// ask 都是**新进程**（客户端 spawn 一个 core 跑一轮）。于是「一进程一次」实际是
+// 「一轮一次」—— 每轮续接都要重跑两条 --help。
+//
+// 实测代价（2026-10-26，dsh 0.2.0-rc.2）：
+//
+//	dsh --profile headless --help   7.09s / 9.01s / 7.66s（本机环境变量齐全时）
+//	                               1.31s（干净 env）
+//	dsh --help                      0.28s
+//
+// 也就是说**每一轮续接白等 7~9 秒**，而且这段是在 turn/start 之前，用户看到的就是
+// 「发出去半天没动静」。本机实测一轮的 7.09s 空窗与此**完全吻合**。
+//
+// 缓存失效判据是 dsh 二进制的指纹（mtime + size）：升级/替换 dsh 后指纹变，自动重探。
+// 不用 `--version` 取版本号当 key —— 那要额外起一次进程（0.3s），而 stat 是零成本，
+// 且「换了二进制」正是唯一需要重探的时机。
+func dshCapsCachePath() string {
+	if p := strings.TrimSpace(os.Getenv("MAGIC_AGENT_DSH_CAPS_CACHE")); p != "" {
+		return p
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-agent", "dsh-caps.json")
+}
+
+// dshBinFingerprint dsh 二进制的身份（mtime 纳秒 + 大小）。取不到 → 空串（不缓存）。
+func dshBinFingerprint(bin string) string {
+	st, err := os.Stat(bin)
+	if err != nil || st.IsDir() {
+		return ""
+	}
+	return fmt.Sprintf("%d-%d", st.ModTime().UnixNano(), st.Size())
+}
+
+// dshCapsDiskEntry 磁盘缓存的一条记录。
+type dshCapsDiskEntry struct {
+	Bin         string `json:"bin"`
+	Fingerprint string `json:"fingerprint"`
+	SessionID   bool   `json:"sessionId"`
+	JSON        bool   `json:"json"`
+	Patch       bool   `json:"patch"`
+	ProbedAt    string `json:"probedAt,omitempty"`
+}
+
+// dshCapsDiskFile 磁盘缓存文件（按 bin 路径分条，多份 dsh 并存也各自有效）。
+type dshCapsDiskFile struct {
+	Version int                         `json:"version"`
+	Entries map[string]dshCapsDiskEntry `json:"entries"`
+}
+
+func dshLoadCapsFromDisk(bin, fp string) (dshHeadlessCaps, bool) {
+	path := dshCapsCachePath()
+	if path == "" || fp == "" {
+		return dshHeadlessCaps{}, false
+	}
+	b, err := os.ReadFile(path)
+	if err != nil || len(b) == 0 {
+		return dshHeadlessCaps{}, false
+	}
+	var f dshCapsDiskFile
+	if err := json.Unmarshal(b, &f); err != nil {
+		return dshHeadlessCaps{}, false
+	}
+	e, ok := f.Entries[bin]
+	if !ok || e.Fingerprint != fp {
+		return dshHeadlessCaps{}, false
+	}
+	return dshHeadlessCaps{SessionID: e.SessionID, JSON: e.JSON, Patch: e.Patch}, true
+}
+
+// dshStoreCapsToDisk 写回一条。失败静默 —— 缓存只是提速手段，写不动不能让调用失败。
+func dshStoreCapsToDisk(bin, fp string, caps dshHeadlessCaps) {
+	path := dshCapsCachePath()
+	if path == "" || fp == "" {
+		return
+	}
+	var f dshCapsDiskFile
+	if b, err := os.ReadFile(path); err == nil && len(b) > 0 {
+		_ = json.Unmarshal(b, &f)
+	}
+	if f.Entries == nil {
+		f.Entries = map[string]dshCapsDiskEntry{}
+	}
+	f.Version = 1
+	/* 顺手清掉**已经不存在的二进制**留下的条目。
+	   不清理的话这个文件会只增不减 —— 测试里的临时 dsh、卸载过的旧版本、换过的
+	   node 版本路径都会一直留着（实测跑一轮全量测试就塞进十几条 /var/folders 下的
+	   临时路径）。每条都要 stat 一次，所以放在写回时才做，读路径上不碰。 */
+	for k := range f.Entries {
+		if strings.TrimSpace(k) == "" {
+			delete(f.Entries, k)
+			continue
+		}
+		if st, err := os.Stat(k); err != nil || st.IsDir() {
+			delete(f.Entries, k)
+		}
+	}
+	f.Entries[bin] = dshCapsDiskEntry{
+		Bin:         bin,
+		Fingerprint: fp,
+		SessionID:   caps.SessionID,
+		JSON:        caps.JSON,
+		Patch:       caps.Patch,
+		ProbedAt:    time.Now().Format(time.RFC3339),
+	}
+	if dir := filepath.Dir(path); dir != "" {
+		_ = os.MkdirAll(dir, 0o700)
+	}
+	out, err := json.MarshalIndent(f, "", "  ")
+	if err != nil {
+		return
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, append(out, '\n'), 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, path)
+}
+
+// dshHeadlessCapabilities 探测这台 dsh 支持哪些 headless flag。
+//
+// 三级缓存：进程内 sync.Map → 磁盘（按二进制指纹校验）→ 真起进程探。
+// 见 dshCapsCachePath 的注释：没有磁盘这层，等于每轮续接白等 7~9 秒。
 //
 // 为什么必须探测：dsh 启动器在**第一个它不认识的 token 处结束**解析，剩下的都当
 // app 参数交给 headless —— 老版本不认这俩 flag 时，它们会被拼进**任务文本**
-// （静默改写提示词），比直接报错难查得多。探测代价约一次 `--help`，一进程一次。
+// （静默改写提示词），比直接报错难查得多。
 //
 // ⚠️ 只有在输出**确实是 headless 的 help**（同时含 "Usage:" 与 "--profile"）时才据它判断；
 // 否则（--help 跑不起来、被包装脚本吞掉、输出被截断）一律按「都支持」处理 ——
 // 「探测不到」不等于「不支持」，宁可让现代 dsh 正常工作，也不因一次探测抖动把续接判死。
 func dshHeadlessCapabilities(ctx context.Context, bin string) dshHeadlessCaps {
-	if v, ok := dshCapsCache.Load(bin); ok {
+	fp := dshBinFingerprint(bin)
+	key := bin + "|" + fp
+	if v, ok := dshCapsCache.Load(key); ok {
 		return v.(dshHeadlessCaps)
 	}
+	// 磁盘命中：连一次子进程都不用起。
+	if caps, ok := dshLoadCapsFromDisk(bin, fp); ok {
+		dshCapsCache.Store(key, caps)
+		return caps
+	}
 	caps := dshHeadlessCaps{SessionID: true, JSON: true, Patch: true}
 	if stdout, stderr, err := runCLI(ctx, bin, "--profile", "headless", "--help"); err == nil {
 		help := stdout + stderr
@@ -195,7 +328,13 @@ func dshHeadlessCapabilities(ctx context.Context, bin string) dshHeadlessCaps {
 			caps.Patch = strings.Contains(help, "--patch")
 		}
 	}
-	dshCapsCache.Store(bin, caps)
+	// ⚠️ 探测**中途被取消 / 超时**时不落盘：那两秒可能连 help 都没跑完，
+	// 存下去等于把「没探到」永久固化成「都支持」—— 后续每轮都照着错的判断走，
+	// 而用户再也不会遇到一次会纠正它的探测。落盘的必须是完整探完的结果。
+	if ctx.Err() == nil && fp != "" {
+		dshStoreCapsToDisk(bin, fp, caps)
+	}
+	dshCapsCache.Store(key, caps)
 	return caps
 }
 

package/internal/agent/env.go

@@ -6,8 +6,10 @@ package agent
 // 「只能属于父进程」的变量。见 childEnvDenylist。
 
 import (
+	"net"
 	"os"
 	"strings"
+	"time"
 )
 
 // serverEnvPrefix 剔除的前缀：父会话内置 HTTP 服务的监听地址。
@@ -98,24 +100,194 @@ var envDenylist = map[string]bool{
 	//   - CODEBUDDY_CONFIG_DIR / CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION /
 	//     CODEBUDDY_SAFE_DELETE_BULK_GUARD —— 宿主配置/沙箱细节，claude/codebuddy
 	//     不需要。
+	// Electron 的「拿 Electron 当 node 跑」开关。宿主应用（WorkBuddy）把它设成 1，
+	// 子进程继承后，任何 Electron 可执行文件都会以 node 模式启动 —— 引擎 CLI 不需要
+	// 这个身份，留着只会把宿主的启动链路带进来（2026-10-26 实测，见下方 NODE_OPTIONS）。
+	"ELECTRON_RUN_AS_NODE": true,
+
 	"CODEBUDDY_MCP_CONFIG":                           true,
 	"CODEBUDDY_CONFIG_DIR":                           true,
 	"CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION": true,
 	"CODEBUDDY_SAFE_DELETE_BULK_GUARD":               true,
 }
 
+// hostNodeShim 判断一条 NODE_OPTIONS 是否是**宿主 Electron 应用**注入的垫片。
+//
+// 2026-10-26 实测：从 WorkBuddy 的终端里重启 magic-client，父进程环境带着
+//
+//	NODE_OPTIONS=--require=".../WorkBuddy.app/Contents/Resources/app.asar.unpacked/
+//	              cli/vendor/shim/node-language-shim.cjs"
+//	ELECTRON_RUN_AS_NODE=1
+//
+// 于是**每一个**引擎子进程（node 系的 dsh/codex/claude，连 llm 的 node 包装）启动时
+// 都被迫加载那个 shim；shim 要去连 WorkBuddy 的 broker，而 broker 只在 WorkBuddy
+// 运行时存在 —— 报 `connect failed: Connection refused`，任务全部 failed。
+// 不是引擎坏了，是继承了一份不属于它的启动垫片。
+//
+// 只认「.asar / WorkBuddy」这两个特征：用户自己设的 `--max-old-space-size` 之类
+// 照常保留，别误伤。
+func hostNodeShim(val string) bool {
+	v := strings.ToLower(val)
+	return strings.Contains(v, ".asar") || strings.Contains(v, "workbuddy")
+}
+
+// hostShimDir 判断 PATH 里的一段是不是宿主 Electron 应用塞进来的「假命令」目录。
+//
+// 2026-10-26 真机实测（比 NODE_OPTIONS 更隐蔽的那个）：从 WorkBuddy 的终端起
+// magic-client，继承到的 PATH **最前面**是
+//
+//	/Applications/WorkBuddy.app/.../cli/vendor/shim/brokered-bin
+//
+// 里面有 29 个被替换掉的基础命令（cat / cp / dd / chmod / 7z …）。命中它们之后，
+// 那个 shell 脚本会 require `node-brokered-fs-shim.cjs`，去连 WorkBuddy 的 broker；
+// broker 只在 WorkBuddy 运行时存在 —— 于是引擎一调 `cat` 就
+// `connect failed: Connection refused`，整条任务 failed。
+//
+// 只认 `.asar` 与 `brokered-bin` 两个特征，用户自己的 PATH 顺序原样保留。
+func hostShimDir(seg string) bool {
+	v := strings.ToLower(seg)
+	return strings.Contains(v, ".asar") || strings.Contains(v, "brokered-bin")
+}
+
+// stripHostShimPath 从 PATH 值里摘掉宿主垫片目录，其余段与顺序不动。
+func stripHostShimPath(val string) string {
+	parts := strings.Split(val, string(os.PathListSeparator))
+	kept := parts[:0]
+	for _, p := range parts {
+		if p == "" || hostShimDir(p) {
+			continue
+		}
+		kept = append(kept, p)
+	}
+	return strings.Join(kept, string(os.PathListSeparator))
+}
+
+// proxyVarNames 参与「死端口」检查的代理变量名。
+//
+// 大小写两套都列：unix 上 HTTP_PROXY 与 http_proxy 是**两个不同的变量**，
+// 而 Node / Go / curl 各读各的（Node 优先小写、Go 优先大写、curl 只读小写）
+// —— 只清一套等于没清。
+//
+// NO_PROXY **不在列**：它是「绕过名单」而不是代理地址，按地址去探测没有意义。
+var proxyVarNames = []string{
+	"HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+	"http_proxy", "https_proxy", "all_proxy",
+}
+
+// proxyProbeTimeout 探测本机代理端口的上限。
+//
+// 回环地址只有两种结局：立刻连上，或立刻 ECONNREFUSED —— 不存在「慢慢超时」。
+// 留 100ms 只为兜个别平台上 SYN 被丢弃的情况，别让探测本身变成新的延迟。
+const proxyProbeTimeout = 100 * time.Millisecond
+
+// loopbackProxyAddr 从一条代理变量值里取出 host:port；**不是本机回环**就返回空。
+//
+// 只认回环是刻意的保守选择：沙箱 / 隧道环境把出网流量转到 127.0.0.1:<会漂移的端口>，
+// 进程启动时拿到的快照一旦过期就是这个状态（见 strippedProxyKeys 的实测数据）。
+// 非回环（公司代理、远程 squid）**一律不碰** —— 那可能只是这一瞬间抖动，清掉会让
+// 本来能出网的引擎彻底断网，代价远大于收益。
+func loopbackProxyAddr(val string) string {
+	v := strings.TrimSpace(val)
+	if v == "" {
+		return ""
+	}
+	if i := strings.Index(v, "://"); i >= 0 { // 去 scheme：http:// https:// socks5://
+		v = v[i+3:]
+	}
+	if i := strings.IndexAny(v, "/?#"); i >= 0 { // 去 path / query
+		v = v[:i]
+	}
+	if i := strings.LastIndexByte(v, '@'); i >= 0 { // 去 user:pass@
+		v = v[i+1:]
+	}
+	host, port, err := net.SplitHostPort(v)
+	if err != nil || port == "" {
+		return ""
+	}
+	host = strings.Trim(host, "[]")
+	if !strings.EqualFold(host, "localhost") {
+		if ip := net.ParseIP(host); ip == nil || !ip.IsLoopback() {
+			return ""
+		}
+	}
+	return net.JoinHostPort(host, port)
+}
+
+// proxyAddrDead 本机 addr 上是否已经没人监听。
+func proxyAddrDead(addr string) bool {
+	c, err := net.DialTimeout("tcp", addr, proxyProbeTimeout)
+	if err != nil {
+		return true
+	}
+	c.Close()
+	return false
+}
+
+// strippedProxyKeys 返回需要**剔除**的代理变量名（可能为空）。
+//
+// 2026-10-26 实测（本机 dsh 0.2.0-rc.2，同一句提示词，各跑两遍）：
+//
+//	代理端口活着  → 首个输出 2.0~2.5s，内容正常
+//	代理端口已死  → 首个输出 **15.4s / 16.7s**，内容是 dsh: TRANSPORT: Connection error.
+//	清掉代理变量  → 首个输出 **2.0s / 2.1s**，内容正常
+//
+// 一次失败的代理连接要白等十几秒才报错 —— 这正是「会话发出去半天没响应」。
+// 而沙箱代理端口随会话漂移（旧会话留下的进程快照必然过期），所以这个状态很常见。
+// 15 秒 vs 至多一次 100ms 的探测，这个取舍没什么可犹豫的。
+//
+// 注意：**只有本机回环地址才会去探**，且同一地址在一次调用里只探一次。
+func strippedProxyKeys() []string {
+	dead := map[string]bool{} // addr → 已确认没人监听
+	var out []string
+	for _, name := range proxyVarNames {
+		addr := loopbackProxyAddr(os.Getenv(name))
+		if addr == "" {
+			continue
+		}
+		v, seen := dead[addr]
+		if !seen {
+			v = proxyAddrDead(addr)
+			dead[addr] = v
+		}
+		if v {
+			out = append(out, name)
+		}
+	}
+	return out
+}
+
 // environ 返回供子 CLI 继承的环境变量（已剔除父进程专属项）。
 func environ() []string {
 	src := os.Environ()
 	out := make([]string, 0, len(src))
+	/* 先算出「指向死端口的本机代理」，循环里直接不继承。
+	   子进程环境里就**不该出现**这个变量 —— 只补空值不行：空值虽然能压下
+	   exec 的「重复 key 取后者」，但环境块里仍留着一条 `HTTP_PROXY=http://...`
+	   的原值，任何「先写入者胜」或自己拼 map 的读取方都还会看到死地址。 */
+	deadProxy := map[string]bool{}
+	for _, k := range strippedProxyKeys() {
+		deadProxy[k] = true
+	}
 	for _, kv := range src {
 		name, _, ok := strings.Cut(kv, "=")
 		if !ok {
 			continue
 		}
-		if envDenied(name) {
+		if envDenied(name) || deadProxy[name] {
 			continue
 		}
+		if name == "NODE_OPTIONS" && hostNodeShim(kv) {
+			continue
+		}
+		/* PATH 不能整条丢（引擎全靠它找 node/python），只摘掉宿主的假命令目录。 */
+		if name == "PATH" {
+			if _, v, ok := strings.Cut(kv, "="); ok {
+				if cleaned := stripHostShimPath(v); cleaned != v {
+					out = append(out, "PATH="+cleaned)
+					continue
+				}
+			}
+		}
 		out = append(out, kv)
 	}
 	return out

package/internal/agent/env_test.go

@@ -9,6 +9,7 @@ package agent
 // 本文件锁定「SERVER__ 前缀必须被剔除」这一行为，防止回归。
 
 import (
+	"net"
 	"os"
 	"strings"
 	"testing"
@@ -146,3 +147,116 @@ func TestEnvDenied(t *testing.T) {
 		}
 	}
 }
+
+// ── 本机代理端口已死时的剔除（2026-10-26）─────────────────────────
+//
+// 背景：沙箱 / 隧道环境把出网流量转到 127.0.0.1:<会漂移的端口>，进程启动时
+// 拿到的快照一旦过期，子 CLI 每次请求都要白等十几秒才报
+// `dsh: TRANSPORT: Connection error.` —— 用户看到的就是「发出去半天没响应」。
+// 实测：代理活着 2.0s、代理已死 15.4s、清掉代理 2.0s。
+
+func TestLoopbackProxyAddr(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"http://127.0.0.1:54107", "127.0.0.1:54107"},
+		{"http://127.0.0.1:54107/", "127.0.0.1:54107"},
+		{"https://127.0.0.1:8080", "127.0.0.1:8080"},
+		{"socks5://127.0.0.1:1080", "127.0.0.1:1080"},
+		{"http://user:pass@127.0.0.1:3128", "127.0.0.1:3128"},
+		{"http://localhost:8080", "localhost:8080"},
+		{"http://[::1]:8080", "[::1]:8080"},
+		{"127.0.0.1:9999", "127.0.0.1:9999"},
+		// 非回环一律返回空：公司代理 / 远程 squid 不能因为一次抖动就断网。
+		{"http://proxy.corp.example:8080", ""},
+		{"http://10.0.0.1:8080", ""},
+		{"", ""},
+		{"   ", ""},
+		{"http://127.0.0.1", ""}, // 没端口
+		{"not a url", ""},
+	}
+	for _, c := range cases {
+		if got := loopbackProxyAddr(c.in); got != c.want {
+			t.Errorf("loopbackProxyAddr(%q) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// 死端口必须从环境块里**消失**（不是补空值：留着原值会让「先写入者胜」的
+// 读取方仍看到死地址）。大小写两套都要处理（Node/Go/curl 各读各的）。
+func TestEnvironStripsDeadLoopbackProxy(t *testing.T) {
+	dead := "http://127.0.0.1:1" // 1 号端口不会有服务
+	for _, k := range []string{"HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"} {
+		t.Setenv(k, dead)
+	}
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if isProxyNameForTest(name) && val == dead {
+			t.Errorf("%s 仍指向死端口：%s", name, kv)
+		}
+	}
+}
+
+// 活着的回环代理必须**原样保留** —— 断掉用户本来能用的代理是更严重的事故。
+func TestEnvironKeepsLiveLoopbackProxy(t *testing.T) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Skipf("无法监听回环端口：%v", err)
+	}
+	defer ln.Close()
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			c.Close()
+		}
+	}()
+	live := "http://" + ln.Addr().String()
+	t.Setenv("HTTP_PROXY", live)
+	t.Setenv("http_proxy", live)
+
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if name == "HTTP_PROXY" || name == "http_proxy" {
+			if val != live {
+				t.Fatalf("%s 本来可用却被改了：want %q, got %q", name, live, val)
+			}
+		}
+	}
+}
+
+// 非回环代理一律不动 —— 哪怕连不上，也可能是这一瞬间抖动。
+func TestEnvironKeepsRemoteProxy(t *testing.T) {
+	remote := "http://proxy.invalid.example:3128"
+	t.Setenv("HTTP_PROXY", remote)
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if name == "HTTP_PROXY" && val != remote {
+			t.Fatalf("非回环代理不该被改：want %q, got %q", remote, val)
+		}
+	}
+}
+
+// NO_PROXY 是绕过名单，不是代理地址，绝不能被当成死代理剔掉。
+func TestEnvironKeepsNoProxy(t *testing.T) {
+	t.Setenv("NO_PROXY", "localhost,127.0.0.1,.internal")
+	found := false
+	for _, kv := range environ() {
+		if kv == "NO_PROXY=localhost,127.0.0.1,.internal" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("NO_PROXY 被误删了")
+	}
+}
+
+// isProxyNameForTest 测试侧的白名单判断（生产侧的白名单在 env.go）。
+func isProxyNameForTest(name string) bool {
+	switch name {
+	case "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+		"http_proxy", "https_proxy", "all_proxy":
+		return true
+	}
+	return false
+}