magic-agent 1.0.1 → 1.0.3

package/internal/agent/custom_models_test.go

@@ -9,8 +9,11 @@ package agent
 //  2. 幂等：无新增时**不落盘**（内容逐字节不变）
 //  3. 只增不改：既有条目与未识别字段原样保留；availableModels 追加不丢
 //  4. 安全兜底：App 缓存缺失 / 条目 disabled → 不建文件、不报错
+//  5. 陌生文件一律不碰：顶层不是 JSON 对象（桌面端是数组）/ 坏 JSON → 逐字节保持原样，
+//     且覆盖写之前一定留 .magic-agent.bak（见 2026-09-30 Windows 事故用例）
 
 import (
+	"bytes"
 	"encoding/json"
 	"os"
 	"path/filepath"
@@ -182,11 +185,112 @@ func TestSyncCustomModelsFromApp_IdempotentAndMergeOnly(t *testing.T) {
 	}
 }
 
-func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
+// 目标文件顶层不是 JSON 对象（桌面端 WorkBuddy 的 models.json 就是**数组**）时，
+// 必须**一个字都不动**、也不留备份（因为压根没写）。
+//
+// 为什么是关键回归：以前把"解析不进 map"当空文件继续写回 {models, availableModels}，
+// 等于把对方的模型清单整体替换成只剩 custom-local 几条 —— 官方模型全丢且不可回滚。
+func TestSyncCustomModelsFromApp_RefusesNonObjectFile(t *testing.T) {
+	// 桌面端 models.json 的真实形状：顶层数组，条目是 LanguageModel。
+	desktop := []byte(`[
+  {
+    "id": "MiniMax-M3",
+    "name": "MiniMax-M3",
+    "vendor": "MiniMax",
+    "url": "https://api.minimaxi.com/v1/chat/completions",
+    "apiKey": "sk-user-own"
+  },
+  {
+    "id": "glm-5.3",
+    "name": "glm-5.3",
+    "url": "https://open.bigmodel.cn/api/paas/v4",
+    "apiKey": "sk-user-own-2"
+  }
+]`)
+
+	cases := []struct {
+		name    string
+		content []byte
+	}{
+		{"顶层是数组（桌面端格式）", desktop},
+		{"坏 JSON", []byte("{oops")},
+		{"顶层是字符串", []byte(`"just a string"`)},
+		{"顶层是数字", []byte(`42`)},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			acc := filepath.Join(dir, "acc.json")
+			writeJSON(t, acc, appCacheFixture())
+			cfg := filepath.Join(dir, "config")
+			if err := os.MkdirAll(cfg, 0o700); err != nil {
+				t.Fatal(err)
+			}
+			path := filepath.Join(cfg, customModelsFileName)
+			if err := os.WriteFile(path, tc.content, 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			added, err := syncCustomModelsFromApp(acc, cfg)
+			if err != nil {
+				t.Errorf("应静默跳过，不该报错: %v", err)
+			}
+			if added != 0 {
+				t.Errorf("added = %d, want 0", added)
+			}
+
+			after, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatalf("原文件必须还在: %v", err)
+			}
+			if !bytes.Equal(after, tc.content) {
+				t.Errorf("原文件被改写了！\nbefore=%s\nafter =%s", tc.content, after)
+			}
+			if _, err := os.Stat(path + customModelsBackupSuffix); !os.IsNotExist(err) {
+				t.Errorf("没写就不该留备份")
+			}
+		})
+	}
+}
+
+// 真的要覆盖写时，必须先把原文留成 <models.json>.magic-agent.bak（可回滚）。
+func TestSyncCustomModelsFromApp_BacksUpBeforeOverwrite(t *testing.T) {
 	dir := t.TempDir()
+	acc := filepath.Join(dir, "acc.json")
+	writeJSON(t, acc, appCacheFixture())
 	cfg := filepath.Join(dir, "config")
+	if err := os.MkdirAll(cfg, 0o700); err != nil {
+		t.Fatal(err)
+	}
 	path := filepath.Join(cfg, customModelsFileName)
 
+	before := []byte("{\n  \"models\": [],\n  \"availableModels\": [\"hy3\"]\n}\n")
+	if err := os.WriteFile(path, before, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	added, err := syncCustomModelsFromApp(acc, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if added == 0 {
+		t.Fatal("本次应有新增（触发落盘）")
+	}
+
+	bak, err := os.ReadFile(path + customModelsBackupSuffix)
+	if err != nil {
+		t.Fatalf("覆盖写之前应留备份: %v", err)
+	}
+	if !bytes.Equal(bak, before) {
+		t.Errorf("备份内容应为改动前的原文\nwant=%s\ngot =%s", before, bak)
+	}
+}
+
+func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
+	dir := t.TempDir()
+	cfg := filepath.Join(dir, "config")
+	path := filepath.Join(cfg, customModelsFileName)
 	cases := []struct{ name, acc string }{
 		{"acc 路径为空", ""},
 		{"acc 文件不存在", filepath.Join(dir, "nope.json")},
@@ -221,7 +325,17 @@ func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
 	}
 }
 
-func TestSyncCustomModelsFromApp_CorruptExistingFileRebuilt(t *testing.T) {
+/* 既有 models.json 无法确认为「CLI 自己的格式」时，一律**不碰**，而不是重建。
+ *
+ * 这条契约是 2026-09-30 改的（Windows 事故）。原行为是「解析失败当空文件，重建」，
+ * 理由看起来无害（CLI 自己也这么兜底）。实际后果是把**别人的**文件整体替换掉：
+ * 桌面端 WorkBuddy 的 models.json 顶层是数组，数组解析不进 map[string]any，
+ * 于是被当成「坏文件」重建 → 里面 61 条官方模型全没了，只剩 8 条 custom-local，
+ * 而且没有备份，不可回滚。
+ *
+ * 宁可少同步一次端点（CLI 会自己报 "has no endpoint url configured"），
+ * 也不要毁掉一份不是我们管的配置。 */
+func TestSyncCustomModelsFromApp_CorruptExistingFileLeftUntouched(t *testing.T) {
 	dir := t.TempDir()
 	acc := filepath.Join(dir, "acc.json")
 	writeJSON(t, acc, appCacheFixture())
@@ -229,16 +343,25 @@ func TestSyncCustomModelsFromApp_CorruptExistingFileRebuilt(t *testing.T) {
 	if err := os.MkdirAll(cfg, 0o700); err != nil {
 		t.Fatal(err)
 	}
-	// 既有 models.json 坏了：应重建（CLI 自己也这么兜：读失败当空），且不崩
-	if err := os.WriteFile(filepath.Join(cfg, customModelsFileName), []byte("{oops"), 0o600); err != nil {
+	path := filepath.Join(cfg, customModelsFileName)
+	broken := []byte("{oops")
+	if err := os.WriteFile(path, broken, 0o600); err != nil {
 		t.Fatal(err)
 	}
+
 	added, err := syncCustomModelsFromApp(acc, cfg)
 	if err != nil {
-		t.Fatalf("坏文件应可恢复: %v", err)
+		t.Fatalf("不认识的文件应静默跳过，不该报错: %v", err)
 	}
-	if added != 2 {
-		t.Errorf("added = %d, want 2", added)
+	if added != 0 {
+		t.Errorf("added = %d, want 0（不碰未知格式）", added)
+	}
+	after, rerr := os.ReadFile(path)
+	if rerr != nil {
+		t.Fatalf("原文件必须还在: %v", rerr)
+	}
+	if !bytes.Equal(after, broken) {
+		t.Errorf("原文件被改写了：%s", after)
 	}
 }
 

package/internal/agent/env.go

@@ -80,9 +80,17 @@ func ChildEnvWith(extraEnv []string) []string {
 }
 
 // envDenied 判断某环境变量是否不允许传给子 CLI。
+//
+// ⚠️ 大小写不敏感（2026-09-30 修，Windows 事故）：环境变量名在 **Windows 上本身
+// 不区分大小写**，父会话用 `server__port` / `Server__Port` 这类大小写写出来时，
+// 原来的逐字符比较会**漏剔除** —— 子 CLI 于是仍读到父进程的监听端口，再起一个服务
+// 撞上 EADDRINUSE，表现为「一进登录界面就卡死 / 嵌套调用永远没结果」。
+// Unix 上变量名区分大小写，折叠大小写只会**更保守**（多剔除几个父会话风格的名字），
+// 不会少剔除，故这里两个平台统一按大写比较。
 func envDenied(name string) bool {
-	if strings.HasPrefix(name, serverEnvPrefix) {
+	upper := strings.ToUpper(name)
+	if strings.HasPrefix(upper, serverEnvPrefix) {
 		return true
 	}
-	return envDenylist[name]
+	return envDenylist[upper]
 }

package/internal/agent/env_test.go

@@ -86,6 +86,43 @@ func TestEnvironStripsPythonVars(t *testing.T) {
 	}
 }
 
+// Windows 的变量名不区分大小写：父会话若写成混合大小写，也必须被剔除。
+// 2026-09-30 事故：漏剔除 → 子 CLI 仍读到父进程端口 → EADDRINUSE 永久挂起，
+// 表现就是「一进登录界面就上不去」。
+func TestEnvDeniedCaseInsensitive(t *testing.T) {
+	cases := map[string]bool{
+		"server__port":         true,
+		"Server__Port":         true,
+		"server__host":         true,
+		"codebuddy_session_id": true,
+		"Codebuddy_Session_Id": true,
+		"pythonhome":           true,
+		"PATH":                 false,
+		"HOME":                 false,
+		// 仍必须放行：引擎靠它选配置目录（见 codebuddyAccountEnv）
+		"codebuddy_config_dir": false,
+	}
+	for name, want := range cases {
+		if got := envDenied(name); got != want {
+			t.Errorf("envDenied(%q) = %v, want %v", name, got, want)
+		}
+	}
+}
+
+// 混合大小写的父会话变量在 environ() 里也必须不见。
+func TestEnvironStripsMixedCaseServerPrefix(t *testing.T) {
+	t.Setenv("server__port", "58311")
+	t.Setenv("Server__Host", "127.0.0.1")
+	t.Setenv("codebuddy_session_id", "should-be-stripped")
+
+	for _, kv := range environ() {
+		name, _, _ := strings.Cut(kv, "=")
+		if envDenied(name) {
+			t.Errorf("被拒绝的变量仍出现在子 CLI 环境里: %s", kv)
+		}
+	}
+}
+
 func TestEnvDenied(t *testing.T) {
 	cases := map[string]bool{
 		"SERVER__PORT":                true,

package/internal/agent/repair_models_test.go

@@ -0,0 +1,194 @@
+package agent
+
+// repair_models_test.go - 事故还原（--repair-models 的落地逻辑，见 custom_models.go）。
+//
+// 场景来自 2026-09-30 Windows 事故：桌面端 models.json 是**数组**，被反向同步覆盖成
+// `{availableModels, models}` 对象后桌面端解析不了，模型清单整个为空。
+// 这里锁住三件事：
+//  1. 明确的坏形状 → 还原成数组，id 去掉 custom-local: 前缀，且先留 .broken.bak
+//  2. 已经是数组 → 一个字都不动
+//  3. 形状对不上（坏 JSON / 空对象 / models 里混着非 custom-local 条目）→ 一律不动
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// clobberedFixture 造一份「被我们覆盖写坏」的 models.json：顶层对象 + 全 custom-local 条目。
+func clobberedFixture() []byte {
+	return []byte(`{
+  "availableModels": [
+    "custom-local:MiniMax-M3",
+    "custom-local:glm-5.3"
+  ],
+  "models": [
+    {
+      "id": "custom-local:MiniMax-M3",
+      "name": "MiniMax-M3",
+      "vendor": "MiniMax",
+      "url": "https://api.minimaxi.com/v1/chat/completions",
+      "apiKey": "sk-user-own",
+      "supportsImages": false
+    },
+    {
+      "id": "custom-local:glm-5.3",
+      "name": "glm-5.3",
+      "vendor": "Zhipu",
+      "url": "https://open.bigmodel.cn/api/paas/v4",
+      "apiKey": "sk-user-own-2"
+    }
+  ]
+}
+`)
+}
+
+func TestRepairModelsFile_RestoresArrayFormat(t *testing.T) {
+	appHome := t.TempDir()
+	path := filepath.Join(appHome, customModelsFileName)
+	if err := os.WriteFile(path, clobberedFixture(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	repaired, note, err := repairModelsFile(appHome)
+	if err != nil {
+		t.Fatalf("repair: %v", err)
+	}
+	if !repaired {
+		t.Fatalf("坏形状应被还原，note=%q", note)
+	}
+
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var arr []map[string]any
+	if err := json.Unmarshal(b, &arr); err != nil {
+		t.Fatalf("还原后应是数组: %v（内容 %s）", err, b)
+	}
+	if len(arr) != 2 {
+		t.Fatalf("条数 = %d, want 2", len(arr))
+	}
+	for _, m := range arr {
+		id, _ := m["id"].(string)
+		if id == "" || strings.HasPrefix(id, customModelIDPrefix) {
+			t.Errorf("id 必须去掉 %s 前缀，实际 %q", customModelIDPrefix, id)
+		}
+	}
+	if arr[0]["id"] != "MiniMax-M3" {
+		t.Errorf("首条 id = %v, want MiniMax-M3", arr[0]["id"])
+	}
+	// 端点与密钥必须原样保留（丢了就只能手抄）
+	if arr[0]["url"] != "https://api.minimaxi.com/v1/chat/completions" || arr[0]["apiKey"] != "sk-user-own" {
+		t.Errorf("端点/密钥没保留: %v", arr[0])
+	}
+
+	// 现场必须留备份，且备份是坏的那份原文
+	bak, err := os.ReadFile(path + ".broken.bak")
+	if err != nil {
+		t.Fatalf("应留 .broken.bak: %v", err)
+	}
+	if !bytes.Equal(bak, clobberedFixture()) {
+		t.Error(".broken.bak 应为被写坏的原文")
+	}
+}
+
+func TestRepairModelsFile_LeavesGoodShapesAlone(t *testing.T) {
+	// 桌面端原生数组格式
+	native := []byte("[\n  {\n    \"id\": \"MiniMax-M3\",\n    \"url\": \"https://x/v1\"\n  }\n]\n")
+
+	cases := []struct {
+		name    string
+		content []byte
+	}{
+		{"已是数组（桌面端原生格式）", native},
+		{"坏 JSON", []byte("{oops")},
+		{"空 JSON 对象", []byte("{}")},
+		{"顶层是字符串", []byte(`"nope"`)},
+		{"models 里混着非 custom-local 条目", []byte(`{"models":[{"id":"hy3","url":"https://x"}]}`)},
+		{"models 是空数组", []byte(`{"models":[],"availableModels":[]}`)},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			appHome := t.TempDir()
+			path := filepath.Join(appHome, customModelsFileName)
+			if err := os.WriteFile(path, tc.content, 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			repaired, _, err := repairModelsFile(appHome)
+			if err != nil {
+				t.Fatalf("形状对不上应静默不改，不该报错: %v", err)
+			}
+			if repaired {
+				t.Errorf("形状对不上不该动手")
+			}
+			after, rerr := os.ReadFile(path)
+			if rerr != nil {
+				t.Fatal(rerr)
+			}
+			if !bytes.Equal(after, tc.content) {
+				t.Errorf("原文件被改写了\nbefore=%s\nafter =%s", tc.content, after)
+			}
+			if _, serr := os.Stat(path + ".broken.bak"); !os.IsNotExist(serr) {
+				t.Errorf("没还原就不该留 .broken.bak")
+			}
+		})
+	}
+}
+
+func TestRepairModelsFile_MissingFileIsNoop(t *testing.T) {
+	appHome := t.TempDir()
+	repaired, note, err := repairModelsFile(appHome)
+	if err != nil {
+		t.Fatalf("没有文件不该报错: %v", err)
+	}
+	if repaired {
+		t.Error("没有文件时不谈还原")
+	}
+	if note == "" {
+		t.Error("应给出「不存在、无需修复」的说明，不静默")
+	}
+}
+
+// 幂等：还原过一次之后，再跑一次必须什么都不做（已经是数组）。
+func TestRepairModelsFile_Idempotent(t *testing.T) {
+	appHome := t.TempDir()
+	path := filepath.Join(appHome, customModelsFileName)
+	if err := os.WriteFile(path, clobberedFixture(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if repaired, _, err := repairModelsFile(appHome); err != nil || !repaired {
+		t.Fatalf("首次应还原: repaired=%v err=%v", repaired, err)
+	}
+	first, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	repaired, _, err := repairModelsFile(appHome)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if repaired {
+		t.Error("第二次不该再动手")
+	}
+	second, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(first, second) {
+		t.Error("第二次不该改动文件")
+	}
+}
+
+// 引擎名到桌面端数据目录的映射：不认识的名字必须报错，而不是猜一个目录去写。
+func TestRepairDesktopModels_UnknownEngine(t *testing.T) {
+	if _, _, err := RepairDesktopModels("no-such-engine"); err == nil {
+		t.Fatal("没有桌面端目录的引擎应报错")
+	}
+}

package/internal/cli/ask.go

@@ -44,24 +44,27 @@ import (
 
 // askOptions 根命令的全部参数。
 type askOptions struct {
-	engine       string
-	model        string
-	system       string
-	prompt       string
-	file         string
-	attach       []string // 附件（截图/图片）路径；与提示词一起发给引擎
-	tools        string
-	timeout      time.Duration
-	retries      int
-	backoff      time.Duration
-	output       string
-	verbose      bool
-	engines      bool
-	contract     bool // 输出带版本的契约 envelope（--contract；客户端启动校验用）
-	noModels     bool
-	login        string // 拉起某引擎自己的交互式登录会话（--login <engine>）
-	events       bool   // --stream 的事件流带契约版本与行号（--events；客户端消费用）
-	control      bool   // 从 stdin 读 NDJSON 控制命令（--control；打断 / 收工 / 回审批）
+	engine   string
+	model    string
+	system   string
+	prompt   string
+	file     string
+	attach   []string // 附件（截图/图片）路径；与提示词一起发给引擎
+	tools    string
+	timeout  time.Duration
+	retries  int
+	backoff  time.Duration
+	output   string
+	verbose  bool
+	engines  bool
+	contract bool // 输出带版本的契约 envelope（--contract；客户端启动校验用）
+	noModels bool
+	login    string // 拉起某引擎自己的交互式登录会话（--login <engine>）
+	// repairModels 还原被反向同步写坏的桌面端 models.json（--repair-models <engine>）：
+	// 2026-09-30 Windows 事故的收尾手段，见 internal/agent/custom_models.go 的事故还原一节。
+	repairModels string
+	events       bool // --stream 的事件流带契约版本与行号（--events；客户端消费用）
+	control      bool // 从 stdin 读 NDJSON 控制命令（--control；打断 / 收工 / 回审批）
 	jsonOut      bool
 	stream       bool
 	noThinking   bool
@@ -145,6 +148,7 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f.BoolVar(&opts.contract, "contract", false, "输出桌面/移动客户端契约：{\"contractVersion\":N,\"engines\":[...]}（engines 与 --engines 同构，另含 capabilities 静态能力字段）。默认不探测模型（快）；要模型写 --no-models=false")
 	f.BoolVar(&opts.noModels, "no-models", false, "配合 --engines / --contract：跳过各引擎的模型探测（只列引擎与可用性，不启动 CLI）")
 	f.StringVar(&opts.login, "login", "", "拉起指定引擎自己的交互式登录会话（如 codebuddy / codebuddy-ai）：自动带上该引擎的账号环境，进去执行 /login 即可；登录态落在该引擎自己的票据上，两个账号互不顶号")
+	f.StringVar(&opts.repairModels, "repair-models", "", "还原被覆盖写坏的桌面端 models.json（如 codebuddy / codebuddy-ai）：把对象格式改回桌面端的数组格式，官方模型清单不动；只在形状确实是坏的时候才改，且先留 .broken.bak 备份")
 	f.BoolVar(&opts.jsonOut, "json", false, "兼容保留：--engines 已默认 JSON，本 flag 不再需要")
 	f.BoolVar(&opts.stream, "stream", false, "流式输出：正文/思考增量实时打到 stdout（text 模式思考走 stderr）")
 	f.BoolVar(&opts.events, "events", false, "配合 --stream：事件流带契约版本与行号（每行加 v / seq，并先发一行 ready），供客户端消费；老消费者不要开（形状与 --stream 不同）")

package/internal/cli/login.go

@@ -14,6 +14,7 @@ import (
 	"os"
 	"os/exec"
 	"strings"
+	"sync"
 
 	"github.com/darren/magic-agent/internal/agent"
 	"github.com/spf13/cobra"
@@ -40,7 +41,11 @@ func runLogin(cmd *cobra.Command, opts *askOptions) error {
 		return err
 	}
 
-	// stdio 直通：交互式界面必须拿到真的 TTY。
+	/* stdio 直通：交互式界面必须拿到真的 TTY。
+	   ⚠️ 这里**刻意不设进程组**（普通引擎调用走 configureProcAttr 自成一组）：
+	   交互式 TUI 必须在**前台进程组**里，否则它从 tty 读输入会被 SIGTTIN 停住 ——
+	   表现就是「一进登录界面就卡住」。代之以「登记子进程 + 退出前带走」的清理
+	   （见 loginChild / stopLoginChild），保证它不会变成占着账号的孤儿。 */
 	c := exec.Command(bin, args...)
 	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
 	c.Env = agent.ChildEnvWith(extraEnv)
@@ -49,20 +54,72 @@ func runLogin(cmd *cobra.Command, opts *askOptions) error {
 	}
 
 	// 提示走 stderr：stdout 留给子进程的交互界面，不被污染。
+	// 第三行是给「上一次登录没成功」的情形：残留的登录态得先清掉，否则会一直登不上。
 	fmt.Fprintf(cmd.ErrOrStderr(),
 		"magic-agent: 已按 %s 的账号环境启动 %s\n"+
-			"            在里面执行 /login 完成登录（退出后本命令结束）\n", eng.Name(), bin)
+			"            在里面执行 /login 完成登录（退出后本命令结束）\n"+
+			"            若上一次登录没成功、这次进去仍登不上：先执行 /logout 清掉残留登录态，再执行 /login\n",
+		eng.Name(), bin)
 
-	if runErr := c.Run(); runErr != nil {
+	if startErr := c.Start(); startErr != nil {
+		return fmt.Errorf("启动 %s 失败: %w", bin, startErr)
+	}
+	setLoginChild(c)
+	defer clearLoginChild()
+
+	if runErr := c.Wait(); runErr != nil {
 		var ee *exec.ExitError
 		if errors.As(runErr, &ee) {
 			return fmt.Errorf("%s 会话退出码 %d", eng.Name(), ee.ExitCode())
 		}
-		return fmt.Errorf("启动 %s 失败: %w", bin, runErr)
+		return fmt.Errorf("%s 会话异常: %w", eng.Name(), runErr)
 	}
 	return nil
 }
 
+/* ── 交互式登录子进程的清理登记 ──────────────────────────────
+ *
+ * 为什么单独记一笔：登录是**唯一**不走进程组管理的子进程（理由见上面 runLogin 的
+ * 注释 —— 交互式 TUI 必须留在前台组里）。因此它既不在会话登记表（--stop 管不到），
+ * 也不会被 installSignalStop 的「杀会话」路径带走。一旦 magic-agent 被 SIGTERM
+ * （桌面壳的「停止」按钮、`kill <pid>`）终止，这个 CLI 就成孤儿，继续占着该账号的
+ * 配置目录 / 端口，下一次 --login 起来会撞上残留状态 —— 用户看到的就是
+ * 「登录失败后再也登不上」。所以退出前必须补一刀。
+ */
+var (
+	loginMu    sync.Mutex
+	loginChild *exec.Cmd
+)
+
+// setLoginChild 登记正在跑的登录子进程。
+func setLoginChild(c *exec.Cmd) {
+	loginMu.Lock()
+	loginChild = c
+	loginMu.Unlock()
+}
+
+// clearLoginChild 注销（登录会话正常结束 / 启动失败时调用）。
+func clearLoginChild() {
+	setLoginChild(nil)
+}
+
+/* stopLoginChild 杀掉正在跑的登录子进程（若在），返回是否真的动了手。
+ *
+ * 用**单进程**信号（group=false）：它本来就与 magic-agent 同组，负 pid 会把
+ * magic-agent 自己一起杀掉。
+ */
+func stopLoginChild() bool {
+	loginMu.Lock()
+	c := loginChild
+	loginChild = nil
+	loginMu.Unlock()
+	if c == nil || c.Process == nil {
+		return false
+	}
+	_ = agent.KillPID(c.Process.Pid, false)
+	return true
+}
+
 // loginCapableEngines 列出实现了 LoginRunner 的引擎名（报错提示用）。
 func loginCapableEngines() string {
 	var names []string

package/internal/cli/login_test.go

@@ -0,0 +1,99 @@
+package cli
+
+// login_test.go - `--login` 的参数校验与「退出前带走登录子进程」的清理契约。
+//
+// 这两件事都是「登录失败后再也登不上」那个用户问题的直接成因：
+//   - 参数写错时给一句看得懂的中文（而不是 cobra 的英文裸报错，且退出码要对）；
+//   - 登录 TUI 必须留在前台进程组里（否则读 tty 被 SIGTTIN 停住），代价是
+//     magic-agent 被 SIGTERM / 关终端时必须主动把它带走，不能留成占着账号的孤儿。
+
+import (
+	"errors"
+	"os/exec"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+// `--login` 后面没跟引擎名：必须给出中文 usage（点名可用引擎），且算参数错（exit 2）。
+// cobra 在解析阶段就报错（走不到 runLogin），所以这条靠 SetFlagErrorFunc 兜住。
+func TestLoginWithoutEngineNameIsUsageError(t *testing.T) {
+	_, _, err := runAskCmd(t, "", "--login")
+	if err == nil {
+		t.Fatal("--login 缺引擎名应报错")
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "需要引擎名") {
+		t.Errorf("应是中文用法提示，实际 %q", msg)
+	}
+	/* ⚠️ 不断言「提示里点名了 codebuddy」：包内用例会在 Engines() 首次调用前
+	   agent.Register 假引擎，触发 registry 的已知脆弱点（内置引擎整体不注册，
+	   见 agent/engine.go 的守卫注释），那时可用引擎列表本来就是空的。
+	   这里只锚定稳定契约：中文提示 + usage（exit 2）。 */
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError（exit 2），实际 %T", err)
+	}
+}
+
+// 未知引擎名：usage 错误 + 列出可用引擎，不静默启一个空 bin。
+func TestLoginUnknownEngine(t *testing.T) {
+	_, _, err := runAskCmd(t, "", "--login", "no-such-engine")
+	if err == nil {
+		t.Fatal("未知引擎应报错")
+	}
+	if !strings.Contains(err.Error(), "未知引擎") {
+		t.Errorf("错误应点名未知引擎，实际 %q", err.Error())
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError（exit 2），实际 %T", err)
+	}
+}
+
+// 不支持交互式登录的引擎：明确说不必用 --login，而不是硬造一条命令。
+func TestLoginEngineWithoutLoginRunner(t *testing.T) {
+	_, _, err := runAskCmd(t, "", "--login", "claude")
+	if err == nil {
+		t.Fatal("claude 不支持 --login，应报错")
+	}
+	if !strings.Contains(err.Error(), "不需要 --login") {
+		t.Errorf("错误应说明该引擎不需要 --login，实际 %q", err.Error())
+	}
+}
+
+// 登录子进程必须能被 stopLoginChild 收掉（进程真死）。
+// 为什么值得测：登录是唯一不进进程组的子进程，孤儿化正是「登录失败后再也登不上」的成因。
+//
+// 判据用 c.Wait()（真回收）而不是 PIDAlive —— 被 SIGKILL 的子进程在没人 Wait 之前
+// 是僵尸，仍然会被 kill(pid, 0) 判成「活着」，拿它当判据会假红。
+func TestStopLoginChildKillsProcess(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("用 sleep 当靶子，Windows 另论")
+	}
+	c := exec.Command("sleep", "60")
+	if err := c.Start(); err != nil {
+		t.Fatalf("起靶子进程失败: %v", err)
+	}
+	setLoginChild(c)
+
+	if !stopLoginChild() {
+		t.Fatal("stopLoginChild 应报告动了手")
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- c.Wait() }()
+	select {
+	case werr := <-done:
+		var ee *exec.ExitError
+		if !errors.As(werr, &ee) {
+			t.Fatalf("靶子应被信号杀掉，实际 err=%v", werr)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("登录子进程未被收掉（5s 内没退出）")
+	}
+
+	// 已经清空：再调一次不应再动手（幂等，避免误杀复用的 pid）。
+	if stopLoginChild() {
+		t.Error("注销后再调 stopLoginChild 不应再动手")
+	}
+}