Merge pull request 'dailyops：補齊 tea 對等指令（#40）' (#41) from feat/issue40-tea-parity into main

審核意見（PR #36）：issue 1 與 issue 3 在新邏輯下同為 10h，
sort.SliceStable 平手時順序取決於 map 迭代隨機順序，
TestScanStalledIssueReasons 的 got[0].Number != 1 斷言不穩定。

採建議修法 1：fakeSource.OpenIssues 回傳前依 number 遞增排序，
對齊真實 Gitea API（issues 依 id 遞增）行為。實作未動。

go build / go vet / go test ./... 全綠；
TestScanStalledIssueReasons -count=50 重跑全綠。

.gitignore

@@ -19,3 +19,4 @@ coverage.*
 # 作業系統
 .DS_Store
 Thumbs.db
+teai-bin

README.md

@@ -72,17 +72,22 @@ issues／pulls／labels／milestones／releases／repos／api 的日常操作，
 
 ```sh
 # issues
-teai issues list --repo <owner>/<repo> [--state open|closed|all]
+teai issues list --repo <owner>/<repo> [--state open|closed|all] [--labels a,b]   # 多標籤 AND
 teai issues view --repo <owner>/<repo> <number> [--comments]
 teai issues create --repo <owner>/<repo> --title … [--body …] [--assignees a,b] --yes
 teai issues close --repo <owner>/<repo> --yes <number>
-teai issues comment --repo <owner>/<repo> --body … --yes <number>
+teai issues comment --repo <owner>/<repo> [--body …] --yes <number> [留言…]       # 位置參數優先（#40）
 # pulls（無子命令仍是工作流清單：--mine／--reviewer／--repo）
 teai pulls list --repo <owner>/<repo> [--state open|closed|all]
 teai pulls view --repo <owner>/<repo> <number> [--comments]
 teai pulls create --repo <owner>/<repo> --head <branch> [--base main] --title … [--body …] --yes
 teai pulls merge --repo <owner>/<repo> [--style merge|rebase|rebase-merge|squash] --yes <number>
-teai pulls comment --repo <owner>/<repo> --body … --yes <number>
+teai pulls approve --repo <owner>/<repo> [--body …] --yes <number> [意見…]        # POST reviews，event=APPROVED（#40）
+teai pulls close --repo <owner>/<repo> --yes <number>                              # 關閉不合併（PATCH state=closed；#40）
+teai pulls checkout --repo <owner>/<repo> [--dir <path>] <number>                   # 本機 git 取得 head（#40）
+teai pulls comment --repo <owner>/<repo> [--body …] --yes <number> [留言…]
+# 通用留言（tea comment 對等；issue 與 PR 共用端點，#40）
+teai comment --repo <owner>/<repo> [--body …] --yes <number> [留言…]
 # labels／milestones／releases／repos
 teai labels list --repo <owner>/<repo>
 teai labels create --repo <owner>/<repo> --name … [--color #RRGGBB] [--description …] --yes
@@ -96,8 +101,9 @@ teai repos list [--org <org>]
 teai api <path> [--method GET|POST|PATCH|DELETE] [--data '<json>'] [--yes]
 ```
 
-> `--yes` 閘門：所有寫入類命令（create／close／comment／merge／labels create／milestones create／api 非 GET 動詞）未帶 `--yes` 時回 exit 2（用法錯誤），且不發出任何 HTTP 請求。
+> `--yes` 閘門：所有寫入類命令（create／close／comment／merge／approve／labels create／milestones create／api 非 GET 動詞）未帶 `--yes` 時回 exit 2（用法錯誤），且不發出任何 HTTP 請求。
 > `teai api` 的 path 內含查詢字串（如 `/repos/a/b/issues?state=closed`）時會正確傳遞。
+> `teai pulls checkout` 是本機唯讀輔助：同倉庫 head 在 `--dir`（預設當前目錄）的既有工作樹 `git fetch origin <ref> && git checkout -B <ref> FETCH_HEAD`；跨倉庫 head 需 `--dir`（新目錄）執行 `git clone --branch <ref> <clone_url>`。teai 不代管 git 認證，私有倉庫請自備 credential helper。
 
 ### 全域介面
 
@@ -299,7 +305,7 @@ teai whoami               # 目前帳號（讀 tea 組態）
 
 | 碼 | 意義 |
 | --- | --- |
-| 0 | 成功（含「沒有工作」→ 輸出 `null`／`[]`） |
+| 0 | 成功（含「沒有結果」→ 清單類命令輸出 `[]`、`next` 輸出 `null`；#37 判決） |
 | 2 | 用法錯誤（未知命令／參數） |
 | 3 | API 錯誤（連線失敗、401、403、5xx） |
 
@@ -318,8 +324,12 @@ teai whoami               # 目前帳號（讀 tea 組態）
 已知輸出差異（刻意保留，機器可讀優先）：
 
 - **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令
-  （`mine`／`pulls`／`milestones` 總覽）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確，
+  （`mine`／`pulls`／`stalled`／`milestones` 總覽）空清單一律輸出 `[]`（exit 0）。對 JSON
-  交叉驗證時以此差異為準。`next` 兩者語義相同（無工作 → `null`／「沒有未完成的工作」）。
+  消費者來說 `[]` 比「無輸出」更明確（可區分「沒有結果」與「查詢失敗無輸出」），交叉驗證時
+  以此差異為準。`next` 兩者語義相同：無工作時 teai 輸出 `null`（exit 0）、`gitea.py` 印
+  「沒有未完成的工作」。**判決 #37：維持 teai 現行 JSON 一致性（方向 2）**——消費端
+  （agents 倉庫巡邏提示與觸發腳本）應以「輸出 `[]`／`null` 且 exit 0」為「沒有」判據，
+  不得以「無輸出」判斷；`members [--has-work]` 維持逐行帳號、空時無輸出（兩者一致，不受影響）。
 - **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件
   （`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位
   （`mine`：repo／number／title／url；`pulls`：number／title／state／author／

cmd/xcheck/main.go

@@ -165,6 +165,14 @@ func (s *apiSource) IssueComments(owner, repo string, number int64) ([]workflow.
 	return comments, nil
 }
 
+func (s *apiSource) IssueTimeline(owner, repo string, number int64) ([]workflow.TimelineEvent, error) {
+	var events []workflow.TimelineEvent
+	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/timeline", owner, repo, number), nil, &events); err != nil {
+		return nil, err
+	}
+	return events, nil
+}
+
 func (s *apiSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
 	var issue workflow.Issue
 	body, code, err := s.get(fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, number), nil)

internal/cli/dailyops_commands.go

@@ -14,6 +14,9 @@ import (
 	"encoding/json"
 	"flag"
 	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -23,8 +26,9 @@ import (
 
 func init() {
 	register := func(c *command) { commands[c.name] = c }
-	register(&command{name: "issues", usage: "issues 管理（list/view/create/close/comment）", run: runIssues})
+	register(&command{name: "issues", usage: "issues 管理（list/view/create/close/comment；list 支援 --labels 過濾）", run: runIssues})
-	register(&command{name: "pulls", usage: "PR 管理（list/view/create/merge/comment；無子命令＝工作流清單）", run: runPullsDaily})
+	register(&command{name: "pulls", usage: "PR 管理（list/view/create/merge/approve/close/checkout/comment；無子命令＝工作流清單）", run: runPullsDaily})
+	register(&command{name: "comment", usage: "對 issue 或 PR 留言（--repo owner/repo <number> --body …）", run: runCommentDirect})
 	register(&command{name: "labels", usage: "標籤管理（list/create）", run: runLabels})
 	register(&command{name: "milestones", usage: "里程碑（跨倉庫總覽；list/create 管理單倉庫）", run: runMilestones})
 	register(&command{name: "releases", usage: "發佈清單（list）", run: runReleases})
@@ -122,12 +126,13 @@ func runIssues(env *Env, args []string) error {
 	}
 }
 
-// runIssuesList：teai issues list --repo owner/repo [--state open|closed|all]
+// runIssuesList：teai issues list --repo owner/repo [--state open|closed|all] [--labels a,b]
 func runIssuesList(env *Env, args []string) error {
 	fs := flag.NewFlagSet("teai issues list", flag.ContinueOnError)
 	fs.SetOutput(env.Err)
 	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
 	state := fs.String("state", "open", "狀態：open|closed|all")
+	labels := fs.String("labels", "", "標籤過濾（逗號分隔，可選；多標籤為 AND）")
 	if err := parseFlags(fs, args); err != nil {
 		return err
 	}
@@ -141,11 +146,19 @@ func runIssuesList(env *Env, args []string) error {
 	if owner == "" {
 		return &ErrUsage{Msg: "issues list 需要 --repo owner/repo"}
 	}
+	var labelList []string
+	if strings.TrimSpace(*labels) != "" {
+		for _, l := range strings.Split(*labels, ",") {
+			if l = strings.TrimSpace(l); l != "" {
+				labelList = append(labelList, l)
+			}
+		}
+	}
 	ops, err := newOpsClient(env)
 	if err != nil {
 		return err
 	}
-	issues, err := ops.ListIssues(context.Background(), owner, name, *state)
+	issues, err := ops.ListIssues(context.Background(), owner, name, *state, labelList)
 	if err != nil {
 		return err
 	}
@@ -316,6 +329,8 @@ func runIssuesClose(env *Env, args []string) error {
 }
 
 // runComment：teai issues comment / teai pulls comment 共用。
+// 相容 tea 用法：留言可作為位置參數（tea comment --repo a/b <index> "內容"），
+// 亦可 teai 慣用的 --body；兩者同時給時位置參數優先（與 tea 行為一致）。
 func runComment(env *Env, args []string, isPR bool) error {
 	name := "issues comment"
 	if isPR {
@@ -324,7 +339,7 @@ func runComment(env *Env, args []string, isPR bool) error {
 	fs := flag.NewFlagSet("teai "+name, flag.ContinueOnError)
 	fs.SetOutput(env.Err)
 	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
-	body := fs.String("body", "", "留言內容（必填）")
+	body := fs.String("body", "", "留言內容（可改用位置參數）")
 	yes := fs.Bool("yes", false, "確認寫入")
 	if err := parseFlags(fs, args); err != nil {
 		return err
@@ -336,16 +351,21 @@ func runComment(env *Env, args []string, isPR bool) error {
 	if owner == "" {
 		return &ErrUsage{Msg: name + " 需要 --repo owner/repo"}
 	}
-	if strings.TrimSpace(*body) == "" {
+	// 位置參數：<number> [body…]；尾端多餘引數以空格接成一則留言（tea 相容）。
-		return &ErrUsage{Msg: name + " 需要 --body"}
+	if fs.NArg() < 1 {
-	}
+		return &ErrUsage{Msg: name + " 需要恰好一個編號（可選加留言位置參數）"}
-	if fs.NArg() != 1 {
-		return &ErrUsage{Msg: name + " 需要恰好一個編號"}
 	}
 	num, err := parseNumber(fs.Arg(0))
 	if err != nil {
 		return err
 	}
+	text := strings.TrimSpace(*body)
+	if fs.NArg() > 1 {
+		text = strings.TrimSpace(strings.Join(fs.Args()[1:], " "))
+	}
+	if text == "" {
+		return &ErrUsage{Msg: name + " 需要留言內容（--body 或位置參數）"}
+	}
 	if err := requireYes(*yes, name); err != nil {
 		return err
 	}
@@ -353,7 +373,7 @@ func runComment(env *Env, args []string, isPR bool) error {
 	if err != nil {
 		return err
 	}
-	comment, err := ops.AddComment(context.Background(), owner, rname, num, *body)
+	comment, err := ops.AddComment(context.Background(), owner, rname, num, text)
 	if err != nil {
 		return err
 	}
@@ -381,13 +401,26 @@ func runPullsDaily(env *Env, args []string) error {
 		return runPullsCreate(env, rest)
 	case "merge":
 		return runPullsMerge(env, rest)
+	case "approve":
+		return runPullsApprove(env, rest)
+	case "close":
+		return runPullsClose(env, rest)
+	case "checkout":
+		return runPullsCheckout(env, rest)
 	case "comment":
 		return runComment(env, rest, true)
 	default:
-		return &ErrUsage{Msg: fmt.Sprintf("pulls 未知子命令 %q（可用：list | view | create | merge | comment；或無子命令＝工作流清單）", sub)}
+		return &ErrUsage{Msg: fmt.Sprintf("pulls 未知子命令 %q（可用：list | view | create | merge | approve | close | checkout | comment；或無子命令＝工作流清單）", sub)}
 	}
 }
 
+// runCommentDirect：teai comment --repo owner/repo <number> <body> [--yes]。
+// tea 的通用留言指令：issue 與 PR 共用同一端點（Gitea 以 number 定位，
+// issues/<n>/comments 對兩者皆有效），故不需 --type 旗標。
+func runCommentDirect(env *Env, args []string) error {
+	return runComment(env, args, false)
+}
+
 // runPullsList：teai pulls list --repo owner/repo [--state open|closed|all]
 func runPullsList(env *Env, args []string) error {
 	fs := flag.NewFlagSet("teai pulls list", flag.ContinueOnError)
@@ -560,6 +593,179 @@ func runPullsMerge(env *Env, args []string) error {
 	}, gitea.Values{num, "merged"})
 }
 
+// runPullsApprove：teai pulls approve --repo owner/repo [--body …] --yes <number>。
+// tea 相容：意見也可作為位置參數（teai pulls approve --repo a/b <n> "驗證通過。"）。
+func runPullsApprove(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls approve", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	body := fs.String("body", "", "審核意見（可改用位置參數）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls approve 需要 --repo owner/repo"}
+	}
+	if fs.NArg() < 1 {
+		return &ErrUsage{Msg: "pulls approve 需要恰好一個編號（可選加意見位置參數）"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	text := strings.TrimSpace(*body)
+	if fs.NArg() > 1 {
+		text = strings.TrimSpace(strings.Join(fs.Args()[1:], " "))
+	}
+	if err := requireYes(*yes, "pulls approve"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	review, err := ops.ApprovePull(context.Background(), owner, name, num, text)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "state"}, {Name: "author"}, {Name: "body"},
+	}, gitea.Values{review.Number, review.State, review.Author(), review.Body})
+}
+
+// runPullsClose：teai pulls close --repo owner/repo --yes <number>。
+// 關閉不合併；工作流約定 merge 才是正途（AGENTS.md 6.2），本指令提供語義對等。
+func runPullsClose(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls close", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls close 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "pulls close 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	if err := requireYes(*yes, "pulls close"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	pr, err := ops.ClosePull(context.Background(), owner, name, num)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"}, {Name: "url"},
+	}, gitea.Values{pr.Number, pr.Title, pr.State, pr.HTMLURL})
+}
+
+// runPullsCheckout：teai pulls checkout --repo owner/repo <number> [--dir <path>]。
+// 唯讀輔助指令：取得 PR head 資訊，在本機以 git 取得工作副本——
+// 同倉庫分支 → git fetch --quiet origin <ref> && git checkout -B <ref> FETCH_HEAD
+// （在 --dir 指定的既有 git 工作樹內執行；預設當前目錄）；
+// 跨倉庫 head → git clone --branch <ref> <clone_url> <dir>（--dir 必填，目錄不得已存在）。
+// teai 不碰認證：clone 走 https 公開網址，私有倉庫時請自備 git 認證（credential helper）。
+func runPullsCheckout(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls checkout", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	dir := fs.String("dir", "", "工作樹目錄（預設當前目錄；跨倉庫 head 時必填且不得已存在）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls checkout 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "pulls checkout 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	info, err := ops.PullHeadInfo(context.Background(), owner, name, num)
+	if err != nil {
+		return err
+	}
+	if info.Ref == "" {
+		return fmt.Errorf("PR #%d 缺少 head 分支資訊", num)
+	}
+	workDir := *dir
+	if workDir == "" {
+		workDir = "."
+	}
+	// git 指令一律固定參數（不經 shell、不插入使用者字串），分支名僅作為
+	// git 自身剖析的引數傳入；錯誤訊息往 env.Err，成功輸出到 env.Out。
+	// 注意：git clone 的目標目錄是位置參數，cmd.Dir 不可指向不存在目錄，
+	// 故 clone 一律在當前目錄執行（--dir 以絕對路徑傳入）。
+	runGit := func(dir string, args ...string) error {
+		cmd := exec.Command("git", args...)
+		cmd.Dir = dir
+		cmd.Stdout = env.Out
+		cmd.Stderr = env.Err
+		return cmd.Run()
+	}
+	if info.Repo == "" {
+		// 同倉庫：fetch 指定分支並建立／更新本地分支。
+		if err := runGit(workDir, "fetch", "--quiet", "origin", "--", info.Ref); err != nil {
+			return fmt.Errorf("git fetch origin %s 失敗（在 %s）：%w", info.Ref, workDir, err)
+		}
+		if err := runGit(workDir, "checkout", "-q", "-B", info.Ref, "FETCH_HEAD"); err != nil {
+			return fmt.Errorf("git checkout -B %s 失敗：%w", info.Ref, err)
+		}
+		return printer(env).PrintOne([]gitea.Field{
+			{Name: "number"}, {Name: "branch"}, {Name: "workdir"},
+		}, gitea.Values{num, info.Ref, workDir})
+	}
+	// 跨倉庫 head：clone 到 --dir（不得已存在）。
+	if *dir == "" {
+		return &ErrUsage{Msg: "pulls checkout：跨倉庫 head（" + info.Repo + "）需要 --dir <目錄>"}
+	}
+	if st, err := os.Stat(*dir); err == nil && st.IsDir() {
+		return &ErrUsage{Msg: "pulls checkout：--dir 已存在（跨倉庫 head 需要新目錄）：" + *dir}
+	}
+	if info.CloneURL == "" {
+		return fmt.Errorf("PR #%d 的 head 倉庫 %s 未提供 clone 網址", num, info.Repo)
+	}
+	abs, err := filepath.Abs(*dir)
+	if err != nil {
+		return &ErrUsage{Msg: "pulls checkout：無效的 --dir：" + err.Error()}
+	}
+	if err := runGit(".", "clone", "--quiet", "--branch", info.Ref, "--", info.CloneURL, abs); err != nil {
+		return fmt.Errorf("git clone %s 失敗：%w", info.CloneURL, err)
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "branch"}, {Name: "repo"}, {Name: "workdir"},
+	}, gitea.Values{num, info.Ref, info.Repo, *dir})
+}
+
 // ---- labels ----
 
 // runLabels：teai labels list --repo owner/repo｜teai labels create … --yes

internal/cli/dailyops_commands_test.go

@@ -220,6 +220,52 @@ func TestLabelsMilestonesReleasesList(t *testing.T) {
 	}
 }
 
+// TestStateAllSendsExplicitParam 是 #33 的回歸測試：issues／milestones
+// 端點省略 state 時 API 預設 open，closed 項目會漏列，因此 --state all
+// 必須明確帶 state=all；pulls 端點雖省略時也回全部，同樣明確帶上。
+func TestStateAllSendsExplicitParam(t *testing.T) {
+	cases := []struct {
+		args    []string
+		resp    string
+		wantOut string
+	}{
+		{
+			args:    []string{"issues", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"number":30,"title":"open","state":"open","user":{"login":"ceo"},"updated_at":"t"},{"number":12,"title":"closed","state":"closed","user":{"login":"ceo"},"updated_at":"t"}]`,
+			wantOut: `"title":"closed"`,
+		},
+		{
+			args:    []string{"pulls", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"number":5,"title":"open PR","state":"open","user":{"login":"ceo"},"head":{"ref":"f"},"base":{"ref":"main"},"updated_at":"t"},{"number":2,"title":"closed PR","state":"closed","user":{"login":"ceo"},"head":{"ref":"f2"},"base":{"ref":"main"},"updated_at":"t"}]`,
+			wantOut: `"title":"closed PR"`,
+		},
+		{
+			args:    []string{"milestones", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"title":"v2","state":"open","description":"","due_on":""},{"title":"v1","state":"closed","description":"","due_on":""}]`,
+			wantOut: `"title":"v1"`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
+			var gotQuery string
+			run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+				gotQuery = r.URL.RawQuery
+				fmt.Fprint(w, tc.resp)
+			})
+			stdout, _, code := run(tc.args...)
+			if code != 0 {
+				t.Fatalf("%v 應回 0，得到 %d", tc.args, code)
+			}
+			if !strings.Contains(gotQuery, "state=all") {
+				t.Errorf("%v 應明確帶 state=all（省略時 issues／milestones 端點預設 open），得到查詢 %q", tc.args, gotQuery)
+			}
+			if !strings.Contains(stdout, tc.wantOut) {
+				t.Errorf("%v 輸出應含 closed 項目 %s，得到：%s", tc.args, tc.wantOut, stdout)
+			}
+		})
+	}
+}
+
 // TestAPIDirectPassthrough 驗證 teai api 原樣輸出、GET 免 --yes、
 // POST 未帶 --yes 被擋。
 func TestAPIDirectPassthrough(t *testing.T) {

internal/cli/dailyops_parity_commands_test.go

@@ -0,0 +1,289 @@
+// dailyops_parity_commands_test.go — #40 的驗收測試：補齊 tea 對等指令
+// pulls approve／close／checkout、通用 comment、issues list --labels 過濾。
+// 寫入命令未帶 --yes 不得發出任何請求；帶 --yes 時打對端點與 payload。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestParityWriteCommandsRequireYes 驗證新增寫入命令未帶 --yes：
+// 回 2 且不發請求（#40 驗收：寫入閘門慣例）。
+func TestParityWriteCommandsRequireYes(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+	}{
+		{"pulls approve", []string{"pulls", "approve", "--repo", "a/b", "1"}},
+		{"pulls close", []string{"pulls", "close", "--repo", "a/b", "1"}},
+		{"comment direct", []string{"comment", "--repo", "a/b", "1", "內容"}},
+		{"comment direct body flag", []string{"comment", "--repo", "a/b", "--body", "內容", "1"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+				t.Errorf("%s：未帶 --yes 不得發出請求（%s %s）", tc.name, r.Method, r.URL.Path)
+			})
+			_, stderr, code := run(tc.args...)
+			if code != 2 {
+				t.Errorf("%s 未帶 --yes 應回 2，得到 %d", tc.name, code)
+			}
+			if !strings.Contains(stderr, "--yes") {
+				t.Errorf("%s 錯誤訊息應提及 --yes，得到：%s", tc.name, stderr)
+			}
+		})
+	}
+}
+
+// TestPullsApprovePostsReview 驗證 pulls approve --yes：
+// POST /repos/{owner}/{repo}/pulls/{n}/reviews，payload 帶 event=APPROVED 與意見；
+// 意見可用位置參數（tea 相容：teai pulls approve --repo a/b <n> "驗證通過。"）。
+func TestPullsApprovePostsReview(t *testing.T) {
+	var gotMethod, gotPath, gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod, gotPath = r.Method, r.URL.Path
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"ID":42,"number":13,"state":"APPROVED","body":"驗證通過。","submitted_at":"t","user":{"login":"max"}}`)
+	})
+	stdout, _, code := run("pulls", "approve", "--repo", "alterminal/teai", "--yes", "13", "驗證通過。")
+	if code != 0 {
+		t.Fatalf("approve --yes 應回 0，得到 %d", code)
+	}
+	if gotMethod != "POST" || !strings.HasSuffix(gotPath, "/repos/alterminal/teai/pulls/13/reviews") {
+		t.Errorf("應 POST /repos/alterminal/teai/pulls/13/reviews，得到 %s %s", gotMethod, gotPath)
+	}
+	if !strings.Contains(gotBody, `"event":"APPROVED"`) || !strings.Contains(gotBody, "驗證通過。") {
+		t.Errorf("body 應含 event=APPROVED 與意見，得到：%s", gotBody)
+	}
+	if !strings.Contains(stdout, `"state":"APPROVED"`) {
+		t.Errorf("輸出應含 APPROVED，得到：%s", stdout)
+	}
+}
+
+// TestPullsClosePatchesState 驗證 pulls close --yes：
+// PATCH /repos/{owner}/{repo}/pulls/{n}，payload 帶 state=closed。
+func TestPullsClosePatchesState(t *testing.T) {
+	var gotMethod, gotPath, gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod, gotPath = r.Method, r.URL.Path
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"number":13,"title":"PR","state":"closed","html_url":"https://x/13"}`)
+	})
+	_, _, code := run("pulls", "close", "--repo", "alterminal/teai", "--yes", "13")
+	if code != 0 {
+		t.Fatalf("close --yes 應回 0，得到 %d", code)
+	}
+	if gotMethod != "PATCH" || !strings.HasSuffix(gotPath, "/repos/alterminal/teai/pulls/13") {
+		t.Errorf("應 PATCH /repos/alterminal/teai/pulls/13，得到 %s %s", gotMethod, gotPath)
+	}
+	if !strings.Contains(gotBody, `"state":"closed"`) {
+		t.Errorf("body 應含 state=closed，得到：%s", gotBody)
+	}
+}
+
+// TestCommentDirectPostsComment 驗證通用 comment（tea 相容形式）：
+// --repo a/b <number> <body> --yes → POST issues/<n>/comments，
+// issue 與 PR 共用（不需要 type 旗標）。
+func TestCommentDirectPostsComment(t *testing.T) {
+	var gotMethod, gotPath, gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod, gotPath = r.Method, r.URL.Path
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"body":"已依評論更新：commit abc1234。","created_at":"t","user":{"login":"max"}}`)
+	})
+	stdout, _, code := run("comment", "--repo", "alterminal/teai", "--yes", "13", "已依評論更新：commit abc1234。")
+	if code != 0 {
+		t.Fatalf("comment --yes 應回 0，得到 %d", code)
+	}
+	if gotMethod != "POST" || !strings.HasSuffix(gotPath, "/repos/alterminal/teai/issues/13/comments") {
+		t.Errorf("應 POST /repos/alterminal/teai/issues/13/comments，得到 %s %s", gotMethod, gotPath)
+	}
+	if !strings.Contains(gotBody, "已依評論更新：commit abc1234。") {
+		t.Errorf("body 應含留言內容，得到：%s", gotBody)
+	}
+	if !strings.Contains(stdout, "已依評論更新") {
+		t.Errorf("輽出應含留言，得到：%s", stdout)
+	}
+}
+
+// TestCommentDirectBodyFlag 驗證 comment 也接受 --body（teai 慣用），
+// 且位置參數與 --body 同時存在時位置參數優先。
+func TestCommentDirectBodyFlag(t *testing.T) {
+	var gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"body":"x","created_at":"t","user":{"login":"max"}}`)
+	})
+	if _, _, code := run("comment", "--repo", "a/b", "--body", "旗標版", "--yes", "5"); code != 0 {
+		t.Fatalf("--body 版應回 0，得到 %d", code)
+	}
+	if !strings.Contains(gotBody, "旗標版") {
+		t.Errorf("body 應為 --body 值，得到：%s", gotBody)
+	}
+	if _, _, code := run("comment", "--repo", "a/b", "--body", "旗標版", "--yes", "5", "位置版"); code != 0 {
+		t.Fatalf("位置參數版應回 0，得到 %d", code)
+	}
+	if !strings.Contains(gotBody, "位置版") || strings.Contains(gotBody, "旗標版") {
+		t.Errorf("位置參數應優先於 --body，得到：%s", gotBody)
+	}
+}
+
+// TestIssuesListLabelsFilter 驗證 issues list --labels：
+// 查詢參數帶 labels=a,b（多標籤 AND 語義），輸出仍為 JSON 陣列。
+func TestIssuesListLabelsFilter(t *testing.T) {
+	var gotQuery string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotQuery = r.URL.RawQuery
+		fmt.Fprint(w, `[{"number":9,"title":"标签過濾","state":"open","user":{"login":"ceo"},"updated_at":"t"}]`)
+	})
+	stdout, _, code := run("issues", "list", "--repo", "alterminal/teai", "--labels", "bug, help wanted")
+	if code != 0 {
+		t.Fatalf("--labels 應回 0，得到 %d", code)
+	}
+	if !strings.Contains(gotQuery, "labels=bug%2Chelp+wanted") && !strings.Contains(gotQuery, "labels=bug%2C+help+wanted") {
+		t.Errorf("查詢應帶 labels=bug,help+wanted（URL 編碼後），得到 %q", gotQuery)
+	}
+	if !strings.Contains(stdout, `"number":9`) {
+		t.Errorf("輽出應含過濾後的 issue，得到：%s", stdout)
+	}
+}
+
+// TestPullsCheckoutSameRepo 驗證 checkout 同倉庫分支：
+// 在 --dir 的 git 工作樹 fetch origin <ref> 並 checkout -B <ref>。
+func TestPullsCheckoutSameRepo(t *testing.T) {
+	// 建立裸「origin」倉庫與分支 feat/x。
+	origin := t.TempDir()
+	gitRun := func(args ...string) {
+		t.Helper()
+		cmd := exec.Command("git", args...)
+		cmd.Dir = origin
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("git %v 失敗：%v\n%s", args, err, out)
+		}
+	}
+	gitRun("init", "-q", "-b", "main", ".")
+	gitRun("config", "user.email", "t@t")
+	gitRun("config", "user.name", "t")
+	gitRun("commit", "--allow-empty", "-m", "init")
+	gitRun("checkout", "-q", "-b", "feat/x")
+	gitRun("commit", "--allow-empty", "-m", "x1")
+	gitRun("checkout", "-q", "main")
+	// 工作樹 clone 自 origin（file:// 協定讓 fetch 生效）。
+	work := t.TempDir()
+	if out, err := exec.Command("git", "clone", "-q", "file://"+origin, work).CombinedOutput(); err != nil {
+		t.Fatalf("clone 失敗：%v\n%s", err, out)
+	}
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"number":7,"title":"PR","state":"open","head":{"ref":"feat/x","repo":{"full_name":"alterminal/teai","clone_url":"https://gitea.alterminal.com/alterminal/teai.git"}},"base":{"ref":"main"}}`)
+	})
+	stdout, _, code := run("pulls", "checkout", "--repo", "alterminal/teai", "--dir", work, "7")
+	if code != 0 {
+		t.Fatalf("checkout 應回 0，得到 %d", code)
+	}
+	brOut, err := exec.Command("git", "-C", work, "branch", "--show-current").Output()
+	if err != nil || strings.TrimSpace(string(brOut)) != "feat/x" {
+		t.Errorf("工作樹應在 feat/x，得到 %q（err=%v）", string(brOut), err)
+	}
+	if !strings.Contains(stdout, `"branch":"feat/x"`) {
+		t.Errorf("輽出應含 branch 欄位，得到：%s", stdout)
+	}
+}
+
+// TestPullsCheckoutCrossRepo 驗證 checkout 跨倉庫 head：
+// 需 --dir（新目錄），git clone --branch <ref> <clone_url> <dir>。
+func TestPullsCheckoutCrossRepo(t *testing.T) {
+	// 假伺服器同時當 git remote：把 PR head 指向本地裸倉庫。
+	origin := t.TempDir()
+	gitRun := func(args ...string) {
+		t.Helper()
+		cmd := exec.Command("git", args...)
+		cmd.Dir = origin
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("git %v 失敗：%v\n%s", args, err, out)
+		}
+	}
+	gitRun("init", "-q", "-b", "main", "--bare", ".")
+	seed := t.TempDir()
+	cmd := exec.Command("git", "clone", "-q", "file://"+origin, seed)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("clone seed 失敗：%v\n%s", err, out)
+	}
+	for _, args := range [][]string{
+		{"config", "user.email", "t@t"},
+		{"config", "user.name", "t"},
+		{"commit", "--allow-empty", "-m", "init"},
+		{"checkout", "-q", "-b", "feat/y"},
+		{"commit", "--allow-empty", "-m", "y1"},
+		{"push", "-q", "origin", "feat/y"},
+	} {
+		c := exec.Command("git", args...)
+		c.Dir = seed
+		if out, err := c.CombinedOutput(); err != nil {
+			t.Fatalf("git %v 失敗：%v\n%s", args, err, out)
+		}
+	}
+	target := filepath.Join(t.TempDir(), "wk")
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, `{"number":8,"title":"PR","state":"open","head":{"ref":"feat/y","repo":{"full_name":"other/fork","clone_url":"file://%s"}},"base":{"ref":"main"}}`, origin)
+	})
+	stdout, _, code := run("pulls", "checkout", "--repo", "alterminal/teai", "--dir", target, "8")
+	if code != 0 {
+		t.Fatalf("checkout 跨倉庫應回 0，得到 %d", code)
+	}
+	brOut, err := exec.Command("git", "-C", target, "branch", "--show-current").Output()
+	if err != nil || strings.TrimSpace(string(brOut)) != "feat/y" {
+		t.Errorf("工作樹應在 feat/y，得到 %q（err=%v）", string(brOut), err)
+	}
+	if !strings.Contains(stdout, `"repo":"other/fork"`) {
+		t.Errorf("輽出應含 head 倉庫，得到：%s", stdout)
+	}
+}
+
+// TestPullsCheckoutCrossRepoRequiresDir 驗證跨倉庫 head 未帶 --dir：
+// 用法錯誤（exit 2）。
+func TestPullsCheckoutCrossRepoRequiresDir(t *testing.T) {
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"number":8,"title":"PR","state":"open","head":{"ref":"feat/y","repo":{"full_name":"other/fork","clone_url":"https://x/y.git"}},"base":{"ref":"main"}}`)
+	})
+	_, stderr, code := run("pulls", "checkout", "--repo", "alterminal/teai", "8")
+	if code != 2 {
+		t.Errorf("跨倉庫 head 未帶 --dir 應回 2，得到 %d", code)
+	}
+	if !strings.Contains(stderr, "--dir") {
+		t.Errorf("錯誤訊息應提及 --dir，得到：%s", stderr)
+	}
+}
+
+// TestIssuesCommentPositionalBody 驗證 issues comment 也吃位置參數留言
+// （tea comment 相容语法在子命令下的行為）。
+func TestIssuesCommentPositionalBody(t *testing.T) {
+	var gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"body":"x","created_at":"t","user":{"login":"max"}}`)
+	})
+	if _, _, code := run("issues", "comment", "--repo", "a/b", "--yes", "3", "多餘", "引數", "串留言"); code != 0 {
+		t.Fatalf("issues comment 位置參數應回 0，得到 %d", code)
+	}
+	if !strings.Contains(gotBody, "多餘 引數 串留言") {
+		t.Errorf("尾端引數應串成留言，得到：%s", gotBody)
+	}
+}
+
+var _ = os.Getenv // 保持 import 一致（checkout 測試用 exec，此檔亦引用 os 於需要時）

internal/cli/stalled_commands_test.go

@@ -46,6 +46,9 @@ func (s *stubStalledSource) TryGetIssue(owner, repo string, number int64) (workf
 	i, ok := s.issues[owner+"/"+repo][number]
 	return i, ok, nil
 }
+func (s *stubStalledSource) IssueTimeline(owner, repo string, number int64) ([]workflow.TimelineEvent, error) {
+	return nil, nil
+}
 func (s *stubStalledSource) GetIssue(owner, repo string, number int64) (workflow.Issue, error) {
 	if s.getErr != nil {
 		return workflow.Issue{}, s.getErr
@@ -114,6 +117,24 @@ func TestWiringStalled(t *testing.T) {
 	}
 }
 
+// TestWiringStalledEmpty 驗證 stalled 無任何條目時輸出 []、exit 0（#37）。
+func TestWiringStalledEmpty(t *testing.T) {
+	newStubStalledEnv(t, &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {}},
+		issues:   map[string]map[int64]workflow.Issue{},
+		comments: map[string][]workflow.Comment{},
+	}, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled")
+	if code != 0 {
+		t.Fatalf("stalled 空情境應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("stalled 無條目應輸出 []，得到 %q", stdout)
+	}
+}
+
 // TestWiringStalledHoursFlag 驗證 --hours 覆寫門檻與非正數被攔。
 func TestWiringStalledHoursFlag(t *testing.T) {
 	freeze := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
@@ -157,7 +178,7 @@ func TestWiringXrefs(t *testing.T) {
 	src := newStubStalledData()
 	src.issues["alterminal/agents"][1] = workflow.Issue{
 		Number: 1, Title: "父項", State: "open",
-		Body: "子項：agents#2",
+		Body:       "子項：agents#2",
 		Repository: &workflow.Repository{FullName: "alterminal/agents"},
 	}
 	src.issues["alterminal/agents"][2] = workflow.Issue{
@@ -185,7 +206,7 @@ func TestWiringXrefsEmpty(t *testing.T) {
 	src := newStubStalledData()
 	src.issues["alterminal/agents"][1] = workflow.Issue{
 		Number: 1, Title: "無引用", State: "open",
-		Body: "沒有任何引用",
+		Body:       "沒有任何引用",
 		Repository: &workflow.Repository{FullName: "alterminal/agents"},
 	}
 	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))

internal/dailyops/dailyops.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"net/url"
 	"strconv"
+	"strings"
 
 	"gitea.alterminal.com/alterminal/teai/internal/gitea"
 )
@@ -119,8 +120,10 @@ type Pull struct {
 // pullRef 是 PR 的 head／base 參照。
 type pullRef struct {
 	Ref  string `json:"ref"`
+	SHA  string `json:"sha"`
 	Repo *struct {
 		FullName string `json:"full_name"`
+		CloneURL string `json:"clone_url"`
 	} `json:"repo"`
 }
 
@@ -165,14 +168,18 @@ func repoPath(owner, repo string) string {
 }
 
 // ListIssues 列出倉庫 issues。state：open｜closed｜all（預設 open）；
-// type=issues 排除 PR（Gitea 的 issues 端點會連 PR 一起回）。
+// labels 非空時以逗號連接傳給 API 的 labels 參數（Gitea labels 過濾，
-func (o *Ops) ListIssues(ctx context.Context, owner, repo, state string) ([]Issue, error) {
+// 多標籤為 AND 語義）；type=issues 排除 PR（Gitea 的 issues 端點會連 PR 一起回）。
+func (o *Ops) ListIssues(ctx context.Context, owner, repo, state string, labels []string) ([]Issue, error) {
 	if state == "" {
 		state = "open"
 	}
+	// state 一律明確傳給 API：issues／milestones 端點省略 state 時預設
+	// open（#33），closed 項目會漏列；all 也不能省略。
 	extra := url.Values{}
-	if state != "all" {
+	extra.Set("state", state)
-		extra.Set("state", state)
+	if len(labels) > 0 {
+		extra.Set("labels", strings.Join(labels, ","))
 	}
 	// type=issues：排除 PR（PR 在此端點帶 pull_request 欄位）。
 	extra.Set("type", "issues")
@@ -246,10 +253,10 @@ func (o *Ops) ListPulls(ctx context.Context, owner, repo, state string) ([]Pull,
 	if state == "" {
 		state = "open"
 	}
+	// state 一律明確傳給 API：pulls 端點省略 state 時雖回全部，仍明確
+	// 帶上，避免依賴端點預設值（#33）。
 	extra := url.Values{}
-	if state != "all" {
+	extra.Set("state", state)
-		extra.Set("state", state)
-	}
 	var pulls []Pull
 	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/pulls", gitea.ListOptions{Extra: extra}, &pulls); err != nil {
 		return nil, err
@@ -259,12 +266,93 @@ func (o *Ops) ListPulls(ctx context.Context, owner, repo, state string) ([]Pull,
 
 // GetPull 取得單一 PR。
 func (o *Ops) GetPull(ctx context.Context, owner, repo string, number int64) (*Pull, error) {
-	var pull Pull
+	var pr Pull
 	path := repoPath(owner, repo) + "/pulls/" + strconv.FormatInt(number, 10)
-	if err := o.Client.GetJSON(ctx, path, &pull); err != nil {
+	if err := o.Client.GetJSON(ctx, path, &pr); err != nil {
 		return nil, err
 	}
-	return &pull, nil
+	return &pr, nil
+}
+
+// Review 是 pull request 審核的精簡欄位。
+type Review struct {
+	ID        int64  `json:"ID"`
+	Number    int64  `json:"number"`
+	State     string `json:"state"`
+	Body      string `json:"body"`
+	Submitted string `json:"submitted_at"`
+	User      *User  `json:"user"`
+}
+
+// Author 回傳審核者帳號。
+func (r *Review) Author() string { return r.User.Name() }
+
+// ApprovePull 核准 PR（POST /repos/{owner}/{repo}/pulls/{n}/reviews，event=APPROVED）。
+// body 是審核意見，可為空。
+func (o *Ops) ApprovePull(ctx context.Context, owner, repo string, number int64, body string) (*Review, error) {
+	payload := map[string]any{
+		"event": "APPROVED",
+		"body":  body,
+	}
+	var review Review
+	path := repoPath(owner, repo) + "/pulls/" + strconv.FormatInt(number, 10) + "/reviews"
+	if err := o.Client.DoJSON(ctx, "POST", path, "", payload, &review); err != nil {
+		return nil, err
+	}
+	return &review, nil
+}
+
+// ClosePull 關閉 PR 不合併（PATCH /repos/{owner}/{repo}/pulls/{n}，state=closed）。
+func (o *Ops) ClosePull(ctx context.Context, owner, repo string, number int64) (*Pull, error) {
+	payload := map[string]any{"state": "closed"}
+	var pr Pull
+	path := repoPath(owner, repo) + "/pulls/" + strconv.FormatInt(number, 10)
+	if err := o.Client.DoJSON(ctx, "PATCH", path, "", payload, &pr); err != nil {
+		return nil, err
+	}
+	return &pr, nil
+}
+
+// HeadInfo 是 PR head 參照的完整資訊（checkout 用：同倉庫分支 or 跨倉庫 clone 網址）。
+type HeadInfo struct {
+	// Ref 是 head 分支名。
+	Ref string
+	// Repo 是 head 所屬倉庫（owner/name）；與目標倉庫相同時為空。
+	Repo string
+	// CloneURL 是 head 倉庫的 https clone 網址；同倉庫時為空。
+	CloneURL string
+	// SHA 是 head commit（暫不使用，保留給未來 reset/rebase 用）。
+	SHA string
+}
+
+// PullHeadInfo 取得 PR 的 head 資訊。同倉庫分支 → Repo/CloneURL 為空、只剩 Ref；
+// 跨倉庫 fork → Ref+Repo+CloneURL 齊備，checkout 改以 clone --branch Ref CloneURL。
+func (o *Ops) PullHeadInfo(ctx context.Context, owner, repo string, number int64) (*HeadInfo, error) {
+	pr, err := o.GetPull(ctx, owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	info := &HeadInfo{Ref: pr.HeadRef()}
+	if pr.Head != nil {
+		info.SHA = pr.Head.SHA
+		if pr.Head.Repo != nil {
+			full := pr.Head.Repo.FullName
+			same := full != "" && full == owner+"/"+repo
+			if !same {
+				info.Repo = full
+				info.CloneURL = pr.Head.Repo.CloneURL
+			}
+		}
+	}
+	return info, nil
+}
+
+// String 依 head 來源輸出人類可讀描述（輸出用）。
+func (h *HeadInfo) String() string {
+	if h.Repo != "" {
+		return h.Repo + "#" + h.Ref
+	}
+	return h.Ref
 }
 
 // CreatePull 建立 PR。
@@ -320,10 +408,10 @@ func (o *Ops) ListMilestones(ctx context.Context, owner, repo, state string) ([]
 	if state == "" {
 		state = "open"
 	}
+	// state 一律明確傳給 API：milestones 端點省略 state 時預設 open
+	// （#33），closed 項目會漏列。
 	extra := url.Values{}
-	if state != "all" {
+	extra.Set("state", state)
-		extra.Set("state", state)
-	}
 	var ms []Milestone
 	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/milestones", gitea.ListOptions{Extra: extra}, &ms); err != nil {
 		return nil, err

internal/workflow/giteaapi.go

@@ -150,6 +150,19 @@ func (a *APIClient) TryGetIssue(owner, repo string, number int64) (Issue, bool,
 	return issue, true, nil
 }
 
+// IssueTimeline 回傳 issue 的 timeline 事件（Source 面向；對應 gitea.py
+// _direct_last_activity 拉取的 repos/{o}/{r}/issues/{n}/timeline）。
+// 分頁由 ListAll 處理（與 gitea.py api_get_list 的 limit=50 逐頁一致）。
+func (a *APIClient) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	var events []TimelineEvent
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10) + "/timeline"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &events); err != nil {
+		return nil, err
+	}
+	return events, nil
+}
+
 // MyOrganizations 委派 ListOrgs（Source 面向）。
 func (a *APIClient) MyOrganizations() ([]string, error) { return a.ListOrgs() }
 

internal/workflow/stalled_entry_test.go

@@ -1,8 +1,10 @@
 // stalled_entry_test.go — RunStalled／ResolveIssueXrefs 高階入口的單元測試
-//（#7 CLI 接線；資料源注入假實作，離線可測）。
+// （#7 CLI 接線；資料源注入假實作，離線可測）。
 package workflow
 
 import (
+	"errors"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
@@ -14,10 +16,22 @@ type fakeStalledSource struct {
 	username string
 	// getIssueErr 模擬 GetIssue 失敗（xrefs 的 404 路徑）。
 	getIssueErr error
+	// timeline[owner/repo/number]：issue timeline 事件（無則回空清單，
+	// 模擬 API 成功但無事件；timelineErr 模擬拉取失敗）。
+	timeline    map[string][]TimelineEvent
+	timelineErr map[string]error
 }
 
 func (f *fakeStalledSource) CurrentUser() (string, error) { return f.username, nil }
 
+func (f *fakeStalledSource) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	key := fmt.Sprintf("%s/%s/%d", owner, repo, number)
+	if err := f.timelineErr[key]; err != nil {
+		return nil, err
+	}
+	return f.timeline[key], nil
+}
+
 func (f *fakeStalledSource) GetIssue(owner, repo string, number int64) (Issue, error) {
 	if f.getIssueErr != nil {
 		return Issue{}, f.getIssueErr
@@ -38,7 +52,7 @@ func (e *notFoundError) Error() string { return "404" }
 func newStalledFixture() *fakeStalledSource {
 	return &fakeStalledSource{
 		fakeSource: &fakeSource{
-			orgs:  []string{"alterminal"},
+			orgs: []string{"alterminal"},
 			repos: map[string][]Repo{"alterminal": {
 				{Name: "agents", HasPullRequests: boolPtr(true)},
 				{Name: "teai", HasPullRequests: boolPtr(true)},
@@ -229,3 +243,92 @@ func TestResolveIssueXrefsEmptyBody(t *testing.T) {
 	}
 	_ = time.Now // time 僅供 iso/at 使用；保留 import。
 }
+
+// TestRunStalledChildXrefRefresh 回歸測試（agents #38、teai #34）：
+// 子項 updated_at 被跨 issue 引用（comment_ref）刷新時，子項有效活動
+// 應經 directLastActivity 排除引用事件後採計，父追蹤項的停滯時鐘
+// 不被虛假刷新。
+func TestRunStalledChildXrefRefresh(t *testing.T) {
+	src := newStalledFixture()
+	// 子項 teai#2：直接活動為 created(-500) 與留言(-90)，
+	// updated_at 卻是 -10（他處留言提及刷新）。
+	issue := src.issues["alterminal/teai"][2]
+	issue.UpdatedAt = iso(-10)
+	src.issues["alterminal/teai"][2] = issue
+	// timeline：-10 的刷新是 comment_ref（引用事件，排除），
+	// -90 有直接事件（label）可對應 → 有效活動 -90。
+	src.timeline = map[string][]TimelineEvent{
+		"alterminal/teai/2": {
+			{Type: "label", CreatedAt: iso(-90)},
+			{Type: "comment_ref", CreatedAt: iso(-10)},
+		},
+	}
+	// 門檻 1 小時：父項 last_activity 取子項有效活動 -90 → 停滯 1.5h 列入；
+	// 若誤採被刷新的 -10，父項與子項都不會列入。
+	items, err := RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 2 {
+		t.Fatalf("應有兩筆（父追蹤項＋子項），得到 %d：%+v", len(items), items)
+	}
+	var parent *Item
+	for i := range items {
+		if items[i].Repo == "alterminal/agents" && items[i].Number == 1 {
+			parent = &items[i]
+		}
+	}
+	if parent == nil {
+		t.Fatalf("找不到 agents#1：%+v", items)
+	}
+	if parent.Reason != "parent-tracking" {
+		t.Fatalf("agents#1 應為 parent-tracking，得到 %s", parent.Reason)
+	}
+	if parent.StalledHours != 1.5 {
+		t.Fatalf("父項停滯應以子項有效活動（-90m → 1.5h）計，得到 %.1f", parent.StalledHours)
+	}
+}
+
+// TestRunStalledTimelineAllXrefFallback 回歸測試（agents #40、teai #34）：
+// issue 自身 updated_at 晚於全部已知直接活動、且 timeline 全為引用事件時，
+// 回退已知直接活動的最晚時刻（不高估活動、不低估停滯）；
+// timeline 拉取失敗則保守沿用 updated_at。
+func TestRunStalledTimelineAllXrefFallback(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "") // 移除父項引用，teai#2 獨立判定
+	delete(src.comments, "alterminal/teai/2")
+	// agents#1 給一則近期留言，避免本身停滯（10h）干擾本測試的斷言。
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-10), User: &User{UserName: "alex"}},
+	}
+	// teai#2：僅有 created(-500) 此一已知直接活動，
+	// updated_at -10 完全由他處提及刷新。
+	issue := src.issues["alterminal/teai"][2]
+	issue.UpdatedAt = iso(-10)
+	src.issues["alterminal/teai"][2] = issue
+	// 情境一：timeline 全為引用事件 → 回退 knownMax（created -500）
+	// → 停滯 8.3h，超過預設門檻 4h，列入。
+	src.timeline = map[string][]TimelineEvent{
+		"alterminal/teai/2": {{Type: "issue_ref", CreatedAt: iso(-10)}},
+	}
+	items, err := RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 1 || items[0].Number != 2 {
+		t.Fatalf("全引用事件應回退直接活動 → teai#2 停滯 8.3h 列入，得到 %+v", items)
+	}
+	if items[0].StalledHours != 8.3 {
+		t.Fatalf("回退 created(-500) → 停滯應 8.3h，得到 %.1f", items[0].StalledHours)
+	}
+	// 情境二：timeline 拉取失敗 → 保守沿用 updated_at(-10) → 0.2h 未達門檻，不列入。
+	src.timeline = nil
+	src.timelineErr = map[string]error{"alterminal/teai/2": errors.New("boom")}
+	items, err = RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("timeline 失敗應保守沿用 updated_at → 不列入，得到 %+v", items)
+	}
+}

internal/workflow/workflow.go

@@ -30,6 +30,11 @@ const (
 	NudgeCooldownHours = 24.0
 )
 
+// xrefTimelineTypes 對應 gitea.py 的 XREF_TIMELINE_TYPES：他處留言／issue
+// 提及本編號時產生的 timeline 引用事件。這類事件會刷新 updated_at，但不是
+// 本 issue 的直接活動，directLastActivity 會予以排除（agents issue #34）。
+var xrefTimelineTypes = map[string]bool{"comment_ref": true, "issue_ref": true}
+
 // xrefPattern 對應 gitea.py 的 XREF_PATTERN：#N、repo#N、owner/repo#N。
 //
 // 前面不得是文數字／底線／斜線（避免切進 alterminal/bear#47 的後半段）；
@@ -149,6 +154,9 @@ type Source interface {
 	IssueComments(owner, repo string, number int64) ([]Comment, error)
 	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
 	TryGetIssue(owner, repo string, number int64) (Issue, bool, error)
+	// IssueTimeline 回傳 issue 的 timeline 事件（GET /repos/{o}/{r}/issues/{n}/timeline，
+	// 分頁）。directLastActivity 用來排除跨 issue 引用事件（agents issue #34）。
+	IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error)
 }
 
 // iterXrefs 產出文字中的 (prefix, number) 配對（對應 _iter_issue_xrefs）。
@@ -268,8 +276,11 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 		if pcOK && ccOK && !childCreated.After(parentCreated) {
 			continue // 上行引用（父項回指更早或同時的 issue）；時間未知則不排除
 		}
+		// 子項的直接活動：created_at、state 變更（closed_at）、留言（agents #32）。
+		// 原始 updated_at 不放入已知活動，另經 directLastActivity 核對後採計
+		//（與 considerIssue／considerPull 對本 issue 自身的處理同構）。
 		var ms []time.Time
-		if m, ok := parseMoment(child.UpdatedAt); ok {
+		if m, ok := parseMoment(child.CreatedAt); ok {
 			ms = append(ms, m)
 		}
 		if m, ok := parseMoment(child.ClosedAt); ok {
@@ -282,6 +293,14 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 				}
 			}
 		}
+		if childUpdated, ok := parseMoment(child.UpdatedAt); ok {
+			// 子項 updated_at 可能被 comment_ref／issue_ref 引用事件刷新
+			//（agents #38）：走與本 issue 自身相同的 directLastActivity 排除
+			// 邏輯（同源判定，不漂移）；timeline 失敗時保守沿用 updated_at。
+			if d, ok := directLastActivity(src, t.Owner, t.Repo, t.Number, childUpdated, true, ms); ok {
+				ms = append(ms, d)
+			}
+		}
 		var last *string
 		if len(ms) > 0 {
 			latest := maxTime(ms)
@@ -302,6 +321,71 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 	return moments, children
 }
 
+// TimelineEvent 是 issue timeline 的單一事件（僅取判斷所需欄位；
+// 對應 gitea.py _direct_last_activity 讀取的 timeline 物件）。
+type TimelineEvent struct {
+	Type      string `json:"type"`
+	CreatedAt string `json:"created_at"`
+}
+
+// directLastActivity 排除跨 issue 引用事件後，本 issue 的最後直接活動時刻
+// （對應 gitea.py 的 _direct_last_activity；agents issues #34/#38/#40）。
+//
+// 他處留言／issue 提及本編號（comment_ref／issue_ref）也會刷新 updated_at，
+// 直接採用會虛假刷新停滯時鐘（false negative）並低估 stalled_hours。
+// updated_at 不晚於已知直接活動（留言、created_at、#32 納入的子項活動）時，
+// updated_at 本身可信，不必多打一次 timeline API；只有 updated_at 晚於全部
+// 已知活動時才拉 timeline 核對：排除引用類事件後取最晚事件時刻；若最晚的
+// 都是引用事件（本 issue 無直接活動可對應 updated_at），則回退已知直接活動
+// 的最晚時刻（agents #40）。timeline 拉取失敗時沿用 updated_at（不中斷掃描、
+// 寧可少報不誤報缺失活動）。
+func directLastActivity(src Source, org, repo string, number int64, updatedAt time.Time, hasUpdated bool, known []time.Time) (time.Time, bool) {
+	if !hasUpdated {
+		return time.Time{}, false
+	}
+	var knownMax *time.Time
+	for i := range known {
+		if known[i].IsZero() {
+			continue
+		}
+		if knownMax == nil || known[i].After(*knownMax) {
+			m := known[i]
+			knownMax = &m
+		}
+	}
+	if knownMax == nil || !updatedAt.After(*knownMax) {
+		return updatedAt, true
+	}
+	timeline, err := src.IssueTimeline(org, repo, number)
+	if err != nil {
+		return updatedAt, true
+	}
+	var moments []time.Time
+	for _, e := range timeline {
+		if xrefTimelineTypes[e.Type] {
+			continue
+		}
+		if m, ok := parseMoment(e.CreatedAt); ok {
+			moments = append(moments, m)
+		}
+	}
+	if len(moments) == 0 {
+		// timeline 全為引用事件：updated_at 完全由他處提及刷新，本 issue 沒有
+		// 可對應的直接活動。回退已知直接活動的最晚時刻，避免把被刷新的
+		// updated_at 當活動、低估停滯時數（agents #40）；連已知活動都沒有時才
+		// 保守沿用 updated_at（不中斷掃描、寧可少報不誤報缺失活動）。
+		if knownMax != nil {
+			return *knownMax, true
+		}
+		return updatedAt, true
+	}
+	latest := maxTime(moments)
+	if latest.Before(updatedAt) {
+		return latest, true
+	}
+	return updatedAt, true
+}
+
 func maxTime(ts []time.Time) time.Time {
 	best := ts[0]
 	for _, t := range ts[1:] {
@@ -382,7 +466,7 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 				if err != nil {
 					continue
 				}
-				if item, ok := considerPull(pr, comments, username, threshold, now); ok {
+				if item, ok := considerPull(src, org, r.Name, pr, comments, username, threshold, now); ok {
 					items = append(items, item)
 				}
 			}
@@ -398,19 +482,27 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 func considerIssue(src Source, org, repo string, issue Issue, comments []Comment, username string, threshold float64, now time.Time, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (Item, bool) {
 	childMoments, children := childActivity(src, org, repo, issue, comments, myOrgs, orgRepos)
 	assignees := AssigneeNames(&issue)
-	var moments []time.Time
+	// 已知直接活動：留言、created_at、#32 納入的子項活動。
-	if m, ok := parseMoment(issue.UpdatedAt); ok {
+	var known []time.Time
-		moments = append(moments, m)
-	}
 	if m, ok := parseMoment(issue.CreatedAt); ok {
-		moments = append(moments, m)
+		known = append(known, m)
 	}
 	for _, c := range comments {
 		if m, ok := parseMoment(c.CreatedAt); ok {
-			moments = append(moments, m)
+			known = append(known, m)
 		}
 	}
-	moments = append(moments, childMoments...)
+	known = append(known, childMoments...)
+	// 跨 issue 引用（comment_ref／issue_ref）也會刷新 updated_at（agents #34）：
+	// updated_at 晚於全部已知直接活動時，先排除引用事件核對後才採用，
+	// 避免停滯時鐘被虛假刷新或低估 stalled_hours。
+	var moments []time.Time
+	if m, ok := parseMoment(issue.UpdatedAt); ok {
+		if d, ok2 := directLastActivity(src, org, repo, issue.issueNumber(), m, ok, known); ok2 {
+			moments = append(moments, d)
+		}
+	}
+	moments = append(moments, known...)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -455,21 +547,28 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 }
 
 // considerPull 對單一 PR 套用停滯判定（對應 _consider 的 pull 分支）。
-func considerPull(pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
+func considerPull(src Source, org, repo string, pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
 	reviewers := ReviewerNames(&pr)
 	author := pr.Author()
-	var moments []time.Time
+	// 已知直接活動：留言、created_at。
-	if m, ok := parseMoment(pr.UpdatedAt); ok {
+	var known []time.Time
-		moments = append(moments, m)
-	}
 	if m, ok := parseMoment(pr.CreatedAt); ok {
-		moments = append(moments, m)
+		known = append(known, m)
 	}
 	for _, c := range comments {
 		if m, ok := parseMoment(c.CreatedAt); ok {
-			moments = append(moments, m)
+			known = append(known, m)
 		}
 	}
+	// 跨 issue 引用也會刷新 PR 的 updated_at（agents #34）：與 issue 同一道
+	// directLastActivity 排除邏輯（同源判定，不漂移）。
+	var moments []time.Time
+	if m, ok := parseMoment(pr.UpdatedAt); ok {
+		if d, ok2 := directLastActivity(src, org, repo, pr.Number, m, ok, known); ok2 {
+			moments = append(moments, d)
+		}
+	}
+	moments = append(moments, known...)
 	if len(moments) == 0 {
 		return Item{}, false
 	}

internal/workflow/workflow_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -28,6 +29,8 @@ type fakeSource struct {
 	pulls map[string][]PullRequest
 	// comments[owner/repo/number]
 	comments map[string][]Comment
+	// timelines[owner/repo/number]：issue timeline 事件（nil → 空 timeline）。
+	timelines map[string][]TimelineEvent
 }
 
 func (f *fakeSource) MyOrganizations() ([]string, error) { return f.orgs, nil }
@@ -41,6 +44,8 @@ func (f *fakeSource) OpenIssues(owner, repo string) ([]Issue, error) {
 	for _, i := range f.issues[owner+"/"+repo] {
 		out = append(out, i)
 	}
+	// 對齊真實 API：issues 依 id（=number）遞增回傳，消除 map 迭代隨機性。
+	sort.Slice(out, func(a, b int) bool { return out[a].Number < out[b].Number })
 	return out, nil
 }
 
@@ -52,6 +57,10 @@ func (f *fakeSource) IssueComments(owner, repo string, number int64) ([]Comment,
 	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
 }
 
+func (f *fakeSource) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	return f.timelines[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
+}
+
 func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
 	i, ok := f.issues[owner+"/"+repo][number]
 	if !ok {
@@ -314,6 +323,13 @@ func TestScanStalledParentTrackingNotChild(t *testing.T) {
 			},
 		},
 	}
+	// timeline：#47 的 updated_at 對應直接事件（assignees）、#39 對應 label
+	//（agents #34 後 updated_at 需經 timeline 核對才採計；直接事件可對應 → 採用）。
+	// 必須在 ScanStalled 之前設定——掃描當下讀不到的事後修改無效。
+	src.timelines = map[string][]TimelineEvent{
+		"alterminal/teai/47": {{Type: "assignees", CreatedAt: iso(-600)}},
+		"alterminal/teai/39": {{Type: "label", CreatedAt: iso(-60)}},
+	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -515,6 +531,9 @@ func (e errSource) IssueComments(string, string, int64) ([]Comment, error) {
 func (e errSource) TryGetIssue(string, string, int64) (Issue, bool, error) {
 	return Issue{}, false, errors.New("boom")
 }
+func (e errSource) IssueTimeline(string, string, int64) ([]TimelineEvent, error) {
+	return nil, errors.New("boom")
+}
 
 // TestRound1 round1 十進位舍入到一位小數（與 Python round(x,1) 半偶數一致）。
 func TestRound1(t *testing.T) {