magic-agent 2.4.3 → 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

@@ -133,6 +133,10 @@ const (
 	StateCancelled       = "cancelled"        // 被 --stop 取消
 	StateInterrupted     = "interrupted"      // 当前轮被打断（会话仍可继续）
 	StateGone            = "gone"             // 记录里是 running，但进程已不在（自然退出/被别处杀掉）
+	/* queued 已受理、还在作业队列里等（**不是**活着：没有进程，也没有会话日志）。
+	   由服务端作业队列预登记（见 RegisterQueued），真开跑时抹掉、交给 core 自己的
+	   running 记录。列表页据此把「排在前面的那几条」画出来。 */
+	StateQueued = "queued"
 )
 
 // isLiveState 这个状态是否代表「会话/进程还活着」（running / waiting_approval / idle）。
@@ -144,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` 写入，一次性全部改写磁盘上的
@@ -481,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
 		}
 	}
@@ -519,13 +541,90 @@ 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
 }
 
+// RegisterQueued 预登记一条「已受理、还没开跑」的会话（作业队列用）。
+//
+// 为什么（2026-10-24 用户：「没跑也先登记啊」）：串行模式下作业在服务端排队，
+// 此前只有真开跑（core 的 Begin）才写登记表 —— 排在后面的几条既不在 --sessions 里，
+// 也不在任何客户端的列表上，看起来像「发完凭空消失」。现在受理即登记（state=queued），
+// 谁排在队里、排第几，列表页从这一刻就能看见；真开跑 / 终结时由队列调 RemoveQueued
+// 抹掉占位，交给 core 自己的那条 running 记录。
+//
+// 口径：
+//   - RunID 用客户端的幂等键（request_id；没有就用 job id）：客户端据此把本地那条
+//     「等待中」和这条登记行认成同一条，不会画两行。core 的 run_id 是 run-… 前缀，
+//     两者不会撞。
+//   - PID 恒 0、state=queued：读侧（normalizeDead / externalBusy / Stop）都按
+//     「非活着」处理，不占工作空间锁、不会被误判成在跑。
+//   - 覆盖写是幂等的：队列每推进一次状态就同步一次。
+func RegisterQueued(rec Record) error {
+	dir := Dir()
+	rec.RunID = strings.TrimSpace(rec.RunID)
+	if dir == "" || rec.RunID == "" {
+		return fmt.Errorf("register queued: 缺少登记目录或 run_id")
+	}
+	/* RunID 会直接当文件名用（<run_id>.json），而排队占位的 id 来自客户端的
+	   request_id —— 不能让 `../x`、带分隔符的 id 逃出登记目录。作业队列侧已经
+	   做过一次安全化（见 client 的 queuedSessionID），这里再挡一道。 */
+	if !validRecordName(rec.RunID) {
+		return fmt.Errorf("register queued: 非法 run_id %q", rec.RunID)
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return err
+	}
+	rec.State = StateQueued
+	rec.PID = 0
+	rec.KillGroup = false
+	rec.PromptHead = head(rec.PromptHead, 80)
+	if rec.StartedAt.IsZero() {
+		rec.StartedAt = time.Now()
+	}
+	rec.UpdatedAt = time.Now()
+	data, err := json.MarshalIndent(rec, "", "  ")
+	if err != nil {
+		return err
+	}
+	path := filepath.Join(dir, rec.RunID+".json")
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		return err
+	}
+	setStatus(rec)
+	return nil
+}
+
+// RemoveQueued 抹掉排队占位（开跑 / 终结 / 取消时由作业队列调用）。
+// 没有占位文件就什么都不做 —— 也**不要**去清状态表：那条键可能已经是真实会话的了。
+func RemoveQueued(runID string) {
+	runID = strings.TrimSpace(runID)
+	dir := Dir()
+	if runID == "" || dir == "" || !validRecordName(runID) {
+		return
+	}
+	path := filepath.Join(dir, runID+".json")
+	if _, err := os.Stat(path); err != nil {
+		return
+	}
+	if err := os.Remove(path); err != nil {
+		return
+	}
+	dropStatuses(map[string]bool{runID: true})
+}
+
 // supersedeSiblings 停掉同一会话上**还活着**的上一次运行。
 //
 // 为什么（2026-10-21，用户：「两边的回话状态不一致，一边结束了，一边还在显示运行中」）：
@@ -536,9 +635,27 @@ func Begin(o BeginOptions) (*Handle, error) {
 // 登记表里那条旧 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
@@ -547,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
@@ -557,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)
@@ -572,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", " "))
@@ -582,6 +719,22 @@ func head(s string, n int) string {
 	return string(r[:n]) + "…"
 }
 
+// validRecordName 登记文件名是否安全：只允许字母 / 数字 / - _ .，且不能是 . / ..。
+// 只给排队占位用 —— 它的 id 可能来自客户端（request_id），不能直接拼进路径。
+func validRecordName(id string) bool {
+	if id == "" || id == "." || id == ".." || len(id) > 96 {
+		return false
+	}
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '-', r == '_', r == '.':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
 // cwdOf 取进程当前目录；拿不到就留空（需求归纳按 workspace 归属时会退回用
 // Workspace 字段，两者都没有就只是不参与按目录的自动分组，不影响会话本身）。
 func cwdOf() string {
@@ -593,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) {
@@ -611,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 的收口点）。
 //
 // 两件事保证「统一」而不是「谁最后写谁算」：