magic-agent 2.3.2 → 2.4.2

package/internal/client/service.go

@@ -80,6 +80,14 @@ type Options struct {
 	// 为什么可配：UA 会决定站点给哪一版页面。中国大陆出口 + 移动 UA 时，Google 会跳到
 	// http://www.google.cn/m（该路径本身就是 404）；换成桌面 UA 则走香港跳转、可正常打开。
 	BrowseUA string
+	// AllowAnyOrigin 对**任意 Origin** 回 CORS 头（2026-10-23）。
+	//
+	// 默认只放行「本机页面」（见 withCORS）：APK / 桌面壳这些容器源的 Origin 各不相同，
+	// 自托管部署的入口也不止本机 —— 只放行 loopback 时，从别的设备 / 别的源打开的页面
+	// 会被浏览器判成跨域失败（用户侧就是「只能本地访问」）。
+	// 打开它 = 任意网页都能**读**响应；真正的门锁仍是令牌（没有 X-Magic-Token 一律 401）。
+	// `--lan` 时默认开启（都绑 0.0.0.0 了，再按 loopback 卡 Origin 没有意义）。
+	AllowAnyOrigin bool
 }
 
 // Service 本地服务。
@@ -95,6 +103,12 @@ type Service struct {
 	runs map[string]*askRun
 	seq  int64
 
+	// jobs 服务端作业队列（同一 workspace 串行 + 幂等 + 持久化），见 jobs.go。
+	jobs *jobQueue
+
+	// inst 服务实例的稳定 id（见 instance.go）：同一台桌面的多个入口靠它归一。
+	inst instanceIDCache
+
 	// 内置浏览器中转用的 HTTP 客户端（惰性建、带 cookie jar，按上游 host 存会话）。
 	// 见 browse.go —— 它让 iframe 的流量走**桌面端网络**，而不是手机直连。
 	browseOnce sync.Once
@@ -196,6 +210,9 @@ func New(opts Options) (*Service, error) {
 			return nil, fmt.Errorf("core 缺通道能力 %s（需要支持 --stream --events 与 --control 的版本）", f)
 		}
 	}
+	/* 作业队列：服务端权威的排队层（多客户端串行 / 幂等 / 重启恢复）。
+	   必须在 New 里就建好：/desk/ask 第一次进来就要能入队。 */
+	s.jobs = newJobQueue(s)
 	return s, nil
 }
 
@@ -218,6 +235,10 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/desk/profile", s.guard(s.handleProfile))
 	mux.HandleFunc("/desk/modules", s.guard(s.handleModules))
 	mux.HandleFunc("/desk/sessions", s.guard(s.handleSessions))
+	/* 服务端作业队列（2026-10-23）：跨客户端提交 / 查询 / 取消 / 事件。
+	   /desk/ask 也走同一个调度器，这里给需要「先入队、不挂长连接」的客户端用。 */
+	mux.HandleFunc("/desk/jobs", s.guard(s.handleJobs))
+	mux.HandleFunc("/desk/jobs/", s.guard(s.handleJobsSub))
 	mux.HandleFunc("/desk/upload", s.guard(s.handleUpload))
 	// 回读已上传附件（缩略图 / 历史回看）：<img> 带不了自定义头，靠 guard 支持的 ?token= 过鉴权。
 	mux.HandleFunc("/desk/uploads/", s.guard(s.handleUploadGet))
@@ -299,9 +320,15 @@ func (s *Service) withCORS(next http.Handler) http.Handler {
 		if origin != "" {
 			// Origin 会随请求方变，不加 Vary 会把一个源的响应喂给另一个源。
 			w.Header().Add("Vary", "Origin")
-			if localOrigin(origin) {
+			if s.opts.AllowAnyOrigin || localOrigin(origin) {
 				w.Header().Set("Access-Control-Allow-Origin", origin)
-				w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+				/* ⚠️ 写方法必须点名（2026-10-23 用户：「删除无法删除」）。
+				   只写 GET/POST 时，容器里（源=https://localhost）的删除 / 重命名 / 置顶同步
+				   全是带 X-Magic-Token 的 DELETE、PUT → 必发 OPTIONS 预检 → 浏览器看到
+				   DELETE 未被允许，**真请求根本发不出去**（fetch 直接 reject）。
+				   同源页面（/m/ 远程加载、桌面壳）不走预检，所以只有打包进 App 的那侧坏 ——
+				   curl 也永远看不见这条，必须靠 cors_test 钉住。 */
+				w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
 				w.Header().Set("Access-Control-Allow-Headers", "X-Magic-Token, Content-Type")
 				w.Header().Set("Access-Control-Max-Age", "600")
 			}
@@ -396,6 +423,13 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 		"engines":          len(s.contract.Engines),
 		"defaultWorkspace": wd,
 		"workspacesRoot":   filepath.Dir(wd),
+		// 服务端作业队列（2026-10-23）：有它才谈得上「多客户端串行 + 幂等」。
+		// 老插件没有该字段 → 客户端退回本地排队（见 client-ui-mobile 的 fallback）。
+		"jobs": true,
+		// 服务实例的稳定 id（2026-10-23，只增字段）：同一台桌面的本地 / 局域网 / 公网
+		// 入口可能有多条 URL，客户端据此把它们归一成同一个环境（队列与设置共用）。
+		// 老插件没有该字段 → 客户端退回按连接各自算环境。
+		"instanceId": s.instanceID(),
 		// 远程移动端界面在不在（见 handleMobileUI）。
 		// 客户端的闸门页要据此决定「跳远程 /m/ 还是用包里自带的 ui.html」。
 		// 为什么不放在 features 里：features 是**core 的能力位**（s.contract.Features），
@@ -681,8 +715,15 @@ func (s *Service) handleSessionMessages(w http.ResponseWriter, r *http.Request)
 			}
 			return
 		}
+		/* 停止这一轮：**跨进程**用 —— 手机 / 另一台设备只尾随了别人进程里跑的那一轮，
+		   手里没有 ask id（/desk/ask/{id}/control 打不到），只能按会话 id 停。
+		   与 core 的 `--stop` 同一条路（登记表里的 pid + SIGTERM）。 */
+		if ok && action == "stop" && r.Method == http.MethodPost {
+			s.handleSessionStop(w, r, id)
+			return
+		}
 		writeErr(w, http.StatusMethodNotAllowed,
-			"POST / PUT 只支持 /desk/session/{id}/title 与 /desk/session/{id}/title/summarize")
+			"POST / PUT 只支持 /desk/session/{id}/title、/desk/session/{id}/title/summarize 与 /desk/session/{id}/stop")
 		return
 	}
 	if r.Method != http.MethodGet {
@@ -1071,6 +1112,27 @@ func truncateForMsg(s string) string {
 	return string(r[:cap]) + "…"
 }
 
+// handleSessionStop 停止某条会话正在跑的那一轮（跨进程）。
+//
+// 语义与 core 的 `magic-agent --stop <id>` 完全一致（session.Stop：SIGTERM 进程组，
+// 宽限期不退再 SIGKILL，最后把状态写成 cancelled）：
+//   - id 收 session_id 或 run_id；
+//   - 幂等：进程已不在 / 会话已结束 → stopped=false + reason，仍是 200；
+//   - 找不到 id → 404（多半是 id 写错了）。
+//
+// 为什么不让客户端一律走 /desk/ask/{id}/control：那个 id 只存在于**拉起 core 的那个
+// 进程**里。手机、另一台设备、桌面壳直接 exec 的轮次都只能读盘尾随（见 /desk/session/{id}/follow），
+// 手里没有 ask id；这时不看登记表就永远停不下来（用户侧表现：「点了停止只回一句
+// 还没拿到轮次 id」）。
+func (s *Service) handleSessionStop(w http.ResponseWriter, r *http.Request, id string) {
+	res, err := session.Stop(id)
+	if err != nil {
+		writeErr(w, http.StatusNotFound, fmt.Sprintf("停止会话 %s 失败：%v", id, err))
+		return
+	}
+	writeJSON(w, http.StatusOK, res)
+}
+
 // handleSessionDelete DELETE /desk/session/{id}：删掉一个会话 —— 登记表记录（可多条 run）
 // 与落盘的事件日志。id 可以是 session_id 或 run_id。
 //
@@ -1796,6 +1858,15 @@ type askRequest struct {
 	// 不改变执行语义。core 没有 feature.session.hosted 时插件**忽略**它 ——
 	// 实时气泡仍由客户端自己标，老 core 上只是历史回放少一个标识，不该阻断发送。
 	Hosted bool `json:"hosted,omitempty"`
+	// RequestID 客户端生成的幂等键（2026-10-23，只增字段）。
+	//
+	// 同一个 id 重复提交（断线重连 / App 重启 / 两个标签页同时发）只执行一次：
+	// 服务端按它找到原作业并接回去，见 jobs.go。空 = 旧客户端，按匿名提交处理
+	// （仍参与 workspace 串行，但没有幂等保护）。
+	RequestID string `json:"request_id,omitempty"`
+	// Serial 是否参与「同一 workspace 单槽」串行（nil / true = 参与）。
+	// 客户端「并行模式」显式传 false；服务端仍会套一层全局并发上限。
+	Serial *bool `json:"serial,omitempty"`
 }
 
 // teamRequest 团队模式的请求体（POST /desk/ask 的 team 字段）。
@@ -1982,6 +2053,19 @@ func (r *askRun) finish(code int) {
 	r.mu.Unlock()
 }
 
+// snapshot 取 seq > after 的事件（after=0 时额外放行网关合成的用户提问，seq=0）。
+// 与 handleAskEvents 的返回口径一致，供 SSE 中继与作业事件共用。
+func (r *askRun) snapshot(after uint64) (out []askEvent, lastSeq uint64, done bool, code int, stderr string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, e := range r.events {
+		if e.seq > after || (e.seq == 0 && after == 0) {
+			out = append(out, e)
+		}
+	}
+	return out, r.seq, r.ended, r.code, r.stderr.String()
+}
+
 // handleAsk 发起一轮并**把 core 的 NDJSON 事件原样中继**给调用方（SSE）。
 //
 // 中继而不是解释：事件契约的解析权在客户端（桌面 / 移动端各一份实现），
@@ -1996,18 +2080,79 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
 		return
 	}
-	if strings.TrimSpace(req.Prompt) == "" {
-		writeErr(w, http.StatusBadRequest, "prompt 不能为空")
+	engine, _, st, perr := s.prepareAsk(req)
+	if perr != nil {
+		writeErr(w, st, perr.Error())
+		return
+	}
+
+	/* 从这里开始交给服务端调度器（见 jobs.go）：
+	   · 同一 workspace 同时只跑一条；
+	   · request_id 相同 = 同一次提交，重连 / 重发不会多跑一遍；
+	   · 排队期间在 SSE 里发 `queued`（老客户端忽略未知事件），开跑时再发 `open`。 */
+	source := requestSource(req.Client, r.Header.Get("Origin"))
+	job, created, jerr := s.jobs.submitAsk(req, engine, source)
+	if jerr != nil {
+		writeErr(w, http.StatusBadRequest, jerr.Error())
+		return
+	}
+
+	// SSE 头必须在**第一帧之前**发出，否则客户端拿到的是 application/json。
+	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("X-Accel-Buffering", "no")
+	flusher, _ := w.(http.Flusher)
+	send := func(event string, payload any) {
+		b, _ := json.Marshal(payload)
+		if event != "" {
+			fmt.Fprintf(w, "event: %s\n", event)
+		}
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		if flusher != nil {
+			flusher.Flush()
+		}
+	}
+
+	ctx := r.Context()
+	run, ok := s.jobs.waitStarted(ctx, job, func(pos int) {
+		send("queued", map[string]any{"job": job.ID, "state": JobQueued, "position": pos})
+	})
+	if !ok {
+		/* 排队期间客户端断开：匿名提交（没有 request_id）没人会再来接，直接撤掉；
+		   带 request_id 的留着 —— 客户端重启后会按同一个 id 接回来。 */
+		if ctx.Err() != nil && created && strings.TrimSpace(req.RequestID) == "" {
+			s.jobs.cancel(job.ID, "client disconnected")
+		}
+		/* 开跑前就终结（启动失败 / 被取消 / 排队过期）：补一帧 end，
+		   否则客户端只能看到连接被关掉、不知道原因。 */
+		if jv := s.jobs.get(job.ID); jv != nil && jv.terminal() {
+			code := -1
+			if jv.State == JobDone {
+				code = 0
+			}
+			send("end", map[string]any{"id": job.ID, "code": code, "stderr": jv.Error, "state": jv.State})
+		}
 		return
 	}
+	send("open", map[string]any{"id": run.id, "engine": engine, "core": s.opts.MagicAgent, "job": job.ID})
+	s.relayRun(ctx, w, run, flusher, send)
+}
+
+/*
+prepareAsk 校验请求并拼出 core 参数（/desk/ask 与 /desk/jobs 共用一份）。
+
+	返回 (engine, args, HTTP 状态码, error)；error 非空时状态码用于直接回给客户端。
+*/
+func (s *Service) prepareAsk(req askRequest) (string, []string, int, error) {
+	if strings.TrimSpace(req.Prompt) == "" {
+		return "", nil, http.StatusBadRequest, fmt.Errorf("prompt 不能为空")
+	}
 	engine := strings.TrimSpace(req.Engine)
 	if engine == "" {
-		writeErr(w, http.StatusBadRequest, "engine 不能为空（清单见 /desk/engines）")
-		return
+		return "", nil, http.StatusBadRequest, fmt.Errorf("engine 不能为空（清单见 /desk/engines）")
 	}
 	if !s.opts.Profile.AllowsEngine(engine) {
-		writeErr(w, http.StatusForbidden, fmt.Sprintf("profile 白名单不允许引擎 %q", engine))
-		return
+		return "", nil, http.StatusForbidden, fmt.Errorf("profile 白名单不允许引擎 %q", engine)
 	}
 
 	idle := strings.TrimSpace(req.Idle)
@@ -2056,14 +2201,12 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		/* 老 core 不认识 --team（exit 2），这里先挡下并**说清楚为什么**：
 		   让用户看到「core 太旧，请升级」比让它跑一轮后报 usage error 好得多。 */
 		if !hasStr(s.contract.Features, FeatureSessionTeam) {
-			writeErr(w, http.StatusNotImplemented,
-				"当前 core 不支持团队模式（缺少 "+FeatureSessionTeam+" 能力位，请升级 magic-agent）")
-			return
+			return "", nil, http.StatusNotImplemented,
+				fmt.Errorf("当前 core 不支持团队模式（缺少 %s 能力位，请升级 magic-agent）", FeatureSessionTeam)
 		}
 		teamArgs, terr := teamFlags(req.Team, s.opts.Profile, s.teamRoleNames())
 		if terr != nil {
-			writeErr(w, http.StatusBadRequest, terr.Error())
-			return
+			return "", nil, http.StatusBadRequest, terr
 		}
 		args = append(args, teamArgs...)
 	}
@@ -2079,16 +2222,13 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		}
 		st, err := os.Stat(p)
 		if err != nil {
-			writeErr(w, http.StatusBadRequest, "附件不可访问："+p)
-			return
+			return "", nil, http.StatusBadRequest, fmt.Errorf("附件不可访问：%s", p)
 		}
 		if !st.Mode().IsRegular() {
-			writeErr(w, http.StatusBadRequest, "附件不是普通文件："+p)
-			return
+			return "", nil, http.StatusBadRequest, fmt.Errorf("附件不是普通文件：%s", p)
 		}
 		if st.Size() > maxUploadBytes {
-			writeErr(w, http.StatusBadRequest, fmt.Sprintf("附件超过 %dMB：%s", maxUploadBytes>>20, p))
-			return
+			return "", nil, http.StatusBadRequest, fmt.Errorf("附件超过 %dMB：%s", maxUploadBytes>>20, p)
 		}
 		args = append(args, "-a", p)
 	}
@@ -2098,35 +2238,35 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	if req.Hosted && hasStr(s.contract.Features, FeatureSessionHosted) {
 		args = append(args, "--hosted")
 	}
+	return engine, args, http.StatusOK, nil
+}
 
-	/* 子进程**不绑 HTTP 请求的生命周期**（2026-10-19）：此前用 r.Context()，手机端 SSE
-	   一断（锁屏 / 切后台 / WebView 回收 / 页面刷新）就会 SIGKILL core —— core 来不及写
-	   终态，登记表里那条会话就永远停在 running：界面显示「一直不结束」，移动端的串行门
-	   （同空间有 running 就排队）还会被它永久挡住，新任务发不出去。
-	   客户端断连只意味着「没人看直播了」，不是「取消任务」；任务只应由显式控制
-	   （/desk/ask/{id}/control 的 stop）或自然结束来终止。
-	   WithoutCancel 保留请求里的值（便于排障），但不继承取消信号。
-	   也**不能**在这里 WithCancel + defer cancel：handler 断连就会返回，defer 一执行
-	   就等于把仍在跑的任务杀掉 —— 那正是要修的行为。 */
-	ctx := context.WithoutCancel(r.Context())
+/*
+	startAsk 真正拉起 core 并开始吸收 stdout（不绑任何 HTTP 请求）。
 
+排队与否由 jobs.go 决定；这里只负责「起了之后」的事：
+stdout 全部进 askRun 的回放缓冲，谁来读（SSE / /desk/ask/{id}/events / 作业事件）
+都用同一份，断连不影响任务本身。
+*/
+func (s *Service) startAsk(req askRequest, engine string, args []string, source string) (*askRun, error) {
+	ctx := context.WithoutCancel(context.Background())
 	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
 	/* 两个「谁发起的」维度随环境变量传给 core，落到会话登记表：
 	   · EnvSource  设备形态（mobile / pc）—— 按请求 Origin 判定，列表页显示设备标志；
-	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话**，
-	     不把直接跑 CLI / 别的应用的任务混进来（用户 2026-10-12）。 */
+	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话**。
+	   另外注入工作空间锁（选入式，见 internal/session/workspace_lock.go）：core 在 Begin
+	   时先抢锁再写 running，让直接跑 CLI 的进程也参与同一套串行。 */
 	cmd.Env = append(os.Environ(),
-		session.EnvSource+"="+requestSource(req.Client, r.Header.Get("Origin")),
-		session.EnvClient+"="+s.opts.Profile.AppID())
+		session.EnvSource+"="+source,
+		session.EnvClient+"="+s.opts.Profile.AppID(),
+		session.EnvWorkspaceLock+"=1")
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
-		writeErr(w, http.StatusInternalServerError, "stdin pipe: "+err.Error())
-		return
+		return nil, fmt.Errorf("stdin pipe: %w", err)
 	}
 	stdout, err := cmd.StdoutPipe()
 	if err != nil {
-		writeErr(w, http.StatusInternalServerError, "stdout pipe: "+err.Error())
-		return
+		return nil, fmt.Errorf("stdout pipe: %w", err)
 	}
 	run := &askRun{
 		id:      s.nextID(),
@@ -2139,8 +2279,7 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		session: strings.TrimSpace(req.Session),
 		/* 这一轮算在哪个工作区（收尾后自动归纳要按它定位）。
 		   请求没带 workspace 时 core 会用它自己的 cwd 记录会话 —— 插件 spawn core 时
-		   不换目录，所以那个 cwd 就是插件自己的 cwd（见 handleHealth 的 defaultWorkspace）。
-		   两处口径必须一致，否则「聊了半天需求页没变」：归纳去的是另一个目录。 */
+		   不换目录，所以那个 cwd 就是插件自己的 cwd（见 handleHealth 的 defaultWorkspace）。 */
 		workspace: pinnedWorkspace(req.Workspace),
 	}
 	cmd.Stderr = run.stderr
@@ -2148,117 +2287,67 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	   断线重连 / 打开运行中会话时补出来的画面会缺「用户问的是什么」。 */
 	run.appendPrompt(req.Prompt, req.Attachments, req.Hosted)
 	if err := cmd.Start(); err != nil {
-		writeErr(w, http.StatusBadGateway, "启动 core 失败："+err.Error())
-		return
+		return nil, fmt.Errorf("启动 core 失败：%w", err)
 	}
 	s.mu.Lock()
 	s.runs[run.id] = run
 	s.mu.Unlock()
-	// 注意：这里**不** defer 摘除 s.runs —— 断连后 handler 会先返回，任务仍在跑；
-	// 摘除由后台读 stdout 的 goroutine 在 core 真正退出时做（见下）。
+	go s.pumpAsk(run, stdout)
+	return run, nil
+}
 
-	// SSE 头必须在**第一行事件之前**发出，否则客户端拿到的是 application/json。
-	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
-	w.Header().Set("Cache-Control", "no-cache")
-	w.Header().Set("X-Accel-Buffering", "no")
-	flusher, _ := w.(http.Flusher)
-	send := func(event string, payload any) {
-		b, _ := json.Marshal(payload)
-		if event != "" {
-			fmt.Fprintf(w, "event: %s\n", event)
-		}
-		fmt.Fprintf(w, "data: %s\n\n", b)
-		if flusher != nil {
-			flusher.Flush()
+// pumpAsk 读尽 stdout（断连也照读，否则管道写满会把 core 卡死），收尾后通知调度器。
+func (s *Service) pumpAsk(run *askRun, stdout io.Reader) {
+	sc := bufio.NewScanner(stdout)
+	sc.Buffer(make([]byte, 0, 64*1024), 4<<20)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" {
+			continue
 		}
+		run.appendEvent(line)
 	}
-	send("open", map[string]any{"id": run.id, "engine": engine, "core": s.opts.MagicAgent})
+	werr := run.cmd.Wait()
+	code := 0
+	if werr != nil {
+		var ee *exec.ExitError
+		if errors.As(werr, &ee) {
+			code = ee.ExitCode()
+		} else {
+			code = -1
+		}
+	}
+	run.finish(code)
+	s.jobs.runEnded(run)
+	/* 需求自动归纳（2026-10-22）：一轮收尾后防抖触发（12s 内再来一轮顺延）。
+	   用 run 上记死的 workspace，不重新读 cwd —— 归纳必须落在**这一轮聊的那个目录**。 */
+	s.maybeAutoConsolidate(run.workspace)
+	close(run.done)
+	/* 任务结束后**不立刻摘除**：客户端可能在断线重连后补拉终态（askRetention 窗口）。 */
+	time.AfterFunc(askRetention, func() {
+		s.mu.Lock()
+		if cur := s.runs[run.id]; cur == run {
+			delete(s.runs, run.id)
+		}
+		s.mu.Unlock()
+	})
+}
 
-	/* SSE 心跳（2026-10-19 真实报障：手机端 17.7s 就「连接中断」，而 core 在首段输出前
-	   静默了约 27s —— 期间一个字节都没写，移动网络 / WebView 会把这条连接当成死连接掐掉，
-	   服务端任务其实一直跑到了 turn_end）。
-	   注释帧（以 ':' 开头、没有 data 行）按 SSE 规范会被客户端忽略，
-	   本仓库的 transport-http.js 解析器也只认 data 行，因此安全。 */
+/*
+relayRun 把一轮的事件按 seq 增量推给 SSE。
+
+	不再用「读 stdout 的 goroutine → channel」那条路：作业可能先排队再开跑，
+	多一个消费者时 channel 会互相抢；回放缓冲天然支持多读者。
+*/
+func (s *Service) relayRun(ctx context.Context, w http.ResponseWriter, run *askRun, flusher http.Flusher, send func(string, any)) {
+	var after uint64
+	tick := time.NewTicker(80 * time.Millisecond)
 	ping := time.NewTicker(10 * time.Second)
+	defer tick.Stop()
 	defer ping.Stop()
-
-	/* 读 stdout 与写 SSE 分开成两个 goroutine（2026-10-19）：
-	   客户端断连时 handler 立即返回，但**后台必须继续把 core 的 stdout 抽干** ——
-	   否则管道写满后 core 会阻塞在写事件上，任务反而被卡死。
-	   handler 走人之前关掉 detached，后台就改为「只 drain、不再入队」。 */
-	lines := make(chan string, 64)
-	detached := make(chan struct{})
-	finished := make(chan int, 1)
-	go func() {
-		sc := bufio.NewScanner(stdout)
-		sc.Buffer(make([]byte, 0, 64*1024), 4<<20)
-		gone := false
-		for sc.Scan() {
-			line := strings.TrimSpace(sc.Text())
-			if line == "" {
-				continue
-			}
-			// 先入回放缓冲，再判断有没有人在看直播：断连之后客户端要靠这份缓冲
-			// 按 seq 续传，漏掉「gone 之后」的行就等于把断点之后的内容丢了。
-			run.appendEvent(line)
-			if gone {
-				continue // 没人看了：只 drain，避免 core 写满管道
-			}
-			select {
-			case lines <- line:
-			case <-detached:
-				gone = true
-			}
-		}
-		close(lines)
-		werr := cmd.Wait()
-		code := 0
-		if werr != nil {
-			var ee *exec.ExitError
-			if errors.As(werr, &ee) {
-				code = ee.ExitCode()
-			} else {
-				code = -1
-			}
-		}
-		run.finish(code)
-		/* 需求自动归纳（2026-10-22）：一轮收尾后防抖触发（12s 内再来一轮顺延）。
-		   用 run 上记死的 workspace，不重新读 cwd —— 归纳必须落在**这一轮聊的那个目录**，
-		   而进程 cwd 在这期间可能被 profile 切换（--ui-dir 之类的启动参数不影响，但
-		   以后会有切换空间的功能；钉住是零成本的正确做法）。
-		   放在 finish 之后：先让 /desk/asks 与 SSE 看到本轮结束，再让后台开始整理。 */
-		s.maybeAutoConsolidate(run.workspace)
-		close(run.done)
-		/* 任务结束后**不立刻摘除**：客户端可能在断线重连后在补拉终态
-		   （`GET /desk/ask/{id}/events`），留 askRetention 的时间窗。
-		   保留期内若同一个 id 被重新登记（不可能，id 唯一）也不覆盖。
-		   handleAsks 会按 ended 过滤，所以这个「僵尸条目」不会出现在运行中列表。 */
-		time.AfterFunc(askRetention, func() {
-			s.mu.Lock()
-			if cur := s.runs[run.id]; cur == run {
-				delete(s.runs, run.id)
-			}
-			s.mu.Unlock()
-		})
-		finished <- code
-	}()
-	// 断连后后台继续跑完任务；handler 只负责把已有事件送出去。
-	defer close(detached)
-
 	for {
 		select {
-		case line, ok := <-lines:
-			if !ok {
-				lines = nil // 等 finished（stdout 已读尽，core 正在退出）
-				continue
-			}
-			// 原样中继：核心事件流自己就是 NDJSON，不再包一层。
-			fmt.Fprintf(w, "data: %s\n\n", line)
-			if flusher != nil {
-				flusher.Flush()
-			}
-		case code := <-finished:
-			send("end", map[string]any{"id": run.id, "code": code, "stderr": run.stderr.String()})
+		case <-ctx.Done():
 			return
 		case <-ping.C:
 			// 心跳：只养连接，不下发业务数据（解析端会忽略没有 data 行的帧）。
@@ -2266,8 +2355,29 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 			if flusher != nil {
 				flusher.Flush()
 			}
-		case <-r.Context().Done():
-			return
+		case <-tick.C:
+			events, last, done, code, stderr := run.snapshot(after)
+			for _, e := range events {
+				/* seq=0 是网关合成的「用户提问」（见 appendPrompt）：它只进回放缓冲，
+				   不进实时 SSE —— 实时路径上客户端自己已经画过用户气泡了。 */
+				if e.seq == 0 {
+					continue
+				}
+				fmt.Fprintf(w, "data: %s\n\n", e.data)
+				if e.seq > after {
+					after = e.seq
+				}
+			}
+			if last > after {
+				after = last
+			}
+			if flusher != nil {
+				flusher.Flush()
+			}
+			if done {
+				send("end", map[string]any{"id": run.id, "code": code, "stderr": stderr})
+				return
+			}
 		}
 	}
 }

package/internal/client/service_test.go

@@ -71,7 +71,13 @@ const hostedContract = `{"contractVersion":2,"features":["feature.session.events
 
 func newTestService(t *testing.T, core string) *Service {
 	t.Helper()
-	svc, err := New(Options{MagicAgent: core, Profile: DefaultProfile(), Token: "tok"})
+	/* 测试互不干扰：作业目录 / 实例 id 都放临时目录；并发上限放大（假 core 不退出，
+	   不放大就会把同一进程里后续用例堵在队列里）。串行语义由 TestJobs* 用独立服务端覆盖。 */
+	t.Setenv("MAGIC_CLIENT_JOBS_DIR", t.TempDir())
+	t.Setenv("MAGIC_CLIENT_MAX_RUNNING", "64")
+	prof := DefaultProfile()
+	prof.Storage.Dir = t.TempDir()
+	svc, err := New(Options{MagicAgent: core, Profile: prof, Token: "tok"})
 	if err != nil {
 		t.Fatalf("New: %v", err)
 	}
@@ -111,6 +117,33 @@ func TestNewRejectsContractMismatch(t *testing.T) {
 	})
 }
 
+// TestSessionStopRoute 手机 / 另一台设备只能按**会话 id** 停（那一轮在别人的进程里，
+// 手里没有 ask id）：路由必须存在，且未知 id 要诚实 404 —— 默默 200 会让界面以为停住了。
+func TestSessionStopRoute(t *testing.T) {
+	t.Setenv(session.EnvDir, t.TempDir())
+	svc := newTestService(t, fakeCore(t, goodContract))
+	srv := httptest.NewServer(svc.Handler())
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/desk/session/no-such-session/stop", nil)
+	req.Header.Set("X-Magic-Token", "tok")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("未知会话应 404，实际 %d", resp.StatusCode)
+	}
+	var body map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(fmt.Sprint(body["error"]), "no such session") {
+		t.Errorf("404 应说明找不到该会话，实际 %v", body["error"])
+	}
+}
+
 // TestAuthRequired 静态资源不鉴权，但 /desk/* 必须带令牌 ——
 // 本地端口对同机所有进程可见，不鉴权等于把引擎执行权交出去。
 func TestAuthRequired(t *testing.T) {
@@ -204,6 +237,18 @@ type sseReader struct {
 func openSSE(t *testing.T, url, token string, body any) *sseReader {
 	t.Helper()
 	b, _ := json.Marshal(body)
+	/* 这些用例验的是「中继 / 参数透传」，不是串行：显式 serial=false 让它们保持并发，
+	   否则假 core 跑完一轮后还等在 stdin 上，会把同一 workspace 的下一条堵死。
+	   串行语义由 TestJobs* 专门覆盖。 */
+	var m map[string]any
+	if err := json.Unmarshal(b, &m); err == nil && m != nil {
+		if _, ok := m["serial"]; !ok {
+			m["serial"] = false
+			if nb, err := json.Marshal(m); err == nil {
+				b = nb
+			}
+		}
+	}
 	req, _ := http.NewRequest(http.MethodPost, url+"/desk/ask", bytes.NewReader(b))
 	req.Header.Set("X-Magic-Token", token)
 	req.Header.Set("Accept", "text/event-stream")

package/internal/session/session.go

@@ -325,6 +325,8 @@ type Handle struct {
 	noPersist bool
 	// lastTouch 上次 Touch 续期的时间（节流用，见 Touch）。
 	lastTouch time.Time
+	// lock 工作空间串行锁（见 workspace_lock.go；未启用时为 nil）。
+	lock *WorkspaceLock
 }
 
 // RunID 本次运行的 id。
@@ -416,6 +418,7 @@ func (h *Handle) Finish(sessionID, state string) {
 	if h == nil {
 		return
 	}
+	defer h.lock.Release() // 工作空间锁随本轮结束释放（未启用时是 nil，安全）
 	if state == StateFailed {
 		if cur, err := readRecord(h.path); err == nil && isTerminalOverride(cur.State) {
 			state = cur.State
@@ -478,6 +481,17 @@ func Begin(o BeginOptions) (*Handle, error) {
 	if !o.NoPersist {
 		dropUnreadable(dir)
 	}
+	/* 工作空间串行锁（选入式，见 workspace_lock.go）：拿到锁之后才写 running 记录，
+	   别的进程看到的「在跑」就一定是已经可以开跑的。
+	   ⚠️ 团队子任务（ParentRunID 非空）不参与：它们与主任务同属一个工作空间，
+	      再取一把锁就是自己锁自己。 */
+	var wl *WorkspaceLock
+	if strings.TrimSpace(o.ParentRunID) == "" {
+		var lerr error
+		if wl, lerr = acquireWorkspaceLock(o.Workspace); lerr != nil {
+			return nil, lerr
+		}
+	}
 
 	now := time.Now()
 	rec := Record{
@@ -503,7 +517,7 @@ func Begin(o BeginOptions) (*Handle, error) {
 	}
 	// path 照样算出来：追加入口的 socket 与它同目录同前缀（见 AppendSocketPath），
 	// 句柄里留着它，SetAppendPath 之类也不用知道自己是不是在存档模式。
-	h := &Handle{rec: rec, path: filepath.Join(dir, rec.RunID+".json"), noPersist: o.NoPersist}
+	h := &Handle{rec: rec, path: filepath.Join(dir, rec.RunID+".json"), noPersist: o.NoPersist, lock: wl}
 	h.write() // noPersist 时这里什么都不做
 	// 「新起即停旧」：同一条会话上还活着的上一次运行先停掉（见 supersedeSiblings）。
 	if !o.NoPersist && rec.SessionID != "" {