magic-agent 2.6.0 → 2.6.3

package/internal/session/multiclient_test.go

@@ -0,0 +1,368 @@
+package session
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+/* 多客户端仲裁的不变量（2026-10-26）。
+ *
+ * 用户定调：「是 magic-agent 本身要支持多客户端」。
+ * 也就是说，仲裁必须在 **core**，不能指望每个宿主自己排一遍 ——
+ * 能起轮次的地方有桌面壳、HTTP 插件、手机、手工 CLI、CI，
+ * 少一个宿主漏实现，同一批文件就已经被两个引擎改了。
+ *
+ * 这些用例钉的就是「core 自己扛得住」那几条，与宿主无关：
+ *   ① 锁默认生效（不需要任何宿主注入环境变量）；
+ *   ② 能关（跑批 / 测试 / 团队模式要能显式退出）；
+ *   ③ 等待方能读到「谁占着」（而不是只知道「有人在跑」）；
+ *   ④ 跨客户端的重复接管**不静默杀**（同客户端才接管）；
+ *   ⑤ 兼容旧版锁文件（升级途中不能让两代进程各认一种格式而同时跑）。
+ */
+
+// TestWorkspaceLockDefaultsOn 不设任何环境变量，锁也必须生效 ——
+// 这是「magic-agent 本身支持多客户端」的最小含义：不依赖宿主注入。
+func TestWorkspaceLockDefaultsOn(t *testing.T) {
+	t.Setenv(EnvDir, t.TempDir())
+	// 显式清掉，模拟「宿主什么都没配」的真实情况（t.Setenv 只在本用例内生效）
+	t.Setenv(EnvWorkspaceLock, "zzz-unset")
+	t.Setenv(EnvWorkspaceLockWait, "1s")
+	ws := t.TempDir()
+
+	h1, err := Begin(BeginOptions{Workspace: ws, Engine: "claude", Client: "client-a"})
+	if err != nil {
+		t.Fatalf("第一轮 Begin 失败：%v", err)
+	}
+	// 同 workspace 的第二轮必须等（不是立刻拿到）
+	done := make(chan error, 1)
+	go func() {
+		h2, err := Begin(BeginOptions{Workspace: ws, Engine: "claude", Client: "client-b"})
+		if err == nil {
+			h2.Finish("", StateDone)
+		}
+		done <- err
+	}()
+	select {
+	case err := <-done:
+		t.Fatalf("默认启用时，同 workspace 的第二轮不应立刻拿到锁（err=%v）", err)
+	case <-time.After(300 * time.Millisecond):
+	}
+	h1.Finish("", StateDone)
+	select {
+	case <-done:
+	case <-time.After(3 * time.Second):
+		t.Fatal("第一轮结束后，第二轮仍未拿到锁")
+	}
+}
+
+// TestWorkspaceLockCanBeDisabled 显式关掉时必须真的不排 ——
+// 跑批 / 测试 / 团队模式依赖这个开关，不能被「默认启用」连坐。
+func TestWorkspaceLockCanBeDisabled(t *testing.T) {
+	t.Setenv(EnvDir, t.TempDir())
+	t.Setenv(EnvWorkspaceLock, "0")
+	ws := t.TempDir()
+
+	h1, err := Begin(BeginOptions{Workspace: ws, Engine: "claude"})
+	if err != nil {
+		t.Fatalf("Begin(1): %v", err)
+	}
+	// 关掉之后第二轮立刻拿到（不做串行）
+	h2, err := Begin(BeginOptions{Workspace: ws, Engine: "claude"})
+	if err != nil {
+		t.Fatalf("关掉锁之后第二轮应立刻拿到：%v", err)
+	}
+	h2.Finish("", StateDone)
+	h1.Finish("", StateDone)
+}
+
+// TestWorkspaceLockHolderIsReadable 等待方要能读到「谁占着」。
+// 只写 pid 的话，界面只能说「有人在跑」，用户不知道该去停哪一端。
+func TestWorkspaceLockHolderIsReadable(t *testing.T) {
+	t.Setenv(EnvDir, t.TempDir())
+	t.Setenv(EnvWorkspaceLock, "1")
+	t.Setenv(EnvWorkspaceLockWait, "1s")
+	ws := t.TempDir()
+
+	h, err := Begin(BeginOptions{Workspace: ws, Engine: "claude", Client: "com.magic.test", Source: SourceMobile})
+	if err != nil {
+		t.Fatalf("Begin: %v", err)
+	}
+	defer h.Finish("", StateDone)
+
+	got, ok := LockHolderFor(ws)
+	if !ok {
+		t.Fatal("锁已持有，LockHolderFor 应报出来")
+	}
+	if got.PID != os.Getpid() {
+		t.Errorf("holder pid = %d, want %d", got.PID, os.Getpid())
+	}
+	if got.Client != "com.magic.test" {
+		t.Errorf("holder client = %q, want com.magic.test（界面据此说「手机上那条」）", got.Client)
+	}
+	if got.Source != SourceMobile {
+		t.Errorf("holder source = %q, want %q", got.Source, SourceMobile)
+	}
+	/* run_id 是取锁之后补写的：没有它，界面上那句「pid=123 占着」没法点进
+	   --sessions 里对应那一行，用户也就查不出到底是谁。 */
+	if got.RunID != h.RunID() {
+		t.Errorf("holder run_id = %q, want %q（取锁后要补写）", got.RunID, h.RunID())
+	}
+	if got.Since.IsZero() {
+		t.Error("holder since 不该是零值（界面要显示「占了多久」）")
+	}
+
+	// 没锁的目录：报 false，不是零值 + true
+	if _, ok := LockHolderFor(t.TempDir()); ok {
+		t.Error("没有锁文件的目录不该报「有持有者」")
+	}
+}
+
+// TestLockKeyNormalizesPath 归一必须唯一，否则「同一个目录的两种写法」会被当成两个空间。
+func TestLockKeyNormalizesPath(t *testing.T) {
+	base := t.TempDir()
+	a, fa := LockKey(base + "/")
+	b, fb := LockKey(base)
+	if a != b || fa != fb {
+		t.Errorf("尾斜杠不该改变锁键：%q/%q vs %q/%q", a, fa, b, fb)
+	}
+	c, fc := LockKey(base + "//./")
+	if c != a || fc != fa {
+		t.Errorf("冗余分隔符不该改变锁键：%q vs %q", c, a)
+	}
+	if a == "" || fa == "" {
+		t.Fatal("LockKey 不该返回空")
+	}
+	// 不同目录必须不同
+	other, _ := LockKey(t.TempDir())
+	if other == a {
+		t.Error("不同目录不该算出同一个锁键")
+	}
+}
+
+// TestSupersedeDoesNotCrossClients 跨客户端的重复接管**不许静默杀**。
+//
+// 这是这次改动里最要紧的一条：用户在手机上跑着一条，在 PC 上点开同一条继续问，
+// 改前 core 会把手机上那条直接 SIGTERM —— 手机端只看到「突然已停止」。
+func TestSupersedeDoesNotCrossClients(t *testing.T) {
+	isolate(t)
+	// 关锁：本用例要单独验证 supersede 的分支判断，不能让锁先把第二轮挡住
+	t.Setenv(EnvWorkspaceLock, "0")
+
+	old := exec.Command("sleep", "30")
+	if err := old.Start(); err != nil {
+		t.Fatalf("起占位进程: %v", err)
+	}
+	alive := make(chan struct{})
+	go func() { _ = old.Wait(); close(alive) }()
+	t.Cleanup(func() { _ = old.Process.Kill() })
+
+	// 「手机端」那条：client = com.magic.test
+	oldH, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-x", PID: old.Process.Pid, Client: "com.magic.test"})
+	if err != nil {
+		t.Fatalf("Begin(手机端): %v", err)
+	}
+
+	// 「PC 端」接管同一条会话：client 不同 → 不许杀
+	if _, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-x", PID: os.Getpid(), Client: "magic-test"}); err != nil {
+		t.Fatalf("Begin(PC 端): %v", err)
+	}
+
+	select {
+	case <-alive:
+		t.Fatal("跨客户端的会话被静默终止了 —— 这正是要修的那把暗刀")
+	case <-time.After(600 * time.Millisecond):
+		// 正常：对面还活着
+	}
+
+	rec, found, err := Find(oldH.RunID())
+	if err != nil || !found {
+		t.Fatalf("Find: %+v %v %v", rec, found, err)
+	}
+	if rec.State == StateCancelled {
+		t.Fatalf("跨客户端不该写成 cancelled（实际两端都该照常跑，由锁与状态表协调），实得 %q", rec.State)
+	}
+}
+
+// TestSupersedeSameClientStillTakesOver 同一客户端的重复接管**照旧**停旧 ——
+// 改成多客户端之后不能把原来要解决的「两份日志抢写」问题放过。
+func TestSupersedeSameClientStillTakesOver(t *testing.T) {
+	isolate(t)
+	t.Setenv(EnvWorkspaceLock, "0")
+
+	old := exec.Command("sleep", "30")
+	if err := old.Start(); err != nil {
+		t.Fatalf("起占位进程: %v", err)
+	}
+	alive := make(chan struct{})
+	go func() { _ = old.Wait(); close(alive) }()
+	t.Cleanup(func() { _ = old.Process.Kill() })
+
+	oldH, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-y", PID: old.Process.Pid, Client: "magic-test"})
+	if err != nil {
+		t.Fatalf("Begin(old): %v", err)
+	}
+	if _, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-y", PID: os.Getpid(), Client: "magic-test"}); err != nil {
+		t.Fatalf("Begin(new): %v", err)
+	}
+
+	select {
+	case <-alive:
+	case <-time.After(3 * time.Second):
+		t.Fatal("同一客户端的上一次运行没被停掉（两份日志会抢写）")
+	}
+	rec, _, _ := Find(oldH.RunID())
+	if rec.State != StateCancelled {
+		t.Fatalf("旧 run 应写成 %q，实得 %q", StateCancelled, rec.State)
+	}
+}
+
+// TestSupersedeEmptyClientBehavesLikeSameClient 两边都没 client（都是直接跑 CLI）
+// 属于「同一来源」，照旧接管 —— 用户开两个终端跑同一会话同样是灾难。
+func TestSupersedeEmptyClientBehavesLikeSameClient(t *testing.T) {
+	isolate(t)
+	t.Setenv(EnvWorkspaceLock, "0")
+
+	old := exec.Command("sleep", "30")
+	if err := old.Start(); err != nil {
+		t.Fatalf("起占位进程: %v", err)
+	}
+	alive := make(chan struct{})
+	go func() { _ = old.Wait(); close(alive) }()
+	t.Cleanup(func() { _ = old.Process.Kill() })
+
+	if _, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-z", PID: old.Process.Pid}); err != nil {
+		t.Fatalf("Begin(old): %v", err)
+	}
+	if _, err := Begin(BeginOptions{Engine: "claude", SessionID: "sess-z", PID: os.Getpid()}); err != nil {
+		t.Fatalf("Begin(new): %v", err)
+	}
+	select {
+	case <-alive:
+	case <-time.After(3 * time.Second):
+		t.Fatal("两边都没 client 时应视为同一来源，旧运行要被接管")
+	}
+}
+
+// TestLockFileReadsLegacyFormat 旧版锁文件（`pid\n时间戳`）必须照旧认。
+//
+// 为什么单列一条：升级途中，上一个版本留下的锁文件还在。若新代码只认 JSON，
+// 它会读不出 pid → 判不出死进程 → 那个锁要等 6 小时 stale 才回收；
+// 更糟的是可能被当成「坏文件」直接抢过来 —— 两个进程就同时跑了。
+func TestLockFileReadsLegacyFormat(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv(EnvDir, dir)
+	ws := t.TempDir()
+
+	_, name := workspaceLockKey(ws)
+	lockDir := filepath.Join(dir, "locks")
+	if err := os.MkdirAll(lockDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	// 一个几乎不可能存活的 pid，写成**旧格式**
+	deadPID := 999999
+	body := strconv.Itoa(deadPID) + "\n" + strconv.FormatInt(time.Now().UnixNano(), 10) + "\n"
+	if err := os.WriteFile(filepath.Join(lockDir, name+".lock"), []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	if h, ok := LockHolderFor(ws); !ok || h.PID != deadPID {
+		t.Fatalf("旧格式锁文件应能读出 pid=%d，实得 %+v ok=%v", deadPID, h, ok)
+	}
+
+	// 死 pid 的旧格式锁必须能被回收（否则一行崩溃留下的记录要堵 6 小时）
+	t.Setenv(EnvWorkspaceLock, "1")
+	t.Setenv(EnvWorkspaceLockWait, "3s")
+	done := make(chan error, 1)
+	go func() {
+		h, err := Begin(BeginOptions{Workspace: ws, Engine: "claude"})
+		if err == nil {
+			h.Finish("", StateDone)
+		}
+		done <- err
+	}()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("陈旧旧格式锁应被回收：%v", err)
+		}
+	case <-time.After(4 * time.Second):
+		t.Fatal("旧格式的陈旧锁没被回收：Begin 一直等")
+	}
+}
+
+// TestLockFileWritesJSON 新写的锁文件是 JSON（能带身份），且 Release 只删自己那把。
+func TestLockFileWritesJSON(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv(EnvDir, dir)
+	t.Setenv(EnvWorkspaceLock, "1")
+	ws := t.TempDir()
+
+	h, err := Begin(BeginOptions{Workspace: ws, Engine: "claude", Client: "c1"})
+	if err != nil {
+		t.Fatalf("Begin: %v", err)
+	}
+	p := lockFilePath(ws)
+	b, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatalf("读锁文件: %v", err)
+	}
+	var probe map[string]any
+	if err := json.Unmarshal(b, &probe); err != nil {
+		t.Fatalf("新锁文件应是 JSON（能带持有者身份）：%v（内容 %q）", err, string(b))
+	}
+	if probe["pid"] == nil {
+		t.Error("锁文件里必须有 pid")
+	}
+
+	// 伪造「不是自己」的锁：Release 不该删掉别人的
+	if err := os.WriteFile(p, encodeLock(LockHolder{PID: 424242, Client: "other"}), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	h.Finish("", StateDone)
+	if _, err := os.Stat(p); err != nil {
+		t.Error("Release 不该删掉 pid 不是自己的那把锁")
+	}
+	_ = os.Remove(p)
+}
+
+// TestLockTimeoutMentionsHolder 等超时的报错要带上「谁占着」。
+// 原来的文案只有路径，用户看到「等超时了」却不知道该去停谁。
+func TestLockTimeoutMentionsHolder(t *testing.T) {
+	t.Setenv(EnvDir, t.TempDir())
+	t.Setenv(EnvWorkspaceLock, "1")
+	t.Setenv(EnvWorkspaceLockWait, "300ms")
+	ws := t.TempDir()
+
+	blocker := exec.Command("sleep", "30")
+	if err := blocker.Start(); err != nil {
+		t.Fatalf("起占位进程: %v", err)
+	}
+	t.Cleanup(func() { _ = blocker.Process.Kill() })
+
+	// 手写一把「活着的别人」持有的锁
+	ld := lockDirPath()
+	if err := os.MkdirAll(ld, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	_, name := workspaceLockKey(ws)
+	body := encodeLock(LockHolder{PID: blocker.Process.Pid, Client: "com.magic.test", Source: SourceMobile, Since: time.Now()})
+	if err := os.WriteFile(filepath.Join(ld, name+".lock"), body, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Begin(BeginOptions{Workspace: ws, Engine: "claude"})
+	if err == nil {
+		t.Fatal("锁被活着的人占着，Begin 应超时报错")
+	}
+	for _, want := range []string{"超时", "pid=", "com.magic.test", "手机"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("超时报错里应包含 %q（用户要能看出在等谁），实际：%v", want, err)
+		}
+	}
+}

package/internal/session/session.go

@@ -148,6 +148,14 @@ func isLiveState(s string) bool {
 	return s == StateRunning || s == StateWaitingApproval || s == StateIdle
 }
 
+// IsLiveState 导出版（2026-10-26）：**客户端也要问同一个问题**。
+//
+// 为什么必须导出而不是让调用方自己写 `s == "running" || ...`：多客户端之后，
+// 判断「这条会话还活着吗」的地方从 core 内部扩散到了各宿主（列表上标不标「进行中」、
+// 要不要显示「这个目录被占着」、能不能续接）。一旦新增一个活着状态（idle 就是这么加的），
+// 漏改任何一处都会静默地少显示一条活会话。判定只留一份，谁要问就调它。
+func IsLiveState(s string) bool { return isLiveState(s) }
+
 // normalizeState 把磁盘上的**旧状态值**归一成当前词表。
 //
 // 为什么必须有：`stopped` 在 2026-09-29 之前由 `--stop` 写入，一次性全部改写磁盘上的
@@ -485,14 +493,24 @@ func Begin(o BeginOptions) (*Handle, error) {
 	if !o.NoPersist {
 		dropUnreadable(dir)
 	}
-	/* 工作空间串行锁（选入式，见 workspace_lock.go）：拿到锁之后才写 running 记录，
+	/* 工作空间串行锁（默认启用，见 workspace_lock.go）：拿到锁之后才写 running 记录，
 	   别的进程看到的「在跑」就一定是已经可以开跑的。
 	   ⚠️ 团队子任务（ParentRunID 非空）不参与：它们与主任务同属一个工作空间，
-	      再取一把锁就是自己锁自己。 */
+	      再取一把锁就是自己锁自己。
+	   ⚠️ 锁里要写**持有者身份**（client / source / run_id / session_id）——
+	      等待方靠它回答「我在等谁」（手机上那条？还是另一个窗口？）。
+	      只写 pid 的话，用户看到的永远是「有人在跑」，不知道该去停谁。 */
 	var wl *WorkspaceLock
 	if strings.TrimSpace(o.ParentRunID) == "" {
 		var lerr error
-		if wl, lerr = acquireWorkspaceLock(o.Workspace); lerr != nil {
+		if wl, lerr = acquireWorkspaceLock(o.Workspace, LockHolder{
+			Client:    normalizeClient(o.Client),
+			Source:    normalizeSource(o.Source),
+			SessionID: strings.TrimSpace(o.SessionID),
+			Engine:    o.Engine,
+			// RunID 此刻还没生成（下面才算），先留空：
+			// 拿到锁之后立刻补写一次（见下面的 noteLockRun）。
+		}); lerr != nil {
 			return nil, lerr
 		}
 	}
@@ -523,9 +541,14 @@ func Begin(o BeginOptions) (*Handle, error) {
 	// 句柄里留着它，SetAppendPath 之类也不用知道自己是不是在存档模式。
 	h := &Handle{rec: rec, path: filepath.Join(dir, rec.RunID+".json"), noPersist: o.NoPersist, lock: wl}
 	h.write() // noPersist 时这里什么都不做
+	/* 锁文件的持有者身份补上 run_id（取锁时它还没生成）：等待方要能按 run_id 对上
+	   `--sessions` 里那一行，否则「占用者 pid=123」这种线索在界面上没法点进去。 */
+	if wl != nil {
+		wl.noteRun(rec.RunID)
+	}
 	// 「新起即停旧」：同一条会话上还活着的上一次运行先停掉（见 supersedeSiblings）。
 	if !o.NoPersist && rec.SessionID != "" {
-		supersedeSiblings(rec.SessionID, rec.RunID, rec.PID)
+		supersedeSiblings(rec.SessionID, rec.RunID, rec.PID, rec.Client)
 	}
 	return h, nil
 }
@@ -612,9 +635,27 @@ func RemoveQueued(runID string) {
 // 登记表里那条旧 run 又一直 running，`Find` 于是永远答「在跑」。
 // 而同一会话本来也不该被两个引擎进程同时续接（引擎侧的会话状态也会互相覆盖）。
 //
+// ── 2026-10-26 修：**跨客户端不许静默杀** ─────────────────────────────
+// 原先这里对任何「同会话 + 还活着」的旧 run 一律 SIGTERM，不看是谁起的。多客户端
+// 场景下这条就是一把暗刀：用户在手机上跑着一条对话，在 PC 上点开同一条会话接着问
+// （本意是「继续」），core 在 PC 这轮 Begin 时把手机上那条**静默终止**了 ——
+// 手机端看到的是「突然已停止」，既没有提示也不知道为什么。
+//
+// 现在的口径分两档：
+//
+//	① 同一个 client（或两边都为空 = 都是直接跑 CLI）→ **照旧接管**。
+//	   这是原本要解决的问题（同一份日志被两个进程同时续写），不能因为改成多客户端就放过。
+//	② 跨 client → **不杀**，改由工作空间锁在 Begin 阶段就把并发挡在门外。
+//	   跨端的续接本来也不该发生：session 级状态表（status.go）是共享的，PC 端看到
+//	   「手机上正跑着」应当提示用户，而不是抢过来把对面杀了。
+//
+// 为什么要留 ① 而不干脆全删：直接跑 CLI 的两个进程（用户开了两个终端）client 都是空，
+// 那种并发同样是灾难。②只说「不同客户端不该互相杀」，没说「并发就对了」——
+// 并发由锁和 isLiveState 挡住，这里只负责「同一来源的重复接管」。
+//
 // 口径与 Stop 一致：先 SIGTERM，宽限期不退再 SIGKILL，确认消失后写 cancelled。
 // 只在落盘模式下做：NoPersist 的调用彼此看不见，也无从判定谁是「旧」的。
-func supersedeSiblings(sessionID, runID string, selfPID int) {
+func supersedeSiblings(sessionID, runID string, selfPID int, selfClient string) {
 	sessionID = strings.TrimSpace(sessionID)
 	if sessionID == "" {
 		return
@@ -623,6 +664,7 @@ func supersedeSiblings(sessionID, runID string, selfPID int) {
 	if err != nil {
 		return
 	}
+	self := normalizeClient(selfClient)
 	for _, r := range all {
 		if r.RunID == runID || r.SessionID != sessionID {
 			continue
@@ -633,6 +675,16 @@ func supersedeSiblings(sessionID, runID string, selfPID int) {
 		if r.PID <= 0 || r.PID == selfPID || !agent.PIDAlive(r.PID) {
 			continue
 		}
+		/* 跨客户端：不动手，只说明。见上面「跨客户端不许静默杀」。
+		   用 stderr 是为了让**当前这轮**的调用方（壳 / 插件）能把这句话转给界面 ——
+		   用户需要知道「你正在接的这条会话，另一边还跑着」。 */
+		if other := normalizeClient(r.Client); other != self {
+			fmt.Fprintf(os.Stderr,
+				"magic-agent: 同一会话的另一端仍在运行（pid %d / %s / 客户端 %s），本端不接管；"+
+					"如需继续请先停掉那一端（magic-agent --stop %s）\n",
+				r.PID, r.RunID, clientLabel(other), sessionID)
+			continue
+		}
 		_ = agent.TerminatePID(r.PID, r.KillGroup)
 		if !waitGone(r.PID, 2*time.Second) {
 			_ = agent.KillPID(r.PID, r.KillGroup)
@@ -648,6 +700,15 @@ func supersedeSiblings(sessionID, runID string, selfPID int) {
 	}
 }
 
+// clientLabel 客户端标识的人话（空 = 直接跑 CLI，不是「未知」）。
+func clientLabel(c string) string {
+	c = strings.TrimSpace(c)
+	if c == "" {
+		return "（直接命令行）"
+	}
+	return c
+}
+
 // head 截取开头 n 个字符（按 rune，避免把中文切坏）。
 func head(s string, n int) string {
 	s = strings.TrimSpace(strings.ReplaceAll(s, "\n", " "))
@@ -685,12 +746,17 @@ func cwdOf() string {
 }
 
 // List 返回全部记录（新的在前）；顺带清理读不出来的坏文件。
+//
+// ⚠️ 一次遍历读一遍就够了（2026-10-26 修）：此前先调 dropUnreadable(dir)（把每个 json
+// 读一遍）、主循环再 readRecord 一遍 —— 同一份目录被读了两遍、反序列化两遍。实测 407
+// 条记录时是 814 次读盘 + 814 次 JSON 解析，而 go 侧整个 --sessions 只值 20ms，
+// 客户端列表接口却要 200~900ms，这一份白读是其中一块。现在坏文件在**同一次遍历里**
+// 顺手删掉，语义与原来的「先清后列」完全一致（坏文件本来就不出现在结果里）。
 func List() ([]Record, error) {
 	dir := Dir()
 	if dir == "" {
 		return nil, fmt.Errorf("cannot resolve sessions dir")
 	}
-	dropUnreadable(dir)
 	entries, err := os.ReadDir(dir)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -703,12 +769,18 @@ func List() ([]Record, error) {
 		if e.IsDir() || !strings.HasSuffix(e.Name(), ".json") {
 			continue
 		}
-		if rec, err := readRecord(filepath.Join(dir, e.Name())); err == nil {
-			if normalizeDead(&rec) {
-				writeRecord(rec)
-			}
-			out = append(out, rec)
+		p := filepath.Join(dir, e.Name())
+		rec, err := readRecord(p)
+		if err != nil {
+			/* 坏文件（写了一半 / 非法 JSON）永远读不出来：顺手清掉，别让它每次 List
+			   都白读一遍。只删 `.json` 且确实解析失败的，其余一概不动。 */
+			_ = os.Remove(p)
+			continue
+		}
+		if normalizeDead(&rec) {
+			writeRecord(rec)
 		}
+		out = append(out, rec)
 	}
 	sort.Slice(out, func(i, j int) bool { return out[i].StartedAt.After(out[j].StartedAt) })
 	return out, nil

package/internal/session/session_test.go

@@ -201,6 +201,13 @@ func TestFinishKeepsStoppedState(t *testing.T) {
 // 增量读的另一端会漏掉终态；登记表里旧 run 又一直 running，Find 永远答「在跑」。
 func TestBeginSupersedesAliveSibling(t *testing.T) {
 	isolate(t)
+	/* ⚠️ 必须显式关掉工作空间锁（2026-10-26）：本用例在**同一个 workspace** 里连着
+	   Begin 两次。锁默认启用之后，第二次 Begin 会先卡在锁上（等 10 分钟），
+	   根本走不到 supersedeSiblings —— 而这个用例验的正是 supersede 那一步。
+	   两者是两道独立的防线：锁管「不同进程同时进同一目录」，supersede 管
+	   「同一条会话被重复接管」（跨 workspace 续接同一 session 时锁挡不住）。
+	   关锁之后若 supersede 失效，这个用例照样会红 —— 它没有失去意义。 */
+	t.Setenv(EnvWorkspaceLock, "0")
 
 	// 用一个真实存活进程冒充「同会话的上一次运行」（supersedeSiblings 会按 pid 判活、下手）。
 	old := exec.Command("sleep", "30")

package/internal/session/status.go

@@ -140,6 +140,27 @@ func StatusForAny(sessionID, runID string) string {
 	return m[strings.TrimSpace(runID)].State
 }
 
+// StatusSnapshot 取整张状态表的**只读快照**，供批量读取（列表页）用。
+//
+// 为什么需要（2026-10-26）：StatusForAny 每次都走 loadStatuses()，而它为了不让调用方
+// 误改缓存，会把整张表**深拷贝**一遍再返回。列表页逐行调它 = 每行一次全表拷贝 + 一次
+// 加锁解锁；407 行就是 407 次。这里只拷一次，调用方自己按 id 取。
+//
+// 返回的 map 是**副本**，调用方随便读（也别指望去改它会影响缓存）。
+func StatusSnapshot() map[string]StatusEntry {
+	m, _ := loadStatuses()
+	return m
+}
+
+// StatusOf 从快照里取一条会话的状态（session_id 优先，其次 run_id）——
+// 与 StatusForAny 同口径，只是不再重复加载表。表为 nil 时返回空串。
+func StatusOf(snapshot map[string]StatusEntry, sessionID, runID string) string {
+	if e, ok := snapshot[strings.TrimSpace(sessionID)]; ok && e.State != "" {
+		return e.State
+	}
+	return snapshot[strings.TrimSpace(runID)].State
+}
+
 // setStatus 把一条登记记录的状态写进会话级状态表（writeRecord 的收口点）。
 //
 // 两件事保证「统一」而不是「谁最后写谁算」：

package/internal/session/status_test.go

@@ -142,3 +142,31 @@ func TestDeleteDropsStatuses(t *testing.T) {
 		t.Fatalf("删除后状态该被清掉，实得 %q", got)
 	}
 }
+
+// TestStatusOfMatchesStatusForAny 快照读取必须与逐条读取**逐字一致**。
+//
+// 为什么单独立一条（2026-10-26）：列表页从 StatusForAny 换成了 StatusSnapshot + StatusOf
+// （逐行调前者会让底层把整张表深拷贝一遍，407 行 = 407 次全表拷贝）。这类「为了性能换一条
+// 取数路径」的改动最容易悄悄改变语义 —— 键优先级（session 优先 / run 兜底）只要漏一处，
+// 列表上的状态就会一部分对、一部分错，而且极难看出来。这里把两者钉成同一个答案。
+func TestStatusOfMatchesStatusForAny(t *testing.T) {
+	withStatusHome(t)
+	now := time.Now()
+	setStatus(Record{RunID: "run-a", SessionID: "sess-a", State: StateIdle, StartedAt: now})
+	setStatus(Record{RunID: "run-b", State: StateRunning, StartedAt: now})
+	snap := StatusSnapshot()
+
+	cases := [][2]string{
+		{"sess-a", "run-a"}, // 两个键都有：取 session
+		{"", "run-b"},       // 只有 run：取 run
+		{"sess-a", "run-b"}, // 撞车：session 优先（与 StatusForAny 同口径）
+		{"nope", "nope2"},   // 都没有：空
+		{"", ""},            // 空 id：空
+	}
+	for _, c := range cases {
+		want := StatusForAny(c[0], c[1])
+		if got := StatusOf(snap, c[0], c[1]); got != want {
+			t.Fatalf("StatusOf(%q,%q) = %q，StatusForAny 却是 %q", c[0], c[1], got, want)
+		}
+	}
+}

package/internal/session/title.go

@@ -133,6 +133,22 @@ func TitleForAny(sessionID, runID string) string {
 	return m[strings.TrimSpace(runID)]
 }
 
+// TitleSnapshot 取整张标题表的**只读快照**，供批量读取（列表页）用。
+//
+// 与 StatusSnapshot 同一个理由（2026-10-26）：TitleForAny 每次都会让 loadTitles()
+// 把整张表深拷贝一份（缓存不能交给调用方乱改）。列表页逐行调它，407 行就是 407 次
+// 全表拷贝 —— 而它要的只是一个 O(1) 的查表。这里拷一次，调用方自己按 id 取。
+func TitleSnapshot() map[string]string { return Titles() }
+
+// TitleOf 从快照里取一条会话的标题：**session_id 优先，其次 run_id** ——
+// 与 TitleForAny 同口径，只是不再重复加载表。
+func TitleOf(snapshot map[string]string, sessionID, runID string) string {
+	if t := snapshot[strings.TrimSpace(sessionID)]; t != "" {
+		return t
+	}
+	return snapshot[strings.TrimSpace(runID)]
+}
+
 // AdoptTitle 把标题从 run_id 迁到 session_id（幂等），并**清掉那个 run_id 键**。
 //
 // 只在新键**为空**时搬：用户可能已经手动重命名过（那就是权威值），不能被旧键覆盖回去。

package/internal/session/title_test.go

@@ -296,3 +296,29 @@ func TestSummarizeCachedAcrossKeys(t *testing.T) {
 		t.Fatal("命中时应把标题迁到 session_id（否则下一轮又要重算）")
 	}
 }
+
+// TestTitleOfMatchesTitleForAny 快照读取必须与逐条读取**逐字一致**（理由见 status_test.go
+// 的 TestStatusOfMatchesStatusForAny：列表页为省掉逐行全表拷贝换了取数路径）。
+func TestTitleOfMatchesTitleForAny(t *testing.T) {
+	withTitleHome(t)
+	if err := SetTitle("sess-a", "会话标题"); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetTitle("run-b", "只按 run 存的"); err != nil {
+		t.Fatal(err)
+	}
+	snap := TitleSnapshot()
+
+	cases := [][2]string{
+		{"sess-a", "run-b"}, // 撞车：session 优先
+		{"", "run-b"},       // 只按 run
+		{"nope", "nope"},    // 都没有
+		{"", ""},            // 空 id
+	}
+	for _, c := range cases {
+		want := TitleForAny(c[0], c[1])
+		if got := TitleOf(snap, c[0], c[1]); got != want {
+			t.Fatalf("TitleOf(%q,%q) = %q，TitleForAny 却是 %q", c[0], c[1], got, want)
+		}
+	}
+}