@kienntpixon/dieu-phoi 0.7.4 → 0.7.6

package/lib/wtgc.cjs

@@ -0,0 +1,756 @@
+'use strict';
+// r1 s3 (core 0.7.6): `dieu-phoi wt gc [--repo R | --all-repos] [--yes] [--json] [--no-measure]`.
+// Quét mọi worktree đăng ký trong git của mỗi repo (có dấu hay không), xếp vào lớp, báo dung lượng, và CHỈ khi --yes mới
+// gỡ lớp `safe` (+ vỏ thư mục mồ côi, mục prunable, nhánh tạm đã merge không còn worktree). Dry-run mặc định.
+//
+// Lớp (class):
+//   safe       wtSafety ok: nhánh đang checkout THẬT đã vào một ref bền bất kỳ (mergedAnywhere), sạch, không agent sống,
+//              không khoá thật; có dấu → tuổi ≥ 1 giờ và task đã có verdict pass/accept; không dấu (chỉ tên do wt add sinh /
+//              .claude/worktrees/agent-*) hoặc dấu thiếu verdict → nhàn rỗi > 24 giờ (phụ lục Q1).
+//   keep-slot  slot giữ lại: tên tự đặt, dấu keep:true, có Library/ (Unity), nhánh lane/*, file .dieu-phoi-keep, hoặc khớp
+//              wt_keep trong config. KHÔNG BAO GIỜ tự gỡ (phụ lục Q3).
+//   abandoned  chưa merge nhưng sạch, không agent sống, không khoá, và verdict reject cuối hoặc nhàn rỗi ≥ wt_abandon_days
+//              (14). CHỈ liệt kê ở bước này: lưu tag + gỡ thuộc s4 (`wt gc --abandoned --yes`).
+//   keep       giữ kèm lý do: dirty, agent sống, khoá thật, detached, mới tạo, chưa nhàn rỗi đủ, chưa merge mà chưa bỏ dở...
+//   prunable   thư mục đã mất (git worktree list: prunable) → `git worktree prune`.
+//   shell      thư mục vỏ khớp mẫu tên tạm nhưng không đăng ký, chỉ còn junction/rỗng → removeShell; có file thật → keep.
+//   temp-branch nhánh tạm (dp/*, worktree-agent-*, <prefix>/<id8>) đã merge vào ref bền, không còn worktree → git branch -d.
+// Dung lượng: ước lượng rẻ (lstat, không đi xuyên link/junction, trần thời gian mỗi mục và tổng); quá trần thì "≥ x".
+
+const fs = require('fs');
+const path = require('path');
+const core = require('../hook.cjs');
+const agg = require('./aggregate.cjs');
+const { ctxOf, repoOf } = require('./args.cjs');
+const deps = require('./deps.cjs');
+const repos = require('./repos.cjs');
+const F = require('./wtfast.cjs');
+const W = require('./worktree.cjs');
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const GC_TASK = 'wtgcauto'; // task_id đặt cho sự kiện gỡ worktree không dấu
+const DEFAULT_MANUAL_BUDGET_MS = 55000; // chạy tay (không --auto): dư địa cho đĩa lạnh nhưng vẫn dưới 60 giây
+const DEFAULT_BUDGET_MS = 25000; // ngân sách quét (seed + quét repo; hook cần cả lệnh dưới ~30 giây)
+const DEFAULT_SEED_MS = 10000; // phần ngân sách dành cho seed sổ repo (--all-repos)
+const DEFAULT_MEASURE_MS = 5000; // ngân sách đo dung lượng (toàn lệnh)
+const ITEM_MEASURE_MS = 1500; // trần đo mỗi mục (quá thì báo "≥")
+const ITEM_MEASURE_ENTRIES = 150000;
+const REPO_GIT_PER_WT_MS = 1000; // --all-repos: cộng thêm cho mỗi worktree liên kết
+const REPO_GIT_MAX_MS = 18000; // trần cứng mỗi repo (--all-repos): repo lớn như isle làm dần qua các lần chạy nhờ bộ nhớ đệm, không ăn hết ngân sách 30 giây
+const REPO_GIT_MS = 6000; // trần thời gian cho MỖI repo (repo lạnh/chậm: phần còn lại của repo đó để lần sau)
+const PREFETCH_CONC = 8; // số `git status` chạy song song trong tiền quét
+const PREFETCH_CALL_MS = 30000; // trần mỗi `git status` của tiền quét (đĩa lạnh)
+const GIT_CALL_MS = 4000; // trần mỗi lệnh git trong quét (repo git treo/chậm thì bỏ qua mục đó, không kéo cả lệnh)
+const GC_SCANNED = 'gc-scanned.json'; // repo -> ts lần quét xong gần nhất: lần sau quét repo cũ nhất trước (ngân sách cắt thì lần sau làm tiếp)
+const WT_CACHE = 'wt-gc-cache.json'; // bộ nhớ đệm bền: mỗi worktree -> { head, dirMs, dirty: {v,ts}, newest: {v,ts}, incomplete: {ts} }
+// BẤT BIẾN AN TOÀN: đệm chỉ được rút ngắn kết quả ÂM (keep / idle-unknown). Không bao giờ dùng đệm để kết luận "sạch" hay "nhàn rỗi":
+// một mục chỉ thành safe/abandoned sau git status + duyệt mtime + kiểm agent sống TƯƠI trong chính lượt quét (xem freshCheck).
+const WT_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // quá hạn thì tính lại (chặn đệm cũ ngầm quá lâu); đường gỡ (--yes) luôn kiểm lại, không dùng đệm
+const SCAN_WALK_CAP = 20000; // quét: trần số mục duyệt mtime mỗi worktree (hết trần = nhàn rỗi không biết = giữ; duyệt xong thì được đệm nên chỉ tốn một lần)
+const SCAN_WALK_MS = 8000;
+const REMOVE_WALK_CAP = 60000; // đường gỡ --yes: duyệt kỹ hơn
+const REMOVE_WALK_MS = 10000;
+const DEFAULT_ABANDON_DAYS = 14;
+const GC_LAST = 'gc-last.json';
+const GC_LOG = 'gc-log.jsonl'; // r1 s5: mỗi lần gc tự động (verdict / hook / đĩa) một dòng
+const GC_TOTALS = 'gc-totals.json'; // r1 s5: số liệu lớp cần duyệt của lần gc nền gần nhất (hook đọc để in cảnh báo thiếu đĩa)
+// Lớp mà gc tự động được phép đụng. abandoned / keep-slot / keep KHÔNG BAO GIỜ nằm trong đây: dù nhánh gỡ sau này (0.7.7) thêm lớp abandoned, đường tự động vẫn bị chặn ở đây.
+const AUTO_CLASSES = new Set(['safe', 'shell', 'prunable', 'temp-branch']);
+const SEED_MAX_AGE_MS = 30 * 60 * 1000; // --all-repos: seed lại (sự kiện, run dir, thư mục cha) nếu lần seed trước cũ hơn 30 phút
+
+const nrm = (p) => W.realKey(p);
+
+// ---- đo dung lượng ----
+
+/** Tổng byte (kích thước logic) dưới `dir`, không đi xuyên symlink/junction, dừng khi hết `ms`. { bytes, approx }. */
+function measureDir(dir, ms, maxEntries) {
+  const end = Date.now() + ms;
+  let bytes = 0;
+  let seen = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    let ents;
+    try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; }
+    for (const e of ents) {
+      const p = path.join(d, e.name);
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (deps.isLink(p)) continue; // junction Windows
+        stack.push(p);
+        continue;
+      }
+      try { bytes += fs.lstatSync(p).size; } catch (_) { /* file vừa mất */ }
+      if ((++seen & 255) === 0 && (Date.now() > end || seen > (maxEntries || ITEM_MEASURE_ENTRIES))) return { bytes, approx: true };
+    }
+    if (Date.now() > end) return { bytes, approx: true };
+  }
+  return { bytes, approx: false };
+}
+
+function fmtBytes(n) {
+  if (!Number.isFinite(n)) return '?';
+  if (n >= 1073741824) return `${(n / 1073741824).toFixed(1)} GB`;
+  if (n >= 1048576) return `${Math.round(n / 1048576)} MB`;
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+  return `${n} B`;
+}
+const sizeStr = (it) => (it.bytes === null || it.bytes === undefined ? '-' : `${it.approx ? '≥ ' : ''}${fmtBytes(it.bytes)}${it.approx ? ' (đo một phần)' : ''}`);
+
+// ---- cấu hình ----
+
+/** wt_keep: mảng hoặc chuỗi phân tách bằng dấu phẩy/chấm phẩy; mỗi mẫu là đường dẫn đầy đủ, tên thư mục, hoặc glob có `*`. */
+function keepPatterns(ctx) {
+  const raw = process.env.DIEU_PHOI_WT_KEEP !== undefined && process.env.DIEU_PHOI_WT_KEEP !== ''
+    ? process.env.DIEU_PHOI_WT_KEEP : ctx && ctx.config ? ctx.config.wt_keep : null;
+  if (!raw) return [];
+  const list = Array.isArray(raw) ? raw : String(raw).split(/[;,]/);
+  return list.map((s) => String(s).trim()).filter(Boolean).map((s) => {
+    const re = new RegExp(`^${s.replace(/\\/g, '/').replace(/[.+?^${}()|[\]]/g, '\\$&').replace(/\*/g, '.*')}$`, process.platform === 'win32' ? 'i' : '');
+    return re;
+  });
+}
+
+function matchesKeep(pats, wtPath) {
+  const full = String(wtPath).replace(/\\/g, '/').replace(/\/+$/, '');
+  const base = full.slice(full.lastIndexOf('/') + 1);
+  return pats.some((re) => re.test(full) || re.test(base));
+}
+
+/** Lý do slot giữ lại (chuỗi) hoặc null. Gồm các điều kiện Q3 của s1 + Library/, lane/*, .dieu-phoi-keep, wt_keep. */
+function slotReason(main, w, mark, pats) {
+  const s1 = W.keepSlotReason(main, w.path, mark);
+  if (s1) return s1;
+  if (matchesKeep(pats, w.path)) return 'khớp wt_keep trong config';
+  if (w.branch && w.branch.startsWith('lane/')) return `nhánh ${w.branch} (lane/*) là slot giữ lại`;
+  try { if (fs.statSync(path.join(w.path, 'Library')).isDirectory()) return 'có thư mục Library/ (Unity) — slot giữ lại'; } catch (_) { /* không có */ }
+  if (fs.existsSync(path.join(w.path, '.dieu-phoi-keep'))) return 'có file .dieu-phoi-keep';
+  return null;
+}
+
+// ---- quét một repo ----
+
+function verdictIndex(events) {
+  const last = new Map();
+  const discarded = new Set();
+  for (const e of events) {
+    if (!e || typeof e.task_id !== 'string') continue;
+    if (e.kind === 'verdict') last.set(e.task_id, agg.normalizeVerdict(e).outcome);
+    else if (e.kind === 'discard') discarded.add(e.task_id);
+  }
+  return { last, discarded };
+}
+
+function listHeads(main) {
+  const r = W.gitRun(main, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+  return r.ok ? r.out.split(/\r?\n/).filter(Boolean) : [];
+}
+
+/** Vỏ thư mục khớp mẫu tên tạm nhưng không đăng ký trong git. */
+function orphanShells(main, regKeys) {
+  const out = [];
+  const consider = (dir, re) => {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch (_) { return; }
+    for (const n of names) {
+      if (!re.test(n)) continue;
+      const p = path.join(dir, n);
+      if (regKeys.has(nrm(p))) continue;
+      try { if (!fs.lstatSync(p).isDirectory()) continue; } catch (_) { continue; }
+      out.push(p);
+    }
+  };
+  const mainBase = path.basename(main).replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  consider(path.dirname(main), new RegExp(`^${mainBase}-wt-[a-z0-9]{8}$`, process.platform === 'win32' ? 'i' : ''));
+  consider(path.join(main, '.claude', 'worktrees'), /^agent-/);
+  return out;
+}
+
+/** Vỏ chỉ còn junction/thư mục rỗng (đệ quy) thì xoá được; có file thật → false. */
+function shellIsEmptyish(dir) {
+  if (deps.isLink(dir)) return true;
+  let ents;
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return false; }
+  for (const e of ents) {
+    const p = path.join(dir, e.name);
+    if (e.isSymbolicLink() || deps.isLink(p)) continue;
+    if (e.isDirectory()) { if (!shellIsEmptyish(p)) return false; continue; }
+    return false;
+  }
+  return true;
+}
+
+function loadWtCache(ctx) {
+  try { const j = JSON.parse(fs.readFileSync(path.join(ctx.paths.data, WT_CACHE), 'utf8')); return j && j.wts ? j : { wts: {} }; } catch (_) { return { wts: {} }; }
+}
+function saveWtCache(ctx, cache) {
+  const keep = {};
+  const now = Date.now();
+  for (const [k, v] of Object.entries(cache.wts || {})) if (v && now - Math.max((v.dirty && v.dirty.ts) || 0, (v.newest && v.newest.ts) || 0, (v.incomplete && v.incomplete.ts) || 0) < 7 * WT_CACHE_TTL_MS) keep[k] = v;
+  try { fs.writeFileSync(path.join(ctx.paths.data, WT_CACHE), JSON.stringify({ version: 1, wts: keep })); } catch (_) { /* best effort */ }
+}
+/** Đệm còn hiệu lực của worktree (HEAD sha và mtime thư mục worktree không đổi, chưa quá hạn): { dirty?: true, newest?: number|null, incomplete?: true } hoặc null.
+ * Chỉ dùng để ra kết quả ÂM nhanh (bẩn / mới hoạt động / không biết nhàn rỗi = giữ); kết quả dương luôn được kiểm lại tươi. */
+function cacheOf(st, key, head, dirMs) {
+  const e = st.wtCache && st.wtCache.wts[key];
+  if (!e || !head || e.head !== head || e.dirMs !== dirMs) return null;
+  const fresh = (f) => f && Date.now() - f.ts < WT_CACHE_TTL_MS;
+  const out = {};
+  if (fresh(e.dirty) && e.dirty.v === true) out.dirty = true;
+  if (fresh(e.newest) && e.newest.v !== undefined) out.newest = e.newest.v;
+  else if (fresh(e.incomplete)) out.incomplete = true; // lần trước duyệt hết trần của MỘT worktree: không thử lại trong hạn đệm (nhàn rỗi vẫn không biết = giữ)
+  return out.dirty === undefined && out.newest === undefined && !out.incomplete ? null : out;
+}
+
+/** sf có thể cho kết quả dương (safe hoặc abandoned) không. */
+function positiveOf(sf, w, gone, abandonMs) {
+  if (sf.ok) return true;
+  return !sf.merged && sf.dirty === false && !sf.live && !sf.lock && !sf.idle_unknown && !!w.branch && !w.detached
+    && (gone || (sf.idle_ms !== null && sf.idle_ms >= abandonMs));
+}
+/** sf đến từ kiểm tươi đầy đủ: git status thật cho kết quả sạch và duyệt mtime đầy đủ thật (không đệm, không bị cắt). */
+function freshCheck(sf) {
+  return sf.dirty === false && !sf.dirty_cached && !sf.dirty_skipped && !!sf.walk && sf.walk.complete === true && sf.walk.cached !== true;
+}
+
+/** Quét một repo → { repo, items, error }. Chỉ đọc. `st` = { deadline, events, idx } dùng chung. */
+function scanRepo(ctx, repoDir, st) {
+  const res = { repo: repoDir, main: null, items: [], error: null };
+  let info;
+  try { info = F.mainOf(repoDir); } catch (e) { res.error = e.message; return res; }
+  const { main, common } = info;
+  res.main = main;
+  // Đọc sổ worktree và tên nhánh từ .git (không gọi git); chỉ gọi git khi repo có worktree liên kết hoặc nhánh tạm.
+  let reg;
+  try { reg = F.registeredFs(main, common); } catch (e) { res.error = e.message; return res; }
+  // --all-repos: trần mỗi repo tăng theo số worktree liên kết (repo nhiều worktree như isle cần ~1 giây/worktree trên đĩa lạnh).
+  if (st.allRepos && st.repoStart) {
+    st.repoDeadline = Math.min(st.deadline, st.repoStart + Math.min(REPO_GIT_MAX_MS, REPO_GIT_MS + REPO_GIT_PER_WT_MS * reg.length));
+    W.setGitDeadline(st.repoDeadline, GIT_CALL_MS);
+  }
+  const tempNames = F.localHeadNames(common).filter((b) => W.isTempBranch(b));
+  // Repo không có worktree liên kết và không có nhánh tạm: không có gì để phân lớp ngoài thư mục vỏ mồ côi -> bỏ sớm, O(1).
+  if (reg.length <= 1 && !tempNames.length) {
+    for (const p of orphanShells(main, new Set(reg.map((r) => nrm(r.path))))) {
+      const ok = shellIsEmptyish(p);
+      res.items.push({
+        repo: main, path: p, branch: null, class: ok ? 'shell' : 'keep', marked: false, task_id: null, bytes: null, approx: false, idle_days: null,
+        merged_into: [], why: ok ? 'thư mục vỏ không đăng ký, chỉ còn junction/rỗng' : 'thư mục không đăng ký nhưng còn file thật: chỉ báo, xoá tay',
+      });
+    }
+    return res;
+  }
+  let facts = null;
+  const factsOf = () => { if (!facts) facts = F.makeFacts(main, reg); return facts; };
+  const marks = new Map();
+  for (const m of W.markedWorktrees(common)) if (m.path) marks.set(nrm(m.path), m);
+  const pats = keepPatterns(ctx);
+  const abandonMs = W.numSetting(ctx, 'DIEU_PHOI_WT_ABANDON_DAYS', 'wt_abandon_days', DEFAULT_ABANDON_DAYS) * DAY_MS;
+  const regKeys = new Set(reg.map((r) => nrm(r.path)));
+  const checkedOut = new Set(reg.map((r) => r.branch).filter(Boolean));
+  const walkCap = W.numSetting(ctx, 'DIEU_PHOI_WT_WALK_CAP', 'wt_walk_cap', SCAN_WALK_CAP);
+  const walkMs = W.numSetting(ctx, 'DIEU_PHOI_WT_WALK_MS', 'wt_walk_ms', SCAN_WALK_MS);
+  const dirMsOf = (p) => { try { return fs.statSync(p).mtimeMs; } catch (_) { return null; } };
+  const cacheFor = (w) => (st.wtCache && w.branch && !w.detached ? cacheOf(st, nrm(w.path), factsOf().shaOf(w.branch), dirMsOf(w.path)) : null);
+
+  // Tiền quét song song `git status` cho ứng viên có thể thành safe/abandoned (chỉ tín hiệu git rẻ: tuổi commit cuối là cận trên
+  // của nhàn rỗi, nên commit chưa đủ cũ thì chắc chắn không phải ứng viên). Việc còn lại của wtSafety vẫn đồng bộ.
+  try {
+    const cand = [];
+    for (const w of reg) {
+      if (nrm(w.path) === nrm(main) || w.prunable || !w.branch || w.detached || (w.locked !== null && w.locked !== undefined)) continue;
+      if (!fs.existsSync(w.path) || slotReason(main, w, marks.get(nrm(w.path)) || null, pats)) continue;
+      const cm = factsOf().commitMs(w.branch);
+      if (cm === null || cm === undefined) continue;
+      const base = Date.now() - cm;
+      if (base >= (factsOf().mergedOf(w.branch).merged ? HOUR_MS : abandonMs)) { const c = cacheFor(w); if (!(c && c.dirty === true)) cand.push(w.path); }
+    }
+    if (cand.length > 1) W.prefetchDirty(cand, { deadline: Math.min(st.deadline, st.repoDeadline || Infinity), concurrency: PREFETCH_CONC, callMs: PREFETCH_CALL_MS });
+  } catch (_) { /* tiền quét chỉ là tối ưu */ }
+
+  for (const w of reg) {
+    if (nrm(w.path) === nrm(main)) continue;
+    const mark = marks.get(nrm(w.path)) || null;
+    const item = {
+      repo: main, path: w.path, branch: w.branch || null, class: 'keep', why: null, marked: !!mark,
+      task_id: mark ? mark.task_id : null, bytes: null, approx: false, idle_days: null, merged_into: [], _w: w, _mark: mark,
+    };
+    res.items.push(item);
+    if (w.prunable || !fs.existsSync(w.path)) {
+      item.class = w.locked !== null && w.locked !== undefined ? 'keep' : 'prunable';
+      item.why = item.class === 'prunable' ? 'thư mục đã mất (git worktree prune)' : 'thư mục mất nhưng đang khoá';
+      continue;
+    }
+    const slot = slotReason(main, w, mark, pats);
+    if (slot) { item.class = 'keep-slot'; item.why = slot; continue; }
+    if (Date.now() > st.deadline || Date.now() > (st.repoDeadline || Infinity)) { item.why = 'chưa quét kịp (hết ngân sách thời gian), lần sau'; continue; }
+    // `git status` đắt (repo Unity: hàng chục giây): chỉ chạy khi nó còn đổi được phân lớp (ứng viên safe hoặc abandoned).
+    const gone = mark && (st.idx.discarded.has(mark.task_id) || st.idx.last.get(mark.task_id) === 'reject');
+    const minIdle = mark ? 0 : DAY_MS;
+    const sopts = {
+      reg, walkCap, walkMs, cache: cacheFor(w) || undefined,
+      // duyệt file chỉ khi còn đổi được phân lớp: đã merge và cận trên ≥ 1 giờ, hoặc chưa merge và cận trên ≥ ngưỡng bỏ dở.
+      // (không dấu cần nhàn rỗi ≥ 24 giờ nên commit mới hơn 24 giờ thì khỏi duyệt: idle ≤ tuổi commit)
+      walkIdleIf: (base, m) => base !== null && base >= (m && m.merged ? (mark ? HOUR_MS : DAY_MS) : abandonMs),
+      mergedOf: (b) => factsOf().mergedOf(b),
+      commitMsOf: (b) => factsOf().commitMs(b),
+      dirtyNeeded: (r, m) => !r.live && !(r.lock && !r.lock.stale) && !w.detached && !!w.branch
+        && ((m.merged && (minIdle === 0 || (r.idle_ms !== null && r.idle_ms >= minIdle)))
+          || (!m.merged && (gone || (r.idle_ms !== null && r.idle_ms >= abandonMs)))),
+    };
+    let sf = mark ? W.safetyOfMarked(ctx, main, mark, sopts, reg) : W.wtSafety(ctx, main, w, sopts);
+    // Lô chỉ thấy vài nhánh bền: nếu có vẻ bỏ dở mà lô nói "chưa merge", hỏi lại đầy đủ (git contains) trước khi gán nhãn.
+    if (!sf.merged && w.branch && !w.detached && sf.idle_ms !== null && sf.idle_ms >= abandonMs && W.mergedAnywhere(main, w.branch, reg).merged) {
+      const full = { reg, walkCap, walkMs, cache: sopts.cache, walkIdleIf: sopts.walkIdleIf, dirtyNeeded: sopts.dirtyNeeded, commitMsOf: sopts.commitMsOf };
+      sf = mark ? W.safetyOfMarked(ctx, main, mark, full, reg) : W.wtSafety(ctx, main, w, full);
+    }
+    // Bất biến: kết quả dương (safe hoặc abandoned) chỉ được nhận sau kiểm TƯƠI trong lượt này: git status thật (không đệm),
+    // duyệt mtime đầy đủ thật (không đệm, không bỏ qua), agent sống kiểm lại. Chưa đủ thì kiểm lại tươi; không xong trong trần -> idle-unknown = keep.
+    if (positiveOf(sf, w, gone, abandonMs) && !freshCheck(sf)) {
+      const fresh = { reg, walkCap, walkMs, mergedOf: sopts.mergedOf, commitMsOf: sopts.commitMsOf };
+      sf = mark ? W.safetyOfMarked(ctx, main, mark, fresh, reg) : W.wtSafety(ctx, main, w, fresh);
+      sf.rechecked_fresh = true;
+    }
+    item.branch = sf.branch_now || item.branch;
+    item.merged_into = sf.merged_into || [];
+    item.idle_days = sf.idle_ms === null || sf.idle_ms === undefined ? null : Math.floor(sf.idle_ms / DAY_MS);
+    item._sf = sf;
+    if (st.wtCache && w.branch && !w.detached) {
+      const key = nrm(w.path);
+      const head = factsOf().shaOf(w.branch);
+      const dirMs = dirMsOf(w.path);
+      const prev = st.wtCache.wts[key];
+      const same = prev && prev.head === head && prev.dirMs === dirMs;
+      const e = same ? prev : { head, dirMs };
+      const now = Date.now();
+      if (!same) { delete e.clean; delete e.dirty; delete e.newest; delete e.incomplete; }
+      delete e.clean; // định dạng cũ: "sạch" từng được đệm, nay không bao giờ tin
+      if (sf.dirty === true && !sf.dirty_cached) e.dirty = { v: true, ts: now };
+      else if (sf.dirty === false) delete e.dirty;
+      if (sf.walk && sf.walk.complete && !sf.walk.cached) { e.newest = { v: sf.walk.newest, ts: now }; delete e.incomplete; }
+      else if (sf.walk && !sf.walk.complete && !sf.walk.cached && now <= (st.repoDeadline || st.deadline)) e.incomplete = { ts: now }; // trần của worktree này, không phải hạn chót chung
+      if (head && dirMs !== null && (e.dirty || e.newest || e.incomplete)) st.wtCache.wts[key] = e;
+    }
+    if (sf.ok) {
+      item.class = 'safe';
+      item.why = `đã vào ${sf.merged_into.slice(0, 3).join(', ')}; sạch; nhàn rỗi ${sf.idle_ms === null ? '?' : Math.floor(sf.idle_ms / HOUR_MS)} giờ`;
+      if (mark) {
+        const v = st.idx.last.get(mark.task_id);
+        const age = W.ageMsOf(mark);
+        if (age < W.MERGED_MIN_AGE_MS) { item.class = 'keep'; item.why = 'mới tạo dưới 1 giờ'; }
+        else if (v === undefined || W.NOT_DONE.has(v)) {
+          // thiếu verdict pass/accept: coi như không dấu (cần nhàn rỗi > 24 giờ).
+          if (sf.idle_ms === null || sf.idle_ms < DAY_MS) {
+            item.class = 'keep';
+            item.why = `${v === undefined ? 'chưa có verdict' : `verdict ${v}`} và chưa nhàn rỗi đủ 24 giờ`;
+          }
+        }
+      }
+      continue;
+    }
+    item.why = sf.why;
+    // abandoned: chưa merge, sạch (kiểm tươi), không agent sống, không khoá, có nhánh, nhàn rỗi biết được.
+    if (positiveOf(sf, w, gone, abandonMs) && !sf.merged && freshCheck(sf)) {
+      item.class = 'abandoned';
+      item.why = `nhánh ${w.branch} chưa vào nhánh bền nào; sạch; ${gone ? 'task bị loại/discard' : `nhàn rỗi ≥ ${Math.round(abandonMs / DAY_MS)} ngày`} (s4: tag dp-archive rồi gỡ, cần duyệt)`;
+    }
+  }
+
+  for (const p of orphanShells(main, regKeys)) {
+    const ok = shellIsEmptyish(p);
+    res.items.push({
+      repo: main, path: p, branch: null, class: ok ? 'shell' : 'keep', marked: false, task_id: null, bytes: null, approx: false, idle_days: null,
+      merged_into: [], why: ok ? 'thư mục vỏ không đăng ký, chỉ còn junction/rỗng' : 'thư mục không đăng ký nhưng còn file thật: chỉ báo, xoá tay',
+    });
+  }
+
+  // Nhánh tạm đã merge, không còn worktree nào checkout.
+  for (const b of tempNames) {
+    if (checkedOut.has(b)) continue;
+    if (Date.now() > st.deadline || Date.now() > (st.repoDeadline || Infinity)) break;
+    const m = factsOf().mergedOf(b);
+    if (!m.merged) continue;
+    res.items.push({
+      repo: main, path: null, branch: b, class: 'temp-branch', marked: false, task_id: null, bytes: 0, approx: false, idle_days: null,
+      merged_into: m.into, why: `nhánh tạm đã vào ${m.into.slice(0, 3).join(', ')}, không còn worktree`,
+    });
+  }
+  return res;
+}
+
+// ---- gỡ ----
+
+const RM_OPTS = { walkCap: REMOVE_WALK_CAP, walkMs: REMOVE_WALK_MS }; // gỡ thật: kiểm lại từ đầu (không dùng bộ nhớ đệm), duyệt file kỹ hơn
+
+/** Gỡ một worktree `safe`: kiểm lại wtSafety, mở khoá mồ côi, gỡ junction trước, git worktree remove (không --force). */
+function removeSafe(ctx, main, it, st) {
+  const w = it._w;
+  const reg = W.registeredOf(main);
+  const e = W.registeredEntry(main, w.path, reg);
+  if (!e) return { removed: false, msg: `giữ ${w.path}: không còn đăng ký trong git` };
+  const s = it._mark ? W.safetyOfMarked(ctx, main, it._mark, RM_OPTS, reg) : W.wtSafety(ctx, main, e, RM_OPTS);
+  if (!s.ok) return { removed: false, msg: `giữ ${w.path}: ${s.why}` };
+  if (s.lock && s.lock.stale) {
+    const u = W.gitRun(main, ['worktree', 'unlock', w.path]);
+    if (!u.ok) return { removed: false, msg: `giữ ${w.path}: không mở được khoá mồ côi (${u.err || 'không rõ'})` };
+  }
+  const depPath = it._mark && it._mark.deps_path ? it._mark.deps_path : '.';
+  let links;
+  try { links = deps.unlinkDepLinks(w.path, [depPath]); } catch (err) {
+    return { removed: false, msg: `giữ ${w.path}: không gỡ được junction node_modules (${err.message}); không gỡ để tránh xoá xuyên junction` };
+  }
+  const r = W.gitRun(main, ['worktree', 'remove', w.path]);
+  if (!r.ok) { deps.relink(links); return { removed: false, msg: `giữ ${w.path}: git worktree remove lỗi (${r.err || 'không rõ'})` }; }
+  let tail = '';
+  if (fs.existsSync(w.path) || deps.isLink(w.path)) {
+    try { deps.removeShell(w.path); } catch (err) { tail = `; còn vỏ thư mục chưa xoá được (${err.message})`; }
+  }
+  W.recordWt(ctx, it.task_id || GC_TASK, { action: 'remove', path: w.path, repo: main, reason: 'gc-safe', trigger: st.trigger || undefined });
+  // `git branch -d` CHỈ cho nhánh tạm (tự từ chối nếu chưa merge vào HEAD/upstream).
+  const names = new Set([s.branch_now, it._mark && it._mark.branch].filter(Boolean));
+  const msgs = [];
+  for (const b of names) {
+    if (!W.isTempBranch(b)) continue;
+    if (!W.mergedAnywhere(main, b).merged) { msgs.push(`giữ nhánh ${b}: chưa vào nhánh bền nào`); continue; }
+    const d = W.gitRun(main, ['branch', '-d', b]);
+    if (d.ok) noteBranch(ctx, main, st, it.task_id, b, 'gc-safe');
+    msgs.push(d.ok ? `đã xoá nhánh ${b}` : `giữ nhánh ${b}: git branch -d từ chối (${(d.err || 'không rõ').split(/\r?\n/)[0]})`);
+  }
+  return { removed: true, msg: `đã gỡ ${w.path}${msgs.length ? `; ${msgs.join('; ')}` : ''}${tail}` };
+}
+
+/** Mỗi lần gỡ tự động là một sự kiện riêng (action khác add/remove để không nhiễu reposOfTask); tên nhánh vào tóm tắt wt_gc_auto. */
+function noteWt(ctx, st, taskId, ev) {
+  if (st.auto !== true) return;
+  try { W.recordWt(ctx, taskId || GC_TASK, Object.assign({}, ev, { trigger: st.trigger || undefined })); } catch (_) { /* sự kiện: best effort */ }
+}
+
+function noteBranch(ctx, main, st, taskId, branch, reason) {
+  if (st.auto !== true) return;
+  st.removedBranches.push(branch);
+  noteWt(ctx, st, taskId, { action: 'branch-delete', branch, repo: main, reason });
+}
+
+function applyRepo(ctx, rr0, st) {
+  const lines = [];
+  let removed = 0;
+  const main = rr0.main;
+  // verdict: chỉ lớp safe (worktree + nhánh đã merge); worktree của task vừa nghiệm thu mà chưa merge giữ nguyên cả cây lẫn nhánh
+  const allowedAuto = st.trigger === 'verdict' ? new Set(['safe']) : AUTO_CLASSES;
+  const rr = st.auto === true ?Object.assign({}, rr0, { items: rr0.items.filter((i) => allowedAuto.has(i.class)) }) : rr0; // tự động: chỉ lớp safe
+  for (const it of rr.items) {
+    if (st.shouldStop()) break;
+    if (it.class === 'safe') {
+      const r = removeSafe(ctx, main, it, st);
+      lines.push(r.msg);
+      it.done = r.removed;
+      if (r.removed) { removed++; st.reclaimed += it.bytes || 0; }
+    } else if (it.class === 'shell') {
+      try { deps.removeShell(it.path); it.done = true; removed++; lines.push(`đã xoá vỏ ${it.path}`); noteWt(ctx, st, null, { action: 'remove-shell', path: it.path, repo: main, reason: 'gc-shell' }); } catch (e) { lines.push(`giữ vỏ ${it.path}: ${e.message}`); }
+    }
+  }
+  if (rr.items.some((i) => i.class === 'prunable')) {
+    const r = W.gitRun(main, ['worktree', 'prune']);
+    for (const i of rr.items) {
+      if (i.class !== 'prunable') continue;
+      i.done = r.ok;
+      if (r.ok) { removed++; noteWt(ctx, st, null, { action: 'prune', path: i.path, repo: main, reason: 'gc-prune' }); }
+    }
+    lines.push(r.ok ? 'đã git worktree prune (mục có thư mục mất)' : `git worktree prune lỗi: ${r.err}`);
+  }
+  // Nhánh tạm: tính lại sau khi gỡ worktree (nhánh vừa mở khoá khỏi worktree có thể -d được).
+  const still = new Set(W.registeredOf(main).map((r) => r.branch).filter(Boolean));
+  for (const it of rr.items.filter((i) => i.class === 'temp-branch')) {
+    if (still.has(it.branch)) continue;
+    if (!W.mergedAnywhere(main, it.branch).merged) continue;
+    const d = W.gitRun(main, ['branch', '-d', it.branch]);
+    it.done = d.ok;
+    if (d.ok) { removed++; noteBranch(ctx, main, st, null, it.branch, 'gc-temp-branch'); }
+    lines.push(d.ok ? `đã xoá nhánh tạm ${it.branch}` : `giữ nhánh ${it.branch}: git branch -d từ chối (${(d.err || 'không rõ').split(/\r?\n/)[0]})`);
+  }
+  return { lines, removed };
+}
+
+// ---- lệnh ----
+
+/** Repo không có worktree liên kết lẫn nhánh tạm không cần git: quét trước (tức thì); repo cần git sau, theo thứ tự đã sắp. */
+function needGitLast(dirs, limitMs) {
+  const cheap = [];
+  const dear = [];
+  const end = Date.now() + (limitMs || 3000);
+  for (const d of dirs) {
+    let need = true;
+    if (Date.now() > end) { cheap.push(d); continue; } // hết thời gian sắp xếp: phần còn lại giữ thứ tự cũ
+    try {
+      const i = F.mainOf(d);
+      need = F.registeredFs(i.main, i.common).length > 1 || F.localHeadNames(i.common).some((b) => W.isTempBranch(b));
+    } catch (_) { need = false; }
+    (need ? dear : cheap).push(d);
+  }
+  return cheap.concat(dear);
+}
+
+function readScanned(ctx) {
+  try { return JSON.parse(fs.readFileSync(path.join(ctx.paths.data, GC_SCANNED), 'utf8')) || {}; } catch (_) { return {}; }
+}
+
+function reposToScan(ctx, opts, t0, seedMs, sink) {
+  if (Array.isArray(opts.repoDirs)) return opts.repoDirs.slice(); // verdict accept: chỉ repo của các task vừa nghiệm thu
+  if (opts['all-repos'] === true) {
+    try {
+      const r = repos.autoSeedIfStale(ctx.paths.data, {
+        eventsFile: ctx.paths.events, runsDir: core.runsDir(), maxAgeMs: SEED_MAX_AGE_MS, deadline: t0 + seedMs,
+      });
+      sink.seed = r;
+    } catch (e) { sink.seed = { seeded: false, error: e.message }; }
+    const seen = readScanned(ctx);
+    sink.scanned = seen;
+    // repo chưa quét / quét lâu nhất trước; cùng mức thì theo thứ tự gần đây của sổ repo.
+    return repos.listRepos(ctx.paths.data).map((r, i) => { const v = seen[r.path]; return { p: r.path, i, t: v && typeof v === 'object' ? Number(v.ts) || 0 : Number(v) || 0, c: v && typeof v === 'object' ? Number(v.ms) || 0 : 0 }; })
+      .sort((x, y) => x.t - y.t || x.c - y.c || x.i - y.i).map((x) => x.p);
+  }
+  return [repoOf(opts)];
+}
+
+function render(rep) {
+  const out = [];
+  const mode = rep.mode === 'apply' ? 'đã thực hiện' : 'dry-run';
+  out.push(`wt gc (${mode}): ${rep.repos.length} repo, ${rep.counts.safe} safe, ${rep.counts['keep-slot']} keep-slot, ${rep.counts.abandoned} abandoned, ${rep.counts.keep} keep`
+    + `${rep.counts.prunable ? `, ${rep.counts.prunable} prunable` : ''}${rep.counts.shell ? `, ${rep.counts.shell} vỏ` : ''}${rep.counts['temp-branch'] ? `, ${rep.counts['temp-branch']} nhánh tạm` : ''}`
+    + ` — ${rep.elapsed_ms} ms${rep.truncated ? ' (quét bị cắt theo ngân sách)' : ''}`);
+  if (rep.errors && rep.errors.length) out.push(`LỖI: ${rep.errors.join('; ')} (phần dưới là kết quả quét được trước khi lỗi)`);
+  if (rep.timing) {
+    const sd = rep.seed;
+    const ph = sd && sd.phases ? `; pha seed: ${Object.keys(sd.phases).map((k) => `${k}=${sd.phases[k]}ms`).join(' ')}` : '';
+    const cut = sd && sd.skipped && sd.skipped.length ? `; seed bị cắt, bỏ pha: ${sd.skipped.join(', ')}` : '';
+    out.push(`thời gian: seed ${rep.timing.seed_ms} ms, quét ${rep.timing.scan_ms} ms, đo dung lượng ${rep.timing.measure_ms} ms${cut}${ph}`);
+  }
+  const unscanned = rep.repos.filter((r) => !r.main && r.error).length;
+  if (rep.truncated) out.push(`CẮT THEO NGÂN SÁCH: ${unscanned} repo chưa quét kịp (lần sau quét repo cũ nhất trước); chỉnh wt_gc_budget_ms hoặc --budget-ms nếu cần.`);
+  for (const r of rep.repos) {
+    out.push(`\n${r.repo}${r.error ? `  [lỗi: ${r.error}]` : ''}`);
+    for (const it of r.items) {
+      const tag = it.done === true ? `${it.class}*` : it.class;
+      out.push(`  ${tag.padEnd(12)} ${String(sizeStr(it)).padStart(9)}  ${it.path || `(nhánh ${it.branch})`}${it.path && it.branch ? `  [${it.branch}]` : ''}  — ${it.why}`);
+    }
+    for (const l of r.applied || []) out.push(`  > ${l}`);
+  }
+  const t = rep.totals;
+  const lb = (n) => `≥ ${fmtBytes(n)} (đo một phần)`; // đo có hộp thời gian/số mục: luôn là cận dưới, không bao giờ là con số chính xác
+  out.push(`\nThu hồi được ngay (safe): ${lb(t.safe_bytes)}; bỏ dở cần duyệt (abandoned): ${lb(t.abandoned_bytes)}; slot giữ lại (không đụng): ${lb(t.keep_slot_bytes)}`);
+  if (rep.mode === 'apply') out.push(`Đã gỡ ${rep.removed} mục, giải phóng ~${fmtBytes(rep.reclaimed_bytes)}.`);
+  else if (rep.counts.safe + rep.counts.shell + rep.counts.prunable + rep.counts['temp-branch'] > 0) out.push('Dry-run: chưa xoá gì. Chạy lại với --yes để gỡ lớp safe (không đụng keep-slot / abandoned / keep).');
+  return out.join('\n');
+}
+
+/** Lõi: quét (và gỡ nếu apply) → báo cáo cấu trúc. Dùng chung cho CLI và hook (--auto). */
+function runGc(ctx, opts) {
+  const t0 = Date.now();
+  const o = opts || {};
+  const budget = Number.isFinite(Number(o['budget-ms'])) && o['budget-ms'] !== true ? Number(o['budget-ms'])
+    : W.numSetting(ctx, 'DIEU_PHOI_WT_GC_BUDGET_MS', 'wt_gc_budget_ms', o.auto === true ? DEFAULT_BUDGET_MS : DEFAULT_MANUAL_BUDGET_MS);
+  const measureOn = o['no-measure'] !== true && (o.measure === true || o.auto !== true);
+  const apply = o.yes === true;
+  const seedMs = Math.min(budget, W.numSetting(ctx, 'DIEU_PHOI_WT_GC_SEED_MS', 'wt_gc_seed_ms', DEFAULT_SEED_MS));
+  const timing = { seed_ms: 0, scan_ms: 0, measure_ms: 0 };
+  const sink = {};
+  const progress = typeof o.onProgress === 'function' ? o.onProgress : () => {};
+  const st = {
+    deadline: t0 + budget, idx: { last: new Map(), discarded: new Set() }, reclaimed: 0,
+    shouldStop: () => false, auto: o.auto === true, trigger: o.trigger || null, removedBranches: [],
+  };
+  const reps = [];
+  let truncated = false;
+  const fatal = [];
+  try {
+    const dirs0 = reposToScan(ctx, o, t0, seedMs, sink);
+    timing.seed_ms = Date.now() - t0;
+    const dirs = o['all-repos'] === true ? needGitLast(dirs0, 3000) : dirs0;
+    const sk = sink.seed && sink.seed.skipped && sink.seed.skipped.length ? ` (bị cắt, bỏ pha: ${sink.seed.skipped.join(', ')})` : '';
+    progress(`seed ${timing.seed_ms} ms${sk}; ${dirs.length} repo`);
+    st.idx = verdictIndex(core.readEvents(ctx));
+    const scannedNow = {};
+    W.setGitDeadline(st.deadline, GIT_CALL_MS);
+    st.wtCache = o['no-cache'] === true || process.env.DIEU_PHOI_WT_GC_CACHE === '0' ? null : loadWtCache(ctx);
+    let n = 0;
+    for (const dir of dirs) {
+      n++;
+      if (Date.now() > st.deadline) { truncated = true; reps.push({ repo: dir, main: null, items: [], error: 'chưa quét kịp (hết ngân sách), lần sau' }); continue; }
+      const rt = Date.now();
+      // --repo tường minh: cả ngân sách cho repo đó (trần 6 giây/repo chỉ để một repo chậm không ăn hết lần quét --all-repos).
+      st.allRepos = o['all-repos'] === true;
+      st.repoStart = rt;
+      st.repoDeadline = o['all-repos'] === true ? Math.min(st.deadline, rt + REPO_GIT_MS) : st.deadline;
+      W.setGitDeadline(st.repoDeadline, GIT_CALL_MS);
+      let rr;
+      try { rr = scanRepo(ctx, dir, st); } catch (e) { rr = { repo: dir, main: null, items: [], error: e.message }; }
+      reps.push(rr);
+      if (!rr.error && Date.now() <= st.deadline) scannedNow[dir] = { ts: Date.now(), ms: Date.now() - rt };
+      else if (!rr.error) truncated = true;
+      progress(`[${n}/${dirs.length}] ${dir}: ${rr.error ? `lỗi ${rr.error}` : `${rr.items.length} mục`} (${Date.now() - rt} ms)`);
+    }
+    if (Date.now() > st.deadline) truncated = true;
+    if (o['all-repos'] === true) {
+      try { fs.writeFileSync(path.join(ctx.paths.data, GC_SCANNED), JSON.stringify(Object.assign({}, sink.scanned || {}, scannedNow))); } catch (_) { /* best effort */ }
+    }
+  } catch (e) {
+    fatal.push(e && e.message ? e.message : String(e));
+    truncated = true;
+  } finally {
+    if (st.wtCache) saveWtCache(ctx, st.wtCache);
+    W.setGitDeadline(0);
+    W.clearDirtyCache();
+  }
+  timing.scan_ms = Date.now() - t0 - timing.seed_ms;
+
+  // Đo dung lượng: lớp thu hồi trước, rồi slot, rồi phần còn lại; chung một ngân sách.
+  if (measureOn) {
+    const mStart = Date.now();
+    const itemMs = W.numSetting(ctx, 'DIEU_PHOI_WT_GC_ITEM_MS', 'wt_gc_item_ms', ITEM_MEASURE_MS);
+    const mEnd = Date.now() + W.numSetting(ctx, 'DIEU_PHOI_WT_GC_MEASURE_MS', 'wt_gc_measure_ms', DEFAULT_MEASURE_MS);
+    const order = { safe: 0, shell: 0, abandoned: 1, 'keep-slot': 2, keep: 3 };
+    const all = [].concat(...reps.map((r) => r.items)).filter((i) => i.path && i.bytes === null && fs.existsSync(i.path));
+    all.sort((a, b) => (order[a.class] === undefined ? 4 : order[a.class]) - (order[b.class] === undefined ? 4 : order[b.class]));
+    for (const it of all) {
+      const left = mEnd - Date.now();
+      if (left <= 0) break;
+      const m = measureDir(it.path, Math.min(itemMs, left), itemMs > ITEM_MEASURE_MS ? itemMs * 400 : ITEM_MEASURE_ENTRIES);
+      it.bytes = m.bytes;
+      it.approx = m.approx;
+    }
+    timing.measure_ms = Date.now() - mStart;
+  }
+
+  if (apply) {
+    for (const rr of reps) {
+      if (!rr.main) continue;
+      try {
+        const a = applyRepo(ctx, rr, st);
+        rr.applied = a.lines;
+        rr.removed = a.removed;
+      } catch (e) { rr.applied = [`lỗi khi gỡ: ${e.message}`]; }
+    }
+  }
+
+  const counts = { safe: 0, 'keep-slot': 0, abandoned: 0, keep: 0, prunable: 0, shell: 0, 'temp-branch': 0 };
+  const totals = { safe_bytes: 0, abandoned_bytes: 0, keep_slot_bytes: 0, approx: true, lower_bound: true, label: 'cận dưới (đo một phần)' };
+  for (const r of reps) {
+    for (const it of r.items) {
+      counts[it.class] = (counts[it.class] || 0) + 1;
+      if (it.approx) totals.approx = true;
+      if (it.class === 'safe' || it.class === 'shell') totals.safe_bytes += it.bytes || 0;
+      else if (it.class === 'abandoned') totals.abandoned_bytes += it.bytes || 0;
+      else if (it.class === 'keep-slot') totals.keep_slot_bytes += it.bytes || 0;
+    }
+  }
+  const clean = reps.map((r) => ({
+    repo: r.repo, main: r.main, error: r.error, applied: r.applied,
+    items: r.items.map((i) => ({
+      class: i.class, path: i.path, branch: i.branch, why: i.why, marked: i.marked, task_id: i.task_id,
+      bytes: i.bytes, approx: i.approx, idle_days: i.idle_days, merged_into: i.merged_into, done: i.done === true,
+    })),
+  }));
+  const removed = reps.reduce((n, r) => n + (r.removed || 0), 0);
+  const rep = {
+    mode: apply ? 'apply' : 'dry-run', repos: clean, counts, totals, truncated, removed, reclaimed_bytes: st.reclaimed,
+    elapsed_ms: Date.now() - t0, timing, seed: sink.seed || null, errors: fatal,
+  };
+  if (apply && o.trigger && removed > 0) {
+    // (d) gỡ tự động luôn thành sự kiện: `state` đọc kind=wt_gc_auto; từng worktree cũng có sự kiện worktree/remove kèm trigger
+    const paths = [].concat(...reps.map((r) => r.items.filter((i) => i.done === true && AUTO_CLASSES.has(i.class) && i.path).map((i) => i.path))).slice(0, 20);
+    const branches = st.removedBranches.slice(0, 20);
+    try {
+      core.appendEvent(ctx, Object.assign({
+        schema: core.SCHEMA, kind: 'wt_gc_auto', ts: core.nowIso(), agent_id: `wtgc:${o.trigger}`, task_id: GC_TASK,
+        trigger: o.trigger, removed, reclaimed_bytes: st.reclaimed, repos: reps.length, paths, branches, elapsed_ms: rep.elapsed_ms,
+      }, core.commonFields(ctx)));
+    } catch (_) { /* sự kiện: best effort */ }
+  }
+  if (apply) {
+    try {
+      fs.writeFileSync(path.join(ctx.paths.data, GC_LAST), JSON.stringify({ ts: Date.now(), removed, reclaimed_bytes: st.reclaimed, repos: reps.length }));
+    } catch (_) { /* dấu thời gian: best effort */ }
+  }
+  return rep;
+}
+
+/**
+ * r1 s5: gc TỰ ĐỘNG lớp safe (verdict accept / hook UserPromptSubmit / đĩa thấp). Chỉ chạy khi wt_auto_gc != off.
+ * Việc quyết định "safe" vẫn do kiểm tra tươi của runGc (--yes kiểm lại ngay trước mỗi lần gỡ); không lớp nào khác bị đụng.
+ * o: { trigger: 'verdict'|'hook'|'disk', allRepos?, repoDirs?, budgetMs? }. Ghi data/gc-log.jsonl; allRepos ghi thêm data/gc-totals.json.
+ */
+function autoGc(ctx, o) {
+  const x = o || {};
+  if (core.autoGcModeOf(ctx) === 'off') return { skipped: 'off', removed: 0, repos: [], counts: {}, reclaimed_bytes: 0 };
+  const trigger = x.trigger || 'hook';
+  const opts = { yes: true, auto: true, measure: true, trigger };
+  if (x.allRepos) opts['all-repos'] = true;
+  if (Array.isArray(x.repoDirs)) opts.repoDirs = x.repoDirs;
+  if (x.budgetMs) opts['budget-ms'] = x.budgetMs;
+  const rep = runGc(ctx, opts);
+  try {
+    fs.appendFileSync(path.join(ctx.paths.data, GC_LOG), JSON.stringify({
+      ts: new Date().toISOString(), trigger, scope: x.allRepos ? 'all' : 'repos', removed: rep.removed, reclaimed_bytes: rep.reclaimed_bytes,
+      repos: rep.repos.length, counts: rep.counts, truncated: rep.truncated, elapsed_ms: rep.elapsed_ms, errors: rep.errors,
+    }) + '\n');
+  } catch (_) { /* log: best effort */ }
+  if (x.allRepos) {
+    try {
+      fs.writeFileSync(path.join(ctx.paths.data, GC_TOTALS), JSON.stringify({
+        ts: Date.now(), abandoned_bytes: rep.totals.abandoned_bytes, keep_slot_bytes: rep.totals.keep_slot_bytes, reclaimed_bytes: rep.reclaimed_bytes,
+      }) + '\n');
+    } catch (_) { /* best effort */ }
+  }
+  return rep;
+}
+
+/** r1 s5 (d): tóm tắt các sự kiện wt_gc_auto cho `state`: lần cuối + tổng 7 ngày. null nếu chưa có lần nào. */
+function autoGcState(events, now) {
+  const t = typeof now === 'number' ? now : Date.now();
+  const evs = (events || []).filter((e) => e && e.kind === 'wt_gc_auto');
+  if (!evs.length) return null;
+  const last = evs[evs.length - 1];
+  const week = evs.filter((e) => t - Date.parse(e.ts) <= 7 * 86400000);
+  return {
+    last: { ts: last.ts, trigger: last.trigger, removed: last.removed, reclaimed_bytes: last.reclaimed_bytes, paths: last.paths || [], branches: last.branches || [] },
+    runs_7d: week.length,
+    removed_7d: week.reduce((n, e) => n + (Number(e.removed) || 0), 0),
+    reclaimed_bytes_7d: week.reduce((n, e) => n + (Number(e.reclaimed_bytes) || 0), 0),
+  };
+}
+
+function autoGcLines(events, now) {
+  const s = autoGcState(events, now);
+  if (!s) return [];
+  const l = s.last;
+  const shown = l.paths.slice(0, 3).map((p) => path.basename(p)).join(', ');
+  const more = l.paths.length > 3 ? ', …' : '';
+  const br = l.branches.slice(0, 3).join(', ');
+  const brMore = l.branches.length > 3 ? ', …' : '';
+  return ['gc tự động (safe/vỏ/prune/nhánh tạm): lần cuối ' + l.ts + ' [' + l.trigger + '] gỡ ' + l.removed + ' mục ~' + fmtBytes(l.reclaimed_bytes) + (shown ? ' (' + shown + more + ')' : '') + (br ? ' nhánh: ' + br + brMore : '')
+    + '; 7 ngày: ' + s.runs_7d + ' lần, ' + s.removed_7d + ' mục, ~' + fmtBytes(s.reclaimed_bytes_7d)];
+}
+
+/** Luôn trả một bản tóm tắt (kể cả lỗi / hết giờ): stdout rỗng là bug. Tiến trình từng repo ghi ra stderr. */
+function cmdGc(opts) {
+  const t0 = Date.now();
+  const quiet = opts.auto === true;
+  const onProgress = quiet ? null : (m) => { try { process.stderr.write(`wt gc: ${m}\n`); } catch (_) { /* stderr đóng */ } };
+  try {
+    const ctx = ctxOf(opts);
+    const rep = runGc(ctx, Object.assign({}, opts, { onProgress }));
+    if (opts.json) return { code: rep.errors && rep.errors.length ? 1 : 0, out: JSON.stringify(rep) };
+    return { code: rep.errors && rep.errors.length ? 1 : 0, out: render(rep) };
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    const rep = {
+      mode: opts.yes === true ? 'apply' : 'dry-run', repos: [], counts: { safe: 0, 'keep-slot': 0, abandoned: 0, keep: 0, prunable: 0, shell: 0, 'temp-branch': 0 },
+      totals: { safe_bytes: 0, abandoned_bytes: 0, keep_slot_bytes: 0, approx: false }, truncated: true, removed: 0, reclaimed_bytes: 0,
+      elapsed_ms: Date.now() - t0, timing: null, seed: null, errors: [msg],
+    };
+    return { code: 1, out: opts.json ? JSON.stringify(rep) : `wt gc: LỖI — ${msg}\n${render(rep)}` };
+  }
+}
+
+module.exports = { autoGc, autoGcState, autoGcLines, GC_LOG, GC_TOTALS, cmdGc, runGc, scanRepo, measureDir, fmtBytes, slotReason, keepPatterns, GC_TASK, GC_LAST };