magic-agent 2.3.2 → 2.4.2

package/internal/client/jobs.go

@@ -0,0 +1,1160 @@
+package client
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/session"
+)
+
+/* ── 服务端作业队列（2026-10-23，多客户端串行的权威层）──
+
+为什么队列一定要在服务端：
+  · 排队判断原先在每台手机的页面里，各判各的 —— 两台设备同时看到「空闲」就同时开跑；
+  · 页面被杀 / 切环境 / 锁屏，客户端队列就断了，而任务不该断；
+  · 同一个 request_id 需要跨客户端、跨页面实例去重，只有服务端做得到。
+
+几个不变量：
+  1. 同一 workspace 同时只跑一条（Serial=true 时）；不同 workspace 并行；
+  2. 全局并发上限（MAGIC_CLIENT_MAX_RUNNING，默认 4）兜底，防 fork 风暴；
+  3. request_id 相同 = 同一次提交：重复 POST 返回原作业，不会多跑一遍；
+  4. 排队/运行状态落盘（<data dir>/jobs/*.json），服务重启后 queued 继续、running 残留标失败；
+  5. 客户端全断也不撤销已开跑的任务；匿名排队（没有 request_id）在连接断开时撤销。
+
+与 /desk/ask 的关系：/desk/ask 先入队再等准入，排队期间发 `event: queued`，
+准入后照旧发 `open` + 事件流。老客户端不改一行也能拿到服务端串行。
+*/
+
+const (
+	JobQueued    = "queued"
+	JobRunning   = "running"
+	JobDone      = "done"
+	JobFailed    = "failed"
+	JobCancelled = "cancelled"
+	JobExpired   = "expired"
+
+	// jobQueuedTTL 排队多久没轮到就过期（避免关机一周后突然跑一堆旧任务）。
+	jobQueuedTTL = 24 * time.Hour
+	// jobKeepTerminal 终态作业保留多久（幂等重放窗口）。
+	jobKeepTerminal = 7 * 24 * time.Hour
+	// jobMaxQueued 每个 workspace 最多排多少条（防刷）。
+	jobMaxQueued = 100
+)
+
+// JobOwner 谁提交的（列表页与取消权限展示用）。
+type JobOwner struct {
+	Client string `json:"client,omitempty"`
+	Source string `json:"source,omitempty"`
+}
+
+// Job 一条排队/运行中的作业（磁盘形状即 JSON 形状）。
+type Job struct {
+	ID        string `json:"id"`
+	RequestID string `json:"request_id,omitempty"`
+
+	// Workspace 归一后的绝对路径；槽位键就用它（空工作空间 = 服务端 cwd）。
+	Workspace string `json:"workspace"`
+	// ExplicitWorkspace 原请求是否显式带了 -w：恢复时原样下发，不能替用户改写默认语义。
+	ExplicitWorkspace bool `json:"explicit_workspace,omitempty"`
+
+	Session     string       `json:"session,omitempty"`
+	Engine      string       `json:"engine"`
+	Model       string       `json:"model,omitempty"`
+	Prompt      string       `json:"prompt"`
+	Permission  string       `json:"permission,omitempty"`
+	Reasoning   string       `json:"reasoning,omitempty"`
+	Idle        string       `json:"idle,omitempty"`
+	NoThinking  bool         `json:"no_thinking,omitempty"`
+	Hosted      bool         `json:"hosted,omitempty"`
+	Attachments []string     `json:"attachments,omitempty"`
+	Team        *teamRequest `json:"team,omitempty"`
+
+	// Serial 是否参与 workspace 单槽串行（默认 true）。
+	Serial bool `json:"serial"`
+
+	State    string   `json:"state"`
+	Position int      `json:"position,omitempty"`
+	Owner    JobOwner `json:"owner"`
+
+	AskID     string `json:"ask_id,omitempty"`
+	RunID     string `json:"run_id,omitempty"`
+	SessionID string `json:"session_id,omitempty"`
+	PID       int    `json:"pid,omitempty"`
+	Error     string `json:"error,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+	StartedAt time.Time `json:"started_at,omitempty"`
+	UpdatedAt time.Time `json:"updated_at"`
+	ExpiresAt time.Time `json:"expires_at,omitempty"`
+}
+
+func (j *Job) terminal() bool {
+	switch j.State {
+	case JobDone, JobFailed, JobCancelled, JobExpired:
+		return true
+	}
+	return false
+}
+
+// askRequest 把作业还原成 core 启动参数需要的请求（不带上 RequestID：那是队列自己的事）。
+func (j *Job) askRequest() askRequest {
+	req := askRequest{
+		Engine:      j.Engine,
+		Prompt:      j.Prompt,
+		Model:       j.Model,
+		Session:     j.Session,
+		Permission:  j.Permission,
+		Reasoning:   j.Reasoning,
+		Idle:        j.Idle,
+		NoThinking:  j.NoThinking,
+		Hosted:      j.Hosted,
+		Attachments: append([]string(nil), j.Attachments...),
+		Team:        j.Team,
+		Client:      j.Owner.Source,
+	}
+	if j.ExplicitWorkspace {
+		req.Workspace = j.Workspace
+	}
+	return req
+}
+
+type jobQueue struct {
+	svc *Service
+	dir string
+
+	mu      sync.Mutex
+	jobs    map[string]*Job
+	byReq   map[string]string
+	byAsk   map[string]string
+	runs    map[string]*askRun
+	active  map[string]string // workspace → job id
+	running int
+	max     int
+	seq     int64
+
+	wake   chan struct{}
+	stop   chan struct{}
+	closed bool
+	// leaseOwned 本进程是不是调度主（同一 jobs 目录只允许一个进程真正调度）。
+	leaseOwned bool
+}
+
+const envJobsDir = "MAGIC_CLIENT_JOBS_DIR"
+const envMaxRunning = "MAGIC_CLIENT_MAX_RUNNING"
+
+func newJobQueue(s *Service) *jobQueue {
+	dir := strings.TrimSpace(os.Getenv(envJobsDir))
+	if dir == "" {
+		dir = filepath.Join(s.opts.Profile.DataDir(), "jobs")
+	}
+	q := &jobQueue{
+		svc:    s,
+		dir:    dir,
+		jobs:   map[string]*Job{},
+		byReq:  map[string]string{},
+		byAsk:  map[string]string{},
+		runs:   map[string]*askRun{},
+		active: map[string]string{},
+		max:    4,
+		wake:   make(chan struct{}, 1),
+		stop:   make(chan struct{}),
+	}
+	if v := strings.TrimSpace(os.Getenv(envMaxRunning)); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			q.max = n
+		}
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		// 落不了盘就退化成纯内存：队列仍然工作，只是重启会丢 —— 日志里说清楚。
+		s.log.Printf("作业队列无法创建目录 %s（%v），本轮退化为内存队列", dir, err)
+		q.dir = ""
+	}
+	q.load()
+	q.leaseOwned = q.ensureLease()
+	go q.loop()
+	return q
+}
+
+/* ── 持久化 ── */
+
+func (q *jobQueue) path(id string) string { return filepath.Join(q.dir, id+".json") }
+
+// persistLocked 原子写一条作业（tmp + rename）；调用方须持 q.mu（或独占该 Job）。
+func (q *jobQueue) persistLocked(j *Job) {
+	if q == nil || q.dir == "" || j == nil {
+		return
+	}
+	b, err := json.MarshalIndent(j, "", "  ")
+	if err != nil {
+		return
+	}
+	tmp := q.path(j.ID) + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, q.path(j.ID))
+}
+
+// persist 外部调用入口：自己加锁，marshal 时不会与调度器并发改字段。
+func (q *jobQueue) persist(j *Job) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	q.persistLocked(j)
+}
+
+func (q *jobQueue) removeFile(id string) {
+	if q == nil || q.dir == "" {
+		return
+	}
+	_ = os.Remove(q.path(id))
+}
+
+// load 启动时重建索引；queued 保留（带 request_id 的），running 残留标失败。
+func (q *jobQueue) load() {
+	if q.dir == "" {
+		return
+	}
+	entries, err := os.ReadDir(q.dir)
+	if err != nil {
+		return
+	}
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	now := time.Now()
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".json") {
+			continue
+		}
+		b, err := os.ReadFile(filepath.Join(q.dir, e.Name()))
+		if err != nil {
+			continue
+		}
+		var j Job
+		if err := json.Unmarshal(b, &j); err != nil || strings.TrimSpace(j.ID) == "" {
+			continue
+		}
+		switch j.State {
+		case JobRunning:
+			/* 服务重启时还在 running：core 是 NoCancel 起的，可能仍在跑。
+			   这里把作业标失败（调度器不再认它），但真正的互斥交给工作空间锁 +
+			   登记表里的活记录 —— 新任务会被 externalBusy 挡住，直到那轮结束。 */
+			j.State = JobFailed
+			j.Error = "服务重启，未完成的轮次已中断"
+			j.UpdatedAt = now
+			q.persistLocked(&j)
+		case JobQueued:
+			if j.ExpiresAt.IsZero() {
+				j.ExpiresAt = j.CreatedAt.Add(jobQueuedTTL)
+			}
+			if !j.ExpiresAt.After(now) {
+				j.State = JobExpired
+				j.Error = "排队超时，未执行"
+				j.UpdatedAt = now
+				q.persistLocked(&j)
+			} else if strings.TrimSpace(j.RequestID) == "" {
+				// 匿名排队的主人（那条 SSE）已经随进程消失，没人会来接。
+				j.State = JobCancelled
+				j.Error = "服务重启，匿名排队已撤销"
+				j.UpdatedAt = now
+				q.persistLocked(&j)
+			}
+		case JobDone, JobFailed, JobCancelled, JobExpired:
+			if !j.UpdatedAt.IsZero() && now.Sub(j.UpdatedAt) > jobKeepTerminal {
+				_ = os.Remove(filepath.Join(q.dir, e.Name()))
+				continue
+			}
+		default:
+			j.State = JobFailed
+			j.Error = "未知状态，已作废"
+			j.UpdatedAt = now
+		}
+		q.jobs[j.ID] = &j
+		if j.RequestID != "" {
+			q.byReq[j.RequestID] = j.ID
+		}
+		if j.AskID != "" {
+			q.byAsk[j.AskID] = j.ID
+		}
+	}
+}
+
+/* ── 提交 / 查询 / 取消 ── */
+
+func normalizeWorkspace(ws string) string {
+	ws = strings.TrimSpace(ws)
+	if ws == "" {
+		ws, _ = os.Getwd()
+	}
+	if abs, err := filepath.Abs(ws); err == nil {
+		ws = abs
+	}
+	return filepath.Clean(ws)
+}
+
+// submitAsk 入队（或按 request_id 接回原作业）。created=false 表示命中幂等。
+// ⚠️ 返回的是**副本**：调度器随时会把状态改成 running，直接把内部指针交出去
+// 会让 HTTP 响应一边 marshal 一边被改（数据竞争，且客户端可能先看到 running）。
+func (q *jobQueue) submitAsk(req askRequest, engine, source string) (*Job, bool, error) {
+	reqID := strings.TrimSpace(req.RequestID)
+	q.mu.Lock()
+	if reqID != "" {
+		if id, ok := q.byReq[reqID]; ok {
+			j := q.jobs[id]
+			if j != nil {
+				cp := *j
+				cp.Position = q.positionLocked(j)
+				q.mu.Unlock()
+				return &cp, false, nil
+			}
+		}
+	}
+	// 每个 workspace 的排队上限：防客户端刷爆内存/磁盘。
+	ws := normalizeWorkspace(req.Workspace)
+	queued := 0
+	for _, j := range q.jobs {
+		if j.State == JobQueued && j.Workspace == ws {
+			queued++
+		}
+	}
+	if queued >= jobMaxQueued {
+		q.mu.Unlock()
+		return nil, false, fmt.Errorf("工作空间 %s 的排队任务过多（%d），请稍后再试", ws, queued)
+	}
+
+	serial := true
+	if req.Serial != nil {
+		serial = *req.Serial
+	}
+	now := time.Now()
+	j := &Job{
+		ID:                q.nextJobIDLocked(),
+		RequestID:         reqID,
+		Workspace:         ws,
+		ExplicitWorkspace: strings.TrimSpace(req.Workspace) != "",
+		Session:           strings.TrimSpace(req.Session),
+		Engine:            engine,
+		Model:             req.Model,
+		Prompt:            req.Prompt,
+		Permission:        req.Permission,
+		Reasoning:         req.Reasoning,
+		Idle:              req.Idle,
+		NoThinking:        req.NoThinking,
+		Hosted:            req.Hosted,
+		Attachments:       append([]string(nil), req.Attachments...),
+		Team:              req.Team,
+		Serial:            serial,
+		State:             JobQueued,
+		Owner:             JobOwner{Client: strings.TrimSpace(req.Client), Source: source},
+		CreatedAt:         now,
+		UpdatedAt:         now,
+		ExpiresAt:         now.Add(jobQueuedTTL),
+	}
+	q.jobs[j.ID] = j
+	if reqID != "" {
+		q.byReq[reqID] = j.ID
+	}
+	q.recomputePositionsLocked()
+	cp := *j
+	cp.Position = q.positionLocked(j)
+	q.persistLocked(j)
+	q.mu.Unlock()
+	q.signal()
+	return &cp, true, nil
+}
+
+func (q *jobQueue) nextJobIDLocked() string {
+	q.seq++
+	return fmt.Sprintf("job-%d-%d", time.Now().UnixNano()/1e6, q.seq)
+}
+
+// get 返回作业副本（调用方不持锁）。
+func (q *jobQueue) get(id string) *Job {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	j := q.jobs[id]
+	if j == nil {
+		return nil
+	}
+	cp := *j
+	cp.Position = q.positionLocked(j)
+	return &cp
+}
+
+// list 返回作业副本（按创建时间倒序）；workspace 非空时只看该空间。
+func (q *jobQueue) list(workspace string, limit int) []*Job {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	ws := ""
+	if strings.TrimSpace(workspace) != "" {
+		ws = normalizeWorkspace(workspace)
+	}
+	out := make([]*Job, 0, len(q.jobs))
+	for _, j := range q.jobs {
+		if ws != "" && j.Workspace != ws {
+			continue
+		}
+		cp := *j
+		cp.Position = q.positionLocked(j)
+		out = append(out, &cp)
+	}
+	sort.Slice(out, func(i, k int) bool { return out[i].CreatedAt.After(out[k].CreatedAt) })
+	if limit > 0 && len(out) > limit {
+		out = out[:limit]
+	}
+	return out
+}
+
+// positionLocked 该作业在**同 workspace 队列**里排第几（1 起；运行/终态为 0）。
+func (q *jobQueue) positionLocked(j *Job) int {
+	if j.State != JobQueued {
+		return 0
+	}
+	pos := 1
+	for _, o := range q.jobs {
+		if o == j || o.State != JobQueued || o.Workspace != j.Workspace {
+			continue
+		}
+		if o.CreatedAt.Before(j.CreatedAt) ||
+			(o.CreatedAt.Equal(j.CreatedAt) && o.ID < j.ID) {
+			pos++
+		}
+	}
+	return pos
+}
+
+func (q *jobQueue) recomputePositionsLocked() {
+	for _, j := range q.jobs {
+		j.Position = q.positionLocked(j)
+	}
+}
+
+// runOf 作业当前挂着的 askRun（排队中为 nil）。
+func (q *jobQueue) runOf(id string) *askRun {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	return q.runs[id]
+}
+
+func (q *jobQueue) signal() {
+	select {
+	case q.wake <- struct{}{}:
+	default:
+	}
+}
+
+// close 停止调度循环，并给还在跑的轮次发 stop（测试收尾 / 进程优雅退出用）。
+func (q *jobQueue) close() {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	if q.closed {
+		return
+	}
+	q.closed = true
+	close(q.stop)
+	for _, run := range q.runs {
+		if run != nil && run.stdin != nil {
+			_, _ = run.stdin.Write([]byte("{\"op\":\"stop\"}\n"))
+		}
+	}
+	q.releaseLease()
+}
+
+/* ── 准入等待（/desk/ask 用）── */
+
+// waitStarted 阻塞到作业开跑（返回 run），或作业在开跑前就终结 / 客户端断开。
+func (q *jobQueue) waitStarted(ctx contextLike, job *Job, onQueued func(pos int)) (*askRun, bool) {
+	tick := time.NewTicker(200 * time.Millisecond)
+	defer tick.Stop()
+	lastPos := -1
+	began := time.Now()
+	var lastSent time.Time
+	for {
+		q.mu.Lock()
+		internal := q.jobs[job.ID]
+		run := q.runs[job.ID]
+		state := ""
+		pos := 0
+		if internal != nil {
+			state = internal.State
+			pos = q.positionLocked(internal)
+		}
+		q.mu.Unlock()
+		if run != nil {
+			return run, true
+		}
+		if state != JobQueued && state != JobRunning {
+			return nil, false
+		}
+		/* ⚠️ 空队列直通时**不能**先发 queued：老客户端按「第一帧是 open」解析，
+		   而且界面会白闪一下「排队中」。给调度器 400ms 的直通窗口，之后仍在队里才算真排队。
+		   排队超过 10s 也重发一次：既刷新位置，也当 SSE 心跳养住连接。 */
+		if onQueued != nil && pos > 0 && (pos != lastPos || time.Since(lastSent) >= 10*time.Second) &&
+			time.Since(began) >= 400*time.Millisecond {
+			lastPos = pos
+			lastSent = time.Now()
+			onQueued(pos)
+		}
+		select {
+		case <-ctx.Done():
+			return nil, false
+		case <-tick.C:
+		}
+	}
+}
+
+// contextLike 只用到 Done()，避免把 context 的类型细节带进队列签名。
+type contextLike interface {
+	Done() <-chan struct{}
+}
+
+/* ── 调度 ── */
+
+func (q *jobQueue) loop() {
+	tick := time.NewTicker(time.Second)
+	defer tick.Stop()
+	for {
+		select {
+		case <-q.stop:
+			return
+		case <-q.wake:
+		case <-tick.C:
+		}
+		q.leaseOwned = q.ensureLease()
+		q.reloadNew()
+		q.dispatch()
+	}
+}
+
+/*
+── 多实例租约 ──
+
+	同一个 jobs 目录（同一 AppID 的 DataDir）只允许一个进程真正调度：否则两个
+	magic-client 会各自拉起 core，靠 core 侧的工作空间锁才不至于并跑 —— 但那样
+	第二个进程会卡在 Begin 里等，状态显示也不对。
+	非主进程仍然接受提交（写同一个目录），主进程每秒重读目录把新作业收进来；
+	跨进程取消暂不支持（只能停已开跑的 session）—— 这是单实例默认部署之外的兜底。
+*/
+func (q *jobQueue) leasePath() string { return filepath.Join(q.dir, "scheduler.lock") }
+
+func (q *jobQueue) ensureLease() bool {
+	if q.dir == "" {
+		return true
+	}
+	path := q.leasePath()
+	now := time.Now()
+	if b, err := os.ReadFile(path); err == nil {
+		pid := 0
+		if lines := strings.Split(strings.TrimSpace(string(b)), "\n"); len(lines) > 0 {
+			pid, _ = strconv.Atoi(strings.TrimSpace(lines[0]))
+		}
+		if pid == os.Getpid() {
+			_ = os.Chtimes(path, now, now)
+			return true
+		}
+		alive := pid > 0 && agent.PIDAlive(pid)
+		fresh := false
+		if st, serr := os.Stat(path); serr == nil {
+			fresh = now.Sub(st.ModTime()) < 20*time.Second
+		}
+		if alive && fresh {
+			return false
+		}
+		_ = os.Remove(path) // 主进程已不在或心跳过期：接管
+	}
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+	if err != nil {
+		return false
+	}
+	_, _ = fmt.Fprintf(f, "%d\n%d\n", os.Getpid(), now.UnixNano())
+	_ = f.Close()
+	return true
+}
+
+func (q *jobQueue) releaseLease() {
+	if q.dir == "" {
+		return
+	}
+	b, err := os.ReadFile(q.leasePath())
+	if err != nil {
+		return
+	}
+	pid, _ := strconv.Atoi(strings.TrimSpace(strings.SplitN(string(b), "\n", 2)[0]))
+	if pid == os.Getpid() {
+		_ = os.Remove(q.leasePath())
+	}
+}
+
+// reloadNew 把别的实例写进同一目录的作业收进来（主进程负责调度它们）。
+func (q *jobQueue) reloadNew() {
+	if q.dir == "" {
+		return
+	}
+	entries, err := os.ReadDir(q.dir)
+	if err != nil {
+		return
+	}
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() || !strings.HasSuffix(name, ".json") {
+			continue
+		}
+		b, rerr := os.ReadFile(filepath.Join(q.dir, name))
+		if rerr != nil {
+			continue
+		}
+		var j Job
+		if json.Unmarshal(b, &j) != nil || j.ID == "" {
+			continue
+		}
+		cur := q.jobs[j.ID]
+		if cur != nil {
+			// 本地正在跑的不覆盖；其余以磁盘更新时间为准（别的实例可能推进过状态）。
+			if q.runs[j.ID] == nil && j.UpdatedAt.After(cur.UpdatedAt) {
+				*cur = j
+			}
+			continue
+		}
+		q.jobs[j.ID] = &j
+		if j.RequestID != "" {
+			q.byReq[j.RequestID] = j.ID
+		}
+		if j.AskID != "" {
+			q.byAsk[j.AskID] = j.ID
+		}
+	}
+	q.recomputePositionsLocked()
+}
+
+func (q *jobQueue) dispatch() {
+	if !q.leaseOwned {
+		return
+	}
+	q.mu.Lock()
+	if q.closed {
+		q.mu.Unlock()
+		return
+	}
+	// 过期清理 + 终态文件清理（幂等窗口 = jobKeepTerminal）
+	now := time.Now()
+	for id, j := range q.jobs {
+		if j.State == JobQueued && !j.ExpiresAt.IsZero() && !j.ExpiresAt.After(now) {
+			j.State = JobExpired
+			j.Error = "排队超时，未执行"
+			j.UpdatedAt = now
+			q.persistLocked(j)
+		}
+		if j.terminal() && !j.UpdatedAt.IsZero() && now.Sub(j.UpdatedAt) > jobKeepTerminal {
+			if j.RequestID != "" {
+				delete(q.byReq, j.RequestID)
+			}
+			delete(q.byAsk, j.AskID)
+			delete(q.jobs, id)
+			q.removeFile(j.ID)
+		}
+	}
+	// 候选：queued，按创建时间 FIFO；跳过已被占用的 workspace（串行模式）。
+	var cands []*Job
+	for _, j := range q.jobs {
+		if j.State != JobQueued {
+			continue
+		}
+		if j.Serial && q.active[j.Workspace] != "" {
+			continue
+		}
+		cands = append(cands, j)
+	}
+	sort.Slice(cands, func(i, k int) bool {
+		if cands[i].CreatedAt.Equal(cands[k].CreatedAt) {
+			return cands[i].ID < cands[k].ID
+		}
+		return cands[i].CreatedAt.Before(cands[k].CreatedAt)
+	})
+	var admitted []*Job
+	for _, j := range cands {
+		if q.running >= q.max {
+			break
+		}
+		if j.Serial {
+			if q.active[j.Workspace] != "" {
+				continue
+			}
+			q.active[j.Workspace] = j.ID
+		} else if q.active[j.Workspace] != "" {
+			// 并行作业不占槽，但不该和同空间的串行作业抢跑。
+			continue
+		}
+		j.State = JobRunning
+		j.StartedAt = now
+		j.UpdatedAt = now
+		q.running++
+		admitted = append(admitted, j)
+	}
+	q.recomputePositionsLocked()
+	q.mu.Unlock()
+
+	for _, j := range admitted {
+		/* 外部占用（CLI / 上个进程留下的活会话）：串行作业先让路。
+		   这里查登记表而不是只信自己：锁在 core，别的进程也可能正在跑。 */
+		if j.Serial && q.externalBusy(j.Workspace, j.ID) {
+			q.requeue(j.ID, "等待同工作空间的另一个进程结束")
+			continue
+		}
+		go q.launch(j)
+	}
+	if len(admitted) > 0 {
+		q.signal()
+	}
+}
+
+func (q *jobQueue) requeue(id, why string) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	j := q.jobs[id]
+	if j == nil || j.State != JobRunning {
+		return
+	}
+	if j.Serial && q.active[j.Workspace] == id {
+		delete(q.active, j.Workspace)
+	}
+	j.State = JobQueued
+	j.StartedAt = time.Time{}
+	j.UpdatedAt = time.Now()
+	if j.ExpiresAt.IsZero() || j.ExpiresAt.Before(time.Now()) {
+		j.ExpiresAt = time.Now().Add(jobQueuedTTL)
+	}
+	q.running--
+	if q.running < 0 {
+		q.running = 0
+	}
+	q.recomputePositionsLocked()
+	q.persistLocked(j)
+	q.signal()
+}
+
+// externalBusy 登记表里同 workspace 是否还有别的活进程。
+func (q *jobQueue) externalBusy(ws string, selfJob string) bool {
+	recs, err := session.List()
+	if err != nil {
+		return false
+	}
+	q.mu.Lock()
+	selfPID := 0
+	if j := q.jobs[selfJob]; j != nil {
+		selfPID = j.PID
+	}
+	q.mu.Unlock()
+	target := normalizeWorkspace(ws)
+	for _, r := range recs {
+		if r.PID <= 0 || r.PID == selfPID {
+			continue
+		}
+		if r.State != session.StateRunning && r.State != session.StateWaitingApproval && r.State != session.StateIdle {
+			continue
+		}
+		w := strings.TrimSpace(r.Workspace)
+		if w == "" {
+			w = strings.TrimSpace(r.Cwd)
+		}
+		if w == "" {
+			continue
+		}
+		if normalizeWorkspace(w) == target {
+			return true
+		}
+	}
+	return false
+}
+
+// launch 准备参数并拉起 core；收尾由 pumpAsk → runEnded 负责。
+func (q *jobQueue) launch(j *Job) {
+	/* 排队中被取消的那一瞬间可能已经进了 launch：下手前再确认一次，别把已取消的任务跑起来。 */
+	q.mu.Lock()
+	if q.jobs[j.ID] == nil || j.State != JobRunning {
+		q.mu.Unlock()
+		return
+	}
+	q.mu.Unlock()
+	req := j.askRequest()
+	engine, args, st, err := q.svc.prepareAsk(req)
+	if err != nil {
+		q.fail(j.ID, httpStatusPrefix(st)+err.Error())
+		return
+	}
+	run, err := q.svc.startAsk(req, engine, args, j.Owner.Source)
+	if err != nil {
+		q.fail(j.ID, err.Error())
+		return
+	}
+	q.mu.Lock()
+	j.AskID = run.id
+	j.PID = 0
+	if run.cmd.Process != nil {
+		j.PID = run.cmd.Process.Pid
+	}
+	j.UpdatedAt = time.Now()
+	q.runs[j.ID] = run
+	q.byAsk[run.id] = j.ID
+	q.persistLocked(j)
+	q.mu.Unlock()
+}
+
+func httpStatusPrefix(code int) string {
+	if code == 0 || code == http.StatusOK {
+		return ""
+	}
+	return fmt.Sprintf("(%d) ", code)
+}
+
+func (q *jobQueue) fail(id, reason string) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	j := q.jobs[id]
+	if j == nil {
+		return
+	}
+	wasRunning := j.State == JobRunning
+	j.State = JobFailed
+	j.Error = strings.TrimSpace(reason)
+	j.UpdatedAt = time.Now()
+	if j.Serial && q.active[j.Workspace] == j.ID {
+		delete(q.active, j.Workspace)
+	}
+	if wasRunning && q.running > 0 {
+		q.running--
+	}
+	delete(q.runs, j.ID)
+	q.recomputePositionsLocked()
+	q.persistLocked(j)
+	q.signal()
+}
+
+// runEnded pumpAsk 在 core 退出后调用：按退出码落终态、释放槽位。
+func (q *jobQueue) runEnded(run *askRun) {
+	if q == nil || run == nil {
+		return
+	}
+	q.mu.Lock()
+	id := q.byAsk[run.id]
+	j := q.jobs[id]
+	if j == nil {
+		q.mu.Unlock()
+		return
+	}
+	code := 0
+	run.mu.Lock()
+	code = run.code
+	sid := strings.TrimSpace(run.session)
+	rid := strings.TrimSpace(run.run)
+	run.mu.Unlock()
+	if code == 0 {
+		j.State = JobDone
+		j.Error = ""
+	} else {
+		j.State = JobFailed
+		j.Error = strings.TrimSpace(run.stderr.String())
+		if j.Error == "" {
+			j.Error = fmt.Sprintf("core 退出码 %d", code)
+		}
+	}
+	if sid != "" {
+		j.SessionID = sid
+	}
+	if rid != "" {
+		j.RunID = rid
+	}
+	j.UpdatedAt = time.Now()
+	// 先释放（running-- / 清 active），再算位置；否则自己会被当成「还在跑」。
+	if j.Serial && q.active[j.Workspace] == j.ID {
+		delete(q.active, j.Workspace)
+	}
+	if q.running > 0 {
+		q.running--
+	}
+	/* ⚠️ **不要**立刻从 runs 里摘除：/desk/ask 的 waitStarted 可能还在等这一条
+	   （几十毫秒就收工的轮次尤其明显）。保留 askRetention，与 s.runs 同窗口。 */
+	q.recomputePositionsLocked()
+	q.persistLocked(j)
+	q.mu.Unlock()
+	time.AfterFunc(askRetention, func() {
+		q.mu.Lock()
+		delete(q.runs, j.ID)
+		q.mu.Unlock()
+	})
+	q.signal()
+}
+
+// cancel 取消作业：排队中直接出队；运行中把 stop 写进 core 的 stdin。
+func (q *jobQueue) cancel(id, reason string) bool {
+	q.mu.Lock()
+	j := q.jobs[id]
+	if j == nil {
+		q.mu.Unlock()
+		return false
+	}
+	run := q.runs[id]
+	if run == nil {
+		/* 还没真正拉起 core（queued / 刚被调度器标成 running 的那一瞬）：
+		   直接出队，launch 在下手前会再确认状态，不会偷偷跑起来。 */
+		wasRunning := j.State == JobRunning
+		j.State = JobCancelled
+		j.Error = strings.TrimSpace(reason)
+		j.UpdatedAt = time.Now()
+		if j.Serial && q.active[j.Workspace] == j.ID {
+			delete(q.active, j.Workspace)
+		}
+		if wasRunning && q.running > 0 {
+			q.running--
+		}
+		q.recomputePositionsLocked()
+		q.persistLocked(j)
+		q.mu.Unlock()
+		q.signal()
+		return true
+	}
+	q.mu.Unlock()
+	if run != nil && run.stdin != nil {
+		_, err := run.stdin.Write([]byte("{\"op\":\"stop\"}\n"))
+		return err == nil
+	}
+	return false
+}
+
+// cancelByRequest 按客户端幂等键取消（客户端还没拿到 job id 时用）。
+func (q *jobQueue) cancelByRequest(requestID, reason string) bool {
+	requestID = strings.TrimSpace(requestID)
+	if requestID == "" {
+		return false
+	}
+	q.mu.Lock()
+	id := q.byReq[requestID]
+	q.mu.Unlock()
+	if id == "" {
+		return false
+	}
+	return q.cancel(id, reason)
+}
+
+/* ── HTTP ── */
+
+// handleJobs /desk/jobs：GET 列表 / POST 提交。
+func (s *Service) handleJobs(w http.ResponseWriter, r *http.Request) {
+	if s.jobs == nil {
+		writeErr(w, http.StatusServiceUnavailable, "作业队列未初始化")
+		return
+	}
+	switch r.Method {
+	case http.MethodGet:
+		limit := 200
+		if v := strings.TrimSpace(r.URL.Query().Get("limit")); v != "" {
+			if n, err := strconv.Atoi(v); err == nil && n > 0 && n <= 1000 {
+				limit = n
+			}
+		}
+		jobs := s.jobs.list(r.URL.Query().Get("workspace"), limit)
+		s.jobs.mu.Lock()
+		running, max := s.jobs.running, s.jobs.max
+		s.jobs.mu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]any{
+			"jobs":    jobs,
+			"running": running,
+			"max":     max,
+		})
+	case http.MethodPost:
+		var req askRequest
+		if err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&req); err != nil {
+			writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+			return
+		}
+		engine, _, st, err := s.prepareAsk(req)
+		if err != nil {
+			writeErr(w, st, err.Error())
+			return
+		}
+		job, created, err := s.jobs.submitAsk(req, engine, requestSource(req.Client, r.Header.Get("Origin")))
+		if err != nil {
+			writeErr(w, http.StatusTooManyRequests, err.Error())
+			return
+		}
+		code := http.StatusOK
+		if created {
+			code = http.StatusAccepted
+		}
+		writeJSON(w, code, map[string]any{"job": job, "created": created})
+	default:
+		writeErr(w, http.StatusMethodNotAllowed, "GET / POST only")
+	}
+}
+
+// handleJobsSub /desk/jobs/{id}、/{id}/events、/{id}/cancel、/events（全局流）。
+func (s *Service) handleJobsSub(w http.ResponseWriter, r *http.Request) {
+	if s.jobs == nil {
+		writeErr(w, http.StatusServiceUnavailable, "作业队列未初始化")
+		return
+	}
+	rest := strings.Trim(strings.TrimPrefix(r.URL.Path, "/desk/jobs/"), "/")
+	if rest == "events" {
+		s.handleJobsStream(w, r)
+		return
+	}
+	/* POST /desk/jobs/cancel {request_id}：客户端只知道自己的幂等键、还没拿到 job id 时用
+	   （例如排队中点「停止」）。 */
+	if rest == "cancel" {
+		if r.Method != http.MethodPost {
+			writeErr(w, http.StatusMethodNotAllowed, "POST only")
+			return
+		}
+		var body struct {
+			RequestID string `json:"request_id"`
+		}
+		if err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&body); err != nil {
+			writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+			return
+		}
+		ok := s.jobs.cancelByRequest(body.RequestID, "客户端取消")
+		if !ok {
+			writeErr(w, http.StatusNotFound, "没有这个 request_id 对应的作业："+body.RequestID)
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]any{"cancelled": true})
+		return
+	}
+	parts := strings.Split(rest, "/")
+	id := parts[0]
+	if id == "" {
+		writeErr(w, http.StatusNotFound, "用法：GET /desk/jobs/{id}[?after=]，POST /desk/jobs/{id}/cancel")
+		return
+	}
+	action := ""
+	if len(parts) > 1 {
+		action = parts[1]
+	}
+	switch action {
+	case "":
+		if r.Method != http.MethodGet {
+			writeErr(w, http.StatusMethodNotAllowed, "GET only")
+			return
+		}
+		j := s.jobs.get(id)
+		if j == nil {
+			writeErr(w, http.StatusNotFound, "没有这个作业："+id)
+			return
+		}
+		writeJSON(w, http.StatusOK, j)
+	case "events":
+		s.handleJobEvents(w, r, id)
+	case "cancel":
+		if r.Method != http.MethodPost {
+			writeErr(w, http.StatusMethodNotAllowed, "POST only")
+			return
+		}
+		if s.jobs.get(id) == nil {
+			writeErr(w, http.StatusNotFound, "没有这个作业："+id)
+			return
+		}
+		ok := s.jobs.cancel(id, "客户端取消")
+		writeJSON(w, http.StatusOK, map[string]any{"cancelled": ok, "job": s.jobs.get(id)})
+	default:
+		writeErr(w, http.StatusNotFound, "用法：GET /desk/jobs/{id}[?after=]，POST /desk/jobs/{id}/cancel")
+	}
+}
+
+// handleJobEvents 作业事件：排队中返回空列表 + position，开跑后按 seq 增量回放。
+func (s *Service) handleJobEvents(w http.ResponseWriter, r *http.Request, id string) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	var after uint64
+	if v := strings.TrimSpace(r.URL.Query().Get("after")); v != "" {
+		n, err := strconv.ParseUint(v, 10, 64)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "after 必须是十进制序号："+v)
+			return
+		}
+		after = n
+	}
+	j := s.jobs.get(id)
+	if j == nil {
+		writeErr(w, http.StatusNotFound, "没有这个作业："+id)
+		return
+	}
+	run := s.jobs.runOf(id)
+	if run == nil {
+		writeJSON(w, http.StatusOK, map[string]any{
+			"job":              j,
+			"id":               j.AskID,
+			"events":           []any{},
+			"count":            0,
+			"after":            after,
+			"lastSeq":          0,
+			"done":             j.terminal(),
+			"snapshotRequired": false,
+		})
+		return
+	}
+	events, lastSeq, done, code, stderr := run.snapshot(after)
+	raw := make([]json.RawMessage, 0, len(events))
+	for _, e := range events {
+		raw = append(raw, json.RawMessage(append([]byte(nil), e.data...)))
+	}
+	resp := map[string]any{
+		"job":              j,
+		"id":               run.id,
+		"events":           raw,
+		"count":            len(raw),
+		"after":            after,
+		"lastSeq":          lastSeq,
+		"done":             done,
+		"snapshotRequired": false,
+	}
+	if done {
+		resp["code"] = code
+		resp["stderr"] = stderr
+	}
+	writeJSON(w, http.StatusOK, resp)
+}
+
+// handleJobsStream 全局作业列表（SSE 快照流）：多客户端据此实时刷新队列视图。
+func (s *Service) handleJobsStream(w http.ResponseWriter, r *http.Request) {
+	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)
+	ws := r.URL.Query().Get("workspace")
+	send := func() {
+		jobs := s.jobs.list(ws, 300)
+		s.jobs.mu.Lock()
+		running, max := s.jobs.running, s.jobs.max
+		s.jobs.mu.Unlock()
+		b, _ := json.Marshal(map[string]any{"jobs": jobs, "running": running, "max": max, "at": time.Now().UTC()})
+		fmt.Fprintf(w, "event: jobs\ndata: %s\n\n", b)
+		if flusher != nil {
+			flusher.Flush()
+		}
+	}
+	send()
+	tick := time.NewTicker(2 * time.Second)
+	defer tick.Stop()
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case <-tick.C:
+			send()
+		}
+	}
+}
+
+// ioLimit 已内联为 io.LimitReader（保持与 /desk/ask 同一上限）。