internal/cli：stalled 與 xrefs 命令接線，完成 #7 CLI 層（堆疊於 #23）

- workflow 新增 StalledSource 介面（Source＋CurrentUser＋GetIssue）與
  高階入口 RunStalled／ResolveIssueXrefs（xrefs 輸出附 source 出處）
- APIClient 補上 StalledSource 面向（GetIssue／TryGetIssue 等）
- CLI 新增 teai stalled [--hours N]（JSON 與 gitea.py 位元組相容：
  停用 HTML 轉義、縮排 2）與 teai xrefs <owner>/<repo> <number>
  （404 → exit 3）；table 模式 stalled_hours 定點一位小數
- 接線層與 workflow 層單元測試（注入假資料源、固定時刻）
- README 狀態行更新

驗證：go build／vet／test 全綠；對真實 API 並行掃描，stalled 輸出
與 gitea.py 位元組一致（2169 bytes）；xrefs 邊界案例（PR#50／
issue#49 略過、CJK 緊鄰、跨倉庫 owner/repo#N）與 Python 版一致。

README.md

@@ -6,7 +6,7 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
 
 - **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置
 - **目標站點：** `https://gitea.alterminal.com`
-- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）與日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）已實作；stalled/xrefs（#7）進行中
+- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）、日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）與管理者巡邏命令（#7：stalled/xrefs）已實作
 - **範圍（#3）：** 不避開 tea 已有的功能；單一工具涵蓋完整操作
 
 ## 安裝與建置

cmd/xcheck/main.go

@@ -132,8 +132,8 @@ func (s *apiSource) MyOrganizations() ([]string, error) {
 	return names, nil
 }
 
-func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repository, error) {
+func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
-	var repos []workflow.Repository
+	var repos []workflow.Repo
 	if err := s.listAll("orgs/"+org+"/repos", nil, &repos); err != nil {
 		return nil, err
 	}
@@ -157,7 +157,7 @@ func (s *apiSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error
 	return pulls, nil
 }
 
-func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Comment, error) {
+func (s *apiSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
 	var comments []workflow.Comment
 	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/comments", owner, repo, number), nil, &comments); err != nil {
 		return nil, err
@@ -165,7 +165,7 @@ func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Co
 	return comments, nil
 }
 
-func (s *apiSource) TryGetIssue(owner, repo string, number int) (workflow.Issue, bool, error) {
+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)
 	if err != nil {

internal/cli/stalled_commands.go

@@ -0,0 +1,170 @@
+// stalled_commands.go — 管理者巡邏命令的 CLI 接線（#7）：
+// stalled [--hours N] 與 xrefs <owner>/<repo> <number>。
+//
+// 核心邏輯在 internal/workflow（ScanStalled／ResolveIssueXrefs），
+// 本檔只做旗標剖析、資料源接線與輸出格式化。輸出走得體架構的
+// Printer（--output json|table）；錯誤經 cli.exitCodeFor 映射結束碼
+// （用法 2／API 3）。token 解析選序見 internal/gitea/auth.go。
+package cli
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"strconv"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+func init() {
+	commands["stalled"] = &command{
+		name:  "stalled",
+		usage: "停滯的 open issues／PR（管理者巡邏；--hours N 門檻，預設 4）",
+		run:   runStalled,
+	}
+	commands["xrefs"] = &command{
+		name:  "xrefs",
+		usage: "解析 issue／PR 內文與留言中的 #N／repo#N／owner/repo#N 引用",
+		run:   runXrefs,
+	}
+}
+
+// newStalledSourceFunc 建立 stalled／xrefs 的資料源；宣告為變數讓
+// 接線層測試可注入假資料源（不走網路），與 newScannerFunc 同模式。
+var newStalledSourceFunc = newStalledSource
+
+// newStalledSource 依全域選項建立 workflow.StalledSource（API 實作）。
+func newStalledSource(env *Env) (workflow.StalledSource, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &workflow.APIClient{Client: client}, nil
+}
+
+// stalledFields 是 stalled 的 table 欄位（JSON 模式輸出完整 Item，
+// 欄位序與 gitea.py 一致，見 workflow.Item.MarshalJSON）。
+func stalledFields() []gitea.Field {
+	return []gitea.Field{
+		{Name: "type"}, {Name: "repo"}, {Name: "number"}, {Name: "title"},
+		{Name: "last_comment_by"}, {Name: "last_activity_at"},
+		{Name: "stalled_hours"}, {Name: "reason"},
+	}
+}
+
+// stalledRow 把 Item 轉成 table 列（assignees／reviewers／child_activity
+// 僅 JSON 模式輸出；table 給人工抽查用，取共同欄位）。
+// stalled_hours 定點一位小數（fmt.Sprint(9.0) 會印 "9"，與 JSON 的 9.0 不一致）。
+func stalledRow(item workflow.Item) gitea.Values {
+	return gitea.Values{
+		item.Type, item.Repo, item.Number, item.Title,
+		item.LastCommentBy, workflow.FormatMoment(item.LastActivityAt),
+		strconv.FormatFloat(item.StalledHours, 'f', 1, 64), item.Reason,
+	}
+}
+
+// runStalled：teai stalled [--hours N]。
+// 預設門檻 4 小時；--hours 需為正數（同 gitea.py _parse_hours）。
+// JSON 輸出與 gitea.py stalled 位元組相容（workflow.Item 自訂 MarshalJSON；
+// 這裡輸出前停用 HTML 轉義並縮排 2，對應 Python json.dumps(indent=2)）。
+func runStalled(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai stalled", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	hours := fs.Float64("hours", workflow.StalledDefaultHours, "停滯門檻（小時，正數）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "stalled 不接受位置參數"}
+	}
+	if *hours <= 0 {
+		return &ErrUsage{Msg: "--hours 需為正數（小時），例如 --hours 4"}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	items, err := workflow.RunStalled(src, *hours, nowFunc())
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	if p.Format == gitea.FormatTable {
+		rows := make([]gitea.Values, 0, len(items))
+		for _, item := range items {
+			rows = append(rows, stalledRow(item))
+		}
+		return p.PrintList(stalledFields(), rows)
+	}
+	// JSON：空清單輸出 []（README：無停滯項目 → 空陣列）；有項目時
+	// 縮排 2 且停用 HTML 轉義，與 gitea.py 的 _dump 位元組相容。
+	if len(items) == 0 {
+		_, err := fmt.Fprintln(env.Out, "[]")
+		return err
+	}
+	return printJSON(env.Out, items)
+}
+
+// runXrefs：teai xrefs <owner>/<repo> <number>。
+// 編號不存在 → API 錯誤（結束碼 3）；無引用 → []。
+func runXrefs(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai xrefs", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 2 {
+		return &ErrUsage{Msg: "xrefs 需要 <owner>/<repo> <number> 兩個參數"}
+	}
+	owner, name, err := splitRepoFlag(args[0])
+	if err != nil {
+		return err
+	}
+	number, err := strconv.ParseInt(args[1], 10, 64)
+	if err != nil || number <= 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("編號需為正整數，得到 %q", args[1])}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	hits, err := workflow.ResolveIssueXrefs(src, owner, name, number)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(hits))
+	for _, h := range hits {
+		rows = append(rows, gitea.Values{h.Owner, h.Repo, h.Number, h.Source})
+	}
+	return p.PrintList(
+		[]gitea.Field{
+			{Name: "owner"}, {Name: "repo"}, {Name: "number"}, {Name: "source"},
+		},
+		rows,
+	)
+}
+
+// nowFunc 回傳目前時刻；宣告為變數讓測試可固定時刻（stalled 判定用）。
+var nowFunc = time.Now
+
+// printJSON 以縮排 2、停用 HTML 轉義輸出 JSON（與 gitea.py 的
+// json.dumps(ensure_ascii=False, indent=2) 位元組相容；HTML 轉義會把
+// <、>、& 變 \u003c 等，破壞相容性）。
+func printJSON(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	return enc.Encode(v)
+}

internal/cli/stalled_commands_test.go

@@ -0,0 +1,227 @@
+// stalled_commands_test.go — stalled／xrefs CLI 接線層測試（#7）：
+// 注入假 StalledSource，驗證 Run→dispatch→flagset 完整路徑，
+// 不走網路（與 workflow_commands_test.go 同模式）。
+package cli
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// stubStalledSource 以記憶體資料實作 workflow.StalledSource。
+type stubStalledSource struct {
+	username string
+	orgs     []string
+	repos    map[string][]workflow.Repo
+	issues   map[string]map[int64]workflow.Issue
+	comments map[string][]workflow.Comment
+	getErr   error
+}
+
+func (s *stubStalledSource) CurrentUser() (string, error) { return s.username, nil }
+func (s *stubStalledSource) MyOrganizations() ([]string, error) {
+	return s.orgs, nil
+}
+func (s *stubStalledSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+	return s.repos[org], nil
+}
+func (s *stubStalledSource) OpenIssues(owner, repo string) ([]workflow.Issue, error) {
+	var out []workflow.Issue
+	for _, i := range s.issues[owner+"/"+repo] {
+		out = append(out, i)
+	}
+	return out, nil
+}
+func (s *stubStalledSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error) {
+	return nil, nil
+}
+func (s *stubStalledSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
+	return s.comments[owner+"/"+repo+"/"+itoa(number)], nil
+}
+func (s *stubStalledSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
+	i, ok := s.issues[owner+"/"+repo][number]
+	return i, ok, nil
+}
+func (s *stubStalledSource) GetIssue(owner, repo string, number int64) (workflow.Issue, error) {
+	if s.getErr != nil {
+		return workflow.Issue{}, s.getErr
+	}
+	i, ok := s.issues[owner+"/"+repo][number]
+	if !ok {
+		return workflow.Issue{}, &gitea.ErrAPI{Op: "GET /repos/" + owner + "/" + repo + "/issues/" + itoa(number), StatusCode: 404}
+	}
+	return i, nil
+}
+
+func itoa(n int64) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+// newStubStalledEnv 注入假資料源並固定時刻。
+func newStubStalledEnv(t *testing.T, src *stubStalledSource, frozen time.Time) {
+	t.Helper()
+	origSrc, origNow := newStalledSourceFunc, nowFunc
+	newStalledSourceFunc = func(env *Env) (workflow.StalledSource, error) { return src, nil }
+	nowFunc = func() time.Time { return frozen }
+	t.Cleanup(func() { newStalledSourceFunc, nowFunc = origSrc, origNow })
+}
+
+// isoAt 把相對分鐘轉成 ISO8601 字串（假資料用；錨點同 workflow 測試）。
+func isoAt(minutes int) string {
+	return workflow.FormatMoment(time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC).Add(time.Duration(minutes) * time.Minute))
+}
+
+// newStubStalledData 建構 stalled 情境：agents#1 停滯 10 小時（no-assignee）。
+func newStubStalledData() *stubStalledSource {
+	return &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {{Name: "agents"}}},
+		issues: map[string]map[int64]workflow.Issue{
+			"alterminal/agents": {
+				1: {Number: 1, Title: "停滯項", State: "open",
+					CreatedAt: isoAt(-600), UpdatedAt: isoAt(-600),
+					Repository: &workflow.Repository{FullName: "alterminal/agents"}},
+			},
+		},
+		comments: map[string][]workflow.Comment{},
+	}
+}
+
+// TestWiringStalled 驗證 stalled 基本路徑：JSON 輸出含停滯欄位。
+func TestWiringStalled(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), 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)
+	}
+	for _, want := range []string{`"type": "issue"`, `"reason": "no-assignee"`, `"stalled_hours": 10.0`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("stalled 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringStalledHoursFlag 驗證 --hours 覆寫門檻與非正數被攔。
+func TestWiringStalledHoursFlag(t *testing.T) {
+	freeze := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	newStubStalledEnv(t, newStubStalledData(), freeze)
+	// 門檻 20h → 10h 停滯未過門檻 → 空陣列。
+	stdout, _, code := run("stalled", "--hours", "20")
+	if code != 0 {
+		t.Fatalf("stalled --hours 20 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無停滯項應輸出 []，得到 %q", stdout)
+	}
+	// 非正數 → exit 2。
+	_, stderr, code := run("stalled", "--hours", "-1")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled --hours -1 應回 ExitUsage(%d)，得到 %d（stderr=%q）", int(ExitUsage), code, stderr)
+	}
+	// 位置參數 → exit 2。
+	_, _, code = run("stalled", "extra")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled extra 應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	}
+}
+
+// TestWiringStalledTable 驗證 table 輸出（README 範例）。
+func TestWiringStalledTable(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled", "--output", "table")
+	if code != 0 {
+		t.Fatalf("stalled --output table 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{"reason", "no-assignee", "停滯項"} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("table 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefs 驗證 xrefs 解析輸出（含 body／comment 出處）。
+func TestWiringXrefs(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "父項", State: "open",
+		Body: "子項：agents#2",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.issues["alterminal/agents"][2] = workflow.Issue{
+		Number: 2, Title: "子項", State: "open",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.comments["alterminal/agents/1"] = []workflow.Comment{
+		{Body: "看 agents#2", User: &workflow.User{UserName: "alex"}},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	// Printer JSON 為單行緊湊格式（無縮排）；命令清單類輸出一律如此。
+	for _, want := range []string{`"repo":"agents"`, `"number":2`, `"source":"body"`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("xrefs 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefsEmpty 驗證無引用 → []。
+func TestWiringXrefsEmpty(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "無引用", State: "open",
+		Body: "沒有任何引用",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無引用應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringXrefsUsage 驗證參數不足／格式錯誤 → exit 2。
+func TestWiringXrefsUsage(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	if _, _, code := run("xrefs"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 無參數應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 缺編號應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "not-a-repo", "1"); code != int(ExitUsage) {
+		t.Fatalf("xrefs repo 格式錯誤應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents", "abc"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 編號非數字應回 ExitUsage，得到 %d", code)
+	}
+}
+
+// TestWiringXrefsNotFound 驗證 404 → exit 3（API 錯誤）。
+func TestWiringXrefsNotFound(t *testing.T) {
+	src := newStubStalledData()
+	src.getErr = &gitea.ErrAPI{Op: "GET /repos/alterminal/agents/issues/99", StatusCode: 404}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	_, stderr, code := run("xrefs", "alterminal/agents", "99")
+	if code != int(ExitAPI) {
+		t.Fatalf("xrefs 404 應回 ExitAPI(%d)，得到 %d（stderr=%q）", int(ExitAPI), code, stderr)
+	}
+}

internal/workflow/giteaapi.go

@@ -122,3 +122,56 @@ func (a *APIClient) ListComments(owner, repo string, number int64) ([]Comment, e
 	}
 	return comments, nil
 }
+
+// ── StalledSource 面向（#7 CLI 接線）────────────────────────────────────
+// APIClient 在 Client 之外同時實作 StalledSource（Source + CurrentUser +
+// GetIssue），讓 stalled／xrefs 命令與既有命令共用同一個 HTTP 用戶端。
+// 清單類方法直接委派 Client 同名操作，語義一致（type=issues、state=open）。
+
+// GetIssue 單一 issue 查詢（PR 亦經此端點，帶 pull_request 標記）；
+// 失敗（含 404）回 *gitea.ErrAPI，由 CLI 映射結束碼 3。
+func (a *APIClient) GetIssue(owner, repo string, number int64) (Issue, error) {
+	var issue Issue
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10)
+	if err := a.Client.GetJSON(context.Background(), path, &issue); err != nil {
+		return Issue{}, err
+	}
+	return issue, nil
+}
+
+// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)，
+// 供 stalled 父追蹤項掃描靜默略過不存在的子項（Source 介面契約）。
+func (a *APIClient) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
+	issue, err := a.GetIssue(owner, repo, number)
+	if err != nil {
+		return Issue{}, false, nil
+	}
+	return issue, true, nil
+}
+
+// MyOrganizations 委派 ListOrgs（Source 面向）。
+func (a *APIClient) MyOrganizations() ([]string, error) { return a.ListOrgs() }
+
+// OrganizationRepositories 委派 ListOrgRepos（Source 面向）。
+func (a *APIClient) OrganizationRepositories(org string) ([]Repo, error) {
+	return a.ListOrgRepos(org)
+}
+
+// OpenIssues 委派 ListIssues（Source 面向；已排除 PR）。
+func (a *APIClient) OpenIssues(owner, repo string) ([]Issue, error) {
+	return a.ListIssues(owner, repo)
+}
+
+// OpenPulls 委派 ListPulls（Source 面向）。
+func (a *APIClient) OpenPulls(owner, repo string) ([]PullRequest, error) {
+	return a.ListPulls(owner, repo)
+}
+
+// IssueComments 委派 ListComments（Source 面向）。
+func (a *APIClient) IssueComments(owner, repo string, number int64) ([]Comment, error) {
+	return a.ListComments(owner, repo, number)
+}
+
+// 編譯期確認 APIClient 同時實作 Client 與 StalledSource。
+var _ StalledSource = (*APIClient)(nil)

internal/workflow/stalled_entry_test.go

@@ -0,0 +1,231 @@
+// stalled_entry_test.go — RunStalled／ResolveIssueXrefs 高階入口的單元測試
+//（#7 CLI 接線；資料源注入假實作，離線可測）。
+package workflow
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeStalledSource 包 fakeSource 補上 StalledSource 面向。
+type fakeStalledSource struct {
+	*fakeSource
+	username string
+	// getIssueErr 模擬 GetIssue 失敗（xrefs 的 404 路徑）。
+	getIssueErr error
+}
+
+func (f *fakeStalledSource) CurrentUser() (string, error) { return f.username, nil }
+
+func (f *fakeStalledSource) GetIssue(owner, repo string, number int64) (Issue, error) {
+	if f.getIssueErr != nil {
+		return Issue{}, f.getIssueErr
+	}
+	i, ok := f.issues[owner+"/"+repo][number]
+	if !ok {
+		return Issue{}, &notFoundError{}
+	}
+	return i, nil
+}
+
+type notFoundError struct{}
+
+func (e *notFoundError) Error() string { return "404" }
+
+// newStalledFixture 建構掃描情境：alterminal 組織兩個倉庫，
+// agents#1 是父追蹤項（引用 teai#2），teai#2 有較新留言。
+func newStalledFixture() *fakeStalledSource {
+	return &fakeStalledSource{
+		fakeSource: &fakeSource{
+			orgs:  []string{"alterminal"},
+			repos: map[string][]Repo{"alterminal": {
+				{Name: "agents", HasPullRequests: boolPtr(true)},
+				{Name: "teai", HasPullRequests: boolPtr(true)},
+			}},
+			issues: map[string]map[int64]Issue{
+				"alterminal/agents": {
+					1: {Number: 1, Title: "父追蹤項", State: "open",
+						Body: "子項：teai#2", CreatedAt: iso(-600), UpdatedAt: iso(-600),
+						Repository: &Repository{FullName: "alterminal/agents"}},
+				},
+				"alterminal/teai": {
+					2: {Number: 2, Title: "子項", State: "open",
+						CreatedAt: iso(-500), UpdatedAt: iso(-90),
+						Repository: &Repository{FullName: "alterminal/teai"}},
+				},
+			},
+			pulls: map[string][]PullRequest{},
+			comments: map[string][]Comment{
+				"alterminal/teai/2": {
+					{CreatedAt: iso(-90), User: &User{UserName: "alex"}, Body: "推進中"},
+				},
+			},
+		},
+		username: "ceo",
+	}
+}
+
+// TestRunStalledParentTracking 驗證 RunStalled：父追蹤項把子項活動
+// 計入 last_activity（reason=parent-tracking），且門檻預設與覆寫皆可。
+func TestRunStalledParentTracking(t *testing.T) {
+	src := newStalledFixture()
+	// 預設 4 小時門檻：子項 90 分鐘前有活動 → 父項 last_activity 同步，
+	// 未過門檻，清單為空。
+	items, err := RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("預設門檻下不應有停滯項，得到 %d 筆", len(items))
+	}
+	// 門檻降到 1 小時：父追蹤項 last_activity 取子項活動（-90m）→
+	// 停滯 1.5h 列入（reason=parent-tracking、附 child_activity）；
+	// 子項 teai#2 本身也停滯 1.5h（no-assignee）。
+	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].Number == 1 {
+			parent = &items[i]
+		}
+	}
+	if parent == nil {
+		t.Fatalf("找不到 agents#1：%+v", items)
+	}
+	if parent.Reason != "parent-tracking" || parent.Repo != "alterminal/agents" {
+		t.Fatalf("agents#1 應為 parent-tracking，得到 %s（%s）", parent.Reason, parent.Repo)
+	}
+	if len(parent.ChildActivity) == 0 {
+		t.Fatalf("parent-tracking 應附 child_activity")
+	}
+	if parent.StalledHours != 1.5 {
+		t.Fatalf("last_activity 應取子項活動（-90m → 1.5h），得到 %.1f", parent.StalledHours)
+	}
+}
+
+// TestRunStalledNudgeCooldown 驗證催促冷卻：最後留言出自目前帳號
+// 且在 24 小時內 → 不列入；冷卻過後再出現。
+func TestRunStalledNudgeCooldown(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "") // 移除子項引用
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-2), User: &User{UserName: "ceo"}},
+	}
+	findOne := func(items []Item) bool {
+		for _, it := range items {
+			if it.Repo == "alterminal/agents" && it.Number == 1 {
+				return true
+			}
+		}
+		return false
+	}
+	items, err := RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if findOne(items) {
+		t.Fatalf("催促冷卻期內（2 小時前留言）agents#1 不應列入，得到 %+v", items)
+	}
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-30 * 60), User: &User{UserName: "ceo"}},
+	}
+	items, err = RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if !findOne(items) {
+		t.Fatalf("冷卻（24h）過後 agents#1 應再出現，得到 %+v", items)
+	}
+}
+
+// TestResolveIssueXrefs 驗證 xrefs 入口：內文與留言的引用解析、
+// 去重、出處標記與單段 repo 的存在性邊界。
+func TestResolveIssueXrefs(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "看 teai#2 與 #7，另見 alterminal/teai#2")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "teai#2 已處理", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+		{Body: "nope#9 不存在", User: &User{UserName: "max"}, CreatedAt: iso(-5)},
+	}
+	// fixture 的組織倉庫只有 agents → teai#2 單段不解析（repo 不在
+	// alterminal 組織清單）；補上 teai 倉庫讓單段解析成立。
+	src.repos["alterminal"] = []Repo{
+		{Name: "agents", HasPullRequests: boolPtr(true)},
+		{Name: "teai", HasPullRequests: boolPtr(true)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	want := []XrefHit{
+		{Owner: "alterminal", Repo: "teai", Number: 2, Source: "body"},
+		{Owner: "alterminal", Repo: "agents", Number: 7, Source: "body"},
+	}
+	if len(hits) != len(want) {
+		t.Fatalf("應解析出 %d 筆（留言重複的 teai#2 去重、nope#9 略過），得到 %d：%+v",
+			len(want), len(hits), hits)
+	}
+	for i := range want {
+		if hits[i] != want[i] {
+			t.Fatalf("hits[%d] = %+v, want %+v", i, hits[i], want[i])
+		}
+	}
+}
+
+// TestResolveIssueXrefsCommentSource 驗證出處：僅出現在留言的引用
+// 標記為 comment。
+func TestResolveIssueXrefsCommentSource(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "內文無引用")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "追蹤 #9", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 1 || hits[0].Source != "comment" || hits[0].Number != 9 {
+		t.Fatalf("應輸出一筆 source=comment 的 #9，得到 %+v", hits)
+	}
+}
+
+// TestResolveIssueXrefsGetError 驗證 GetIssue 失敗（如 404）層層回傳，
+// 由 CLI 映射結束碼。
+func TestResolveIssueXrefsGetError(t *testing.T) {
+	src := newStalledFixture()
+	src.getIssueErr = &notFoundError{}
+	if _, err := ResolveIssueXrefs(src, "alterminal", "agents", 1); err == nil {
+		t.Fatalf("GetIssue 失敗應回傳錯誤")
+	}
+}
+
+func boolPtr(b bool) *bool { return &b }
+
+// setIssueBody 修改 map 內 issue 的內文（map 元素不可定址，需整體重塞）。
+func setIssueBody(src *fakeStalledSource, owner, repo string, number int64, body string) {
+	key := owner + "/" + repo
+	issue := src.issues[key][number]
+	issue.Body = body
+	src.issues[key][number] = issue
+}
+
+// TestResolveIssueXrefsEmptyBody 驗證無引用時輸出空（CLI 印 []）。
+func TestResolveIssueXrefsEmptyBody(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, strings.Repeat("無引用內文", 3))
+	delete(src.comments, "alterminal/agents/1")
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("無引用應輸出空清單，得到 %+v", hits)
+	}
+	_ = time.Now // time 僅供 iso/at 使用；保留 import。
+}

internal/workflow/types.go

@@ -3,6 +3,8 @@ package workflow
 import (
 	"encoding/json"
 	"regexp"
+	"strings"
+	"time"
 )
 
 // User 是 Gitea API 的使用者物件（僅取工作流判斷會用到的欄位）。
@@ -65,6 +67,7 @@ type PRRef struct {
 
 // Comment 是 issue／PR 的討論留言（PR 的留言也走 issues comments 端點）。
 type Comment struct {
+	Body      string `json:"body"`
 	CreatedAt string `json:"created_at"`
 	User      *User  `json:"user"`
 }
@@ -82,6 +85,9 @@ type Issue struct {
 	Number      int64       `json:"number"`
 	Index       int64       `json:"index"`
 	Title       string      `json:"title"`
+	State       string      `json:"state"`
+	Body        string      `json:"body"`
+	ClosedAt    string      `json:"closed_at"`
 	HTMLURL     string      `json:"html_url"`
 	URL         string      `json:"url"`
 	UpdatedAt   string      `json:"updated_at"`
@@ -216,3 +222,21 @@ func (p *PullRequest) FullName() string {
 	}
 	return repoFullNameFromURL(p.WebURL())
 }
+
+// parseMoment 對應 gitea.py 的 _parse_iso8601：剖析 ISO8601 字串（Z 後綴、
+// 小數秒、時區偏移皆可；無時區視為 UTC），失敗回 (零值, false)。
+// 保留原時區偏移、不轉 UTC——Python datetime.isoformat() 會原樣輸出
+// 「+08:00」這類偏移，轉了 UTC 輸出就變 +00:00，與基準位元組不相容。
+// stalled 掃描的時刻判斷（last_activity、催促冷卻）都以這裡的語義為準。
+func parseMoment(value string) (time.Time, bool) {
+	text := strings.TrimSpace(value)
+	if text == "" {
+		return time.Time{}, false
+	}
+	for _, layout := range []string{time.RFC3339Nano, time.RFC3339, "2006-01-02T15:04:05", "2006-01-02"} {
+		if t, err := time.Parse(layout, text); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}

internal/workflow/workflow.go

@@ -37,85 +37,11 @@ const (
 // Go 的 regexp 不支援 lookbehind，改在掃描時檢查前一字元。
 var xrefPattern = regexp.MustCompile(`([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?)?#(\d+)`)
 
-// User 是 Gitea user 物件的精簡投影。
-type User struct {
-	Username string `json:"username"`
-}
-
-// Comment 是 issue／PR 留言的精簡投影。
-type Comment struct {
-	User      User      `json:"user"`
-	Body      string    `json:"body"`
-	CreatedAt time.Time `json:"created_at"`
-}
-
-// Author 回傳留言作者帳號；空字串表示無法判定。
-func (c Comment) Author() string { return c.User.Username }
-
-// Issue 是 issue 的精簡投影（Gitea /repos/{owner}/{repo}/issues，不含 PR）。
-type Issue struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Body      string     `json:"body"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL        string    `json:"html_url"`
-	Assignees  []User    `json:"assignees"`
-	Repository Reference `json:"repository"`
-	// PullRequest 非 nil 表示這其實是 PR（Gitea 的 /issues API 兩者都回）。
-	PullRequest any `json:"pull_request,omitempty"`
-}
-
-// Reference 是 repository 物件的精簡投影（issue 物件帶 full_name）。
-type Reference struct {
-	FullName string `json:"full_name"`
-}
-
-// Ref 是 PR base/head 的精簡投影（PR 物件沒有 repository 欄位，改讀 base/head.repo）。
-type Ref struct {
-	Repo Reference `json:"repo"`
-}
-
-// PullRequest 是 /repos/{owner}/{repo}/pulls 物件的精簡投影。
-type PullRequest struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL                string `json:"html_url"`
-	Base               Ref    `json:"base"`
-	Head               Ref    `json:"head"`
-	RequestedReviewers []User `json:"requested_reviewers"`
-}
-
-// FullName 回傳 "owner/repo"；PR 沒有 repository 欄位，改讀 base（再退 head）。
-func (p PullRequest) FullName() string {
-	if p.Base.Repo.FullName != "" {
-		return p.Base.Repo.FullName
-	}
-	return p.Head.Repo.FullName
-}
-
-// Repository 是 /orgs/{org}/repos 物件的精簡投影。
-type Repository struct {
-	Name            string `json:"name"`
-	Empty           bool   `json:"empty"`
-	HasPullRequests *bool  `json:"has_pull_requests"`
-}
-
 // Item 是 stalled 掃描的單筆輸出（欄位對應 gitea.py 的 find_stalled_work）。
 type Item struct {
 	Type           string
 	Repo           string
-	Number         int
+	Number         int64
 	Title          string
 	URL            string
 	Assignees      []string
@@ -195,7 +121,7 @@ func writeJSON(b *strings.Builder, v any) {
 // Child 是父追蹤項的子項活動摘要。
 type Child struct {
 	Repo   string `json:"repo"`
-	Number int    `json:"number"`
+	Number int64  `json:"number"`
 	Title  string `json:"title"`
 	State  string `json:"state"`
 	// LastActivityAt 用指標：子項無可解析時刻時 Python 輸出 null（不是 ""）。
@@ -206,7 +132,7 @@ type Child struct {
 type XrefTarget struct {
 	Owner  string
 	Repo   string
-	Number int
+	Number int64
 }
 
 // Source 是 stalled 掃描需要的資料源（CLI 層以 API 實作；測試注入假資料）。
@@ -214,15 +140,15 @@ type Source interface {
 	// MyOrganizations 回傳目前帳號所屬組織清單。
 	MyOrganizations() ([]string, error)
 	// OrganizationRepositories 回傳組織的倉庫清單。
-	OrganizationRepositories(org string) ([]Repository, error)
+	OrganizationRepositories(org string) ([]Repo, error)
 	// OpenIssues 回傳倉庫的 open issues（Gitea 會混入 PR，由掃描端過濾）。
 	OpenIssues(owner, repo string) ([]Issue, error)
 	// OpenPulls 回傳倉庫的 open pull requests。
 	OpenPulls(owner, repo string) ([]PullRequest, error)
 	// IssueComments 回傳 issue／PR 的留言。
-	IssueComments(owner, repo string, number int) ([]Comment, error)
+	IssueComments(owner, repo string, number int64) ([]Comment, error)
 	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
-	TryGetIssue(owner, repo string, number int) (Issue, bool, error)
+	TryGetIssue(owner, repo string, number int64) (Issue, bool, error)
 }
 
 // iterXrefs 產出文字中的 (prefix, number) 配對（對應 _iter_issue_xrefs）。
@@ -278,7 +204,7 @@ func ResolveXrefTargets(org, repo string, texts []string, myOrgs map[string]bool
 	for _, text := range texts {
 		for _, pair := range iterXrefs(text) {
 			prefix, numberStr := pair[0], pair[1]
-			var number int
+			var number int64
 			if _, err := fmt.Sscanf(numberStr, "%d", &number); err != nil || number <= 0 {
 				continue
 			}
@@ -334,23 +260,25 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 		if gerr != nil || !ok {
 			continue
 		}
-		if t.Owner == org && t.Repo == repo && child.Number == parent.Number {
+		if t.Owner == org && t.Repo == repo && child.issueNumber() == parent.issueNumber() {
 			continue // 自我引用
 		}
-		if !parent.CreatedAt.IsZero() && !child.CreatedAt.IsZero() && !child.CreatedAt.After(parent.CreatedAt) {
+		parentCreated, pcOK := parseMoment(parent.CreatedAt)
+		childCreated, ccOK := parseMoment(child.CreatedAt)
+		if pcOK && ccOK && !childCreated.After(parentCreated) {
 			continue // 上行引用（父項回指更早或同時的 issue）；時間未知則不排除
 		}
 		var ms []time.Time
-		if !child.UpdatedAt.IsZero() {
+		if m, ok := parseMoment(child.UpdatedAt); ok {
-			ms = append(ms, child.UpdatedAt)
+			ms = append(ms, m)
 		}
-		if child.ClosedAt != nil && !child.ClosedAt.IsZero() {
+		if m, ok := parseMoment(child.ClosedAt); ok {
-			ms = append(ms, *child.ClosedAt)
+			ms = append(ms, m)
 		}
 		if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
 			for _, c := range cs {
-				if !c.CreatedAt.IsZero() {
+				if m, ok := parseMoment(c.CreatedAt); ok {
-					ms = append(ms, c.CreatedAt)
+					ms = append(ms, m)
 				}
 			}
 		}
@@ -384,20 +312,6 @@ func maxTime(ts []time.Time) time.Time {
 	return best
 }
 
-func usernames(users []User) []string {
-	var out []string
-	seen := map[string]bool{}
-	for _, u := range users {
-		if u.Username == "" || seen[u.Username] {
-			continue
-		}
-		seen[u.Username] = true
-		out = append(out, u.Username)
-	}
-	sort.Strings(out)
-	return out
-}
-
 // ScanStalled 掃描跨組織的停滯 open issues／PR（對應 find_stalled_work）。
 //
 // 判定：最後活動（留言時間與本身 updated_at 取較晚者，父追蹤項再加計
@@ -483,15 +397,20 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 // considerIssue 對單一 issue 套用停滯判定（對應 _consider 的 issue 分支）。
 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 := usernames(issue.Assignees)
+	assignees := AssigneeNames(&issue)
-	moments := []time.Time{issue.UpdatedAt, issue.CreatedAt}
+	var moments []time.Time
+	if m, ok := parseMoment(issue.UpdatedAt); ok {
+		moments = append(moments, m)
+	}
+	if m, ok := parseMoment(issue.CreatedAt); ok {
+		moments = append(moments, m)
+	}
 	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
+		if m, ok := parseMoment(c.CreatedAt); ok {
-			moments = append(moments, c.CreatedAt)
+			moments = append(moments, m)
 		}
 	}
 	moments = append(moments, childMoments...)
-	moments = nonZero(moments)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -500,16 +419,21 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 	if stalled < threshold {
 		return Item{}, false
 	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
+	last := LastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
+	lastCommentBy := ""
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
+	if last != nil {
-		return Item{}, false
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
+			return Item{}, false
+		}
 	}
 	reason := "waiting-outside"
 	switch {
 	case len(assignees) == 0:
 		reason = "no-assignee"
-	case lastCommentBy != "" && containsStr(assignees, lastCommentBy):
+	case lastCommentBy != "" && containsString(assignees, lastCommentBy):
 		reason = "assignee-idle"
 	case lastCommentBy == "":
 		reason = "no-commenter"
@@ -518,8 +442,8 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 		reason = "parent-tracking"
 	}
 	item := Item{
-		Type: "issue", Repo: issue.Repository.FullName, Number: issue.Number,
+		Type: "issue", Repo: issue.FullName(), Number: issue.issueNumber(),
-		Title: issue.Title, URL: issue.URL,
+		Title: issue.Title, URL: issue.WebURL(),
 		Assignees:     assignees,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -532,15 +456,20 @@ 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) {
-	reviewers := usernames(pr.RequestedReviewers)
+	reviewers := ReviewerNames(&pr)
-	author := pr.Author.Username
+	author := pr.Author()
-	moments := []time.Time{pr.UpdatedAt, pr.CreatedAt}
+	var moments []time.Time
+	if m, ok := parseMoment(pr.UpdatedAt); ok {
+		moments = append(moments, m)
+	}
+	if m, ok := parseMoment(pr.CreatedAt); ok {
+		moments = append(moments, m)
+	}
 	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
+		if m, ok := parseMoment(c.CreatedAt); ok {
-			moments = append(moments, c.CreatedAt)
+			moments = append(moments, m)
 		}
 	}
-	moments = nonZero(moments)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -549,10 +478,15 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	if stalled < threshold {
 		return Item{}, false
 	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
+	last := LastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
+	lastCommentBy := ""
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
+	if last != nil {
-		return Item{}, false
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
+			return Item{}, false
+		}
 	}
 	reason := "no-commenter"
 	switch {
@@ -560,12 +494,12 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 		reason = "no-reviewer"
 	case lastCommentBy == author:
 		reason = "author-idle"
-	case lastCommentBy != "" && containsStr(reviewers, lastCommentBy):
+	case lastCommentBy != "" && containsString(reviewers, lastCommentBy):
 		reason = "reviewer-idle"
 	}
 	item := Item{
 		Type: "pull", Repo: pr.FullName(), Number: pr.Number,
-		Title: pr.Title, URL: pr.URL,
+		Title: pr.Title, URL: pr.WebURL(),
 		Author: author, Reviewers: reviewers,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -573,19 +507,6 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	return item, true
 }
 
-// lastComment 回傳最後一則留言（created_at 最新者）的時間與作者。
-func lastComment(comments []Comment) (time.Time, string) {
-	var best time.Time
-	by := ""
-	for _, c := range comments {
-		if c.CreatedAt.After(best) {
-			best = c.CreatedAt
-			by = c.Author()
-		}
-	}
-	return best, by
-}
-
 func anyOpen(children []Child) bool {
 	for _, c := range children {
 		if c.State == "open" {
@@ -595,25 +516,6 @@ func anyOpen(children []Child) bool {
 	return false
 }
 
-func containsStr(list []string, s string) bool {
-	for _, x := range list {
-		if x == s {
-			return true
-		}
-	}
-	return false
-}
-
-func nonZero(ts []time.Time) []time.Time {
-	out := make([]time.Time, 0, len(ts))
-	for _, t := range ts {
-		if !t.IsZero() {
-			out = append(out, t)
-		}
-	}
-	return out
-}
-
 // round1 舍入到小數一位（對應 Python round(x, 1)）。
 // 經 strconv 的十進位正確舍入（半偶數），與 Python 的浮點 round 行為一致，
 // 避免 (x*10+0.5) 截斷在 .x5 邊界產生偏差。
@@ -624,3 +526,111 @@ func round1(v float64) float64 {
 	}
 	return r
 }
+
+// ── CLI 接線用的高階入口（#7：teai stalled／teai xrefs）─────────────────
+
+// StalledSource 是 stalled／xrefs 命令需要的完整資料源：
+// Source（掃描用讀取）加上目前帳號與單一 issue 查詢。
+// APIClient（giteaapi.go）實作此介面；測試以假資料源注入。
+type StalledSource interface {
+	Source
+	// CurrentUser 回傳目前帳號名（催促冷卻判定用）。
+	CurrentUser() (string, error)
+	// GetIssue 嚴格版單一 issue／PR 查詢；失敗回錯誤（xrefs 命令用，
+	// 404 應回 ErrAPI 由 CLI 映射結束碼 3）。
+	GetIssue(owner, repo string, number int64) (Issue, error)
+}
+
+// RunStalled 是 teai stalled 的核心：解析目前帳號後跑 ScanStalled。
+// hours <= 0 時採 StalledDefaultHours（對應 gitea.py stalled [--hours N]
+// 的預設 4 小時）；旗標層已先攔下非正數，這裡是防禦。
+func RunStalled(src StalledSource, hours float64, now time.Time) ([]Item, error) {
+	if hours <= 0 {
+		hours = StalledDefaultHours
+	}
+	username, err := src.CurrentUser()
+	if err != nil {
+		return nil, err
+	}
+	return ScanStalled(src, username, hours, now)
+}
+
+// XrefHit 是 teai xrefs 的單筆輸出：解析後的目標加上出處
+// （README 規格："body"＝內文、"comment"＝留言）。
+type XrefHit struct {
+	Owner  string `json:"owner"`
+	Repo   string `json:"repo"`
+	Number int64  `json:"number"`
+	Source string `json:"source"`
+}
+
+// ResolveIssueXrefs 是 teai xrefs 的核心：取回單一 issue／PR 的內文與
+// 全部留言，解析其中的 #N、repo#N、owner/repo#N 引用（規則同
+// ResolveXrefTargets：單段 repo 僅在父項所屬組織有該倉庫時解析、
+// owner/repo#N 僅在 owner 為所屬組織時解析），去重並保留出現順序，
+// 每筆附首次出現的出處（內文先於留言）。stalled 的父追蹤項判定
+// 內部用同一套解析，不重複實作。
+func ResolveIssueXrefs(src StalledSource, owner, repo string, number int64) ([]XrefHit, error) {
+	issue, err := src.GetIssue(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	comments, err := src.IssueComments(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	orgs, err := src.MyOrganizations()
+	if err != nil {
+		return nil, err
+	}
+	myOrgs := make(map[string]bool, len(orgs))
+	for _, o := range orgs {
+		myOrgs[o] = true
+	}
+	// 組織倉庫清單跨呼叫快取，避免逐則留言重打 API。
+	orgRepoCache := map[string][]string{}
+	orgRepos := func(org string) ([]string, error) {
+		if names, ok := orgRepoCache[org]; ok {
+			return names, nil
+		}
+		repos, err := src.OrganizationRepositories(org)
+		if err != nil {
+			return nil, err
+		}
+		names := make([]string, 0, len(repos))
+		for _, r := range repos {
+			if r.Name != "" {
+				names = append(names, r.Name)
+			}
+		}
+		orgRepoCache[org] = names
+		return names, nil
+	}
+	type sourceText struct {
+		text   string
+		source string
+	}
+	texts := []sourceText{{issue.Body, "body"}}
+	for _, c := range comments {
+		texts = append(texts, sourceText{c.Body, "comment"})
+	}
+	var hits []XrefHit
+	seen := map[XrefTarget]bool{}
+	for _, t := range texts {
+		targets, err := ResolveXrefTargets(owner, repo, []string{t.text}, myOrgs, orgRepos)
+		if err != nil {
+			return nil, err
+		}
+		for _, target := range targets {
+			if seen[target] {
+				continue
+			}
+			seen[target] = true
+			hits = append(hits, XrefHit{
+				Owner: target.Owner, Repo: target.Repo,
+				Number: target.Number, Source: t.source,
+			})
+		}
+	}
+	return hits, nil
+}

internal/workflow/workflow_test.go

@@ -21,9 +21,9 @@ func at(minutes int) time.Time {
 // fakeSource 是注入假資料的 Source。
 type fakeSource struct {
 	orgs  []string
-	repos map[string][]Repository
+	repos map[string][]Repo
 	// issues[owner/repo][number]
-	issues map[string]map[int]Issue
+	issues map[string]map[int64]Issue
 	// pulls[owner/repo]
 	pulls map[string][]PullRequest
 	// comments[owner/repo/number]
@@ -32,7 +32,7 @@ type fakeSource struct {
 
 func (f *fakeSource) MyOrganizations() ([]string, error) { return f.orgs, nil }
 
-func (f *fakeSource) OrganizationRepositories(org string) ([]Repository, error) {
+func (f *fakeSource) OrganizationRepositories(org string) ([]Repo, error) {
 	return f.repos[org], nil
 }
 
@@ -48,11 +48,11 @@ func (f *fakeSource) OpenPulls(owner, repo string) ([]PullRequest, error) {
 	return f.pulls[owner+"/"+repo], nil
 }
 
-func (f *fakeSource) IssueComments(owner, repo string, number int) ([]Comment, error) {
+func (f *fakeSource) IssueComments(owner, repo string, number int64) ([]Comment, error) {
 	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
 }
 
-func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, error) {
+func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
 	i, ok := f.issues[owner+"/"+repo][number]
 	if !ok {
 		return Issue{}, false, nil
@@ -60,11 +60,14 @@ func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, e
 	return i, true, nil
 }
 
-func repoWith(name string, hasPR bool) []Repository {
+func repoWith(name string, hasPR bool) []Repo {
 	h := hasPR
-	return []Repository{{Name: name, HasPullRequests: &h}}
+	return []Repo{{Name: name, HasPullRequests: &h}}
 }
 
+// iso 把相對分鐘轉成 parseMoment 可剖析的 ISO8601 字串（假資料用）。
+func iso(minutes int) string { return FormatMoment(at(minutes)) }
+
 func mustResolve(t *testing.T, org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) []XrefTarget {
 	t.Helper()
 	targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
@@ -157,21 +160,21 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs: []string{"alterminal"},
-		repos: map[string][]Repository{
+		repos: map[string][]Repo{
 			"alterminal": repoWith("agents", true),
 		},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/agents"}, URL: "u1"},
+				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/agents"}, URL: "u1"},
-				2: {Number: 2, Title: "分派者自己最後留言", State: "open", Author: User{"ceo"}, CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u2"},
+				2: {Number: 2, Title: "分派者自己最後留言", State: "open", User: &User{UserName: "ceo"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u2"},
-				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u3"},
+				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u3"},
-				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u4"},
+				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u4"},
-				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: at(-30), UpdatedAt: at(-30), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u5"},
+				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: iso(-30), UpdatedAt: iso(-30), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u5"},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/agents/2": {{User: User{"ceo"}, CreatedAt: at(-300)}},
+			"alterminal/agents/2": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}},
-			"alterminal/agents/4": {{User: User{"dan"}, CreatedAt: at(-300)}},
+			"alterminal/agents/4": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -182,11 +185,11 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	if len(got) != 4 {
 		t.Fatalf("應 4 筆，got %d：%v", len(got), got)
 	}
-	byNumber := map[int]Item{}
+	byNumber := map[int64]Item{}
 	for _, it := range got {
 		byNumber[it.Number] = it
 	}
-	for n, wantReason := range map[int]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
+	for n, wantReason := range map[int64]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
 		if byNumber[n].Reason != wantReason {
 			t.Errorf("issue %d reason = %q, want %q", n, byNumber[n].Reason, wantReason)
 		}
@@ -204,15 +207,15 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("agents", true)},
+		repos: map[string][]Repo{"alterminal": repoWith("agents", true)},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/agents"}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/agents"}},
 			},
 		},
 		comments: map[string][]Comment{
 			// admin（掃描者）10 小時前催促過 → 冷卻中，不列入。
-			"alterminal/agents/1": {{User: User{"admin"}, CreatedAt: at(-600)}},
+			"alterminal/agents/1": {{User: &User{UserName: "admin"}, CreatedAt: iso(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -223,7 +226,7 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 		t.Fatalf("催促冷卻中的項目不應列入，got %v", got)
 	}
 	// 冷卻過了（25 小時前催促）→ 重新列入。
-	src.comments["alterminal/agents/1"] = []Comment{{User: User{"admin"}, CreatedAt: at(-1500)}}
+	src.comments["alterminal/agents/1"] = []Comment{{User: &User{UserName: "admin"}, CreatedAt: iso(-1500)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -240,15 +243,15 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 應以 parent-tracking 列入並附子項摘要；子項本身則是 assignee-idle。
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: at(-700), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
+				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: iso(-700), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
-				7: {Number: 7, Title: "子", State: "open", CreatedAt: at(-650), UpdatedAt: at(-300), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/teai"}},
+				7: {Number: 7, Title: "子", State: "open", CreatedAt: iso(-650), UpdatedAt: iso(-300), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/teai"}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/7": {{User: User{"max"}, CreatedAt: at(-300)}},
+			"alterminal/teai/7": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -286,9 +289,9 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 子項 1 小時前恢復活動 → 父項 last_activity 跟著更新，未達門檻不列入；
 	// 子項本身也不停滯。整份輸出應為空。
 	child := src.issues["alterminal/teai"][7]
-	child.UpdatedAt = at(-60)
+	child.UpdatedAt = iso(-60)
 	src.issues["alterminal/teai"][7] = child
-	src.comments["alterminal/teai/7"] = []Comment{{User: User{"max"}, CreatedAt: at(-60)}}
+	src.comments["alterminal/teai/7"] = []Comment{{User: &User{UserName: "max"}, CreatedAt: iso(-60)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -303,11 +306,11 @@ func TestScanStalledParentTrackingNotChild(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: at(-700), UpdatedAt: at(-600), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
+				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: iso(-700), UpdatedAt: iso(-600), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
-				39: {Number: 39, State: "open", CreatedAt: at(-2000), UpdatedAt: at(-60), Repository: Reference{"alterminal/teai"}},
+				39: {Number: 39, State: "open", CreatedAt: iso(-2000), UpdatedAt: iso(-60), Repository: &Repository{FullName: "alterminal/teai"}},
 			},
 		},
 	}
@@ -345,30 +348,30 @@ func TestScanStalledPullReasons(t *testing.T) {
 	h := true
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
+		repos: map[string][]Repo{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
 		pulls: map[string][]PullRequest{
 			"alterminal/teai": {
-				{Number: 10, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)},
+				{Number: 10, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)},
-				{Number: 11, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
+				{Number: 11, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
-				{Number: 12, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
+				{Number: 12, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
-				{Number: 13, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
+				{Number: 13, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/11": {{User: User{"max"}, CreatedAt: at(-300)}}, // author-idle
+			"alterminal/teai/11": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}}, // author-idle
-			"alterminal/teai/12": {{User: User{"ceo"}, CreatedAt: at(-300)}}, // reviewer-idle
+			"alterminal/teai/12": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}}, // reviewer-idle
-			"alterminal/teai/13": {{User: User{"dan"}, CreatedAt: at(-300)}}, // no-commenter（外部留言）
+			"alterminal/teai/13": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}}, // no-commenter（外部留言）
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
 	}
-	byNumber := map[int]Item{}
+	byNumber := map[int64]Item{}
 	for _, it := range got {
 		byNumber[it.Number] = it
 	}
-	for n, wantReason := range map[int]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
+	for n, wantReason := range map[int64]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
 		item, ok := byNumber[n]
 		if !ok {
 			t.Fatalf("PR %d 應列入，got %v", n, got)
@@ -391,15 +394,15 @@ func TestScanStalledNoPullsFlag(t *testing.T) {
 	h := false
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
+		repos: map[string][]Repo{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/docs": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/docs"}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/docs"}},
 			},
 		},
 		pulls: map[string][]PullRequest{
 			// 即使假資料有 PR，flag 關閉也不應掃。
-			"alterminal/docs": {{Number: 2, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)}},
+			"alterminal/docs": {{Number: 2, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -416,10 +419,10 @@ func TestScanStalledSkipsPRsInIssues(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/teai"}, PullRequest: struct{}{}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/teai"}, PullRequest: &pullMarker{}},
 			},
 		},
 	}
@@ -480,7 +483,7 @@ func TestPullJSON(t *testing.T) {
 // TestScanStalledEmpty 無停滯項目 → 空輸出（CLI 層輸出 []）。
 func TestScanStalledEmpty(t *testing.T) {
 	now := at(0)
-	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repository{"alterminal": repoWith("teai", true)}}
+	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repo{"alterminal": repoWith("teai", true)}}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -501,15 +504,15 @@ func TestScanStalledOrgError(t *testing.T) {
 type errSource struct{}
 
 func (errSource) MyOrganizations() ([]string, error) { return nil, errors.New("boom") }
-func (e errSource) OrganizationRepositories(string) ([]Repository, error) {
+func (e errSource) OrganizationRepositories(string) ([]Repo, error) {
 	return nil, errors.New("boom")
 }
 func (e errSource) OpenIssues(string, string) ([]Issue, error)      { return nil, errors.New("boom") }
 func (e errSource) OpenPulls(string, string) ([]PullRequest, error) { return nil, errors.New("boom") }
-func (e errSource) IssueComments(string, string, int) ([]Comment, error) {
+func (e errSource) IssueComments(string, string, int64) ([]Comment, error) {
 	return nil, errors.New("boom")
 }
-func (e errSource) TryGetIssue(string, string, int) (Issue, bool, error) {
+func (e errSource) TryGetIssue(string, string, int64) (Issue, bool, error) {
 	return Issue{}, false, errors.New("boom")
 }