magic-agent 1.0.49 → 1.0.108

package/internal/requirements/store.go

@@ -0,0 +1,289 @@
+package requirements
+
+import (
+	"bufio"
+	"crypto/sha1"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// EnvDir 覆盖需求存储根目录的环境变量（测试 / 多套数据用）。
+const EnvDir = "MAGIC_AGENT_REQUIREMENTS"
+
+// Root 需求数据的根目录。
+//
+// 与业务项目（掌天瓶的 ~/.magic-test/requirements）**互不相干**：两者是两套数据，
+// 不做自动迁移 —— 静默搬用户的文档比「新功能从头开始攒」危险得多。
+func Root() string {
+	if p := strings.TrimSpace(os.Getenv(EnvDir)); p != "" {
+		return p
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-agent", "requirements")
+}
+
+// DirID 目录 → 工作区 id（'ws-' + sha1(绝对路径) 前 10 位）。
+// 同一目录重复选择天然幂等（与业务项目同一规则，便于两边对照排查）。
+func DirID(dir string) string {
+	d := normalizeDir(dir)
+	if d == "" {
+		return ""
+	}
+	sum := sha1.Sum([]byte(d))
+	return "ws-" + hex.EncodeToString(sum[:])[:10]
+}
+
+// normalizeDir 归一化目录：展开 ~、转绝对、清掉尾部分隔符。
+func normalizeDir(dir string) string {
+	d := strings.TrimSpace(dir)
+	if d == "" {
+		return ""
+	}
+	if d == "~" || strings.HasPrefix(d, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			d = filepath.Join(home, strings.TrimPrefix(strings.TrimPrefix(d, "~"), "/"))
+		}
+	}
+	if abs, err := filepath.Abs(d); err == nil {
+		d = abs
+	}
+	d = filepath.Clean(d)
+	if d == string(filepath.Separator) {
+		return d
+	}
+	return strings.TrimRight(d, string(filepath.Separator))
+}
+
+// wsDir 一个工作区的存储目录。
+func wsDir(id string) string { return filepath.Join(Root(), id) }
+
+// featuresDir 功能点文档目录（<ws>/features，其下按模块再分一级）。
+func featuresDir(id string) string { return filepath.Join(wsDir(id), "features") }
+
+// stateFile / memoryFile 归纳游标与记忆流。
+func stateFile(id string) string  { return filepath.Join(wsDir(id), "state.json") }
+func memoryFile(id string) string { return filepath.Join(wsDir(id), "memory.jsonl") }
+
+// registryFile 工作区注册表（目录 ↔ id ↔ 名字）。
+func registryFile() string { return filepath.Join(Root(), "workspaces.json") }
+
+// safeID 工作区 id 会拼进路径 → 只放行本包生成过的形状（挡目录穿越）。
+func safeID(id string) bool {
+	if !strings.HasPrefix(id, "ws-") || len(id) > 40 {
+		return false
+	}
+	for _, r := range id {
+		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || r == '-' {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+// Entry 一条记忆（= 某会话里的一句用户原话）。
+//
+// N 是**全局单调编号**：模型引用来源时用它（prompt 里的 `#12`），代码据此回查原文
+// 写「来源对话」段 —— 不让模型摘抄原话（实测过它只会摘当轮那一条）。
+type Entry struct {
+	N       int    `json:"n"`
+	Ts      int64  `json:"ts"` // unix 毫秒
+	Session string `json:"session,omitempty"`
+	Seq     uint64 `json:"seq,omitempty"`
+	Title   string `json:"title,omitempty"`
+	Text    string `json:"text"`
+}
+
+// state 一个工作区的归纳游标。
+type state struct {
+	// Consumed 已归纳到记忆流第几条（按条数前进：记忆流只追加，编号不变）。
+	Consumed int `json:"consumed"`
+	// Sessions 每条会话的摄入游标（防重复入记忆流），见 memory.go 的 memCursor。
+	Sessions map[string]memCursor `json:"sessions,omitempty"`
+	// LastConsolidatedAt 最后一次归纳完成时刻（unix 毫秒）。
+	LastConsolidatedAt int64 `json:"last_consolidated_at,omitempty"`
+	// BootstrapAt 首次「按空间目录反推需求基线」完成的时刻（unix 毫秒，0 = 从未初始化）。
+	// 它与 LastConsolidatedAt 是**两个独立事实**：自动归纳可以先产出文档，但只有
+	// 目录基线跑过才算初始化完成（见 bootstrap.go 的说明）。
+	BootstrapAt int64 `json:"bootstrap_at,omitempty"`
+	// LastError 上一次失败原因（成功后清空）。
+	LastError string `json:"last_error,omitempty"`
+}
+
+func readState(id string) state {
+	st := state{}
+	if b, err := os.ReadFile(stateFile(id)); err == nil {
+		_ = json.Unmarshal(b, &st)
+	}
+	if st.Sessions == nil {
+		st.Sessions = map[string]memCursor{}
+	}
+	return st
+}
+
+func writeState(id string, st state) error {
+	if st.Sessions == nil {
+		st.Sessions = map[string]memCursor{}
+	}
+	return writeJSONAtomic(stateFile(id), st)
+}
+
+// readMemory 读整条记忆流（按行，坏行跳过 —— 记忆是追加写，断电最多坏最后一行）。
+func readMemory(id string) []Entry {
+	f, err := os.Open(memoryFile(id))
+	if err != nil {
+		return nil
+	}
+	defer f.Close()
+	out := []Entry{}
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 1<<20)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" {
+			continue
+		}
+		var e Entry
+		if json.Unmarshal([]byte(line), &e) != nil || strings.TrimSpace(e.Text) == "" {
+			continue
+		}
+		if e.N == 0 {
+			e.N = len(out) + 1
+		}
+		out = append(out, e)
+	}
+	return out
+}
+
+// appendMemory 追加若干条记忆（一次打开、一次写；编号由调用方按现有条数续上）。
+func appendMemory(id string, entries []Entry) error {
+	if len(entries) == 0 {
+		return nil
+	}
+	if err := os.MkdirAll(wsDir(id), 0o700); err != nil {
+		return err
+	}
+	f, err := os.OpenFile(memoryFile(id), os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	w := bufio.NewWriter(f)
+	for _, e := range entries {
+		b, err := json.Marshal(e)
+		if err != nil {
+			continue
+		}
+		if _, err := w.Write(append(b, '\n')); err != nil {
+			return err
+		}
+	}
+	return w.Flush()
+}
+
+// workspaceEntry 注册表里的一行。
+type workspaceEntry struct {
+	ID   string `json:"id"`
+	Dir  string `json:"dir"`
+	Name string `json:"name"`
+	// CreatedAt / TouchedAt unix 毫秒。
+	CreatedAt int64 `json:"created_at"`
+	TouchedAt int64 `json:"touched_at"`
+}
+
+func readRegistry() []workspaceEntry {
+	var out []workspaceEntry
+	if b, err := os.ReadFile(registryFile()); err == nil {
+		_ = json.Unmarshal(b, &out)
+	}
+	return out
+}
+
+func writeRegistry(list []workspaceEntry) error {
+	sort.Slice(list, func(i, j int) bool { return list[i].TouchedAt > list[j].TouchedAt })
+	return writeJSONAtomic(registryFile(), list)
+}
+
+// registerWorkspace 登记（或刷新）一个目录作为工作区。
+//
+// 为什么要注册表：一个目录可能**只有归档过的文档、没有会话**（会话被删了 / 换机器），
+// 列表仍应显示它；反过来「有会话但从没归纳过」的目录也要能在列表里看见 —— 后者靠
+// 会话侧的目录反推，见 Workspaces()。
+func registerWorkspace(dir string) workspaceEntry {
+	d := normalizeDir(dir)
+	if d == "" {
+		return workspaceEntry{}
+	}
+	id := DirID(d)
+	now := time.Now().UnixMilli()
+	list := readRegistry()
+	for i := range list {
+		if list[i].ID == id {
+			list[i].Dir = d
+			list[i].Name = filepath.Base(d)
+			list[i].TouchedAt = now
+			_ = writeRegistry(list)
+			return list[i]
+		}
+	}
+	e := workspaceEntry{ID: id, Dir: d, Name: filepath.Base(d), CreatedAt: now, TouchedAt: now}
+	list = append(list, e)
+	_ = writeRegistry(list)
+	return e
+}
+
+// writeJSONAtomic 原子写 JSON（tmp + rename）：并发读的时候不会读到半个文件。
+func writeJSONAtomic(file string, v any) error {
+	if err := os.MkdirAll(filepath.Dir(file), 0o700); err != nil {
+		return err
+	}
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := file + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, file)
+}
+
+// resolveWorkspace 把「ws id 或目录路径」解析成一个工作区；解析不出来返回 ok=false。
+func resolveWorkspace(idOrDir string) (workspaceEntry, bool) {
+	s := strings.TrimSpace(idOrDir)
+	if s == "" {
+		return workspaceEntry{}, false
+	}
+	if safeID(s) {
+		for _, e := range readRegistry() {
+			if e.ID == s {
+				return e, true
+			}
+		}
+		// 注册表里没有但目录存在过（文档还在）：从 state 文件名反推不出目录，
+		// 只能确认它「有存储」——目录留空，清单仍可读（客户端的「目录」按钮会缺失）。
+		if _, err := os.Stat(wsDir(s)); err == nil {
+			return workspaceEntry{ID: s, Name: s}, true
+		}
+		return workspaceEntry{}, false
+	}
+	d := normalizeDir(s)
+	id := DirID(d)
+	for _, e := range readRegistry() {
+		if e.ID == id {
+			return e, true
+		}
+	}
+	if st, err := os.Stat(d); err == nil && st.IsDir() {
+		return workspaceEntry{ID: id, Dir: d, Name: filepath.Base(d)}, true
+	}
+	return workspaceEntry{}, false
+}

package/internal/session/delete.go

@@ -31,10 +31,11 @@ import (
 
 // DeleteResult 删除结果。计数只用于向调用方交代「删掉了什么」，不作判据。
 type DeleteResult struct {
-	ID             string `json:"id"`
-	RecordsRemoved int    `json:"records_removed"`
-	LogsRemoved    int    `json:"logs_removed"`
-	TitlesRemoved  int    `json:"titles_removed"`
+	ID              string `json:"id"`
+	RecordsRemoved  int    `json:"records_removed"`
+	LogsRemoved     int    `json:"logs_removed"`
+	TitlesRemoved   int    `json:"titles_removed"`
+	StatusesRemoved int    `json:"statuses_removed"`
 }
 
 // Delete 删掉一条会话：登记记录 + 事件日志 + 标题覆盖。
@@ -91,6 +92,9 @@ func Delete(id string) (DeleteResult, error) {
 		}
 	}
 	out.TitlesRemoved = dropTitles(names)
+	// 状态表是会话级的覆盖表（见 status.go）：会话没了它还留着，
+	// 同 id 再建会话时会继承一条过期状态（「新建就显示已完成」）。
+	out.StatusesRemoved = dropStatuses(names)
 	return out, nil
 }
 

package/internal/session/session.go

@@ -119,9 +119,15 @@ func normalizeClient(s string) string {
 //	· interrupted 用户**中途打断当前轮**（`--control interrupt`），会话本身仍可继续
 //	· waiting_approval 引擎停下来等用户（提问 / 工具待授权）—— 会话还活着，但没在跑，
 //	  界面上该显示「等审批」而不是「生成中」
+//	· idle         **本轮**已结束，但常驻进程还活着等 `--append` —— 会话还活着，没在跑。
+//	  没有它的时候，keep-alive 会话在轮次之间只能一直写 running：PC 侧按事件流已经显示
+//	  「已完成」，别的端读登记表却以为还在跑（跟进连接空等到 30 分钟、移动端串行门永远
+//	  排不上队）。用户 2026-10-21 报障「pc是会话已结束 但是移动端状态未结束 不统一导致
+//	  还在排队」修的就是这件事。
 const (
 	StateRunning         = "running"          // 正在跑
 	StateWaitingApproval = "waiting_approval" // 卡在等授权 / 等用户回答
+	StateIdle            = "idle"             // 本轮已结束、进程仍在等追加（非终态）
 	StateDone            = "done"             // 正常结束
 	StateFailed          = "failed"           // 报错结束
 	StateCancelled       = "cancelled"        // 被 --stop 取消
@@ -129,6 +135,15 @@ const (
 	StateGone            = "gone"             // 记录里是 running，但进程已不在（自然退出/被别处杀掉）
 )
 
+// isLiveState 这个状态是否代表「会话/进程还活着」（running / waiting_approval / idle）。
+//
+// 全包只有这一处判定：Mark 的可切范围、supersedeSiblings 该不该接管旧进程、Stop 该不该
+// 真去终止、normalizeDead 该不该归一成 gone，四件事问的是同一个问题 ——
+// 各写一份的话，新增一个活着的状态就会漏掉其中一处（idle 就是靠这个收进来的）。
+func isLiveState(s string) bool {
+	return s == StateRunning || s == StateWaitingApproval || s == StateIdle
+}
+
 // normalizeState 把磁盘上的**旧状态值**归一成当前词表。
 //
 // 为什么必须有：`stopped` 在 2026-09-29 之前由 `--stop` 写入，一次性全部改写磁盘上的
@@ -166,12 +181,43 @@ type Record struct {
 	//
 	// 与 Source 的分工：Source 是设备形态（手机/电脑），Client 是发起方应用。
 	// 两者都缺一不可 —— 同一台机器上既有客户端发起的、也有直接跑 CLI 的会话。
-	Client     string    `json:"client,omitempty"`
-	Workspace  string    `json:"workspace,omitempty"`
-	PromptHead string    `json:"prompt_head,omitempty"`
-	State      string    `json:"state"`
-	StartedAt  time.Time `json:"started_at"`
-	UpdatedAt  time.Time `json:"updated_at"`
+	Client    string `json:"client,omitempty"`
+	Workspace string `json:"workspace,omitempty"`
+	// Cwd 这条会话**实际跑在哪个目录**（core 在 Begin 时记下自己的 cwd）。
+	//
+	// 与 Workspace 的分工：Workspace 是调用方**显式指定**的（`-w/--workspace`，用户/客户端
+	// 选的那个空间）；Cwd 是没指定时它自然落到的目录（调用方的 cwd = 默认工作空间）。
+	// 为什么要两个都留（2026-10-22）：需求聚合按目录归属，而**绝大多数调用不带 -w** ——
+	// 只看 Workspace 的话，不指定空间的会话就归不到任何目录，用户会看到「聊了半天
+	// 一条需求都没有」。空 = 旧记录（那时不记 cwd），归属回落到 Workspace。
+	Cwd        string `json:"cwd,omitempty"`
+	PromptHead string `json:"prompt_head,omitempty"`
+	State      string `json:"state"`
+	// Mode 这条会话的运行模式：空 = 单引擎（默认）；"team" = 团队模式。
+	//
+	// 为什么记在这里而不是另开一张表：列表页要能标出「这条是团队会话」，
+	// 用户点进去看到的也是同一段对话。
+	//
+	// 团队拆出的子任务**是独立会话**（用户 2026-10-22：「拆分的子任务跟普通的会话
+	// 一样」）：它们各自有自己的登记记录与日志，靠 ParentRunID / ParentSessionID
+	// 挂在主会话下显示，点进去就是那条子任务的完整过程。上下文仍不共享（见 internal/team）。
+	Mode string `json:"mode,omitempty"`
+	// ParentRunID 父会话（团队主会话）的 run_id；空 = 顶层会话。
+	//
+	// 为什么两个父指针都记：主会话在收尾前可能还没有 session_id（引擎没给），
+	// 这时只能按 run_id 认亲；一旦主会话拿到 session_id，列表就能按 session_id
+	// 归并 —— 两个都留着，读侧哪个非空用哪个（优先 ParentSessionID）。
+	ParentRunID string `json:"parent_run_id,omitempty"`
+	// ParentSessionID 父会话的 session_id；空 = 父会话当时还没有 session_id。
+	ParentSessionID string `json:"parent_session_id,omitempty"`
+	// Agents 团队模式下各类子任务实际派给了谁（按类别归并，同类只留一条）。
+	// 空 = 不是团队会话，或团队只出了计划没执行（--team-plan-only）。
+	//
+	// 只记**路由结果**，不记子任务状态（那是运行目录里 OUT-*.md 的事）：
+	// 登记表是列表页的数据源，塞进每个子任务的状态会让列表接口变成大对象。
+	Agents    []AgentRef `json:"agents,omitempty"`
+	StartedAt time.Time  `json:"started_at"`
+	UpdatedAt time.Time  `json:"updated_at"`
 
 	// Append 追加入口的 unix socket 路径（常驻会话 / --keep-alive 才有）。
 	// 空 = 该会话不可追加（--append 会明确告知原因，不静默）。
@@ -190,6 +236,59 @@ func Dir() string {
 	return filepath.Join(home, ".magic-agent", "sessions")
 }
 
+// AgentRef 团队会话里「某一类子任务交给了谁」。
+type AgentRef struct {
+	// Kind 子任务类别：text | code | image | video | game（见 internal/team.Kinds）。
+	Kind string `json:"kind"`
+	// Engine / Model 实际使用的引擎与模型（空模型 = 引擎默认）。
+	Engine string `json:"engine"`
+	Model  string `json:"model,omitempty"`
+	// Count 这一类别派了几个子任务（合并同类，避免列表里一长串重复行）。
+	Count int `json:"count,omitempty"`
+	// Sessions 这一类别下各子任务**自己的**引擎会话 id（可能为空：引擎没给）。
+	//
+	// 子任务是独立会话（各自有登记记录），这里只是**路由结果的索引**：
+	// 列表页按登记的 ParentRunID / ParentSessionID 把它们挂在主会话下，
+	// 这一串用来快速跳转到某类子任务的会话。留着的用途是排障 / 回查。
+	Sessions []string `json:"sessions,omitempty"`
+}
+
+// ModeTeam 团队模式（Record.Mode 的取值之一）。
+const ModeTeam = "team"
+
+// Mode 返回这条会话的运行模式（空 = 单引擎）。
+func (h *Handle) Mode() string {
+	if h == nil {
+		return ""
+	}
+	return h.rec.Mode
+}
+
+// SetMode 标记运行模式（目前只有 ModeTeam）；值没变时直接返回。
+//
+// 为什么由 CLI 在**开跑前**写：团队会话的计划阶段最早也要几十秒，这期间列表里
+// 已经能看到这条会话了 —— 等收尾才写 Mode，用户点开的就是一条「普通会话」。
+func (h *Handle) SetMode(mode string) {
+	if h == nil || mode == "" || h.rec.Mode == mode {
+		return
+	}
+	h.rec.Mode = mode
+	h.write()
+}
+
+// SetAgents 记录团队会话的路由结果（按类别归并，调用方负责去重）。
+func (h *Handle) SetAgents(refs []AgentRef) {
+	if h == nil {
+		return
+	}
+	if len(refs) == 0 {
+		h.rec.Agents = nil
+	} else {
+		h.rec.Agents = refs
+	}
+	h.write()
+}
+
 // BeginOptions 开始一条会话记录所需的输入。
 type BeginOptions struct {
 	Engine     string
@@ -210,6 +309,10 @@ type BeginOptions struct {
 	// ⚠️ 取反命名（NoPersist 而非 Persist）：默认零值仍是「落盘」，
 	// 既有调用方与测试不必逐个改语义 —— 只有 CLI 显式关它。
 	NoPersist bool
+	// ParentRunID / ParentSessionID 父会话指针（团队拆出的子任务才填）。
+	// 空 = 顶层会话。见 Record 同名字段的说明。
+	ParentRunID     string
+	ParentSessionID string
 }
 
 // Handle 一条运行中会话的句柄（负责回写 pid 与收尾状态）。
@@ -248,25 +351,25 @@ func (h *Handle) SetSessionID(id string) {
 	h.write()
 }
 
-// Mark 就地改状态（只在 running 与 waiting_approval 之间来回时生效）。
+// Mark 就地改状态（只在 isLiveState 的那几个值之间来回时生效）。
 //
 // 为什么需要一个**中途**写状态的入口：引擎会停下来等用户（提问 / 工具待授权），此时这条
 // 会话还活着，但**没在跑** —— 界面上该显示「等审批」而不是「生成中」。这是 2026-09-29
 // 统一会话状态词表时新增的写入点（值取自 anywhere 的 waiting_approval）。
 //
-// ⚠️ 只允许在这两个值之间切：一旦写进终态（done / failed / cancelled / interrupted），
+// 2026-10-21 起多一个取值 idle：keep-alive 会话**本轮结束**（turn_end）时写它，下一轮
+// 第一个事件到达再回到 running。它让登记表在轮次之间说的是实话 —— 别的端据此收尾跟进、
+// 放行排队，与 PC 的「已完成」同口径。
 //
-//	这里不许改回去。终态是「这条会话结束了」的结论，让一个迟到的流事件把它翻回
-//	running，等于让历史撒谎。
+// ⚠️ 只允许在活着的那几个值之间切：一旦写进终态（done / failed / cancelled / interrupted），
+// 这里不许改回去。终态是「这条会话结束了」的结论，让一个迟到的流事件把它翻回
+// running，等于让历史撒谎。
 func (h *Handle) Mark(state string) {
 	if h == nil || state == "" {
 		return
 	}
 	cur := normalizeState(h.rec.State)
-	if cur != StateRunning && cur != StateWaitingApproval {
-		return
-	}
-	if state != StateRunning && state != StateWaitingApproval {
+	if !isLiveState(cur) || !isLiveState(state) {
 		return
 	}
 	if cur == state {
@@ -333,6 +436,8 @@ func (h *Handle) write() {
 		return
 	}
 	_ = os.Rename(tmp, h.path)
+	// 会话级状态与登记表同一步更新（见 status.go）：客户端只读那一份，不再各自按 run 推算。
+	setStatus(h.rec)
 }
 
 // Begin 新建一条 running 记录（NoPersist 时只在内存里建，不落盘）。
@@ -362,18 +467,72 @@ func Begin(o BeginOptions) (*Handle, error) {
 		Source:     normalizeSource(o.Source),
 		Client:     normalizeClient(o.Client),
 		Workspace:  o.Workspace,
+		Cwd:        cwdOf(),
 		PromptHead: head(o.PromptHead, 80),
 		State:      StateRunning,
 		StartedAt:  now,
 		UpdatedAt:  now,
+		// 父会话指针（团队子任务）：落盘后列表页据此把子会话挂在主会话下。
+		ParentRunID:     strings.TrimSpace(o.ParentRunID),
+		ParentSessionID: strings.TrimSpace(o.ParentSessionID),
 	}
 	// path 照样算出来：追加入口的 socket 与它同目录同前缀（见 AppendSocketPath），
 	// 句柄里留着它，SetAppendPath 之类也不用知道自己是不是在存档模式。
 	h := &Handle{rec: rec, path: filepath.Join(dir, rec.RunID+".json"), noPersist: o.NoPersist}
 	h.write() // noPersist 时这里什么都不做
+	// 「新起即停旧」：同一条会话上还活着的上一次运行先停掉（见 supersedeSiblings）。
+	if !o.NoPersist && rec.SessionID != "" {
+		supersedeSiblings(rec.SessionID, rec.RunID, rec.PID)
+	}
 	return h, nil
 }
 
+// supersedeSiblings 停掉同一会话上**还活着**的上一次运行。
+//
+// 为什么（2026-10-21，用户：「两边的回话状态不一致，一边结束了，一边还在显示运行中」）：
+// 同一个 session_id 被两个进程同时 `--resume` 时，两边的 sessionWriter 各算各的 seq、
+// 都往 <session_id>.jsonl 追加 —— 文件里出现成对重号的 seq（实测一条 9506 条事件的
+// 文件里 4589 个重号）。读侧按 `--after seq` 增量续读时，另一条 lane 的事件全都
+// `seq <= after` 被滤掉：一端读到 turn_end 显示「已完成」，另一端永远等不到终态；
+// 登记表里那条旧 run 又一直 running，`Find` 于是永远答「在跑」。
+// 而同一会话本来也不该被两个引擎进程同时续接（引擎侧的会话状态也会互相覆盖）。
+//
+// 口径与 Stop 一致：先 SIGTERM，宽限期不退再 SIGKILL，确认消失后写 cancelled。
+// 只在落盘模式下做：NoPersist 的调用彼此看不见，也无从判定谁是「旧」的。
+func supersedeSiblings(sessionID, runID string, selfPID int) {
+	sessionID = strings.TrimSpace(sessionID)
+	if sessionID == "" {
+		return
+	}
+	all, err := List()
+	if err != nil {
+		return
+	}
+	for _, r := range all {
+		if r.RunID == runID || r.SessionID != sessionID {
+			continue
+		}
+		if !isLiveState(r.State) {
+			continue
+		}
+		if r.PID <= 0 || r.PID == selfPID || !agent.PIDAlive(r.PID) {
+			continue
+		}
+		_ = agent.TerminatePID(r.PID, r.KillGroup)
+		if !waitGone(r.PID, 2*time.Second) {
+			_ = agent.KillPID(r.PID, r.KillGroup)
+			if !waitGone(r.PID, 2*time.Second) {
+				fmt.Fprintf(os.Stderr, "magic-agent: 同会话的上一次运行（pid %d / %s）未能停止，两端状态可能仍不一致\n", r.PID, r.RunID)
+				continue
+			}
+		}
+		r.State = StateCancelled
+		r.UpdatedAt = time.Now()
+		writeRecord(r)
+		fmt.Fprintf(os.Stderr, "magic-agent: 已停止同会话的上一次运行（pid %d / %s），避免两个进程同时续写同一份会话日志\n", r.PID, r.RunID)
+	}
+}
+
 // head 截取开头 n 个字符（按 rune，避免把中文切坏）。
 func head(s string, n int) string {
 	s = strings.TrimSpace(strings.ReplaceAll(s, "\n", " "))
@@ -384,6 +543,16 @@ func head(s string, n int) string {
 	return string(r[:n]) + "…"
 }
 
+// cwdOf 取进程当前目录；拿不到就留空（需求归纳按 workspace 归属时会退回用
+// Workspace 字段，两者都没有就只是不参与按目录的自动分组，不影响会话本身）。
+func cwdOf() string {
+	dir, err := os.Getwd()
+	if err != nil {
+		return ""
+	}
+	return dir
+}
+
 // List 返回全部记录（新的在前）；顺带清理读不出来的坏文件。
 func List() ([]Record, error) {
 	dir := Dir()
@@ -424,7 +593,7 @@ func List() ([]Record, error) {
 // 与 Stop() 的「进程已不在 → gone」判定同口径；PID 缺失（<=0）的老记录无从判断，
 // 保持原样。返回 true 表示状态被改过，调用方需要回写。
 func normalizeDead(rec *Record) bool {
-	if rec.State != StateRunning && rec.State != StateWaitingApproval {
+	if !isLiveState(rec.State) {
 		return false
 	}
 	if rec.PID <= 0 || agent.PIDAlive(rec.PID) {
@@ -436,7 +605,7 @@ func normalizeDead(rec *Record) bool {
 }
 
 // Find 按 run_id 或 session_id 精确匹配一条记录。
-// 同 id 有多条时优先「running」的那条，其次取最新。
+// 同 id 有多条时优先「还活着」的那条（其中 running 优先于 idle/等审批），其次取最新。
 func Find(id string) (Record, bool, error) {
 	want := strings.TrimSpace(id)
 	if want == "" {
@@ -455,6 +624,8 @@ func Find(id string) (Record, bool, error) {
 		switch {
 		case !found:
 			best, found = r, true
+		case isLiveState(r.State) && !isLiveState(best.State):
+			best = r
 		case r.State == StateRunning && best.State != StateRunning:
 			best = r
 		case r.State == best.State && r.StartedAt.After(best.StartedAt):
@@ -484,7 +655,9 @@ func Stop(id string) (StopResult, error) {
 		return StopResult{}, fmt.Errorf("no such session %q（--sessions 可列出全部）", id)
 	}
 
-	if rec.State != StateRunning {
+	/* idle / waiting_approval 的进程同样活着（只是当前没在跑），必须照常终止 ——
+	   否则 --stop 对一条常驻会话只会回一句「已结束」，进程却继续占着会话日志。 */
+	if !isLiveState(rec.State) {
 		/* gone 是 List() 在读侧归一的「进程已不在」，和下面那条死进程分支是同一件事，
 		   原因文案保持一致（Stop 的调用方据此区分「本来就结束了」与「进程没了」）。 */
 		if rec.State == StateGone {
@@ -548,7 +721,11 @@ func readRecord(path string) (Record, error) {
 }
 
 // writeRecord 覆盖写一条记录（按 RunID 定位文件名）。
+//
+// ⚠️ 这里也是**会话级状态**的唯一写入口（setStatus）：Stop / supersedeSiblings /
+// normalizeDead 都不经过 Handle，只走这里 —— 状态表挂在更低一层才覆盖得到它们。
 func writeRecord(rec Record) {
+	setStatus(rec)
 	dir := Dir()
 	if dir == "" || rec.RunID == "" {
 		return

package/internal/session/session_append.go

@@ -240,7 +240,10 @@ func AppendMessage(id, text string) (AppendResult, error) {
 		return AppendResult{Record: rec, Reason: reason},
 			fmt.Errorf("%s；常驻会话要用 --stream --keep-alive 启动，已结束的会话请用 --session <id> 续接", reason)
 	}
-	if rec.State != StateRunning {
+	/* 常驻会话在轮次之间是 idle（本轮已结束、进程还在等追加）—— 这正是 --append
+	   存在的窗口，不能按「已结束」拒收。其它非 running 状态（等审批）维持原样：
+	   那时引擎正停在提问上，追加的内容该走 control 的 answer，而不是当成新一轮。 */
+	if rec.State != StateRunning && rec.State != StateIdle {
 		return AppendResult{Record: rec, Reason: "会话已结束（state=" + rec.State + "）"},
 			fmt.Errorf("会话已结束（state=%s）；请用 --session <id> 续接", rec.State)
 	}

package/internal/session/session_append_test.go

@@ -80,6 +80,25 @@ func TestAppendMessageDelivers(t *testing.T) {
 	}
 }
 
+// 常驻会话在轮次之间是 idle（本轮已结束、进程还在等追加）—— --append 正是这个窗口，
+// 不能按「会话说已结束」拒收（2026-10-21 新增 idle 时一并钉住）。
+func TestAppendMessageAllowsIdle(t *testing.T) {
+	h, _, ch := startAppender(t)
+	h.Mark(StateIdle)
+
+	if _, err := AppendMessage(h.RunID(), "下一轮"); err != nil {
+		t.Fatalf("idle 的常驻会话应能追加: %v", err)
+	}
+	select {
+	case got := <-ch:
+		if got != "下一轮" {
+			t.Errorf("收到的消息 = %q", got)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("没投递")
+	}
+}
+
 // 用会话 id 追加（观物台手里通常只有 session_id）。
 func TestAppendMessageBySessionID(t *testing.T) {
 	isolate(t)