feat(agent): 诊断 run 取消/终止原因,取代笼统的中断提示

- 新增 AbortCause(cancelcause.go):各取消点用 WithCancelCause/WithTimeoutCause
  附上原因(暂停/删除/kill_work/目标达成/drain 兜底/聊天停止/进程关闭/硬超时…),
  captureRun 用 context.Cause 还原出到底是谁、为何取消。
- 新增 terminalreason.go:把终端状态转成可读的一行摘要 + 多行详情(取消原因、
  终止 reason、轮数、卡住的工具),替换原来固定那句猜测式提示。
- engine/worker/planner/capture 及 conversations/orchestration/server 接入;
  cmd/artex/main.go、前端 llm/main-content 相应调整。
- 配套测试 terminalreason_test.go / engine_cancelcause_test.go。

agent/cancelcause.go

@@ -0,0 +1,116 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+)
+
+// AbortCause names WHY a planner/worker run's context was cancelled.
+//
+// Background: when a run's ctx is cancelled mid-flight the harness finishes with
+// ReasonAbortedStreaming / ReasonAbortedTools and Terminal.Err = context.Canceled.
+// ARTEX cancels that ctx from a dozen different places (pause, delete, kill_work,
+// goal-met, settle drain backstop, chat stop, process shutdown, hard run timeout,
+// …) but by the time it reaches captureRun they all collapse into one bare
+// context.Canceled — so the trace could only print a guess-list, not a diagnosis.
+//
+// Fix: every cancel site uses context.WithCancelCause / WithTimeoutCause and
+// attaches one of the causes below; captureRun recovers it via context.Cause and
+// prints exactly who cancelled the run, why, and what happens to the intent.
+//
+// When you add a new cancel site, add its cause HERE — a site that cancels
+// without one shows up in the trace as "canceled_no_cause", by design.
+type AbortCause struct {
+	Code  string // stable machine-readable id (logs / future filtering)
+	Short string // 一句话，进折叠摘要行
+	Text  string // 完整说明：谁取消的、为什么、这条意图接下来会怎样
+}
+
+func (c *AbortCause) Error() string { return c.Text }
+
+func cause(code, short, text string) *AbortCause {
+	return &AbortCause{Code: code, Short: short, Text: text}
+}
+
+// Causef builds an ad-hoc cause with runtime detail (e.g. which intent, which
+// deadline). Use the predeclared vars below when there is nothing dynamic to add.
+func Causef(code, short, format string, args ...any) *AbortCause {
+	return &AbortCause{Code: code, Short: short, Text: fmt.Sprintf(format, args...)}
+}
+
+// The full enumeration of cancel sites, grouped by which context gets cancelled.
+var (
+	// ---- 任务级 exec ctx（Engine.cancelExec：取消该任务在跑的 planner + 全部 worker）----
+
+	AbortPausedByUser = cause("paused_by_user", "用户暂停了任务",
+		"用户暂停了任务（前端「暂停」按钮 / POST /api/tasks/{id}/state action=pause）。本次运行被主动取消，该意图已退回 frontier(open)，恢复任务后会被重新领取、从头重跑")
+
+	AbortPausedByOrchestrator = cause("paused_by_orchestrator", "编排 agent 调用 pause_task 暂停了任务",
+		"编排 agent 调用了 pause_task 工具暂停本任务。本次运行被主动取消，该意图已退回 frontier(open)，恢复后重跑")
+
+	AbortTaskDeleted = cause("task_deleted", "任务被删除",
+		"任务被删除（DELETE /api/tasks/{id}）——删除前先取消在跑的 planner/worker。本次运行的结果不会再被使用")
+
+	AbortPausedOnReload = cause("paused_on_reload", "后端启动时恢复了「已暂停」状态",
+		"后端启动时按库里持久化的「已暂停」状态恢复暂停。本次运行被取消（正常情况下此时并没有在跑的 run）")
+
+	AbortGoalMet = cause("goal_met", "规划者判定目标已达成，任务落终态 done",
+		"规划者判定任务目标已达成、任务落终态 done，随即取消所有在跑的 worker——它们手头的意图跑完也没意义了。该意图标记为 stopped，不是失败")
+
+	AbortSettleDrainTimeout = cause("settle_drain_timeout", "任务级超时收尾：drain 宽限用尽后强制取消",
+		"任务级超时收尾的硬兜底：到达任务 timeout 后等在跑 worker 优雅收尾，超过 90s drain 宽限仍未结束 → 强制取消。该意图标记为 exhausted，收尾阶段通常已把事实/资产写回")
+
+	// ---- 单个 work 的 ctx（Engine.workCancel[intentID]）----
+
+	AbortKilledByPlanner = cause("killed_by_planner", "规划者用 kill_work 终止了这条意图",
+		"规划者调用 kill_work 主动终止了这条意图（判定方向跑偏/无意义，止损）。该意图标记为 stopped，不会被自动重领")
+
+	AbortWorkFinished = cause("work_finished", "work 已正常结束，引擎释放其 context",
+		"work 已正常结束，引擎在 unregisterWork 里释放其 context 资源。这不是中断——若它出现在中断消息里，说明取消与收场事件存在竞态")
+
+	AbortPausedRaceGuard = cause("paused_race_guard", "任务处于暂停态，引擎拒绝启动新 run",
+		"任务处于暂停态时请求执行上下文，引擎直接返回一个已取消的 context（守卫 claim→Execute 的竞态，避免暂停后仍启动新 run）。该意图会退回 frontier")
+
+	// ---- 对话 / 主 Agent 的单轮 ctx（Server.chatCancel[busyKey]）----
+
+	AbortChatStoppedByUser = cause("chat_stopped_by_user", "用户点了「停止」中止本轮对话",
+		"用户点了「停止」，主动中止本轮对话运行（POST .../chat/stop 或 .../conversations/{id}/stop）。已产生的步骤都保留，可以直接发下一条消息")
+
+	AbortChatTurnFinished = cause("chat_turn_finished", "本轮对话已正常结束，服务端释放其 context",
+		"本轮对话已正常结束，服务端在 defer 里释放其 context 资源。这不是中断——若它出现在中断消息里，说明取消与收场事件存在竞态")
+
+	// ---- 进程级 ----
+
+	AbortShutdown = cause("shutdown", "后端进程正在关停（重启 / 更新 / Ctrl-C）",
+		"后端进程收到 SIGINT/SIGTERM 正在关停（重启 / 更新 / 手动 Ctrl-C）。所有在跑的 planner/worker 一并取消；重启后残留的 running 意图会被重置为 open 重跑")
+
+	// ---- 单次 run 级（worker.Execute / planner.Plan 的硬兜底）----
+
+	AbortRunHardTimeout = cause("run_hard_timeout", "单次运行的硬超时兜底触发：某一步卡死了",
+		"单次运行的硬超时兜底被触发：正常情况下软墙钟预算(MaxDuration)会在回合边界优雅收尾，只有当某一步（模型请求或某个工具）自身卡死、久久不返回、导致回合边界检查根本跑不到时，才会走到「软预算 + 90s 宽限」的硬 cancel。请重点看中断前最后一个 tool_use——多半是它挂住了")
+)
+
+// AbortReason resolves the cause attached to a cancelled run context. ok=false
+// means the ctx carries no cause at all (nothing was cancelled).
+func AbortReason(ctx context.Context) (code, short, text string, ok bool) {
+	c := context.Cause(ctx)
+	if c == nil {
+		return "", "", "", false
+	}
+	if ac, ok := errors.AsType[*AbortCause](c); ok {
+		return ac.Code, ac.Short, ac.Text, true
+	}
+	switch {
+	case errors.Is(c, context.DeadlineExceeded):
+		return "deadline_exceeded", "上游 context 到达 deadline（未挂具名原因）",
+			"上游 context 到达 deadline，但设置方没有用 WithTimeoutCause 挂具名原因: " + c.Error(), true
+	case errors.Is(c, context.Canceled):
+		// a plain Canceled means some cancel site still lacks a cause — say so
+		// plainly instead of inventing one.
+		return "canceled_no_cause", "取消方未挂具名原因（漏网的取消点）",
+			"上游 context 被取消，但取消方没有用 context.WithCancelCause 挂上具名原因。" +
+				"这属于漏网的取消点——请在 agent/cancelcause.go 补一条枚举并接到该取消处", true
+	}
+	return "other", firstLine(c.Error(), 80), c.Error(), true
+}