magic-agent 2.3.0 → 2.3.9

package/internal/requirements/consolidate.go

@@ -128,7 +128,15 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	if Root() == "" {
 		return Result{Workspace: ws.ID, Dir: ws.Dir, Error: "无法确定需求存储目录"}, fmt.Errorf("requirements: no storage root")
 	}
-	res := Result{Workspace: ws.ID, Dir: ws.Dir}
+	moduleScope := SlugifyModule(opts.Module)
+	res := Result{Workspace: ws.ID, Dir: ws.Dir, Module: moduleScope}
+
+	// 模块级整理只更新已有模块，不接受一个不存在的名字（否则模型会把新需求
+	// 塞进一个凭空的目录，用户在清单里根本找不到它）。
+	if moduleScope != "" && !contains(listModules(ws.ID), moduleScope) {
+		res.Error = "模块不存在: " + opts.Module
+		return res, fmt.Errorf("requirements: module not found: %s", opts.Module)
+	}
 
 	// 锁：同一工作区同时只允许一轮归纳（客户端防抖 + 手动「立即整理」可能撞上）。
 	release, busy := acquireLock(ws.ID)
@@ -152,8 +160,9 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	/* 首次「整理」：先按空间目录反推一版需求基线，再把旧会话记为已消费。
 	   判断依据是 state.BootstrapAt（不是文档数 / 不是 LastConsolidatedAt）：
 	   自动归纳可能已经产出过几篇文档，但「有没有按目录初始化过」是另一件事。
-	   opts.Auto 的自动路径不初始化 —— 它每轮都可能跑，不能悄悄花几分钟读代码。 */
-	if st.BootstrapAt == 0 && !opts.Auto {
+	   opts.Auto 的自动路径不初始化 —— 它每轮都可能跑，不能悄悄花几分钟读代码。
+	   模块级整理也不初始化：目录基线是空间级的，模块只做增量。 */
+	if st.BootstrapAt == 0 && !opts.Auto && moduleScope == "" {
 		boot, berr := bootstrapWorkspace(ctx, ws, opts)
 		if berr != nil {
 			res.Error = truncRunes(berr.Error(), 240)
@@ -206,8 +215,11 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	if cursor > len(mem) {
 		cursor = len(mem) // 记忆文件被外部截断 → 游标跟着收敛，不越界
 	}
+	/* 模块级整理**不重放**（--requirement-all 是空间级回填），只看游标之后的
+	   新记忆；也不推进游标，否则别的模块的需求会被这一轮悄悄吞掉。 */
+	replay := opts.All && moduleScope == ""
 	entries := mem[cursor:]
-	if opts.All {
+	if replay {
 		entries = mem
 	}
 	if len(entries) == 0 && !opts.Force {
@@ -218,7 +230,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 
 	use := entries
-	if opts.All {
+	if replay {
 		if len(use) > MaxReplayEntries {
 			use = use[len(use)-MaxReplayEntries:]
 		}
@@ -241,7 +253,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		return res, callErr
 	}
 
-	chunks := chunkEntries(use, opts.All)
+	chunks := chunkEntries(use, replay)
 	merger := newDocMerger(ws.ID)
 	byN := make(map[int]Entry, len(mem))
 	for _, e := range mem {
@@ -256,7 +268,15 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		// 每片重新读已有文档：上一片刚写的要点必须出现在这一片的「已有需求点」里，
 		// 否则同一件事会被重复追加。
 		docs := featureDocsOf(ws.ID)
-		prompt := buildPrompt(wsName, docs, chunk, listModules(ws.ID), opts.All)
+		modules := listModules(ws.ID)
+		/* 模块级整理：只让模型看到这个模块的已有文档与模块名 ——
+		   否则它会把别的模块的新需求也一起写回来（那正是用户点的这一下
+		   「只整理一个模块」所不能接受的事）。 */
+		if moduleScope != "" {
+			docs = docsOfModule(docs, moduleScope)
+			modules = []string{moduleScope}
+		}
+		prompt := buildPrompt(wsName, docs, chunk, modules, replay, moduleScope)
 		text, err := call(prompt, outSchema)
 		res.Calls++
 		if err != nil {
@@ -276,28 +296,34 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 
 		// 新模块的同义二审：归纳是逐轮独立的，模型容易把同一件事拆成近义模块
 		//（「任务列表」/「对话列表」）。只有确认已有模块里没有同义项时才允许新建。
+		// 模块级整理不新建模块（作用域就是这个已有模块），因而也不做二审。
 		alias := map[string]string{}
-		existing := listModules(ws.ID)
-		newMods := []string{}
-		seenNew := map[string]bool{}
-		for _, o := range outs {
-			m := SlugifyModule(o.Module)
-			if m == "" || seenNew[m] || contains(existing, m) {
-				continue
+		if moduleScope == "" {
+			existing := listModules(ws.ID)
+			newMods := []string{}
+			seenNew := map[string]bool{}
+			for _, o := range outs {
+				m := SlugifyModule(o.Module)
+				if m == "" || seenNew[m] || contains(existing, m) {
+					continue
+				}
+				seenNew[m] = true
+				newMods = append(newMods, m)
+			}
+			if len(newMods) > 0 && len(existing) > 0 {
+				alias = resolveModuleAlias(call, newMods, existing)
 			}
-			seenNew[m] = true
-			newMods = append(newMods, m)
-		}
-		if len(newMods) > 0 && len(existing) > 0 {
-			alias = resolveModuleAlias(call, newMods, existing)
 		}
 
 		for _, o := range outs {
+			if moduleScope != "" && !outputInModule(o, moduleScope, merger) {
+				continue
+			}
 			w := writeFeatureItem(ws.ID, o, &writeCtx{
 				merger: merger,
 				alias:  alias,
 				kind:   "归纳",
-				all:    opts.All,
+				all:    replay,
 				sourcesOf: func(x featureOut) []string {
 					out := make([]string, 0, len(x.Sources))
 					for _, n := range x.Sources {
@@ -324,7 +350,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 
 	consumed := cursor
-	if !opts.All {
+	if !replay && moduleScope == "" {
 		consumed = cursor + len(use)
 		if consumed > len(mem) {
 			consumed = len(mem)
@@ -339,11 +365,11 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 	res.OK = true
 	res.Consumed = 0
-	if !opts.All {
+	if !replay && moduleScope == "" {
 		res.Consumed = len(use)
 	}
 	res.Replayed = 0
-	if opts.All {
+	if replay {
 		res.Replayed = len(use)
 	}
 	res.Pending = len(mem) - consumed
@@ -435,12 +461,38 @@ func featureDocsOf(id string) []existsDoc {
 	return out
 }
 
+// docsOfModule 只留某个模块下的已有功能点（模块级整理的作用域）。
+func docsOfModule(docs []existsDoc, module string) []existsDoc {
+	out := make([]existsDoc, 0, len(docs))
+	for _, d := range docs {
+		if SlugifyModule(d.Module) == module {
+			out = append(out, d)
+		}
+	}
+	return out
+}
+
+// outputInModule 一条模型增量是否属于本次模块级整理的作用域。
+//
+// 已有功能点按 name 匹配后以它**当前所属模块**为准（与 writeFeatureItem 同一口径：
+// 文档一旦归类就不搬家）；新功能点才看模型给的 module。
+func outputInModule(o featureOut, scope string, merger *docMerger) bool {
+	name := strings.TrimSpace(truncRunes(strings.TrimSpace(o.Name), TitleMaxChars))
+	if name == "" {
+		return false
+	}
+	if hit, has := merger.match(name); has {
+		return SlugifyModule(hit.Module) == scope
+	}
+	return SlugifyModule(o.Module) == scope
+}
+
 // buildPrompt 组归纳 prompt。
 //
 // 规则段是**产品口径**，不是技术参数：哪些话不能写进需求点（缺陷措辞）、
 // 什么样的模块必须复用、结论与问题的界限。这些是业务项目半年里一条条纠正出来的，
 // 换实现时原样保留，别按自己的口味重写。
-func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []string, replay bool) string {
+func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []string, replay bool, scope string) string {
 	mods := make([]string, 0, len(modules))
 	for _, m := range modules {
 		if strings.TrimSpace(m) != "" {
@@ -531,9 +583,19 @@ func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []str
 			"desc 可用记忆重新校核改写（这是唯一允许改写 desc 的场景），" +
 			"需求点/结论里已有的一字不改照抄、缺的补上。"
 	}
+	/* 模块级整理：模型只该动这一个模块。必须写清楚「别的记忆忽略」——
+	   否则它会把整段对话重新归类，用户点一个模块却把别的模块也改了。 */
+	if scope != "" {
+		rules[0] = "0. **本次只整理模块「" + scope + "」**：只输出属于这个模块的功能点" +
+			"（新功能点的 module 必须逐字写「" + scope + "」，已有功能点沿用它的 name）。" +
+			"不属于这个模块的记忆**一律忽略** —— 它们会在「整理整个空间」时处理。"
+	}
 
 	var b strings.Builder
 	b.WriteString("你是资深产品经理，负责把「对话记忆」归纳成**两级**功能点需求文档的**增量**。工作区：" + wsName + "\n\n")
+	if scope != "" {
+		b.WriteString("【模块级整理】本次作用域：模块「" + scope + "」。\n\n")
+	}
 	b.WriteString("== 已有模块（大功能点 · 一级）==\n")
 	if len(mods) == 0 {
 		b.WriteString("（暂无模块，可新建）")

package/internal/requirements/requirements.go

@@ -127,6 +127,13 @@ type Options struct {
 	Engine string
 	// Model 归纳用哪个模型（空 = 引擎默认）。
 	Model string
+	// Module 只整理这个模块（空 = 整个空间）。
+	//
+	// 语义：只把「属于该模块」的增量写回该模块，**不推进空间游标** ——
+	// 其它模块的记忆仍留在 pending，等空间级「整理」或下一次自动归纳处理。
+	// 因此模块级整理是「只增不减、可重复跑」的，不会吞掉别的模块的需求。
+	// ⚠️ 它不会触发首次目录初始化（目录基线天然是空间级的）。
+	Module string
 	// Timeout 单次调用超时（0 = 归纳 240s；首次目录初始化 9m）。
 	Timeout time.Duration
 	// Auto 自动归纳（插件的轮末防抖 / 每日兜底）。
@@ -141,6 +148,8 @@ type Result struct {
 	// Workspace / Dir 归纳的是哪个工作区。
 	Workspace string `json:"workspace,omitempty"`
 	Dir       string `json:"dir"`
+	// Module 这一轮只整理了哪个模块（空 = 整个空间）。
+	Module string `json:"module,omitempty"`
 	// Noop 没有未归纳记忆、也没要求强制跑（等于什么都没做，不是错）。
 	Noop bool `json:"noop,omitempty"`
 	// Bootstrap 这一轮是否完成了首次初始化。

package/internal/requirements/requirements_test.go

@@ -326,6 +326,27 @@ func TestWorkspacesGroupsAndSorts(t *testing.T) {
 	}
 }
 
+// TestResolveWorkspaceByID 按 ws id 也能解析（客户端手里可能只有 id、没有目录）。
+//
+// 老实现的 safeID 把前缀 `ws-` 里的 w/s 也按十六进制校验，任何 id 都过不了：
+// `--consolidate-requirements ws-xxxx` 直接报「工作区不存在」。
+func TestResolveWorkspaceByID(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-id")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	e := registerWorkspace(proj)
+	got, ok := resolveWorkspace(e.ID)
+	if !ok || got.ID != e.ID || got.Dir != proj {
+		t.Fatalf("按 id 应解析出 %s/%s，实际 %+v ok=%v", e.ID, proj, got, ok)
+	}
+	// 路径穿越仍要被挡住。
+	if safeID("ws-../../etc") || safeID("ws-") || safeID("x-ws-1") {
+		t.Error("非法 id 必须被拒绝")
+	}
+}
+
 // TestConsolidatePipeline 走完整链路：摄入 → prompt → 模型输出 → 合并 → 游标前进。
 // 模型用假调用器（真实归纳的网络/CLI 由真机验收覆盖），验的是代码这一侧。
 func TestConsolidatePipeline(t *testing.T) {
@@ -411,6 +432,114 @@ func TestConsolidatePipeline(t *testing.T) {
 	}
 }
 
+// TestConsolidateModuleScope 模块级整理只动这个模块，且不推进空间游标。
+//
+// 用户 2026-10-23 报障：「点需求的一个模块的整理却触发了所有的整理」。
+// 这里钉住三件事：
+//   - 模型只看到这个模块的已有文档（看不到别的模块，才不会把别的模块也改了）；
+//   - 模型即使输出别的模块的增量，也不落盘；
+//   - 空间游标不动 —— 别的模块的需求留给空间级整理，不能被这一下吞掉。
+func TestConsolidateModuleScope(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-module")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeSessionLog(t, session.Dir(), "s-mod", proj, "手机号登录要加验证码", "购物车要支持结算")
+
+	id := DirID(proj)
+	merger := newDocMerger(id)
+	wctx := &writeCtx{merger: merger, kind: "归纳"}
+	for _, o := range []featureOut{
+		{Module: "登录", Name: "手机号登录", Points: []string{"手机号可登录"}},
+		{Module: "支付", Name: "购物车结算", Points: []string{"购物车可结算"}},
+	} {
+		if w := writeFeatureItem(id, o, wctx); !w.ok {
+			t.Fatalf("预置文档失败: %+v", w)
+		}
+	}
+	// 已初始化 + 游标 0：模拟「有一批待整理记忆，已过了首次目录初始化」。
+	if err := writeState(id, state{BootstrapAt: time.Now().UnixMilli(), Sessions: map[string]memCursor{}}); err != nil {
+		t.Fatal(err)
+	}
+
+	old := newCaller
+	defer func() { newCaller = old }()
+	var prompts []string
+	newCaller = func(ctx context.Context, engineName, model string, timeout time.Duration) (llmCall, error) {
+		return func(prompt string, schema *agent.JSONSchema) (string, error) {
+			prompts = append(prompts, prompt)
+			return `{"features":[
+				{"module":"登录","name":"手机号登录","points":["支持验证码登录"],"sources":[1]},
+				{"module":"支付","name":"购物车结算","points":["支持优惠券"],"sources":[2]}
+			]}`, nil
+		}, nil
+	}
+
+	res, err := Consolidate(context.Background(), proj, Options{Module: "登录"})
+	if err != nil {
+		t.Fatalf("模块级整理失败: %v", err)
+	}
+	if !res.OK || res.Module != "登录" {
+		t.Fatalf("结果应标明模块级整理: %+v", res)
+	}
+	if res.Consumed != 0 {
+		t.Errorf("模块级整理不该推进游标，实际 consumed=%d", res.Consumed)
+	}
+	if st := readState(id); st.Consumed != 0 {
+		t.Errorf("state 游标不该被模块级整理推进，实际 %d", st.Consumed)
+	}
+	if res.Updated != 1 || res.Created != 0 {
+		t.Errorf("只该更新登录模块的 1 篇，实际 %+v", res)
+	}
+	if len(prompts) != 1 {
+		t.Fatalf("应只调 1 次模型，实际 %d", len(prompts))
+	}
+	if !strings.Contains(prompts[0], "本次只整理模块「登录」") || !strings.Contains(prompts[0], "【模块级整理】") {
+		t.Errorf("prompt 应写明模块作用域:\n%s", prompts[0])
+	}
+	if strings.Contains(prompts[0], "购物车结算") || strings.Contains(prompts[0], "[模块 支付]") {
+		t.Errorf("prompt 不该带出别的模块的文档:\n%s", prompts[0])
+	}
+
+	moduleOf := func(name string) (string, Doc) {
+		for _, f := range listFeatureFiles(id) {
+			if f.Name == name {
+				return f.Module, ParseDoc(readFile(t, f.File))
+			}
+		}
+		t.Fatalf("找不到文档 %s", name)
+		return "", Doc{}
+	}
+	if mod, d := moduleOf("手机号登录"); mod != "登录" || !contains(d.Points, "支持验证码登录") {
+		t.Errorf("登录模块应收到本模块增量，实际［%s］%+v", mod, d.Points)
+	}
+	if _, d := moduleOf("购物车结算"); len(d.Points) != 1 || contains(d.Points, "支持优惠券") {
+		t.Errorf("别的模块不该被模块级整理改动，实际 %+v", d.Points)
+	}
+
+	// 空间级整理仍应消费这批记忆：两个模块都更新，游标前进。
+	res2, err := Consolidate(context.Background(), proj, Options{})
+	if err != nil {
+		t.Fatalf("空间级整理失败: %v", err)
+	}
+	if res2.Consumed != 2 || res2.Updated != 2 {
+		t.Errorf("空间级整理应消费 2 条并更新 2 篇，实际 %+v", res2)
+	}
+	if st := readState(id); st.Consumed != 2 {
+		t.Errorf("空间级整理后游标应为 2，实际 %d", st.Consumed)
+	}
+	if _, d := moduleOf("购物车结算"); !contains(d.Points, "支持优惠券") {
+		t.Errorf("空间级整理应补上支付模块的增量，实际 %+v", d.Points)
+	}
+
+	// 不存在的模块要明确报错，不能凭空建目录。
+	if _, err := Consolidate(context.Background(), proj, Options{Module: "不存在"}); err == nil ||
+		!strings.Contains(err.Error(), "module not found") {
+		t.Errorf("不存在的模块应报错，实际 %v", err)
+	}
+}
+
 // TestConsolidateBootstrapsOnceThenIncremental 首次「整理」按目录反推，之后只处理新会话。
 //
 // 这是 2026-10-22 用户口径的代码化：

package/internal/requirements/store.go

@@ -77,11 +77,19 @@ func registryFile() string { return filepath.Join(Root(), "workspaces.json") }
 
 // safeID 工作区 id 会拼进路径 → 只放行本包生成过的形状（挡目录穿越）。
 func safeID(id string) bool {
-	if !strings.HasPrefix(id, "ws-") || len(id) > 40 {
+	const prefix = "ws-"
+	if !strings.HasPrefix(id, prefix) || len(id) > 40 {
 		return false
 	}
-	for _, r := range id {
-		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || r == '-' {
+	// 前缀 `ws-` 本身含 w/s，不能拿去跑十六进制校验（老实现的循环把整个 id
+	// 都按 [0-9a-f-] 过滤，于是任何 ws id 都过不了 —— 按 id 整理 workspace
+	// 会报「工作区不存在」）。只校验前缀之后的部分。
+	rest := strings.TrimPrefix(id, prefix)
+	if rest == "" {
+		return false
+	}
+	for _, r := range rest {
+		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') {
 			continue
 		}
 		return false

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 != "" {

package/internal/session/workspace_lock.go

@@ -0,0 +1,165 @@
+package session
+
+import (
+	"crypto/sha1"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* ── 工作空间串行锁（2026-10-23，多客户端串行的一部分）──
+
+为什么要锁在 core 而不是只靠 magic-client 的调度器：
+  · 同一台桌面上，除了 magic-client 起的轮次，还有人直接跑 `magic-agent -p`；
+  · 多台手机连的是同一个 magic-client，但**进程间**（多个 magic-client 实例）也可能并存。
+调度器只能管自己进程里的队列；一个落在文件系统上的锁才能让「谁先跑」对所有进程一致。
+
+为什么是选入式（MAGIC_AGENT_WORKSPACE_LOCK=1）：
+  默认开启会改变 CLI 的既有语义（两条命令并发跑本来是允许的），也会让团队模式的
+  子任务与主任务互相等待。这里只在 magic-client spawn core 时注入该环境变量，
+  团队子任务（ParentRunID 非空）自动跳过。
+
+锁的形态：<sessions dir>/locks/<sha1(workspace)>.lock，内容 `<pid>\n<unix nano>`。
+  · 用 O_CREATE|O_EXCL 原子创建；
+  · 持锁进程已不在 / 文件超过 staleAfter → 视为陈旧并回收；
+  · 进程退出没来得及删也不会永久堵住（下一步的持有者会按 pid 判死回收）。
+*/
+
+// EnvWorkspaceLock 打开「工作空间串行锁」的环境变量（值为 "1" 时生效）。
+const EnvWorkspaceLock = "MAGIC_AGENT_WORKSPACE_LOCK"
+
+// EnvWorkspaceLockWait 等锁上限（Go duration；默认 10m）。
+const EnvWorkspaceLockWait = "MAGIC_AGENT_WORKSPACE_LOCK_WAIT"
+
+const (
+	workspaceLockPoll  = 500 * time.Millisecond
+	workspaceLockStale = 6 * time.Hour
+)
+
+// WorkspaceLock 一把已持有的工作空间锁；Release 幂等。
+type WorkspaceLock struct {
+	path string
+	held bool
+}
+
+func workspaceLockEnabled() bool {
+	return strings.TrimSpace(os.Getenv(EnvWorkspaceLock)) == "1"
+}
+
+func workspaceLockWait() time.Duration {
+	if v := strings.TrimSpace(os.Getenv(EnvWorkspaceLockWait)); v != "" {
+		if d, err := time.ParseDuration(v); err == nil && d > 0 {
+			return d
+		}
+	}
+	return 10 * time.Minute
+}
+
+// lockKey 归一工作空间：空 = 进程 cwd；返回绝对路径 + 哈希文件名。
+func workspaceLockKey(workspace string) (key, file string) {
+	ws := strings.TrimSpace(workspace)
+	if ws == "" {
+		ws, _ = os.Getwd()
+	}
+	if abs, err := filepath.Abs(ws); err == nil {
+		ws = abs
+	}
+	ws = filepath.Clean(ws)
+	sum := sha1.Sum([]byte(ws))
+	return ws, hex.EncodeToString(sum[:])
+}
+
+/*
+AcquireWorkspaceLock 取工作空间锁（阻塞，直到拿到或超时）。
+
+	o.NoPersist 没关系：锁在 sessions 目录，不依赖会话记录落盘。
+	返回 nil 表示未启用（调用方无需处理）。
+*/
+func acquireWorkspaceLock(workspace string) (*WorkspaceLock, error) {
+	if !workspaceLockEnabled() {
+		return nil, nil
+	}
+	dir := Dir()
+	if dir == "" {
+		return nil, fmt.Errorf("cannot resolve sessions dir")
+	}
+	lockDir := filepath.Join(dir, "locks")
+	if err := os.MkdirAll(lockDir, 0o700); err != nil {
+		return nil, err
+	}
+	ws, name := workspaceLockKey(workspace)
+	path := filepath.Join(lockDir, name+".lock")
+	deadline := time.Now().Add(workspaceLockWait())
+	announced := false
+	for {
+		f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+		if err == nil {
+			_, _ = fmt.Fprintf(f, "%d\n%d\n", os.Getpid(), time.Now().UnixNano())
+			_ = f.Close()
+			return &WorkspaceLock{path: path, held: true}, nil
+		}
+		if !os.IsExist(err) {
+			return nil, err
+		}
+		if reapStaleWorkspaceLock(path) {
+			continue
+		}
+		if time.Now().After(deadline) {
+			return nil, fmt.Errorf("等待工作空间 %s 上的上一个任务超时（%s），可用 %s 调整", ws, workspaceLockWait(), EnvWorkspaceLockWait)
+		}
+		if !announced {
+			announced = true
+			fmt.Fprintf(os.Stderr, "magic-agent: 同一工作空间已有任务在跑，等待其结束（%s）…\n", ws)
+		}
+		time.Sleep(workspaceLockPoll)
+	}
+}
+
+// reapStaleWorkspaceLock 回收陈旧锁（pid 已不在 / 文件太老）；返回是否已删。
+func reapStaleWorkspaceLock(path string) bool {
+	st, err := os.Stat(path)
+	if err != nil {
+		return !os.IsNotExist(err) // 文件刚消失：让调用方重试
+	}
+	stale := time.Since(st.ModTime()) > workspaceLockStale
+	if !stale {
+		if b, err := os.ReadFile(path); err == nil {
+			lines := strings.Split(strings.TrimSpace(string(b)), "\n")
+			if len(lines) > 0 {
+				if pid, err := strconv.Atoi(strings.TrimSpace(lines[0])); err == nil {
+					if pid <= 0 || !agent.PIDAlive(pid) {
+						stale = true
+					}
+				}
+			}
+		}
+	}
+	if !stale {
+		return false
+	}
+	_ = os.Remove(path)
+	return true
+}
+
+// Release 释放锁；只删自己持有的那把（内容里的 pid 对得上）。
+func (l *WorkspaceLock) Release() {
+	if l == nil || !l.held {
+		return
+	}
+	l.held = false
+	b, err := os.ReadFile(l.path)
+	if err != nil {
+		return
+	}
+	first := strings.TrimSpace(strings.SplitN(string(b), "\n", 2)[0])
+	if first != strconv.Itoa(os.Getpid()) {
+		return
+	}
+	_ = os.Remove(l.path)
+}