magic-agent 2.4.3 → 2.6.3

package/internal/client/singleinstance_test.go

@@ -0,0 +1,607 @@
+package client
+
+// singleinstance_test.go - 单实例互斥（2026-10-26 用户：「同时只启动1个」）。
+//
+// 要钉住的是那个**用户可见的故障形态**：两份实例共用作业记录，任务在 B 里跑完，
+// 手机连着的 A 拿不到事件 → 界面「本轮没有收到任何输出（连接可能已断开）」。
+// 所以互斥的判据是「这台机器上还有没有活着的实例」，不是端口。
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// lockInTemp 把锁文件指到临时目录（每个用例独立）。
+//
+// 锁现在按**数据目录**分（不同 AppID 各自一把），所以这里返回的是「数据目录」，
+// 锁文件是它下面的 magic-client.lock —— 同时给返回路径，便于断言文件本身。
+func lockInTemp(t *testing.T) string {
+	t.Helper()
+	dataDir := t.TempDir()
+	t.Setenv(EnvLockPath, filepath.Join(dataDir, "magic-client.lock"))
+	return dataDir
+}
+
+// lockPathOf 上面那个数据目录对应的锁文件路径。
+func lockPathOf(dataDir string) string { return filepath.Join(dataDir, "magic-client.lock") }
+
+// writeHolder 手写一份锁文件（模拟「已有一份在跑」）。
+func writeHolder(t *testing.T, path string, h SingleInstanceHolder) {
+	t.Helper()
+	b, err := json.Marshal(h)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// deadPID 找一个确定不存在的 pid（起一个进程记下再杀掉）。
+func deadPID(t *testing.T) int {
+	t.Helper()
+	cmd := exec.Command("sleep", "30")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来占位进程：%v", err)
+	}
+	pid := cmd.Process.Pid
+	_ = cmd.Process.Kill()
+	_ = cmd.Wait()
+	return pid
+}
+
+// TestAcquireSingleInstanceSeparateDataDirsDoNotBlock 不同数据目录可以各跑一份。
+//
+// 这是 2026-10-26 第一版写成「全机单锁」后当场踩到的误伤：本机同时有
+// magic-test 的移动端网关（storage.dir=~/.magic-test，8977）和 magic-agent 自己的
+// 实例（~/.magic-client/magic-agent）。两者作业目录、令牌都不同，本来互不干扰，
+// 全机锁却把其中一份挡在门外。锁的粒度必须是「一份数据目录一把」。
+func TestAcquireSingleInstanceSeparateDataDirsDoNotBlock(t *testing.T) {
+	dirA, dirB := t.TempDir(), t.TempDir()
+
+	// 两个目录各写一把「活着的持有者」，再分别去取 —— 都不能被挡住。
+	// 先把 EnvLockPath 清掉，让锁落到各自的 dataDir 下（这才是真实部署形态）。
+	t.Setenv(EnvLockPath, "")
+
+	lkA, holderA, err := AcquireSingleInstance(dirA, 9100)
+	if err != nil || lkA == nil {
+		t.Fatalf("数据目录 A 没拿到锁：err=%v holder=%+v", err, holderA)
+	}
+	defer lkA.Release()
+
+	lkB, holderB, err := AcquireSingleInstance(dirB, 8977)
+	if err != nil {
+		t.Fatalf("数据目录 B 出错：%v", err)
+	}
+	if lkB == nil {
+		t.Fatalf("不同数据目录竟然被挡住了（holder=%+v）—— 这就是误伤 magic-test 网关的那个 bug", holderB)
+	}
+	defer lkB.Release()
+
+	// 而同一个目录上的第二份仍然要被挡住（互斥本身不能因为分目录而失效）。
+	lkA2, holderA2, err := AcquireSingleInstance(dirA, 0)
+	if err != nil {
+		t.Fatalf("同目录第二份出错：%v", err)
+	}
+	if lkA2 != nil {
+		lkA2.Release()
+		t.Fatal("同一个数据目录上竟然起了两份")
+	}
+	if holderA2 == nil || holderA2.PID != os.Getpid() {
+		t.Errorf("同目录冲突时没报出占用者：%+v", holderA2)
+	}
+}
+
+// TestAcquireSingleInstanceFirstWins 空目录下第一份拿到锁。
+func TestAcquireSingleInstanceFirstWins(t *testing.T) {
+	dataDir := lockInTemp(t)
+	path := lockPathOf(dataDir)
+	lk, holder, err := AcquireSingleInstance(dataDir, 9100)
+	if err != nil {
+		t.Fatalf("AcquireSingleInstance: %v", err)
+	}
+	if lk == nil {
+		t.Fatalf("空目录下没拿到锁，holder=%+v", holder)
+	}
+	defer lk.Release()
+
+	h := ReadSingleInstanceHolder(path)
+	if h == nil || h.PID != os.Getpid() {
+		t.Fatalf("锁文件内容 = %+v，期望 pid=%d", h, os.Getpid())
+	}
+	if h.Port != 9100 {
+		t.Errorf("Port = %d, want 9100", h.Port)
+	}
+}
+
+// TestAcquireSingleInstanceBlocksSecond 活着的实例占着锁时，第二份必须拿不到。
+//
+// 这是核心断言：拿不到不是错误（err 该为 nil），而是返回 nil + 占用者身份，
+// 让调用方打一句「谁在跑、该去停它」。
+func TestAcquireSingleInstanceBlocksSecond(t *testing.T) {
+	dataDir := lockInTemp(t)
+	path := lockPathOf(dataDir)
+	writeHolder(t, path, SingleInstanceHolder{
+		PID: os.Getpid(), Port: 9100, Version: "9.9.9", Since: time.Now(),
+	})
+
+	lk, holder, err := AcquireSingleInstance(dataDir, 0)
+	if err != nil {
+		t.Fatalf("不该返回 err（那是「有人在跑」，不是 IO 故障）：%v", err)
+	}
+	if lk != nil {
+		lk.Release()
+		t.Fatal("第二份竟然拿到了锁")
+	}
+	if holder == nil || holder.PID != os.Getpid() {
+		t.Fatalf("占用人身份丢失：%+v", holder)
+	}
+	if holder.Version != "9.9.9" || holder.Port != 9100 {
+		t.Errorf("占用人信息不完整：%+v", holder)
+	}
+}
+
+// TestAcquireSingleInstanceReclaimsDeadHolder 持有者已死 → 自动回收，不卡住用户。
+func TestAcquireSingleInstanceReclaimsDeadHolder(t *testing.T) {
+	dataDir := lockInTemp(t)
+	path := lockPathOf(dataDir)
+	dead := deadPID(t)
+	writeHolder(t, path, SingleInstanceHolder{PID: dead, Since: time.Now()})
+
+	lk, holder, err := AcquireSingleInstance(dataDir, 0)
+	if err != nil {
+		t.Fatalf("AcquireSingleInstance: %v", err)
+	}
+	if lk == nil {
+		t.Fatalf("持有者已死却没回收，holder=%+v", holder)
+	}
+	defer lk.Release()
+	if h := ReadSingleInstanceHolder(path); h == nil || h.PID != os.Getpid() {
+		t.Errorf("回收后锁内容 = %+v，期望是当前进程", h)
+	}
+}
+
+// TestAcquireSingleInstanceReclaimsStaleByAge 超过上限的锁按陈旧处理。
+//
+// 为什么要这条：进程崩溃没删锁、或 pid 被系统复用给了一个无关进程时，
+// 「pid 活着」会误判成「有人在跑」，把用户永久锁在外面。时间上限是最后一道保险。
+func TestAcquireSingleInstanceReclaimsStaleByAge(t *testing.T) {
+	dataDir := lockInTemp(t)
+	path := lockPathOf(dataDir)
+	writeHolder(t, path, SingleInstanceHolder{
+		PID:   os.Getpid(), // pid 活着，但时间太久
+		Since: time.Now().Add(-singleInstanceStale - time.Minute),
+	})
+
+	lk, holder, err := AcquireSingleInstance(dataDir, 0)
+	if err != nil {
+		t.Fatalf("AcquireSingleInstance: %v", err)
+	}
+	if lk == nil {
+		t.Fatalf("超龄锁没被回收，holder=%+v", holder)
+	}
+	defer lk.Release()
+}
+
+// TestStaleLockFileIsNotCached 坏内容 / 老格式不能把用户挡在外面。
+func TestStaleLockFileIsNotCached(t *testing.T) {
+	t.Run("半截内容按陈旧处理", func(t *testing.T) {
+		dataDir := lockInTemp(t)
+		path := lockPathOf(dataDir)
+		if err := os.WriteFile(path, []byte("{not json"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		lk, _, err := AcquireSingleInstance(dataDir, 0)
+		if err != nil {
+			t.Fatalf("err = %v", err)
+		}
+		if lk == nil {
+			t.Fatal("内容坏掉的锁应被回收")
+		}
+		lk.Release()
+	})
+
+	t.Run("老格式纯 pid 仍能读出占用者", func(t *testing.T) {
+		dataDir := lockInTemp(t)
+		path := lockPathOf(dataDir)
+		if err := os.WriteFile(path, []byte("999999\n1700000000\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		h := ReadSingleInstanceHolder(path)
+		if h == nil || h.PID != 999999 {
+			t.Fatalf("老格式读成 %+v，期望 pid=999999", h)
+		}
+	})
+}
+
+// TestReleaseDoesNotDeleteOthersLock 只删自己的锁。
+//
+// 场景：本进程的锁被判陈旧后，另一个实例抢到并写下自己的 pid。此时本进程
+// 收尾执行 Release —— 如果无脑删文件，会把别人的互斥一起清掉，两个实例并存。
+func TestReleaseDoesNotDeleteOthersLock(t *testing.T) {
+	dataDir := lockInTemp(t)
+	path := lockPathOf(dataDir)
+	lk, _, err := AcquireSingleInstance(dataDir, 0)
+	if err != nil || lk == nil {
+		t.Fatalf("拿锁失败：%v", err)
+	}
+	// 模拟锁被他人接手
+	writeHolder(t, path, SingleInstanceHolder{PID: os.Getpid() + 1<<20, Since: time.Now()})
+	lk.Release()
+	if _, statErr := os.Stat(path); statErr != nil {
+		t.Error("Release 删掉了别人的锁文件")
+	}
+}
+
+// TestReleaseIsIdempotent 重复 Release 不炸。
+func TestReleaseIsIdempotent(t *testing.T) {
+	dataDir := lockInTemp(t)
+	lk, _, err := AcquireSingleInstance(dataDir, 0)
+	if err != nil || lk == nil {
+		t.Fatalf("拿锁失败：%v", err)
+	}
+	lk.Release()
+	lk.Release()
+	var nilLock *SingleInstanceLock
+	nilLock.Release() // nil 也要安全
+}
+
+// TestSingleInstanceConflictMessage 报错文本必须说清「该去停谁」。
+//
+// 这条不是文字洁癖：用户看到「已在运行」只会去换端口，换端口解决不了问题
+// （两份实例照样抢作业目录）。必须明确指向 pid 与 stop 命令。
+func TestSingleInstanceConflictMessage(t *testing.T) {
+	msg := SingleInstanceConflictMessage(&SingleInstanceHolder{
+		PID: 4321, Port: 9100, Version: "2.6.2",
+		Exe:   "/opt/magic-client",
+		Since: time.Now().Add(-2 * time.Minute),
+	})
+	for _, want := range []string{"4321", "9100", "2.6.2", "magic-client stop", "/opt/magic-client"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("报错文本缺少 %q：\n%s", want, msg)
+		}
+	}
+	if msg := SingleInstanceConflictMessage(nil); !strings.Contains(msg, "magic-client stop") {
+		t.Errorf("holder 为空时也要给出可执行的下一步：%s", msg)
+	}
+}
+
+// skipIfKillBlocked 本环境里 agent.KillPID 是否真的生效。
+//
+// 有的沙箱会**静默吞掉** kill：syscall.Kill 返回 nil（没报错），进程照旧活着。
+// 注意探针**必须**走 agent.KillPID —— os/exec 的 Process.Kill 在 runtime 里有另一条
+// 路径，在沙箱里通常照样成功，拿它当判据会得出「kill 好用」的错误结论（本轮实测过）。
+func skipIfKillBlocked(t *testing.T) {
+	t.Helper()
+	cmd := exec.Command("sleep", "30")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来探针进程：%v", err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+	pid := cmd.Process.Pid
+	_ = agent.KillPID(pid, false)
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if !lockPIDAlive(pid) {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Skip("这个环境里 kill 被拦截（返回成功但进程杀不掉），跳过「停掉进程」类断言")
+}
+
+// TestStopReclaimsLockHolderWithoutState `magic-client stop` 必须能停掉**不写状态文件**
+// 的实例（前台 serve / 旧版 *.stale）。
+//
+// 为什么：2026-10-26 的现场就是这个 —— 8977 与 54428 上各挂着一份前台 serve，
+// 状态文件不存在，`stop` 答「本来就没在跑」，用户只能手工 kill。没有这条，
+// 单实例锁反而会把用户锁死（新实例被挡在门外，旧实例又停不掉）。
+func TestStopReclaimsLockHolderWithoutState(t *testing.T) {
+	skipIfKillBlocked(t)
+	dataDir := lockInTemp(t)
+	lockPath := lockPathOf(dataDir)
+
+	// 起一个替身进程，用它充当「另一份不写状态文件的实例」。
+	cmd := exec.Command("sleep", "60")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来替身进程：%v", err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+
+	writeHolder(t, lockPath, SingleInstanceHolder{
+		PID: cmd.Process.Pid, Port: 8977, Exe: "/opt/magic-client.stale", Since: time.Now(),
+	})
+
+	statePath := filepath.Join(t.TempDir(), "client.json")
+	stopped, st, err := StopDaemon(StopOptions{
+		StatePath: statePath, AlsoLockHolder: true, DataDir: dataDir,
+	})
+	if err != nil {
+		t.Fatalf("StopDaemon: %v", err)
+	}
+	if !stopped {
+		t.Fatalf("没停掉锁持有者（st=%+v）—— 用户会陷入「新的起不来、旧的停不掉」", st)
+	}
+	if st == nil || st.PID != cmd.Process.Pid {
+		t.Errorf("回告的实例 = %+v，期望 pid=%d", st, cmd.Process.Pid)
+	}
+	if lockPIDAlive(cmd.Process.Pid) {
+		t.Error("替身进程还活着")
+	}
+	if _, err := os.Stat(lockPath); !os.IsNotExist(err) {
+		t.Errorf("锁文件没清掉（err=%v）：下次启动会走「持有者已死」的回收路径", err)
+	}
+}
+
+// TestStopLeavesLockHolderWhenNotAsked restart 走的是同一条 StopDaemon，
+// 但它绝不能顺手停掉前台实例 —— 参数无从重建，等于「先把用户手上的调试会话杀了再报错」。
+func TestStopLeavesLockHolderWhenNotAsked(t *testing.T) {
+	dataDir := lockInTemp(t)
+	lockPath := lockPathOf(dataDir)
+	cmd := exec.Command("sleep", "60")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来替身进程：%v", err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+	writeHolder(t, lockPath, SingleInstanceHolder{PID: cmd.Process.Pid, Since: time.Now()})
+
+	statePath := filepath.Join(t.TempDir(), "client.json")
+	stopped, _, err := StopDaemon(StopOptions{StatePath: statePath})
+	if err != nil {
+		t.Fatalf("StopDaemon: %v", err)
+	}
+	if stopped {
+		t.Error("没要求也去停了锁持有者")
+	}
+	if !lockPIDAlive(cmd.Process.Pid) {
+		t.Error("替身进程被误杀")
+	}
+}
+
+// TestLockPIDAlive 探活判据。
+func TestLockPIDAlive(t *testing.T) {
+	if !lockPIDAlive(os.Getpid()) {
+		t.Error("自己应该是活的")
+	}
+	if lockPIDAlive(0) || lockPIDAlive(-1) {
+		t.Error("非法 pid 应判死")
+	}
+	dead := deadPID(t)
+	if lockPIDAlive(dead) {
+		t.Errorf("已退出的 pid %d 被误判为活", dead)
+	}
+}
+
+/* ── AppID 级占用登记（2026-10-26 补，治 DataDir 漂移）── */
+
+// claimInTemp 把 AppID 登记目录指到临时目录。
+func claimInTemp(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv(EnvAppIDLockDir, dir)
+	t.Setenv(EnvLockPath, "") // DataDir 锁落到各自 dataDir 下
+	return dir
+}
+
+// TestAppIDClaimBlocksDriftedDataDir 同一 AppID 换了数据目录也要被挡住。
+//
+// 这是本轮最要紧的一条：实测本机 magic-test 既有 ~/.magic-test（profile 写了
+// storage.dir）又有 ~/.magic-client/magic-test（profile 没读到，回落到 AppID 推导）。
+// 两条路径各自一把 DataDir 锁 → **两份都放行**，而作业记录不互通 →
+// 「手机连着 A，任务在 B 里跑完，界面没有收到任何输出」。只看 DataDir 防不住这个。
+func TestAppIDClaimBlocksDriftedDataDir(t *testing.T) {
+	claimDir := claimInTemp(t)
+
+	/* 用一个**真实存活的替身进程**占住 AppID 登记，而不是用本进程 pid。
+	   为什么：AcquireAppIDClaim 对「pid == 自己」有幂等续期分支（同一进程重复调用
+	   不该被自己挡），用本进程 pid 会走到那条分支上，测不到漂移判定。
+	   替身进程必须活着 —— 死了会被判陈旧回收，同样测不到。 */
+	cmd := exec.Command("sleep", "30")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来替身进程：%v", err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+
+	if err := os.MkdirAll(claimDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	occupiedDir := t.TempDir()
+	writeHolder(t, filepath.Join(claimDir, "com.magic.test.lock"), SingleInstanceHolder{
+		PID: cmd.Process.Pid, DataDir: occupiedDir, Since: time.Now(),
+	})
+
+	// 同一 AppID、另一个数据目录（模拟 storage.dir 丢失后的漂移）。
+	driftedDir := t.TempDir()
+	lk, holder, which, err := AcquireInstanceLocks("com.magic.test", driftedDir, 0)
+	if err != nil {
+		t.Fatalf("不该返回 IO 错误：%v", err)
+	}
+	if lk != nil {
+		lk.Release()
+		t.Fatal("同一 AppID 换了数据目录竟然放行了 —— 这就是 DataDir 漂移漏洞")
+	}
+	if which != "appid" {
+		t.Errorf("which = %q，期望 \"appid\"（要能区分是哪一道闸门挡的）", which)
+	}
+	if holder == nil || holder.PID != cmd.Process.Pid {
+		t.Fatalf("没报出占用者：%+v", holder)
+	}
+	if !samePath(holder.DataDir, occupiedDir) {
+		t.Errorf("占用者的 DataDir = %q，期望 %q —— 用户靠它才知道该去停哪个目录的实例",
+			holder.DataDir, occupiedDir)
+	}
+}
+
+// TestAppIDClaimAllowsDifferentApps 不同 AppID 必须互不影响（magic-test 与 magic-agent 并存）。
+func TestAppIDClaimAllowsDifferentApps(t *testing.T) {
+	claimInTemp(t)
+
+	lkA, hA, _, err := AcquireInstanceLocks("com.magic.test", t.TempDir(), 8977)
+	if err != nil || lkA == nil {
+		t.Fatalf("magic-test 没起来：err=%v holder=%+v", err, hA)
+	}
+	defer lkA.Release()
+
+	lkB, hB, which, err := AcquireInstanceLocks("magic-client", t.TempDir(), 9100)
+	if err != nil || lkB == nil {
+		t.Fatalf("不同 AppID 被挡住了（which=%s holder=%+v）—— 这就是误伤 8977 网关的那个 bug", which, hB)
+	}
+	defer lkB.Release()
+}
+
+// TestAppIDClaimAllowsSameDataDir 同一 AppID 同一数据目录时，AppID 这道不挡，交给 DataDir 锁判。
+//
+// 为什么：同一份实例重复调用一次（或 CLI 先探一次再真起）不该被自己挡两道。
+// 判据要区分是哪一道挡的 —— 报错文案完全不同，用户照做的动作也不同。
+func TestAppIDClaimAllowsSameDataDir(t *testing.T) {
+	claimDir := claimInTemp(t)
+	sharedDir := t.TempDir()
+
+	// 替身进程占住「同一 AppID + 同一数据目录」（见上一条注释：不能用本进程 pid）。
+	cmd := exec.Command("sleep", "30")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("起不来替身进程：%v", err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+
+	if err := os.MkdirAll(claimDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeHolder(t, filepath.Join(claimDir, "app.one.lock"), SingleInstanceHolder{
+		PID: cmd.Process.Pid, DataDir: sharedDir, Since: time.Now(),
+	})
+	// DataDir 锁也占上（模拟那个进程真的起来了）。
+	dirLock, _, err := AcquireSingleInstance(sharedDir, 0)
+	if err != nil || dirLock == nil {
+		t.Fatalf("预置 DataDir 锁失败：%v", err)
+	}
+	defer dirLock.Release()
+
+	lk, holder, which, err := AcquireInstanceLocks("app.one", sharedDir, 0)
+	if err != nil {
+		t.Fatalf("不该是 IO 错误：%v", err)
+	}
+	if lk != nil {
+		lk.Release()
+		t.Fatal("同一数据目录上起了两份 —— DataDir 锁失效了")
+	}
+	if which != "datadir" {
+		t.Errorf("which = %q，期望 \"datadir\"（同一目录不该报成「换了目录」）", which)
+	}
+	if holder == nil {
+		t.Error("没报出占用者")
+	}
+}
+
+// TestAppIDClaimReclaimsDeadHolder 持有者已死 → 回收，不把用户永久锁在门外。
+func TestAppIDClaimReclaimsDeadHolder(t *testing.T) {
+	dir := claimInTemp(t)
+	dead := deadPID(t)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeHolder(t, filepath.Join(dir, "app.dead.lock"), SingleInstanceHolder{
+		PID: dead, DataDir: t.TempDir(), Since: time.Now(),
+	})
+
+	lk, holder, which, err := AcquireInstanceLocks("app.dead", t.TempDir(), 0)
+	if err != nil || lk == nil {
+		t.Fatalf("持有者已死却没回收：err=%v holder=%+v which=%s", err, holder, which)
+	}
+	lk.Release()
+}
+
+// TestAcquireInstanceLocksReleasesBothOnFailure DataDir 挡下时必须把已拿到的 AppID 登记放掉。
+//
+// 否则会留下一条指向本进程的登记 —— 本进程还活着，它就不会被判陈旧，
+// 于是「另一份想用别的目录起」会一直被挡，直到本进程退出。这个泄漏极难排查。
+func TestAcquireInstanceLocksReleasesBothOnFailure(t *testing.T) {
+	claimDir := claimInTemp(t)
+	sharedDir := t.TempDir()
+
+	// 先在 sharedDir 上占住 DataDir 锁（模拟「这个目录上已有一份在跑」）。
+	other, _, err := AcquireSingleInstance(sharedDir, 0)
+	if err != nil || other == nil {
+		t.Fatalf("预置锁失败：%v", err)
+	}
+	defer other.Release()
+
+	lk, _, which, err := AcquireInstanceLocks("app.leak", sharedDir, 0)
+	if err != nil {
+		t.Fatalf("不该是 IO 错误：%v", err)
+	}
+	if lk != nil {
+		lk.Release()
+		t.Fatal("不该拿到锁")
+	}
+	if which != "datadir" {
+		t.Errorf("which = %q，期望 datadir", which)
+	}
+	// 关键：AppID 登记必须被清掉。
+	claimPath := filepath.Join(claimDir, "app.leak.lock")
+	if _, statErr := os.Stat(claimPath); !os.IsNotExist(statErr) {
+		t.Errorf("DataDir 挡下后 AppID 登记泄漏了（%s 还在）—— 之后换目录也起不来", claimPath)
+	}
+}
+
+// TestSanitizeAppID AppID 里的点与斜杠不能变成路径分隔符。
+func TestSanitizeAppID(t *testing.T) {
+	cases := map[string]string{
+		"com.magic.test": "com.magic.test", // 点保留（bundleId 的常态）
+		"a/b":            "a_b",            // 斜杠必须换掉，否则写到别的目录
+		"../evil":        ".._evil",
+		"":               "unknown",
+		"名字":             "unknown", // 只留 ASCII，全被换掉后兜底
+	}
+	for in, want := range cases {
+		if got := sanitizeAppID(in); got != want {
+			t.Errorf("sanitizeAppID(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestSamePath 同一目录的判定（~ 展开、相对路径、符号链接）。
+func TestSamePath(t *testing.T) {
+	dir := t.TempDir()
+	if !samePath(dir, dir) {
+		t.Error("同一路径应判同一份")
+	}
+	if !samePath(dir, dir+"/") {
+		t.Error("末尾斜杠不该算两个目录")
+	}
+	if !samePath(dir, dir+"/.") {
+		t.Error("./ 不该算两个目录")
+	}
+	if samePath(dir, t.TempDir()) {
+		t.Error("不同目录被判成同一份")
+	}
+	if samePath("", dir) || samePath(dir, "") {
+		t.Error("空路径不该算同一份")
+	}
+}
+
+// TestAppIDConflictMessage 报错必须说清「换目录不算两份应用」。
+func TestAppIDConflictMessage(t *testing.T) {
+	msg := AppIDConflictMessage("com.magic.test", &SingleInstanceHolder{
+		PID: 4321, DataDir: "/Users/x/.magic-test", Version: "2.6.2",
+		Exe: "/opt/magic-client", Since: time.Now().Add(-3 * time.Minute),
+	})
+	for _, want := range []string{"com.magic.test", "4321", "/Users/x/.magic-test", "magic-client stop"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("报错文本缺少 %q：\n%s", want, msg)
+		}
+	}
+	if m := AppIDConflictMessage("x", nil); !strings.Contains(m, "magic-client stop") {
+		t.Errorf("holder 为空时也要给出可执行的下一步：%s", m)
+	}
+}