@kienntpixon/dieu-phoi 0.7.5 → 0.7.6

package/lib/worktree.cjs

@@ -28,6 +28,7 @@ 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'); // core 0.7.6 (s2): sổ repo đã chạm (data/repos.json)
 
 const MARK = 'dieu-phoi.json';
 const BRANCH_PREFIX = 'dp/';
@@ -40,8 +41,14 @@ const NOT_DONE = new Set(['reject', 'fail', 'timeout', 'aborted']);
 // nên "đã merge" tầm thường; không có ngưỡng này thì bước đang chờ agent đầu tiên có thể bị gỡ.
 const MERGED_MIN_AGE_MS = 60 * 60 * 1000;
 
+// Hạn chót toàn cục cho mọi lệnh git (ms epoch; 0 = không hạn). `wt gc` đặt để một lệnh git treo/chậm không kéo quá ngân sách.
+let gitDeadline = 0;
+let gitCallMs = 60000;
+function setGitDeadline(ts, perCallMs) { gitDeadline = Number(ts) > 0 ? Number(ts) : 0; gitCallMs = Number(perCallMs) > 0 ? Number(perCallMs) : 60000; }
+
 function git(cwd, args) {
-  const r = cp.spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, timeout: 60000 });
+  const timeout = gitDeadline ? Math.max(1500, Math.min(gitCallMs, gitDeadline - Date.now())) : 60000;
+  const r = cp.spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, timeout });
   const err = r.stderr || (r.error ? r.error.message : '') || '';
   return { ok: r.status === 0, out: (r.stdout || '').trim(), err: err.trim() };
 }
@@ -74,18 +81,65 @@ function markedWorktrees(common) {
     out.push({
       admin, name, task_id: mark.task_id, root: mark.root || null, branch: mark.branch || null,
       created_ts: mark.created_ts || null, path: wtPath, exists: !!wtPath && fs.existsSync(wtPath),
+      keep: mark.keep === true,
       deps: typeof mark.deps === 'string' ? mark.deps : null, deps_path: typeof mark.deps_path === 'string' ? mark.deps_path : '.',
     });
   }
   return out;
 }
 
+// `git status` trên đĩa lạnh + Defender mất 5–10 giây mỗi worktree: gc chạy trước song song (một tiến trình node phụ, spawnSync
+// từ phía gọi nên scanRepo vẫn đồng bộ) rồi dirtyOf lấy kết quả từ bộ nhớ đệm một lần.
+const dirtyCache = new Map();
+const PREFETCH_SCRIPT = `
+const cp = require('child_process');
+const input = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+const { paths, concurrency, callMs } = input;
+let i = 0;
+function next() {
+  if (i >= paths.length) return;
+  const p = paths[i++];
+  cp.execFile('git', ['--no-optional-locks', 'status', '--porcelain'], { cwd: p, encoding: 'utf8', windowsHide: true, timeout: callMs, maxBuffer: 8 * 1024 * 1024 }, (err, out) => {
+    const lines = String(out || '').split(/\\r?\\n/).filter(Boolean).slice(0, 2000);
+    process.stdout.write(JSON.stringify({ p, ok: !err, out: lines.join('\\n') }) + '\\n');
+    next();
+  });
+}
+for (let c = 0; c < Math.min(concurrency, paths.length); c++) next();
+`;
+
+/** Chạy `git status` song song cho nhiều worktree; kết quả vào bộ nhớ đệm cho dirtyOf. Tới hạn chót thì dừng (phần còn lại dirtyOf tự gọi). */
+function prefetchDirty(paths, opts) {
+  const o = opts || {};
+  const list = (paths || []).filter(Boolean);
+  if (list.length < 2) return 0;
+  const left = o.deadline ? o.deadline - Date.now() : 120000;
+  if (left < 3000) return 0;
+  const r = cp.spawnSync(process.execPath, ['-e', PREFETCH_SCRIPT], {
+    input: JSON.stringify({ paths: list, concurrency: o.concurrency || 8, callMs: o.callMs || 30000 }),
+    encoding: 'utf8', windowsHide: true, timeout: Math.max(1000, left - 500), maxBuffer: 64 * 1024 * 1024,
+  });
+  let n = 0;
+  for (const line of String(r.stdout || '').split('\n')) {
+    if (!line) continue;
+    try {
+      const j = JSON.parse(line);
+      if (j && j.ok) { dirtyCache.set(realKey(j.p), { ok: true, out: j.out, err: '' }); n++; }
+    } catch (_) { /* dòng bị cắt do hết giờ */ }
+  }
+  return n;
+}
+function clearDirtyCache() { dirtyCache.clear(); }
+
 /**
  * true = còn thay đổi (kể cả file chưa theo dõi), false = sạch, null = không đọc được.
  * s3: dòng `?? …node_modules/` là link (junction dùng chung do --deps link tạo) không tính là thay đổi.
  */
 function dirtyOf(wtPath) {
-  const r = git(wtPath, ['status', '--porcelain']);
+  const k = realKey(wtPath);
+  const pre = dirtyCache.get(k);
+  if (pre) dirtyCache.delete(k); // dùng một lần: kết quả quét song song chỉ hợp lệ cho lượt quét đang chạy
+  const r = pre || git(wtPath, ['--no-optional-locks', 'status', '--porcelain']);
   if (!r.ok) return null;
   const lines = r.out.split(/\r?\n/).filter(Boolean).filter((l) => {
     const m = /^\?\? "?(.*?node_modules)\/?"?$/.exec(l);
@@ -103,35 +157,376 @@ function realKey(p) {
   return process.platform === 'win32' ? r.toLowerCase() : r;
 }
 
+/** Các task id có thể gắn với một worktree: dấu, hậu tố nhánh `<x>/<id8>` / `dp/<id8>`, hậu tố tên thư mục `<x>-<id8>`. */
+function taskIdsOfWorktree(wtPath, branch, mark) {
+  const ids = new Set();
+  const add = (v) => { if (typeof v === 'string' && core.isValidTaskId(v)) ids.add(v); };
+  if (mark) add(mark.task_id);
+  if (branch) add(String(branch).slice(String(branch).lastIndexOf('/') + 1));
+  const base = realKey(wtPath);
+  const leaf = base.slice(base.lastIndexOf('/') + 1);
+  add(leaf.slice(leaf.lastIndexOf('-') + 1));
+  return ids;
+}
+
 /**
- * s8: kiểm "worktree đang là cwd (hoặc thư mục con) của một agent sống" trước khi gỡ. Đọc sổ agent sống data/live
- * (core.readLive: bỏ file quá TTL; kèm ý định giao chưa nhận SubagentStart, mang worktree của brief). Trả mô tả agent
- * ("agent ab12 task xyz") để removeMarked GIỮ worktree, hoặc null. Không ném: sổ lỗi thì coi như không có agent.
+ * s8: kiểm "worktree đang có agent sống" trước khi gỡ. Đọc sổ agent sống data/live (core.readLive: bỏ file quá TTL; kèm ý định
+ * giao chưa nhận SubagentStart, mang worktree của brief). Khớp theo ĐƯỜNG DẪN (cwd/worktree là worktree hoặc thư mục con) HOẶC
+ * theo TASK_ID (agent có cwd là run dir vẫn bắt được nếu task của nó = task gắn với worktree: dấu, hậu tố nhánh, hậu tố tên thư mục).
+ * `taskIds` (Set/mảng) truyền thêm nếu có. Trả { desc, lastMs } (lastMs = hoạt động cuối của agent khớp, ms epoch hoặc null) hoặc
+ * null. Không ném: sổ lỗi thì coi như không có agent.
  */
-function liveAgentInWorktree(ctx, wtPath) {
+function liveActivityOf(ctx, wtPath, taskIds) {
   const wt = realKey(wtPath);
   if (!wt) return null;
   let live;
   try { live = core.readLive(ctx); } catch (_) { return null; }
+  const ids = new Set(taskIds || []);
+  let best = null;
   for (const r of live.agents.concat(live.pending)) {
     const at = realKey(r.cwd || r.worktree);
-    if (!at || !(at === wt || at.startsWith(`${wt}/`))) continue;
+    const byPath = at && (at === wt || at.startsWith(`${wt}/`));
+    const byTask = typeof r.task_id === 'string' && ids.has(r.task_id);
+    if (!byPath && !byTask) continue;
     const who = r.agent_id ? `agent ${String(r.agent_id).slice(0, 8)}` : 'agent đang chờ nhận';
-    return `${who}${r.task_id ? ` task ${r.task_id}` : ''}`;
+    const t = Date.parse(r.last_activity || r.start || r.t || '');
+    const lastMs = Number.isFinite(t) ? t : (Number.isFinite(Number(r.last_activity)) ? Number(r.last_activity) : null);
+    if (!best || (lastMs || 0) > (best.lastMs || 0)) {
+      best = { desc: `${who}${r.task_id ? ` task ${r.task_id}` : ''}${byPath ? '' : ' (khớp theo task_id)'}`, lastMs };
+    }
+  }
+  return best;
+}
+
+/** Tương thích: mô tả agent sống (chuỗi) hoặc null. */
+function liveAgentInWorktree(ctx, wtPath, taskIds) {
+  const r = liveActivityOf(ctx, wtPath, taskIds);
+  return r ? r.desc : null;
+}
+
+// ---- r1 s1: bộ vị từ an toàn duy nhất cho MỌI worktree đăng ký trong git ----
+
+const IDLE_UNMARKED_MS = 24 * 60 * 60 * 1000; // phụ lục Q1: worktree không dấu phải nhàn rỗi > 24 giờ
+const LOCK_STALE_MS = 30 * 60 * 1000; // khoá `initializing` của `git worktree add` bị giết: mồ côi sau 30 phút
+const INIT_LOCK = 'initializing';
+
+/** Tên nhánh (bỏ `refs/heads/` hoặc `refs/remotes/<remote>/`) hoặc null nếu không phải nhánh. */
+function shortBranchOf(ref) {
+  if (ref.startsWith('refs/heads/')) return ref.slice('refs/heads/'.length);
+  const m = /^refs\/remotes\/[^/]+\/(.+)$/.exec(ref);
+  return m ? m[1] : null;
+}
+
+/**
+ * Nhánh tạm (không tính là nơi "đã merge vào"): CHỈ tên do công cụ sinh: dp/*, r####-*, worktree-agent-*, claude/*.
+ * feat/*, rust/<id8>, x/<id8>... KHÔNG tạm (nhánh tích hợp như feat/rust-poc phải được tính là đích merge); nhánh làm việc đang
+ * checkout trong worktree liên kết được loại riêng bởi durablePolicy, không nhờ tên.
+ */
+function isTempBranch(name) {
+  return name.startsWith(BRANCH_PREFIX) || name.startsWith('worktree-agent-') || name.startsWith('claude/') || /^r\d{4}-/.test(name);
+}
+
+/**
+ * Chính sách "ref bền" dùng chung (wtfast.makeFacts và mergedAnywhere): ref nào được tính là ĐÍCH mà một nhánh có thể "đã vào".
+ * reg = sổ worktree (mục đầu = checkout chính); hasUpstream(name) = nhánh cục bộ có upstream; exclude = nhánh đang xét.
+ * policy(name, local) → true khi ref bền:
+ *  - không phải HEAD, không phải chính nhánh đang xét (cả bản remote cùng tên), không phải tên tạm (dp/*, r####-*, worktree-agent-*, claude/*)
+ *    — trừ nhánh checkout của checkout CHÍNH (luôn bền: nhánh tích hợp như feat/overhaul);
+ *  - nhánh CỤC BỘ đang checkout trong một worktree LIÊN KẾT là nhánh làm việc (trivially chứa chính nó, và chứa cả những gì nó
+ *    đã nuốt từ nhánh khác): KHÔNG bền, TRỪ KHI nó có upstream (đã đẩy lên remote, vd feat/rust-poc là nhánh tích hợp đặt ở
+ *    .claude/worktrees/rust-poc-int; nhánh làm việc rust/<id8> không upstream thì không bao giờ bền);
+ *  - mọi ref khác (main/master/develop/release*, nhánh cục bộ không checkout ở worktree liên kết, ref remote) bền.
+ */
+function durablePolicy(reg, hasUpstream, exclude) {
+  const list = reg || [];
+  const mainBranch = list.length && list[0].branch ? list[0].branch : null;
+  const linked = new Set(list.slice(1).map((r) => r.branch).filter(Boolean));
+  return (name, local) => {
+    if (!name || name === 'HEAD' || name === exclude) return false;
+    if (name === mainBranch && local !== false) return true;
+    if (isTempBranch(name)) return false;
+    if (local !== false && linked.has(name)) return !!(hasUpstream && hasUpstream(name));
+    return true;
+  };
+}
+
+/**
+ * Nhánh `branch` đã nằm trong MỘT ref bền chưa (durablePolicy: KHÔNG tính nhánh làm việc đang checkout trong worktree liên kết
+ * trừ khi có upstream, không tính chính nó và nhánh tạm). Dùng
+ * `for-each-ref --contains <sha> refs/heads refs/remotes`. `reg` truyền sẵn thì khỏi gọi `git worktree list`.
+ * Trả { merged, into: [tên nhánh] }; lỗi git / không có nhánh → merged=false (giữ lại).
+ */
+function mergedAnywhere(main, branch, reg) {
+  const none = { merged: false, into: [] };
+  if (!branch) return none;
+  const sha = git(main, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}^{commit}`]);
+  if (!sha.ok || !sha.out) return none;
+  const r = git(main, ['for-each-ref', '--contains', sha.out, '--format=%(refname)%09%(upstream)', 'refs/heads', 'refs/remotes']);
+  if (!r.ok) return none;
+  let list = reg;
+  if (!list) { try { list = registeredOf(main); } catch (_) { list = null; } }
+  if (!list) return none; // không biết ai đang checkout gì thì không dám tính nhánh nào là bền
+  const rows = r.out.split(String.fromCharCode(10)).map((l) => l.replace(String.fromCharCode(13), '')).filter(Boolean).map((l) => l.split(String.fromCharCode(9)));
+  const upstream = new Set();
+  for (const [ref, up] of rows) if (ref.startsWith('refs/heads/') && up) upstream.add(ref.slice('refs/heads/'.length));
+  const ok = durablePolicy(list, (n) => upstream.has(n), branch);
+  const into = [];
+  for (const [ref] of rows) {
+    const name = shortBranchOf(ref);
+    if (name && ok(name, ref.startsWith('refs/heads/')) && !into.includes(name)) into.push(name);
   }
+  return { merged: into.length > 0, into };
+}
+
+/**
+ * Tự gỡ được (khi wtSafety ok) chỉ với: tên do `wt add` sinh (`<tên repo>-wt-<task id 8 ký tự>`) hoặc BẤT KỲ thư mục nào dưới
+ * `<repo>/.claude/worktrees/` (Claude Code quản lý: agent-*, rust-<id8>...; phán quyết điều phối viên cho Q3). Tên tự đặt ở nơi khác
+ * (`<repo>-wt/<lane>`, `<repo>-wt-<tên>`, đường dẫn --path...) là slot giữ lại.
+ */
+function isAutoName(main, wtPath) {
+  const key = realKey(wtPath);
+  const base = key.slice(key.lastIndexOf('/') + 1);
+  const mb = realKey(main);
+  const mainBase = mb.slice(mb.lastIndexOf('/') + 1);
+  const m = /^(.*)-wt-([a-z0-9]{8})$/.exec(base);
+  if (m && m[1] === mainBase) return true;
+  if (key.startsWith(`${mb}/.claude/worktrees/`) && key.length > `${mb}/.claude/worktrees/`.length) return true;
+  // tương thích s1: mẫu cô lập cũ `.../.claude/worktrees/agent-*` ở bất kỳ đâu.
+  return /\/\.claude\/worktrees\/agent-[^/]+$/.test(key);
+}
+
+/** Lý do KHÔNG tự gỡ (chuỗi) hoặc null: là checkout chính, dấu `keep: true` (tạo bằng --path), hoặc tên tự đặt. */
+function keepSlotReason(main, wtPath, mark) {
+  if (realKey(wtPath) === realKey(main)) return 'là checkout chính';
+  if (mark && mark.keep === true) return 'slot giữ lại (dấu keep: true, tạo bằng --path tự đặt): chỉ gỡ tay';
+  if (!isAutoName(main, wtPath)) return 'slot giữ lại (tên thư mục tự đặt, không phải tên do wt add sinh, cũng không nằm dưới <repo>/.claude/worktrees/): chỉ gỡ tay';
   return null;
 }
 
+/** Mục `git worktree list` của đúng đường dẫn (so sánh realKey); `reg` truyền sẵn thì khỏi gọi git lại. */
+function registeredEntry(main, wtPath, reg) {
+  const key = realKey(wtPath);
+  return (reg || registeredOf(main)).find((r) => realKey(r.path) === key) || null;
+}
+
+/** Thư mục admin (git-dir) của một worktree: rev-parse trong worktree; hỏng thì quét <common>/worktrees/NAME/gitdir. */
+function adminDirOf(wtPath, common) {
+  const r = git(wtPath, ['rev-parse', '--path-format=absolute', '--git-dir']);
+  // Thư mục không phải worktree đã đăng ký thì rev-parse trả .git của repo cha: chỉ nhận git-dir nằm trong <common>/worktrees.
+  const inWorktrees = (d) => !common || realKey(path.dirname(d)) === realKey(path.join(common, 'worktrees'));
+  if (r.ok && r.out && inWorktrees(r.out)) return r.out;
+  if (!common) return null;
+  const root = path.join(common, 'worktrees');
+  const key = realKey(wtPath);
+  let names = [];
+  try { names = fs.readdirSync(root); } catch (_) { return null; }
+  for (const n of names) {
+    try {
+      const g = path.dirname(fs.readFileSync(path.join(root, n, 'gitdir'), 'utf8').trim());
+      if (realKey(g) === key) return path.join(root, n);
+    } catch (_) { /* admin hỏng: bỏ qua */ }
+  }
+  return null;
+}
+
+/** Tuổi (ms) của khoá worktree: mtime file `locked` trong git-dir admin, không có thì mtime thư mục admin. null = không đọc được. */
+function lockAgeMs(admin) {
+  if (!admin) return null;
+  for (const p of [path.join(admin, 'locked'), admin]) {
+    try { return Date.now() - fs.statSync(p).mtimeMs; } catch (_) { /* thử mốc kế */ }
+  }
+  return null;
+}
+
+// Thư mục không tính vào "mtime file mới nhất" (nặng/sinh tự động, và đụng vào là do công cụ, không phải người làm).
+const IDLE_SKIP_DIRS = new Set(['.git', 'node_modules', 'target', 'build', 'dist', 'out', 'obj', 'bin', 'Library', 'Temp', 'Logs', '.next', '.nuxt', '.gradle', '.venv', 'venv', '__pycache__', '.cache', '.turbo', 'coverage']);
+const IDLE_WALK_CAP = 3000; // số mục tối đa duyệt mỗi worktree
+const IDLE_WALK_MS = 1500; // thời gian tối đa duyệt mỗi worktree (đĩa lạnh + Defender: ~4 ms/mục)
+
 /**
- * Gỡ một worktree có dấu đang còn thư mục. Không --force: còn thay đổi thì giữ.
+ * Duyệt RỘNG (file nông trước) lấy mtime file MỚI NHẤT trong worktree, có trần số mục (opts.cap) và thời gian (opts.ms, và hạn chót
+ * git toàn cục nếu có); bỏ IDLE_SKIP_DIRS và con trỏ `.git`, không đi qua symlink/junction.
+ * Trả { newest, complete }: complete=false khi hết trần trước khi duyệt xong. Khi đó `newest` chỉ là CẬN DƯỚI của mtime thật:
+ * file mới có thể nằm ở phần chưa duyệt (chạm lại file không đổi nội dung, file bị gitignore: git status không thấy) nên người gọi
+ * PHẢI coi nhàn rỗi là không biết (null), không được dùng như một con số.
+ */
+function walkNewest(root, opts) {
+  const o = opts || {};
+  let budget = o.cap || IDLE_WALK_CAP;
+  const until = Math.min(Date.now() + (o.ms || IDLE_WALK_MS), gitDeadline || Infinity);
+  let newest = null;
+  let complete = true;
+  const queue = [root];
+  for (let qi = 0; qi < queue.length; qi++) {
+    if (budget <= 0 || Date.now() > until) { complete = false; break; }
+    let ents;
+    try { ents = fs.readdirSync(queue[qi], { withFileTypes: true }); } catch (_) { continue; }
+    for (const e of ents) {
+      if (budget-- <= 0 || Date.now() > until) { return { newest, complete: false }; }
+      if (e.isSymbolicLink() || e.name === '.git') continue; // `.git` trong worktree là FILE (con trỏ), mtime = lúc tạo
+      const full = path.join(queue[qi], e.name);
+      if (e.isDirectory()) { if (!IDLE_SKIP_DIRS.has(e.name)) queue.push(full); continue; }
+      try { const m = fs.statSync(full).mtimeMs; if (newest === null || m > newest) newest = m; } catch (_) { /* biến mất giữa chừng */ }
+    }
+  }
+  return { newest, complete };
+}
+
+/** mtime file mới nhất (số) hoặc null; KHÔNG báo bị cắt: chỉ dùng cho kiểm tra/test. Quyết định an toàn dùng walkNewest/idleMsOf. */
+function newestFileMtimeMs(root, opts) { return walkNewest(root, opts).newest; }
+
+/**
+ * Thời gian nhàn rỗi (ms): mốc MỚI NHẤT trong {commit cuối của nhánh, mtime file mới nhất trong worktree (duyệt có trần),
+ * hoạt động cuối của agent sống gắn với worktree}. KHÔNG dùng mtime git-dir admin / index (git status, gc quét... tự làm chúng
+ * nhảy về "bây giờ"). null = không đọc được gì HOẶC duyệt file bị cắt trần (opts.cap/opts.ms): nhàn rỗi không biết, người gọi phải giữ.
+ * opts.cachedNewest (số|null): kết quả duyệt đầy đủ đã lưu; opts.out nhận { walk: {newest, complete, cached} }. `liveMs` = hoạt động cuối của agent sống (ms epoch) hoặc null.
+ * opts.walk === false: bỏ duyệt file (chỉ commit + agent sống): cận trên rẻ của nhàn rỗi thật.
+ */
+function idleMsOf(wtPath, commitMs, liveMs, opts) {
+  const o = opts || {};
+  const marks = [];
+  if (commitMs === undefined) {
+    const c = git(wtPath, ['log', '-1', '--format=%ct']);
+    if (c.ok && /^\d+$/.test(c.out)) marks.push(Number(c.out) * 1000);
+  } else if (commitMs) marks.push(commitMs); // gc quét hàng loạt: thời điểm commit đầu nhánh lấy sẵn từ một lệnh for-each-ref
+  if (o.walk !== false) {
+    // bộ nhớ đệm của gc (HEAD + mtime thư mục worktree không đổi): kết quả duyệt đầy đủ lần trước; không có thì duyệt thật.
+    const w = o.cachedIncomplete === true ? { newest: null, complete: false, cached: true }
+      : o.cachedNewest !== undefined ? { newest: o.cachedNewest, complete: true, cached: true } : walkNewest(wtPath, o);
+    if (o.out) o.out.walk = w;
+    // Duyệt bị cắt (hết trần): không biết file nào mới hơn → nhàn rỗi KHÔNG BIẾT, không phải một con số (an toàn: coi là còn hoạt động).
+    if (!w.complete) return null;
+    if (w.newest !== null) marks.push(w.newest);
+  }
+  if (Number.isFinite(liveMs) && liveMs) marks.push(liveMs);
+  return marks.length ? Math.max(0, Date.now() - Math.max(...marks)) : null;
+}
+
+/**
+ * wtSafety(ctx, main, w, opts): vị từ an toàn DUY NHẤT để gỡ một worktree (verdict accept, wt clean, --merged, gc).
+ * w = mục registeredOf ({path, branch, detached, locked}) + tuỳ chọn { mark: bản ghi markedWorktrees, admin }.
+ * ok khi: thư mục còn; không detached; nhánh đang checkout THẬT (porcelain, không phải mark.branch) đã vào một ref bền
+ * (mergedAnywhere); sạch; không agent sống; nhàn rỗi đủ lâu; không khoá — hoặc khoá `initializing` mồ côi (lock.stale).
+ * opts: requireMerged (mặc định true), minIdleMs (mặc định 0 nếu có dấu, 24 giờ nếu không dấu: phụ lục Q1).
+ * Chỉ đọc, không bao giờ sửa gì. Trả { ok, why, branch_now, merged, merged_into, dirty, live, lock, idle_ms };
+ * lock = null | { reason, stale, age_ms } (stale=true → cần `git worktree unlock` trước khi gỡ).
+ */
+function wtSafety(ctx, main, w, opts) {
+  const o = opts || {};
+  const requireMerged = o.requireMerged !== false;
+  const mark = w.mark || null;
+  const minIdle = Number.isFinite(o.minIdleMs) ? o.minIdleMs : (mark ? 0 : IDLE_UNMARKED_MS);
+  const res = {
+    ok: false, why: null, branch_now: w.branch || null, merged: false, merged_into: [], dirty: null, live: null, lock: null, idle_ms: null,
+  };
+  const fail = (why) => { if (!res.why) res.why = why; };
+  if (!w.path || !fs.existsSync(w.path)) { res.why = 'thư mục đã mất'; return res; }
+  // Q3: slot giữ lại (đường dẫn tự đặt) và checkout chính KHÔNG BAO GIỜ tự gỡ, với mọi đường gọi tự động.
+  const slot = keepSlotReason(main, w.path, mark);
+  if (slot) { res.why = slot; return res; }
+  if (w.detached || !w.branch) { res.why = 'đang ở detached HEAD (không có nhánh), có thể giữ commit riêng'; return res; }
+  const admin = w.admin || adminDirOf(w.path, null);
+  const commitMsOf = o.commitMsOf || null; // opts của gc: batch, không gọi git cho mỗi worktree
+  if (w.locked !== null && w.locked !== undefined) {
+    const reason = String(w.locked);
+    if (reason === INIT_LOCK) {
+      const age = lockAgeMs(admin);
+      const stale = age !== null && age >= LOCK_STALE_MS;
+      res.lock = { reason, stale, age_ms: age };
+      if (!stale) fail(`đang khoá "${INIT_LOCK}" (mới dưới 30 phút, có thể git worktree add còn chạy)`);
+    } else {
+      res.lock = { reason, stale: false, age_ms: lockAgeMs(admin) };
+      fail(`đang bị khoá${reason ? ` (${reason})` : ''}`);
+    }
+  }
+  // Đo nhàn rỗi TRƯỚC mọi lệnh git khác trong worktree (status/log có thể ghi lại index, làm mtime nhảy về "bây giờ").
+  const liveHit = liveActivityOf(ctx, w.path, taskIdsOfWorktree(w.path, w.branch, mark));
+  const liveMs = liveHit ? liveHit.lastMs : null;
+  res.live = liveHit ? liveHit.desc : null;
+  if (res.live) fail(`đang là cwd của agent sống (${res.live})`);
+  // Nhàn rỗi: cận trên rẻ (commit + agent sống) trước; chỉ duyệt file (đắt trên đĩa lạnh) khi opts.walkIdleIf(base, merged) đồng ý.
+  // Lô (for-each-ref) có thể hụt dưới tải (quá trần mỗi lệnh git): thiếu thì hỏi riêng worktree này, không coi là "không có commit".
+  const batched = commitMsOf ? commitMsOf(w.branch) : null;
+  const commitMs = Number.isFinite(batched) && batched > 0 ? batched : (() => {
+    const c = git(w.path, ['log', '-1', '--format=%ct']);
+    return c.ok && /^\d+$/.test(c.out) ? Number(c.out) * 1000 : null;
+  })();
+  const baseIdle = idleMsOf(w.path, commitMs || 0, liveMs, { walk: false });
+  // opts.dirtyNeeded(res, merged): gc bỏ `git status` (đắt trên repo Unity) khi kết quả không còn đổi được phân lớp.
+  const early = o.dirtyNeeded || o.mergedOf ? (o.mergedOf || ((b) => mergedAnywhere(main, b, o.reg)))(w.branch) : null;
+  const walkWanted = !o.walkIdleIf || o.walkIdleIf(baseIdle, early);
+  const cache = o.cache || {};
+  const walkOut = {};
+  const fullIdle = () => idleMsOf(w.path, commitMs || 0, liveMs, { cap: o.walkCap, ms: o.walkMs, cachedNewest: cache.newest, cachedIncomplete: cache.incomplete, out: walkOut });
+  // Đệm chỉ được rút ngắn kết quả ÂM: "bẩn" đã đệm -> giữ ngay; "sạch" không bao giờ lấy từ đệm (luôn git status thật).
+  const dirtyNow = () => { if (cache.dirty === true) { res.dirty_cached = true; return true; } return dirtyOf(w.path); };
+  if (!o.dirtyNeeded) {
+    res.idle_ms = walkWanted ? fullIdle() : baseIdle;
+    res.dirty = dirtyNow();
+    if (res.dirty !== false) fail(res.dirty ? 'còn thay đổi chưa commit' : 'không đọc được trạng thái git');
+  } else {
+    // gc: cận trên rẻ (commit + agent sống) quyết định có cần git status không (superset của nhu cầu thật). Duyệt file (đắt) CHỈ khi
+    // cây sạch: cây bẩn/không đọc được thì đằng nào cũng giữ, nhàn rỗi chính xác không đổi phân lớp.
+    res.idle_ms = baseIdle;
+    if (!o.dirtyNeeded(res, early)) {
+      res.dirty = null;
+      res.dirty_skipped = true;
+    } else {
+      res.dirty = dirtyNow();
+      if (res.dirty !== false) fail(res.dirty ? 'còn thay đổi chưa commit' : 'không đọc được trạng thái git');
+      else if (walkWanted) res.idle_ms = fullIdle();
+    }
+  }
+  if (walkOut.walk) {
+    res.walk = walkOut.walk;
+    // Tín hiệu nhàn rỗi nào không biết (duyệt bị cắt trần, hoặc không có mốc nào) thì KHÔNG an toàn dù minIdle = 0 (worktree có dấu).
+    if (res.idle_ms === null) { res.idle_unknown = true; fail(`idle-unknown: không xác định được nhàn rỗi (${walkOut.walk.complete ? 'không có mốc thời gian nào' : 'duyệt file bị cắt theo trần số mục/thời gian'}), giữ`); }
+  }
+  const m = early || mergedAnywhere(main, w.branch, o.reg);
+  res.merged = m.merged;
+  res.merged_into = m.into;
+  if (requireMerged && !m.merged) fail(`nhánh ${w.branch} chưa vào nhánh bền nào (gc sẽ gỡ khi nhánh vào main)`);
+  if (minIdle > 0 && (res.idle_ms === null || res.idle_ms < minIdle)) {
+    fail(`chưa nhàn rỗi đủ ${Math.round((minIdle / 3600000) * 10) / 10} giờ${res.idle_ms === null ? '' : ` (mới ${Math.round(res.idle_ms / 60000)} phút)`}`);
+  }
+  if (res.dirty_skipped) fail('chưa kiểm sạch (bỏ qua git status vì đã chắc chắn không gỡ được)');
+  res.ok = !res.why;
+  return res;
+}
+
+/** wtSafety cho một worktree có dấu: tìm mục đăng ký tương ứng (reg truyền sẵn thì khỏi gọi git). Không đăng ký → ok=false. */
+function safetyOfMarked(ctx, main, w, opts, reg) {
+  const e = w.path ? registeredEntry(main, w.path, reg) : null;
+  if (!e) {
+    return { ok: false, why: 'không còn đăng ký trong git worktree list', branch_now: null, merged: false, merged_into: [], dirty: null, live: null, lock: null, idle_ms: null };
+  }
+  return wtSafety(ctx, main, Object.assign({}, e, { mark: w, admin: w.admin }), opts);
+}
+
+/** Lý do GIỮ (chuỗi) hoặc null nếu gỡ được. Khác nhánh của dấu thì giữ, trừ khi opts.anyBranch (xét theo nhánh đang checkout). */
+function keepReason(w, s, opts) {
+  if (!(opts && opts.anyBranch) && w.branch && s.branch_now && s.branch_now !== w.branch) {
+    return `đang checkout ${s.branch_now} (không phải nhánh của task ${w.branch})`;
+  }
+  return s.ok ? null : s.why;
+}
+
+/**
+ * Gỡ một worktree có dấu đang còn thư mục. Không --force. Mọi điều kiện an toàn qua wtSafety (+ nhánh đang checkout phải
+ * là nhánh của dấu, trừ opts.anyBranch; slot giữ lại / tên tự đặt không bao giờ được gỡ)..
  * s3: gỡ junction node_modules (không đi xuyên) TRƯỚC `git worktree remove`; git lỗi thì khôi phục junction.
- * Gỡ xong mà còn vỏ thư mục (git để lại) thì xoá vỏ bằng removeShell (link chỉ unlink, không vào đích).
+ * Khoá `initializing` mồ côi → `git worktree unlock` trước khi gỡ. Gỡ xong mà còn vỏ thư mục thì removeShell.
  */
-function removeMarked(w, mainDir, ctx) {
-  const busy = liveAgentInWorktree(ctx, w.path);
-  if (busy) return { removed: false, msg: `giữ ${w.path}: đang là cwd của agent sống (${busy})` };
-  const dirty = dirtyOf(w.path);
-  if (dirty !== false) return { removed: false, msg: `giữ ${w.path}: ${dirty ? 'còn thay đổi chưa commit' : 'không đọc được trạng thái git'}` };
+function removeMarked(w, mainDir, ctx, opts) {
+  const s = safetyOfMarked(ctx, mainDir, w, opts);
+  const why = keepReason(w, s, opts);
+  if (why) return { removed: false, msg: `giữ ${w.path}: ${why}` };
+  let unlocked = '';
+  if (s.lock && s.lock.stale) {
+    const u = git(mainDir, ['worktree', 'unlock', w.path]);
+    if (!u.ok) return { removed: false, msg: `giữ ${w.path}: không mở được khoá "${INIT_LOCK}" mồ côi (${u.err || 'không rõ'})` };
+    unlocked = `; đã mở khoá "${INIT_LOCK}" mồ côi`;
+  }
   let links;
   try { links = deps.unlinkDepLinks(w.path, [w.deps_path || '.']); } catch (e) {
     return { removed: false, msg: `giữ ${w.path}: không gỡ được junction node_modules (${e.message}); KHÔNG gỡ worktree để tránh xoá xuyên junction` };
@@ -146,7 +541,7 @@ function removeMarked(w, mainDir, ctx) {
     try { deps.removeShell(w.path); } catch (e) { shell = `; còn vỏ thư mục chưa xoá được (${e.message})`; }
   }
   const unl = links.length ? `; đã gỡ junction node_modules trước` : '';
-  return { removed: true, msg: `đã gỡ worktree ${w.path} (nhánh ${w.branch || '?'} giữ nguyên${unl}${shell})` };
+  return { removed: true, msg: `đã gỡ worktree ${w.path} (nhánh ${w.branch || '?'} giữ nguyên${unl}${unlocked}${shell})` };
 }
 
 function recordWt(ctx, taskId, fields) {
@@ -171,7 +566,8 @@ function reposOfTask(events, taskId, repoDir) {
  * verdict --task accept (người dùng) / discard: gỡ worktree có dấu của đúng task. Trả các dòng báo, không ném.
  * repoDir: --repo của lệnh (nếu có) — ngoài repo đã ghi trong sự kiện worktree.
  */
-function cleanupTask(ctx, events, taskId, repoDir) {
+function cleanupTask(ctx, events, taskId, repoDir, opts) {
+  const discard = !!(opts && opts.discard);
   const lines = [];
   for (const repo of reposOfTask(events, taskId, repoDir)) {
     let info;
@@ -179,9 +575,13 @@ function cleanupTask(ctx, events, taskId, repoDir) {
     const mine = markedWorktrees(info.common).filter((w) => w.task_id === taskId);
     for (const w of mine) {
       if (!w.exists) { lines.push(`wt: ${w.path || w.name} đã mất thư mục — dọn bằng dieu-phoi wt clean --yes`); continue; }
+      // r1 s1: accept VÀ discard chỉ gỡ khi wtSafety ok (nhánh đang checkout là nhánh của task, đã merge, sạch, không agent
+      // sống, không phải slot giữ lại). Việc bỏ dở chưa merge (Q2) thuộc `wt gc --abandoned` (tag dp-archive, người dùng duyệt).
       const r = removeMarked(w, info.main, ctx);
       if (r.removed) recordWt(ctx, taskId, { action: 'remove', path: w.path, repo: info.main, reason: 'verdict' });
-      lines.push(`wt: ${r.msg}`);
+      const hint = discard && !r.removed && r.msg.includes('chưa vào nhánh bền nào')
+        ? '; việc bỏ dở chưa merge được giữ nguyên: dùng dieu-phoi wt gc (lớp abandoned: lưu tag dp-archive/... rồi gỡ khi bạn duyệt)' : '';
+      lines.push(`wt: ${r.msg}${hint}`);
     }
   }
   return lines;
@@ -220,9 +620,12 @@ function registeredOf(main) {
   const out = [];
   let cur = null;
   for (const line of r.out.split(/\r?\n/)) {
-    if (line.startsWith('worktree ')) { cur = { path: line.slice(9), branch: null, detached: false }; out.push(cur); }
+    if (line.startsWith('worktree ')) { cur = { path: line.slice(9), branch: null, detached: false, locked: null, prunable: false }; out.push(cur); }
     else if (cur && line.startsWith('branch ')) cur.branch = line.slice(7).replace(/^refs\/heads\//, '');
     else if (cur && line === 'detached') cur.detached = true;
+    // r1 s1: `locked` (không lý do → '') hoặc `locked <lý do>`; null = không khoá.
+    else if (cur && (line === 'locked' || line.startsWith('locked '))) cur.locked = line.slice(7);
+    else if (cur && (line === 'prunable' || line.startsWith('prunable '))) cur.prunable = true;
   }
   return out;
 }
@@ -276,7 +679,7 @@ function reusableLines(ctx, main, common) {
     if (v === 'pass' || v === 'accept') why = `verdict ${v}`;
     else if (v !== undefined && !NOT_DONE.has(v) && branchMerged(main, w.branch)) why = 'nhánh đã vào HEAD';
     if (!why) continue;
-    if (liveAgentInWorktree(ctx, w.path)) continue;
+    if (liveAgentInWorktree(ctx, w.path, taskIdsOfWorktree(w.path, w.branch, w))) continue;
     if (dirtyOf(w.path) !== false) continue;
     rows.push(`  - ${w.path} task=${w.task_id} nhánh=${w.branch || '?'} (${why})`);
   }
@@ -340,13 +743,33 @@ function wtAdd(opts) {
   if (fs.existsSync(wtPath)) throw new Error(`wt add: ${wtPath} đã tồn tại`);
   const branch = typeof opts.branch === 'string' && opts.branch ? opts.branch : `${BRANCH_PREFIX}${taskId}`;
   const r = git(main, ['worktree', 'add', '-b', branch, wtPath, ...(base ? [base] : [])]);
-  if (!r.ok) throw new Error(`git worktree add lỗi: ${r.err || 'không rõ'}`);
-  const adminDir = git(wtPath, ['rev-parse', '--path-format=absolute', '--git-dir']).out;
+  const mark = { task_id: taskId, root: main, created_ts: core.nowIso(), branch, deps: 'none', deps_path: depsPath };
+  // Q3: --path tự đặt (khác tên mặc định do wt add sinh) → slot giữ lại, không bao giờ tự gỡ.
+  if (pathKey(wtPath) !== pathKey(path.join(path.dirname(main), `${path.basename(main)}-wt-${taskId}`))) mark.keep = true;
+  if (!r.ok) {
+    // r1 s1: git có thể đã đăng ký worktree (và khoá "initializing") trước khi lỗi/bị giết → vẫn ghi dấu + mở khoá,
+    // để discard / wt clean nhận ra, không để lại worktree mồ côi.
+    const adm = fs.existsSync(wtPath) && registeredEntry(main, wtPath) ? adminDirOf(wtPath, common) : null;
+    if (adm) {
+      fs.writeFileSync(path.join(adm, MARK), `${JSON.stringify(mark, null, 2)}\n`);
+      const e = registeredEntry(main, wtPath);
+      if (e && e.locked === INIT_LOCK) git(main, ['worktree', 'unlock', wtPath]);
+      recordWt(ctx, taskId, { action: 'add', path: wtPath, repo: main, branch, deps: 'none' });
+      throw new Error(`git worktree add lỗi: ${r.err || 'không rõ'}. Worktree ${wtPath} đã được đăng ký dở nên đã ghi dấu task ${taskId}; dọn bằng dieu-phoi discard --task ${taskId} hoặc wt clean.`);
+    }
+    throw new Error(`git worktree add lỗi: ${r.err || 'không rõ'}`);
+  }
+  const adminDir = adminDirOf(wtPath, common);
   if (!adminDir) throw new Error(`worktree ${wtPath} tạo xong nhưng không đọc được git-dir để ghi dấu`);
   const markPath = path.join(adminDir, MARK);
-  const mark = { task_id: taskId, root: main, created_ts: core.nowIso(), branch, deps: 'none', deps_path: depsPath };
   // Dấu ghi trước khi chuẩn bị deps: nếu chết giữa chừng, worktree vẫn có dấu để wt clean nhận ra.
   fs.writeFileSync(markPath, `${JSON.stringify(mark, null, 2)}\n`);
+  // r1 s1: git trên Windows có thể để lại khoá "initializing" nếu tiến trình bị giết giữa checkout → mở khoá và báo.
+  const lk = registeredEntry(main, wtPath);
+  if (lk && lk.locked === INIT_LOCK) {
+    const u = git(main, ['worktree', 'unlock', wtPath]);
+    notes.push(u.ok ? `Đã mở khoá "${INIT_LOCK}" git để lại trên ${wtPath}.` : `CẢNH BÁO: ${wtPath} còn khoá "${INIT_LOCK}" và không mở được (${u.err || 'không rõ'}); chạy git worktree unlock "${wtPath}".`);
+  }
   const d = deps.setupDeps({ main, wtPath, mode: depsMode, depsPath });
   if (d.deps !== 'none') {
     mark.deps = d.deps;
@@ -380,13 +803,16 @@ function wtClean(opts) {
     .map((e) => e.task_id));
   const gone = agg.discardedTaskIds(events);
   const rows = [];
+  const reg = registeredOf(main);
   for (const w of markedWorktrees(common)) {
     let why = null;
     if (!w.exists) why = 'thư mục đã mất';
     else if (accepted.has(w.task_id)) why = 'đã nghiệm thu';
     else if (gone.has(w.task_id)) why = 'đã loại (discard)';
-    else if (ageMsOf(w) >= staleDays * DAY_MS && branchMerged(main, w.branch) && dirtyOf(w.path) === false) {
-      why = `cũ ≥ ${staleDays} ngày, nhánh đã merge vào HEAD`;
+    else if (ageMsOf(w) >= staleDays * DAY_MS) {
+      // r1 s1: "đã merge" xét theo nhánh đang checkout THẬT, vào một ref bền bất kỳ (không chỉ HEAD checkout chính).
+      const sf = safetyOfMarked(ctx, main, w, { requireMerged: true }, reg);
+      if (sf.merged && sf.dirty === false) why = `cũ ≥ ${staleDays} ngày, nhánh đã merge (${sf.branch_now} vào ${sf.merged_into[0]})`;
     }
     if (why) rows.push(Object.assign({}, w, { why }));
   }
@@ -404,12 +830,12 @@ function wtClean(opts) {
       } else lines.push(`sẽ bỏ đăng ký ${w.path || w.name}: ${label}`);
       continue;
     }
-    const busy = liveAgentInWorktree(ctx, w.path);
-    if (busy) { lines.push(`giữ ${w.path}: đang là cwd của agent sống (${busy}) — ${label}`); continue; }
-    const dirty = dirtyOf(w.path);
-    if (dirty !== false) { lines.push(`giữ ${w.path}: ${dirty ? 'còn thay đổi chưa commit' : 'không đọc được trạng thái git'} — ${label}`); continue; }
+    // r1 s1: cùng vị từ wtSafety cho dry-run lẫn --yes (kể cả task bị loại: chưa merge thì để lớp abandoned của gc xử lý).
+    const ropts = { anyBranch: w.why.startsWith('cũ ≥') };
+    const hold = keepReason(w, safetyOfMarked(ctx, main, w, ropts, reg), ropts);
+    if (hold) { lines.push(`giữ ${w.path}: ${hold} — ${label}`); continue; }
     if (!apply) { lines.push(`sẽ gỡ ${w.path}: ${label}`); continue; }
-    const r = removeMarked(w, main, ctx);
+    const r = removeMarked(w, main, ctx, ropts);
     if (r.removed) recordWt(ctx, w.task_id, { action: 'remove', path: w.path, repo: main, reason: w.why });
     lines.push(`${r.msg}: ${label}`);
   }
@@ -478,21 +904,20 @@ function mergedPlan(ctx, main, common, events) {
   const tsOf = (w) => (w.created_ts && Number.isFinite(Date.parse(w.created_ts)) ? Date.parse(w.created_ts) : Infinity);
   const go = [];
   const kept = [];
+  const reg = registeredOf(main);
   for (const w of markedWorktrees(common).sort((a, b) => tsOf(a) - tsOf(b))) {
     if (!w.exists || !w.branch || pathKey(w.path) === pathKey(main)) continue;
-    if (!branchMerged(main, w.branch)) continue;
+    // r1 s1: xét theo nhánh đang checkout THẬT (có thể đã đổi khỏi nhánh của dấu) và ref bền bất kỳ, qua wtSafety.
+    const sf = safetyOfMarked(ctx, main, w, { requireMerged: true }, reg);
+    if (!sf.merged) continue;
     const v = last.get(w.task_id);
     let why = null;
     if (ageMsOf(w) < MERGED_MIN_AGE_MS) why = 'mới tạo dưới 1 giờ';
     else if (v === undefined) why = 'chưa có verdict';
     else if (NOT_DONE.has(v)) why = `verdict ${v}`;
-    else {
-      const busy = liveAgentInWorktree(ctx, w.path);
-      if (busy) why = `đang là cwd của agent sống (${busy})`;
-      else if (dirtyOf(w.path) !== false) why = 'còn thay đổi chưa commit hoặc không đọc được trạng thái git';
-    }
+    else if (!sf.ok) why = sf.why;
     if (why) kept.push({ w, why });
-    else go.push(w);
+    else go.push(Object.assign({}, w, { branch_now: sf.branch_now }));
   }
   return { go, kept };
 }
@@ -511,12 +936,18 @@ function mergedRun(ctx, main, common, apply) {
       lines.push(`sẽ gỡ ${w.path} và xoá nhánh (git branch -d): ${label} (đã merge, có verdict, sạch, không agent sống)`);
       continue;
     }
-    const r = removeMarked(w, main, ctx);
+    const r = removeMarked(w, main, ctx, { anyBranch: true });
     if (!r.removed) { lines.push(`${r.msg}: ${label}`); continue; }
     removed++;
     recordWt(ctx, w.task_id, { action: 'remove', path: w.path, repo: main, reason: 'merged' });
-    const b = git(main, ['branch', '-d', w.branch]);
-    lines.push(`đã gỡ worktree ${w.path}; ${b.ok ? `đã xoá nhánh ${w.branch} (git branch -d)` : `giữ nhánh ${w.branch}: git branch -d lỗi (${b.err || 'không rõ'})`}: ${label}`);
+    // Nhánh của dấu chỉ bị `git branch -d` nếu nó cũng đã vào một ref bền (nhánh đã đổi sang cái khác thì có thể chưa).
+    let brMsg;
+    if (!mergedAnywhere(main, w.branch).merged) brMsg = `giữ nhánh ${w.branch}: chưa vào nhánh bền nào`;
+    else {
+      const b = git(main, ['branch', '-d', w.branch]);
+      brMsg = b.ok ? `đã xoá nhánh ${w.branch} (git branch -d)` : `giữ nhánh ${w.branch}: git branch -d lỗi (${b.err || 'không rõ'})`;
+    }
+    lines.push(`đã gỡ worktree ${w.path}; ${brMsg}: ${label}`);
   }
   return { n: go.length, removed, lines };
 }
@@ -562,15 +993,59 @@ function mergedAfterAccept(ctx, taskIds, repoDir, clean) {
   return lines;
 }
 
+/**
+ * r1 s5 (a): sau verdict accept của người dùng — gc lớp safe giới hạn ở repo của các task vừa nghiệm thu, in những gì đã gỡ.
+ * wt_auto_gc=off → quay về hành vi cũ (nhắc / --clean-merged). --clean-merged giữ làm bí danh (gc safe bao trùm nó).
+ */
+function gcAfterAccept(ctx, taskIds, repoDir, legacyClean) {
+  if (core.autoGcModeOf(ctx) === 'off') return mergedAfterAccept(ctx, taskIds, repoDir, legacyClean === true);
+  const lines = [];
+  try {
+    const events = core.readEvents(ctx);
+    const dirs = new Set();
+    for (const id of taskIds) {
+      for (const r of reposOfTask(events, id, repoDir)) {
+        try { dirs.add(mainCheckoutOf(r).main); } catch (e) { lines.push('wt gc: bỏ qua ' + r + ' (' + e.message + ')'); }
+      }
+    }
+    if (!dirs.size) return lines;
+    const G = require('./wtgc.cjs');
+    const rep = G.autoGc(ctx, { repoDirs: Array.from(dirs), trigger: 'verdict', budgetMs: 20000 });
+    for (const r of rep.repos) {
+      for (const l of r.applied || []) if (/^đã (gỡ|xoá|git worktree prune)/.test(l)) lines.push('wt gc (tự động, lớp safe) ' + r.repo + ': ' + l);
+      if (r.error) lines.push('wt gc: ' + r.repo + ' lỗi: ' + r.error);
+    }
+    const c = rep.counts || {};
+    lines.push('wt gc (tự động, lớp safe): đã gỡ ' + rep.removed + ' mục, ~' + G.fmtBytes(rep.reclaimed_bytes) + '; còn giữ ' + (c.abandoned || 0) + ' bỏ dở / ' + (c['keep-slot'] || 0) + ' slot / ' + (c.keep || 0) + ' khác (không tự gỡ; xem: dieu-phoi wt gc --repo <repo> --measure)');
+  } catch (e) {
+    lines.push('wt gc (tự động): bỏ qua (' + e.message + ')');
+  }
+  return lines;
+}
+
 function cmdWt(opts) {
   const sub = opts._[0];
-  if (sub === 'add') return wtAdd(opts);
+  if (sub === 'add') {
+    const out = wtAdd(opts);
+    try { repos.recordRepo(ctxOf(opts).paths.data, opts.repo || process.cwd(), 'wt'); } catch (_) { /* sổ repo: best effort */ }
+    return out;
+  }
   if (sub === 'clean') return opts.merged === true ? wtCleanMerged(opts) : wtClean(opts);
   if (sub === 'list') return wtList(opts);
+  if (sub === 'repos') return repos.cmdRepos(opts, ctxOf(opts));
+  if (sub === 'gc') return require('./wtgc.cjs').cmdGc(opts); // r1 s3: tự dọn mọi repo đã chạm
   throw new Error('Cú pháp: dieu-phoi wt add --task <task_id> [--repo r] [--path dir] [--branch b] [--base ref] [--force] [--deps auto|link|install|none] [--deps-path dir]\n'
     + '         dieu-phoi wt clean [--repo r] [--stale-days N] [--yes]\n'
     + '         dieu-phoi wt clean --merged [--repo r] [--yes]\n'
-    + '         dieu-phoi wt list [--repo r] [--all] [--json]');
+    + '         dieu-phoi wt list [--repo r] [--all] [--json]\n'
+    + '         dieu-phoi wt repos [--seed <thư mục…>] [--json]\n'
+    + '         dieu-phoi wt gc [--repo r | --all-repos] [--yes] [--json] [--no-measure]');
 }
 
-module.exports = { cmdWt, cleanupTask, mergedAfterAccept, mainCheckoutOf, markedWorktrees, registeredOf, liveAgentInWorktree, MARK };
+module.exports = {
+  walkNewest,
+  cmdWt, cleanupTask, mergedAfterAccept, gcAfterAccept, mainCheckoutOf, markedWorktrees, registeredOf, liveAgentInWorktree, MARK,
+  prefetchDirty, clearDirtyCache, wtSafety, safetyOfMarked, mergedAnywhere, durablePolicy, registeredEntry, adminDirOf, liveActivityOf, taskIdsOfWorktree, idleMsOf, newestFileMtimeMs, setGitDeadline,
+  // r1 s3: dùng bởi lib/wtgc.cjs
+  gitRun: git, realKey, dirtyOf, isTempBranch, keepSlotReason, isAutoName, numSetting, ageMsOf, recordWt, NOT_DONE, MERGED_MIN_AGE_MS,
+};