magic-agent 2.4.3 → 2.6.3

package/internal/client/service_test.go

@@ -8,11 +8,13 @@ import (
 	"image"
 	"image/png"
 	"io"
+	"log"
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -66,6 +68,23 @@ echo '{"v":1,"seq":4,"type":"result","text":"hi"}'
 
 const goodContract = `{"contractVersion":2,"features":["feature.session.events","feature.session.control"],"engines":[{"engine":"claude","ok":true,"capabilities":["session.stream"]}]}`
 
+// fakeCoreWithSessions 与 fakeCore 相同，只是 `--sessions` 返回调用方给的那段 JSON。
+// 用于断言「插件是否原样透传 core 给的字段」——字段集合必须由用例决定，
+// 写死在 fakeCore 里就测不出透传。
+func fakeCoreWithSessions(t *testing.T, sessionsJSON string) string {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "magic-agent")
+	script := "#!/bin/sh\ncase \"$*\" in\n" +
+		"  *--contract*)\n    echo '" + goodContract + "'\n    exit 0\n    ;;\n" +
+		"  *--sessions*)\n    cat <<'EOF'\n" + sessionsJSON + "\nEOF\n    exit 0\n    ;;\n" +
+		"esac\nexit 0\n"
+	if err := os.WriteFile(path, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
 // hostedContract 多了托管历史标识的能力位（2026-10-23 只增）。
 const hostedContract = `{"contractVersion":2,"features":["feature.session.events","feature.session.control","feature.session.hosted"],"engines":[{"engine":"claude","ok":true,"capabilities":["session.stream"]}]}`
 
@@ -415,7 +434,8 @@ func TestAskRelaysAndControl(t *testing.T) {
 
 // TestSessionsProxy 列表页要的是 core 的**持久会话登记表**（`--sessions`），
 // 且只回「本客户端 + 同族 magic-* 来源」那些（原口径见用户 2026-10-12
-// 「不是 magic-agent 客户端调用的任务不显示」；2026-10-15 放宽到名单，见 extraSessionClients）。
+// 「不是 magic-agent 客户端调用的任务不显示」；2026-10-15 放宽到名单，
+// 2026-10-26 改成按同族前缀判，见 sessionClientVisible）。
 //
 // 登记表目录是全机共享的，假 core 故意返回四种来源：本客户端的、没有 client 的
 // （= 直接跑 CLI / 旧记录）、别的应用的、掌天瓶（magic-test）的 —— 匿名那条与别家应用仍被滤掉，
@@ -452,6 +472,84 @@ func TestSessionsProxy(t *testing.T) {
 	}
 }
 
+// sessionClientVisible 同族判定（2026-10-26，用户：「多个客户端要能拉到同样的会话历史」）。
+//
+// 这条用例钉的是**维护点消失**：此前放行名单是写死的 {magic-test, magic-agent}，
+// 每接一个新客户端都要回来改常量；忘改的表现是那个客户端静默少一堆会话。
+// 现在按 `magic-` 前缀判，新增客户端不必再动代码。
+func TestSessionClientVisible(t *testing.T) {
+	const self = "com.magic.test"
+	cases := []struct {
+		client string
+		want   bool
+		why    string
+	}{
+		// ① 自己
+		{self, true, "本插件自己的 AppID"},
+		{"", false, "匿名 = 手工跑 / CI / 旧记录，不混进本应用列表"},
+		{"   ", false, "只有空白等同匿名"},
+		// ② 同族（前缀 magic-）
+		{"magic-test", true, "掌天瓶桌面壳（不经插件，直接 exec core）"},
+		{"magic-agent", true, "core 自身 / 直连 CLI 的显式标识"},
+		{"magic-stock", true, "将来新增的 magic-* 客户端：**不该再回来改代码**"},
+		{"magic-foo-bar", true, "同族任意名字"},
+		// ③ 异族：前缀相近但不是这一族
+		{"magicclient", false, "没有连字符 → 不是本族命名约定"},
+		{"magical-tool", false, "magical- 不是 magic- 前缀"},
+		{"other-app", false, "不相干应用"},
+		{"com.example.app", false, "不相干应用（bundleId 形态）"},
+	}
+	for _, c := range cases {
+		if got := sessionClientVisible(c.client, self); got != c.want {
+			t.Errorf("sessionClientVisible(%q) = %v，want %v（%s）", c.client, got, c.want, c.why)
+		}
+	}
+}
+
+// TestSessionsProxyKeepsUnknownFields：`/desk/sessions` 必须**原样透传** core 给的字段。
+// handleSessions 刻意解成 []map[string]any 而不是结构体，就是为了 core 往后给会话行加
+// 字段时插件不用跟着改。2026-10-26 多客户端仲裁新增的 `workspace_locked` /
+// `lock_holder` 正是靠这条路径到达手机端与 PC 端的 —— 谁把这行改成结构体、又忘了补字段，
+// 界面上就是「在手机上看着能发，按下去卡十分钟」，且没有任何报错可查。
+// 所以这里用一条**不在任何结构体里**的字段来钉住透传语义（比钉具体字段名更耐久）。
+func TestSessionsProxyKeepsUnknownFields(t *testing.T) {
+	core := fakeCoreWithSessions(t, `[{"run_id":"run-1","session_id":"sess-1","engine":"claude",
+	  "state":"running","source":"pc","client":"magic-client",
+	  "workspace_locked":true,
+	  "lock_holder":{"pid":4242,"client":"magic-test","source":"pc"}}]`)
+	svc := newTestService(t, core)
+	srv := httptest.NewServer(svc.Handler())
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodGet, srv.URL+"/desk/sessions", nil)
+	req.Header.Set("X-Magic-Token", "tok")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+
+	// 用 map 解，不假设字段集合：断言的是「这些字段确实出来了」。
+	var rows []map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&rows); err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 {
+		t.Fatalf("应剩 1 条，实际 %d: %+v", len(rows), rows)
+	}
+	if v, ok := rows[0]["workspace_locked"]; !ok || v != true {
+		t.Fatalf("workspace_locked 被吞了（多客户端排队提示会失效）：%+v", rows[0])
+	}
+	holder, ok := rows[0]["lock_holder"].(map[string]any)
+	if !ok {
+		t.Fatalf("lock_holder 被吞了（客户端答不出「在等谁」）：%+v", rows[0])
+	}
+	/* JSON 数字解成 float64 —— 断言值本身即可，别在这里比类型。 */
+	if pid, _ := holder["pid"].(float64); int(pid) != 4242 {
+		t.Errorf("lock_holder.pid = %v，want 4242", holder["pid"])
+	}
+}
+
 func TestAskPassesSaveHistory(t *testing.T) {
 	svc := newTestService(t, fakeCore(t, goodContract))
 	srv := httptest.NewServer(svc.Handler())
@@ -518,6 +616,13 @@ func TestAskInjectsClientEnv(t *testing.T) {
 func TestAskInjectsProfileAppID(t *testing.T) {
 	prof := DefaultProfile()
 	prof.App.BundleID = "magic-test"
+	/* ⚠️ 必须把数据目录钉到临时目录（2026-10-26 实测）。
+	   这条用例走的是**真实** New() → 真的建作业队列并落盘。DefaultProfile() 的
+	   Storage.Dir 是空的，于是 DataDir() 回落到 ~/.magic-client/<AppID>；而这里
+	   把 BundleID 改成了 magic-test —— 结果就是每次跑测试都往用户的
+	   ~/.magic-client/magic-test/jobs 里写一条 prompt=hi、engine=claude 的作业。
+	   那条作业的 workspace 还是 internal/client，看起来像真任务，排查时极具误导性。 */
+	prof.Storage.Dir = t.TempDir()
 	svc, err := New(Options{MagicAgent: fakeCore(t, goodContract), Profile: prof, Token: "tok"})
 	if err != nil {
 		t.Fatal(err)
@@ -718,6 +823,57 @@ func TestModulesStatic(t *testing.T) {
 	}
 }
 
+// TestRootServesMobileUIToPhone 手机打开 "/" 必须落到移动端界面，且令牌随查询串带过去；
+// 桌面 UA、以及「移动端界面不存在」两种情况仍给 PC 页 —— 后者保证不会把手机送进 404。
+func TestRootServesMobileUIToPhone(t *testing.T) {
+	const iphoneUA = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
+	const desktopUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36"
+
+	uiDir, mobileDir := t.TempDir(), t.TempDir()
+	for dir, body := range map[string]string{uiDir: "PC", mobileDir: "MOBILE"} {
+		if err := os.WriteFile(filepath.Join(dir, "index.html"), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// 直接构造 Service、只测 handleStatic：这条逻辑不碰 core，测试也就不需要假 core 子进程
+	// （那是个 sh 脚本，Windows 上跑不起来，见 fakeCore）。
+	newSvc := func(mobileRoot string) *Service {
+		return &Service{opts: Options{Profile: DefaultProfile(), UIRoot: uiDir, MobileRoot: mobileRoot}}
+	}
+	get := func(t *testing.T, svc *Service, path, ua string) *httptest.ResponseRecorder {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		req.Header.Set("User-Agent", ua)
+		rec := httptest.NewRecorder()
+		svc.handleStatic(rec, req)
+		return rec
+	}
+
+	t.Run("手机访问根路径跳移动端", func(t *testing.T) {
+		rec := get(t, newSvc(mobileDir), "/?token=tok", iphoneUA)
+		if rec.Code != http.StatusFound {
+			t.Fatalf("应 302，实际 %d", rec.Code)
+		}
+		if loc := rec.Header().Get("Location"); loc != "/m/?token=tok" {
+			t.Errorf("跳转目标不对：%s", loc)
+		}
+	})
+
+	t.Run("桌面访问根路径仍是PC页", func(t *testing.T) {
+		rec := get(t, newSvc(mobileDir), "/?token=tok", desktopUA)
+		if rec.Code != http.StatusOK || rec.Body.String() != "PC" {
+			t.Errorf("桌面应拿到 PC 页，实际 %d / %q", rec.Code, rec.Body.String())
+		}
+	})
+
+	t.Run("没有移动端界面时不跳", func(t *testing.T) {
+		rec := get(t, newSvc(t.TempDir()), "/?token=tok", iphoneUA) // 空目录 ⇒ hasMobileUI=false
+		if rec.Code != http.StatusOK || rec.Body.String() != "PC" {
+			t.Errorf("应退回 PC 页，实际 %d / %q", rec.Code, rec.Body.String())
+		}
+	})
+}
+
 func TestUploadReadBackAndTraversalGuard(t *testing.T) {
 	svc, err := New(Options{MagicAgent: fakeCore(t, goodContract), Profile: DefaultProfile(), Token: "tok"})
 	if err != nil {
@@ -1220,3 +1376,63 @@ func multipartWrite(buf *bytes.Buffer, field, name string, content []byte) strin
 	_ = w.Close()
 	return w.FormDataContentType()
 }
+
+/*
+WatchHost（2026-10-26）：重启出来的新实例是 detach 的，桌面壳的 r.stop() 杀不到它。
+没有这道闸，壳退出后会留下孤儿占着端口与单实例锁，下次开壳「插件启动即退出」。
+
+两个方向都要钉住：
+
+	① 托管进程没了 → 必须调用 quit（服务主动收摊）；
+	② 没有托管进程（HostPID=0，`magic-client start` 起的常驻实例）→ 永远不调用 quit
+	   （常驻实例本来就该活过启动它的终端）。
+*/
+func TestWatchHostQuitsWhenHostGone(t *testing.T) {
+	old := hostPollInterval
+	hostPollInterval = 5 * time.Millisecond
+	defer func() { hostPollInterval = old }()
+
+	// 造一个「已经不存在的 pid」：起一个马上退出的子进程，等它被回收。
+	cmd := exec.Command(os.Args[0], "-test.run=TestWatchHostHelperProcess")
+	cmd.Env = append(os.Environ(), "WATCH_HOST_HELPER=1")
+	if err := cmd.Start(); err != nil {
+		t.Fatal(err)
+	}
+	deadPID := cmd.Process.Pid
+	_ = cmd.Wait()
+
+	quit := make(chan struct{}, 1)
+	s := &Service{log: log.New(io.Discard, "", 0), opts: Options{HostPID: deadPID}}
+	s.WatchHost(func() { quit <- struct{}{} })
+
+	select {
+	case <-quit:
+	case <-time.After(3 * time.Second):
+		t.Fatal("托管进程已退出，但服务没有收摊（会留下孤儿占端口）")
+	}
+}
+
+// 常驻实例（HostPID=0）不该被这道闸影响。
+func TestWatchHostIgnoresUnmanaged(t *testing.T) {
+	old := hostPollInterval
+	hostPollInterval = 5 * time.Millisecond
+	defer func() { hostPollInterval = old }()
+
+	quit := make(chan struct{}, 1)
+	s := &Service{log: log.New(io.Discard, "", 0)} // HostPID = 0
+	s.WatchHost(func() { quit <- struct{}{} })
+
+	select {
+	case <-quit:
+		t.Fatal("没有托管进程的常驻实例不该自己退出")
+	case <-time.After(100 * time.Millisecond):
+	}
+}
+
+// TestWatchHostHelperProcess 只作为「一个会被立刻回收的子进程」存在。
+func TestWatchHostHelperProcess(t *testing.T) {
+	if os.Getenv("WATCH_HOST_HELPER") == "1" {
+		return
+	}
+	t.Skip("仅作为子进程桩使用")
+}

package/internal/client/sessions_cache.go

@@ -0,0 +1,148 @@
+package client
+
+// sessions_cache.go - 会话清单（/desk/sessions）的短 TTL 缓存 + 单飞。
+//
+// 2026-10-26 用户报障「会话列表现在显示很慢」。实测（同一台机器、同一份登记表）：
+//
+//	core 直跑 --sessions            18~22ms
+//	经本插件 /desk/sessions         200~900ms（负载 9~11 时接近 1s）
+//	10 并发同一接口                 每个 1.6s，墙钟 1.7s（没有串行锁，纯进程争抢）
+//	/dsk/health（不 spawn core）    1~3ms
+//	/desk/titles（读缓存文件）        <1ms
+//
+// 也就是说：慢的全部来自「每次请求都 spawn 一个 core 进程」这一步，而不是数据量
+// （空目录 6ms vs 407 条记录 20ms，同一量级）。而列表页恰恰是**轮询**驱动的：
+//
+//	· 移动端主列表每 5s 拉一次 /desk/sessions（startListPoll）
+//	· 它每次 loadSessions 还会并发问 /desk/titles、/health、/dirs、/jobs 共 5 个接口
+//	· 队列放行前的探活（PROBE_MS=700ms）、串行门（SLOT_POLL_MS=3s）、完成通知（5s）
+//	  各自还有一份 /desk/sessions 轮询
+//
+// 于是「打开一次列表」= 每 5 秒起一个新进程，机器忙时排队叠加，用户看到的就是一顿一顿。
+//
+// 两条修法，都在这一层做（不动 core，也不要求客户端改调用方式）：
+//
+//	① 短 TTL 缓存：TTL 内直接回上一次的结果。列表页对「晚 1 秒」无感 —— 它本来就在
+//	   5s 轮询，而会话状态变化（开跑 / 收尾 / 排队）走的是事件流，不依赖这份清单的实时性。
+//	② 单飞（single-flight）：TTL 过期瞬间若来了 N 个并发请求，只让**一个**去 spawn
+//	   core，其余等同一次结果。这正是上面「10 并发 1.6s」那组数字的解药。
+//
+// ⚠️ 缓存什么、不缓存什么：
+//   - 缓存的是 **core 的原始输出**（`--sessions` 的 JSON 字节），不是过滤后的结果。
+//     client 过滤依赖 selfID（每个实例一个），缓存原始输出才能保证不同实例各按自己的
+//     AppID 过一遍 —— 缓存过滤结果的话，第二个实例会拿到别人的列表。
+//   - **不缓存失败**：spawn 失败必须每次都真去试，否则一次瞬时故障会把列表钉死 1 秒。
+//   - 写操作（删除 / 停 / 改标题 / 派发）后由调用方调 invalidateSessionsCache() 主动失效，
+//     避免「刚删掉的会话还在列表里停留一个 TTL」这种看起来像 bug 的现象。
+
+import (
+	"context"
+	"os"
+	"strings"
+	"sync"
+	"time"
+)
+
+/* sessionsCacheTTL 缓存的存活时长。
+ *
+ * 取值依据：轮询间隔最短的是队列探活 PROBE_MS=700ms（那一段用户正在等任务落地，要快），
+ * 其次是主列表 5s。1s 的意思是「同一秒内的所有轮询合并成一次 spawn」——
+ * 移动端一次 loadSessions 的 5 个并发请求、以及多个轮询器同刻撞上，全部命中同一份。
+ * 再长就会让「刚发起的任务」在列表上晚一拍出现，那是用户看得见的。
+ *
+ * 可被 MAGIC_CLIENT_SESSIONS_TTL 覆盖（测试用：设 0 关缓存，设很大的值验证命中）。 */
+const sessionsCacheTTL = time.Second
+
+// sessionsCache 会话清单的短 TTL 缓存（并发安全）。
+//
+// 零值可用：body 为空表示还没缓存过。
+type sessionsCache struct {
+	mu     sync.Mutex
+	body   []byte    // core `--sessions` 的原始输出
+	expiry time.Time // 这份数据的过期时刻
+
+	/* flight 单飞：非 nil 表示「已经有一个请求在 spawn core」，其余请求等它。
+	   用它而不用 sync.Once / 每请求一把锁，是因为要能**跨请求**共享同一次结果 ——
+	   TTL 刚过的那一瞬间往往正好是几个轮询器同时醒来。 */
+	flight *sessionsFlight
+}
+
+// sessionsFlight 一次进行中的 core 调用，别的请求 await 它的结果。
+type sessionsFlight struct {
+	done chan struct{}
+	body []byte
+	err  error
+}
+
+// get 取清单：命中未过期的缓存直接返回；否则（单飞地）真去 spawn 一次 core。
+//
+// fetch 是真正取数的函数（生产里是 spawn core + 读 stdout）。它只会被**一个**并发
+// 请求执行，其余请求等这一个的结果 —— 这是本文件存在的核心价值。
+func (c *sessionsCache) get(ctx context.Context, ttl time.Duration, fetch func(context.Context) ([]byte, error)) ([]byte, error) {
+	c.mu.Lock()
+	if ttl > 0 && c.body != nil && time.Now().Before(c.expiry) {
+		body := c.body
+		c.mu.Unlock()
+		return body, nil
+	}
+	if f := c.flight; f != nil {
+		// 已经有人在取了：等它，别再起一个 core。
+		c.mu.Unlock()
+		select {
+		case <-f.done:
+			return f.body, f.err
+		case <-ctx.Done():
+			// 等的人自己超时了：如实报错，但**不要**去动别人的 flight。
+			return nil, ctx.Err()
+		}
+	}
+	f := &sessionsFlight{done: make(chan struct{})}
+	c.flight = f
+	c.mu.Unlock()
+
+	body, err := fetch(ctx)
+
+	c.mu.Lock()
+	f.body, f.err = body, err
+	c.flight = nil
+	/* 只缓存成功结果：失败必须下次真去试（否则一次瞬时故障把列表钉死一个 TTL）。
+	   另外缓存的是原始输出 —— 见文件头「缓存什么」那段。 */
+	if err == nil && ttl > 0 {
+		c.body = body
+		c.expiry = time.Now().Add(ttl)
+	}
+	c.mu.Unlock()
+	close(f.done) // 唤醒所有等的人（必须在释放锁之后：他们醒来第一件事可能就是抢锁）
+	return body, err
+}
+
+// invalidate 主动失效缓存（写操作之后调）。
+//
+// 为什么需要：删会话 / 停会话 / 新派发之后，列表应当**立刻**反映。不失效的话用户会看到
+// 「我刚删的那条还在」，然后过一秒自己消失 —— 那种体验比慢更让人怀疑程序。
+func (c *sessionsCache) invalidate() {
+	c.mu.Lock()
+	c.body = nil
+	c.expiry = time.Time{}
+	c.mu.Unlock()
+}
+
+// invalidateSessionsCache 让下一次 /desk/sessions 重新 spawn core。
+func (s *Service) invalidateSessionsCache() { s.sessCache.invalidate() }
+
+// sessionsTTL 当前生效的缓存时长。
+//
+// 默认 sessionsCacheTTL（1s）；MAGIC_CLIENT_SESSIONS_TTL 可覆盖（Go duration 写法，
+// 如 "0" 关缓存 / "5s" 加长）。只给测试与排障用 —— 生产不该靠环境变量调性能。
+// 值解析失败按默认走（宁可慢一点，也不要因为一个笔误把列表变成不刷新）。
+func sessionsTTL() time.Duration {
+	v := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_SESSIONS_TTL"))
+	if v == "" {
+		return sessionsCacheTTL
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil || d < 0 {
+		return sessionsCacheTTL
+	}
+	return d
+}

package/internal/client/sessions_cache_test.go

@@ -0,0 +1,163 @@
+package client
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TTL 内第二次取数必须命中缓存 —— 这是「会话列表慢」的主要修法：
+// 列表页每 5s 轮询一次、一次 loadSessions 还并发问 5 个接口，全都要合并成一次 spawn。
+func TestSessionsCacheHitsWithinTTL(t *testing.T) {
+	var calls int32
+	var c sessionsCache
+	fetch := func(context.Context) ([]byte, error) {
+		atomic.AddInt32(&calls, 1)
+		return []byte("[1]"), nil
+	}
+	for i := 0; i < 5; i++ {
+		body, err := c.get(context.Background(), time.Minute, fetch)
+		if err != nil || string(body) != "[1]" {
+			t.Fatalf("第 %d 次取数失败: %v %s", i, err, body)
+		}
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("TTL 内只该 spawn 一次，实际 %d 次", got)
+	}
+}
+
+// TTL 过期后必须重新取数（不能把列表钉死在旧数据上）。
+func TestSessionsCacheRefetchesAfterTTL(t *testing.T) {
+	var calls int32
+	var c sessionsCache
+	fetch := func(context.Context) ([]byte, error) {
+		n := atomic.AddInt32(&calls, 1)
+		return []byte{byte('0' + n)}, nil
+	}
+	if _, err := c.get(context.Background(), 0, fetch); err != nil { // ttl=0 = 不缓存
+		t.Fatal(err)
+	}
+	if _, err := c.get(context.Background(), 0, fetch); err != nil {
+		t.Fatal(err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("ttl=0 时每次都该真取，实际 %d 次", got)
+	}
+}
+
+// 失败**不缓存**：一次瞬时故障不该让列表在下一个 TTL 里继续报错。
+func TestSessionsCacheDoesNotCacheErrors(t *testing.T) {
+	var calls int32
+	var c sessionsCache
+	boom := errors.New("spawn 失败")
+	fetch := func(context.Context) ([]byte, error) {
+		if atomic.AddInt32(&calls, 1) == 1 {
+			return nil, boom
+		}
+		return []byte("ok"), nil
+	}
+	if _, err := c.get(context.Background(), time.Minute, fetch); !errors.Is(err, boom) {
+		t.Fatalf("第一次应如实返回错误，实际 %v", err)
+	}
+	body, err := c.get(context.Background(), time.Minute, fetch)
+	if err != nil || string(body) != "ok" {
+		t.Fatalf("失败被缓存了：err=%v body=%s", err, body)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("失败后应再试一次，实际 %d 次", got)
+	}
+}
+
+// 单飞：并发请求只 spawn 一个 core。这就是「10 并发各 1.6s」那组数字的解药。
+func TestSessionsCacheSingleFlight(t *testing.T) {
+	var calls int32
+	var c sessionsCache
+	release := make(chan struct{})
+	fetch := func(context.Context) ([]byte, error) {
+		atomic.AddInt32(&calls, 1)
+		<-release // 卡住，让所有并发请求都进来等同一趟
+		return []byte("shared"), nil
+	}
+	const n = 10
+	var wg sync.WaitGroup
+	bodies := make([]string, n)
+	errs := make([]error, n)
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			body, err := c.get(context.Background(), time.Minute, fetch)
+			bodies[i], errs[i] = string(body), err
+		}(i)
+	}
+	// 等所有 goroutine 都进到 get 里，再放行 fetch。
+	time.Sleep(100 * time.Millisecond)
+	close(release)
+	wg.Wait()
+
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("%d 个并发请求只该 spawn 一次，实际 %d 次", n, got)
+	}
+	for i := 0; i < n; i++ {
+		if errs[i] != nil || bodies[i] != "shared" {
+			t.Fatalf("第 %d 个请求拿到 %q / %v，应该都拿到同一份结果", i, bodies[i], errs[i])
+		}
+	}
+}
+
+// 失效后必须重新取数（删除会话 / 改标题之后靠它让列表立刻反映）。
+func TestSessionsCacheInvalidate(t *testing.T) {
+	var calls int32
+	var c sessionsCache
+	fetch := func(context.Context) ([]byte, error) {
+		atomic.AddInt32(&calls, 1)
+		return []byte("x"), nil
+	}
+	if _, err := c.get(context.Background(), time.Minute, fetch); err != nil {
+		t.Fatal(err)
+	}
+	c.invalidate()
+	if _, err := c.get(context.Background(), time.Minute, fetch); err != nil {
+		t.Fatal(err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("失效后应重新取数，实际 %d 次", got)
+	}
+}
+
+// 等待方超时不能连带毁掉别人的 flight（别人还要拿结果）。
+func TestSessionsCacheWaitersTimeoutIndependently(t *testing.T) {
+	var c sessionsCache
+	release := make(chan struct{})
+	fetch := func(context.Context) ([]byte, error) {
+		<-release
+		return []byte("slow"), nil
+	}
+	go func() { _, _ = c.get(context.Background(), time.Minute, fetch) }()
+	time.Sleep(50 * time.Millisecond)
+
+	// 这个请求自己超时：应当拿到 ctx 错误，而不是 hang 住。
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Millisecond)
+	defer cancel()
+	if _, err := c.get(ctx, time.Minute, fetch); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("等待方应返回超时，实际 %v", err)
+	}
+	// 把原件放行，确认它仍能正常完成（没被等待方的超时带崩）。
+	close(release)
+	deadline := time.Now().Add(time.Second)
+	for {
+		c.mu.Lock()
+		ready := c.body != nil
+		c.mu.Unlock()
+		if ready {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("原件没完成：等待方的超时可能误伤了它")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}