sync: collector/ 同步自 inkstone/arcrun-rag@1edbbb2（桌面小幫手 0.18.37）

CHANGELOG.md

@@ -47,6 +47,28 @@
 
 ---
 
+## 0.18.37（2026-08-26）
+
+- 🔴 **雲端被清空過的檔案，小幫手現在會自己發現並補送**：以前小幫手送成功一次就會在本機蓋一個「已送」的章，而那個章**永遠不會過期**。萬一雲端被重裝或清空，那批檔案就**再也不會被送上去**，而且沒有任何地方會跟你說——你只會發現「檔案明明在資料夾裡，AI 卻查不到」，而且查不出為什麼。現在它會跟雲端對一次帳，發現那邊沒有就重新送。
+- **重跑第二次不會又全部送一遍**：對完帳之後它分得出「雲端真的沒有」與「我上次送過了」，不會把你的 AI 額度燒掉。
+- **補送的時候看得到**：不會靜悄悄跑完。
+
+## 0.18.36（2026-08-24）
+
+- 🔴 **移除資料夾時，可以順便把我們放進去的隱藏檔案一起清掉**：小幫手整理你的資料夾時，會在**每一層**放一個隱藏的整理稿目錄（`.wiki`／`.arcrun-rag`）。以前你把資料夾從清單移除之後，這些東西**全部留在原地**——隱藏的、散在幾十層裡，你自己幾乎刪不乾淨。現在移除的對話框多了一個勾選框「順便把 Arcrun RAG 放在這個資料夾裡的檔案清掉」，勾起來會**先把確切要刪哪些列給你看**，你看過再按確定。
+- **只刪我們自己建的，你的檔案一個都不會碰**：每一筆都要有我們自己寫下的依據（我們放的說明檔、我們的整理帳本、我們的檔名前綴）才會刪；只要有一個東西認不出來，那整個目錄就原封不動留著，並且在清單上告訴你留了什麼、為什麼留。
+- **這幾種情況我們刻意不刪**：你那個資料夾裡如果還有別的資料夾也在同步清單裡，它底下的東西不碰；以前從你資料夾搬進暫存區的檔案不碰（那些是你的）；捷徑（symlink）不碰。
+- 不勾這個框的話，行為跟以前一模一樣：硬碟上一個檔都不會少。
+
+## 0.18.35（2026-08-24）
+
+- 🔴 **桌面小幫手多了「App 界面」：一打開就是九宮格，點一下就用得到**：以前小幫手只做一件事——把資料夾整理進知識庫；要用知識庫上的 App（例如寫一則筆記），得另外開瀏覽器登入雲端。現在小幫手最上面多了一頁「App 界面」，裡面是**你連的那個知識庫實際裝了的 App**，一個 icon 一個 App，點下去就在小幫手裡打開，不用再開瀏覽器。
+- 這批 App **跟你在知識庫網頁上看到的是同一批**：清單直接跟知識庫要，桌面上不另存一份，所以你在任何一台電腦看到的都一樣；在雲端裝了新 App，回到這裡按「重新整理」就會出現。
+- 沒有自己畫面的 App 也點得開：會列出它能做的事，一條一顆「現在執行」。
+- 連了不只一個知識庫的話，「App 界面」上方可以切換要看哪一個。
+- 還沒連上知識庫、或這個知識庫一個 App 都沒裝，畫面會直接說是哪一種情況，不會只給你一片空白。
+- **原本的功能一項都沒少**：同步狀態與「立刻同步」搬到了每一頁都看得到的最上方，首頁、各知識庫、AI 設定、版本與更新都在側邊欄原來的位置。
+
 ## 0.18.34（2026-08-20）
 
 - 🔴 **雲端現在看得到你資料夾的完整層次，不再只有第一層**：以前不管你的資料夾疊了幾層，雲端只認得最外面那一層——`專案/教育部標案/會議紀錄` 這種放在深處的資料夾，在知識庫裡完全不存在，只會以檔案路徑的一段文字出現。現在**每一層資料夾都有自己的一格**，而且**每一格都連著它的上一層**，所以你可以像在檔案總管裡一樣，從最外層一路點進最深的那個資料夾。每一格還會告訴你這一層直接放了幾份文件、連同底下的子資料夾一共幾份。

cleanup.go

@@ -0,0 +1,543 @@
+// cleanup.go — 斷連時把 daemon 自己寫進使用者資料夾的東西收回來
+// （arcrun-rag#138，leo 2026-08-24：「碎型會在每個資料夾安裝隱藏資料夾，人工刪除不容易，
+// 所以當它斷連，應該要可以幫它把 Arcrun RAG 建立的資料夾刪掉」）。
+//
+// 🔴 這是本 repo 唯一一支會**刪使用者資料夾裡的檔**的程式碼。tidy.go 的紅線是
+// 「一行 os.Remove 都沒有」——那條紅線在這裡不成立（使用者要的就是刪掉），
+// 所以改用另一組更嚴的規矩：
+//
+//	① **只刪帳面上認得出來的東西。** 不靠「路徑看起來像我們的」「副檔名是 .md」
+//	   這類推測——每一筆都要說得出一句**我們自己寫下的證據**（見 CleanupItem.Evidence）。
+//	② **一個認不出來的鄰居，就讓整個目錄留下。** `.wiki/` 裡只要有一個檔不在帳本上、
+//	   也沒有標記，就從「刪整個目錄」降級成「只刪認得出來的那幾個檔」，目錄本身留著。
+//	   ⇒ 誤留一點殘渣是可接受的；誤刪使用者的知識不是。
+//	③ **先看清單再動手。** PlanCleanup 只讀不寫，ApplyCleanup 動手前**重算一次**計畫
+//	   （不吃呼叫端傳回來的舊清單）——畫面上看到的是快照，刪的當下才是真相。
+//
+// 認人的三種證據（全部是 daemon 自己寫下去的字，不是猜的）：
+//
+//	E1 `.arcrun-rag/` 工作區：目錄裡的 `.gitignore` 內容**逐字**等於 workspaceIgnoreBody
+//	   （repoguard.go 寫的那份，自己寫著「整個資料夾可以安全刪除」）。
+//	E2 `.wiki/` 卡片目錄：目錄裡的 `.gitignore` 內容逐字等於 wikiIgnoreBody
+//	   （wikishape.go 寫的，自己寫著「不是你的檔案」），或目錄裡有解析得開的
+//	   `manifest.json`（我們的 wiki 帳本）。
+//	E3 `system-dev/wiki/cards/` 底下帶 MachineMark（`arcrun-`）前綴的檔
+//	   ——machinemark.go 的規約：daemon 在監看根底下產生的每個檔名都帶這個前綴。
+//
+// 🔴 三個**刻意不刪**的東西（每一個都是實查出來的，不是保守而已）：
+//
+//	① `.arcrun-rag/legacy-template/`：那是 tidy.go 的**收容處**，裡面裝的是從使用者
+//	   資料夾**搬進來的檔**。tidy 自己說得很清楚：「TemplateOwns 是路徑身分判準，
+//	   分不出『daemon 鋪的』還是『repo 本來就有的』」⇒ 那些檔的所有權我們判不了。
+//	   而 `.arcrun-rag/.gitignore` 上「整個資料夾可以安全刪除」那句話是 #105 寫的，
+//	   當時工作區裡還沒有收容處。**不把那句話套到收容處上**（#138 紅線第三條問的正是這題）。
+//	② 另一個**還在監看清單裡**的資料夾底下的東西：實務上真的會巢狀
+//	   （2026-08-24 現場：`pms` 與 `pms/pms_v1_legacy` 同時在看守）。移除外層時把內層的
+//	   工作區刪掉＝把一個還在跑的同步弄壞。
+//	③ 任何 symlink：不跟隨、不刪。刪一條指出去的連結會刪到監看根以外的東西。
+package collector
+
+import (
+	"encoding/json"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// 產物分類（給畫面分組用，也是 Apply 的處理方式）。
+const (
+	CleanupKindWorkspace = "workspace"   // `.arcrun-rag/` 工作區（整個目錄）
+	CleanupKindWorkFile  = "work-file"   // 工作區裡的單一項目（收容處存在時的降級路徑）
+	CleanupKindWikiDir   = "wiki-dir"    // `.wiki/` 卡片目錄（整個目錄）
+	CleanupKindWikiFile  = "wiki-file"   // `.wiki/` 裡的單一產物（有陌生鄰居時的降級路徑）
+	CleanupKindMarked    = "marked-card" // 帶 arcrun- 標記的卡片（非隱藏的卡片產物區）
+)
+
+// CleanupItem＝一筆「打算刪掉」的東西。Evidence 是白話的認人依據，會直接顯示給使用者看
+// ——沒有 Evidence 的東西不准進這個清單。
+type CleanupItem struct {
+	Rel      string `json:"rel"` // 相對監看根，斜線分隔
+	IsDir    bool   `json:"is_dir"`
+	Kind     string `json:"kind"`
+	Evidence string `json:"evidence"`
+	Files    int    `json:"files"` // 這一筆底下有幾個檔（目錄才 > 1）
+	Bytes    int64  `json:"bytes"`
+}
+
+// CleanupKeep＝一筆「認得出來但刻意不刪」或「認不出來所以不敢刪」的東西。
+// 這份清單和 Remove 一樣要給使用者看——沉默地留下殘渣，跟沉默地刪掉一樣糟。
+type CleanupKeep struct {
+	Rel    string `json:"rel"`
+	Reason string `json:"reason"`
+}
+
+// CleanupPlan＝一次清理的完整帳目。PlanCleanup 只讀不寫，這份東西就是「動手前的清單」。
+type CleanupPlan struct {
+	Root   string        `json:"root"`
+	Remove []CleanupItem `json:"remove"`
+	Keep   []CleanupKeep `json:"keep"`
+	Files  int           `json:"files"` // Remove 涵蓋的檔案總數
+	Bytes  int64         `json:"bytes"`
+}
+
+// CleanupFailure＝刪不掉的那一筆（權限、檔案正被開著…）。
+type CleanupFailure struct {
+	Rel   string `json:"rel"`
+	Error string `json:"error"`
+}
+
+// CleanupResult＝實際刪掉了什麼。
+type CleanupResult struct {
+	Removed []string         `json:"removed"`
+	Failed  []CleanupFailure `json:"failed"`
+	Files   int              `json:"files"`
+	Bytes   int64            `json:"bytes"`
+}
+
+var cleanupBakRe = regexp.MustCompile(`^(.*)\.bak-\d+$`)
+
+// WorkspaceIgnoreBodyForTest／WikiIgnoreBodyForTest 讓**別的 package 的迴歸網**
+// （cmd/arcrun-app）造得出「與 daemon 真正寫下去一字不差」的宣告檔。
+//
+// 為什麼不讓測試自己抄一份字串：抄的那份會漂。認人的判準是「逐字相等」，
+// 判準與樣本一旦不同源，這兩份 .gitignore 改一個字就會有一整層測試靜默失效。
+// 名字帶 ForTest 是說給讀 code 的人聽的——**production 路徑不准依賴它們**。
+func WorkspaceIgnoreBodyForTest() string { return workspaceIgnoreBody }
+func WikiIgnoreBodyForTest() string      { return wikiIgnoreBody }
+
+// PlanCleanup 列出「把 root 從監看清單移除時，可以連帶收掉的 daemon 產物」。
+//
+// **這支函式不寫任何檔案。** otherRoots＝其他仍在監看清單裡的資料夾（絕對路徑）；
+// 落在它們底下的東西一律不碰（見檔頭不刪清單②）。
+func PlanCleanup(root string, otherRoots []string) (*CleanupPlan, error) {
+	absRoot, err := filepath.Abs(root)
+	if err != nil {
+		return nil, err
+	}
+	absRoot = filepath.Clean(absRoot)
+	if st, serr := os.Lstat(absRoot); serr != nil {
+		return nil, serr
+	} else if !st.IsDir() {
+		return nil, &fs.PathError{Op: "cleanup", Path: absRoot, Err: fs.ErrInvalid}
+	}
+
+	// 只留「真的在 absRoot 底下」的其他根——不在底下的本來就走不到，留著只會拖慢比對。
+	var others []string
+	for _, o := range otherRoots {
+		a, oerr := filepath.Abs(o)
+		if oerr != nil {
+			continue
+		}
+		a = filepath.Clean(a)
+		if a != absRoot && pathWithin(absRoot, a) {
+			others = append(others, a)
+		}
+	}
+
+	p := &cleanupPlanner{
+		root:   absRoot,
+		others: others,
+		cards:  collectWikiCardIndex(absRoot, others),
+		plan:   &CleanupPlan{Root: absRoot},
+	}
+	p.walk(absRoot)
+	sort.Slice(p.plan.Remove, func(i, j int) bool { return p.plan.Remove[i].Rel < p.plan.Remove[j].Rel })
+	sort.Slice(p.plan.Keep, func(i, j int) bool { return p.plan.Keep[i].Rel < p.plan.Keep[j].Rel })
+	return p.plan, nil
+}
+
+// ApplyCleanup 真的動手刪。
+//
+// 🔴 它**重算一次計畫**，不接受呼叫端傳進來的舊清單——使用者看清單、按確定之間可能過了
+// 幾秒或幾分鐘，那段時間裡他可能剛好把一個自己的檔存進 `.wiki/`。畫面上那份是快照，
+// 刪的當下重算的這份才是判準。回傳的 plan 就是實際執行的那一份（呼叫端要顯示就用它）。
+func ApplyCleanup(root string, otherRoots []string) (*CleanupPlan, *CleanupResult, error) {
+	plan, err := PlanCleanup(root, otherRoots)
+	if err != nil {
+		return nil, nil, err
+	}
+	res := &CleanupResult{}
+	// 由深到淺刪：先刪目錄裡的東西，再刪目錄自己（降級路徑會同時出現父目錄底下的多筆）。
+	items := append([]CleanupItem(nil), plan.Remove...)
+	sort.Slice(items, func(i, j int) bool { return len(items[i].Rel) > len(items[j].Rel) })
+	for _, it := range items {
+		abs := filepath.Join(plan.Root, filepath.FromSlash(it.Rel))
+		// 最後一道機械閘：不管計畫怎麼算的，目標一定要在監看根底下，而且不是 symlink。
+		if !pathWithin(plan.Root, abs) {
+			res.Failed = append(res.Failed, CleanupFailure{Rel: it.Rel, Error: "路徑不在這個資料夾底下，沒有刪"})
+			continue
+		}
+		st, serr := os.Lstat(abs)
+		if serr != nil {
+			if os.IsNotExist(serr) {
+				continue // 已經不在了（重複按、或上一輪刪過）＝不是失敗
+			}
+			res.Failed = append(res.Failed, CleanupFailure{Rel: it.Rel, Error: serr.Error()})
+			continue
+		}
+		if st.Mode()&os.ModeSymlink != 0 {
+			res.Failed = append(res.Failed, CleanupFailure{Rel: it.Rel, Error: "這是一條捷徑（symlink），沒有刪"})
+			continue
+		}
+		var derr error
+		if it.IsDir {
+			derr = os.RemoveAll(abs)
+		} else {
+			derr = os.Remove(abs)
+		}
+		if derr != nil {
+			res.Failed = append(res.Failed, CleanupFailure{Rel: it.Rel, Error: derr.Error()})
+			continue
+		}
+		res.Removed = append(res.Removed, it.Rel)
+		res.Files += it.Files
+		res.Bytes += it.Bytes
+	}
+	sort.Strings(res.Removed)
+	return plan, res, nil
+}
+
+// ── 以下是實作細節 ────────────────────────────────────────────────
+
+type cleanupPlanner struct {
+	root   string
+	others []string
+	cards  map[string]bool // 帳本上每張卡的絕對路徑
+	plan   *CleanupPlan
+}
+
+func (p *cleanupPlanner) rel(abs string) string {
+	r, err := filepath.Rel(p.root, abs)
+	if err != nil {
+		return filepath.ToSlash(abs)
+	}
+	return filepath.ToSlash(r)
+}
+
+func (p *cleanupPlanner) remove(abs, kind, evidence string, isDir bool) {
+	files, bytes := countTree(abs)
+	p.plan.Remove = append(p.plan.Remove, CleanupItem{
+		Rel: p.rel(abs), IsDir: isDir, Kind: kind, Evidence: evidence, Files: files, Bytes: bytes,
+	})
+	p.plan.Files += files
+	p.plan.Bytes += bytes
+}
+
+func (p *cleanupPlanner) keep(abs, reason string) {
+	p.plan.Keep = append(p.plan.Keep, CleanupKeep{Rel: p.rel(abs), Reason: reason})
+}
+
+// walk 走整棵樹。刻意**不用 filepath.WalkDir**：我們要在「進不進去某個目錄」這件事上
+// 完全自己說了算（其他隱藏目錄整棵跳過、別的監看根整棵跳過、symlink 不跟隨）。
+func (p *cleanupPlanner) walk(dir string) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		abs := filepath.Join(dir, e.Name())
+		if e.Type()&os.ModeSymlink != 0 {
+			continue // 捷徑一律不碰（可能指到監看根以外）
+		}
+		if !e.IsDir() {
+			continue // 目錄以外的檔，只有在下面那幾個已認定的目錄裡才會被處理
+		}
+		if p.underOtherRoot(abs) {
+			p.keep(abs, "這個資料夾也還在同步清單裡，它底下的東西留給它自己管")
+			continue
+		}
+		switch e.Name() {
+		case workspaceRelDir:
+			p.planWorkspace(abs)
+			continue
+		case wikiRelDir:
+			p.planWikiDir(abs)
+			continue
+		}
+		if strings.HasPrefix(e.Name(), ".") {
+			continue // 其他隱藏目錄整棵跳過——daemon 的 Scan 也不進去，那裡不會有我們的東西
+		}
+		if p.rel(abs) == cardsRelDir {
+			p.planMarkedCards(abs)
+			continue
+		}
+		p.walk(abs)
+	}
+}
+
+func (p *cleanupPlanner) underOtherRoot(abs string) bool {
+	for _, o := range p.others {
+		if abs == o || pathWithin(o, abs) {
+			return true
+		}
+	}
+	return false
+}
+
+// planWorkspace 處理 `.arcrun-rag/`。
+func (p *cleanupPlanner) planWorkspace(abs string) {
+	if !fileHasExactBody(filepath.Join(abs, ".gitignore"), workspaceIgnoreBody) {
+		p.keep(abs, "這個 .arcrun-rag 目錄裡沒有我們寫的 .gitignore 宣告，認不出是不是我們建的，所以不動它")
+		return
+	}
+	const ev = "目錄裡的 .gitignore 逐字等於我們寫的那份（自己寫著「整個資料夾可以安全刪除」）"
+
+	quarantine := filepath.Join(abs, "legacy-template")
+	if st, err := os.Lstat(quarantine); err == nil && st.IsDir() && !isEmptyDir(quarantine) {
+		// 收容處裡是「從你的資料夾搬進來的檔」⇒ 整個目錄不能一次刪，改成逐項刪、留下收容處。
+		p.keep(quarantine, "這裡面是以前從你的資料夾搬進來的檔案（不是我們產生的），所有權判不了，一律留著讓你自己處理")
+		entries, err := os.ReadDir(abs)
+		if err != nil {
+			return
+		}
+		for _, e := range entries {
+			if e.Name() == "legacy-template" {
+				continue
+			}
+			child := filepath.Join(abs, e.Name())
+			if e.Type()&os.ModeSymlink != 0 {
+				p.keep(child, "這是一條捷徑（symlink），不碰")
+				continue
+			}
+			p.remove(child, CleanupKindWorkFile, ev, e.IsDir())
+		}
+		return
+	}
+	p.remove(abs, CleanupKindWorkspace, ev, true)
+}
+
+// planWikiDir 處理一個 `.wiki/`。
+//
+// 兩步：① 這個目錄是不是我們的（要有我們寫下的宣告）② 裡面**每一個**東西是不是都認得。
+// 第二步是這支函式的重點——認得全部才刪整個目錄，有一個認不得就降級成逐檔刪。
+func (p *cleanupPlanner) planWikiDir(abs string) {
+	evidence := ""
+	if fileHasExactBody(filepath.Join(abs, ".gitignore"), wikiIgnoreBody) {
+		evidence = "目錄裡的 .gitignore 逐字等於我們寫的那份（自己寫著「這個資料夾是 Arcrun RAG 產生的 wiki，不是你的檔案」）"
+	} else if isOurWikiManifest(filepath.Join(abs, "manifest.json")) {
+		evidence = "目錄裡有我們寫的 manifest.json（wiki 帳本，記著每張卡對應哪份原稿）"
+	} else {
+		p.keep(abs, "這個 .wiki 目錄裡既沒有我們寫的 .gitignore、也沒有我們的 manifest.json，認不出是不是我們建的，所以不動它")
+		return
+	}
+
+	entries, err := os.ReadDir(abs)
+	if err != nil {
+		p.keep(abs, "讀不到這個目錄的內容（"+err.Error()+"），所以不動它")
+		return
+	}
+	type known struct {
+		name  string
+		isDir bool
+	}
+	var ours []known
+	var strangers []string
+	accounted := map[string]bool{}
+	for _, e := range entries {
+		if p.wikiEntryIsOurs(abs, e) {
+			accounted[e.Name()] = true
+		}
+	}
+	for _, e := range entries {
+		if accounted[e.Name()] {
+			ours = append(ours, known{e.Name(), e.IsDir()})
+			continue
+		}
+		// `.bak-<unixnano>` 是 safeWriteCard 的備份：本體認得，它就認得。
+		if m := cleanupBakRe.FindStringSubmatch(e.Name()); m != nil && accounted[m[1]] {
+			ours = append(ours, known{e.Name(), e.IsDir()})
+			continue
+		}
+		strangers = append(strangers, e.Name())
+	}
+
+	if len(strangers) == 0 {
+		p.remove(abs, CleanupKindWikiDir, evidence, true)
+		return
+	}
+	// 降級：只刪認得出來的那幾個，目錄與陌生鄰居原封不動。
+	for _, k := range ours {
+		p.remove(filepath.Join(abs, k.name), CleanupKindWikiFile, evidence, k.isDir)
+	}
+	for _, s := range strangers {
+		p.keep(filepath.Join(abs, s), "這個檔不在我們的帳本上、也沒有 arcrun- 標記——可能是你自己放進來的，留著")
+	}
+}
+
+// wikiEntryIsOurs 回答「`.wiki/` 裡的這一項是不是我們寫的」。四條路，全部要拿得出證據。
+func (p *cleanupPlanner) wikiEntryIsOurs(dir string, e os.DirEntry) bool {
+	if e.Type()&os.ModeSymlink != 0 {
+		return false // 捷徑一律不算我們的
+	}
+	abs := filepath.Join(dir, e.Name())
+	if e.IsDir() {
+		return false // 我們從來不在 .wiki/ 底下開子目錄
+	}
+	switch {
+	case e.Name() == ".gitignore":
+		return fileHasExactBody(abs, wikiIgnoreBody)
+	case e.Name() == "manifest.json":
+		return isOurWikiManifest(abs)
+	case e.Name() == "00-INDEX.md":
+		return fileHasPrefix(abs, "# 00-INDEX")
+	case p.cards[abs]:
+		return true // 帳本上有這張卡
+	case IsMarked(e.Name()):
+		return true // machinemark.go 的規約前綴
+	}
+	return false
+}
+
+// planMarkedCards 處理 `system-dev/wiki/cards/`——那是**看得見**的卡片產物區
+// （監看根不在筆記庫也不在版控時的落點）。這裡不刪目錄，只刪帶標記的檔：
+// 那個目錄是 system-dev-template 的規約路徑，使用者自己的卡也住在那裡（#105 的教訓）。
+func (p *cleanupPlanner) planMarkedCards(abs string) {
+	_ = filepath.WalkDir(abs, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() || d.Type()&os.ModeSymlink != 0 {
+			return nil
+		}
+		if IsMarked(d.Name()) {
+			p.remove(path, CleanupKindMarked, "檔名帶 arcrun- 標記——daemon 產生的每個檔都帶這個前綴（machinemark.go 規約）", false)
+		}
+		return nil
+	})
+}
+
+// collectWikiCardIndex 把樹裡每一份 `.wiki/manifest.json` 讀出來，攤成「這些絕對路徑是我們的卡」。
+//
+// 為什麼要掃整棵樹而不是只讀監看根那一份：實務上樹裡會有**別的監看根**留下的帳本
+// （`pms/pms_v1_legacy/.wiki/manifest.json`）。帳本裡的卡路徑是相對**它自己的根**
+// （＝那個 `.wiki` 的上層目錄），所以每份帳本各自解析。
+func collectWikiCardIndex(absRoot string, others []string) map[string]bool {
+	out := map[string]bool{}
+	var walk func(dir string)
+	walk = func(dir string) {
+		entries, err := os.ReadDir(dir)
+		if err != nil {
+			return
+		}
+		for _, e := range entries {
+			if !e.IsDir() || e.Type()&os.ModeSymlink != 0 {
+				continue
+			}
+			abs := filepath.Join(dir, e.Name())
+			if e.Name() == wikiRelDir {
+				addManifestCards(out, abs)
+				continue
+			}
+			if strings.HasPrefix(e.Name(), ".") {
+				continue
+			}
+			walk(abs)
+		}
+	}
+	walk(absRoot)
+	// 別的監看根底下那份帳本也要讀——它記的卡可能落在**我們這一側**（節點在共同祖先下）。
+	// 讀帳本是純讀取，不代表會刪那邊的東西（刪不刪由 underOtherRoot 決定）。
+	for _, o := range others {
+		addManifestCards(out, filepath.Join(o, wikiRelDir))
+	}
+	return out
+}
+
+func addManifestCards(out map[string]bool, wikiDir string) {
+	path := filepath.Join(wikiDir, "manifest.json")
+	m, ok := readOurWikiManifest(path)
+	if !ok {
+		return
+	}
+	owner := filepath.Dir(wikiDir) // 帳本裡的路徑相對這一層
+	for _, d := range m.Docs {
+		for _, c := range d.Cards {
+			c = strings.TrimSpace(c)
+			if c == "" || strings.Contains(c, "..") || filepath.IsAbs(filepath.FromSlash(c)) {
+				continue // 帳本被改壞時不讓它把我們指到樹外面
+			}
+			out[filepath.Join(owner, filepath.FromSlash(c))] = true
+		}
+	}
+}
+
+func readOurWikiManifest(path string) (*wikiManifest, bool) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, false
+	}
+	var m wikiManifest
+	if json.Unmarshal(data, &m) != nil {
+		return nil, false
+	}
+	// 認的是形狀，不是「檔名叫 manifest.json」：要有版本號，而且每筆 doc 都要有我們的鍵。
+	if m.Version <= 0 {
+		return nil, false
+	}
+	for _, d := range m.Docs {
+		if d.Node == "" || d.DocID == "" {
+			return nil, false
+		}
+	}
+	return &m, true
+}
+
+func isOurWikiManifest(path string) bool {
+	_, ok := readOurWikiManifest(path)
+	return ok
+}
+
+// fileHasExactBody：檔案內容**逐字**等於 want。逐字比對是刻意的——「開頭像」不夠，
+// 有人可能在我們的宣告後面接自己的規則，那份 .gitignore 就不只是我們的了。
+func fileHasExactBody(path, want string) bool {
+	data, err := os.ReadFile(path)
+	return err == nil && string(data) == want
+}
+
+func fileHasPrefix(path, want string) bool {
+	f, err := os.Open(path)
+	if err != nil {
+		return false
+	}
+	defer f.Close()
+	buf := make([]byte, len(want))
+	n, _ := f.Read(buf)
+	return n == len(want) && string(buf) == want
+}
+
+// pathWithin 回答 child 是不是 parent 底下（不含 parent 自己）。純字串比對，
+// 呼叫端傳進來的都已經是 Abs+Clean 過的路徑。
+func pathWithin(parent, child string) bool {
+	rel, err := filepath.Rel(parent, child)
+	if err != nil {
+		return false
+	}
+	return rel != "." && !strings.HasPrefix(rel, "..") && !filepath.IsAbs(rel)
+}
+
+func isEmptyDir(dir string) bool {
+	entries, err := os.ReadDir(dir)
+	return err == nil && len(entries) == 0
+}
+
+// countTree 算一筆刪除目標涵蓋幾個檔、多少位元組（給清單顯示「會刪掉 N 個檔」）。
+func countTree(abs string) (files int, bytes int64) {
+	st, err := os.Lstat(abs)
+	if err != nil {
+		return 0, 0
+	}
+	if !st.IsDir() {
+		return 1, st.Size()
+	}
+	_ = filepath.WalkDir(abs, func(_ string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil
+		}
+		if info, ierr := d.Info(); ierr == nil {
+			files++
+			bytes += info.Size()
+		}
+		return nil
+	})
+	return files, bytes
+}

cleanup_cli.go

@@ -0,0 +1,95 @@
+// cleanup_cli.go — `collector cleanup` 子命令（arcrun-rag#138）。
+//
+// 為什麼 App 之外還要有一支 CLI：#138 的驗收條件是「使用者要能在動手前看到將要刪掉
+// 哪些東西」。畫面上那份清單與這支印出來的是**同一個 PlanCleanup**——
+// 一份判斷邏輯兩個出口，不會出現「畫面說會刪 A、實際刪了 B」。
+// 而且出事時（畫面按鈕壞掉、使用者不信任 GUI）他仍然有一條看得見全部細節的路。
+package collector
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// multiFlag 讓 --keep 可以重複給（其他還在看守的資料夾）。
+type multiFlag []string
+
+func (m *multiFlag) String() string     { return strings.Join(*m, ",") }
+func (m *multiFlag) Set(v string) error { *m = append(*m, v); return nil }
+
+func runCleanup(args []string) int {
+	fs2 := newFlagSet()
+	folder := fs2.String("folder", "", "要斷連的資料夾（必填）")
+	apply := fs2.Bool("apply", false, "真的刪（不加＝只列清單，什麼都不動）")
+	asJSON := fs2.Bool("json", false, "輸出 JSON（給程式讀）")
+	var keep multiFlag
+	fs2.Var(&keep, "keep", "其他還在看守的資料夾（可重複給）——它們底下的東西一律不碰")
+	if err := fs2.Parse(args); err != nil {
+		return 2
+	}
+	if *folder == "" {
+		fmt.Fprintln(os.Stderr, "錯誤：--folder 為必填")
+		return 2
+	}
+
+	var plan *CleanupPlan
+	var res *CleanupResult
+	var err error
+	if *apply {
+		plan, res, err = ApplyCleanup(*folder, keep)
+	} else {
+		plan, err = PlanCleanup(*folder, keep)
+	}
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "collector cleanup:", err)
+		return 1
+	}
+
+	if *asJSON {
+		out := struct {
+			Plan   *CleanupPlan   `json:"plan"`
+			Result *CleanupResult `json:"result,omitempty"`
+		}{plan, res}
+		data, _ := json.MarshalIndent(out, "", "  ")
+		fmt.Println(string(data))
+		if res != nil && len(res.Failed) > 0 {
+			return 1
+		}
+		return 0
+	}
+
+	fmt.Println(plan.Root)
+	if len(plan.Remove) == 0 {
+		fmt.Println("沒有找到任何 Arcrun RAG 建立的東西——這個資料夾不需要清理。")
+	} else {
+		if !*apply {
+			fmt.Println("※ 這只是清單，什麼都還沒刪。確認沒問題後，同一行指令加上 --apply 才會真的刪。")
+		}
+		fmt.Printf("會刪掉 %d 項（共 %d 個檔）：\n", len(plan.Remove), plan.Files)
+		for _, it := range plan.Remove {
+			mark := "檔"
+			if it.IsDir {
+				mark = "目錄"
+			}
+			fmt.Printf("  刪 %s  %s（%d 個檔）\n      依據：%s\n", mark, it.Rel, it.Files, it.Evidence)
+		}
+	}
+	if len(plan.Keep) > 0 {
+		fmt.Printf("留著不動 %d 項：\n", len(plan.Keep))
+		for _, k := range plan.Keep {
+			fmt.Printf("  留 %s\n      原因：%s\n", k.Rel, k.Reason)
+		}
+	}
+	if res != nil {
+		fmt.Printf("實際刪掉 %d 項 / %d 個檔。\n", len(res.Removed), res.Files)
+		for _, f := range res.Failed {
+			fmt.Printf("  ✗ 刪不掉 %s（%s）\n", f.Rel, f.Error)
+		}
+		if len(res.Failed) > 0 {
+			return 1
+		}
+	}
+	return 0
+}

cleanup_test.go

@@ -0,0 +1,429 @@
+// cleanup_test.go — 斷連清理的迴歸網（arcrun-rag#138）。
+//
+// 這支測的重點**不是「有沒有刪掉」**，是「**有沒有刪到不該刪的**」。
+// 每一個 case 都對應一種「差一點就誤刪使用者知識」的擺法。
+package collector
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+func cuWriteFile(t *testing.T, path, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// makeWiki 造一個「長得跟 daemon 產的一模一樣」的 .wiki 目錄。
+func makeWiki(t *testing.T, dir string, cards ...string) {
+	t.Helper()
+	cuWriteFile(t, filepath.Join(dir, ".gitignore"), wikiIgnoreBody)
+	cuWriteFile(t, filepath.Join(dir, "00-INDEX.md"), "# 00-INDEX\n\n## 文件\n")
+	for _, c := range cards {
+		cuWriteFile(t, filepath.Join(dir, c), "# "+strings.TrimSuffix(c, ".md")+"\n")
+	}
+}
+
+// makeRootManifest 寫出監看根那一份 `.wiki/manifest.json`（帳本）。
+// nodeCards＝節點 →「相對監看根」的卡片路徑，跟 daemon 實際寫的形狀一致
+// （2026-08-24 對照 `pms` 現場的真檔驗過：帳本涵蓋每一張卡，只有 00-INDEX.md 不在裡面）。
+func makeRootManifest(t *testing.T, root string, nodeCards map[string][]string) {
+	t.Helper()
+	m := &wikiManifest{Version: 1}
+	for node, cards := range nodeCards {
+		m.Docs = append(m.Docs, wikiDoc{
+			Node: nodeKeyOf(node), Path: "來源.md", DocID: "doc-" + node + "-1",
+			Status: "extracted", Cards: cards,
+		})
+	}
+	data, err := json.MarshalIndent(m, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	cuWriteFile(t, filepath.Join(root, wikiRelDir, "manifest.json"), string(data)+"\n")
+}
+
+func makeWorkspace(t *testing.T, root string) {
+	t.Helper()
+	cuWriteFile(t, filepath.Join(root, workspaceRelDir, ".gitignore"), workspaceIgnoreBody)
+	cuWriteFile(t, filepath.Join(root, workspaceRelDir, "wiki", "cards", "arcrun-資料夾總覽-x.md"), "# x\n")
+}
+
+func relsOf(items []CleanupItem) []string {
+	out := make([]string, 0, len(items))
+	for _, it := range items {
+		out = append(out, it.Rel)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func keepRels(keeps []CleanupKeep) []string {
+	out := make([]string, 0, len(keeps))
+	for _, k := range keeps {
+		out = append(out, k.Rel)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// snapshotTree 記下整棵樹每個檔的相對路徑與內容雜湊——用來證明「使用者的檔一個都沒動」。
+func cuSnapshotTree(t *testing.T, root string) map[string]string {
+	t.Helper()
+	out := map[string]string{}
+	err := filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return nil
+		}
+		rel, _ := filepath.Rel(root, p)
+		data, rerr := os.ReadFile(p)
+		if rerr != nil {
+			return nil
+		}
+		out[filepath.ToSlash(rel)] = string(data)
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+// ── ① 基本盤：多層巢狀的 .wiki 與工作區全部收掉，使用者的原稿一個不少 ──
+
+func TestCleanupRemovesNestedProductsKeepsUserFiles(t *testing.T) {
+	root := t.TempDir()
+	// 使用者的東西
+	cuWriteFile(t, filepath.Join(root, "README.md"), "我的說明\n")
+	cuWriteFile(t, filepath.Join(root, "docs", "設計.md"), "我的設計\n")
+	cuWriteFile(t, filepath.Join(root, "docs", "deep", "更深的.md"), "我的深層檔\n")
+	// daemon 的東西（三層）
+	makeWorkspace(t, root)
+	makeWiki(t, filepath.Join(root, wikiRelDir), "根卡.md")
+	makeWiki(t, filepath.Join(root, "docs", wikiRelDir), "設計卡.md")
+	makeWiki(t, filepath.Join(root, "docs", "deep", wikiRelDir), "深卡.md")
+	makeRootManifest(t, root, map[string][]string{
+		"":          {".wiki/根卡.md"},
+		"docs":      {"docs/.wiki/設計卡.md"},
+		"docs/deep": {"docs/deep/.wiki/深卡.md"},
+	})
+
+	before := cuSnapshotTree(t, root)
+
+	plan, res, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("不該有刪不掉的：%+v", res.Failed)
+	}
+	want := []string{".arcrun-rag", ".wiki", "docs/.wiki", "docs/deep/.wiki"}
+	if got := relsOf(plan.Remove); !equalStrings(got, want) {
+		t.Fatalf("要刪的清單不對\n got=%v\nwant=%v", got, want)
+	}
+
+	after := cuSnapshotTree(t, root)
+	// 使用者的檔：逐一比對「內容一字不差」。
+	for _, rel := range []string{"README.md", "docs/設計.md", "docs/deep/更深的.md"} {
+		if after[rel] != before[rel] {
+			t.Fatalf("使用者的檔被動到了：%s（before=%q after=%q）", rel, before[rel], after[rel])
+		}
+	}
+	// 剩下的檔**只能是**使用者那三個。
+	if len(after) != 3 {
+		t.Fatalf("清完之後應該只剩使用者的 3 個檔，實際剩 %d：%v", len(after), after)
+	}
+	for _, hidden := range []string{".wiki", ".arcrun-rag", "docs/.wiki", "docs/deep/.wiki"} {
+		if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(hidden))); !os.IsNotExist(err) {
+			t.Fatalf("%s 沒被刪掉", hidden)
+		}
+	}
+}
+
+// ── ② 陌生鄰居：.wiki 裡有一個不是我們的檔 ⇒ 整個目錄留下，只刪認得的 ──
+
+func TestCleanupKeepsWikiDirWithStrangerFile(t *testing.T) {
+	root := t.TempDir()
+	wiki := filepath.Join(root, wikiRelDir)
+	makeWiki(t, wiki, "卡.md")
+	makeRootManifest(t, root, map[string][]string{"": {".wiki/卡.md"}})
+	cuWriteFile(t, filepath.Join(wiki, "我自己寫的.md"), "這是我的\n")
+
+	plan, res, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = res
+	for _, it := range plan.Remove {
+		if it.Kind == CleanupKindWikiDir {
+			t.Fatalf("有陌生鄰居時不准整個目錄刪掉：%+v", it)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(wiki, "我自己寫的.md")); err != nil {
+		t.Fatalf("使用者自己的檔被刪了：%v", err)
+	}
+	if _, err := os.Stat(wiki); err != nil {
+		t.Fatalf(".wiki 目錄不該被刪：%v", err)
+	}
+	// 帳本以外的檔（00-INDEX 與 .gitignore 是我們的）該刪掉。
+	if _, err := os.Stat(filepath.Join(wiki, "00-INDEX.md")); !os.IsNotExist(err) {
+		t.Fatalf("00-INDEX.md 應該被刪掉")
+	}
+	if !contains(keepRels(plan.Keep), ".wiki/我自己寫的.md") {
+		t.Fatalf("留下的東西要出現在 Keep 清單上讓使用者看到：%v", keepRels(plan.Keep))
+	}
+}
+
+// ── ③ 沒有我們宣告的 .wiki（使用者自己的同名目錄）⇒ 一個檔都不碰 ──
+
+func TestCleanupIgnoresForeignWikiDir(t *testing.T) {
+	root := t.TempDir()
+	wiki := filepath.Join(root, wikiRelDir)
+	cuWriteFile(t, filepath.Join(wiki, "我的筆記.md"), "我的\n")
+	cuWriteFile(t, filepath.Join(wiki, "00-INDEX.md"), "# 00-INDEX\n") // 連名字都一樣也不行
+
+	before := cuSnapshotTree(t, root)
+	plan, _, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Remove) != 0 {
+		t.Fatalf("沒有我們的宣告就一個都不准刪：%v", relsOf(plan.Remove))
+	}
+	if got := cuSnapshotTree(t, root); len(got) != len(before) {
+		t.Fatalf("樹被動到了：before=%v after=%v", before, got)
+	}
+}
+
+// ── ④ .gitignore 被使用者改過（後面加了自己的規則）⇒ 不算我們的宣告 ──
+
+func TestCleanupRequiresExactIgnoreBody(t *testing.T) {
+	root := t.TempDir()
+	wiki := filepath.Join(root, wikiRelDir)
+	makeWiki(t, wiki, "卡.md")
+	cuWriteFile(t, filepath.Join(wiki, ".gitignore"), wikiIgnoreBody+"\n!我要收版控的.md\n")
+
+	plan, err := PlanCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Remove) != 0 {
+		t.Fatalf(".gitignore 被改過就不該認：%v", relsOf(plan.Remove))
+	}
+}
+
+// ── ⑤ 工作區裡有 legacy-template 收容處 ⇒ 收容處留著，其餘刪 ──
+
+func TestCleanupKeepsLegacyTemplateQuarantine(t *testing.T) {
+	root := t.TempDir()
+	makeWorkspace(t, root)
+	quar := filepath.Join(root, legacyTemplateRelDir, "system-dev", "wiki", "status.md")
+	cuWriteFile(t, quar, "使用者的舊 status\n")
+
+	plan, res, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("不該有失敗：%+v", res.Failed)
+	}
+	if _, err := os.Stat(quar); err != nil {
+		t.Fatalf("收容處裡的檔被刪了——那是從使用者資料夾搬進來的：%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(root, workspaceRelDir, "wiki")); !os.IsNotExist(err) {
+		t.Fatalf("工作區裡我們自己的東西該刪掉")
+	}
+	if !contains(keepRels(plan.Keep), ".arcrun-rag/legacy-template") {
+		t.Fatalf("收容處要出現在 Keep 清單：%v", keepRels(plan.Keep))
+	}
+}
+
+// ── ⑥ 另一個還在看守的巢狀根 ⇒ 它底下的東西一個都不碰（2026-08-24 pms 現場擺法）──
+
+func TestCleanupSkipsOtherWatchedRoot(t *testing.T) {
+	root := t.TempDir()
+	inner := filepath.Join(root, "legacy")
+	makeWorkspace(t, root)
+	makeWiki(t, filepath.Join(root, wikiRelDir), "外卡.md")
+	makeRootManifest(t, root, map[string][]string{"": {".wiki/外卡.md"}})
+	makeWorkspace(t, inner)
+	makeWiki(t, filepath.Join(inner, wikiRelDir), "內卡.md")
+	makeWiki(t, filepath.Join(inner, "sub", wikiRelDir), "更內卡.md")
+	makeRootManifest(t, inner, map[string][]string{
+		"":    {".wiki/內卡.md"},
+		"sub": {"sub/.wiki/更內卡.md"},
+	})
+
+	plan, res, err := ApplyCleanup(root, []string{inner})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("不該有失敗：%+v", res.Failed)
+	}
+	for _, rel := range relsOf(plan.Remove) {
+		if strings.HasPrefix(rel, "legacy/") {
+			t.Fatalf("動到另一個還在看守的根：%s", rel)
+		}
+	}
+	for _, p := range []string{
+		filepath.Join(inner, workspaceRelDir, ".gitignore"),
+		filepath.Join(inner, wikiRelDir, "內卡.md"),
+		filepath.Join(inner, "sub", wikiRelDir, "更內卡.md"),
+	} {
+		if _, err := os.Stat(p); err != nil {
+			t.Fatalf("還在看守的資料夾底下的東西被刪了：%s（%v）", p, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(root, wikiRelDir)); !os.IsNotExist(err) {
+		t.Fatalf("外層自己的 .wiki 該刪掉")
+	}
+}
+
+// ── ⑦ 看得見的卡片產物區：只刪帶 arcrun- 標記的檔，目錄與別人的卡不動 ──
+
+func TestCleanupMarkedCardsOnly(t *testing.T) {
+	root := t.TempDir()
+	cards := filepath.Join(root, filepath.FromSlash(cardsRelDir))
+	cuWriteFile(t, filepath.Join(cards, "arcrun-機器卡.md"), "# 機器卡\n")
+	cuWriteFile(t, filepath.Join(cards, "leo自己的卡.md"), "# 我的\n")
+	cuWriteFile(t, filepath.Join(root, "system-dev", "wiki", "status.md"), "我的 status\n")
+
+	_, res, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("不該有失敗：%+v", res.Failed)
+	}
+	if _, err := os.Stat(filepath.Join(cards, "arcrun-機器卡.md")); !os.IsNotExist(err) {
+		t.Fatalf("帶標記的卡該刪掉")
+	}
+	for _, p := range []string{
+		filepath.Join(cards, "leo自己的卡.md"),
+		filepath.Join(root, "system-dev", "wiki", "status.md"),
+		cards,
+	} {
+		if _, err := os.Stat(p); err != nil {
+			t.Fatalf("不該動的東西被動了：%s（%v）", p, err)
+		}
+	}
+}
+
+// ── ⑧ symlink 不跟隨、不刪（指出去的連結會刪到監看根以外）──
+
+func TestCleanupNeverFollowsSymlink(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	cuWriteFile(t, filepath.Join(outside, "外面的重要檔.md"), "別碰\n")
+	makeWiki(t, filepath.Join(root, wikiRelDir), "卡.md")
+	if err := os.Symlink(outside, filepath.Join(root, "捷徑")); err != nil {
+		t.Skipf("這台建不了 symlink：%v", err)
+	}
+	// 連 .wiki 自己是條捷徑的情況也擋
+	link2 := filepath.Join(root, "sub", wikiRelDir)
+	if err := os.MkdirAll(filepath.Join(root, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(outside, link2); err != nil {
+		t.Fatal(err)
+	}
+
+	plan, res, err := ApplyCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("不該有失敗：%+v", res.Failed)
+	}
+	for _, rel := range relsOf(plan.Remove) {
+		if strings.HasPrefix(rel, "捷徑") || strings.HasPrefix(rel, "sub/") {
+			t.Fatalf("動到 symlink：%s", rel)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(outside, "外面的重要檔.md")); err != nil {
+		t.Fatalf("監看根以外的檔被刪了：%v", err)
+	}
+}
+
+// ── ⑨ PlanCleanup 保證不寫檔（「先看清單」的前提就是看清單這件事本身無副作用）──
+
+func TestPlanCleanupWritesNothing(t *testing.T) {
+	root := t.TempDir()
+	cuWriteFile(t, filepath.Join(root, "我的.md"), "x\n")
+	makeWorkspace(t, root)
+	makeWiki(t, filepath.Join(root, wikiRelDir), "卡.md")
+	makeWiki(t, filepath.Join(root, "docs", wikiRelDir), "卡2.md")
+
+	before := cuSnapshotTree(t, root)
+	plan, err := PlanCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Remove) == 0 {
+		t.Fatal("這份擺法應該找得到東西")
+	}
+	after := cuSnapshotTree(t, root)
+	if len(before) != len(after) {
+		t.Fatalf("PlanCleanup 動了檔案：before=%d after=%d", len(before), len(after))
+	}
+	for k, v := range before {
+		if after[k] != v {
+			t.Fatalf("PlanCleanup 改了 %s", k)
+		}
+	}
+	// 每一筆都要說得出依據——沒依據的東西不准進清單。
+	for _, it := range plan.Remove {
+		if strings.TrimSpace(it.Evidence) == "" {
+			t.Fatalf("這一筆沒有依據：%+v", it)
+		}
+	}
+}
+
+// ── ⑩ 帳本認卡：卡名不帶標記、也不是 00-INDEX，靠 manifest.json 認出來 ──
+
+func TestCleanupAccountsCardsViaManifest(t *testing.T) {
+	root := t.TempDir()
+	wiki := filepath.Join(root, wikiRelDir)
+	cuWriteFile(t, filepath.Join(wiki, "手動卡.md"), "# 手動卡\n")
+	cuWriteFile(t, filepath.Join(wiki, "manifest.json"), `{"version":1,"docs":[
+		{"node":"(根)","path":"a.md","doc_id":"abc","status":"extracted","cards":[".wiki/手動卡.md"]}]}`)
+	// 故意不放 .gitignore ⇒ 只能靠帳本認人
+	plan, err := PlanCleanup(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := relsOf(plan.Remove); !equalStrings(got, []string{".wiki"}) {
+		t.Fatalf("帳本上的卡＋帳本自己＝全部認得，應該整個目錄刪掉，實際 %v（keep=%v）", got, keepRels(plan.Keep))
+	}
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func contains(ss []string, want string) bool {
+	for _, s := range ss {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}

cloud_audit.go

@@ -0,0 +1,284 @@
+// cloud_audit.go — 本機帳本 ↔ 雲端索引對帳（`inkstone/arcrun-rag#140`）。
+//
+// 病（`inkstone/Arcrun#165` 斷點一，2026-08-26 實測）：
+//
+//	本機 manifest 蓋的「已送成功」章**永遠不會過期**。雲端在 2026-08-14 被重裝／清空之後，
+//	那些檔案的 content_hash 沒變 ⇒ Scan() 不產生事件 ⇒ **永遠不會重送**，
+//	而且**沒有任何地方會說話**。使用者看到的是「檔案明明在資料夾裡，AI 卻查不到」。
+//	實據：youlinhsieh-test1 的 8 個檔 ingested_at 落在 07-29~08-06、零 fail_count，
+//	雲端 D1 的 MIN(created_at) 卻是 08-14 20:27 ⇒ 分界線乾淨得可怕。
+//
+// 解的形狀（**不是把兩邊砍掉重來**，那是紅線）：
+//
+//	章不再是「我送過了」，而是「我送過了**而且雲端現在還有**」。
+//	後半句本機答不出來，只能去問雲端 ⇒ 這支檔就是那個問句。
+//
+// 為什麼問得起（不必等雲端先改）：cypher-executor 早就有 `/kbdb/entries` proxy，
+// 認證用的正是 daemon 本來就帶著的 `X-Arcrun-API-Key`（routes/kbdb-proxy.ts，
+// owner_id 由 server 端強制注入，租戶跨不過去）。⇒ **零雲端改動、零新憑證。**
+//
+// 三條自我約束（對應票上的紅線）：
+//   - **不刪任何東西**：對帳只會把本機的章拔掉（讓它重走既有的送件路），
+//     不碰雲端 entry、不碰 .wiki 卡、不碰使用者的檔。
+//   - **不做全量重送**：一次只問 cloudAuditBatch 個檔，且同一個檔
+//     cloudAuditRecheckInterval 內只問一次；問到「雲端沒有」才拔章。
+//   - **不會重送兩次**：拔過章的檔在 cloudAuditRepairGrace 內不再被拔第二次
+//     （雲端 ingest 是非同步的，剛送出去那幾秒查不到是正常的——
+//     沒有這道閘，它會變成一個每輪重送、把額度燒光的迴圈，
+//     那就是「把一個 bug 換成另一個」）。
+package collector
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"sort"
+	"strings"
+	"time"
+)
+
+// cloudAuditRecheckInterval＝同一個檔多久重新對一次帳。
+// 24 小時的理由：這是「雲端被清空」這種罕見事故的偵測延遲上限，
+// 而使用者按「立刻同步」（ForceSync）時本輪一律重對，不必等它。
+const cloudAuditRecheckInterval = 24 * time.Hour
+
+// cloudAuditRepairGrace＝同一個檔拔過章之後，多久內不准再拔第二次。
+//
+// 🔴 這是「重跑第二次不可以又全部重送一遍」（#140 驗收條件 5）的那道閘。
+// 雲端 rag_ingest_card 是觸發式的，卡片不會在 POST 回來的那一瞬間就查得到；
+// 沒有這個窗口，對帳會在下一輪又判它「不在」⇒ 重送 ⇒ 無限迴圈 ⇒ 燒光額度。
+const cloudAuditRepairGrace = 24 * time.Hour
+
+// cloudAuditBatch＝單輪最多問幾個檔。
+// 與 DefaultMaxEventsPerRun 同一個精神：巨量積壓（實據 27,164 檔）不該一輪湧完。
+const cloudAuditBatch = 20
+
+// cloudAuditFolderInterval＝同一個資料夾兩次對帳批次的最小間隔。
+// daemon 預設 5 秒一輪，沒有這道節流就是每 5 秒 20 個請求。
+const cloudAuditFolderInterval = 60 * time.Second
+
+// cloudAuditProbePace＝批次內每個請求之間的間隔。
+// 比 directPaceInterval（700ms）短很多是因為這是 D1 的單筆 COUNT，不是 LLM——
+// 20 個請求約 2 秒跑完，不會讓一輪掃描明顯變慢。
+const cloudAuditProbePace = 100 * time.Millisecond
+
+// cloudAuditHTTP：對帳是唯讀查詢，逾時要短——問不到就當「這輪沒查」，
+// 絕不能因為雲端慢就把整輪同步拖住（同 cloud_version.go 的判準）。
+var cloudAuditHTTP = &http.Client{Timeout: 20 * time.Second}
+
+// probeCloudCard 可在測試中替換，避免真實網路呼叫。
+var probeCloudCard = cloudCardPresent
+
+// cloudCardPresent 問雲端「這個庫裡還有沒有這個檔的卡」。
+//
+// 判準＝`metadata_json.source == kb://<相對路徑>#0`。為什麼是 `#0` 而不是頁名：
+//   - 頁名是 basename 去副檔名（pageNameOf），**兩個資料夾裡的同名檔會撞在一起**；
+//   - `source` 是 rag_ingest_card parse_card 寫死的 `kb://<path>#<第幾塊>`，
+//     而第 0 塊必然存在（卡片至少一塊）⇒ 它就是「這張卡在不在」的存在性鍵，
+//     也正是 rag_takedown_direct 用來比對的同一個鍵（兩邊用同一把尺）。
+//
+// `offset` 故意帶一個大數：回應只要 `total`，不要 entries 本身——
+// 卡片內文動輒數 KB，20 個檔就是幾百 KB 的白搭流量。
+//
+// 回傳的 ok=false＝**這次沒查成**（連不上、非 2xx、回應不是 JSON）。
+// 呼叫端必須把它當「不知道」，**不准當成「雲端沒有」**——
+// 那會讓一次網路抖動變成一次全量重送。
+func cloudCardPresent(cfg *DirectConfig, library, relPath string) (present bool, ok bool, err error) {
+	base := strings.TrimSuffix(cfg.CypherURL, "/")
+	if base == "" || strings.TrimSpace(cfg.APIKey) == "" {
+		return false, false, fmt.Errorf("沒有雲端連線資訊（cypher_url／api_key 是空的）")
+	}
+	q := url.Values{}
+	q.Set("source", "kb://"+relPath+"#0")
+	q.Set("entry_type", "block")
+	q.Set("limit", "1")
+	q.Set("offset", "1000000") // 只要 total，不要把卡片內文整包拉下來
+	if strings.TrimSpace(library) != "" {
+		q.Set("library", library)
+	}
+	req, err := http.NewRequest(http.MethodGet, base+"/kbdb/entries?"+q.Encode(), nil)
+	if err != nil {
+		return false, false, err
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("X-Arcrun-API-Key", cfg.APIKey)
+	resp, err := cloudAuditHTTP.Do(req)
+	if err != nil {
+		return false, false, err
+	}
+	defer resp.Body.Close()
+	body, rerr := io.ReadAll(io.LimitReader(resp.Body, 8192))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return false, false, fmt.Errorf("HTTP %d：%s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	if rerr != nil {
+		return false, false, rerr
+	}
+	var payload struct {
+		Success *bool `json:"success"`
+		Total   *int  `json:"total"`
+	}
+	if jerr := json.Unmarshal(body, &payload); jerr != nil {
+		return false, false, fmt.Errorf("雲端回應不是 JSON：%s", strings.TrimSpace(string(body)))
+	}
+	// 🔴 total 缺席時回 ok=false 而不是「total=0」。少一個欄位可能是端點換了形狀，
+	//    把它讀成「雲端沒有這個檔」就會全部重送——寧可什麼都不做。
+	if payload.Total == nil || (payload.Success != nil && !*payload.Success) {
+		return false, false, fmt.Errorf("雲端回應少了 total 欄位：%s", strings.TrimSpace(string(body)))
+	}
+	return *payload.Total > 0, true, nil
+}
+
+// auditCandidates 挑出這一輪要問的檔：蓋過章、且太久沒對過帳的，最久沒對的排前面。
+//
+// 三種**不問**（每一種都對應一個會咬人的情境）：
+//   - 沒蓋過章（IngestedHash 空）：雲端本來就不該有它，Scan() 自己會重送。
+//   - NoCloudCard：萃取判定「無可萃取概念」⇒ 本來就沒送過卡上雲。
+//     不排除它的話，對帳每次都會說「雲端沒有」⇒ 每天重萃一次，永遠停不下來。
+//   - 剛拔過章還在 grace 內：見 cloudAuditRepairGrace。
+func auditCandidates(m *Manifest, now int64, force bool) []string {
+	recheck := int64(cloudAuditRecheckInterval.Seconds())
+	grace := int64(cloudAuditRepairGrace.Seconds())
+	var out []string
+	for p, e := range m.Entries {
+		if e == nil || strings.TrimSpace(e.IngestedHash) == "" || e.NoCloudCard {
+			continue
+		}
+		if e.CloudMissingAt > 0 && now-e.CloudMissingAt < grace {
+			continue
+		}
+		if !force && e.CloudCheckedAt > 0 && now-e.CloudCheckedAt < recheck {
+			continue
+		}
+		out = append(out, p)
+	}
+	// 最久沒對帳的先問（0＝從沒問過，天然排最前）；同分時按路徑排序，讓同一份輸入
+	// 永遠得到同一個輸出（可測）。
+	sort.Slice(out, func(i, j int) bool {
+		ai, aj := m.Entries[out[i]].CloudCheckedAt, m.Entries[out[j]].CloudCheckedAt
+		if ai != aj {
+			return ai < aj
+		}
+		return out[i] < out[j]
+	})
+	if len(out) > cloudAuditBatch {
+		out = out[:cloudAuditBatch]
+	}
+	return out
+}
+
+// auditResult＝一輪對帳的結果，給呼叫端組人話與記帳用。
+type auditResult struct {
+	Checked int    // 這輪真的問了幾個檔
+	Voided  int    // 其中幾個雲端查不到、章被拔掉（＝已排進重送佇列）
+	Err     string // 對帳本身失敗的真因（原文，不改寫——leo 2026-08-06 原則）
+}
+
+// auditCloudLedger 對一個監看根跑一輪對帳。回 nil＝這輪不必對（節流中／沒有候選）。
+//
+// 🔴 它**只做一件事**：把「雲端已經沒有了」的章拔掉。
+// 拔完之後，接下來的 Scan() 會因為 `orig[p].IngestedHash == ""` 自然補一發 added
+// （scan.go 步驟 4「上輪偵測過但 ingest 未成功 → 重試」），
+// 於是重送走的是**既有的**萃取路：既有的單輪上限、既有的失敗退避、既有的額度冷卻
+// 全部照舊生效。⇒ 沒有第二條送件路，也沒有第二套節流要維護。
+func auditCloudLedger(cfg *DirectConfig, absRoot string, m *Manifest, dryRun bool, now time.Time) *auditResult {
+	if dryRun {
+		return nil
+	}
+	nowUnix := now.Unix()
+	if !cfg.ForceSync && m.CloudAuditAt > 0 &&
+		nowUnix-m.CloudAuditAt < int64(cloudAuditFolderInterval.Seconds()) {
+		return nil // 節流：同一個資料夾一分鐘內不重問
+	}
+	cands := auditCandidates(m, nowUnix, cfg.ForceSync)
+	if len(cands) == 0 {
+		// 沒有候選也要記時間，否則每輪都要重走一次上面那個迴圈。
+		m.CloudAuditAt = nowUnix
+		return nil
+	}
+	lib := cfg.libraryFor(absRoot)
+	res := &auditResult{}
+	for _, p := range cands {
+		e := m.Entries[p]
+		if e == nil {
+			continue
+		}
+		present, ok, err := probeCloudCard(cfg, lib, p)
+		if !ok {
+			// 問不到就整批停手：連不上時繼續問剩下的 19 個只是重複同一個錯誤。
+			// **絕不把「沒查成」當成「雲端沒有」**（那會讓一次網路抖動變成全量重送）。
+			if err != nil {
+				res.Err = err.Error()
+			}
+			break
+		}
+		res.Checked++
+		e.CloudCheckedAt = nowUnix
+		if present {
+			continue
+		}
+		// 雲端真的沒有 ⇒ 這個章是假的，拔掉。**不動使用者的任何東西。**
+		e.IngestedHash = ""
+		e.CloudMissingAt = nowUnix
+		// 失敗退避是「這個檔壞掉」的病歷，跟「雲端被清空」無關——留著會讓補送
+		// 卡在上一次的退避階梯裡（實測那 8 個檔 fail_count 全是 0，但別的資料夾不一定）。
+		e.FailCount, e.LastFailAt, e.NextRetry = 0, 0, 0
+		res.Voided++
+		pace2(cloudAuditProbePace)
+	}
+	m.CloudAuditAt = nowUnix
+	if res.Checked == 0 && res.Err == "" {
+		return nil
+	}
+	return res
+}
+
+// ResyncSummary 從 manifest 現況算出「補送」這件事現在講到哪裡」。
+//
+// 為什麼是**從 manifest 重算**而不是記一個計數器：計數器是「本輪做了幾件事」，
+// 沒事做的那輪就會歸零——2026-08-05 leo 實撞的「明明做完了畫面卻永遠寫等待中」
+// 就是那個形狀。這裡算的是**現況**（還有幾份沒補回來），補完自然歸零、不必有人去清。
+func ResyncSummary(m *Manifest, now time.Time) (pending, repaired int) {
+	nowUnix := now.Unix()
+	fresh := int64(cloudAuditRepairGrace.Seconds())
+	for _, e := range m.Entries {
+		if e == nil || e.CloudMissingAt == 0 {
+			continue
+		}
+		if strings.TrimSpace(e.IngestedHash) == "" {
+			pending++ // 章拔掉了、還沒補送成功
+		} else if e.IngestedAt >= e.CloudMissingAt && nowUnix-e.IngestedAt < fresh {
+			repaired++ // 剛補送成功（只講最近一天的，不然這行會永遠掛在畫面上）
+		}
+	}
+	return pending, repaired
+}
+
+// resyncNote 把上面兩個數字翻成使用者看得懂的一句話。
+//
+// leo 2026-08-06 的原則（「別人的錯誤一律要顯示給用戶看，不然就會變成我的錯誤」）
+// 在這裡的形狀是：**不能靜悄悄地重送**。使用者只要看到「有 8 份在補送」，
+// 就知道畫面上的數字為什麼會動、也知道不是自己弄壞的。
+func resyncNote(pending, repaired int, lastErr string) string {
+	switch {
+	case pending > 0 && repaired > 0:
+		return fmt.Sprintf("雲端上找不到先前送過的檔案（知識庫可能重裝過），正在自動補送：已補回 %d 份，還有 %d 份排隊中。", repaired, pending)
+	case pending > 0:
+		return fmt.Sprintf("雲端上找不到 %d 份先前送過的檔案（知識庫可能重裝過），已排進佇列自動補送，你不必做任何事。", pending)
+	case repaired > 0:
+		return fmt.Sprintf("已把雲端上遺失的 %d 份檔案補送回知識庫。", repaired)
+	case lastErr != "":
+		return "暫時無法跟雲端核對哪些檔案還在（不影響同步，稍後自動再試）。"
+	}
+	return ""
+}
+
+// pace2＝可指定長度的節流（directPaceInterval 那支是萃取路專用的固定 700ms）。
+// 拉成獨立函式是為了讓測試能把它調成 0。
+var pace2 = func(d time.Duration) {
+	if d > 0 {
+		time.Sleep(d)
+	}
+}

cloud_audit_test.go

@@ -0,0 +1,390 @@
+package collector
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 每個測試都把節流關掉，避免 20 個探測睡 2 秒。
+func init() { pace2 = func(time.Duration) {} }
+
+func newAuditManifest(paths ...string) *Manifest {
+	m := &Manifest{FolderID: "f", Root: "/root", Entries: map[string]*ManifestEntry{}}
+	for _, p := range paths {
+		m.Entries[p] = &ManifestEntry{
+			ContentHash:  "sha256:" + p,
+			IngestedHash: "sha256:" + p,
+			IngestedAt:   100,
+		}
+	}
+	return m
+}
+
+// stubProbe 讓測試指定「雲端有哪些」，並記錄被問了幾次。
+func stubProbe(t *testing.T, present map[string]bool, err error) *int {
+	t.Helper()
+	calls := 0
+	orig := probeCloudCard
+	probeCloudCard = func(cfg *DirectConfig, library, relPath string) (bool, bool, error) {
+		calls++
+		if err != nil {
+			return false, false, err
+		}
+		return present[relPath], true, nil
+	}
+	t.Cleanup(func() { probeCloudCard = orig })
+	return &calls
+}
+
+func auditCfg() *DirectConfig {
+	return &DirectConfig{CypherURL: "https://x.invalid", APIKey: "ns", Namespace: "ns"}
+}
+
+// 本票的主場景：雲端被清空 ⇒ 章全部作廢 ⇒ Scan() 補發 added ⇒ 重送。
+func TestAudit_CloudWiped_VoidsStampsAndScanReemits(t *testing.T) {
+	m := newAuditManifest("a.md", "b.pdf")
+	stubProbe(t, map[string]bool{}, nil) // 雲端什麼都沒有
+	now := time.Unix(1_000_000, 0)
+
+	res := auditCloudLedger(auditCfg(), "/root", m, false, now)
+	if res == nil || res.Voided != 2 || res.Checked != 2 {
+		t.Fatalf("預期對帳 2 份、作廢 2 份，實得 %+v", res)
+	}
+	for p, e := range m.Entries {
+		if e.IngestedHash != "" {
+			t.Fatalf("%s 的章沒有被拔掉", p)
+		}
+		if e.CloudMissingAt != now.Unix() {
+			t.Fatalf("%s 沒有記下 cloud_missing_at", p)
+		}
+	}
+
+	// 這才是真正的驗收：拔章之後 Scan() 要自己補發 added（不必另造送件路）。
+	root := t.TempDir()
+	writeFile(t, root, "a.md", "hello", time.Unix(900_000, 0))
+	writeFile(t, root, "b.pdf", "world", time.Unix(900_000, 0))
+	m2 := newAuditManifest("a.md", "b.pdf")
+	for _, e := range m2.Entries {
+		e.IngestedHash = "" // 對帳剛拔掉的狀態
+	}
+	// content_hash 讓 Scan 自己重算，這裡只要它認得出「這兩個路徑還沒 ingest 成功」。
+	payload, err := Scan(root, m2, ScanOptions{MaxRemovedRatio: 0.4})
+	if err != nil {
+		t.Fatalf("Scan: %v", err)
+	}
+	added := map[string]bool{}
+	for _, ev := range payload.Events {
+		if ev.Type == "added" {
+			added[ev.Path] = true
+		}
+	}
+	if !added["a.md"] || !added["b.pdf"] {
+		t.Fatalf("拔章後 Scan 沒有補發 added，實得 %+v", payload.Events)
+	}
+}
+
+// 驗收條件 5：重跑第二次不可以又全部重送一遍。
+func TestAudit_SecondRunDoesNotVoidAgain(t *testing.T) {
+	m := newAuditManifest("a.md")
+	stubProbe(t, map[string]bool{}, nil)
+	now := time.Unix(1_000_000, 0)
+
+	if r := auditCloudLedger(auditCfg(), "/root", m, false, now); r == nil || r.Voided != 1 {
+		t.Fatalf("第一輪應該作廢 1 份，實得 %+v", r)
+	}
+	// 模擬補送成功（雲端仍在 ingest 中、查不到）
+	m.MarkIngestedBy("a.md", "sha256:a.md", now.Unix()+1, "workers-ai")
+
+	// 一小時後再對帳：雲端還是查不到，但 grace 內**不准**再拔一次章。
+	later := now.Add(time.Hour)
+	m.CloudAuditAt = 0 // 解除資料夾層節流，只考驗 per-path grace
+	r2 := auditCloudLedger(auditCfg(), "/root", m, false, later)
+	if r2 != nil && r2.Voided > 0 {
+		t.Fatalf("grace 期間又拔了章 ⇒ 會變成無限重送迴圈：%+v", r2)
+	}
+	if m.Entries["a.md"].IngestedHash == "" {
+		t.Fatal("章被重複拔掉了")
+	}
+}
+
+// 雲端有的檔不准被動到（否則就是全量重送）。
+func TestAudit_PresentCardsUntouched(t *testing.T) {
+	m := newAuditManifest("a.md", "b.md")
+	stubProbe(t, map[string]bool{"a.md": true, "b.md": true}, nil)
+	now := time.Unix(1_000_000, 0)
+
+	res := auditCloudLedger(auditCfg(), "/root", m, false, now)
+	if res == nil || res.Voided != 0 || res.Checked != 2 {
+		t.Fatalf("預期 0 作廢、2 已對帳，實得 %+v", res)
+	}
+	for p, e := range m.Entries {
+		if e.IngestedHash == "" {
+			t.Fatalf("%s 的章被誤拔", p)
+		}
+		if e.CloudCheckedAt != now.Unix() {
+			t.Fatalf("%s 沒記下對帳時間 ⇒ 下一輪會重問，變成請求風暴", p)
+		}
+	}
+}
+
+// 🔴 網路抖動不准被讀成「雲端沒有」——那會讓一次逾時變成一次全量重送。
+func TestAudit_ProbeFailureNeverVoids(t *testing.T) {
+	m := newAuditManifest("a.md", "b.md")
+	calls := stubProbe(t, nil, fmt.Errorf("connection reset"))
+	res := auditCloudLedger(auditCfg(), "/root", m, false, time.Unix(1_000_000, 0))
+	if res == nil || res.Voided != 0 || res.Err == "" {
+		t.Fatalf("查不到時不該作廢、且要留下真因，實得 %+v", res)
+	}
+	if *calls != 1 {
+		t.Fatalf("問不到就該整批停手（只問 1 次），實得 %d 次", *calls)
+	}
+	for p, e := range m.Entries {
+		if e.IngestedHash == "" {
+			t.Fatalf("%s 因為一次網路錯誤就被作廢", p)
+		}
+	}
+}
+
+// 從沒送成功過的檔不必問雲端（Scan 自己會重送），沒送過卡的檔更不能問（會無限重萃）。
+func TestAudit_SkipsUnstampedAndNoCardEntries(t *testing.T) {
+	m := newAuditManifest("stamped.md", "unstamped.md", "nocard.md")
+	m.Entries["unstamped.md"].IngestedHash = ""
+	m.Entries["nocard.md"].NoCloudCard = true
+	calls := stubProbe(t, map[string]bool{}, nil)
+
+	auditCloudLedger(auditCfg(), "/root", m, false, time.Unix(1_000_000, 0))
+	if *calls != 1 {
+		t.Fatalf("只該問 stamped.md 一個，實得 %d 次", *calls)
+	}
+	if m.Entries["nocard.md"].IngestedHash == "" {
+		t.Fatal("沒送過卡的檔被作廢 ⇒ 會每天重萃一次，永遠停不下來")
+	}
+}
+
+// 單輪上限＋最久沒對帳的排前面（巨量資料夾也要輪得完）。
+func TestAudit_BatchCapAndOldestFirst(t *testing.T) {
+	m := &Manifest{FolderID: "f", Root: "/root", Entries: map[string]*ManifestEntry{}}
+	for i := 0; i < cloudAuditBatch+5; i++ {
+		p := fmt.Sprintf("f%02d.md", i)
+		m.Entries[p] = &ManifestEntry{
+			ContentHash: "h", IngestedHash: "h",
+			CloudCheckedAt: int64(i), // 越前面越久沒對
+		}
+	}
+	var asked []string
+	orig := probeCloudCard
+	probeCloudCard = func(cfg *DirectConfig, library, relPath string) (bool, bool, error) {
+		asked = append(asked, relPath)
+		return true, true, nil
+	}
+	t.Cleanup(func() { probeCloudCard = orig })
+
+	// force=true 才會忽略「24 小時內對過帳」的閘（上面的 CloudCheckedAt 是很小的數字，
+	// 對現在的時間來說早就過期了，這裡用 force 讓意圖明確）。
+	cfg := auditCfg()
+	cfg.ForceSync = true
+	auditCloudLedger(cfg, "/root", m, false, time.Unix(1_000_000, 0))
+	if len(asked) != cloudAuditBatch {
+		t.Fatalf("單輪上限沒生效：問了 %d 個（上限 %d）", len(asked), cloudAuditBatch)
+	}
+	if asked[0] != "f00.md" {
+		t.Fatalf("最久沒對帳的沒排最前面，第一個是 %s", asked[0])
+	}
+}
+
+// 資料夾層節流：daemon 每 5 秒一輪，不能每輪都對雲端發一批請求。
+func TestAudit_FolderIntervalThrottle(t *testing.T) {
+	m := newAuditManifest("a.md")
+	calls := stubProbe(t, map[string]bool{"a.md": true}, nil)
+	now := time.Unix(1_000_000, 0)
+
+	auditCloudLedger(auditCfg(), "/root", m, false, now)
+	auditCloudLedger(auditCfg(), "/root", m, false, now.Add(5*time.Second))
+	if *calls != 1 {
+		t.Fatalf("節流沒生效：5 秒內問了 %d 次", *calls)
+	}
+	// 使用者按「立刻同步」要能穿透節流。
+	cfg := auditCfg()
+	cfg.ForceSync = true
+	auditCloudLedger(cfg, "/root", m, false, now.Add(6*time.Second))
+	if *calls != 2 {
+		t.Fatalf("立刻同步沒有穿透節流：共問了 %d 次", *calls)
+	}
+}
+
+// 24 小時內對過帳的檔不重問（一般輪次）。
+func TestAudit_RecheckInterval(t *testing.T) {
+	m := newAuditManifest("a.md")
+	m.Entries["a.md"].CloudCheckedAt = 1_000_000
+	calls := stubProbe(t, map[string]bool{"a.md": true}, nil)
+	auditCloudLedger(auditCfg(), "/root", m, false, time.Unix(1_000_000+3600, 0))
+	if *calls != 0 {
+		t.Fatalf("一小時前才對過帳，不該重問（實得 %d 次）", *calls)
+	}
+}
+
+// dryRun 不准碰帳本。
+func TestAudit_DryRunDoesNothing(t *testing.T) {
+	m := newAuditManifest("a.md")
+	calls := stubProbe(t, map[string]bool{}, nil)
+	if r := auditCloudLedger(auditCfg(), "/root", m, true, time.Unix(1_000_000, 0)); r != nil {
+		t.Fatalf("dry-run 不該做任何事，實得 %+v", r)
+	}
+	if *calls != 0 || m.Entries["a.md"].IngestedHash == "" || m.CloudAuditAt != 0 {
+		t.Fatal("dry-run 動了帳本或打了網路")
+	}
+}
+
+// 🔴 scan.go 的 carry 段漏欄位是這個檔案歷史上犯過兩次的錯（t195 fail_count、5fcc139
+// LastError）。第三次的代價是「防重送迴圈的 grace 消失 ⇒ 燒光額度」，所以釘死它。
+func TestScan_CarriesCloudAuditFields(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "a.md", "hello", time.Unix(900_000, 0))
+	m := &Manifest{FolderID: "f", Root: root, Entries: map[string]*ManifestEntry{}}
+	if _, err := Scan(root, m, ScanOptions{MaxRemovedRatio: 0.4}); err != nil {
+		t.Fatalf("首輪 Scan: %v", err)
+	}
+	e := m.Entries["a.md"]
+	e.IngestedHash = e.ContentHash
+	e.CloudCheckedAt = 111
+	e.CloudMissingAt = 222
+	e.NoCloudCard = true
+
+	if _, err := Scan(root, m, ScanOptions{MaxRemovedRatio: 0.4}); err != nil {
+		t.Fatalf("次輪 Scan: %v", err)
+	}
+	got := m.Entries["a.md"]
+	if got.CloudCheckedAt != 111 || got.CloudMissingAt != 222 || !got.NoCloudCard {
+		t.Fatalf("Scan 重建 entry 時把雲端對帳欄位抹掉了：%+v", got)
+	}
+}
+
+// MarkIngestedBy 要保住 grace 標記（不然剛補送成功的檔立刻又回到可拔章的池子），
+// 但要把 NoCloudCard 歸位（這一輪送了卡就不是「沒卡的檔」了）。
+func TestMarkIngested_KeepsGraceClearsNoCard(t *testing.T) {
+	m := newAuditManifest("a.md")
+	e := m.Entries["a.md"]
+	e.CloudCheckedAt, e.CloudMissingAt, e.NoCloudCard = 111, 222, true
+	m.MarkIngestedBy("a.md", "h2", 999, "workers-ai")
+	if e.CloudCheckedAt != 111 || e.CloudMissingAt != 222 {
+		t.Fatalf("對帳記錄被清掉了：%+v", e)
+	}
+	if e.NoCloudCard {
+		t.Fatal("NoCloudCard 沒有歸位")
+	}
+	if !m.MarkNoCloudCard("a.md") || !e.NoCloudCard {
+		t.Fatal("MarkNoCloudCard 沒生效")
+	}
+}
+
+// 補送進度是「現況快照」而不是「本輪計數」——沒事做的那輪不能歸零、補完要自然消失。
+func TestResyncSummary(t *testing.T) {
+	now := time.Unix(1_000_000, 0)
+	m := newAuditManifest("pending.md", "repaired.md", "normal.md")
+	m.Entries["pending.md"].IngestedHash = ""
+	m.Entries["pending.md"].CloudMissingAt = now.Unix() - 60
+	m.Entries["repaired.md"].CloudMissingAt = now.Unix() - 60
+	m.Entries["repaired.md"].IngestedAt = now.Unix() - 30
+
+	pending, repaired := ResyncSummary(m, now)
+	if pending != 1 || repaired != 1 {
+		t.Fatalf("預期 pending=1 repaired=1，實得 %d/%d", pending, repaired)
+	}
+	if note := resyncNote(pending, repaired, ""); !strings.Contains(note, "補送") {
+		t.Fatalf("人話沒生出來：%q", note)
+	}
+	// 一天後那句「已補回」要自己消失，不能永遠掛在畫面上。
+	_, repairedLater := ResyncSummary(m, now.Add(25*time.Hour))
+	if repairedLater != 0 {
+		t.Fatalf("舊的補送紀錄沒有過期：%d", repairedLater)
+	}
+}
+
+// cloudCardPresent 打的是真的 HTTP，形狀對不對用假伺服器釘住
+// （URL 形狀一旦漂掉，對帳會靜默地永遠回「雲端沒有」＝全量重送）。
+func TestCloudCardPresent_RequestShapeAndParsing(t *testing.T) {
+	var got url.Values
+	var gotKey string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = r.URL.Query()
+		gotKey = r.Header.Get("X-Arcrun-API-Key")
+		if r.URL.Path != "/kbdb/entries" {
+			t.Errorf("打錯端點：%s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"success": true, "entries": []any{}, "count": 0, "total": 1})
+	}))
+	defer srv.Close()
+
+	cfg := &DirectConfig{CypherURL: srv.URL, APIKey: "ns"}
+	present, ok, err := cloudCardPresent(cfg, "mylib", "docs/小果被AFTEE詐貸.pdf")
+	if err != nil || !ok || !present {
+		t.Fatalf("total=1 應該讀成 present，實得 present=%v ok=%v err=%v", present, ok, err)
+	}
+	if got.Get("source") != "kb://docs/小果被AFTEE詐貸.pdf#0" {
+		t.Fatalf("source 鍵不對：%q", got.Get("source"))
+	}
+	if got.Get("library") != "mylib" || got.Get("entry_type") != "block" {
+		t.Fatalf("庫／型別 filter 不對：%v", got)
+	}
+	if got.Get("offset") == "" || got.Get("offset") == "0" {
+		t.Fatalf("沒有用大 offset 避開卡片內文：%q", got.Get("offset"))
+	}
+	if gotKey != "ns" {
+		t.Fatalf("沒帶 X-Arcrun-API-Key：%q", gotKey)
+	}
+}
+
+func TestCloudCardPresent_ZeroTotalIsMissing(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"success": true, "total": 0})
+	}))
+	defer srv.Close()
+	present, ok, err := cloudCardPresent(&DirectConfig{CypherURL: srv.URL, APIKey: "ns"}, "lib", "a.md")
+	if err != nil || !ok || present {
+		t.Fatalf("total=0 應該讀成 missing，實得 present=%v ok=%v err=%v", present, ok, err)
+	}
+}
+
+// 🔴 端點換了形狀（少了 total）要回「不知道」，不准回「雲端沒有」。
+func TestCloudCardPresent_MissingTotalIsUnknown(t *testing.T) {
+	cases := map[string]http.HandlerFunc{
+		"沒有 total 欄位": func(w http.ResponseWriter, r *http.Request) {
+			_ = json.NewEncoder(w).Encode(map[string]any{"success": true, "entries": []any{}})
+		},
+		"success=false": func(w http.ResponseWriter, r *http.Request) {
+			_ = json.NewEncoder(w).Encode(map[string]any{"success": false, "total": 0, "error": "boom"})
+		},
+		"不是 JSON": func(w http.ResponseWriter, r *http.Request) {
+			_, _ = w.Write([]byte("<html>cloudflare</html>"))
+		},
+		"401": func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(401)
+			_, _ = w.Write([]byte(`{"error":"缺少 X-Arcrun-API-Key header"}`))
+		},
+	}
+	for name, h := range cases {
+		t.Run(name, func(t *testing.T) {
+			srv := httptest.NewServer(h)
+			defer srv.Close()
+			_, ok, err := cloudCardPresent(&DirectConfig{CypherURL: srv.URL, APIKey: "ns"}, "lib", "a.md")
+			if ok {
+				t.Fatalf("%s 應該回 ok=false（不知道），不能回「雲端沒有」", name)
+			}
+			if err == nil {
+				t.Fatalf("%s 沒有留下真因", name)
+			}
+		})
+	}
+}
+
+func TestCloudCardPresent_NoConnectionInfo(t *testing.T) {
+	if _, ok, _ := cloudCardPresent(&DirectConfig{}, "lib", "a.md"); ok {
+		t.Fatal("沒有連線資訊時不該宣稱查得到答案")
+	}
+}

cmd/arcrun-app/.version-source-files.json

@@ -1,20 +1,27 @@
 {
  "_algo": 4,
- "version": "0.18.34",
- "fingerprint": "d8c7490b9d32e62e",
+ "version": "0.18.37",
+ "fingerprint": "3bb5c94f68a26a06",
  "files": {
   ".gitignore": "4d56952b0fb13bf8f9b6c13a6d4c34a075bac3af447636a1df4335d7576e2f97",
-  "CHANGELOG.md": "435942d764a283e1637b2ac7b6bc7304b9fc1e79b152f89780d1fa8e62440aa4",
+  "CHANGELOG.md": "ba7a2a7cc8071e62c7493057abff43c81739c7828332a9124fcb415263b3b649",
   "DAEMON_LINE": "d5019abbdc8a5f2919e9e3510391891cd7fbdf0765bf16ec83caa779f370116d",
   "README.md": "9d92cac236b20a0b183eea3e7f5e39ad492f05192c4ea602eb11c3d09967327f",
   "check-standalone.sh": "65fbce096326791c2f103a51e76d0ad79e9e510e2a7700b49ac2d2d81f73c853",
+  "cleanup.go": "59a45672f7f73d73833685846148ba20f71d5b3f42340be5a74a10437be267fc",
+  "cleanup_cli.go": "5dc41aac30f39757658d7bc95ab727ecc799b8242fd752edcedbb8423935fbf0",
+  "cleanup_test.go": "23d627a12ec476bb8898847185a1464cb78e2186278299ff13c84a3d54af63c0",
+  "cloud_audit.go": "a51f5c6eafaa75ce282b307e8dd2986f0b316a3c24282bed0856002819dd86e2",
+  "cloud_audit_test.go": "1790837e8a5726d62258436937f9c474f7abd03e6229832fdbd40f8cd7aa756a",
   "cloud_latest.go": "c2ad7f87bbd55247540eb924ac3be5deadbc4488b504770a5127a01c748f0e0f",
   "cloud_latest_test.go": "703963b65da91ae0c4638b9ad676ca7f12a474c635e903a5d988e4980b3888aa",
   "cloud_version.go": "eebc2552e09e199928e82607bebf90daef36b5721ec9b8a098304c10dbec46f9",
   "cloud_version_test.go": "66c004de1f0a3958851f22a22367065f13b3381ac7d936ae54d812c26a0b9fb6",
   "cmd/arcrun-app/.gitignore": "7502ba597654ebb3463535bdfb51c271abad666a67c7ac8ab36deca1a72615f8",
-  "cmd/arcrun-app/README.md": "9ea849308b5e578d9a43b73fc3d72637d21428eca9c96a448d31078e8627bcb4",
-  "cmd/arcrun-app/app.go": "4c65f895c68f82a84d633e6e6d05fbabb86e51632f9ae3d693e39a67ca2b981c",
+  "cmd/arcrun-app/README.md": "23e53fdf53fcd96b6d8d7a121eb91d3242d11b69d655770473b745c49bb387b9",
+  "cmd/arcrun-app/app.go": "d7552348ea2c662bceabd866a33650c69278420374fc95200c1c86270a6e46b8",
+  "cmd/arcrun-app/apps.go": "0df6da9d55adbdec500fbb01005a305287d1dbf796b7e463f2b2f222626b4c96",
+  "cmd/arcrun-app/apps_test.go": "0e2f137f8b49f421e869ab3192ca12c8bb756029d8730487ccc44733aaf7f96c",
   "cmd/arcrun-app/arcrun-app": "e2bdf54a15d69860df05820274a80d7497b7d62a4e8ba219f72f30b543456b79",
   "cmd/arcrun-app/assets/store/README.md": "a9028a727947c5038ca938c664b18e4851ae3bf0e6d8838c82aedea43d02ded2",
   "cmd/arcrun-app/assets/store/Square150x150Logo.png": "27942d943096ba23f036b030726e905f6df6123428cd7d8ec687ce5b11e42db1",
@@ -48,9 +55,11 @@
   "cmd/arcrun-app/build/windows/wails.exe.manifest": "c63cb75ce48fb1354c95264f6fc43a7686a9b85a82a71efa9722ae4ce6561dc0",
   "cmd/arcrun-app/changelog-section.sh": "8b39dfdfbf8670fc850102e43b056b98dda52b2a7bd2a49f8d961c171c7abe23",
   "cmd/arcrun-app/check-cis.sh": "0627a2187160fd1f8c9f618588f6398c4b087a91394e8d387f9a9710f79dd8a5",
+  "cmd/arcrun-app/check-launcher.mjs": "0c9b4ebd142554b69c1eedf46e5618078b60a050b9f7e5afbf6d3c34d509337d",
+  "cmd/arcrun-app/check-remove-cleanup.sh": "b049881d1608b70fc0f27a130a1a794d780a522317d02ea8e17a866986c87c2c",
   "cmd/arcrun-app/check-render.sh": "8cd0fb4fe975111f74afb3bc841bc34fe9b160aeddcf67559a504c5187b8ae02",
   "cmd/arcrun-app/check-tray.sh": "7ff5c5e4d3dba6a356d9b556fc93cefe1c9e93827362ddd553fdb02717701cf5",
-  "cmd/arcrun-app/connect.go": "18fc927ab55858596c1c6b9e913694fd60cc6dd0c12f4f1640144dcf7f12b1d9",
+  "cmd/arcrun-app/connect.go": "0da69f6b781c3283851304511b1bd2ebd6f3b9663ae28b3605bab13072d39f9d",
   "cmd/arcrun-app/daemon-notes.mjs": "452434bf3d744366717219968ee94ba7bb773dbbcd62d69a46937cbb967811b9",
   "cmd/arcrun-app/daemon-version.py": "786a0212800dd5c5d3a9ff9faf5c5930be1428f033bc20a9de9399a30b18a824",
   "cmd/arcrun-app/daemon-version.test.mjs": "ee052f19806ba0fa3970442199a57dc76d69829c5b72f9e3879dc50ce0f1abfc",
@@ -79,8 +88,8 @@
   "cmd/arcrun-app/frontend/src/assets/fonts/OFL.txt": "8656c2a27357b3140047a39b27e3cd928256544ad8a004ef77087f761358208c",
   "cmd/arcrun-app/frontend/src/assets/fonts/nunito-v16-latin-regular.woff2": "06f3af3fe52542d40ad9bc14ec03e04deaabd09ec369221cc8f536db1c72bf55",
   "cmd/arcrun-app/frontend/src/assets/images/logo-universal.png": "157a874acd3363634747287c0b01034e9f1eec838a4cf39827dfea789e730494",
-  "cmd/arcrun-app/frontend/src/main.js": "75bec60d9af627c990b2f2007ffd70e28e33a4a728522099777e028cd670e385",
-  "cmd/arcrun-app/frontend/src/style.css": "08e890f3f0d7f603249175d5415f64c43370d08bbd30b66c7ccb39a58e399169",
+  "cmd/arcrun-app/frontend/src/main.js": "26c4ecf26b848916c96620a0e7aa6d91f1da208dd96597c08f39717b4e4eddee",
+  "cmd/arcrun-app/frontend/src/style.css": "24b3797c731720b60ce8a2a19582b4a76e8e37a9d2eacce8dbe205ba4008849b",
   "cmd/arcrun-app/gen-icons.py": "df5b3b33e500fc564badfc8bd2a9ca6a43f7d7e3b31111c41e3b322137c4c96c",
   "cmd/arcrun-app/go.mod": "8b9e57bcfd44886d1ec06480e033af706ff3fed470786c57074900dd48ecf86f",
   "cmd/arcrun-app/go.sum": "bc4453654c203e5af251c5a3061616cb0ceeb1b6a78a02ace2ca85524d217256",
@@ -88,13 +97,15 @@
   "cmd/arcrun-app/manifest_field_test.go": "8d7d742d54c5ef003d34ecd12f8d1e444e4e55c5dd0f8f8625f5e9c20cdf5285",
   "cmd/arcrun-app/quit_test.go": "c7b46b466ef5243cbecfaa236cecdc0c3466892a7dfadc6280e7a9c22f843389",
   "cmd/arcrun-app/quota_card_test.go": "6cc0afdb3de1fd002419523f80be0b290970bc965d68f7c1c63fa641ba10b488",
-  "cmd/arcrun-app/remove_folder_takedown_test.go": "46efb110a4f7afd89bab76072e17640e695772049391410f614a61110d8cd626",
+  "cmd/arcrun-app/remove_folder_cleanup_test.go": "e2d9636f92560f2f30fc256e7b27f5002e681ec07c3f6b348b344a4cdc22dbe8",
+  "cmd/arcrun-app/remove_folder_takedown_test.go": "6e30b13b9031e5d434bd1e38a0c8f66bc82ede5367123729529a8d35c982185f",
   "cmd/arcrun-app/selfupdate.go": "a1722cd1bfc90c8f068f3ee39f5aac43c7e9a5bf4a0144604482768e618065cb",
   "cmd/arcrun-app/selfupdate_test.go": "1c0752f3b3f4f262620e096558ded38ed21db94195b760a3f3b046ce9dbdd4ab",
   "cmd/arcrun-app/skipped_test.go": "f4c9de16c349c0b7f48ce62a6506364c87e3d4fbc99f415e3e6aec7d3da7f1aa",
   "cmd/arcrun-app/supervise.go": "f7eb6c74524b5d8d0abe520b831a98b85d19d18c00d1a585493ababcbd01c81f",
   "cmd/arcrun-app/tray_darwin.go": "ff3cb22fc2663b08b9f3cd14887ab4411ed338ec8920b58ad0fac029f09edae0",
   "cmd/arcrun-app/tray_darwin.m": "b4ddf0bb420adf00d580d65c8cfbbe130a78e803dd1e92a1617ddaf6ef172fac",
+  "cmd/arcrun-app/tray_other.go": "0c3df95b5f7999f6319d0bf5e24fdbf821bf97a79db04077d9e7eaf358299880",
   "cmd/arcrun-app/tray_windows.go": "adb4f390d3523ac3676f16c27f2b5ea4b9cee850113bc767a45ab9ce503d4963",
   "cmd/arcrun-app/update_api.go": "1e94052085cea79d406a06772fd171944090a31c30af0456f57b214b065d4d87",
   "cmd/arcrun-app/upgrade_repair_test.go": "65413d0b07b6c011de2af2783247d0f602a680a199229b52a77e176626c8ef26",
@@ -111,7 +122,7 @@
   "convert_table_test.go": "d0371b7566ef3152f9dd42f9f990e0dffa1c50a0c8e874a28415fa2e4c188394",
   "convert_test.go": "04f3fa30d1be5f910c0e0be3308ced2963191ab030a9eaccd986ef581fcd4e18",
   "convert_wiring_test.go": "09e97bf32ace245b55acc7d65ee5c0bb7fd84f8fb1aab61f603f9e9d18b22f13",
-  "direct.go": "98d51b233e31320de20f4c605ce420433fb4720136c9eb188fbd69e1a136fb69",
+  "direct.go": "1cf3a57ab5016a0fe7ad30c3e36789825f705de93456faeb237bee5e45e1c6ac",
   "direct_extract_test.go": "d3465c1b5953858ae780d192a2cf515d452f48eee3ff18a6345ce64320debbbb",
   "direct_multi_test.go": "d0aa211d90aaaa9d7dbe2b04f1aaa5989e91e91b037144cc0f4e0fd068f43c2b",
   "direct_pacing.go": "2690b2fff858250028886bc3cd7793be54b4d4a03ddca41485476cb04b79f7c3",
@@ -146,8 +157,8 @@
   "machineid.go": "d4224e684ecfbafe2efc7e0b95377f9e669ee1256a442aa72ce2cab3b219fc56",
   "machineid_test.go": "5b54ac62ee1fb28b8f0a873888aeddb844af0aa74472bfb849573cfc6691a290",
   "machinemark.go": "b93464c2ee89a73c0e0da38bcce5dc1ba6c1deba2fc483f28c6021c3ffdee4a0",
-  "main.go": "e02e7b32dd230f33e35c7ebf62d81b7599e2b86a0ef7cadc0fd34b672f42381d",
-  "manifest.go": "768049a34c06920711a980bb19fb41e7f1feff648f22265ba0c3d1c1ad85020f",
+  "main.go": "fe2f69739f3ee92713f8aaca925068ecf97b33d476eee826fc1e0d5def8f0d10",
+  "manifest.go": "cbfaf5fc83b5a0ff8c2a62d776bb1a8e0d99367ec31a7fbc4081bd56d848c145",
   "manifest_extractedby_test.go": "8019fe35675a1e801b7bda829ee1d647de32db03c029b1c651f71573e644c69e",
   "manifest_retry_test.go": "e6b4a321ccddfeed8cdbfabe6d031d5a9c59a33b47baf0b6d21150fa8406748a",
   "multiaccount_connected_test.go": "ba1817b73a5dd0dd5d300750e54d5c53bd82a75ef6e43caeddfcb2303d64ff66",
@@ -162,7 +173,7 @@
   "repoguard_test.go": "ce0316a59af944c3cf391961653fe82294fd45e728d35b4b7fcd99b2b20e7b5c",
   "safewrite.go": "d5dd09ffe894fb9fb94656a4bb50d246bd8c65ab21a7ad81463f43dfdacc8a57",
   "safewrite_test.go": "2980f0f86f78fb265403e31d4cba6da43f4dbc16e7c4711cfccba23175578358",
-  "scan.go": "23993b1411af0a0308aa6614e514d8c60bcbeed6ed93087b9c5bcc2e0f4763e9",
+  "scan.go": "03a15d7dac31a4853e1bf1baf760da6d26d708e2805a533ccef5d117a438856e",
   "scan_carry_lasterror_test.go": "6fa542422fb3e00b5ec4355b5db8df7086361b2dacefd67755d75c0ddfa55575",
   "scan_dedup_scale_test.go": "573b3c78bec86614bf4d2f99b7c3c3157f92c24af73cae7290428fc7f43f0362",
   "scan_dedup_test.go": "580ec58596ca54aa3d29b417e7d098fd2e3455fd39bf10e7da02d453c0786df0",
@@ -172,7 +183,7 @@
   "supervisor/hidewindow_windows.go": "29796dbe90ecb35e6f1451dacf956d42928c6a393271befc5c7f6863d5315fb3",
   "supervisor/supervisor.go": "cb17332ce5a7190627839e624895c56b508635edbd2c29758f794d5c3bb39388",
   "supervisor/supervisor_test.go": "f5582d54c55065fbc834fe96754df9c8cd6efe9f88f30208bbce84ddea08fea7",
-  "sync_status.go": "5f35c17a01e07146b155081714200e07eb54e5e0de191be0b2208b9e13e92daa",
+  "sync_status.go": "59e8e2c81ec5a1cbd46e852bd7c794c4179c76ac62561f21550a41afb9e2be2d",
   "sync_status_test.go": "9314b354679f0c5090257cf6918185c33b74102bfac0acb655c3e97b81a247b3",
   "t52_library_test.go": "14188d0afdad0f9aa16d19a74ea28c45c3d18fcfeabc5deb6fb0466d05778a51",
   "template_install.go": "d0aa0098e431696a63ef8d3714c124591b8ba193ccd5a8359a4ea03e397ee358",

cmd/arcrun-app/.version-source.json

@@ -4,5 +4,8 @@
  "0.18.31": "d6b2b6083258b853",
  "0.18.32": "4753db807169fe3d",
  "0.18.33": "7ba0f6dd2d080925",
- "0.18.34": "d8c7490b9d32e62e"
+ "0.18.34": "d8c7490b9d32e62e",
+ "0.18.35": "3bd7f3fb0124bda4",
+ "0.18.36": "abb2f2cc2498f071",
+ "0.18.37": "3bb5c94f68a26a06"
 }

cmd/arcrun-app/README.md

@@ -1,19 +1,84 @@
-# README
+# Arcrun 桌面小幫手（Wails）— 地端 build 說明
 
-## About
+> 這份取代了原本 `wails init` 留下的英文樣板 README（那份只寫「用 `wails build`」，
+> 而這裡真正的打包線是旁邊那四支腳本，不是裸的 `wails build`）。
+>
+> 🔴 **為什麼會有這份**（leo 2026-08-24，`inkstone/arcrun-rag#137`）：
+> 「daemon 部分要傳給地端做，**或是你做好給它 build**」——採後者。
+> 雲端只交**編得起來的 code**，安裝檔（DMG／exe／msix）由地端打，
+> 因為那需要 macOS／Windows 環境與簽章，雲端沒有。
 
-This is the official Wails Vanilla template.
+---
 
-You can configure the project by editing `wails.json`. More information about the project settings can be found
-here: https://wails.io/docs/reference/project-config
+## 一、一次性前置（每台機器裝一次）
 
-## Live Development
+| 需要 | 怎麼裝 | 用來做什麼 |
+|---|---|---|
+| Go **1.25+** | `brew install go`（`go.mod` 寫 `go 1.25.0`；較舊的 Go 會自己抓 toolchain） | 編 App 與 collector |
+| Node 18+ | `brew install node` | 編前端（Vite） |
+| Wails CLI v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@v2.13.0` | 打包 |
+| mingw-w64 | `brew install mingw-w64` | **只有要打 Windows 版才需要**（WebView2 要 CGo 交叉編譯） |
+| cmake、icu4c | `brew install cmake icu4c` ＋ `bash build-msix.sh --setup` | **只有要送 Microsoft Store 才需要** |
 
-To run in live development mode, run `wails dev` in the project directory. This will run a Vite development
-server that will provide very fast hot reload of your frontend changes. If you want to develop in a browser
-and have access to your Go methods, there is also a dev server that runs on http://localhost:34115. Connect
-to this in your browser, and you can call your Go code from devtools.
+> `wails` 裝完記得 `export PATH="$PATH:$(go env GOPATH)/bin"`（四支 build 腳本自己也會補這行）。
 
-## Building
+## 二、打包：跑既有的腳本，不要自己下 `wails build`
 
-To build a redistributable, production mode package, use `wails build`.
+```sh
+cd collector/cmd/arcrun-app
+
+./build-mac.sh      # → build/bin/Arcrun.app
+./build-dmg.sh      # → dist/Arcrun-<版本>.dmg      （自己會先跑 build-mac.sh）
+./build-win.sh      # → dist/Arcrun-<版本>.exe      （在 Mac 上交叉編譯，需 mingw-w64）
+./build-msix.sh     # → dist/Arcrun-<版本>.msix     （送 Store 用；不必自購憑證）
+```
+
+🔴 **版本號不要手打。** `daemon-version.py --stamp` 會從 `collector/CHANGELOG.md`
+最上面那個「下一版（未發佈）」段落戳出版號並補上日期——四支腳本都已經呼叫它。
+本次（`#137`）的 changelog 段落已經寫好，所以**這一版打出來會是 `0.18.35`**
+（`./daemon-version.py` 唯讀查詢可以先確認）。
+
+🔴 打包前若改過任何 `collector/` 底下的檔，指紋會變 ⇒ 同一個版號不准對應兩份原始碼，
+腳本會擋下來並告訴你怎麼辦。那是刻意的閘，不要繞過它。
+
+## 三、交貨前自己先驗（這三支都在本目錄，跑得很快）
+
+```sh
+go test ./...                       # 後端（含本次新增的 App 啟動器 12 條）
+bash check-cis.sh                   # CIS 合規（色票／lockup／選中態）
+npm --prefix frontend run build && node check-launcher.mjs   # 畫面與互動（需 playwright）
+```
+
+`check-launcher.mjs` 會真的把 `frontend/dist` 渲染出來、真的點下去，
+截圖丟在 `/tmp/arcrun-launcher-shots/`。沒裝 playwright 它會自己跳過
+（`npm i -D playwright && npx playwright install chromium`）。
+
+macOS 上另外還有 `check-render.sh`（量 lockup 像素與深色模式），需要本機的 Chrome。
+
+## 四、只有在真機上才驗得到的（雲端做不到，地端請補）
+
+雲端這台沒有 GUI、也沒有 WebView，所以下面這些**沒有被驗過**，
+打包完請在真機上走一次：
+
+1. `wails dev`（或直接開打好的 `Arcrun.app`）能不能起來、視窗尺寸對不對。
+2. 系統匣：Mac 是原生 `NSStatusItem`（`tray_darwin.m`）、Windows 是 `energye/systray`；
+   點 icon 開窗、右鍵只有「結束 Arcrun」。
+3. **App 啟動器**（本次新增）：打開就落在「App 界面」，九宮格列出的是你連的那個
+   知識庫實際裝了的 App；點一個進去、按一下它的動作，看結果回不回得來。
+4. Windows：WebView2 有沒有裝、SmartScreen 會不會攔、Defender 會不會誤判。
+
+## 五、平台檔案對照（改東西前先看這張）
+
+| 檔 | build tag | 說明 |
+|---|---|---|
+| `tray_darwin.go` / `tray_darwin.m` | `darwin` | macOS 原生 NSStatusItem |
+| `tray_windows.go` | `windows` | Windows systray |
+| `tray_other.go` | `!darwin && !windows` | **no-op**。讓 `go build`／`go test` 在 Linux／CI 上跑得起來，對出貨零影響（Linux 不是出貨平台） |
+| `dock_darwin.go` / `dock_other.go` | 同上 | Dock icon 隱藏 |
+
+## 六、開發時的即時預覽
+
+```sh
+wails dev
+```
+Vite 熱重載；`http://localhost:34115` 可以用瀏覽器連進去，Go 方法一樣叫得到。

cmd/arcrun-app/app.go

@@ -68,6 +68,15 @@ type accountCfg struct {
 	RetiringFolders []string `json:"retiring_folders,omitempty"`
 	Extractor       string   `json:"extractor,omitempty"`
 	GeminiAPIKey    string   `json:"gemini_api_key,omitempty"`
+	// PortalSession／PortalSessionExp＝這台電腦對這個知識庫的 portal 登入憑證
+	// （arcrun-rag#137 App 啟動器用；App 詳情與動作只有 portal session 那條路有，
+	// 見 apps.go 檔頭）。**這是 session token 不是密碼**——密碼仍然零落地。
+	//
+	// 🔴 這兩欄是 App 端獨有的（collector 的 AccountConfig 沒有）：collector 讀 config
+	//    時會忽略不認得的欄位，所以加在這裡是安全的；反過來（collector 有而這裡沒有）
+	//    才是上面那條註解講的、會靜默掉欄位的方向。
+	PortalSession    string `json:"portal_session,omitempty"`
+	PortalSessionExp int64  `json:"portal_session_exp,omitempty"`
 }
 
 type directConfig struct {
@@ -110,6 +119,9 @@ type syncStatus struct {
 	// arcrun-rag#46：「移除並收回中」的資料夾進度（key＝資料夾路徑）。
 	// 形狀定義在 collector/sync_status.go，這裡原樣接住不另定義一份會漂移的結構。
 	Retiring map[string]collector.RetiringStatus `json:"retiring,omitempty"`
+	// arcrun-rag#140：雲端上找不到、正在自動補送的資料夾（key＝資料夾路徑）。
+	// 同上：形狀定義在 collector/sync_status.go，這裡原樣接住。
+	Resync map[string]collector.ResyncStatus `json:"resync,omitempty"`
 }
 
 type skippedDoc struct {
@@ -232,6 +244,10 @@ type UIFolder struct {
 	Retiring        bool   `json:"retiring,omitempty"`
 	RetireRemaining int    `json:"retireRemaining,omitempty"` // 還剩幾筆
 	RetireError     string `json:"retireError,omitempty"`     // 失敗真因（原文，不改寫）
+	// arcrun-rag#140：雲端上找不到先前送過的檔案（知識庫被重裝／清空過），正在自動補送。
+	// 🔴 這張票的病有一半是「**沒有任何地方會說話**」——檔案在資料夾裡、AI 卻查不到，
+	//    而且查不出為什麼。所以補送不能靜悄悄地跑，這一行就是那句話的落點。
+	ResyncNote string `json:"resyncNote,omitempty"` // 一句人話（沒事＝空字串，前端不畫）
 }
 type UIAccount struct {
 	Name    string     `json:"name"`
@@ -496,7 +512,13 @@ func (a *App) GetState() UIState {
 	for i, acc := range cfg.Accounts {
 		ui := UIAccount{Name: accountName(acc), Host: shortHost(acc.CypherURL), Email: acc.Email}
 		for _, f := range acc.WatchFolders {
-			ui.Folders = append(ui.Folders, UIFolder{Path: f, AccIdx: i})
+			uf := UIFolder{Path: f, AccIdx: i}
+			// arcrun-rag#140：雲端補送中就把那句人話帶到畫面上。
+			// key＝資料夾路徑，與 collector 寫入 status.json 時同一把（見 direct.go 的 resync[root]）。
+			if rs, ok := sync.Resync[f]; ok {
+				uf.ResyncNote = rs.Note
+			}
+			ui.Folders = append(ui.Folders, uf)
 		}
 		// 收回中的資料夾照樣列出來，只是標成「收回中」——不然按下移除之後它立刻消失，
 		// 使用者無從知道撤除還在跑、更看不到失敗的原因（那正是這張票的病的另一面）。
@@ -719,7 +741,18 @@ func (a *App) AddFolder(accIdx int, path string) error {
 // vs 我不要這份資料了），而**猜錯任何一邊都是不可逆的**——猜「保留」則產品承諾的
 // 「資料所有權完全屬於使用者」是假的；猜「收回」則整理好的知識被誤刪。
 // ⇒ 在動作的當下把兩個後果講清楚、讓他自己挑（見前端 confirmRemove 的文案）。
-func (a *App) RemoveFolder(accIdx int, path string, takedown bool) error {
+//
+// cleanupLocal＝第三個獨立選擇（arcrun-rag#138，leo 2026-08-24：「碎型會在每個資料夾
+// 安裝隱藏資料夾，人工刪除不容易，所以當它斷連，應該要可以幫它把 Arcrun RAG 建立的
+// 資料夾刪掉」）：連同硬碟上那些隱藏資料夾一起收掉。
+//
+// 與 takedown **正交，不合成一個開關**：takedown 管**雲端**的知識（搜尋還找不找得到），
+// cleanupLocal 管**他硬碟上**的產物（資料夾乾不乾淨）。兩個後果不一樣，合起來就是替他決定
+// ——這正是 #46 那次修掉的病，別再犯一次。
+//
+// 🔴 順序不可顛倒：**先把資料夾從 WatchFolders 拿掉並重啟看守，再刪本地產物。**
+// 反過來的話 collector 還看著那個根，剛刪掉的 `.wiki/` 下一輪就長回來。
+func (a *App) RemoveFolder(accIdx int, path string, takedown, cleanupLocal bool) error {
 	cfg, err := loadCfg()
 	if err != nil {
 		return err
@@ -753,6 +786,17 @@ func (a *App) RemoveFolder(accIdx int, path string, takedown bool) error {
 		return err
 	}
 	restartWatch()
+	if cleanupLocal && found {
+		// 看守已經停掉了（restartWatch 讀的是剛存下去的設定），現在刪才不會被重建。
+		// 刪不掉的那幾筆不讓整個移除失敗——資料夾已經從清單拿掉了，那是使用者要的主要結果；
+		// 清理是附帶的善後，回一個講得出「哪幾筆沒刪掉、為什麼」的錯誤就好。
+		if _, res, cerr := collector.ApplyCleanup(path, cfg.otherWatchedRoots(accIdx, path)); cerr != nil {
+			return fmt.Errorf("資料夾已經移除，但清理 Arcrun RAG 建立的檔案時出錯：%w", cerr)
+		} else if len(res.Failed) > 0 {
+			return fmt.Errorf("資料夾已經移除，但有 %d 個項目刪不掉（第一個：%s——%s）",
+				len(res.Failed), res.Failed[0].Rel, res.Failed[0].Error)
+		}
+	}
 	if takedown {
 		// 不必等下一輪輪詢——使用者剛按下按鈕，他期待「現在就開始」。
 		// 沿用既有的 sync-now 訊號檔，不新發明一套 IPC。
@@ -761,6 +805,43 @@ func (a *App) RemoveFolder(accIdx int, path string, takedown bool) error {
 	return nil
 }
 
+// PlanFolderCleanup 回答「按下『連同這個資料夾裡的檔案一起清掉』會刪到哪些東西」。
+//
+// 🔴 #138 的驗收條件之一：「使用者要能在動手前看到將要刪掉哪些東西」——不是按下去就無聲刪光。
+// 這支**只讀不寫**（collector.PlanCleanup 保證），前端在確認對話框裡先叫它、把清單攤出來。
+// 真的動手時 ApplyCleanup 會**重算一次**，所以這裡拿到的清單過期也不會刪錯東西。
+func (a *App) PlanFolderCleanup(accIdx int, path string) (*collector.CleanupPlan, error) {
+	cfg, err := loadCfg()
+	if err != nil {
+		return nil, err
+	}
+	if accIdx < 0 || accIdx >= len(cfg.Accounts) {
+		return nil, fmt.Errorf("找不到這個知識庫帳號")
+	}
+	return collector.PlanCleanup(path, cfg.otherWatchedRoots(accIdx, path))
+}
+
+// otherWatchedRoots＝除了 path 以外、**所有帳號**還在看守（或還在收回中）的資料夾。
+//
+// 🔴 為什麼要跨帳號收集：巢狀擺法是真的（2026-08-24 現場，`pms` 與 `pms/pms_v1_legacy`
+// 同時在同一個帳號的看守清單裡）。移除外層時把內層的工作區刪掉＝把一個還在跑的同步弄壞，
+// 而且不同帳號可以看守同一棵樹底下的不同層——判準是「這條路徑還有沒有人在用」，
+// 跟它掛在哪個帳號無關。
+func (c *directConfig) otherWatchedRoots(accIdx int, path string) []string {
+	var out []string
+	for i := range c.Accounts {
+		for _, f := range c.Accounts[i].WatchFolders {
+			if i == accIdx && f == path {
+				continue
+			}
+			out = append(out, f)
+		}
+		// 還在收回中的資料夾同樣還沒結束——它的帳本正在被逐筆撤除，別去動它的檔。
+		out = append(out, c.Accounts[i].RetiringFolders...)
+	}
+	return out
+}
+
 // pruneFinishedRetirements 把「collector 已回報收乾淨」的資料夾從設定裡清掉。
 //
 // 為什麼由 App 清而不是 collector 自己清：config.json 的寫入者只有 App 一個，

cmd/arcrun-app/apps.go

@@ -0,0 +1,495 @@
+package main
+
+// apps.go — 桌面小幫手的 App 啟動器後端（inkstone/arcrun-rag#137）
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// 這個檔案在解什麼
+// ─────────────────────────────────────────────────────────────────────────────
+// leo 2026-08-24：「所有的 App 需要有一個類似 Android/iOS 的九宮格啟動界面，
+// 每個 App 有一個 icon，**這會運行在 portal 及 daemon**。」
+//
+// 桌面這半沒有自己的 KBDB，也**不准**在本機另存一份 App 清單
+// （上游 `inkstone/Arcrun#82` 已定「安裝態只有一份真相源」＝實例的 `{tenant}:app:{id}`）。
+// ⇒ 本檔做的事只有一件：**去使用者連的那個實例問**，把答案原樣交給畫面。
+// 沒有任何預設清單、沒有快取到磁碟、沒有第二份 schema。
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// 為什麼是「兩條路」而不是一條（這是本票的規格判斷，理由寫在這裡不寫在票上）
+// ─────────────────────────────────────────────────────────────────────────────
+// 上游同一份安裝態有兩個對外面：
+//
+//	① `/portal/data/apps*`      認 **portal session**（Bearer）——Portal 那半走這條，
+//	   清單／詳情（含畫面 HTML）／動作三支齊全。
+//	② `/apps`                   認 **X-Arcrun-API-Key**（＝實例 namespace）——CLI／操盤 AI 走這條，
+//	   **只有清單**，沒有詳情、沒有動作。
+//
+// 小幫手手上本來就有 ②的鑰匙（`config.json` 的 `api_key`，連線時實例自己下發的），
+// 但**沒有**①的 session（密碼刻意零落地，見 connect.go）。
+//
+// 所以：
+//   - **清單一律先走①、拿不到就退回②**。兩支回的都是 `summarizeApp` 的同一個形狀
+//     （id/name/icon/has_ui/version），所以九宮格**在完全沒登入的情況下也是真資料**。
+//   - **詳情與動作只有①有**，所以那兩件需要一次 portal 登入。連線精靈當下順手換一張
+//     session（`Connect` 已經有密碼在手，見 connect.go 的呼叫點），使用者通常不會再被問。
+//     session 過期（實例預設 7 天）才會在 App 頁上出現一次登入框。
+//
+// 🔴 密碼仍然零落地：存的是 session token，不是密碼（與 connect.go 同一條紅線）。
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// 不做輪詢
+// ─────────────────────────────────────────────────────────────────────────────
+// 畫面每秒打一次 `GetState()`，但**本檔的任何函式都不掛在那條線上**——
+// App 清單只在「打開啟動器」與「按重新整理」時才去問實例一次。
+// 把網路請求塞進每秒的 tick 等於自己造一個輪詢器，那是明令禁止的形狀。
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// appHTTPTimeout：App 動作背後是一整條工作流（可能打 LLM），比單純讀清單久得多。
+// 清單／詳情用短的，動作用長的——不讓「讀清單」被一條慢工作流的預算拖著。
+const (
+	appReadTimeout   = 20 * time.Second
+	appActionTimeout = 120 * time.Second
+)
+
+// ── 前端要的形狀 ───────────────────────────────────────────────────────────
+
+// UIApp＝九宮格上的一格。逐欄對應上游 `summarizeApp`，不多不少——
+// 多一欄就是在桌面端發明一個實例不認得的概念。
+type UIApp struct {
+	ID      string `json:"id"`
+	Name    string `json:"name"`
+	Icon    string `json:"icon"`
+	HasUI   bool   `json:"hasUi"`
+	Version string `json:"version"`
+}
+
+// UIAppList＝一個知識庫的啟動器內容。
+//
+// 🔴 Error 與「空清單」是兩件事，不准混成同一句話（arcrun-rag#10「寧可明顯失敗」）：
+//   - `Error != ""`  ⇒ 問不到（連不上／實例太舊沒有這支端點）——畫面要說「問不到」
+//   - `Error == "" && len(Apps) == 0` ⇒ 真的一個都沒裝——畫面要說「還沒有 App」
+//
+// 兩者長得像，但使用者該做的事完全相反。
+type UIAppList struct {
+	AccIdx  int     `json:"accIdx"`
+	Account string  `json:"account"` // 知識庫顯示名（畫面上的切換器用）
+	Host    string  `json:"host"`
+	Apps    []UIApp `json:"apps"`
+	Error   string  `json:"error"`
+	// Source＝這份清單是用哪把鑰匙問到的（"session"／"apikey"）。給診斷用，
+	// 畫面不依它分支——兩條路的內容是同一份安裝態。
+	Source string `json:"source"`
+}
+
+// UIAppWorkflow＝App 的一條工作流（沒有自帶畫面的 App 就靠這個列表當預設畫面，
+// 與 Portal 的 renderAppView 同一套呈現，不另立第二種）。
+type UIAppWorkflow struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+// UIAppDetail＝點進一個 App 之後要的全部東西。
+type UIAppDetail struct {
+	ID        string          `json:"id"`
+	Name      string          `json:"name"`
+	Icon      string          `json:"icon"`
+	Version   string          `json:"version"`
+	HasUI     bool            `json:"hasUi"`
+	UIHtml    string          `json:"uiHtml"`
+	Workflows []UIAppWorkflow `json:"workflows"`
+	Actions   []string        `json:"actions"`
+	// NeedsLogin＝這台機器沒有（或已過期）這個知識庫的 portal session。
+	// 不是錯誤，是「還差一步」——畫面要長出登入框，不是紅字。
+	NeedsLogin bool   `json:"needsLogin"`
+	Email      string `json:"email"` // 登入框預填（帳號本來就存在 config 裡）
+	Error      string `json:"error"`
+}
+
+// ── 內部：HTTP 小工具 ─────────────────────────────────────────────────────
+
+// apiBaseOf 回傳這個帳號的 API base（cypher origin）。
+// 連線精靈存進來的 CypherURL 已經是 API 位址（normalizePortalURL 換算過），
+// 這裡只做去尾斜線，**不重新發明第二套換算**。
+func apiBaseOf(a accountCfg) string {
+	return strings.TrimRight(strings.TrimSpace(a.CypherURL), "/")
+}
+
+// accountAt 取第 idx 個帳號；越界回錯（前端傳來的索引可能落後於剛改過的設定）。
+func accountAt(cfg *directConfig, idx int) (accountCfg, error) {
+	if cfg == nil || idx < 0 || idx >= len(cfg.Accounts) {
+		return accountCfg{}, errors.New("找不到這個知識庫")
+	}
+	return cfg.Accounts[idx], nil
+}
+
+// appDo 送一個請求並讀回 body。回傳 (status, body, err)；err 只代表「連不上」，
+// HTTP 4xx/5xx 一律當成「連得上但被拒絕」由呼叫端判讀——
+// 把兩者混成一個 error 就分不出「網路斷了」與「密碼過期了」。
+func appDo(req *http.Request, timeout time.Duration) (int, []byte, error) {
+	res, err := (&http.Client{Timeout: timeout}).Do(req)
+	if err != nil {
+		return 0, nil, errors.New("連不上這個知識庫——請確認網路正常")
+	}
+	defer res.Body.Close()
+	b, _ := io.ReadAll(io.LimitReader(res.Body, 4<<20)) // App 自帶畫面可能不小，但給上限
+	return res.StatusCode, b, nil
+}
+
+// appErrMessage 從實例回的 JSON 撈 error 欄位；撈不到就用狀態碼講人話。
+func appErrMessage(status int, body []byte) string {
+	var e struct {
+		Error string `json:"error"`
+	}
+	if json.Unmarshal(body, &e) == nil && strings.TrimSpace(e.Error) != "" {
+		return e.Error
+	}
+	switch status {
+	case http.StatusNotFound:
+		return "這個知識庫還沒有 App 功能（實例版本較舊，更新後就會出現）"
+	case http.StatusUnauthorized, http.StatusForbidden:
+		return "這個知識庫的登入已過期"
+	}
+	return fmt.Sprintf("知識庫回了 HTTP %d", status)
+}
+
+// ── portal session（詳情與動作唯一的鑰匙）────────────────────────────────
+
+// sessionValid：留 60 秒安全邊際，免得剛好在請求路上過期。
+func sessionValid(a accountCfg) bool {
+	return strings.TrimSpace(a.PortalSession) != "" &&
+		(a.PortalSessionExp == 0 || time.Now().Unix() < a.PortalSessionExp-60)
+}
+
+// portalLogin 用帳密換一張 portal session token。
+//
+// 🔴 這支是**唯一**碰密碼的地方，而且密碼只活在參數裡：換完就丟，不寫檔、不 log。
+func portalLogin(base, email, password string) (token string, expiresIn int64, err error) {
+	body, _ := json.Marshal(map[string]string{
+		"email":    strings.ToLower(strings.TrimSpace(email)),
+		"password": password,
+	})
+	req, err := http.NewRequest(http.MethodPost, base+"/portal/login", bytes.NewReader(body))
+	if err != nil {
+		return "", 0, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	status, raw, err := appDo(req, appReadTimeout)
+	if err != nil {
+		return "", 0, err
+	}
+	var out struct {
+		Success        bool   `json:"success"`
+		SessionToken   string `json:"session_token"`
+		SessionExpires int64  `json:"session_expires_in"`
+		Error          string `json:"error"`
+	}
+	_ = json.Unmarshal(raw, &out)
+	if status != http.StatusOK || !out.Success || out.SessionToken == "" {
+		if strings.TrimSpace(out.Error) != "" {
+			return "", 0, errors.New(out.Error)
+		}
+		return "", 0, errors.New(appErrMessage(status, raw))
+	}
+	return out.SessionToken, out.SessionExpires, nil
+}
+
+// storeSession 把換到的 session 寫回設定（只存 token 與到期時間，不存密碼）。
+func storeSession(idx int, token string, expiresIn int64) error {
+	cfg, err := loadCfg()
+	if err != nil {
+		return err
+	}
+	if idx < 0 || idx >= len(cfg.Accounts) {
+		return errors.New("找不到這個知識庫")
+	}
+	cfg.Accounts[idx].PortalSession = token
+	if expiresIn > 0 {
+		cfg.Accounts[idx].PortalSessionExp = time.Now().Unix() + expiresIn
+	} else {
+		cfg.Accounts[idx].PortalSessionExp = 0
+	}
+	return saveCfg(cfg)
+}
+
+// clearSession 在實例說「這張 session 不算數」時把它丟掉。
+// 留著一張已知無效的 token 只會讓下一次再撞一次 401，然後畫面又閃一下錯誤。
+func clearSession(idx int) {
+	cfg, err := loadCfg()
+	if err != nil || idx < 0 || idx >= len(cfg.Accounts) {
+		return
+	}
+	if cfg.Accounts[idx].PortalSession == "" && cfg.Accounts[idx].PortalSessionExp == 0 {
+		return
+	}
+	cfg.Accounts[idx].PortalSession = ""
+	cfg.Accounts[idx].PortalSessionExp = 0
+	if err := saveCfg(cfg); err != nil {
+		appLog("清掉過期的知識庫登入失敗：%v", err)
+	}
+}
+
+// tryStoreSessionFromLogin 在連線精靈成功之後順手換一張 session（connect.go 呼叫）。
+// **失敗不算連線失敗**——沒有 session 只是「App 詳情要再登入一次」，
+// 而資料夾同步這條主線根本用不到它。
+func tryStoreSessionFromLogin(cfg *directConfig, idx int, email, password string) {
+	if idx < 0 || idx >= len(cfg.Accounts) {
+		return
+	}
+	token, exp, err := portalLogin(apiBaseOf(cfg.Accounts[idx]), email, password)
+	if err != nil {
+		appLog("連線成功但沒換到知識庫的 App 登入（不影響同步）：%v", err)
+		return
+	}
+	cfg.Accounts[idx].PortalSession = token
+	if exp > 0 {
+		cfg.Accounts[idx].PortalSessionExp = time.Now().Unix() + exp
+	}
+}
+
+// ── 前端呼叫的四支 ─────────────────────────────────────────────────────────
+
+// ListApps 回一個知識庫上「實際裝了的」App。
+//
+// 兩條路的順序與理由見檔頭。**沒有任何寫死的清單**——問不到就誠實說問不到。
+func (a *App) ListApps(accIdx int) UIAppList {
+	out := UIAppList{AccIdx: accIdx}
+	cfg, _ := loadCfg()
+	acc, err := accountAt(cfg, accIdx)
+	if err != nil {
+		out.Error = err.Error()
+		return out
+	}
+	out.Account = accountName(acc)
+	out.Host = shortHost(acc.CypherURL)
+	base := apiBaseOf(acc)
+	if base == "" {
+		out.Error = "這個知識庫沒有網址，請重新連線一次"
+		return out
+	}
+
+	// ① portal session（與 Portal 那半同一支端點、同一份權限）
+	if sessionValid(acc) {
+		req, _ := http.NewRequest(http.MethodGet, base+"/portal/data/apps", nil)
+		req.Header.Set("Authorization", "Bearer "+acc.PortalSession)
+		status, raw, derr := appDo(req, appReadTimeout)
+		switch {
+		case derr != nil:
+			out.Error = derr.Error()
+			return out
+		case status == http.StatusOK:
+			out.Apps = parseAppList(raw)
+			out.Source = "session"
+			return out
+		case status == http.StatusUnauthorized || status == http.StatusForbidden:
+			clearSession(accIdx) // 過期了 ⇒ 掉到 ② 去，清單照樣看得到
+		default:
+			// 其他錯（例如 5xx）**不要**掉到 ②——那會把「實例出問題」偽裝成正常。
+			out.Error = appErrMessage(status, raw)
+			return out
+		}
+	}
+
+	// ② 實例 API key（小幫手本來就有的那把；只有清單，沒有詳情／動作）
+	if strings.TrimSpace(acc.APIKey) == "" {
+		out.Error = "這台電腦還沒有這個知識庫的鑰匙，請重新連線一次"
+		return out
+	}
+	req, _ := http.NewRequest(http.MethodGet, base+"/apps", nil)
+	req.Header.Set("X-Arcrun-API-Key", acc.APIKey)
+	status, raw, derr := appDo(req, appReadTimeout)
+	if derr != nil {
+		out.Error = derr.Error()
+		return out
+	}
+	if status != http.StatusOK {
+		out.Error = appErrMessage(status, raw)
+		return out
+	}
+	out.Apps = parseAppList(raw)
+	out.Source = "apikey"
+	return out
+}
+
+// parseAppList 讀 `{apps:[…]}`。兩支端點回的都是 summarizeApp 的形狀，所以只有一份解析。
+// 純函式（單測用）。
+func parseAppList(raw []byte) []UIApp {
+	var body struct {
+		Apps []struct {
+			ID      string `json:"id"`
+			Name    string `json:"name"`
+			Icon    string `json:"icon"`
+			HasUI   bool   `json:"has_ui"`
+			Version string `json:"version"`
+		} `json:"apps"`
+	}
+	if json.Unmarshal(raw, &body) != nil {
+		return nil
+	}
+	apps := make([]UIApp, 0, len(body.Apps))
+	for _, x := range body.Apps {
+		name := x.Name
+		if strings.TrimSpace(name) == "" {
+			name = x.ID
+		}
+		apps = append(apps, UIApp{ID: x.ID, Name: name, Icon: x.Icon, HasUI: x.HasUI, Version: x.Version})
+	}
+	return apps
+}
+
+// GetApp 取一個 App 的詳情（自帶畫面／工作流清單／動作白名單）。
+//
+// 🔴 只有 portal session 這一條路——上游的 API key 面**沒有**詳情端點
+//
+//	（`/apps` 只有列表；見 `cypher-executor/src/routes/apps.ts`）。
+//	所以沒有 session 時回 NeedsLogin，讓畫面長一次登入框，而不是回一句錯誤。
+func (a *App) GetApp(accIdx int, id string) UIAppDetail {
+	out := UIAppDetail{ID: id}
+	cfg, _ := loadCfg()
+	acc, err := accountAt(cfg, accIdx)
+	if err != nil {
+		out.Error = err.Error()
+		return out
+	}
+	out.Email = acc.Email
+	if !sessionValid(acc) {
+		out.NeedsLogin = true
+		return out
+	}
+	base := apiBaseOf(acc)
+	req, _ := http.NewRequest(http.MethodGet, base+"/portal/data/apps/"+urlPathEscape(id), nil)
+	req.Header.Set("Authorization", "Bearer "+acc.PortalSession)
+	status, raw, derr := appDo(req, appReadTimeout)
+	if derr != nil {
+		out.Error = derr.Error()
+		return out
+	}
+	if status == http.StatusUnauthorized || status == http.StatusForbidden {
+		clearSession(accIdx)
+		out.NeedsLogin = true
+		return out
+	}
+	if status != http.StatusOK {
+		out.Error = appErrMessage(status, raw)
+		return out
+	}
+	var d struct {
+		ID        string   `json:"id"`
+		Name      string   `json:"name"`
+		Icon      string   `json:"icon"`
+		Version   string   `json:"version"`
+		HasUI     bool     `json:"has_ui"`
+		UIHtml    string   `json:"ui_html"`
+		Actions   []string `json:"actions"`
+		Workflows []struct {
+			Name        string `json:"name"`
+			Description string `json:"description"`
+		} `json:"workflows"`
+	}
+	if json.Unmarshal(raw, &d) != nil {
+		out.Error = "這個知識庫回的內容看不懂（版本可能不相容）"
+		return out
+	}
+	out.ID, out.Name, out.Icon, out.Version = d.ID, d.Name, d.Icon, d.Version
+	out.HasUI, out.UIHtml, out.Actions = d.HasUI, d.UIHtml, d.Actions
+	for _, w := range d.Workflows {
+		out.Workflows = append(out.Workflows, UIAppWorkflow{Name: w.Name, Description: w.Description})
+	}
+	if strings.TrimSpace(out.Name) == "" {
+		out.Name = out.ID
+	}
+	return out
+}
+
+// RunAppAction 觸發 App 的一個白名單動作，回傳實例給的結果 JSON（原樣字串）。
+//
+// 🔴 白名單由**實例**裁決，不在這裡複製一份判斷（K6：前端／桌面端都不是裁決點）。
+//
+//	這裡不認得任何 action 名稱，只負責把使用者按的那顆按鈕送出去。
+//
+// payloadJSON 是前端組好的 JSON 物件字串；空字串＝沒有 payload。
+func (a *App) RunAppAction(accIdx int, id, action, payloadJSON string) (string, error) {
+	cfg, _ := loadCfg()
+	acc, err := accountAt(cfg, accIdx)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(action) == "" {
+		return "", errors.New("沒有指定要做什麼")
+	}
+	if !sessionValid(acc) {
+		return "", errors.New("這個知識庫的登入已過期，請在畫面上重新登入一次")
+	}
+	var payload any = map[string]any{}
+	if s := strings.TrimSpace(payloadJSON); s != "" {
+		if err := json.Unmarshal([]byte(s), &payload); err != nil {
+			return "", errors.New("送出的內容格式不對")
+		}
+	}
+	body, _ := json.Marshal(map[string]any{"action": action, "payload": payload})
+	req, err := http.NewRequest(http.MethodPost,
+		apiBaseOf(acc)+"/portal/data/apps/"+urlPathEscape(id)+"/action", bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+acc.PortalSession)
+	status, raw, derr := appDo(req, appActionTimeout)
+	if derr != nil {
+		return "", derr
+	}
+	if status == http.StatusUnauthorized || status == http.StatusForbidden {
+		// 403 也可能是「這個動作不在白名單」——那句話由實例自己講，這裡照抄。
+		if status == http.StatusUnauthorized {
+			clearSession(accIdx)
+		}
+		return "", errors.New(appErrMessage(status, raw))
+	}
+	if status != http.StatusOK {
+		return "", errors.New(appErrMessage(status, raw))
+	}
+	return string(raw), nil
+}
+
+// PortalLogin 讓使用者在 App 頁上補一次登入（session 過期時）。
+// email 用 config 裡存的那個（就是他連線時用的帳號），只問密碼。
+func (a *App) PortalLogin(accIdx int, password string) error {
+	cfg, _ := loadCfg()
+	acc, err := accountAt(cfg, accIdx)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(acc.Email) == "" {
+		return errors.New("這個知識庫沒有記錄帳號，請用「新增知識庫帳號」重新連一次")
+	}
+	token, exp, err := portalLogin(apiBaseOf(acc), acc.Email, password)
+	if err != nil {
+		return err
+	}
+	return storeSession(accIdx, token, exp)
+}
+
+// urlPathEscape：App id 的字元集上游已限死 `^[a-z][a-z0-9_-]{0,63}$`，
+// 但我們是**收方**不是**發方**——照樣 escape，不假設對面永遠守規矩。
+func urlPathEscape(s string) string {
+	var b strings.Builder
+	for _, r := range s {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9',
+			r == '-', r == '_', r == '.', r == '~':
+			b.WriteRune(r)
+		default:
+			for _, c := range []byte(string(r)) {
+				fmt.Fprintf(&b, "%%%02X", c)
+			}
+		}
+	}
+	return b.String()
+}

cmd/arcrun-app/apps_test.go

@@ -0,0 +1,384 @@
+package main
+
+// apps_test.go — App 啟動器後端的驗收（inkstone/arcrun-rag#137）
+//
+// 🔴 這裡的假實例**不是憑印象寫的**：每一支端點的路徑、認證標頭、回應欄位名，
+//
+//	都是照 `inkstone/Arcrun` 分支 `feat/app-system-v0` 的原始碼抄下來的
+//	（`cypher-executor/src/routes/apps.ts`、`routes/portal-data.ts`、
+//	 `lib/app-system.ts` 的 summarizeApp／detailApp、`routes/portal.ts` 的 /portal/login）。
+//	抄錯了測試就會綠得很假——所以下面每一段都標了它對應上游哪一支。
+//
+// 這組測試回答的是驗收條件 1 與 2 裡「機器答得出來」的那幾格：
+//   - 清單真的來自實例（兩條路都試過），桌面端沒有任何寫死清單
+//   - 「問不到」與「一個都沒裝」分得出來
+//   - session 過期會被清掉、且清單仍然看得到（退回 API key）
+//   - 動作真的打到 /portal/data/apps/:id/action，白名單由實例裁決
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeCfgWithAccount 造一份最小可用的 config.json（一個知識庫）。
+func writeCfgWithAccount(t *testing.T, base string, acc accountCfg) {
+	t.Helper()
+	acc.CypherURL = base
+	if acc.Namespace == "" {
+		acc.Namespace = "ns-test"
+	}
+	cfg := map[string]any{
+		"manifest": filepath.Join(appDir(), "manifest.json"),
+		"accounts": []accountCfg{acc},
+	}
+	b, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(appDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(configPath(), b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func tempHome(t *testing.T) {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+}
+
+// fakeInstance 是「一台裝了 App 系統的 Arcrun 實例」的最小替身。
+type fakeInstance struct {
+	// sessionToken＝目前有效的 session；空字串＝任何 Bearer 都算過期。
+	sessionToken string
+	password     string
+	apiKey       string
+	// 收到的動作（給測試斷言用）
+	gotAction  string
+	gotPayload map[string]any
+	// 讓測試模擬「實例壞掉」
+	listStatus int
+}
+
+func (f *fakeInstance) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	// 上游 summarizeApp 的形狀（lib/app-system.ts）
+	summary := []map[string]any{
+		{"id": "note", "name": "筆記", "icon": "🗒️", "has_ui": true, "version": "0.1.0"},
+		{"id": "weekly", "name": "週報", "icon": "📊", "has_ui": false, "version": "0.2.0"},
+	}
+	mux := http.NewServeMux()
+
+	// POST /portal/login（routes/portal.ts）
+	mux.HandleFunc("/portal/login", func(w http.ResponseWriter, r *http.Request) {
+		var in struct{ Email, Password string }
+		_ = json.NewDecoder(r.Body).Decode(&in)
+		if in.Password != f.password {
+			w.WriteHeader(401)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "email 或密碼錯誤"})
+			return
+		}
+		f.sessionToken = "sess-" + in.Email
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"success": true, "session_token": f.sessionToken, "session_expires_in": 604800,
+		})
+	})
+
+	// GET /apps（routes/apps.ts，X-Arcrun-API-Key）
+	mux.HandleFunc("/apps", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Arcrun-API-Key") != f.apiKey {
+			w.WriteHeader(401)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "缺少 X-Arcrun-API-Key header"})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"apps": summary, "count": len(summary)})
+	})
+
+	// /portal/data/apps*（routes/portal-data.ts，Bearer portal session）
+	mux.HandleFunc("/portal/data/apps", func(w http.ResponseWriter, r *http.Request) {
+		if !f.authed(r) {
+			w.WriteHeader(401)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "session 無效或已過期"})
+			return
+		}
+		if f.listStatus != 0 {
+			w.WriteHeader(f.listStatus)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "實例內部錯誤"})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"apps": summary, "count": len(summary)})
+	})
+	mux.HandleFunc("/portal/data/apps/", func(w http.ResponseWriter, r *http.Request) {
+		if !f.authed(r) {
+			w.WriteHeader(401)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "session 無效或已過期"})
+			return
+		}
+		rest := strings.TrimPrefix(r.URL.Path, "/portal/data/apps/")
+		if strings.HasSuffix(rest, "/action") {
+			id := strings.TrimSuffix(rest, "/action")
+			var in struct {
+				Action  string         `json:"action"`
+				Payload map[string]any `json:"payload"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&in)
+			// 上游 runAppAction：白名單不中 → 403（K6，裁決點在實例不在呼叫端）
+			if id != "note" || in.Action != "notes-create" {
+				w.WriteHeader(403)
+				_ = json.NewEncoder(w).Encode(map[string]any{"error": "這個動作不在這個 App 的白名單內"})
+				return
+			}
+			f.gotAction, f.gotPayload = in.Action, in.Payload
+			_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "result": map[string]any{"id": "blk_1"}})
+			return
+		}
+		if rest != "note" {
+			w.WriteHeader(404)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": "找不到這個 App"})
+			return
+		}
+		// 上游 detailApp 的形狀
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"id": "note", "name": "筆記", "icon": "🗒️", "version": "0.1.0",
+			"has_ui": true, "ui_html": "<div id=x>hi</div>",
+			"workflows": []map[string]string{{"name": "notes-create", "description": "寫入一則筆記"}},
+			"actions":   []string{"notes-create"},
+		})
+	})
+	return httptest.NewServer(mux)
+}
+
+func (f *fakeInstance) authed(r *http.Request) bool {
+	tok := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
+	return f.sessionToken != "" && tok == f.sessionToken
+}
+
+// ── 驗收條件 1：清單來自實例，兩條路都通 ────────────────────────────────
+
+func TestListApps_UsesPortalSessionWhenAvailable(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "sess-a", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{
+		InstanceName: "我的庫", Email: "a@b.c", APIKey: "ns-test",
+		PortalSession: "sess-a", PortalSessionExp: 0,
+	})
+
+	got := (&App{}).ListApps(0)
+	if got.Error != "" {
+		t.Fatalf("不該有錯：%s", got.Error)
+	}
+	if got.Source != "session" {
+		t.Fatalf("該走 portal session，實際走 %q", got.Source)
+	}
+	if len(got.Apps) != 2 || got.Apps[0].ID != "note" || got.Apps[0].Icon != "🗒️" || !got.Apps[0].HasUI {
+		t.Fatalf("清單沒有原樣接住實例的回應：%+v", got.Apps)
+	}
+	if got.Account != "我的庫" {
+		t.Fatalf("知識庫名字不對：%q", got.Account)
+	}
+}
+
+func TestListApps_FallsBackToApiKeyWithoutSession(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	// 完全沒有 session（＝剛升級上來、或從沒登入過）——九宮格照樣要看得到真資料
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test"})
+
+	got := (&App{}).ListApps(0)
+	if got.Error != "" || got.Source != "apikey" || len(got.Apps) != 2 {
+		t.Fatalf("沒有 session 時該退回 API key 並照樣列出來：%+v", got)
+	}
+}
+
+func TestListApps_ExpiredSessionIsClearedAndListStillWorks(t *testing.T) {
+	tempHome(t)
+	// 實例已經不認這張 session（f.sessionToken 與 config 裡那張不同）
+	fi := &fakeInstance{sessionToken: "sess-new", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{
+		Email: "a@b.c", APIKey: "ns-test", PortalSession: "sess-old",
+	})
+
+	got := (&App{}).ListApps(0)
+	if got.Error != "" || got.Source != "apikey" || len(got.Apps) != 2 {
+		t.Fatalf("session 過期時清單仍該看得到（退回 API key）：%+v", got)
+	}
+	// 已知無效的 token 要被丟掉，否則下一次還會再撞一次 401
+	cfg, _ := loadCfg()
+	if cfg.Accounts[0].PortalSession != "" {
+		t.Fatalf("過期的 session 沒有被清掉：%q", cfg.Accounts[0].PortalSession)
+	}
+}
+
+// 🔴「問不到」不准偽裝成「一個都沒裝」——實例 5xx 時不准悄悄退回 API key 假裝正常。
+func TestListApps_InstanceErrorIsNotDisguisedAsEmpty(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "sess-a", password: "pw", apiKey: "ns-test", listStatus: 500}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test", PortalSession: "sess-a"})
+
+	got := (&App{}).ListApps(0)
+	if got.Error == "" {
+		t.Fatalf("實例回 500 卻沒有回報錯誤：%+v", got)
+	}
+	if len(got.Apps) != 0 {
+		t.Fatalf("出錯時不該給半份清單：%+v", got.Apps)
+	}
+}
+
+func TestListApps_UnknownAccountSaysSo(t *testing.T) {
+	tempHome(t)
+	writeCfgWithAccount(t, "https://example.invalid", accountCfg{Email: "a@b.c", APIKey: "k"})
+	if got := (&App{}).ListApps(7); got.Error == "" {
+		t.Fatalf("越界的索引該回錯，不是空清單")
+	}
+}
+
+// ── 驗收條件 2：點進去能用 ───────────────────────────────────────────────
+
+func TestGetApp_ReturnsDetailWithUI(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "sess-a", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test", PortalSession: "sess-a"})
+
+	d := (&App{}).GetApp(0, "note")
+	if d.Error != "" || d.NeedsLogin {
+		t.Fatalf("不該有錯也不該要登入：%+v", d)
+	}
+	if !d.HasUI || d.UIHtml != "<div id=x>hi</div>" {
+		t.Fatalf("自帶畫面沒接住：%+v", d)
+	}
+	if len(d.Workflows) != 1 || d.Workflows[0].Name != "notes-create" {
+		t.Fatalf("工作流清單沒接住：%+v", d.Workflows)
+	}
+	if len(d.Actions) != 1 || d.Actions[0] != "notes-create" {
+		t.Fatalf("動作白名單沒接住：%+v", d.Actions)
+	}
+}
+
+// 沒有 session ⇒ 回 NeedsLogin（要長登入框），不是回一句錯誤。
+// 這是刻意的：上游的 API key 面**沒有**詳情端點（routes/apps.ts 只有 install/list/delete），
+// 所以「看詳情」在協定上就只有 portal session 那一條路。
+func TestGetApp_WithoutSessionAsksForLoginNotError(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test"})
+
+	d := (&App{}).GetApp(0, "note")
+	if !d.NeedsLogin {
+		t.Fatalf("沒有 session 時該回 NeedsLogin：%+v", d)
+	}
+	if d.Error != "" {
+		t.Fatalf("這不是錯誤，是還差一步：%q", d.Error)
+	}
+	if d.Email != "a@b.c" {
+		t.Fatalf("登入框要能預填帳號：%q", d.Email)
+	}
+}
+
+func TestPortalLogin_StoresSessionNotPassword(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test"})
+
+	if err := (&App{}).PortalLogin(0, "wrong"); err == nil {
+		t.Fatalf("密碼錯了應該要失敗")
+	}
+	if err := (&App{}).PortalLogin(0, "pw"); err != nil {
+		t.Fatalf("密碼對了卻失敗：%v", err)
+	}
+	raw, err := os.ReadFile(configPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 🔴 密碼零落地：整份 config 裡不准出現密碼字串
+	if strings.Contains(string(raw), "pw\"") || strings.Contains(string(raw), "\"password\"") {
+		t.Fatalf("密碼被寫進 config 了：%s", raw)
+	}
+	cfg, _ := loadCfg()
+	if cfg.Accounts[0].PortalSession == "" || cfg.Accounts[0].PortalSessionExp == 0 {
+		t.Fatalf("session 沒有存起來：%+v", cfg.Accounts[0])
+	}
+	// 存了 session 之後，詳情就拿得到了
+	if d := (&App{}).GetApp(0, "note"); d.NeedsLogin || d.Error != "" {
+		t.Fatalf("登入之後詳情還是拿不到：%+v", d)
+	}
+}
+
+func TestRunAppAction_HitsInstanceAndCarriesPayload(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "sess-a", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test", PortalSession: "sess-a"})
+
+	out, err := (&App{}).RunAppAction(0, "note", "notes-create", `{"text":"嗨"}`)
+	if err != nil {
+		t.Fatalf("動作失敗：%v", err)
+	}
+	if !strings.Contains(out, "blk_1") {
+		t.Fatalf("沒有把實例的結果原樣帶回來：%s", out)
+	}
+	if fi.gotAction != "notes-create" || fi.gotPayload["text"] != "嗨" {
+		t.Fatalf("payload 沒送到：%q %+v", fi.gotAction, fi.gotPayload)
+	}
+}
+
+// 白名單是**實例**裁決的（K6）——桌面端不複製一份判斷，只負責把實例的話原樣說出來。
+func TestRunAppAction_WhitelistIsDecidedByInstance(t *testing.T) {
+	tempHome(t)
+	fi := &fakeInstance{sessionToken: "sess-a", password: "pw", apiKey: "ns-test"}
+	srv := fi.server(t)
+	defer srv.Close()
+	writeCfgWithAccount(t, srv.URL, accountCfg{Email: "a@b.c", APIKey: "ns-test", PortalSession: "sess-a"})
+
+	_, err := (&App{}).RunAppAction(0, "note", "rm-rf", "")
+	if err == nil {
+		t.Fatalf("不在白名單的動作該失敗")
+	}
+	if !strings.Contains(err.Error(), "白名單") {
+		t.Fatalf("該把實例的原話帶回來，實際：%v", err)
+	}
+}
+
+// ── 純函式 ──────────────────────────────────────────────────────────────
+
+func TestParseAppList_FallsBackToIdWhenNameMissing(t *testing.T) {
+	apps := parseAppList([]byte(`{"apps":[{"id":"x","name":"","icon":"","has_ui":false,"version":"1"}]}`))
+	if len(apps) != 1 || apps[0].Name != "x" {
+		t.Fatalf("沒有名字時該退回 id：%+v", apps)
+	}
+}
+
+func TestUrlPathEscape(t *testing.T) {
+	for in, want := range map[string]string{
+		"note":   "note",
+		"a/b":    "a%2Fb",
+		"a b":    "a%20b",
+		"../etc": "..%2Fetc",
+		"筆記":     "%E7%AD%86%E8%A8%98",
+	} {
+		if got := urlPathEscape(in); got != want {
+			t.Fatalf("urlPathEscape(%q)=%q，想要 %q", in, got, want)
+		}
+	}
+}

cmd/arcrun-app/check-launcher.mjs

@@ -0,0 +1,284 @@
+// check-launcher.mjs — App 啟動器的**看得見的驗收**（inkstone/arcrun-rag#137）
+//
+// 🔴 leo 2026-08-04：「既然是 Web，你做的時候**無法檢視**？」
+//    ⇒ 這支就是那句話對 App 啟動器的兌現：真的把 frontend/dist 渲染出來、
+//      真的按下去、真的量畫面上有什麼，而不是「看程式碼覺得應該會動」。
+//
+// 與旁邊 check-render.sh 的分工：
+//   · check-render.sh  量 CIS 的像素（lockup 接合／深色模式）——只跑得動 macOS 的 Chrome
+//   · 本檔             驗 App 啟動器的**行為**（九宮格／點進去／sandbox 橋／既有頁沒壞）
+//     用 playwright 的 chromium，macOS／Linux／CI 都跑得動
+//
+// 跑法：`node check-launcher.mjs`（沒裝 playwright 就自己跳過，不擋別人的流程）
+// 產出：截圖在 /tmp/arcrun-launcher-shots/，每一條檢查印一行 ✅／❌
+//
+// ⚠️ 這支驗的是**前端這一半**（畫面、互動、sandbox 邊界）。後端那一半
+//    （真的去問實例、session／API key 兩條路、白名單由實例裁決）在 apps_test.go，
+//    那裡打的是照上游原始碼寫的假實例。**兩邊都綠才算前後端一體。**
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const dist = path.join(here, 'frontend', 'dist');
+const shots = '/tmp/arcrun-launcher-shots';
+
+// playwright 從哪裡來：本地 node_modules 優先，其次全域安裝（CI／雲端常見）。
+// CommonJS 包從 ESM import 進來時，具名匯出可能只在 default 上，兩種都接。
+async function loadChromium() {
+  const tries = ['playwright', '/opt/node22/lib/node_modules/playwright/index.js'];
+  for (const spec of tries) {
+    try {
+      const m = await import(spec);
+      const c = m.chromium || (m.default && m.default.chromium);
+      if (c) return c;
+    } catch { /* 下一個 */ }
+  }
+  return null;
+}
+const chromium = await loadChromium();
+if (!chromium) {
+  console.log('⚠️  沒有 playwright，跳過畫面驗收（npm i -D playwright && npx playwright install chromium）');
+  process.exit(0);
+}
+if (!fs.existsSync(path.join(dist, 'index.html'))) {
+  console.error('❌ 沒有 frontend/dist——先 npm --prefix frontend run build');
+  process.exit(1);
+}
+
+// ── 靜態伺服器（dist 原樣，不改任何一個 byte）──
+const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.png': 'image/png' };
+const srv = http.createServer((req, res) => {
+  const rel = decodeURIComponent(req.url.split('?')[0]);
+  const f = path.join(dist, rel === '/' ? 'index.html' : rel);
+  if (!f.startsWith(dist) || !fs.existsSync(f) || fs.statSync(f).isDirectory()) { res.writeHead(404).end(); return; }
+  res.writeHead(200, { 'Content-Type': MIME[path.extname(f)] || 'application/octet-stream' });
+  fs.createReadStream(f).pipe(res);
+});
+await new Promise((r) => srv.listen(0, '127.0.0.1', r));
+const origin = `http://127.0.0.1:${srv.address().port}`;
+
+// ── 假後端：形狀逐欄對齊 apps.go 的 UIAppList／UIAppDetail ──
+//
+// 🔴 這裡**不是**在假裝 Go 那半會怎麼運作（那由 apps_test.go 打真 HTTP 驗）。
+//    這裡只回「Go 已經回過來的東西長什麼樣」，讓畫面有東西可畫。
+const mock = (scenario) => `
+const scenario = ${JSON.stringify(scenario)};
+window.__scenario = scenario;
+window.__calls = [];
+const APPS = [
+  { id: 'note',   name: '筆記', icon: '🗒️', hasUi: true,  version: '0.1.0' },
+  { id: 'weekly', name: '週報', icon: '📊', hasUi: false, version: '0.2.0' },
+];
+const DETAIL = {
+  note: { id:'note', name:'筆記', icon:'🗒️', version:'0.1.0', hasUi:true,
+    uiHtml: '<h3 id="t">河道</h3><button id="go">寫一則</button><pre id="out"></pre>' +
+      '<scr'+'ipt>document.getElementById("go").onclick=async()=>{' +
+      'const r=await window.arcrunApp.action("notes-create",{text:"嗨"});' +
+      'document.getElementById("out").textContent=JSON.stringify(r);};' +
+      'document.title="app-ui-loaded";' +
+      'window.__peek=(()=>{try{return typeof parent.go}catch(e){return "BLOCKED:"+e.name}})();' +
+      '</scr'+'ipt>',
+    workflows:[{name:'notes-create',description:'寫入一則筆記'}], actions:['notes-create'] },
+  weekly: { id:'weekly', name:'週報', icon:'📊', version:'0.2.0', hasUi:false, uiHtml:'',
+    workflows:[{name:'weekly-report',description:'每週一產週報'}], actions:['weekly-report'] },
+};
+const ACCOUNTS = [{
+  name:'我的知識庫', host:'arcrun-cypher-executor.demo.workers.dev', folders:[{path:'/Users/leo/Notes',accIdx:0}],
+  cloudVerKnown:true, cloudVerStale:false, cloudVerMine:'1.4.42', email:'leo@example.com',
+}];
+window.go = { main: { App: {
+  GetState: async () => ({
+    version:'v0.18.34', statusBig:'看守中 · 資料夾有變動就會自動整理', statusSub:'上次檢查 10:21',
+    syncing:false, engine:'workers-ai', geminiKey:'',
+    accounts: scenario === 'noaccount' ? [] : ACCOUNTS,
+    steps:[{title:'看守資料夾',meta:'有變動就自動開始',state:'done'},
+           {title:'發現變化',meta:'上次 10:20',state:'done'},
+           {title:'用 AI 整理成知識卡',state:'done'},
+           {title:'上傳到你的知識庫',meta:'上次 3 份',state:'done'}],
+    skipped:null, engineTrouble:false, logFolder:'/Users/leo/.arcrun-rag',
+    progress:{total:120,done:117,pending:3,cantSync:0,groups:[]}, quota:null,
+  }),
+  ListApps: async (i) => {
+    window.__calls.push(['ListApps', i]);
+    if (scenario === 'listerror') return { accIdx:i, account:'我的知識庫', apps:[], error:'連不上這個知識庫——請確認網路正常' };
+    if (scenario === 'noapps')    return { accIdx:i, account:'我的知識庫', apps:[], error:'', source:'session' };
+    return { accIdx:i, account:'我的知識庫', host:'demo', apps:APPS, error:'', source:'session' };
+  },
+  GetApp: async (i, id) => {
+    window.__calls.push(['GetApp', i, id]);
+    if (scenario === 'needlogin') return { id, name:'筆記', icon:'🗒️', needsLogin:true, email:'leo@example.com', workflows:[], actions:[] };
+    return DETAIL[id];
+  },
+  RunAppAction: async (i, id, action, payload) => {
+    window.__calls.push(['RunAppAction', i, id, action, payload]);
+    if (action !== 'notes-create' && action !== 'weekly-report') throw new Error('這個動作不在這個 App 的白名單內');
+    return JSON.stringify({ ok:true, result:{ id:'blk_1', echo: JSON.parse(payload||'{}') } });
+  },
+  PortalLogin: async (i, pw) => { window.__calls.push(['PortalLogin', i]); if (pw !== 'pw') throw new Error('email 或密碼錯誤'); },
+  SyncNow: async () => {}, PickFolder: async () => '', AddFolder: async () => {}, RemoveFolder: async () => {},
+  SetAI: async () => {}, OpenURL: () => { window.__calls.push(['OpenURL']); }, OpenLogFolder: async () => {},
+  Connect: async () => {}, CheckUpdate: async () => ({ latest:'v0.18.34' }),
+  DownloadUpdate: async () => ({}), ApplyUpdate: async () => {}, ExportDiagnostics: async () => '',
+}}};
+`;
+
+let fail = 0;
+const ok = (m) => console.log('  ✅ ' + m);
+const ng = (m) => { console.log('  ❌ ' + m); fail = 1; };
+const check = (cond, m) => (cond ? ok(m) : ng(m));
+
+fs.mkdirSync(shots, { recursive: true });
+const browser = await chromium.launch();
+
+async function open(scenario, theme = 'light') {
+  const ctx = await browser.newContext({ viewport: { width: 1100, height: 760 } });
+  const page = await ctx.newPage();
+  await page.addInitScript(`try{localStorage.setItem('arcrun_app_theme','${theme}')}catch(e){}`);
+  await page.addInitScript(mock(scenario));
+  const errs = [];
+  page.on('pageerror', (e) => errs.push(String(e)));
+  await page.goto(origin);
+  await page.waitForTimeout(400);
+  return { ctx, page, errs };
+}
+
+console.log('━━━ App 啟動器畫面驗收 ━━━');
+
+// ① 打開就是九宮格，磁磚是真資料（不是寫死的）
+{
+  const { ctx, page, errs } = await open('ok');
+  await page.waitForSelector('.appgrid', { timeout: 5000 }).catch(() => {});
+  const tiles = await page.$$eval('.appcell .nm', (n) => n.map((e) => e.textContent.trim()));
+  check(errs.length === 0, `啟動器沒有 JS 例外${errs.length ? '（' + errs[0] + '）' : ''}`);
+  check(await page.$('.appgrid') !== null, '打開就看到九宮格');
+  check(tiles.join('|') === '筆記|週報|加裝 App', `磁磚＝實例回的那兩個 App ＋ 加裝（實際：${tiles.join('|')}）`);
+  check((await page.$eval('.apphead .s', (e) => e.textContent)).includes('2 個 App 已安裝'), '頁首說得出裝了幾個');
+  const calls = await page.evaluate(() => window.__calls.filter((c) => c[0] === 'ListApps').length);
+  check(calls === 1, `只問了實例一次，不是每秒輪詢（實際 ${calls} 次）`);
+  await page.waitForTimeout(2500);
+  const calls2 = await page.evaluate(() => window.__calls.filter((c) => c[0] === 'ListApps').length);
+  check(calls2 === 1, `2.5 秒後仍然只問過一次（實際 ${calls2} 次）— 沒有掛在每秒的 tick 上`);
+  await page.screenshot({ path: `${shots}/01-launcher-light.png` });
+  await ctx.close();
+}
+
+// ①b 深色模式也要對
+{
+  const { ctx, page } = await open('ok', 'dark');
+  await page.waitForSelector('.appgrid');
+  await page.screenshot({ path: `${shots}/02-launcher-dark.png` });
+  check(await page.getAttribute('html', 'data-theme') === 'dark', '深色模式渲染得出來');
+  await ctx.close();
+}
+
+// ② 點一個「有自帶畫面」的 App → 進 sandbox iframe，且橋真的通
+{
+  const { ctx, page, errs } = await open('ok');
+  await page.waitForSelector('.appgrid');
+  await page.click('[data-appopen="note"]');
+  await page.waitForSelector('#appFrame', { timeout: 5000 });
+  const frame = await (await page.$('#appFrame')).contentFrame();
+  await frame.waitForSelector('#go', { timeout: 5000 });
+  check(true, '點「筆記」進得去，App 自帶畫面渲染出來');
+  // 🔴 sandbox 邊界：iframe 裡的 script 不准碰得到 parent 的 window.go
+  //    （那上面掛著 RemoveFolder(takedown)／SetAI／Connect）
+  const peek = await frame.evaluate(() => window.__peek);
+  check(typeof peek === 'string' && peek.startsWith('BLOCKED'), `iframe 碰不到 parent 的 window.go（實際：${peek}）`);
+  // 橋：iframe 按鈕 → postMessage → go.RunAppAction → 回到 iframe
+  await frame.click('#go');
+  await frame.waitForFunction(() => document.getElementById('out').textContent.length > 0, null, { timeout: 5000 });
+  const out = await frame.$eval('#out', (e) => e.textContent);
+  check(out.includes('blk_1'), `sandbox 橋走得通，結果回得到 App 畫面（實際：${out.slice(0, 80)}）`);
+  const call = await page.evaluate(() => window.__calls.find((c) => c[0] === 'RunAppAction'));
+  check(call && call[3] === 'notes-create' && JSON.parse(call[4]).text === '嗨', 'payload 原樣送到後端');
+  check(errs.length === 0, `App 頁沒有 JS 例外${errs.length ? '（' + errs[0] + '）' : ''}`);
+  await page.screenshot({ path: `${shots}/03-app-ui.png` });
+  await ctx.close();
+}
+
+// ②b 沒有自帶畫面的 App → 工作流清單 ＋「現在執行」
+{
+  const { ctx, page } = await open('ok');
+  await page.waitForSelector('.appgrid');
+  await page.click('[data-appopen="weekly"]');
+  await page.waitForSelector('.wfitem', { timeout: 5000 });
+  check(await page.$eval('.wfitem .nm', (e) => e.textContent) === 'weekly-report', '沒有畫面的 App 列出它的工作流');
+  await page.click('[data-apprun="weekly-report"]');
+  await page.waitForFunction(() => document.querySelector('.wfitem .out').textContent.includes('完成'), null, { timeout: 5000 });
+  check(true, '「現在執行」按得動，結果顯示在那一列底下');
+  await page.screenshot({ path: `${shots}/04-app-workflows.png` });
+  await ctx.close();
+}
+
+// ③ 三種「不是正常」的狀態都要說人話，且分得出來
+{
+  const { ctx, page } = await open('noapps');
+  await page.waitForSelector('.appgrid');
+  const txt = await page.textContent('#page');
+  check(txt.includes('這個知識庫還沒有 App'), '一個都沒裝 → 說「還沒有 App」並教怎麼裝');
+  check(!txt.includes('連不上'), '一個都沒裝時不准講成連線失敗');
+  await page.screenshot({ path: `${shots}/05-empty.png` });
+  await ctx.close();
+}
+{
+  const { ctx, page } = await open('listerror');
+  await page.waitForTimeout(300);
+  const txt = await page.textContent('#page');
+  check(txt.includes('暫時看不到') && txt.includes('連不上'), '問不到 → 說「問不到」並帶實例的原話');
+  check(!txt.includes('還沒有 App'), '問不到時不准講成「一個都沒裝」');
+  await page.screenshot({ path: `${shots}/06-error.png` });
+  await ctx.close();
+}
+{
+  const { ctx, page } = await open('noaccount');
+  await page.waitForTimeout(300);
+  const txt = await page.textContent('#page');
+  check(txt.includes('歡迎使用 Arcrun') || txt.includes('還沒有連上知識庫'), '沒連任何實例 → 說人話（連線精靈），不是空白');
+  await page.screenshot({ path: `${shots}/07-noaccount.png` });
+  await ctx.close();
+}
+{
+  const { ctx, page } = await open('needlogin');
+  await page.waitForSelector('.appgrid');
+  await page.click('[data-appopen="note"]');
+  await page.waitForSelector('#apPw', { timeout: 5000 });
+  check(await page.inputValue('#apEmail') === 'leo@example.com', 'session 過期 → 長登入框並預填帳號');
+  await page.screenshot({ path: `${shots}/08-needlogin.png` });
+  await ctx.close();
+}
+
+// ④ 驗收條件 3：現有功能一項都沒少
+{
+  const { ctx, page, errs } = await open('ok');
+  await page.waitForSelector('.appgrid');
+  const navs = await page.$$eval('#side .nav .nm', (n) => n.map((e) => e.textContent.trim()));
+  for (const want of ['App 界面', '首頁', '我的知識庫', 'AI 設定', '版本與更新']) {
+    check(navs.includes(want), `側欄仍有「${want}」`);
+  }
+  const pages = [
+    ['home', '現在的狀態'],
+    ['lib:0', '開啟知識庫網頁'],
+    ['ai', '用哪個 AI 幫你整理文件'],
+    ['update', '版本與更新'],
+  ];
+  for (const [p, marker] of pages) {
+    await page.click(`#side .nav[data-p="${p}"]`);
+    await page.waitForTimeout(200);
+    const t = await page.textContent('#page');
+    check(t.includes(marker), `「${p}」頁還在（找得到「${marker}」）`);
+  }
+  // 全站頁首的同步狀態與「立刻同步」在每一頁都看得到（首頁換走了它們也沒消失）
+  check((await page.textContent('#statusBig')).includes('看守中'), '同步狀態在全站頁首，換頁不會不見');
+  check(await page.$('#btnSync') !== null, '「立刻同步」按鈕還在');
+  check(errs.length === 0, `逛完全部頁面沒有 JS 例外${errs.length ? '（' + errs[0] + '）' : ''}`);
+  await page.screenshot({ path: `${shots}/09-existing-update.png` });
+  await ctx.close();
+}
+
+await browser.close();
+srv.close();
+console.log(`\n截圖：${shots}`);
+console.log(fail ? '\n❌ 畫面驗收未過' : '\n✅ 畫面驗收全過');
+process.exit(fail);

cmd/arcrun-app/check-remove-cleanup.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# check-remove-cleanup.sh — 驗**使用者真的會走的那條路**：
+# 從各庫頁按「移除」→ 對話框 → 勾「順便清掉」→ 看到清單 → 按確定（arcrun-rag#138）。
+#
+# 🔴 為什麼要這一支：Go 那邊的迴歸網只證明「函式做對事」，證明不了
+#    「按鈕存在、清單真的攤出來、第四個參數真的傳下去」。#138 的驗收條件裡
+#    「使用者要能在動手前看到將要刪掉哪些東西」**只有前端驗得到**。
+#    （同 check-render.sh 的理由：改完 UI 不准拿沒看過的畫面交件。）
+#
+# 做法沿用 check-render.sh：把 dist 複製到暫存、插一支 mock.js 假扮 window.go，
+# 再用 headless Chrome 真的載入、真的點下去，最後 --dump-dom 讀結果。
+set -uo pipefail
+cd "$(dirname "$0")"
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+[ -x "$CHROME" ] || { echo "❌ 找不到 Chrome，跳過"; exit 0; }
+[ -d frontend/dist ] || { echo "❌ 沒有 frontend/dist——先 (cd frontend && npm run build)"; exit 1; }
+
+W=$(mktemp -d)
+SRV_PID=""
+cleanup() { rm -rf "$W"; [ -n "$SRV_PID" ] && kill "$SRV_PID" 2>/dev/null; }
+trap cleanup EXIT
+lsof -ti tcp:8798 2>/dev/null | xargs -r kill 2>/dev/null; sleep 0.3
+cp -R frontend/dist/* "$W/"
+
+cat > "$W/mock.js" <<'JS'
+// 假的 window.go：一個知識庫、一個看守中的資料夾，PlanFolderCleanup 回一份
+// 形狀與 collector.CleanupPlan 完全一致的清單（含「留著不動」那一半）。
+window.__calls = [];
+window.go = { main: { App: {
+  GetState: async () => ({
+    version: 'v0', statusBig: '看守中', statusSub: '', syncing: false,
+    engine: 'workers-ai', geminiKey: '', extractedOK: 0,
+    accounts: [{ name: '測試庫', host: 'arcrun-cypher-executor.example.workers.dev',
+      folders: [{ path: '/kb/pms', accIdx: 0, retiring: false }] }],
+  }),
+  PlanFolderCleanup: async (acc, path) => {
+    window.__calls.push(['PlanFolderCleanup', acc, path]);
+    return {
+      root: path, files: 52, bytes: 1234,
+      remove: [
+        { rel: '.arcrun-rag', is_dir: true, kind: 'workspace', evidence: '依據甲', files: 1, bytes: 10 },
+        { rel: '.wiki', is_dir: true, kind: 'wiki-dir', evidence: '依據乙', files: 8, bytes: 100 },
+        { rel: 'docs/.wiki', is_dir: true, kind: 'wiki-dir', evidence: '依據乙', files: 43, bytes: 900 },
+      ],
+      keep: [{ rel: 'pms_v1_legacy', reason: '這個資料夾也還在同步清單裡' }],
+    };
+  },
+  RemoveFolder: async (acc, path, takedown, cleanupLocal) => {
+    window.__calls.push(['RemoveFolder', acc, path, takedown, cleanupLocal]);
+  },
+  SyncNow: async () => {}, PickFolder: async () => '', AddFolder: async () => {},
+  SetAI: async () => {}, OpenURL: () => {}, Connect: async () => {},
+  CheckUpdate: async () => ({}), OpenLogFolder: () => {}, LogFolderPath: () => '',
+  ListApps: async () => ({ apps: [] }),
+} } };
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const say = (k, v) => {
+  const d = document.createElement('div');
+  d.setAttribute('data-check', k); d.textContent = String(v);
+  document.body.appendChild(d);
+};
+
+addEventListener('DOMContentLoaded', async () => {
+  await sleep(600);                       // 等 main.js 拿到 state、畫完側欄
+  // 走到各庫頁（使用者點側邊欄那個庫）
+  const nav = [...document.querySelectorAll('.nav')].find((b) => (b.dataset.p || '').startsWith('lib:'));
+  if (nav) nav.click(); else location.hash = '';
+  await sleep(300);
+
+  const rm = document.querySelector('[data-rm]');
+  say('有移除按鈕', !!rm);
+  if (!rm) { say('done', 1); return; }
+  rm.click();
+  await sleep(200);
+
+  const box = document.getElementById('rmClean');
+  say('有清理勾選框', !!box);
+  say('預設不勾', box ? box.checked === false : false);
+  if (!box) { say('done', 1); return; }
+
+  box.checked = true; box.dispatchEvent(new Event('change'));
+  await sleep(400);
+  const planTxt = (document.getElementById('rmPlan') || {}).textContent || '';
+  say('清單有列出要刪的路徑', planTxt.includes('.arcrun-rag') && planTxt.includes('docs/.wiki'));
+  say('清單有列出留著不動的', planTxt.includes('pms_v1_legacy'));
+  say('清單有講幾個檔', planTxt.includes('52'));
+
+  document.getElementById('c2').click();
+  await sleep(400);
+  const call = window.__calls.find((c) => c[0] === 'RemoveFolder');
+  say('有呼叫 RemoveFolder', !!call);
+  say('第四個參數帶了 true', call ? call[4] === true : false);
+  say('路徑正確', call ? call[2] === '/kb/pms' : false);
+  say('done', 1);
+});
+JS
+
+python3 - "$W" <<'PY'
+import sys
+p = sys.argv[1] + '/index.html'
+s = open(p, encoding='utf-8').read()
+s = s.replace('src="/assets/', 'src="./assets/').replace('href="/assets/', 'href="./assets/')
+s = s.replace('<script type="module"', '<script src="./mock.js"></script>\n<script type="module"', 1)
+open(p, 'w', encoding='utf-8').write(s)
+PY
+
+(cd "$W" && python3 -m http.server 8798 >/dev/null 2>&1) &
+SRV_PID=$!
+sleep 2
+"$CHROME" --headless --disable-gpu --virtual-time-budget=8000 --dump-dom \
+  "http://localhost:8798/index.html" 2>/dev/null > "$W/dom.html"
+
+python3 - "$W/dom.html" <<'PY'
+import re, sys
+dom = open(sys.argv[1], encoding='utf-8').read()
+got = dict(re.findall(r'<div data-check="([^"]+)">([^<]*)</div>', dom))
+if not got:
+    print("  ❌ 頁面沒跑到底（一個檢查點都沒寫出來）——看 dom.html"); sys.exit(1)
+bad = 0
+for k, v in got.items():
+    if k == 'done':
+        continue
+    ok = v == 'true'
+    print(f"  {'✅' if ok else '❌'} {k}：{v}")
+    bad += 0 if ok else 1
+if 'done' not in got:
+    print("  ❌ 驅動腳本沒跑完"); sys.exit(1)
+sys.exit(1 if bad else 0)
+PY

cmd/arcrun-app/connect.go

@@ -104,6 +104,10 @@ func (a *App) Connect(portalURL, email, password string) error {
 			cfg.Accounts[i].APIKey = r.Config.Namespace
 			cfg.Accounts[i].Email = r.Config.Email
 			cfg.Accounts[i].InstanceName = r.Config.InstanceName
+			// arcrun-rag#137：密碼**此刻**還在手上，順手換一張 portal session，
+			// 之後 App 啟動器要看詳情／按動作就不必再問一次密碼。
+			// 換不到不算連線失敗（同步這條主線用不到它），見 apps.go。
+			tryStoreSessionFromLogin(cfg, i, r.Config.Email, password)
 			return saveCfg(cfg)
 		}
 	}
@@ -117,6 +121,8 @@ func (a *App) Connect(portalURL, email, password string) error {
 		Namespace:    r.Config.Namespace,
 		APIKey:       r.Config.Namespace,
 	})
+	// arcrun-rag#137：同上，順手換一張 portal session 給 App 啟動器用。
+	tryStoreSessionFromLogin(cfg, len(cfg.Accounts)-1, r.Config.Email, password)
 	if wasFirstEver {
 		// leo 2026-08-08：全新安裝自動裝一個「可刪除的預設庫」，讓使用者不必
 		// 自己選資料夾也能立刻看到「丟檔 → 知識卡 → 搜得到」整條路（見 default_library.go）。

cmd/arcrun-app/frontend/src/main.js

@@ -27,10 +27,28 @@ $('themeBtn').onclick = () =>
   applyTheme(document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');
 
 let state = null;
-let page = 'home';        // 'home' | 'ai' | 'update' | 'lib:<idx>'
+// page：'apps'（App 啟動器）| 'app:<accIdx>:<id>' | 'home' | 'ai' | 'update' | 'lib:<idx>'
+//
+// 🔴 arcrun-rag#137：預設落在 App 啟動器，不是首頁——leo 2026-08-24 的原話是
+//    「**打開桌面小幫手就看到**跟 Portal 同一套的 App 啟動器」。
+//    同步狀態沒有因此消失：它在**全站頁首**（statusBig/statusSub＋「立刻同步」），
+//    每一頁都看得到；首頁那些卡片仍在側欄的「首頁」裡，一鍵可達。
+//    還沒連任何知識庫時 render() 會把它改回 'home'（那裡才是連線精靈）。
+let page = 'apps';
 let updateInfo = null;
 let obStep = 1;           // 首次啟動精靈目前在第幾步（issue #23，見 onboarding()）
 
+// ── App 啟動器的暫存（arcrun-rag#137）──
+//
+// 🔴 這是**畫面暫存，不是本機清單**：只活在這個視窗的記憶體裡，關掉就沒了，
+//    永遠不寫檔。上游 inkstone/Arcrun#82 已定「安裝態只有一份真相源」＝實例上那一份，
+//    桌面端不准另存一份（本票紅線）。存在這裡只是為了不要每次換頁都重打一次網路。
+let appsAccIdx = 0;       // 啟動器現在在看哪一個知識庫
+let appsCache = {};       // accIdx -> ListApps() 的回傳（undefined＝還沒問，null＝正在問）
+let appDetail = null;     // 目前打開的那個 App 的詳情（GetApp() 的回傳）
+let appDetailKey = '';    // 'accIdx:id'，避免慢回應蓋掉已經換過去的另一個 App
+let appFrameBridge = null; // App 自帶畫面那個 iframe 的 postMessage 監聽器（換頁時要拆掉）
+
 // ── 覆蓋層（只給必須打斷的確認）──
 function openSheet(html, wire) { $('sheet').innerHTML = html; $('overlay').classList.add('on'); if (wire) wire(); }
 function closeSheet() { $('overlay').classList.remove('on'); }
@@ -50,7 +68,21 @@ document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeSheet
 // 之後若那個提案 confirm，是在這層之上疊總覽 pill，不是重做這裡。
 function renderNav() {
   const accs = (state && state.accounts) || [];
+  // arcrun-rag#137：「App」這一段在最上面，且**只有連了知識庫才出現**——
+  // 沒有實例就沒有 App，把一個必定空的入口擺在第一項只會讓人以為壞了。
+  // 目前打開的那個 App 以子項的形式掛在「App 界面」下面（同 Portal 的做法：
+  // 已安裝的 App 是側欄的一格），這樣使用者知道自己在哪、也回得去。
+  const appNav = !accs.length ? '' : `
+    <div class="sec">App</div>
+    <div class="nav" data-p="apps"><span class="ic">▦</span><span class="nm">App 界面</span></div>
+    ${page.startsWith('app:') && appDetail && !appDetail.error ? `
+      <div class="nav" data-p="${esc(page)}" style="padding-left:44px">
+        <span class="ic">${esc(appDetail.icon || '▢')}</span>
+        <span class="nm">${esc(appDetail.name || appDetail.id)}</span>
+      </div>` : ''}
+    <div class="sec">小幫手</div>`;
   $('nav').innerHTML = `
+    ${appNav}
     <div class="nav" data-p="home"><span class="ic">◫</span><span class="nm">首頁</span></div>
     ${accs.length ? `<div class="sec">知識庫</div>` : ''}
     ${accs.map((a, i) => `
@@ -64,7 +96,17 @@ function renderNav() {
     <div class="nav" data-p="update"><span class="ic">↧</span><span class="nm">版本與更新</span></div>`;
   $('nav').querySelectorAll('.nav').forEach((el) => {
     el.classList.toggle('on', el.dataset.p === page);
-    el.onclick = () => { page = el.dataset.p; renderNav(); renderPage(); };
+    el.onclick = () => {
+      const p = el.dataset.p;
+      if (p === page) return;
+      // 離開 App 頁時把 iframe 的橋拆掉（見 goToApp 同一段理由）。
+      if (page.startsWith('app:') && appFrameBridge) {
+        window.removeEventListener('message', appFrameBridge); appFrameBridge = null;
+      }
+      page = p;
+      renderNav(); renderPage();
+      if (p === 'apps') loadApps(appsAccIdx);
+    };
   });
 }
 
@@ -278,9 +320,10 @@ function pageLib(s, idx) {
       ${f.retireError ? `<div class="d folder-note">${esc(f.retireError)}</div>` : ''}` : `
       <div class="folder">
         <span class="path" title="${esc(f.path)}">${esc(f.path)}</span>
-        <span class="tag">自動同步中</span>
+        <span class="tag">${f.resyncNote ? '補送中' : '自動同步中'}</span>
         <button class="ghost" data-rm="${esc(f.path)}" data-acc="${f.accIdx}">移除</button>
-      </div>`).join('')
+      </div>
+      ${f.resyncNote ? `<div class="d folder-note">${esc(f.resyncNote)}</div>` : ''}`).join('')
       || `<div class="empty"><div class="t">這個知識庫還沒有資料夾</div>
            <div class="d">按右上的「加入資料夾」，選一個要自動整理的資料夾。</div></div>`}`;
 }
@@ -411,10 +454,260 @@ function onboarding() {
     </div>`;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// App 啟動器（arcrun-rag#137）
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// leo 2026-08-24：「所有的 App 需要有一個類似 Android/iOS 的九宮格啟動界面，
+// 每個 App 有一個 icon，**這會運行在 portal 及 daemon**。」
+//
+// 🔴 清單一律問實例，桌面端沒有任何寫死或存檔的 App 名單（本票紅線；
+//    上游 inkstone/Arcrun#82「安裝態只有一份真相源」）。後端兩條取得路徑
+//    與為什麼是兩條，全寫在 collector/cmd/arcrun-app/apps.go 的檔頭。
+//
+// 🔴 **不掛在每秒的 tick 上**：只有「打開啟動器」「按重新整理」「切知識庫」
+//    這三個使用者動作會真的去問實例一次。把它塞進 tick 等於自造輪詢器。
+
+// loadApps 去問某個知識庫裝了哪些 App；問完只在「使用者還停在啟動器」時重畫。
+async function loadApps(accIdx, force) {
+  if (!force && appsCache[accIdx] !== undefined) return;
+  appsCache[accIdx] = null;                      // null＝問中（畫面顯示「查詢中」）
+  if (page === 'apps') renderPage();
+  let res;
+  try {
+    res = await go.ListApps(accIdx);
+  } catch (ex) {
+    res = { accIdx, apps: [], error: String(ex) };
+  }
+  appsCache[accIdx] = res;
+  if (page === 'apps') renderPage();
+}
+
+function pageApps(s) {
+  const accs = s.accounts || [];
+  if (!accs.length) {
+    // 「沒連任何實例時要說人話」（驗收條件 1）——不是空白，也不是壞掉的樣子。
+    return `<div class="empty">
+      <div class="t">還沒有連上知識庫</div>
+      <div class="d">App 住在你的知識庫上，連上之後這裡就會列出它裝了哪些 App。</div>
+      <button class="primary" id="apConnect">連上知識庫</button>
+    </div>`;
+  }
+  if (appsAccIdx >= accs.length) appsAccIdx = 0;
+  const acc = accs[appsAccIdx];
+  const r = appsCache[appsAccIdx];
+
+  // 知識庫切換器：只有一個庫時不畫（一顆永遠只能按自己的按鈕是純噪音）。
+  const switcher = accs.length > 1 ? `
+    <div class="appswitch">
+      ${accs.map((a, i) => `<span class="chip ${i === appsAccIdx ? 'on' : ''}" data-appacc="${i}">${esc(a.name)}</span>`).join('')}
+    </div>` : '';
+
+  let sub = '查詢中…';
+  let body = `<div class="card"><div class="d">正在問「${esc(acc.name)}」裝了哪些 App…</div></div>`;
+
+  if (r) {
+    if (r.error) {
+      // 🔴 「問不到」與「一個都沒裝」是兩件事，畫面上必須分得出來
+      //    （使用者該做的事完全相反：一個是修連線，一個是去裝 App）。
+      sub = '這次沒問到';
+      body = `<div class="card">
+        <h3>暫時看不到這個知識庫的 App</h3>
+        <div class="d">${esc(r.error)}</div>
+        <div class="acts"><button id="apRetry">再試一次</button></div>
+      </div>`;
+    } else {
+      const apps = r.apps || [];
+      sub = `${apps.length} 個 App 已安裝`;
+      body = `<div class="appgrid">
+        ${apps.map((a) => `
+          <div class="appcell">
+            <div class="apptile" data-appopen="${esc(a.id)}" title="${esc(a.name)}${a.version ? ' · v' + esc(a.version) : ''}">${esc(a.icon || '▢')}</div>
+            <div class="nm" title="${esc(a.name)}">${esc(a.name)}</div>
+          </div>`).join('')}
+        <div class="appcell">
+          <div class="apptile add" id="apAdd" title="怎麼加裝 App">＋</div>
+          <div class="nm dim">加裝 App</div>
+        </div>
+      </div>
+      ${apps.length ? '' : `<div class="card" style="margin-top:26px">
+        <h3>這個知識庫還沒有 App</h3>
+        <div class="d">App 是裝在知識庫上的：跟你的 AI 說一句「幫我裝一個 X」，
+        或用 <b>acr</b> 推一份 App 宣告上去。裝好之後回到這裡按「重新整理」就會出現。</div>
+      </div>`}`;
+    }
+  }
+
+  return `
+    <div class="apphead">
+      <div class="g">
+        <div class="t">App 界面</div>
+        <div class="s">${esc(acc.name)} · ${esc(sub)}</div>
+      </div>
+      <button id="apRefresh">重新整理</button>
+    </div>
+    ${switcher}
+    ${body}`;
+}
+
+// ── 單一 App 的頁 ─────────────────────────────────────────────────────────
+
+async function loadAppDetail(accIdx, id) {
+  const key = accIdx + ':' + id;
+  appDetailKey = key;
+  appDetail = null;
+  renderPage();
+  let d;
+  try {
+    d = await go.GetApp(accIdx, id);
+  } catch (ex) {
+    d = { id, error: String(ex) };
+  }
+  if (appDetailKey !== key) return;   // 使用者已經換去別的 App 了，這份回應作廢
+  appDetail = d;
+  renderNav();                        // 側欄的 App 子項要顯示名字與 icon
+  renderPage();
+}
+
+function pageApp(accIdx, id) {
+  const d = appDetail;
+  const head = (ico, nm, ver) => `
+    <div class="head">
+      <span class="ico">${esc(ico || '▢')}</span>
+      <span class="nm">${esc(nm || id)}</span>
+      ${ver ? `<span class="vr">v${esc(ver)}</span>` : ''}
+      <span class="sp"></span>
+      <button data-appback="1">‹ 回 App 界面</button>
+    </div>`;
+
+  if (!d) return `<div class="appview">${head('', id, '')}<div class="card"><div class="d">載入中…</div></div></div>`;
+
+  if (d.needsLogin) {
+    // session 過期／這台機器還沒換過 session。不是錯誤，是「還差一步」。
+    return `<div class="appview">${head(d.icon, d.name, d.version)}
+      <div class="card">
+        <h3>請先登入這個知識庫</h3>
+        <div class="d">要打開 App 的畫面、或執行它的動作，需要你在這個知識庫的帳號登入一次
+        （之後這台電腦會記住一段時間，同步不受影響）。</div>
+        <div class="field"><div class="lb">帳號</div>
+          <input type="text" id="apEmail" value="${esc(d.email || '')}" disabled/></div>
+        <div class="field"><div class="lb">密碼</div><input type="password" id="apPw"/></div>
+        <div class="err" id="apErr" style="display:none"></div>
+        <div class="acts"><button class="primary" id="apLogin">登入</button></div>
+      </div></div>`;
+  }
+
+  if (d.error) {
+    return `<div class="appview">${head(d.icon, d.name, d.version)}
+      <div class="card">
+        <h3>打不開這個 App</h3>
+        <div class="d">${esc(d.error)}</div>
+        <div class="acts"><button id="apReload">再試一次</button></div>
+      </div></div>`;
+  }
+
+  if (d.hasUi && d.uiHtml) {
+    // 自帶畫面 ⇒ 掛進 sandbox iframe（mountAppUI 會在 wire() 之後填內容）。
+    return `<div class="appview">${head(d.icon, d.name, d.version)}
+      <iframe class="appframe" id="appFrame" sandbox="allow-scripts"></iframe></div>`;
+  }
+
+  // 沒有自帶畫面 ⇒ 列出工作流，一條一顆「現在執行」
+  //（與 Portal 的系統預設畫面同一套，不另立第二種呈現）。
+  const wfs = d.workflows || [];
+  if (!wfs.length) {
+    return `<div class="appview">${head(d.icon, d.name, d.version)}
+      <div class="card"><h3>這個 App 沒有可以按的東西</h3>
+      <div class="d">它既沒有自己的畫面，也沒有登記任何工作流。</div></div></div>`;
+  }
+  return `<div class="appview">${head(d.icon, d.name, d.version)}
+    ${wfs.map((w) => `
+      <div class="wfitem" data-wf="${esc(w.name)}">
+        <div class="top">
+          <span class="nm">${esc(w.name)}</span>
+          <button data-apprun="${esc(w.name)}">現在執行</button>
+        </div>
+        ${w.description ? `<div class="d">${esc(w.description)}</div>` : ''}
+        <div class="out"></div>
+      </div>`).join('')}`;
+}
+
+// mountAppUI 把 App 自帶的 HTML 放進 **sandbox iframe**。
+//
+// 🔴 為什麼一定要 iframe（這是桌面端與 Portal 的關鍵差異，不是潔癖）：
+//    Portal 是網頁，把 App 的 HTML 直接 innerHTML 進去，那段 script 最多拿到
+//    同一頁的 fetch 與 session token。**桌面這半不一樣**——這裡的 window 上掛著
+//    `window.go.main.App`：`Connect`／`SetAI`／`RemoveFolder(…, takedown=true, cleanupLocal=true)`
+//    全都在上面。直接 innerHTML ＝ 任何一個 App 的作者都能刪掉使用者雲端的知識
+//    ——#138 之後**連他硬碟上的整理稿也刪得掉**，這道窄門只會越來越重要。
+//    ⇒ `sandbox="allow-scripts"`（**不給** allow-same-origin ⇒ 不同源，
+//      碰不到 parent 的任何東西），只留一條 postMessage 的窄門。
+//
+// 🔴 窄門的形狀刻意與 Portal 一致：App 作者一樣只認得
+//    `window.arcrunApp.action(action, payload)`，回一個 `{ok,status,d}`——
+//    這樣同一個 App 的畫面在 Portal 與桌面上都跑得起來，作者不必寫兩份。
+function mountAppUI(accIdx, d) {
+  const f = $('appFrame');
+  if (!f) return;
+  const bridge = `
+<script>
+(function () {
+  var seq = 0, pending = {};
+  window.addEventListener('message', function (e) {
+    var m = e.data;
+    if (!m || m.__arcrun !== 'result') return;
+    var p = pending[m.id]; if (!p) return; delete pending[m.id];
+    p(m.payload);
+  });
+  window.arcrunApp = {
+    action: function (action, payload) {
+      return new Promise(function (resolve) {
+        var id = ++seq; pending[id] = resolve;
+        parent.postMessage({ __arcrun: 'action', id: id, action: action, payload: payload || {} }, '*');
+      });
+    }
+  };
+})();
+<\/script>`;
+  // 讓 App 的畫面跟本體同一套底色／字體（它是 Arcrun 的一部分，不是外站）。
+  const skin = `<style>
+    :root{color-scheme:${document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'}}
+    html,body{margin:0;padding:16px;background:transparent;
+      color:${getComputedStyle(document.documentElement).getPropertyValue('--ink').trim() || '#17181A'};
+      font-family:-apple-system,"IBM Plex Sans","PingFang TC","Noto Sans TC","Microsoft JhengHei",system-ui,sans-serif;
+      font-size:15px}
+  </style>`;
+  f.srcdoc = '<!doctype html><meta charset="utf-8">' + skin + bridge + d.uiHtml;
+  f.onload = () => {
+    if (appFrameBridge) window.removeEventListener('message', appFrameBridge);
+    appFrameBridge = async (ev) => {
+      if (!f.contentWindow || ev.source !== f.contentWindow) return;   // 只認自己這個 iframe
+      const m = ev.data;
+      if (!m || m.__arcrun !== 'action') return;
+      const reply = (payload) =>
+        f.contentWindow && f.contentWindow.postMessage({ __arcrun: 'result', id: m.id, payload }, '*');
+      try {
+        const raw = await go.RunAppAction(accIdx, d.id, String(m.action || ''), JSON.stringify(m.payload || {}));
+        let parsed = null;
+        try { parsed = JSON.parse(raw); } catch (e) { parsed = { ok: true, result: raw }; }
+        reply({ ok: true, status: 200, d: parsed });
+      } catch (ex) {
+        reply({ ok: false, status: 0, d: { error: String(ex) } });
+      }
+    };
+    window.addEventListener('message', appFrameBridge);
+  };
+}
+
 function renderPage() {
   if (!state) return;
   let html;
-  if (page.startsWith('lib:')) html = pageLib(state, Number(page.slice(4)));
+  if (page === 'apps') html = pageApps(state);
+  else if (page.startsWith('app:')) {
+    const p = page.split(':');
+    html = pageApp(Number(p[1]), p.slice(2).join(':'));
+  }
+  else if (page.startsWith('lib:')) html = pageLib(state, Number(page.slice(4)));
   else if (page === 'ai') html = pageAI(state);
   else if (page === 'update') html = pageUpdate(state);
   else html = pageHome(state);
@@ -447,12 +740,105 @@ function wire() {
   document.querySelectorAll('[data-rm]').forEach((b) => {
     b.onclick = () => confirmRemove(Number(b.dataset.acc), b.dataset.rm);
   });
+
+  // ── App 啟動器（arcrun-rag#137）──
+  on('apConnect', showConnect);
+  on('apRefresh', () => loadApps(appsAccIdx, true));
+  on('apRetry', () => loadApps(appsAccIdx, true));
+  on('apAdd', showHowToInstallApp);
+  on('apReload', () => { const p = page.split(':'); loadAppDetail(Number(p[1]), p.slice(2).join(':')); });
+  on('apLogin', appLogin);
+  document.querySelectorAll('[data-appacc]').forEach((b) => {
+    b.onclick = () => { appsAccIdx = Number(b.dataset.appacc); renderPage(); loadApps(appsAccIdx); };
+  });
+  document.querySelectorAll('[data-appopen]').forEach((b) => {
+    b.onclick = () => goToApp(appsAccIdx, b.dataset.appopen);
+  });
+  document.querySelectorAll('[data-appback]').forEach((b) => {
+    b.onclick = () => { page = 'apps'; appDetail = null; appDetailKey = ''; renderNav(); renderPage(); };
+  });
+  document.querySelectorAll('[data-apprun]').forEach((b) => { b.onclick = () => runAppAction(b); });
+
+  // App 自帶畫面：DOM 換好之後才掛 iframe（srcdoc 要等元素真的在文件裡）
+  if (page.startsWith('app:') && appDetail && appDetail.hasUi && appDetail.uiHtml) {
+    mountAppUI(Number(page.split(':')[1]), appDetail);
+  }
+}
+
+// goToApp 換到某個 App 的頁。換頁前先把上一個 App 的 postMessage 監聽器拆掉——
+// 不拆的話每開一次 App 就多留一個死監聽器（而且它還綁著舊的 accIdx/appId）。
+function goToApp(accIdx, id) {
+  if (appFrameBridge) { window.removeEventListener('message', appFrameBridge); appFrameBridge = null; }
+  page = 'app:' + accIdx + ':' + id;
+  renderNav();
+  loadAppDetail(accIdx, id);
+}
+
+// 「加裝 App」：桌面端**不假裝自己能安裝**——安裝是實例上的動作
+// （跟 AI 說一句話，或 acr 推一份宣告）。這裡只把「東西從哪來」講清楚，
+// 順便給一個開知識庫網頁的出口。
+function showHowToInstallApp() {
+  const acc = (state.accounts || [])[appsAccIdx];
+  const portal = acc ? 'https://' + acc.host.replace('arcrun-cypher-executor.', 'arcrun-rag-ui.') + '/portal/' : '';
+  openSheet(`
+    <h2>怎麼加裝 App？</h2>
+    <p>App 是裝在<b>知識庫</b>上的，不是裝在這台電腦上——所以你在任何一台電腦、
+    或在知識庫網頁上，看到的都是同一批 App。</p>
+    <p>兩種裝法：跟你的 AI 說「幫我裝一個 ⋯⋯」，或用 <b>acr</b> 把一份 App 宣告推上去。
+    裝好之後回到這裡按「重新整理」就會出現。</p>
+    <div class="acts">
+      <button id="c1">知道了</button>
+      ${portal ? `<button class="primary" id="c2">開啟知識庫網頁</button>` : ''}
+    </div>`,
+    () => {
+      $('c1').onclick = closeSheet;
+      if ($('c2')) $('c2').onclick = () => { go.OpenURL(portal); closeSheet(); };
+    });
+}
+
+async function appLogin() {
+  const accIdx = Number(page.split(':')[1]);
+  const id = page.split(':').slice(2).join(':');
+  const err = $('apErr');
+  const btn = $('apLogin');
+  if (btn) btn.disabled = true;
+  try {
+    await go.PortalLogin(accIdx, $('apPw').value);
+    if (btn) btn.disabled = false;
+    loadAppDetail(accIdx, id);
+  } catch (ex) {
+    if (btn) btn.disabled = false;
+    if (err) { err.textContent = String(ex); err.style.display = 'block'; }
+  }
+}
+
+// runAppAction：沒有自帶畫面的 App，那顆「現在執行」。
+// 🔴 白名單是**實例**裁決的（K6）——這裡不認得任何動作名稱，只負責把按鈕送出去、
+//    把實例回的話原樣顯示。失敗就說失敗，不改寫成「可能成功」。
+async function runAppAction(btn) {
+  const accIdx = Number(page.split(':')[1]);
+  const id = page.split(':').slice(2).join(':');
+  const item = btn.closest('.wfitem');
+  const out = item && item.querySelector('.out');
+  btn.disabled = true;
+  if (out) { out.className = 'out'; out.textContent = '執行中…'; }
+  try {
+    const raw = await go.RunAppAction(accIdx, id, btn.dataset.apprun, '{}');
+    if (out) out.textContent = '完成：' + String(raw).slice(0, 600);
+  } catch (ex) {
+    if (out) { out.className = 'out bad'; out.textContent = '失敗：' + String(ex); }
+  }
+  btn.disabled = false;
 }
 
 function render(s) {
   const first = !state;
   const navChanged = state && JSON.stringify((state.accounts||[]).map(a=>[a.name,(a.folders||[]).length]))
                           !== JSON.stringify((s.accounts||[]).map(a=>[a.name,(a.folders||[]).length]));
+  // arcrun-rag#137：還沒連上任何知識庫時，第一眼要落在連線精靈（首頁），
+  // 不是一個註定空的 App 啟動器。連上之後（accounts 從 0 變成 1）也不要硬把
+  // 使用者拉走——他當下正在看剛連好的東西。
+  if (first && page === 'apps' && !(s.accounts || []).length) page = 'home';
   state = s;
   $('ver').textContent = s.version || '';
   $('statusBig').textContent = s.statusBig;
@@ -460,6 +846,9 @@ function render(s) {
   $('statusSub').textContent = s.statusSub;
   if (first || navChanged) { renderNav(); renderPage(); }
   else if (page === 'home') renderPage();   // 首頁的狀態時間軸要跟著跳
+  // 🔴 這是**唯一**一次自動去問實例：第一次拿到 state（＝知道有哪些知識庫）之後。
+  //    之後只有使用者按重新整理／切知識庫才會再問一次——**不掛在每秒的 tick 上**。
+  if (first && page === 'apps' && (s.accounts || []).length) loadApps(appsAccIdx);
 }
 
 async function tick() { try { render(await go.GetState()); } catch (e) {} }
@@ -481,28 +870,70 @@ async function addFolder(accIdx) {
 //    那句話**在技術上是對的**，但它預設使用者要的是「只停止同步」，
 //    而他要的是「我不要這份資料了」。⇒ 病不在少一句說明，在**替他決定了**。
 //    現在兩個選擇都擺出來、後果各寫一行，由他挑。
+// 🔴 arcrun-rag#138（leo 2026-08-24）：「碎型會在每個資料夾安裝隱藏資料夾，人工刪除不容易，
+//    所以當它斷連，應該要可以幫它把 Arcrun RAG 建立的資料夾刪掉」
+//    ⇒ 多一個**獨立的勾選框**，不是第三顆單選：雲端怎麼處理、硬碟怎麼處理是兩件事，
+//      合成一個選項就又是替他決定（#46 修掉的正是那個病）。
+//    🔴 預設不勾——刪檔不可逆，預設值往「什麼都不動」倒。
+//    🔴 勾了才去問清單，並且把**每一筆路徑攤出來**：#138 的驗收條件白紙黑字寫著
+//      「使用者要能在動手前看到將要刪掉哪些東西」，按下去就無聲刪光不算做完。
 function confirmRemove(accIdx, path) {
   openSheet(`
     <h2>移除這個資料夾？</h2>
-    <p>「${esc(path)}」要怎麼處理？<b>你電腦裡的原始檔案不會被動到</b>，兩個選擇的差別只在雲端。</p>
+    <p>「${esc(path)}」要怎麼處理？<b>你自己的檔案不會被動到</b>——下面兩個選擇差在雲端，最後那個勾選框差在你的硬碟。</p>
     <label class="radio"><input type="radio" name="rmMode" value="takedown" checked/>
       <span><b>連同雲端的知識一起收回</b><br/>
       <span class="d">這個資料夾整理出來的知識會從知識庫刪除，之後搜尋找不到、AI 也不會再拿它回答。<b>刪掉就要不回來</b>。</span></span></label>
     <label class="radio"><input type="radio" name="rmMode" value="unwatch"/>
       <span><b>只停止同步，雲端的知識保留</b><br/>
       <span class="d">以後這個資料夾有變動不會再上傳，但之前整理好的知識留在知識庫裡，搜尋和 AI 照樣找得到。</span></span></label>
+    <label class="radio"><input type="checkbox" id="rmClean"/>
+      <span><b>順便把 Arcrun RAG 放在這個資料夾裡的檔案清掉</b><br/>
+      <span class="d">我們會在每一層資料夾放一個隱藏的整理稿目錄（<code>.wiki</code>／<code>.arcrun-rag</code>），
+      散在各層、你自己很難刪乾淨。勾起來會先列出<b>確切要刪哪些</b>給你看過再動手；認不出是我們建的一律留著。</span></span></label>
+    <div id="rmPlan" class="d" style="display:none;margin:8px 0 4px"></div>
     <div class="acts"><button id="c1">取消</button><button class="primary" id="c2">確定</button></div>`,
     () => {
       $('c1').onclick = closeSheet;
+      const box = $('rmClean'), out = $('rmPlan');
+      box.onchange = async () => {
+        if (!box.checked) { out.style.display = 'none'; out.innerHTML = ''; return; }
+        out.style.display = ''; out.textContent = '正在看這個資料夾裡有哪些是我們建的…';
+        try {
+          out.innerHTML = renderCleanupPlan(await go.PlanFolderCleanup(accIdx, path));
+        } catch (e) {
+          out.textContent = '看不到清單（' + e + '）——沒把握就先別勾這一項。';
+        }
+      };
       $('c2').onclick = async () => {
         const mode = document.querySelector('input[name="rmMode"]:checked');
         const takedown = !mode || mode.value === 'takedown';
-        await go.RemoveFolder(accIdx, path, takedown); closeSheet();
+        await go.RemoveFolder(accIdx, path, takedown, box.checked); closeSheet();
         state = await go.GetState(); renderNav(); renderPage();
       };
     });
 }
 
+// renderCleanupPlan 把「將要刪掉什麼／刻意留下什麼」攤成使用者看得懂的清單。
+// 🔴 留下的那一半一樣要顯示：沉默地留下殘渣，跟沉默地刪掉一樣糟——他要的是
+//    「這個資料夾乾淨了」，那就得讓他看得到還有什麼沒清、為什麼沒清。
+function renderCleanupPlan(plan) {
+  const rm = (plan && plan.remove) || [], keep = (plan && plan.keep) || [];
+  if (!rm.length && !keep.length) return '這個資料夾裡沒有找到任何 Arcrun RAG 建立的檔案，不需要清理。';
+  let h = '';
+  if (rm.length) {
+    h += `<b>會刪掉這 ${rm.length} 項（共 ${plan.files} 個檔）：</b><ul style="margin:4px 0 0 16px">`;
+    for (const it of rm) h += `<li>${esc(it.rel)}${it.is_dir ? '／' : ''}（${it.files} 個檔）</li>`;
+    h += '</ul>';
+  }
+  if (keep.length) {
+    h += `<b style="display:block;margin-top:8px">這 ${keep.length} 項我不會動：</b><ul style="margin:4px 0 0 16px">`;
+    for (const k of keep) h += `<li>${esc(k.rel)} — ${esc(k.reason)}</li>`;
+    h += '</ul>';
+  }
+  return h;
+}
+
 function showConnect() {
   openSheet(`
     <h2>連上你的知識庫</h2>

cmd/arcrun-app/frontend/src/style.css

@@ -304,3 +304,111 @@ input[type=text], input[type=password] {
   width: 7px; height: 7px; border-radius: 50%; flex: none;
   background: var(--err); margin-left: 4px;
 }
+
+/* ══════════════════════════════════════════════════════════════════════════
+   App 啟動器（arcrun-rag#137）
+   leo 2026-08-24：「所有的 App 需要有一個類似 Android/iOS 的**九宮格啟動界面**，
+   每個 App 有一個 icon，這會運行在 portal 及 daemon。」
+
+   🔴 尺寸／圓角／間距逐項照 leo 已核准的設計稿（Launcher-Desktop.dc.html）：
+      磁磚 88x88、圓角 22、格線 gap 32/24、hover 上浮 2px、標籤 14px 置中。
+   🔴 顏色**一個 hex 都不准出現**——全部走 arcrun-cis.css 的變數（本檔開頭那條規矩）。
+   ══════════════════════════════════════════════════════════════════════════ */
+
+/* 頁首：知識庫名 ＋ 幾個 App ＋ 重新整理（同 .libhead 的結構，不另發明一種頁首） */
+.apphead {
+  display: flex; align-items: center; gap: 14px;
+  padding-bottom: 18px; margin-bottom: 26px;
+  border-bottom: 2px solid rgba(var(--amber-rgb), .35);   /* 設計稿的 accentSoft 分隔線 */
+}
+.apphead .g { flex: 1; min-width: 0; }
+.apphead .t { font-size: 22px; font-weight: 600; letter-spacing: .04em; }
+.apphead .s { margin-top: 5px; font-size: 13.5px; color: rgba(var(--ink-rgb), .55); }
+
+/* 多個知識庫時才出現的切換器（只有一個庫時畫面上不該有這排噪音） */
+.appswitch { display: flex; gap: 8px; margin-bottom: 20px; flex-wrap: wrap; }
+/* 圓角用 10px（同 button），刻意**不用**膠囊——check-cis.sh 明文擋膠囊選中態
+   （leo 08-04 否決過），而且這排切換器與按鈕本來就該是同一種形狀語彙。 */
+.appswitch .chip {
+  padding: 6px 13px; font-size: 13px; border-radius: 10px;
+  border: 1px solid rgba(var(--ink-rgb), .18);
+  color: rgba(var(--ink-rgb), .6); cursor: pointer; user-select: none;
+}
+.appswitch .chip.on {
+  border-color: var(--amber); color: var(--amber);
+  background: rgba(var(--amber-rgb), .08); font-weight: 600;
+}
+
+/* 九宮格本體。auto-fill 而不是固定 4 欄：桌面視窗是可以被拉窄的（min 820px），
+   固定欄數會在窄視窗把磁磚擠變形。 */
+.appgrid {
+  display: grid; grid-template-columns: repeat(auto-fill, minmax(116px, 1fr));
+  gap: 32px 24px;
+}
+.appcell { display: flex; flex-direction: column; align-items: center; gap: 11px; }
+.apptile {
+  width: 88px; height: 88px; border-radius: 22px;
+  display: flex; align-items: center; justify-content: center;
+  font-size: 38px; line-height: 1;
+  background: var(--well); border: 1px solid rgba(var(--ink-rgb), .1);
+  cursor: pointer; user-select: none;
+  transition: border-color .12s, background .12s, transform .12s;
+}
+.apptile:hover {
+  transform: translateY(-2px);
+  border-color: var(--amber);
+  background: rgba(var(--amber-rgb), .08);
+}
+/* 「加裝 App」——設計稿是虛線框＋加號，語意是「這一格還沒有東西」 */
+.apptile.add {
+  background: none; border: 1.5px dashed rgba(var(--ink-rgb), .22);
+  font-size: 28px; color: rgba(var(--ink-rgb), .45);
+}
+.appcell .nm {
+  font-size: 14px; text-align: center; line-height: 1.4;
+  max-width: 116px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.appcell .nm.dim { color: rgba(var(--ink-rgb), .55); }
+
+/* App 頁 */
+.appview { display: flex; flex-direction: column; }
+.appview .head {
+  display: flex; align-items: center; gap: 12px;
+  padding-bottom: 14px; margin-bottom: 16px;
+  border-bottom: 1px solid rgba(var(--ink-rgb), .1);
+}
+.appview .head .ico { font-size: 24px; line-height: 1; }
+.appview .head .nm { font-size: 17px; font-weight: 600; }
+.appview .head .vr {
+  font-size: 12px; color: rgba(var(--ink-rgb), .4);
+  font-family: ui-monospace, Menlo, monospace;
+}
+.appview .head .sp { flex: 1; }
+
+/* App 自帶畫面：**關在 sandbox iframe 裡**（見 main.js mountAppUI 的理由）。
+   高度吃滿剩下的版面，讓 App 自己決定要怎麼排。 */
+/* 高度用 calc 而不是 flex:1／height:100%：#page 是 flex item ＋ 自帶 padding，
+   百分比高度在那裡會多算出一段 padding 而長出一條假捲軸。
+   250px＝頁首(約 90) + main padding(48) + App 頁首(約 60) + 呼吸。 */
+.appframe {
+  width: 100%; height: calc(100vh - 250px); min-height: 420px;
+  border: 1px solid rgba(var(--ink-rgb), .1); border-radius: 12px;
+  background: var(--paper-a);
+}
+
+/* 沒有自帶畫面的 App＝列出它的工作流，一條一顆「現在執行」
+   （與 Portal 的系統預設畫面同一套呈現，不另立第二種） */
+.wfitem {
+  background: var(--well); border-radius: 12px;
+  padding: 15px 18px; margin-bottom: 10px;
+}
+.wfitem .top { display: flex; align-items: baseline; gap: 12px; }
+.wfitem .nm { font-size: 15px; font-weight: 600; flex: 1; min-width: 0; }
+.wfitem .d { margin-top: 7px; font-size: 13.5px; color: rgba(var(--ink-rgb), .55); line-height: 1.7; }
+.wfitem .out {
+  margin-top: 8px; font-size: 12.5px; line-height: 1.6;
+  font-family: ui-monospace, Menlo, monospace;
+  color: rgba(var(--ink-rgb), .55);
+  word-break: break-all; white-space: pre-wrap;
+}
+.wfitem .out.bad { color: var(--err); }

cmd/arcrun-app/remove_folder_cleanup_test.go

@@ -0,0 +1,168 @@
+// remove_folder_cleanup_test.go — arcrun-rag#138：移除資料夾時可以連同硬碟上的
+// 隱藏資料夾一起收掉，而且**只收我們自己建的**。
+//
+// 本檔釘 App 這一半的四件事（認人的判準本身由 collector/cleanup_test.go 釘）：
+//  1. 沒勾清理 ⇒ 硬碟上一個檔都不准少（預設不刪，跟 #46 同一條紅線）
+//  2. 勾了清理 ⇒ 我們的隱藏資料夾（含巢狀層）沒了，使用者的檔案一個不少
+//  3. 另一個還在看守（或還在收回中）的資料夾底下 ⇒ 不碰
+//  4. PlanFolderCleanup 只讀不寫，且拿得到「將要刪掉哪些」的清單
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"testing"
+
+	collector "arcrun-rag/collector"
+)
+
+func mkfile(t *testing.T, path, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// makeFakeWatched 造一個「daemon 跑過」的資料夾：使用者的原稿＋我們的隱藏產物（兩層）。
+func makeFakeWatched(t *testing.T, root string) {
+	t.Helper()
+	mkfile(t, filepath.Join(root, "我的原稿.md"), "使用者的知識\n")
+	mkfile(t, filepath.Join(root, "docs", "設計.md"), "使用者的設計\n")
+	// 工作區與各層卡片目錄的內容逐字取自 collector 真正寫下去的那兩份宣告
+	mkfile(t, filepath.Join(root, ".arcrun-rag", ".gitignore"), collector.WorkspaceIgnoreBodyForTest())
+	for _, node := range []string{"", "docs"} {
+		dir := filepath.Join(root, node, ".wiki")
+		mkfile(t, filepath.Join(dir, ".gitignore"), collector.WikiIgnoreBodyForTest())
+		mkfile(t, filepath.Join(dir, "00-INDEX.md"), "# 00-INDEX\n\n## 文件\n")
+		mkfile(t, filepath.Join(dir, "arcrun-一張卡.md"), "# 卡\n")
+	}
+}
+
+func listFiles(t *testing.T, root string) []string {
+	t.Helper()
+	var out []string
+	_ = filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return nil
+		}
+		rel, _ := filepath.Rel(root, p)
+		out = append(out, filepath.ToSlash(rel))
+		return nil
+	})
+	sort.Strings(out)
+	return out
+}
+
+// ① 沒勾清理＝行為與從前一字不差：硬碟上一個檔都不准少。
+func TestRemoveFolderWithoutCleanupTouchesNothing(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	root := filepath.Join(t.TempDir(), "kb")
+	makeFakeWatched(t, root)
+	newTestCfgWithFolder(t, root)
+
+	before := listFiles(t, root)
+	if err := (&App{}).RemoveFolder(0, root, false, false); err != nil {
+		t.Fatalf("移除失敗：%v", err)
+	}
+	after := listFiles(t, root)
+	if len(before) != len(after) {
+		t.Fatalf("沒勾清理就不准動硬碟：before=%v after=%v", before, after)
+	}
+}
+
+// ② 勾了清理：我們的東西沒了，使用者的東西一個不少。
+func TestRemoveFolderWithCleanupRemovesOnlyOurs(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	root := filepath.Join(t.TempDir(), "kb")
+	makeFakeWatched(t, root)
+	newTestCfgWithFolder(t, root)
+
+	if err := (&App{}).RemoveFolder(0, root, false, true); err != nil {
+		t.Fatalf("移除失敗：%v", err)
+	}
+	got := listFiles(t, root)
+	want := []string{"docs/設計.md", "我的原稿.md"}
+	sort.Strings(want)
+	if len(got) != len(want) {
+		t.Fatalf("清完之後應該只剩使用者的檔\n got=%v\nwant=%v", got, want)
+	}
+	for i := range got {
+		if got[i] != want[i] {
+			t.Fatalf("清完之後應該只剩使用者的檔\n got=%v\nwant=%v", got, want)
+		}
+	}
+}
+
+// ③ 巢狀在裡面、但**還在收回中**的資料夾 ⇒ 不碰它底下的東西。
+func TestRemoveFolderCleanupSkipsRetiringNestedRoot(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	root := filepath.Join(t.TempDir(), "kb")
+	inner := filepath.Join(root, "legacy")
+	makeFakeWatched(t, root)
+	makeFakeWatched(t, inner)
+
+	cfg := &directConfig{
+		Accounts: []accountCfg{{
+			CypherURL: "https://example.workers.dev", Namespace: "abc", APIKey: "abc",
+			WatchFolders:    []string{root},
+			RetiringFolders: []string{inner}, // 還在把雲端的資料收回來，別動它的檔
+		}},
+		Extractor: "workers-ai",
+	}
+	if err := saveCfg(cfg); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := (&App{}).RemoveFolder(0, root, false, true); err != nil {
+		t.Fatalf("移除失敗：%v", err)
+	}
+	for _, p := range []string{
+		filepath.Join(inner, ".arcrun-rag", ".gitignore"),
+		filepath.Join(inner, ".wiki", "arcrun-一張卡.md"),
+		filepath.Join(inner, "docs", ".wiki", "arcrun-一張卡.md"),
+	} {
+		if _, err := os.Stat(p); err != nil {
+			t.Fatalf("還在收回中的資料夾底下的東西被刪了：%s（%v）", p, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(root, ".wiki")); !os.IsNotExist(err) {
+		t.Fatalf("外層自己的 .wiki 該被清掉")
+	}
+}
+
+// ④ 先看清單：拿得到內容，而且看完之後硬碟一個檔都沒變。
+func TestPlanFolderCleanupIsReadOnly(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	root := filepath.Join(t.TempDir(), "kb")
+	makeFakeWatched(t, root)
+	newTestCfgWithFolder(t, root)
+
+	before := listFiles(t, root)
+	plan, err := (&App{}).PlanFolderCleanup(0, root)
+	if err != nil {
+		t.Fatalf("拿不到清單：%v", err)
+	}
+	if len(plan.Remove) == 0 {
+		t.Fatal("這份擺法應該列得出東西")
+	}
+	for _, it := range plan.Remove {
+		if it.Evidence == "" {
+			t.Fatalf("清單上每一筆都要說得出依據：%+v", it)
+		}
+	}
+	if after := listFiles(t, root); len(after) != len(before) {
+		t.Fatalf("看清單這個動作動了硬碟：before=%v after=%v", before, after)
+	}
+}

cmd/arcrun-app/remove_folder_takedown_test.go

@@ -38,7 +38,7 @@ func TestRemoveFolderWithTakedownQueuesRetirement(t *testing.T) {
 	t.Setenv("USERPROFILE", home)
 	newTestCfgWithFolder(t, "/kb/logseq-plugin")
 
-	if err := (&App{}).RemoveFolder(0, "/kb/logseq-plugin", true); err != nil {
+	if err := (&App{}).RemoveFolder(0, "/kb/logseq-plugin", true, false); err != nil {
 		t.Fatalf("移除失敗：%v", err)
 	}
 	cfg, err := loadCfg()
@@ -90,7 +90,7 @@ func TestRemoveFolderWithoutTakedownKeepsCloudData(t *testing.T) {
 	t.Setenv("USERPROFILE", home)
 	newTestCfgWithFolder(t, "/kb/keep-cloud")
 
-	if err := (&App{}).RemoveFolder(0, "/kb/keep-cloud", false); err != nil {
+	if err := (&App{}).RemoveFolder(0, "/kb/keep-cloud", false, false); err != nil {
 		t.Fatalf("移除失敗：%v", err)
 	}
 	cfg, _ := loadCfg()

cmd/arcrun-app/tray_other.go

@@ -0,0 +1,19 @@
+//go:build !darwin && !windows
+
+package main
+
+// tray_other.go — 非出貨平台（Linux 等）的系統匣 no-op（arcrun-rag#137）。
+//
+// 為什麼加這一個檔：`setupTray` 只在 `tray_darwin.go`／`tray_windows.go` 有實作，
+// 所以整包在 Linux **連編都編不起來**（`undefined: setupTray`）——
+// 連帶 `go build ./...`／`go test ./...` 這兩件最基本的機械驗證在雲端／CI 上做不了，
+// 而這台桌面 App 的出貨機是 macOS 與 Windows，本來就沒人會在 Linux 跑它。
+//
+// ⇒ 補一個 no-op，讓「編得過／測得過」這條線在任何機器上都成立。
+// **對出貨零影響**：darwin 與 windows 兩個 tag 都排除了這個檔，
+// 兩邊拿到的仍然是各自那份真正的托盤實作。
+//
+// 🔴 這不是「Linux 版桌面 App」：Linux 上沒有托盤、也沒有人測過 WebView，
+//
+//	它存在的唯一理由是讓編譯器與測試跑得起來（同 dock_other.go 的先例）。
+func setupTray(_ *App) {}

direct.go

@@ -672,6 +672,10 @@ func RunDirectOnce(cfg *DirectConfig, dryRun bool) ([]DirectResult, int, *Trigge
 	// 每輪重建、照現況重報（level-triggered），App 看到 done 才把設定裡那一筆清掉。
 	var retiring map[string]RetiringStatus
 
+	// `inkstone/arcrun-rag#140`：這一輪各個資料夾的「雲端補送」現況（key＝資料夾路徑）。
+	// 同 retiring 的 level-triggered 語意：每輪照 manifest 現況重報，補完自然消失。
+	var resync map[string]ResyncStatus
+
 	// t215：全域「雲端最新版」只抓一次（自帶節流，見 cloud_latest.go）——
 	// 這是所有帳號共用的同一把尺，不是逐帳號各打一次。
 	latestRelease, latestOK := FetchLatestCloudRelease()
@@ -733,6 +737,13 @@ func RunDirectOnce(cfg *DirectConfig, dryRun bool) ([]DirectResult, int, *Trigge
 			r, e, p, rp := runDirectOnceRoot(accCfg, root, dryRun, qs, now)
 			totalProgress = totalProgress.Add(rp.Progress)
 			stuckReasons = append(stuckReasons, rp.StuckReasons...)
+			// #140：有話要說才佔畫面（零值＝這個資料夾沒有補送中的事）。
+			if rp.Resync.Pending > 0 || rp.Resync.Repaired > 0 || rp.Resync.LastError != "" {
+				if resync == nil {
+					resync = map[string]ResyncStatus{}
+				}
+				resync[root] = rp.Resync
+			}
 			if multi {
 				for i := range r {
 					r[i].Root = root
@@ -828,6 +839,7 @@ func RunDirectOnce(cfg *DirectConfig, dryRun bool) ([]DirectResult, int, *Trigge
 			ExtractorError: extractorError,
 			AccountDetails: accountDetails,
 			Retiring:       retiring, // arcrun-rag#46：移除並收回中的資料夾進度
+			Resync:         resync,   // arcrun-rag#140：雲端上找不到、正在自動補送的資料夾
 		}
 		// G-6.2：把「讀不了的檔」寫進狀態檔，App 首頁才有東西可以講。
 		// 排序＝畫面每輪穩定（map 迭代順序隨機，不排的話清單會自己跳動）。
@@ -1204,6 +1216,10 @@ func accountsConnected(cfg *DirectConfig) bool {
 type rootProgress struct {
 	Progress     SyncProgress // 這一根的 Total/Done/Pending/Stuck（Unreadable 由呼叫端補，見 progress.go）
 	StuckReasons []string     // 已放棄自動重試那些條目的 LastError 原文，交給 ClassifyFailure 分類
+	// Resync＝這一根的「雲端補送」現況（#140）。**從 manifest 現況重算**，不是本輪計數
+	// ——後者在沒事做的那輪會歸零，那正是 2026-08-05 leo 實撞的「明明做完了畫面卻寫等待中」。
+	// 沒事＝零值，呼叫端不寫進 status.json（不製造常駐噪音）。
+	Resync ResyncStatus
 }
 
 // qs：這個帳號本輪共用的額度冷卻狀態（跨同帳號的多個監看根，見 quota.go）。
@@ -1255,6 +1271,52 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool, qs *quotaSta
 	if err != nil {
 		return append(results, DirectResult{Status: "failed", Error: err.Error()}), 1, nil, rootProgress{}
 	}
+	// 2026-08-07 task 3（斷點續傳）：每個事件處理完就立刻存檔，不要等整輪跑完。
+	// 舊行為＝整個 for 迴圈跑完才 Save 一次——process 在跑到一半被殺掉（重開機、
+	// 換版、當機）時，**已經成功的那些也會遺失**，下次重開等於從頭來過，
+	// 且已經花掉的額度/請求全部白費（正是 leo 要求「不從頭來」要防的事）。
+	// 改成每個事件收工就存一次：kill 在任何一刻，磁碟上的 manifest 都反映
+	// 「這一刻之前已確定成功的事」，下一輪只會處理真正還沒做完的。
+	//
+	// （#140：定義位置從「Scan() 之後」往上搬到這裡，因為雲端對帳跑在 Scan() 之前
+	//  也要落盤——拔掉的章沒存進磁碟，process 被殺掉就等於沒對過帳。內容一字未動。）
+	saveManifest := func() {
+		if dryRun {
+			return
+		}
+		if serr := m.Save(absManifest); serr != nil {
+			results = append(results, DirectResult{Status: "failed", Error: "manifest 存檔失敗（斷點續傳可能失效）：" + serr.Error()})
+			exit = 1
+		}
+	}
+
+	// 🔴 雲端對帳（`inkstone/arcrun-rag#140`，2026-08-26）——**必須在 Scan() 之前**。
+	// 它做的唯一一件事是把「雲端已經沒有了」的 ingested 章拔掉；拔完之後
+	// 下面那個 Scan() 就會因為 `orig[p].IngestedHash == ""` 自然補一發 added 事件
+	// （scan.go 步驟 4 的既有語意「上輪偵測過但 ingest 未成功 → 重試」）
+	// ⇒ 補送走的是**既有的**萃取路，既有的單輪上限／失敗退避／額度冷卻全部照舊生效。
+	// 放在 Scan() 之後就得再等一輪才會動，且要另外發明一條送件路。見 cloud_audit.go。
+	auditErr := ""
+	if ar := auditCloudLedger(cfg, absRoot, m, dryRun, runNow); ar != nil {
+		auditErr = ar.Err
+		if ar.Voided > 0 {
+			results = append(results, DirectResult{
+				Type: "resync", Path: absRoot, Status: "noticed",
+				Error: fmt.Sprintf("雲端上找不到 %d 份先前送過的檔案（對帳了 %d 份，知識庫可能重裝過），已排進佇列自動補送", ar.Voided, ar.Checked),
+			})
+		}
+		if ar.Err != "" {
+			// 上游錯誤原文照顯示（leo 2026-08-06：「別人的錯誤一律要顯示給用戶看，
+			// 不然就會變成我的錯誤」）。對帳失敗**不設 exit**：它是保險絲不是主流程，
+			// 連不上雲端時檔案同步照常走。
+			results = append(results, DirectResult{
+				Type: "resync", Path: absRoot, Status: "noticed",
+				Error: "無法跟雲端核對哪些檔案還在（不影響同步，稍後自動再試）：" + ar.Err,
+			})
+		}
+		saveManifest() // 拔掉的章與對帳時間當下就落盤（斷點續傳同款）
+	}
+
 	// 2026-08-07 task 3：Scan() 會把 removed 的路徑從 m.Entries 整批拿掉（rebuild 語意，
 	// 見 scan.go 步驟 7）——但那只是「偵測到不見了」，不代表下架 POST 已經成功。
 	// 沒有這份快照的話，本輪只要有任何一個 added/modified 事件先觸發了下面的
@@ -1291,22 +1353,6 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool, qs *quotaSta
 
 	now := runNow.Unix()
 
-	// 2026-08-07 task 3（斷點續傳）：每個事件處理完就立刻存檔，不要等整輪跑完。
-	// 舊行為＝整個 for 迴圈跑完才 Save 一次——process 在跑到一半被殺掉（重開機、
-	// 換版、當機）時，**已經成功的那些也會遺失**，下次重開等於從頭來過，
-	// 且已經花掉的額度/請求全部白費（正是 leo 要求「不從頭來」要防的事）。
-	// 改成每個事件收工就存一次：kill 在任何一刻，磁碟上的 manifest 都反映
-	// 「這一刻之前已確定成功的事」，下一輪只會處理真正還沒做完的。
-	saveManifest := func() {
-		if dryRun {
-			return
-		}
-		if serr := m.Save(absManifest); serr != nil {
-			results = append(results, DirectResult{Status: "failed", Error: "manifest 存檔失敗（斷點續傳可能失效）：" + serr.Error()})
-			exit = 1
-		}
-	}
-
 	// 結構先行（InkStoneCo#43，2026-08-15）：掃描一結束（純本機、免費、秒級）就先把
 	// 「這個資料夾有哪些檔案／最近改了什麼」送上知識庫，**不等 LLM 萃取、不受額度影響**
 	// ——走 rag_ingest_card（零 LLM 的機械收口），所以刻意放在：
@@ -1528,6 +1574,12 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool, qs *quotaSta
 					res.Status = "ingested"
 					// 記下是誰萃的（t73/leo 07-27）：換萃取器時才分辨得出哪些卡是舊的。
 					m.MarkIngestedBy(ev.Path, ev.SourceHash, now, cfg.Extractor)
+					// 🔴 #140：`cards` 為空＝該檔被判「無可萃取概念」，這一輪**一張卡都沒上雲**。
+					//   不記下來的話，雲端對帳每天都會查到「雲端沒有它」⇒ 每天重萃一次、
+					//   永遠停不下來，而且每次都燒一份 AI 額度。
+					if len(cards) == 0 {
+						m.MarkNoCloudCard(ev.Path)
+					}
 					qs.DailyCount++ // 2026-08-07：今天的成就數（額度訊息「今天已經幫你整理了 N 份」用）
 				} else {
 					// t195：記下失敗並排定退避，否則下輪又把它當新檔重試
@@ -1678,6 +1730,18 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool, qs *quotaSta
 			rp.StuckReasons = append(rp.StuckReasons, e.LastError)
 		}
 	}
+	// #140：同一套「現況快照」邏輯——補送進度也是原地數出來的，不是本輪計數器。
+	if pending, repaired := ResyncSummary(m, runNow); pending > 0 || repaired > 0 || auditErr != "" {
+		rp.Resync = ResyncStatus{
+			Pending:   pending,
+			Repaired:  repaired,
+			LastError: auditErr, // 真因原文，不改寫（leo 2026-08-06）
+			Note:      resyncNote(pending, repaired, auditErr),
+		}
+		if m.CloudAuditAt > 0 {
+			rp.Resync.CheckedAt = time.Unix(m.CloudAuditAt, 0).UTC().Format(time.RFC3339)
+		}
+	}
 	return results, exit, payload, rp
 }
 

main.go

@@ -89,6 +89,8 @@ func Run(args []string) int {
 		return runTemplateInstall(args[1:])
 	case "tidy":
 		return runTidy(args[1:])
+	case "cleanup":
+		return runCleanup(args[1:])
 	default:
 		usage()
 		return 2
@@ -107,7 +109,9 @@ func usage() {
   collector sync   --root <dir> --manifest <file> [--max-removed-ratio 0.4] [--dry-run]
   collector direct --config <config.json> [--once] [--dry-run]
   collector tidy   --folder <dir> [--apply] [--json]
+  collector cleanup --folder <dir> [--keep <還在看守的別的資料夾>]… [--apply] [--json]
 tidy: 找出以前寫進資料夾、還沒帶 arcrun- 標記的舊產物並改名/搬走（預設只列出不動手，加 --apply 才執行；從不刪檔）
+cleanup: 斷連時把 daemon 建立的 .arcrun-rag/ 與各層 .wiki/ 收掉（預設只列清單，加 --apply 才真的刪；認不出來的一律留著）
 upload 需環境變數: CF_ACCOUNT_ID / CF_API_TOKEN / R2_BUCKET
 sync   另需:      ARCRUN_TRIGGER_URL（named-webhook 觸發完整 URL）
 direct（無 R2）:  監看資料夾 → 讀檔內容直送實例 rag_ingest_direct workflow；設定走 --config JSON`)

manifest.go

@@ -56,6 +56,27 @@ type ManifestEntry struct {
 	//    真因（Cloudflare「當日免費額度用完」／「這份 PDF 沒有文字層」）**當場消失**
 	//    ⇒ 使用者以為是我們壞掉。原因必須跟著 entry 存活到下次成功為止。
 	LastError string `json:"last_error,omitempty"`
+
+	// ── 雲端對帳（`inkstone/arcrun-rag#140`，2026-08-26）──────────────────────
+	// 病：上面那個 IngestedHash 的章**永遠不會過期**。雲端 08-14 被重裝／清空之後，
+	// 檔案內容沒變 ⇒ 不產生事件 ⇒ 永遠不會重送，而且沒有任何地方會說話。
+	// ⇒ 章的意思要從「我送過了」改成「我送過了**而且雲端現在還有**」，
+	//   後半句只能去問雲端（見 cloud_audit.go）。這三個欄位是那個問答的記帳。
+	//
+	// CloudCheckedAt＝最後一次向雲端確認過這個檔的時間（unix 秒）。
+	// 用途有二：①決定「太久沒對帳」該重問（cloudAuditRecheckInterval）；
+	// ②讓候選排序把最久沒對的排前面 ⇒ 巨量資料夾也會被輪完，不會有人永遠排不到。
+	CloudCheckedAt int64 `json:"cloud_checked_at,omitempty"`
+	// CloudMissingAt＝最後一次「雲端查不到、章被拔掉」的時間（unix 秒，0＝從沒發生）。
+	// 🔴 它同時是**防重送迴圈的閘**：雲端 ingest 非同步，剛送出去那幾秒查不到是正常的，
+	//    沒有這個窗口，對帳下一輪又判它不在 ⇒ 每輪重送 ⇒ 把使用者的 AI 額度燒光
+	//    ⇒ 那就是「把一個 bug 換成另一個」（#140 驗收條件 5 明文禁止）。
+	CloudMissingAt int64 `json:"cloud_missing_at,omitempty"`
+	// NoCloudCard＝這一次 ingest 蓋章時**沒有任何卡片被送上雲**
+	//（萃取判定「無可萃取概念」，cards 為空 ⇒ direct.go 的送卡迴圈一圈都沒跑）。
+	// 🔴 不記這一格的話，對帳每天都會查到「雲端沒有它」⇒ 每天重萃一次、永遠停不下來。
+	//    舊的 manifest 沒有這一格＝當成「送過」，那正是本票要救的那批檔的處境。
+	NoCloudCard bool `json:"no_cloud_card,omitempty"`
 }
 
 // retryBackoff 退避階梯：1m → 5m → 15m → 1h → 6h，之後每次 6h。
@@ -101,6 +122,12 @@ type Manifest struct {
 	// 不在任何一邊的掃描結果裡，下一輪不會再有 renamed 事件把它帶出來。不記住它，
 	// 一次下架失敗（雲端剛好那幾秒掛掉）就永久遺失，舊卡從此不會再被清。
 	PendingTakedowns map[string]string `json:"pending_takedowns,omitempty"`
+
+	// CloudAuditAt＝這個資料夾最後一次跑雲端對帳批次的時間（unix 秒）。
+	// 純節流用（cloudAuditFolderInterval）：daemon 預設 5 秒一輪，沒有這道閘
+	// 就是每 5 秒對雲端發 20 個請求。與 InventoryHash 同為 Manifest 層欄位，
+	// Scan() 的 rebuild 只重建 Entries，天然跨輪存活。
+	CloudAuditAt int64 `json:"cloud_audit_at,omitempty"`
 }
 
 // QueueTakedown 記一筆「這個舊路徑（連同當時的頁名）還沒在雲端下架」的待辦。
@@ -186,6 +213,27 @@ func (m *Manifest) MarkIngestedBy(path, sourceHash string, at int64, extractor s
 	// 成功即清掉失敗狀態（t195）：下次再壞會從第一階退避重新算起。
 	e.FailCount, e.LastFailAt, e.NextRetry = 0, 0, 0
 	e.LastError = ""
+	// #140：預設「這次有送卡上雲」；真的一張卡都沒送的那條路由呼叫端補打
+	// MarkNoCloudCard（見 direct.go 的 cards 為空分支）。預設值放這裡而不是
+	// 讓呼叫端每次都設，是因為漏設的方向要落在**安全的那一邊**：
+	// 誤標 false ⇒ 頂多多對一次帳（一個唯讀請求）；誤標 true ⇒ 這個檔從此
+	// 不再被對帳，雲端掉了也沒人發現——那正是本票在修的病。
+	e.NoCloudCard = false
+	// 🔴 CloudCheckedAt／CloudMissingAt **刻意不清**：
+	//    前者是輪值排序的依據，後者是防重送迴圈的 grace 窗口與「補送過」的證據
+	//    （ResyncSummary 靠 IngestedAt >= CloudMissingAt 判斷這份是不是剛補回來的）。
+	//    清掉等於把剛補送成功的那批檔立刻放回可再拔章的池子。
+	return true
+}
+
+// MarkNoCloudCard 標記「這次 ingest 沒有任何卡片被送上雲端」。
+// 只有萃取判定「無可萃取概念」（cards 為空）的那條路會呼叫。見 NoCloudCard 欄位註解。
+func (m *Manifest) MarkNoCloudCard(path string) bool {
+	e, ok := m.Entries[path]
+	if !ok {
+		return false
+	}
+	e.NoCloudCard = true
 	return true
 }
 

scan.go

@@ -556,6 +556,15 @@ func Scan(root string, m *Manifest, opts ScanOptions) (*TriggerPayload, error) {
 			//   ⇒ 畫面只剩 humanizeFailure 的最後退路「當時沒有記下原因」。
 			//   這正是上面那句警告的第二次實例——真因是我們自己刪掉的，不是沒記。
 			ne.LastError = carry.LastError
+			// 🔴 #140（2026-08-26）：雲端對帳的三個欄位同樣要 carry，而且漏了會**很貴**：
+			//   - CloudCheckedAt 歸零 ⇒ 每輪都判「太久沒對帳」⇒ 每輪重問整批（請求風暴）
+			//   - CloudMissingAt 歸零 ⇒ **防重送迴圈的 grace 消失** ⇒ 補送 → 下一輪又拔章
+			//     → 再補送…把使用者的 AI 額度燒光（票上明文禁止的「把一個 bug 換成另一個」）
+			//   - NoCloudCard 歸零 ⇒ 沒卡可送的檔每天被重萃一次，永遠停不下來
+			//   這正是上面那句警告（t195／LastError 5fcc139）的第三次實例，所以照著它走。
+			ne.CloudCheckedAt = carry.CloudCheckedAt
+			ne.CloudMissingAt = carry.CloudMissingAt
+			ne.NoCloudCard = carry.NoCloudCard
 		}
 		newEntries[p] = ne
 	}

sync_status.go

@@ -52,6 +52,23 @@ type RetiringStatus struct {
 	LastError string `json:"last_error,omitempty"` // 最後一次失敗的真因（原文，不改寫）
 }
 
+// ResyncStatus＝某個監看資料夾的「雲端補送」現況（`inkstone/arcrun-rag#140`）。
+//
+// 🔴 為什麼一定要有畫面：這張票的病不只是「該送的沒送」，還有
+// 「**沒有任何地方會說話**」——使用者看到檔案在資料夾裡、AI 卻查不到，
+// 而且查不出為什麼。所以修法不能靜悄悄地重送：他要看得見
+// 「有 N 份在補送、不是你弄壞的、你不必做任何事」。
+//
+// 與 Retiring／FolderPlans 同族：**每輪照 manifest 現況重算的快照**，
+// 不進 CarryForwardActivity——補完就自然歸零，不必有人去清它。
+type ResyncStatus struct {
+	Pending   int    `json:"pending"`              // 章已拔掉、還沒補送成功的份數
+	Repaired  int    `json:"repaired"`             // 最近一天內已補送成功的份數
+	CheckedAt string `json:"checked_at,omitempty"` // 最近一次對帳時間（RFC3339）
+	Note      string `json:"note,omitempty"`       // 給使用者看的一句人話
+	LastError string `json:"last_error,omitempty"` // 對帳本身失敗的真因（原文，不改寫）
+}
+
 // SyncStatus 彙總每輪同步的萃取結果，持久化至 ~/.arcrun-rag/status.json。
 // 托盤依此決定顯示「已萃 N 檔」、「⚠ 萃取失敗 M 檔」還是「⚠ 萃取引擎未就緒」。
 type SyncStatus struct {
@@ -83,6 +100,10 @@ type SyncStatus struct {
 	// 與 SkippedDocs 同族——每輪照現況重算的快照，不進 CarryForwardActivity。
 	Retiring map[string]RetiringStatus `json:"retiring,omitempty"`
 
+	// `inkstone/arcrun-rag#140`：雲端上找不到、正在自動補送的資料夾（key＝資料夾路徑）。
+	// 與 Retiring 同族的現況快照，見 ResyncStatus 註解。
+	Resync map[string]ResyncStatus `json:"resync,omitempty"`
+
 	// 🔴 G-6.2「不准安靜地略過」（2026-08-06）：副檔名不在 allowedExt 的檔案，
 	// 以前在 scan.go 的白名單閘就 `return nil` 蒸發了——沒事件、沒紀錄、沒畫面。
 	// 使用者丟一份 .doc 進資料夾，得到的回應是**完全的沉默**。