magic-agent 2.4.3 → 2.6.3

package/internal/client/suggest.go

@@ -15,11 +15,13 @@ package client
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"io"
 	"net/http"
-	"os/exec"
 	"strings"
+	"sync"
 	"time"
 	"unicode/utf8"
 
@@ -41,6 +43,77 @@ const (
 // 2 = 允许「当前会话收尾」与「刚切过去的另一个会话」各一条，超出直接 429。
 var suggestSlots = make(chan struct{}, 2)
 
+// 建议缓存：同一轮问答（user+reply+引擎/模型都相同）的建议只跑一次模型调用。
+// 界面在会话切换 / 重渲染时会重复请求同一轮的建议，没缓存就每次都起一个旁路
+// 引擎进程白烧一次调用（用户 2026-10-24：「会话的建议要有缓存 不能每次都重复跑」）。
+// 只缓存**成功**响应（含空数组——空也是合法结果）；失败不缓存，下次重试。
+const (
+	suggestCacheTTL     = 30 * time.Minute
+	suggestCacheMaxSize = 128
+)
+
+type suggestCacheEntry struct {
+	payload  []byte // 成功响应的 JSON（已保证 Suggestions 非 nil）
+	expireAt time.Time
+	usedAt   time.Time // LRU 淘汰用
+}
+
+var suggestCache = struct {
+	sync.Mutex
+	m map[string]suggestCacheEntry
+}{m: make(map[string]suggestCacheEntry)}
+
+// suggestCacheKey 按完整请求内容算 key：user/reply 一样但换了引擎/模型就分开算。
+func suggestCacheKey(body struct {
+	User           string `json:"user"`
+	Reply          string `json:"reply"`
+	Engine         string `json:"engine"`
+	Model          string `json:"model"`
+	FallbackEngine string `json:"fallbackEngine"`
+	FallbackModel  string `json:"fallbackModel"`
+}) string {
+	h := sha256.Sum256([]byte(strings.Join([]string{
+		body.User, body.Reply, body.Engine, body.Model, body.FallbackEngine, body.FallbackModel,
+	}, "\x00")))
+	return hex.EncodeToString(h[:])
+}
+
+// suggestCacheGet 命中返回响应 JSON；顺带做惰性过期与 LRU 容量控制。
+func suggestCacheGet(key string) ([]byte, bool) {
+	suggestCache.Lock()
+	defer suggestCache.Unlock()
+	e, ok := suggestCache.m[key]
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(e.expireAt) {
+		delete(suggestCache.m, key)
+		return nil, false
+	}
+	e.usedAt = time.Now()
+	suggestCache.m[key] = e
+	return e.payload, true
+}
+
+func suggestCachePut(key string, payload []byte) {
+	suggestCache.Lock()
+	defer suggestCache.Unlock()
+	if len(suggestCache.m) >= suggestCacheMaxSize {
+		// 淘汰最久未用的一条（缓存最多 128 条，线性找足够快）。
+		var oldestKey string
+		var oldest time.Time
+		first := true
+		for k, v := range suggestCache.m {
+			if first || v.usedAt.Before(oldest) {
+				oldestKey, oldest, first = k, v.usedAt, false
+			}
+		}
+		delete(suggestCache.m, oldestKey)
+	}
+	now := time.Now()
+	suggestCache.m[key] = suggestCacheEntry{payload: payload, expireAt: now.Add(suggestCacheTTL), usedAt: now}
+}
+
 // handleSuggest POST /desk/suggest。
 //
 // 请求：{"user":"用户上一句","reply":"本轮回答正文","engine":"可选","model":"可选"}
@@ -55,6 +128,10 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 		Reply  string `json:"reply"`
 		Engine string `json:"engine"`
 		Model  string `json:"model"`
+		// 建议引擎的主备（2026-10-24，只增字段）：主建议引擎失败时先试它，
+		// 再落到 core 内置的 llm 兜底。空 = 老行为。
+		FallbackEngine string `json:"fallbackEngine"`
+		FallbackModel  string `json:"fallbackModel"`
 	}
 	if r.Body != nil {
 		if err := json.NewDecoder(io.LimitReader(r.Body, suggestMaxBody)).Decode(&body); err != nil {
@@ -70,6 +147,14 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	body.User = clipRunes(strings.TrimSpace(body.User), suggestMaxUserRunes)
 	body.Reply = clipRunes(body.Reply, suggestMaxReplyRunes)
 
+	// 同一轮问答的重复请求直接回缓存（切换会话/重渲染会反复要同一轮的建议）。
+	cacheKey := suggestCacheKey(body)
+	if payload, ok := suggestCacheGet(cacheKey); ok {
+		w.Header().Set("X-Suggest-Cache", "hit")
+		writeJSONBytes(w, http.StatusOK, payload)
+		return
+	}
+
 	select {
 	case suggestSlots <- struct{}{}:
 		defer func() { <-suggestSlots }()
@@ -90,7 +175,13 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	if m := strings.TrimSpace(body.Model); m != "" {
 		args = append(args, "-m", m)
 	}
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	if fb := strings.TrimSpace(body.FallbackEngine); fb != "" {
+		args = append(args, "--suggest-fallback-engine", fb)
+		if m := strings.TrimSpace(body.FallbackModel); m != "" {
+			args = append(args, "--suggest-fallback-model", m)
+		}
+	}
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
 	cmd.Stdin = bytes.NewReader(payload)
 	var stdout, stderr bytes.Buffer
 	cmd.Stdout = &stdout
@@ -119,9 +210,21 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	if res.Suggestions == nil {
 		res.Suggestions = []string{}
 	}
+	if payload, err := json.Marshal(res); err == nil {
+		suggestCachePut(cacheKey, payload)
+		writeJSONBytes(w, http.StatusOK, payload)
+		return
+	}
 	writeJSON(w, http.StatusOK, res)
 }
 
+// writeJSONBytes 按预序列化的字节写响应（缓存命中与缓存写入共用同一份形状）。
+func writeJSONBytes(w http.ResponseWriter, code int, payload []byte) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(code)
+	_, _ = w.Write(payload)
+}
+
 // clipRunes 按 rune 截断（中文不能按字节切）。
 func clipRunes(s string, max int) string {
 	if max <= 0 || utf8.RuneCountInString(s) <= max {

package/internal/client/suggest_test.go

@@ -6,15 +6,31 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 )
 
 // fakeSuggestCore 写一个假 core 脚本：记录 argv → 吃掉 stdin → 打印一份建议 JSON。
+//
+// Windows 上 exec 不了 sh 脚本（既有基线），改写等价的 .cmd 批处理 —— scriptBody
+// 仍收 sh 语法，由映射表翻成 cmd 等价物；没翻译的写法直接 Fatal，防止静默跑错。
 func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
 	t.Helper()
 	argLog := filepath.Join(dir, "args.txt")
 	p := filepath.Join(dir, "magic-agent")
+	if runtime.GOOS == "windows" {
+		p += ".cmd"
+		win, ok := shToCmd[scriptBody]
+		if !ok {
+			t.Fatalf("没给该 sh 脚本体准备 Windows 等价物：%q", scriptBody)
+		}
+		body := "@echo off\r\necho %*>\"" + argLog + "\"\r\nfind /v \"\" >NUL\r\n" + win + "\r\n"
+		if err := os.WriteFile(p, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return p, argLog
+	}
 	body := "#!/bin/sh\nprintf '%s' \"$*\" > " + argLog + "\ncat >/dev/null\n" + scriptBody + "\n"
 	if err := os.WriteFile(p, []byte(body), 0o755); err != nil {
 		t.Fatal(err)
@@ -22,6 +38,15 @@ func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
 	return p, argLog
 }
 
+// shToCmd 测试里用到的假 core 脚本体的 cmd 等价写法。
+var shToCmd = map[string]string{
+	`printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`: `echo {"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}`,
+	`printf '{"suggestions":["继续"],"engine":"fake","elapsedMs":9}\n'`:                  `echo {"suggestions":["继续"],"engine":"fake","elapsedMs":9}`,
+	`printf '{"suggestions":[]}\n'`:        `echo {"suggestions":[]}`,
+	"echo 'llm CLI not found' >&2\nexit 3": `echo llm CLI not found 1>&2&exit /b 3`,
+	`printf 'not json\n'`:                  `echo not json`,
+}
+
 func TestSuggestEndpoint(t *testing.T) {
 	dir := t.TempDir()
 	core, argLog := fakeSuggestCore(t, dir, `printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`)
@@ -53,6 +78,67 @@ func TestSuggestEndpoint(t *testing.T) {
 	}
 }
 
+func TestSuggestEndpointCacheHit(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":["继续"],"engine":"fake","elapsedMs":9}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+	body := `{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"fake-engine"}`
+
+	call := func() *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(body)))
+		return rec
+	}
+
+	first := call()
+	if first.Code != http.StatusOK {
+		t.Fatalf("首次 code = %d，body=%s", first.Code, first.Body.String())
+	}
+	if first.Header().Get("X-Suggest-Cache") == "hit" {
+		t.Fatalf("首次请求不应命中缓存")
+	}
+	second := call()
+	if second.Code != http.StatusOK {
+		t.Fatalf("二次 code = %d，body=%s", second.Code, second.Body.String())
+	}
+	if second.Header().Get("X-Suggest-Cache") != "hit" {
+		t.Fatalf("同内容的第二次请求应命中缓存")
+	}
+	if second.Body.String() != first.Body.String() {
+		t.Fatalf("缓存响应与首次不一致：%s vs %s", second.Body.String(), first.Body.String())
+	}
+
+	// 换引擎 = 换 key，不能复用旧缓存。
+	third := httptest.NewRecorder()
+	s.handleSuggest(third, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"other-engine"}`)))
+	if third.Header().Get("X-Suggest-Cache") == "hit" {
+		t.Fatalf("换了引擎应重新生成，不该命中缓存")
+	}
+
+	// 失败不缓存：core 挂了下次要重试。
+	failing := &Service{opts: Options{MagicAgent: fakeSuggestCoreFailing(t, dir)}}
+	f1 := httptest.NewRecorder()
+	failing.handleSuggest(f1, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"失败那轮"}`)))
+	if f1.Code != http.StatusBadGateway {
+		t.Fatalf("失败轮 code = %d，期望 502", f1.Code)
+	}
+	f2 := httptest.NewRecorder()
+	failing.handleSuggest(f2, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"失败那轮"}`)))
+	if f2.Code != http.StatusBadGateway {
+		t.Fatalf("失败后重试仍应走 core（code = %d，期望 502）", f2.Code)
+	}
+}
+
+// fakeSuggestCoreFailing 恒定失败的假 core（复用 fakeSuggestCore 的平台适配）。
+func fakeSuggestCoreFailing(t *testing.T, dir string) string {
+	t.Helper()
+	p, _ := fakeSuggestCore(t, dir, "echo 'llm CLI not found' >&2\nexit 3")
+	return p
+}
+
 func TestSuggestEndpointBadRequests(t *testing.T) {
 	dir := t.TempDir()
 	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":[]}\n'`)

package/internal/client/team_flags.go

@@ -92,21 +92,35 @@ func teamFlags(t *teamRequest, profile Profile, roles []string) ([]string, error
 		r := t.Routes[rawKind]
 		engine := strings.TrimSpace(r.Engine)
 		model := strings.TrimSpace(r.Model)
-		if engine == "" {
+		fbEngine := strings.TrimSpace(r.FallbackEngine)
+		fbModel := strings.TrimSpace(r.FallbackModel)
+		/* 备用可以单独配（主引擎留空 = 跟随主引擎 + 这一路的备）：所以这里不能用
+		   「engine 为空就 continue」把整条略掉 —— 有备用就得下发。 */
+		if engine != "" {
+			if !profile.AllowsEngine(engine) {
+				return nil, fmt.Errorf("team.routes.%s 的引擎 %q 不在 profile 白名单内", kind, engine)
+			}
+			spec := kind + "=" + engine
 			if model != "" {
-				// 只给模型不给引擎：语义不明（模型属于某一家引擎），不猜。
-				return nil, fmt.Errorf("team.routes.%s 给了 model 但没给 engine", kind)
+				spec += "/" + model
 			}
-			continue // 整条空 = 该类跟随主引擎
-		}
-		if !profile.AllowsEngine(engine) {
-			return nil, fmt.Errorf("team.routes.%s 的引擎 %q 不在 profile 白名单内", kind, engine)
+			args = append(args, "--team-route", spec)
+		} else if model != "" {
+			// 只给模型不给引擎：语义不明（模型属于某一家引擎），不猜。
+			return nil, fmt.Errorf("team.routes.%s 给了 model 但没给 engine", kind)
 		}
-		spec := kind + "=" + engine
-		if model != "" {
-			spec += "/" + model
+		if fbEngine != "" {
+			if !profile.AllowsEngine(fbEngine) {
+				return nil, fmt.Errorf("team.routes.%s 的备用引擎 %q 不在 profile 白名单内", kind, fbEngine)
+			}
+			spec := kind + "=" + fbEngine
+			if fbModel != "" {
+				spec += "/" + fbModel
+			}
+			args = append(args, "--team-fallback", spec)
+		} else if fbModel != "" {
+			return nil, fmt.Errorf("team.routes.%s 给了备用 model 但没给备用 engine", kind)
 		}
-		args = append(args, "--team-route", spec)
 	}
 	return args, nil
 }

package/internal/client/team_flags_test.go

@@ -146,6 +146,45 @@ func TestTeamFlagsRejectsModelWithoutEngine(t *testing.T) {
 	}
 }
 
+func TestTeamFlagsFallbackRoute(t *testing.T) {
+	// 主备（2026-10-24）：主 + 备都要翻成 flag；只配备用也要下发（主引擎跟随主引擎）。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {Engine: "codebuddy", Model: "hy3", FallbackEngine: "dsh", FallbackModel: "v3"},
+		"text":  {FallbackEngine: "claude"},
+	}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	joined := strings.Join(args, " ")
+	if !strings.Contains(joined, "--team-route image=codebuddy/hy3") {
+		t.Fatalf("主引擎没下发：%v", args)
+	}
+	if !strings.Contains(joined, "--team-fallback image=dsh/v3") {
+		t.Fatalf("备用引擎没下发：%v", args)
+	}
+	if !strings.Contains(joined, "--team-fallback text=claude") {
+		t.Fatalf("只配备用的路由没下发：%v", args)
+	}
+	if strings.Contains(joined, "--team-route text=") {
+		t.Fatalf("只配备用不该伪造主引擎：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsBadFallback(t *testing.T) {
+	// 备用引擎同样要过白名单。
+	if _, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {Engine: "llm", FallbackEngine: "claude"},
+	}}, Profile{Engines: []string{"llm"}}, nil); err == nil {
+		t.Fatal("备用引擎不在白名单时应报错")
+	}
+	// 备用 model 没有备用 engine：语义不明，不猜。
+	if _, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {FallbackModel: "sonnet"},
+	}}, Profile{}, nil); err == nil || !strings.Contains(err.Error(), "备用") {
+		t.Fatalf("err = %v，应提到备用", err)
+	}
+}
+
 func TestTeamFlagsAcceptsPlanRoute(t *testing.T) {
 	// plan = 计划阶段（谁来拆任务），与五类子任务一样可以单独指定引擎。
 	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"plan": {Engine: "claude"}}}, Profile{}, nil)

package/internal/client/testmain_test.go

@@ -0,0 +1,88 @@
+package client
+
+import (
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+)
+
+/* 测试用的「假 magic-client serve」：TestRestartDaemonReal 里把测试二进制软链成
+ * magic-client 再以 RUN_AS_SERVE=1 起子进程 —— 并且让这个子进程本身也是 "magic-client" 路径
+ * （restartDaemon 按「同一个可执行文件」认领实例）。
+ *
+ * 只实现升级链路用到的三件事：/desk/health、/desk/core/upgrade、/desk/version，外加
+ * 升级成功后 restartDaemon 用同一套参数再拉起自己。端口取自 MAGIC_TEST_STATE 旁的
+ * port 文件（第一次由父进程预先挑好），从而能验证「重启后端口不变」。
+ */
+func TestMain(m *testing.M) {
+	if os.Getenv("RUN_AS_SERVE") == "1" {
+		runFakeServe()
+		return
+	}
+	os.Exit(m.Run())
+}
+
+const fakeServeToken = "test-token-0123456789abcdef"
+
+func runFakeServe() {
+	statePath := strings.TrimSpace(os.Getenv("MAGIC_TEST_STATE"))
+	portFile := statePath + ".port"
+	core := os.Getenv("MAGIC_AGENT_BIN")
+
+	svc := &Service{opts: Options{MagicAgent: core, StatePath: statePath}, log: log.New(os.Stderr, "fake-serve: ", 0)}
+	svc.contract = Contract{ContractVersion: RequiredContractVersion, Version: coreBinaryVersion(core), Features: requiredFeatures}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/desk/health", func(w http.ResponseWriter, r *http.Request) {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "version": svc.contract.Version})
+	})
+	mux.HandleFunc("/desk/version", func(w http.ResponseWriter, r *http.Request) {
+		writeJSON(w, http.StatusOK, map[string]any{"version": coreBinaryVersion(core), "pid": os.Getpid()})
+	})
+	mux.HandleFunc("/desk/core/upgrade", svc.handleCoreUpgrade)
+	if err := os.MkdirAll(filepath.Dir(statePath), 0o700); err != nil {
+		panic(err)
+	}
+
+	/* 端口：父进程预挑了一个（写进 .port），子进程优先用它。 */
+	addr := "127.0.0.1:0"
+	if b, err := os.ReadFile(portFile); err == nil {
+		addr = "127.0.0.1:" + strings.TrimSpace(string(b))
+	}
+	ln, err := net.Listen("tcp", addr)
+	if err != nil { // 端口被占：由系统分配
+		if ln, err = net.Listen("tcp", "127.0.0.1:0"); err != nil {
+			panic(err)
+		}
+	}
+	port := ln.Addr().(*net.TCPAddr).Port
+	_ = os.WriteFile(portFile, []byte(fmt.Sprint(port)), 0o644)
+
+	/* 监听起来之后才记「由 start 拉起」的样子：Exe 是本进程路径、Addr 是**真实**的监听端口。
+	   （restartDaemon 会原样复用这个 Addr —— 端口不变，前端才能按原地址重连。） */
+	self, _ := os.Executable()
+	st := &DaemonState{PID: os.Getpid(), Port: port, Lan: false, Exe: self, Token: fakeServeToken,
+		Addr: ln.Addr().String(), StatePath: statePath}
+	if err := writeDaemonState(statePath, st); err != nil {
+		panic(err)
+	}
+
+	// restartDaemon 拉起的新实例要用同一个 Addr：旧实例收到 SIGTERM 立刻让出端口。
+	srv := &http.Server{Handler: mux}
+	go func() {
+		ch := make(chan os.Signal, 1)
+		signal.Notify(ch, syscall.SIGTERM)
+		<-ch
+		_ = srv.Close()
+	}()
+	if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
+		fmt.Fprintln(os.Stderr, "fake-serve:", err)
+	}
+}

package/internal/client/workspace_default_test.go

@@ -0,0 +1,158 @@
+package client
+
+// workspace_default_test.go - 默认工作区不能退化成文件系统根（2026-10-26 实测事故）。
+//
+// 事故现场：插件被 `cd /` 起来 → /desk/health 的 defaultWorkspace 报 `/` →
+// 移动端新建会话的工作区就是根目录。后果不只是「文件写在 /」：
+//   · 作业文件写 "workspace": "/"，而 core 自己登记的是真实 cwd，两边对不上；
+//   · mode=auto 的同空间冲突判定、core 的工作空间锁都按这个 key 算 ——
+//     `/` 变成「全机所有会话同一个空间」的万能桶，串行/并行全判错。
+//
+// 所以这里钉住三件事：根目录不当默认、有 cwd 就用 cwd、cwd 是根时退回上次用过的工作区。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writePrefs 往 prefs 文件写一份配置（只写关心的字段）。
+func writePrefs(t *testing.T, v map[string]any) string {
+	t.Helper()
+	p := mobilePrefsPath()
+	if p == "" {
+		t.Fatal("mobilePrefsPath() 为空")
+	}
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+// withTempHome 把 HOME 指向临时目录（prefs 落在 $HOME/.magic-agent 下）。
+func withTempHome(t *testing.T) string {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	return home
+}
+
+// TestIsRootDir 根目录的唯一判据：自己和自己的父目录相同。
+func TestIsRootDir(t *testing.T) {
+	cases := []struct {
+		path string
+		want bool
+	}{
+		{"/", true},
+		{"/tmp", false},
+		{"/Users/x/project", false},
+		{"", false},
+	}
+	for _, c := range cases {
+		if got := isRootDir(c.path); got != c.want {
+			t.Errorf("isRootDir(%q) = %v, want %v", c.path, got, c.want)
+		}
+	}
+}
+
+// TestDefaultWorkspaceUsesCwd cwd 有意义时就用它，不去翻 prefs。
+func TestDefaultWorkspaceUsesCwd(t *testing.T) {
+	withTempHome(t)
+	proj := t.TempDir()
+	if err := os.Chdir(proj); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir("/Users") })
+
+	// prefs 里放一个别的目录，确认 cwd 优先。
+	if err := os.WriteFile(mobilePrefsPath(), []byte(`{"lastWorkspace":"/tmp"}`), 0o600); err != nil {
+		// 目录可能不存在，先建
+		_ = os.MkdirAll(filepath.Dir(mobilePrefsPath()), 0o700)
+		_ = os.WriteFile(mobilePrefsPath(), []byte(`{"lastWorkspace":"/tmp"}`), 0o600)
+	}
+
+	// 注意：真实路径可能带 /private 前缀（macOS 的 /tmp 是软链），所以比较 EvalSymlinks。
+	want, _ := filepath.EvalSymlinks(proj)
+	got, _ := filepath.EvalSymlinks(defaultWorkspace())
+	if got != want {
+		t.Errorf("defaultWorkspace() = %q, want cwd %q", got, want)
+	}
+}
+
+// TestDefaultWorkspaceFallsBackWhenCwdIsRoot cwd 是 `/` 时退回上次用过的工作区。
+//
+// 这条是本次事故的直接回归测试。
+func TestDefaultWorkspaceFallsBackWhenCwdIsRoot(t *testing.T) {
+	withTempHome(t)
+	last := t.TempDir()
+	writePrefs(t, map[string]any{"lastWorkspace": last})
+
+	if err := os.Chdir("/"); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir("/Users") })
+
+	want, _ := filepath.EvalSymlinks(last)
+	got, _ := filepath.EvalSymlinks(defaultWorkspace())
+	if got != want {
+		t.Errorf("cwd 为 / 时 defaultWorkspace() = %q, want 上次工作区 %q", got, want)
+	}
+	if isRootDir(got) {
+		t.Errorf("默认工作区仍然退化成了根目录 %q", got)
+	}
+}
+
+// TestDefaultWorkspaceIgnoresBadPrefs prefs 里的值不可用时不能当默认。
+//
+// 三种坏值：不是绝对路径、目录已不存在、字段缺失。任一条被当成默认工作区，
+// 都会让会话归到一个不该归的地方（相对路径还会按插件 cwd 解释，等于又回到根目录）。
+func TestDefaultWorkspaceIgnoresBadPrefs(t *testing.T) {
+	withTempHome(t)
+	if err := os.Chdir("/"); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir("/Users") })
+
+	bad := []struct {
+		name string
+		v    map[string]any
+	}{
+		{"相对路径", map[string]any{"lastWorkspace": "relative/dir"}},
+		{"目录不存在", map[string]any{"lastWorkspace": "/definitely/not/here/xyz"}},
+		{"字段缺失", map[string]any{"engine": "dsh"}},
+		{"空串", map[string]any{"lastWorkspace": ""}},
+	}
+	for _, c := range bad {
+		t.Run(c.name, func(t *testing.T) {
+			writePrefs(t, c.v)
+			got := defaultWorkspace()
+			// 没有可用兜底时只能回到 cwd（/），但绝不能是 prefs 里的坏值。
+			if c.v["lastWorkspace"] != "" && c.v["lastWorkspace"] != nil {
+				if got == c.v["lastWorkspace"] {
+					t.Errorf("采纳了不可用的 lastWorkspace %v", c.v["lastWorkspace"])
+				}
+			}
+			if got != "/" && !filepath.IsAbs(got) {
+				t.Errorf("返回值不是绝对路径：%q", got)
+			}
+		})
+	}
+}
+
+// TestLastWorkspacePrefRejectsMissingDir 已删除的目录不算「上次用过的工作区」。
+func TestLastWorkspacePrefRejectsMissingDir(t *testing.T) {
+	withTempHome(t)
+	gone := filepath.Join(t.TempDir(), "deleted")
+	writePrefs(t, map[string]any{"lastWorkspace": gone})
+	if got := lastWorkspacePref(); got != "" {
+		t.Errorf("目录已不存在却仍返回 %q", got)
+	}
+}

package/internal/client/workspacelockenv_test.go

@@ -0,0 +1,54 @@
+package client
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/session"
+)
+
+/*
+工作空间锁开关的下发口径（2026-10-26）。
+
+	为什么单独立一个文件、而不塞进 startAsk 的用例里：这条判据翻转的代价极隐蔽。
+	core 的锁从「选入式」改成「默认生效」之后，**不传变量**的含义从「不排」变成了
+	「排」。于是原先「串行才传 =1」的写法会在无人察觉时把并行模式串起来 ——
+	界面上的表现是「切了并行，任务还是一个一个跑」，没人会先怀疑环境变量。
+
+	锁的两端（core / 插件）分属两个包，任何一端单独改都会被另一端静默抵消，
+	所以这条不变量必须在这里被钉死。
+*/
+func TestWorkspaceLockEnvForSerial(t *testing.T) {
+	got := workspaceLockEnv(nil)
+	if len(got) != 0 {
+		t.Fatalf("serial 未指定应按串行处理、什么都不传，实际 %v", got)
+	}
+}
+
+func TestWorkspaceLockEnvSerialLeavesDefault(t *testing.T) {
+	serial := true
+	got := workspaceLockEnv(&serial)
+	/* 不写 `=1` 是刻意的：core 的默认值就是开，显式写一遍只是多一个会和
+	   workspaceLockEnabled 的解析口径分叉的地方。 */
+	if len(got) != 0 {
+		t.Fatalf("串行作业不该追加任何变量（core 默认即开），实际 %v", got)
+	}
+}
+
+func TestWorkspaceLockEnvParallelDisables(t *testing.T) {
+	serial := false
+	got := workspaceLockEnv(&serial)
+	if len(got) != 1 {
+		t.Fatalf("并行作业必须且只能追加一条变量，实际 %v", got)
+	}
+	want := session.EnvWorkspaceLock + "=0"
+	if got[0] != want {
+		t.Fatalf("并行作业应下发 %q，实际 %q", want, got[0])
+	}
+	/* 值必须是 core 认的「关」：workspaceLockEnabled 只把 "0"/"false"/"off"/"no"
+	   当关闭。写成 "false" 也行，但拼错成 "no " / "OFF " 之类就静默失效了 ——
+	   这里断言到字面量，改 core 的解析口径时会立刻被这条测试拽住。 */
+	if !strings.HasSuffix(got[0], "=0") {
+		t.Fatalf("关闭值必须是 core 认得的写法，实际 %q", got[0])
+	}
+}