magic-agent 2.6.0 → 2.6.3

package/internal/cli/events_test.go

@@ -31,6 +31,15 @@ func sinkSamples() []agent.StreamEvent {
 			Reason: "without result line",
 			Status: agent.StatusFailed, ItemID: "claude_msg_1", ItemRevision: 4,
 		},
+		/* 额度卡三项（2026-10-25）：非空时才出现在 wire 上 —— 放进样本是为了让上面
+		   那条「两条路径字段集只差 v/seq」的断言也覆盖到它们（否则新字段漏了 marshal
+		   到老形状里也测不出来）。 */
+		{
+			Kind: agent.KindTurnFailed, Text: "", SessionID: "sess_quota",
+			Error: "429 You have exceeded the 5-hour usage quota.", Reason: "429 You have exceeded the 5-hour usage quota.",
+			ErrorKind: agent.ErrorKindQuota, ErrorCode: "429", ResetAt: "2026-10-25T15:07:27+08:00",
+			Status: agent.StatusFailed,
+		},
 	}
 }
 
@@ -250,6 +259,47 @@ func TestTurnFailedPayloadFields(t *testing.T) {
 	}
 }
 
+// 额度卡三项必须原样过 wire（客户端靠它决定画额度卡还是普通失败卡）：
+// 名字与 CLAUDE-CONTRACT / CLIENT-CONTRACT.md 1.1.1 那张表逐字一致，改一个字母
+// 客户端就再也认不出来 —— 所以这里按**字符串字段名**断言，而不是读结构体。
+func TestTurnFailedQuotaFields(t *testing.T) {
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "codebuddy", true)
+	if err := s.stream(agent.StreamEvent{
+		Kind: agent.KindTurnFailed, SessionID: "s2",
+		Error: "429 You have exceeded the 5-hour usage quota.", Reason: "429 You have exceeded the 5-hour usage quota.",
+		ErrorKind: agent.ErrorKindQuota, ErrorCode: "429", ResetAt: "2026-10-25T15:07:27+08:00",
+		Status: agent.StatusFailed,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m := decodeEventLine(t, buf.String())
+	if m["error_kind"] != "quota" {
+		t.Errorf("error_kind = %v，want quota", m["error_kind"])
+	}
+	if m["error_code"] != "429" {
+		t.Errorf("error_code = %v，want 429", m["error_code"])
+	}
+	if m["reset_at"] != "2026-10-25T15:07:27+08:00" {
+		t.Errorf("reset_at = %v", m["reset_at"])
+	}
+
+	/* 分不出来时三项都不出现（omitempty）—— 老消费者的字段集因此不变。 */
+	buf.Reset()
+	if err := s.stream(agent.StreamEvent{
+		Kind: agent.KindTurnFailed, SessionID: "s3",
+		Error: "工具执行失败", Reason: "工具执行失败", Status: agent.StatusFailed,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m = decodeEventLine(t, buf.String())
+	for _, k := range []string{"error_kind", "error_code", "reset_at"} {
+		if _, ok := m[k]; ok {
+			t.Errorf("分不出来时不该出现 %s：%v", k, m)
+		}
+	}
+}
+
 // ── 黄金样本：钉住 Claude / CodeBuddy 在 wire 上的真实字节形状 ──
 //
 // 为什么不复用上面的 TestStreamEventPayloadConvergenceFields：

package/internal/cli/judge.go

@@ -0,0 +1,104 @@
+package cli
+
+// judge.go - `--judge-conflict <file|->`：判断本轮任务与同空间运行中任务是否冲突。
+//
+// 为什么要单独一条 CLI（2026-10-26）：「自动」任务模式要在**开跑前**决定这一轮是并行还是
+// 排队，判断依据是两边「在干什么」—— 这是语义问题，只能由模型答；而提示词与解析口径必须
+// 只有一份（移动端 / PC / 服务端都不能各写一套）。口径收进 core（internal/judge）之后，
+// magic-client 的作业队列 exec 这一条即可。
+//
+// 与 `--suggest-followups` 同一套旁路调用：独立进程、新会话、ToolsOff、不写历史。
+//
+// 退出码：
+//
+//	0  判定完成（conflict=true / false 都是成功；调用方按结论排队或放行）
+//	1  引擎失败（不可用 / 超时 / 输出不是 JSON）—— 调用方按「默认并行」放行
+//	2  参数错（请求 JSON 读不到 / 不合法 / 缺 prompt）
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/darren/magic-agent/internal/judge"
+)
+
+// runJudgeConflict 读请求 JSON → 调 judge.Judge → 打印 JSON 结论。
+func runJudgeConflict(cmd *cobra.Command, opts *askOptions) error {
+	body, err := readJudgeInput(cmd, opts.judgeInput)
+	if err != nil {
+		return &usageError{err}
+	}
+	/* 引擎：没显式传 -e 时用 llm（启动最快，2.5s 预算内能答完）；传了就以调用方的为准
+	   （调用方传的是用户配的「建议引擎」）。 */
+	engine := judge.DefaultEngine
+	if flagChanged(cmd, "engine") {
+		engine = opts.engine
+	}
+	model := ""
+	if flagChanged(cmd, "model") {
+		model = opts.model
+	}
+	res, err := judge.Judge(cmd.Context(), judge.Request{
+		Prompt:     body.Prompt,
+		Candidates: body.Candidates,
+		Engine:     engine,
+		Model:      model,
+		Timeout:    judge.DefaultTimeout,
+	})
+	if err != nil {
+		return fmt.Errorf("--judge-conflict: 判定失败: %w", err)
+	}
+	if res.Overlaps == nil {
+		res.Overlaps = []string{}
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
+// readJudgeInput 读请求 JSON：`-` = stdin，其余按文件路径（支持 `@file`）。
+// 上限 256KB：判定只该带「本轮提示词 + 几个候选的摘要」，超了说明调用方塞了整条历史。
+func readJudgeInput(cmd *cobra.Command, spec string) (judge.RequestBody, error) {
+	var body judge.RequestBody
+	src := strings.TrimSpace(spec)
+	read := func(r io.Reader, from string) error {
+		b, err := io.ReadAll(io.LimitReader(r, 256<<10))
+		if err != nil {
+			return fmt.Errorf("读%s失败：%w", from, err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return fmt.Errorf("%s不是合法 JSON：%w", from, err)
+		}
+		return nil
+	}
+	switch src {
+	case "":
+		return body, fmt.Errorf("--judge-conflict 需要请求 JSON：传文件路径或 \"-\"（stdin）")
+	case "-":
+		if err := read(cmd.InOrStdin(), "stdin "); err != nil {
+			return body, err
+		}
+	default:
+		path := strings.TrimPrefix(src, "@")
+		if strings.HasPrefix(path, "~/") {
+			if home, herr := os.UserHomeDir(); herr == nil {
+				path = home + path[1:]
+			}
+		}
+		f, err := os.Open(path)
+		if err != nil {
+			return body, fmt.Errorf("读请求文件失败：%w", err)
+		}
+		defer f.Close()
+		if err := read(f, "请求文件 "); err != nil {
+			return body, err
+		}
+	}
+	if strings.TrimSpace(body.Prompt) == "" {
+		return body, fmt.Errorf(`缺少 prompt（本轮任务）：形如 {"prompt":"…","candidates":[…]}（candidates 为空表示没有冲突对象）`)
+	}
+	return body, nil
+}

package/internal/cli/root.go

@@ -486,6 +486,9 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 			case flagChanged(cmd, "suggest-followups"):
 				// 值可以是 "-"（stdin），所以用「传过没有」判，而不是「值非空」。
 				return runSuggestFollowups(cmd, opts)
+			case flagChanged(cmd, "judge-conflict"):
+				// 同上：值可以是 "-"（stdin）。
+				return runJudgeConflict(cmd, opts)
 			case flagChanged(cmd, "title-force"):
 				// --title-force 只在 --summarize-title 下成立：单给它必然是调用方误解了
 				// （想要「强制重新归纳」却没给 id）。明说，不静默忽略。
@@ -717,20 +720,28 @@ var (
 // key 一般用引擎名（codebuddy / codebuddy-ai / trae …）；命中且未过期的缓存直接返回，
 // 不触碰 CLI / 文件。底层走 probeEngineModels / probeEngineCredits（可被测试替换）。
 // ListModels 出错或返回空清单时**不缓存**（视为瞬时态，下次重探）。
-func cachedModelList(ctx context.Context, key string, l agent.ModelLister) (models []string, credits map[string]string, note string) {
+//
+// noSource 区分两种"拿不到模型"的语义（见 agent.ErrNoModelSource）：
+//   - true  = 引擎**本来就不提供**模型清单（arkclaw 按 claw_id 绑模型、
+//     codebuddy-gateway 用网关进程的模型）—— 它不是故障，调用方不该因此隐藏引擎；
+//   - false = 有来源但这次探测失败（CLI 退出码非 0 / 空清单）—— 可以隐藏或置灰。
+//
+// 以前两者只靠 note 字符串表达，客户端只能看"note 是否为空"一刀切，
+// 把 arkclaw / MagicAI / codebuddy-gateway 一起隐藏了（2026-10 报障）。
+func cachedModelList(ctx context.Context, key string, l agent.ModelLister) (models []string, credits map[string]string, note string, noSource bool) {
 	modelListCacheMu.Lock()
 	if it, ok := modelListCache[key]; ok && time.Now().Before(it.expiresAt) {
 		modelListCacheMu.Unlock()
-		return it.models, it.credits, ""
+		return it.models, it.credits, "", false
 	}
 	modelListCacheMu.Unlock()
 
 	models, err := probeEngineModels(ctx, l)
 	if err != nil {
-		return nil, nil, err.Error()
+		return nil, nil, err.Error(), errors.Is(err, agent.ErrNoModelSource)
 	}
 	if len(models) == 0 {
-		return nil, nil, "no models reported"
+		return nil, nil, "no models reported", false
 	}
 	if cl, ok := l.(agent.ModelCreditLister); ok {
 		credits = probeEngineCredits(ctx, cl)
@@ -742,7 +753,7 @@ func cachedModelList(ctx context.Context, key string, l agent.ModelLister) (mode
 		expiresAt: time.Now().Add(modelListCacheTTL),
 	}
 	modelListCacheMu.Unlock()
-	return models, credits, ""
+	return models, credits, "", false
 }
 
 // clearModelListCache 清空模型清单缓存（测试用，避免用例之间互相命中缓存）。
@@ -834,6 +845,14 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		Version    string   `json:"version,omitempty"`
 		Models     []string `json:"models,omitempty"`
 		ModelsNote string   `json:"models_note,omitempty"`
+		/* ModelsSource 模型清单的**来源语义**（machine-readable，取代"靠 models_note
+		   猜"的做法；只增字段不升 contractVersion）：
+		     dynamic —— models 可用；
+		     none    —— 引擎本身不提供模型选择（模型绑在 claw_id / 网关进程上），
+		                **不是故障**：调用方应保留这一行并显示「引擎默认」；
+		     failed  —— 有动态来源但本次探测失败（CLI 非 0 退出等），可隐藏或置灰。
+		   旧 core 没有该字段，调用方按 models_note 前缀兜底（见 shared/conversation.js）。 */
+		ModelsSource string `json:"models_source,omitempty"`
 		// ModelCredits 各模型的积分倍率（machine-readable，model → 倍率数字字符串，
 		// 如 "fast-model":"0.34"，源于客户端 "x0.34 credits"；与 models 同源同链探测，
 		// 仅实现了 agent.ModelCreditLister 的引擎给出 —— 目前 codebuddy / codebuddy-ai）。
@@ -1025,6 +1044,7 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		lister := agent.ModelListerOf(e)
 		if lister == nil {
 			rows[i].ModelsNote = "no dynamic model source"
+			rows[i].ModelsSource = "none"
 			continue
 		}
 		wg.Add(1)
@@ -1032,7 +1052,7 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 			defer wg.Done()
 			ctx, cancel := context.WithTimeout(cmd.Context(), agent.DefaultModelProbeTimeout)
 			defer cancel()
-			models, credits, note := cachedModelList(ctx, name, l)
+			models, credits, note, noSource := cachedModelList(ctx, name, l)
 			// codebuddy 系：展示时剥掉自定义模型 id 的 "custom-local:" 前缀（噪点）；
 			// -m 实际传值时由引擎按裸名补回前缀（见 codebuddyCore.modelArg），
 			// 自定义模型依旧可用。
@@ -1043,10 +1063,19 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 			switch {
 			case note != "":
 				rows[i].ModelsNote = note
+				// 语义型"没有模型源"≠ 探测失败：前者保留可选项（模型由 claw_id /
+				// 网关进程决定），后者才让调用方隐藏。
+				if noSource {
+					rows[i].ModelsSource = "none"
+				} else {
+					rows[i].ModelsSource = "failed"
+				}
 			case len(models) == 0:
 				rows[i].ModelsNote = "no models reported"
+				rows[i].ModelsSource = "failed"
 			default:
 				rows[i].Models = models
+				rows[i].ModelsSource = "dynamic"
 				if credits != nil {
 					rows[i].ModelCredits = credits
 				}

package/internal/cli/session.go

@@ -385,31 +385,95 @@ func runSessions(cmd *cobra.Command, opts *askOptions) error {
 		// 所以非流式跑出来的会话没有历史可回放 —— 客户端要拿它判断「这条点开有东西看吗」，
 		// 而让客户端自己去拼日志路径就是把本仓库的内部布局当接口用。
 		HasLog bool `json:"has_log"`
+		/* WorkspaceLocked 这条会话所在的目录当前是不是被**别人**占着工作空间锁
+		   （2026-10-26，多客户端仲裁）。
+
+		   为什么要有这个字段：core 现在默认对同 workspace 串行（见 workspace_lock.go），
+		   但**等待发生在 Begin 里**，客户端在发请求的那一刻看不到「我要等」——
+		   用户看到的只是「点了没反应 / 转很久」。把这个判断上移到列表里，
+		   客户端就能在按下发送之前就说「这个目录正被手机端占着，已排队」。
+		   ⚠️ 只增字段，老客户端忽略即可（不升契约版本）。 */
+		WorkspaceLocked bool `json:"workspace_locked,omitempty"`
+		// LockHolder 占着这个目录的那一端是谁（pid / client / source / run_id）。
+		// 只在 WorkspaceLocked 为真时给；用户的追问永远是「谁在占」，只有 pid 答不了。
+		LockHolder *session.LockHolder `json:"lock_holder,omitempty"`
 	}
 	logDir, _ := sessionLogDir()
+	/* 锁的查询按**目录**去重：一屏几十条会话大多在同一个 workspace 上，
+	   逐行读一次锁文件既浪费又要处理「同一目录答案不一致」的边界。
+	   这里先收集涉及的目录，各查一次。 */
+	lockOf := map[string]*session.LockHolder{}
+	lockOfWorkspace := func(ws string) *session.LockHolder {
+		key, _ := session.LockKey(ws)
+		if h, ok := lockOf[key]; ok {
+			return h
+		}
+		var out *session.LockHolder
+		if h, ok := session.LockHolderFor(ws); ok && h.PID != os.Getpid() {
+			/* 排除自己：列表页说「你自己占着这个目录」是噪音 ——
+			   用户关心的是「我要不要等别人」。 */
+			out = &h
+		}
+		lockOf[key] = out
+		return out
+	}
+	/* 标题表与状态表各取**一次**快照（2026-10-26 修）：
+	   这两个查询原本逐行调用，而每次调用都会让底层把整张表深拷贝一遍（缓存不能交给
+	   调用方乱改）+ 加一次锁。407 行 = 814 次全表拷贝。列表页要的只是 O(1) 查表，
+	   拷一次就够 —— 语义不变（TitleOf / StatusOf 与 TitleForAny / StatusForAny 同口径）。 */
+	titles := session.TitleSnapshot()
+	statuses := session.StatusSnapshot()
 	rows := make([]row, 0, len(records))
 	for _, r := range records {
 		/* 标题的键可能是 session_id，也可能是 run_id（首轮归纳时引擎还没吐 id，见
 		   session.TitleForAny）—— 两个都认，且**一次取定**，免得两个客户端因为
 		   「谁先拿到 id」而显示不同标题。取不到才回落 prompt_head（= 还没归纳）。 */
-		title := session.TitleForAny(r.SessionID, r.RunID)
+		title := session.TitleOf(titles, r.SessionID, r.RunID)
 		summarized := title != ""
 		if title == "" {
 			title = r.PromptHead
 		}
+		hasLog := session.HasSessionLogIn(logDir, r.SessionID, r.RunID)
 		/* 排队占位（服务端作业队列预登记，state=queued）还没有会话日志，归纳必然失败。
 		   这里直接报「已定稿」，客户端就不会每轮列表刷新都去打一次 --summarize-title。
 		   真开跑后 core 那条记录照常走归纳。 */
 		if r.State == session.StateQueued {
 			summarized = true
 		}
+		/* 结构性不可能归纳：**已经有 session_id、却没有事件日志**。
+		   这种会话每一次归纳都必然失败，重试一万次结果一样，所以直接报「已定稿」，
+		   客户端别再去打那一发（否则它永远停在「待归纳」，每次刷新重来一遍）。
+
+		   为什么必然失败（见 runSummarizeTitle）：归纳的输入必须是**首问**，首问只从
+		   事件日志里取；日志读不到时唯一的兜底是 prompt_head，而那条兜底**只在还没有
+		   session_id 时**才允许（有 id = 至少第二轮，prompt_head 记的是当前这轮追问，
+		   拿它归纳等于把标题改成最新追问 —— 正是「标题每次追问都在变」那个老问题）。
+		   于是 `sessionID != "" && 无日志` 落进「读不到首问」的硬失败分支。
+
+		   什么时候会落到这个组合：引擎当时是非流式跑的（日志只在 --stream 时写）、
+		   或日志被清理而登记还在。两者都不会自己好转 —— 除非用户明确要求 `--title-force`
+		   重来（客户端的手动「重新归纳」按钮照常能打）。 */
+		if !summarized && r.SessionID != "" && !hasLog {
+			summarized = true
+		}
 		/* 统一状态：一条会话一个值（各轮的行给出同一个），决定客户端画「进行中 / 已完成」。
 		   没有条目（改造前的老记录）才回落这一轮的 state。alive 也**按它算** ——
 		   否则一行里 status=idle、alive=true 自相矛盾，客户端又会分叉。 */
-		status := session.StatusForAny(r.SessionID, r.RunID)
+		status := session.StatusOf(statuses, r.SessionID, r.RunID)
 		if status == "" {
 			status = r.State
 		}
+		/* 这个会话所在目录当前被谁占着（空 workspace 用 cwd 兜底，与锁的归一一致）。
+		   只有**活着的**会话才关心：已收尾的会话不给这个字段，免得列表上到处是
+		   「锁被占着」的陈旧提示（锁文件可能因为进程刚退出还没删）。 */
+		var holder *session.LockHolder
+		if session.IsLiveState(status) {
+			ws := r.Workspace
+			if ws == "" {
+				ws = r.Cwd
+			}
+			holder = lockOfWorkspace(ws)
+		}
 		rows = append(rows, row{
 			RunID:           r.RunID,
 			SessionID:       r.SessionID,
@@ -431,7 +495,9 @@ func runSessions(cmd *cobra.Command, opts *askOptions) error {
 			TitleSummarized: summarized,
 			StartedAt:       r.StartedAt.Format("2006-01-02 15:04:05"),
 			UpdatedAt:       r.UpdatedAt.Format("2006-01-02 15:04:05"),
-			HasLog:          session.HasSessionLogIn(logDir, r.SessionID, r.RunID),
+			HasLog:          hasLog,
+			WorkspaceLocked: holder != nil,
+			LockHolder:      holder,
 		})
 	}
 	return printJSON(cmd.OutOrStdout(), rows)

package/internal/cli/session_test.go

@@ -157,10 +157,20 @@ func TestAskRegistersSession(t *testing.T) {
 	if r.Alive {
 		t.Error("已结束的会话不该标 alive")
 	}
-	// 记录文件确实落在指定目录
+	/* 记录文件确实落在指定目录。
+	   ⚠️ 只数 `.json`（2026-10-26）：工作空间锁默认启用之后，同一个目录里还会多出
+	   `locks/` 子目录（见 internal/session/workspace_lock.go）。原来按目录项数断言
+	   「= 1」会因为多了这个子目录而假失败 —— 它数的是「目录里有几样东西」，
+	   而这里想验的是「登记记录落在哪」，两者本来就不是一回事。 */
 	entries, _ := os.ReadDir(dir)
-	if len(entries) != 1 {
-		t.Errorf("目录里文件数 = %d want 1", len(entries))
+	nJSON := 0
+	for _, e := range entries {
+		if !e.IsDir() && strings.HasSuffix(e.Name(), ".json") {
+			nJSON++
+		}
+	}
+	if nJSON != 1 {
+		t.Errorf("目录里登记记录数 = %d want 1（entries=%v）", nJSON, entries)
 	}
 }
 
@@ -339,3 +349,72 @@ func mustSessions(t *testing.T) string {
 	}
 	return out
 }
+
+// TestSessionsMarksUnsortedWhenSummarizeImpossible 有 session_id 却没有事件日志的会话，
+// 归纳**必然失败**（见 runSummarizeTitle 里「读不到首问」那条硬失败分支），列表要直接
+// 报「已定稿」—— 否则客户端每轮刷新都去打一发 --summarize-title，永远是失败，永远重来。
+//
+// 为什么这个标记必须由 core 给：客户端只看得到 title（恒非空，回落 prompt_head）与
+// title_summarized，它**没有**能力判断「这个组合注定失败」——那依赖归纳的输入从哪来，
+// 是 CLI 的内部知识。让客户端自己猜就会分叉。
+func TestSessionsMarksUnsortedWhenSummarizeImpossible(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv(session.EnvDir, dir)
+	oldLog := SessionLogDirOverride
+	defer func() { SessionLogDirOverride = oldLog }()
+	SessionLogDirOverride = t.TempDir() // 空目录：任何会话都没有事件日志
+
+	/* 造两条记录：一条会拿到 session_id（引擎吐 id，归纳必然读不到首问），
+	   一条不吐 id（首轮，prompt_head 就是首问，归纳**有**机会成功）。
+	   用真实的调用链造（假引擎 + --save-registry），不手写记录文件 ——
+	   writeRecord 没导出，而且手写的记录容易和 Read 侧的归一规则脱节。 */
+	registerFake(&sidEngine{name: "fake-hard-sid", text: "ok", sid: "sid-hard-fail"})
+	if _, _, err := runAskCmd(t, "", "--save-registry", "-e", "fake-hard-sid", "有 id 没日志"); err != nil {
+		t.Fatalf("造带 id 的记录失败: %v", err)
+	}
+	registerFake(&stringEngine{name: "fake-no-sid", text: "ok"})
+	if _, _, err := runAskCmd(t, "", "--save-registry", "-e", "fake-no-sid", "没 id 也没日志"); err != nil {
+		t.Fatalf("造无 id 的记录失败: %v", err)
+	}
+
+	var rows []struct {
+		RunID           string `json:"run_id"`
+		SessionID       string `json:"session_id"`
+		TitleSummarized bool   `json:"title_summarized"`
+		HasLog          bool   `json:"has_log"`
+	}
+	out := mustSessions(t)
+	if err := json.Unmarshal([]byte(out), &rows); err != nil {
+		t.Fatalf("--sessions 输出不是 JSON：%v", err)
+	}
+	bySID := map[string]struct {
+		TitleSummarized bool
+		HasLog          bool
+	}{}
+	for _, r := range rows {
+		bySID[r.SessionID] = struct {
+			TitleSummarized bool
+			HasLog          bool
+		}{r.TitleSummarized, r.HasLog}
+	}
+
+	hard, ok := bySID["sid-hard-fail"]
+	if !ok {
+		t.Fatalf("有 session_id 的那条没出现在列表里：%s", out)
+	}
+	if hard.HasLog {
+		t.Error("前置条件不成立：这条本来就没有日志")
+	}
+	if !hard.TitleSummarized {
+		t.Error("有 session_id + 无日志 = 归纳必然失败，列表必须报 title_summarized=true（别再让客户端重试）")
+	}
+
+	// 没有 session_id 的那条：SessionID 为空串。
+	soft, ok := bySID[""]
+	if !ok {
+		t.Fatalf("没有 session_id 的那条没出现在列表里：%s", out)
+	}
+	if soft.TitleSummarized {
+		t.Error("没有 session_id 的会话归纳有机会成功（prompt_head 就是首问），不该被标成已定稿")
+	}
+}

package/internal/cli/sessionlog.go

@@ -118,6 +118,12 @@ type sessionEvent struct {
 	// Error / Reason 异常收尾的原因（仅 turn_failed），与事件流同源。
 	Error  string `json:"error,omitempty"`
 	Reason string `json:"reason,omitempty"`
+	/* 失败分类（2026-10-25，仅 turn_failed）：与事件流同名同义（见 events.go 的
+	   streamEventPayload）。落盘它是为了让**历史回放画出同一张卡** —— 额度用尽
+	   那一轮翻回去看，仍应是「额度卡」而不是普通失败卡。 */
+	ErrorKind string `json:"error_kind,omitempty"`
+	ErrorCode string `json:"error_code,omitempty"`
+	ResetAt   string `json:"reset_at,omitempty"`
 	// Attachments 用户提问携带的附件（仅 kind:"user" 有）。引擎事件里没有附件信息
 	// （`image` 事件只对应助手**产出**），所以只有落在这里，历史回放才复原得出
 	// 「那一轮用了哪张图」—— 移动端据此在历史气泡里画出缩略图。

package/internal/cli/sessionlog_test.go

@@ -216,10 +216,30 @@ func TestSessionWriterRealisticStream(t *testing.T) {
 	if len(evs) != 7 {
 		t.Fatalf("ReadSessionLog 期望 7 条，实得 %d", len(evs))
 	}
+
+	/* 额度卡三项要**落盘**（2026-10-25）：只走实时流不带它们，用户翻历史时那一轮就退回
+	   普通失败卡 —— 「当时看到的」和「事后回看的」长成两张脸，是本仓库反复踩过的那类问题。 */
+	sw2, err := newSessionWriterAuto(sessionLogDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sw2.setSessionID("sess-quota")
+	sw2.push(sessionEvent{
+		Kind: "turn_failed", Status: "failed",
+		Error: "429 You have exceeded the 5-hour usage quota.", Reason: "429 You have exceeded the 5-hour usage quota.",
+		ErrorKind: "quota", ErrorCode: "429", ResetAt: "2026-10-25T15:07:27+08:00",
+	})
+	drain(t, sw2)
+	back, err := ReadSessionLog("", "sess-quota")
+	if err != nil || len(back) != 1 {
+		t.Fatalf("读回额度那一轮失败：%v（%d 条）", err, len(back))
+	}
+	if back[0].ErrorKind != "quota" || back[0].ErrorCode != "429" || back[0].ResetAt != "2026-10-25T15:07:27+08:00" {
+		t.Errorf("落盘丢了额度字段：%+v", back[0])
+	}
 }
 
-/* ── 2026-10-15：日志不再等 session_id 才创建 ──
-   用户要求：「不等终点事件就应该创建会话落库，这样多个客户端马上就能看到正在跑的会话」。
+/* ── 2026-10-15：日志不再等 session_id 才创建 ──   用户要求：「不等终点事件就应该创建会话落库，这样多个客户端马上就能看到正在跑的会话」。
    此前日志要等引擎吐 session_id 才知道文件名 → 正在跑的会话读出来永远是空历史；
    引擎整轮不给 id 时（dsh 的 headless 回退轮）更是收工就把内存 buffer 丢光。 */
 

package/internal/client/apk.go

@@ -105,6 +105,11 @@ func (s *Service) handleAppInfo(w http.ResponseWriter, r *http.Request) {
 		Version string `json:"version"`
 		Size    int64  `json:"size"`
 		URL     string `json:"url"`
+		/* Upgrade（2026-10-26 只增字段）：这个客户端**自己能不能**做桌面端 npm 一键升级
+		   （npm 在 PATH 上、找得到目标二进制）。为 true 时界面的「检测更新」会顺手问
+		   /desk/core，一次把「App 有没有新版」「桌面 CLI 有没有新版」都报出来。
+		   旧插件没有这个字段 → 界面只查 APK，不假装能升桌面端。 */
+		Upgrade bool `json:"upgrade"`
 	}{}
 	if s.apkAvailable() {
 		if st, err := os.Stat(s.apkPath); err == nil {
@@ -113,6 +118,9 @@ func (s *Service) handleAppInfo(w http.ResponseWriter, r *http.Request) {
 			out.URL = "/desk/app.apk"
 		}
 	}
+	if s.upgradableCore() {
+		out.Upgrade = true
+	}
 	writeJSON(w, http.StatusOK, out)
 }
 

package/internal/client/apk_test.go

@@ -41,6 +41,7 @@ func TestAppInfoAndAPK(t *testing.T) {
 		Version string `json:"version"`
 		Size    int64  `json:"size"`
 		URL     string `json:"url"`
+		Upgrade bool   `json:"upgrade"`
 	}
 	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
 		t.Fatal(err)
@@ -48,6 +49,12 @@ func TestAppInfoAndAPK(t *testing.T) {
 	if got.Version != "2.1.2" || got.URL != "/desk/app.apk" || got.Size != int64(len("fake-apk-2.1.2")) {
 		t.Fatalf("app info = %+v", got)
 	}
+	// 2026-10-26：/desk/app 要顺手告诉界面「这份客户端能不能一键升桌面端 npm」，
+	// 界面据此一次检测 APK + npm。值与本机真实探测一致（测试机上有没有 npm 不定），
+	// 不写死。
+	if got.Upgrade != s.upgradableCore() {
+		t.Fatalf("/desk/app.upgrade 与本机探测不一致：%+v", got)
+	}
 
 	rec = httptest.NewRecorder()
 	s.handleAppAPK(rec, httptest.NewRequest(http.MethodGet, "/desk/app.apk", nil))
@@ -87,6 +94,58 @@ func TestAppInfoWithoutAPK(t *testing.T) {
 	}
 }
 
+// 2026-10-26 用户：「版本检测需要同时考虑 apk 和 npm，都要支持升级」。
+// 升级链路（coreupgrade.go）早就写好、单测也一直在跑，但正式路由从没挂上 ——
+// 手机问 /desk/core 拿到的是 404 页而不是版本信息。这条钉住「真的挂上去了」。
+func TestVersionRoutesRegistered(t *testing.T) {
+	s, _ := newUpgradeService(t)
+	h := s.Handler()
+	hdr := map[string]string{"X-Magic-Token": s.opts.Token}
+	for _, path := range []string{"/desk/core", "/desk/core/upgrade"} {
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		for k, v := range hdr {
+			req.Header.Set(k, v)
+		}
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, req)
+		if rec.Code == http.StatusNotFound {
+			t.Fatalf("%s 没挂到正式路由上（404）", path)
+		}
+	}
+	// GET /desk/core 的响应形状：界面按这些字段决定「能不能一键升」。
+	req := httptest.NewRequest(http.MethodGet, "/desk/core", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("/desk/core code = %d: %s", rec.Code, rec.Body.String())
+	}
+	var info coreInfo
+	if err := json.Unmarshal(rec.Body.Bytes(), &info); err != nil {
+		t.Fatal(err)
+	}
+	if !info.CanUpgrade || !info.Upgradable || info.Latest != "2.4.2" {
+		t.Fatalf("/desk/core = %+v", info)
+	}
+}
+
+// 找得到 npm + 目标二进制时，/desk/app 必须明说「能升桌面端」，界面才会去问 /desk/core。
+func TestAppInfoReportsNpmUpgradeAvailability(t *testing.T) {
+	s, _ := newUpgradeService(t)
+	apk := writeTestAPK(t, t.TempDir(), "2.4.1")
+	s.apkPath = apk
+	rec := httptest.NewRecorder()
+	s.handleAppInfo(rec, httptest.NewRequest(http.MethodGet, "/desk/app", nil))
+	var got struct {
+		Upgrade bool `json:"upgrade"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if !got.Upgrade {
+		t.Fatalf("/desk/app.upgrade = false，但假 npm 与目标二进制都在：%s", rec.Body.String())
+	}
+}
+
 func TestAPKVersionFallsBackToFilename(t *testing.T) {
 	dir := t.TempDir()
 	apk := filepath.Join(dir, "magic-agent-mobile-3.2.1-release.apk")