magic-agent 2.4.3 → 2.6.3

package/internal/client/requirements_test.go

@@ -288,3 +288,106 @@ func TestAutoConsolidateMarksAuto(t *testing.T) {
 		t.Errorf("自动归纳应带 --requirement-auto，实际 %v", readCalls(t, logPath))
 	}
 }
+
+// TestAutoConsolidateUsesDefaultEngine 自动归纳要和手动「整理」同一个口径：
+// 用「我的 → 默认引擎/模型」（/desk/prefs 存的那份），而不是固定 llm。
+//
+// 2026-10-26 用户：「手动自动都要默认设置的引擎」。改之前自动路径硬传空串，
+// 界面上配了 dsh 也没用，后台永远走 llm 的默认模型。
+func TestAutoConsolidateUsesDefaultEngine(t *testing.T) {
+	// 隔离家目录：mobile-prefs.json 落这里（Windows 读 USERPROFILE，两边都设）。
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	if err := os.MkdirAll(filepath.Join(home, ".magic-agent"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	prefs := `{"magic.engine":"dsh","magic.model":"modelverse/deepseek-v4.1-flash-1017",` +
+		`"magic.fallback.engine":"claude","magic.fallback.model":"opus"}`
+	if err := os.WriteFile(filepath.Join(home, ".magic-agent", "mobile-prefs.json"),
+		[]byte(prefs), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	core := reqCore(t, `"feature.session.events","feature.session.control",`+
+		`"`+FeatureRequirements+`"`, logPath)
+	svc := newTestService(t, core)
+	svc.runAutoConsolidate("/proj")
+
+	var line string
+	for _, c := range readCalls(t, logPath) {
+		if strings.Contains(c, "--consolidate-requirements /proj") {
+			line = c
+		}
+	}
+	if line == "" {
+		t.Fatalf("自动归纳没调 core：%v", readCalls(t, logPath))
+	}
+	if !strings.Contains(line, "--requirement-engine dsh") {
+		t.Errorf("自动归纳应带默认引擎 dsh，实际 %q", line)
+	}
+	if !strings.Contains(line, "--requirement-model modelverse/deepseek-v4.1-flash-1017") {
+		t.Errorf("自动归纳应带默认模型，实际 %q", line)
+	}
+	if !strings.Contains(line, "--requirement-auto") {
+		t.Errorf("带上引擎也不能丢 --requirement-auto，实际 %q", line)
+	}
+	// 备用引擎是「主引擎失败才切」的，绝不能当成默认值顶上。
+	if strings.Contains(line, "claude") || strings.Contains(line, "opus") {
+		t.Errorf("自动归纳不该用备用引擎，实际 %q", line)
+	}
+}
+
+// TestAutoConsolidateNoPrefsFallsBack 没配过默认引擎 = 不传，交给 core 的默认（llm）。
+// 既不能编一个引擎出来，也不能因为文件缺失让后台路径报错。
+func TestAutoConsolidateNoPrefsFallsBack(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home) // 没有 mobile-prefs.json
+
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	core := reqCore(t, `"feature.session.events","feature.session.control",`+
+		`"`+FeatureRequirements+`"`, logPath)
+	svc := newTestService(t, core)
+	svc.runAutoConsolidate("/proj")
+
+	var line string
+	for _, c := range readCalls(t, logPath) {
+		if strings.Contains(c, "--consolidate-requirements /proj") {
+			line = c
+		}
+	}
+	if line == "" {
+		t.Fatalf("自动归纳没调 core：%v", readCalls(t, logPath))
+	}
+	if strings.Contains(line, "--requirement-engine") || strings.Contains(line, "--requirement-model") {
+		t.Errorf("没配默认引擎时不该带引擎/模型，实际 %q", line)
+	}
+}
+
+// TestAutoConsolidateRespectsEngineWhitelist profile 白名单外的默认引擎不能让自动归纳
+// 每轮都失败（core 会 403）：传空回落 core 默认，而不是硬传。
+func TestAutoConsolidateRespectsEngineWhitelist(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	if err := os.MkdirAll(filepath.Join(home, ".magic-agent"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(home, ".magic-agent", "mobile-prefs.json"),
+		[]byte(`{"magic.engine":"dsh","magic.model":"m"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := newTestService(t, reqCore(t, `"feature.session.events","feature.session.control",`+
+		`"`+FeatureRequirements+`"`, logPath))
+	svc.opts.Profile.Engines = []string{"claude"}
+	svc.runAutoConsolidate("/proj")
+
+	for _, c := range readCalls(t, logPath) {
+		if strings.Contains(c, "--requirement-engine") {
+			t.Errorf("白名单外的引擎不该透传，实际 %q", c)
+		}
+	}
+}

package/internal/client/restart.go

@@ -0,0 +1,288 @@
+package client
+
+/* restart.go - `POST /desk/restart`：让手机上「我的 → 重启服务」能重启桌面端客户端。
+ *
+ * ── 为什么不能在本进程里直接做 ──
+ * 重启 = 停掉自己再拉起自己。StopDaemon 会 TerminatePID 本进程，写在同一个进程里
+ * 等于「自杀到一半」：响应发不出去、后面的 start 也轮不到。
+ * 所以这里只做三件事：**先立标志、先答 200、再由进程内定时器拉起**一个脱离终端的
+ * `magic-client restart` 助手；助手停旧实例、按状态文件里的参数拉起新实例
+ * （见 daemon.go 的 RestartDaemon）。
+ *
+ * ── 地址变了怎么办（2026-10-25 用户：「重启后如果地址变化了也要刷新原环境的连接地址和token」）──
+ * 令牌跨重启稳定（token 文件），地址却未必：换网 / 换 Wi-Fi 后网卡 IP 变了、状态文件丢了
+ * 换了令牌、端口撞了。手机存的是「地址 + 令牌」，旧的就永远连不上。解法是让**旧实例**
+ * 在死之前把「新实例的手机入口 + 令牌」挂到自己的 /desk/health 上（restartHandoff）：
+ * 手机探活时顺走，改完地址与令牌再连（见 client-ui-mobile 的 restartClient）。
+ *
+ * ── 为什么要「先标志、定时器后触发」（2026-10-25 用户定调）──
+ * 旧链路在 handler 里当场 spawn 带 `--delay 1s` 的助手，两个毛病：
+ *  ① 重复点击（双击 / 手机重试 / 两台设备同时点）各起一个助手，两个助手互相把对方
+ *     刚拉起的实例停掉 —— 端口抢占，手机 30 秒以上还「重启后连不上」；
+ *  ② 助手在 handler 里就起身，与「响应 flush 回手机」只隔一个 --delay，先后靠运气。
+ * 新链路：标志让重复点击变成一句「已在重启中」（幂等，不再排第二个定时器）；
+ * 定时器到点才拉助手，严格晚于 handler 返回 —— 响应一定先落地，服务才可能被杀。
+ * 标志同时经 /desk/health.restarting 带出去：手机探活看到它 = 旧实例认账、即将下线。
+ *
+ * ── 为什么先校验状态文件 ──
+ * 重启参数全来自 `~/.magic-client/client.json`。如果那个文件不存在（前台 serve 起的）
+ * 或指向的不是本进程（同机跑着两个实例），照着它重启会重启**别人**。两种都当场拒绝，
+ * 让手机看到能落地的一句话，而不是「点了没反应」。
+ */
+
+import (
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// restartDelay 定时器等多久再拉助手：给这次 200 响应留落地时间。
+// 是 var 不是 const：测试里改小，不用真等一秒。
+var restartDelay = time.Second
+
+// restartHandoffTTL 旧实例认账、把「新实例的地址 + 令牌」经 /desk/health 交代出去的时长。
+//
+// 为什么需要（2026-10-25 用户：「重启后如果地址变化了也要刷新原环境的连接地址和token」）：
+// 手机里存的是「地址 + 令牌」。令牌跨重启稳定，地址却会变 —— 换了 Wi-Fi / 热点、watchdog
+// 起了另一个监听地址、状态文件丢了重发了一个令牌……新实例起来后旧地址就**永远**连不上了，
+// 手机只能看到一片「连不上」，不知道新地址是什么。而旧实例恰恰在「刚答完 200、还没死」的那
+// 一小段里能算出新实例的地址（按即将生效的参数），所以让它把结论挂在自己的 /desk/health 上，
+// 手机在探活时顺手取走，改完地址与令牌再连。
+//
+// 2 分钟 ≈ 助手停旧起新的正常耗时（3–7 秒，抢端口时见过 30 秒以上）的余量：
+// 新实例真起来后旧实例就没了，这段窗口只是兜住「新实例没起来时旧实例还活着」的情形。
+const restartHandoffTTL = 2 * time.Minute
+
+// restartHandoffMu 守着下面那组交接结果（定时器 goroutine 写、handler 读）。
+var (
+	restartHandoffMu    sync.Mutex
+	restartHandoffURLs  []string // 新实例的手机可用入口（不带令牌，形如 http://10.0.0.5:9100/）
+	restartHandoffToken string   // 新实例的令牌（同机局域网门锁，只回给已持令牌的 /desk/health）
+	restartHandoffUntil time.Time
+)
+
+// setRestartHandoff 记下「新实例会是什么样」，供 /desk/health 交代出去。
+func setRestartHandoff(urls []string, token string) {
+	restartHandoffMu.Lock()
+	defer restartHandoffMu.Unlock()
+	restartHandoffURLs = append([]string(nil), urls...)
+	restartHandoffToken = token
+	restartHandoffUntil = time.Now().Add(restartHandoffTTL)
+}
+
+// restartHandoff 当前该交代的新实例信息；现在不该交代 → nil。
+//
+// 正常情况下（旧实例已经出过交接）就按交接本身交代，不论重启标志：手机可能在
+// restarting 变 true 之后就取走了、第二次探活发生在标志被复位/用例隔离之后。
+// 什么都没交接（进程刚起来）→ 不交代。
+func restartHandoff() map[string]any {
+	if !restartRequested() && !restartHandoffArmed() {
+		return nil
+	}
+	restartHandoffMu.Lock()
+	defer restartHandoffMu.Unlock()
+	if time.Now().After(restartHandoffUntil) {
+		return nil
+	}
+	if len(restartHandoffURLs) == 0 && restartHandoffToken == "" {
+		return nil
+	}
+	return map[string]any{
+		"urls":  append([]string(nil), restartHandoffURLs...),
+		"token": restartHandoffToken,
+	}
+}
+
+// restartHandoffArmed 是否真的出过一次交接（与过期无关）。
+func restartHandoffArmed() bool {
+	restartHandoffMu.Lock()
+	defer restartHandoffMu.Unlock()
+	return !restartHandoffUntil.IsZero()
+}
+
+// handoffOfPlan 按重启助手要用的启动参数，算出新实例的入口与令牌。
+//
+// 顺序有讲究：**公网域名排第一**。隧道是壳起的、magic-client 重启不碰它，所以域名是
+// 「重启后最不容易失效」的入口（2026-10-25 用户：「重启也尽量不要变 cloudflare 域名
+// 就可以了」）。局域网地址排在后面，只在没开公网时才当主入口。
+//
+// 端口：新实例显式 `--addr` 时就是它；局域网实例没写 addr 时 serve 侧固定绑
+// DefaultLanAddr（见 cmd/magic-client/main.go），RestartDaemon → StartDaemon 也显式带上。
+// 两侧都拿不到端口 = 会退化成随机端口，算不准就不报局域网地址。
+// 本地回环（127.0.0.1:端口）对手机没用，不放进 urls。
+func handoffOfPlan(plan *DaemonState, publicURL string) ([]string, string) {
+	if plan == nil {
+		return nil, ""
+	}
+	token := strings.TrimSpace(plan.Token)
+	var out []string
+	if u := strings.TrimRight(strings.TrimSpace(publicURL), "/"); u != "" {
+		out = append(out, u+"/")
+	}
+	if !plan.Lan {
+		return out, token
+	}
+	listen := strings.TrimSpace(plan.Addr)
+	if listen == "" {
+		listen = DefaultLanAddr
+	}
+	host, portStr, err := net.SplitHostPort(listen)
+	if err != nil {
+		return out, token
+	}
+	port, err := strconv.Atoi(portStr)
+	if err != nil || port <= 0 {
+		return out, token
+	}
+	if ip := net.ParseIP(host); ip != nil && ip.IsLoopback() {
+		return out, token // 只绑了回环：手机够不着，别报一个连不上的地址
+	}
+	for _, a := range LanAddresses(port) {
+		out = append(out, "http://"+a+"/")
+	}
+	return out, token
+}
+
+// restartPending 本进程是否已受理过一次重启（「标志」）。
+//
+// 为什么必须在服务端记：重复点击的对手不只是这一台手机 —— 手机重试、另一台设备
+// 同时点，都会各带一个 POST 过来。没有标志就会各排一个定时器、各起一个助手，
+// 两个助手互相把对方刚拉起的实例停掉（端口抢占，输家要等 ready 超时）。
+var (
+	restartMu      sync.Mutex
+	restartPending bool
+)
+
+// restartSpawner 定时器到点时真正干活的人：脱离终端拉一个 `magic-client restart`
+// 助手停旧起新。包级变量是为了测试能换成不碰真进程的假动作。
+var restartSpawner = spawnRestartHelper
+
+// restartOnTimer 定时器到点时做的事：先把「新实例的样子」挂到 /desk/health 上交代出去，
+// 再拉助手。交接必须抢在停旧实例（spawn 之后秒级）之前，否则手机根本来不及取。
+// 是 var 而不是直接调：用例要能观察「交接在助手起身之前就有了」。
+var restartOnTimer = func(st *DaemonState, publicURL, exe string, lg *log.Logger) {
+	// 新实例的启动参数 = 旧实例状态文件里那一套（RestartDaemon → StartDaemon 原样用）。
+	urls, token := handoffOfPlan(st, publicURL)
+	setRestartHandoff(urls, token)
+	restartSpawner(exe, lg, statePathOf(st))
+}
+
+// statePathOf 这份状态记录自己所在的路径（重启助手要照着它去找回同一份参数）。
+func statePathOf(st *DaemonState) string {
+	if st == nil {
+		return ""
+	}
+	return st.StatePath
+}
+
+// restartRequested 本进程是否已受理过重启。/desk/health 带这个字段，
+// 手机据此把「旧实例认账」当成「它马上要下线」，不必等连接真的断。
+func restartRequested() bool {
+	restartMu.Lock()
+	defer restartMu.Unlock()
+	return restartPending
+}
+
+// handleRestart 重启后台实例（手机「我的」页那枚按钮）。
+func (s *Service) handleRestart(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	/* 认领自己（2026-10-26 用户：「通过 magic-test 启动的无法在移动端点击重启服务重启」）。
+	 *
+	 * 这里原来只读 DefaultStatePath()（= `magic-client start` 的 client.json），
+	 * 于是**前台 serve** 一律撞 409「当前实例不是后台启动的」。而 magic-test 的桥接正是
+	 * `spawn(bin, ['serve', ...])` 起的实例 —— 手机上连的就是它，按钮永远点不动。
+	 *
+	 * selfDaemonState() 是「按本进程 pid 认领状态文件」的通用实现（先看 --state / 环境变量，
+	 * 再扫目录里 client*.json），前台 serve 现在也登记了自己那份（serve.json），
+	 * 两条启动路径因此共用同一条重启链路。
+	 *
+	 * 仍然拒绝「状态文件指向别人」：同机可能跑着好几个实例，重启错的等于把别人的服务踢掉。 */
+	st := s.selfDaemonState()
+	if st == nil {
+		/* 分两种说法，别让人对着同一句话反复试：
+		   · 目录里**有**别人的登记 → 这台进程是手工 serve 且没登记（老版本 / 显式跳过），
+		     只能去终端重启；
+		   · 目录里一份都没有 → 从没 start 过，也没新版本的自登记。 */
+		writeErr(w, http.StatusConflict,
+			"这个实例没有可用的状态记录（不是 `magic-client start` 起的，也不是登记过自己的 serve）："+
+				"不能自重启。请到桌面终端执行 magic-client restart，或用 magic-client start 重启服务")
+		return
+	}
+	exe, err := os.Executable()
+	if err != nil {
+		writeErr(w, http.StatusInternalServerError, "定位自身可执行文件失败："+err.Error())
+		return
+	}
+
+	/* 标志：本进程已受理过一次重启。重复点击（双击 / 手机重试 / 另一台设备同时点）
+	   直接答「已在重启中」—— 不再排第二个定时器、不再起第二个助手。 */
+	restartMu.Lock()
+	if restartPending {
+		restartMu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]any{
+			"ok": true, "restarting": true, "already_pending": true, "pid": os.Getpid(),
+		})
+		return
+	}
+	restartPending = true
+	restartMu.Unlock()
+
+	// 先答，再让定时器触发：handler 返回后响应才真正落回手机，AfterFunc 在这一刻
+	// 之后才跑 —— 助手起身严格晚于响应落地，不存在「先把服务杀了、响应卡在缓冲区」。
+	writeJSON(w, http.StatusOK, map[string]any{
+		"ok":         true,
+		"restarting": true,
+		"pid":        os.Getpid(),
+	})
+	/* 公网域名要在**启动定时器之前**取：它是「重启后最不容易失效」的入口
+	   （隧道由壳托管、客户端重启不碰它），必须进交接里告诉手机。 */
+	pub := s.publicURLOrEmpty()
+	time.AfterFunc(restartDelay, func() { restartOnTimer(st, pub, exe, s.log) })
+	s.log.Printf("收到重启请求：%s 后由定时器拉起助手停旧起新（旧实例即将停止）；"+
+		"期间 /desk/health 会交代新实例的地址与令牌", restartDelay)
+}
+
+// spawnRestartHelper 脱离终端拉一个 `magic-client restart` 助手：它停旧实例、按状态
+// 文件里的参数起新实例。不带 --delay —— 定时器已经等过 restartDelay 了。
+//
+// ⚠️ `--state` 必须显式传（2026-10-26）：助手默认读 ~/.magic-client/client.json，
+// 而本进程可能是**前台 serve**（magic-test 桥接那种），它的登记在 <数据目录>/serve.json。
+// 不传的话助手会去重启**另一个**实例 —— 最坏情况是把同机 9100 那个 `start` 实例停掉，
+// 而用户手机连着的这个照旧活着：界面上就是「点了重启，连的那个没动静，另一个却重启了」。
+func spawnRestartHelper(exe string, lg *log.Logger, statePath string) {
+	logPath := DefaultLogPath()
+	var logf *os.File
+	if logPath != "" {
+		logf, _ = os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	}
+	args := []string{"restart"}
+	if p := strings.TrimSpace(statePath); p != "" {
+		args = append(args, "--state", p)
+	}
+	cmd := exec.Command(exe, args...)
+	if logf != nil {
+		cmd.Stdout, cmd.Stderr = logf, logf
+	}
+	detach(cmd)
+	if err := cmd.Start(); err != nil {
+		if lg != nil {
+			lg.Printf("重启失败（spawn %s restart）：%v（手机侧可去桌面执行 magic-client restart）", exe, err)
+		}
+		_ = logf.Close()
+		return
+	}
+	// 子进程已拿到自己的句柄：父进程这份可以关了（它马上要被停）。
+	_ = logf.Close()
+	if lg != nil {
+		lg.Printf("重启助手已启动：%s restart --state %s（旧实例即将停止）", exe, statePath)
+	}
+}

package/internal/client/restart_handoff_test.go

@@ -0,0 +1,230 @@
+package client
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+/*
+重启交接（2026-10-25 用户：「重启后如果地址变化了也要刷新原环境的连接地址和token」）：
+
+	旧实例受理重启后，在定时器到点、停自己之前，把「新实例的手机入口 + 令牌」挂到
+	/desk/health.restartHandoff 上；手机探活时取走，改完原环境再连。
+*/
+
+func resetRestartHandoffForTest() {
+	restartHandoffMu.Lock()
+	restartHandoffURLs, restartHandoffToken, restartHandoffUntil = nil, "", time.Time{}
+	restartHandoffMu.Unlock()
+}
+
+// healthBody 打一次 /desk/health，返回原始 JSON。
+func healthBody(t *testing.T, svc *Service) map[string]any {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/desk/health", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("health = %d，want 200（body: %s）", rec.Code, rec.Body.String())
+	}
+	var out map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("解析 health 失败: %v（%s）", err, rec.Body.String())
+	}
+	return out
+}
+
+// 没受理重启 / 已过期 → 不带 restartHandoff（老语义：只有 restarting 标志）。
+// 受理后 → 带 urls + token；交接值在定时器到点（助手起身）之前就已有，不是等助手回来。
+func TestHealthRestartHandoff(t *testing.T) {
+	prof := DefaultProfile()
+	prof.Storage.Dir = t.TempDir()
+	svc := &Service{log: log.New(io.Discard, "", 0), opts: Options{Profile: prof}}
+
+	resetRestartPendingForTest()
+	resetRestartHandoffForTest()
+	defer resetRestartPendingForTest()
+	defer resetRestartHandoffForTest()
+
+	if raw, ok := healthBody(t, svc)["restartHandoff"]; ok && raw != nil {
+		armed := restartHandoffArmed()
+		restartHandoffMu.Lock()
+		until := restartHandoffUntil
+		restartHandoffMu.Unlock()
+		t.Fatalf("没重启时 restartHandoff 应为 null（json 里键常在、值为 null），实际 %v（armed=%v until=%v pending=%v）",
+			raw, armed, until, restartRequested())
+	}
+
+	setRestartHandoff([]string{"http://10.1.2.3:9100/"}, "new-token-0123456789abcdef")
+	got, ok := healthBody(t, svc)["restartHandoff"].(map[string]any)
+	if !ok {
+		t.Fatal("受理重启后 health 应带 restartHandoff")
+	}
+	if got["token"] != "new-token-0123456789abcdef" {
+		t.Errorf("restartHandoff.token = %v，want 新实例令牌", got["token"])
+	}
+	urls, _ := got["urls"].([]any)
+	if len(urls) != 1 || urls[0] != "http://10.1.2.3:9100/" {
+		t.Errorf("restartHandoff.urls = %v，want [http://10.1.2.3:9100/]", got["urls"])
+	}
+
+	// 过期（旧实例一直没被停掉）→ 不再交代，别让手机拿一份可能已过时的地址一直重连。
+	restartHandoffMu.Lock()
+	restartHandoffUntil = time.Now().Add(-time.Second)
+	restartHandoffMu.Unlock()
+	if raw := healthBody(t, svc)["restartHandoff"]; raw != nil {
+		t.Errorf("交接过期后 health 不该再带 restartHandoff，实际 %v", raw)
+	}
+	// 从没交接过的实例（刚起来）即便 restarting 被立着也不报空交接。
+	resetRestartHandoffForTest()
+	if raw := healthBody(t, svc)["restartHandoff"]; raw != nil {
+		t.Errorf("没算出交接内容时不该带空 restartHandoff，实际 %v", raw)
+	}
+}
+
+// 只绑回环 / 关掉局域网：手机够不着，不是「地址变了」，不交代（仍交代令牌 —— 令牌换了
+// 手机同样连不上，哪怕地址没变）。
+func TestHandoffOfPlanSkipsLoopback(t *testing.T) {
+	urls, token := handoffOfPlan(&DaemonState{Lan: false, Addr: "127.0.0.1:9100", Token: "tk-0123456789abcdef0123"}, "")
+	if len(urls) != 0 {
+		t.Errorf("只绑回环时不该报 URL，实际 %v", urls)
+	}
+	if token != "tk-0123456789abcdef0123" {
+		t.Errorf("令牌应原样带出，实际 %q", token)
+	}
+	if urls, _ := handoffOfPlan(nil, ""); urls != nil {
+		t.Errorf("没有状态文件时不该报 URL，实际 %v", urls)
+	}
+	// 局域网实例没写 addr：serve 侧固定绑 DefaultLanAddr，端口必须算成 9100 而不是 0。
+	urls, _ = handoffOfPlan(&DaemonState{Lan: true, Port: 9100, Token: "tk"}, "")
+	for _, u := range urls {
+		if !strings.HasSuffix(u, ":9100/") {
+			t.Errorf("局域网实例的入口应带默认端口 9100，实际 %q", u)
+		}
+		if strings.Contains(u, "127.0.0.1") || strings.Contains(u, "localhost") {
+			t.Errorf("不该把回环地址报给手机：%q", u)
+		}
+	}
+}
+
+// 公网域名排第一（2026-10-25 用户：「重启也尽量不要变 cloudflare 域名就可以了」）：
+// 隧道由壳托管、客户端重启不碰它，域名是重启后最不容易失效的入口。
+func TestHandoffOfPlanPrefersPublicURL(t *testing.T) {
+	urls, _ := handoffOfPlan(&DaemonState{Lan: true, Port: 9100, Token: "tk"}, "https://abc-xyz.trycloudflare.com")
+	if len(urls) == 0 || urls[0] != "https://abc-xyz.trycloudflare.com/" {
+		t.Fatalf("公网域名应排在交接第一位，实际 %v", urls)
+	}
+	// 只绑回环（--local）也照样交公网域名：手机走隧道，域名是唯一入口。
+	urls, _ = handoffOfPlan(&DaemonState{Lan: false, Addr: "127.0.0.1:9100", Token: "tk"}, "https://abc.trycloudflare.com")
+	if len(urls) != 1 || urls[0] != "https://abc.trycloudflare.com/" {
+		t.Errorf("--local 实例应只交公网域名，实际 %v", urls)
+	}
+}
+
+// 域名落盘后，重启（新进程）第一眼就能从 /desk/health 拿到它 —— 不必等探测。
+func TestPublicURLSurvivesRestart(t *testing.T) {
+	prof := DefaultProfile()
+	prof.Storage.Dir = t.TempDir()
+	svc := &Service{opts: Options{Profile: prof}}
+	svc.savePublicURL("https://keep-me.trycloudflare.com")
+
+	// 模拟重启：另一个 Service（同一 profile）没有内存缓存。
+	fresh := &Service{opts: Options{Profile: prof}, log: log.New(io.Discard, "", 0)}
+	got := fresh.publicURL()
+	if got != "https://keep-me.trycloudflare.com" {
+		t.Fatalf("重启后 publicURL = %q，want 落盘域名（否则手机会退回局域网地址）", got)
+	}
+	// 落盘值读进内存后应立刻可用，且不因为「第一次探测还没回来」而丢。
+	if fresh.pubURL == "" {
+		t.Error("落盘域名应已进内存缓存")
+	}
+}
+
+// 隧道真没了：连续两次探空、且过了宽限期才删落盘值（只探空一次就删太激进）。
+func TestSavedPublicURLClearedOnlyAfterRepeatedMiss(t *testing.T) {
+	prof := DefaultProfile()
+	prof.Storage.Dir = t.TempDir()
+	svc := &Service{opts: Options{Profile: prof}}
+
+	svc.savePublicURL("https://gone.trycloudflare.com")
+	svc.pubLoaded = true
+	svc.pubURL = "https://gone.trycloudflare.com"
+	svc.pubMiss = 0
+
+	// 第一次探空：宽限期内 → 域名顶着，文件也不删。
+	svc.pubGraceTo = time.Now().Add(publicGrace)
+	svc.applyProbeResult("")
+	if svc.pubURL != "https://gone.trycloudflare.com" {
+		t.Errorf("宽限期内探空不该撤掉已知域名，实际 %q", svc.pubURL)
+	}
+	if svc.loadSavedPublicURL() == "" {
+		t.Error("第一次探空不该删落盘域名")
+	}
+
+	// 宽限期结束 + 连续第二次探空 → 认定隧道没了：内存与落盘都清。
+	svc.pubGraceTo = time.Time{}
+	svc.applyProbeResult("")
+	if svc.pubURL != "" {
+		t.Errorf("两次探空后应清掉内存域名，实际 %q", svc.pubURL)
+	}
+	if v := svc.loadSavedPublicURL(); v != "" {
+		t.Errorf("两次探空后应删掉落盘域名，实际 %q", v)
+	}
+}
+
+// 定时器到点：先落交接，再拉助手（手机必须在旧实例被停之前就能取到新地址）。
+func TestRestartTimerHandsOffBeforeSpawn(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "client.json")
+	t.Setenv(EnvState, statePath)
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatal(err)
+	}
+	st := &DaemonState{PID: os.Getpid(), Port: 9100, Token: "old-token", Exe: exe, Lan: true}
+	if err := writeDaemonState(statePath, st); err != nil {
+		t.Fatal(err)
+	}
+
+	resetRestartPendingForTest()
+	resetRestartHandoffForTest()
+	defer resetRestartPendingForTest()
+	defer resetRestartHandoffForTest()
+
+	spawnedToken := make(chan string, 1)
+	oldSpawner := restartSpawner
+	restartSpawner = func(string, *log.Logger, string) {
+		// 助手起身的那一刻，交接必须已经在 /desk/health 上（否则手机来不及取）。
+		h, ok := restartHandoff()["token"].(string)
+		if !ok {
+			h = ""
+		}
+		spawnedToken <- h
+	}
+	defer func() { restartSpawner = oldSpawner }()
+	oldDelay := restartDelay
+	restartDelay = 50 * time.Millisecond
+	defer func() { restartDelay = oldDelay }()
+
+	s := &Service{log: log.New(io.Discard, "", 0)}
+	rec := httptest.NewRecorder()
+	s.handleRestart(rec, httptest.NewRequest(http.MethodPost, "/desk/restart", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST /desk/restart = %d，want 200（body: %s）", rec.Code, rec.Body.String())
+	}
+	select {
+	case tok := <-spawnedToken:
+		if tok != "old-token" {
+			t.Errorf("助手起身时交接里的令牌 = %q，want 状态文件里的令牌 old-token", tok)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("定时器没有拉起助手")
+	}
+}