@link-assistant/hive-mind 1.73.9 → 1.74.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @link-assistant/hive-mind
 
+## 1.74.0
+
+### Minor Changes
+
+- b00a51c: feat(cleanup): add a task-aware `cleanup` command to free disk space safely (#1848)
+
+  Adds a new `cleanup` bin that removes stale hive-mind temporary
+  directories/files under the system temp dir while preserving folders that belong
+  to currently-running tasks, protected system paths, and any clone with
+  uncommitted or unpushed work.
+
+  Highlights:
+  - `--dry-run` / `-n` prints the full list of kept folders and folders that would
+    be deleted (with sizes and reasons), deleting nothing.
+  - `--keep-active-tasks-folders` (default on) detects active tasks from running
+    processes (`/proc`) and live isolation sessions (`screen`/`tmux` +
+    `$ --status`), and matches clones to tasks by branch name using the same logic
+    as `solve` (issue → `issue-{n}-{hex}` scoped to the repo; PR → its resolved
+    head branch). Disable with `--no-keep-active-tasks-folders`.
+  - Keeps `/tmp/start-command/` and system-owned temp entries by default;
+    `--force-start-command` allows deleting `/tmp/start-command` when needed.
+  - Optional Ubuntu/system cleanup behind explicit flags: `--apt`, `--journal`,
+    `--docker`, `--npm` (and `--system` shorthand), with `--sudo`.
+  - Safe by default: keeps unrecognised entries unless `--all`, never deletes
+    paths held open by a running process or used by the cleanup process itself,
+    and requires confirmation unless `--force`.
+
 ## 1.73.9
 
 ### Patch Changes

package/README.hi.md

@@ -717,6 +717,42 @@ solve https://github.com/owner/repo/issues/123 --resume 657e6db1-6eb3-4a8d
 (cd /tmp/gh-issue-solver-123456789 && claude --resume session-id)
 ```
 
+### डिस्क क्लीनअप
+
+`cleanup` पुरानी hive-mind अस्थायी डायरेक्टरी/फ़ाइलों (जैसे प्रति-कार्य क्लोन
+`/tmp/gh-issue-solver-*`, MCP कॉन्फ़िग फ़ाइलें, लॉग डाउनलोड डायरेक्टरी आदि) को हटाकर
+डिस्क स्थान खाली करता है, जबकि **वर्तमान में चल रहे कार्यों से संबंधित फ़ोल्डर**,
+सुरक्षित सिस्टम पथ, और बिना कमिट या बिना पुश किए बदलावों वाले किसी भी क्लोन को बनाए
+रखता है। यह चल रही प्रक्रियाओं और लाइव आइसोलेशन सेशन से सक्रिय कार्यों का पता लगाता है
+और `solve` के समान लॉजिक का उपयोग करते हुए शाखा नाम द्वारा क्लोन को कार्यों से मिलाता
+है (issue → `issue-{n}-{hex}`; PR → इसकी हल की गई head शाखा)।
+
+```bash
+# पूर्वावलोकन: रखे जाने वाले और हटाए जाने वाले फ़ोल्डरों की सूची (कुछ भी नहीं हटाता)
+cleanup --dry-run
+
+# पुरानी अस्थायी फ़ाइलें वास्तव में हटाएँ (पहले पुष्टि माँगता है)
+cleanup
+
+# पुष्टि प्रॉम्प्ट के बिना हटाएँ
+cleanup --force
+
+# गैर-hive-mind अस्थायी प्रविष्टियों पर भी विचार करें (अधिक आक्रामक)
+cleanup --all --dry-run
+
+# /tmp/start-command को हटाने की अनुमति दें (डिफ़ॉल्ट रूप से रखा जाता है; इसमें आइसोलेशन लॉग होते हैं)
+cleanup --force-start-command
+
+# Ubuntu / सिस्टम क्लीनअप (apt कैश, journald लॉग, npm कैश)
+cleanup --system --sudo
+
+# सक्रिय-कार्य पहचान अक्षम करें (केवल सुरक्षित पथ रखे जाते हैं)
+cleanup --no-keep-active-tasks-folders --dry-run
+```
+
+विकल्पों की पूरी सूची के लिए `cleanup --help` चलाएँ। यह कमांड dry-run के अनुकूल है और
+हर रन के लिए टाइमस्टैम्प वाला `cleanup-*.log` लिखता है।
+
 ## 🔍 निगरानी और लॉगिंग
 
 लॉग में resume कमांड खोजें:

package/README.md

@@ -737,6 +737,43 @@ solve https://github.com/owner/repo/issues/123 --resume 657e6db1-6eb3-4a8d
 (cd /tmp/gh-issue-solver-123456789 && claude --resume session-id)
 ```
 
+### Disk Cleanup
+
+`cleanup` frees disk space by removing stale hive-mind temporary
+directories/files (per-task clones like `/tmp/gh-issue-solver-*`, MCP config
+files, log download dirs, …) while **keeping folders that belong to
+currently-running tasks**, protected system paths, and any clone with
+uncommitted or unpushed work. It detects active tasks from running processes and
+live isolation sessions and matches clones to tasks by branch name using the
+same logic as `solve` (issue → `issue-{n}-{hex}`; PR → its resolved head
+branch).
+
+```bash
+# Preview: list kept folders and folders that would be deleted (deletes nothing)
+cleanup --dry-run
+
+# Actually delete stale temp artifacts (asks for confirmation first)
+cleanup
+
+# Delete without the confirmation prompt
+cleanup --force
+
+# Also consider non-hive-mind temp entries (more aggressive)
+cleanup --all --dry-run
+
+# Allow deleting /tmp/start-command (kept by default; holds isolation logs)
+cleanup --force-start-command
+
+# Ubuntu / system cleanup (apt caches, journald logs, npm cache)
+cleanup --system --sudo
+
+# Disable active-task detection (only protected paths are kept)
+cleanup --no-keep-active-tasks-folders --dry-run
+```
+
+Run `cleanup --help` for the full list of options. The command is dry-run
+friendly and writes a timestamped `cleanup-*.log` for every run.
+
 ## 🔍 Monitoring & Logging
 
 Find resume commands in logs:

package/README.ru.md

@@ -719,6 +719,43 @@ solve https://github.com/owner/repo/issues/123 --resume 657e6db1-6eb3-4a8d
 (cd /tmp/gh-issue-solver-123456789 && claude --resume session-id)
 ```
 
+### Очистка диска
+
+`cleanup` освобождает место на диске, удаляя устаревшие временные каталоги/файлы
+hive-mind (клоны для каждой задачи вида `/tmp/gh-issue-solver-*`, файлы
+конфигурации MCP, каталоги загрузки логов и т. д.), при этом **сохраняя папки,
+относящиеся к выполняющимся в данный момент задачам**, защищённые системные пути и
+любой клон с незакоммиченными или неотправленными изменениями. Он обнаруживает
+активные задачи по запущенным процессам и активным сессиям изоляции и сопоставляет
+клоны с задачами по имени ветки, используя ту же логику, что и `solve`
+(issue → `issue-{n}-{hex}`; PR → его разрешённая head-ветка).
+
+```bash
+# Предпросмотр: список сохраняемых и удаляемых папок (ничего не удаляет)
+cleanup --dry-run
+
+# Реально удалить устаревшие временные файлы (сначала запросит подтверждение)
+cleanup
+
+# Удалить без запроса подтверждения
+cleanup --force
+
+# Учитывать также не-hive-mind временные записи (более агрессивно)
+cleanup --all --dry-run
+
+# Разрешить удаление /tmp/start-command (по умолчанию сохраняется; хранит логи изоляции)
+cleanup --force-start-command
+
+# Очистка Ubuntu / системы (кэши apt, логи journald, кэш npm)
+cleanup --system --sudo
+
+# Отключить обнаружение активных задач (сохраняются только защищённые пути)
+cleanup --no-keep-active-tasks-folders --dry-run
+```
+
+Запустите `cleanup --help`, чтобы увидеть полный список опций. Команда удобна для
+режима dry-run и записывает лог `cleanup-*.log` с меткой времени при каждом запуске.
+
 ## 🔍 Мониторинг и логирование
 
 Найдите команды возобновления в логах:

package/README.zh.md

@@ -713,6 +713,41 @@ solve https://github.com/owner/repo/issues/123 --resume 657e6db1-6eb3-4a8d
 (cd /tmp/gh-issue-solver-123456789 && claude --resume session-id)
 ```
 
+### 磁盘清理
+
+`cleanup` 通过删除过时的 hive-mind 临时目录/文件（如每个任务的克隆
+`/tmp/gh-issue-solver-*`、MCP 配置文件、日志下载目录等）来释放磁盘空间，同时
+**保留属于当前正在运行任务的文件夹**、受保护的系统路径，以及任何包含未提交或未推送
+更改的克隆。它通过运行中的进程和实时隔离会话检测活动任务，并使用与 `solve` 相同的
+逻辑按分支名称将克隆与任务匹配（issue → `issue-{n}-{hex}`；PR → 其解析出的 head
+分支）。
+
+```bash
+# 预览：列出保留的文件夹和将被删除的文件夹（不删除任何内容）
+cleanup --dry-run
+
+# 实际删除过时的临时文件（会先要求确认）
+cleanup
+
+# 删除时不显示确认提示
+cleanup --force
+
+# 同时考虑非 hive-mind 临时项（更激进）
+cleanup --all --dry-run
+
+# 允许删除 /tmp/start-command（默认保留；其中存放隔离日志）
+cleanup --force-start-command
+
+# Ubuntu / 系统清理（apt 缓存、journald 日志、npm 缓存）
+cleanup --system --sudo
+
+# 禁用活动任务检测（仅保留受保护的路径）
+cleanup --no-keep-active-tasks-folders --dry-run
+```
+
+运行 `cleanup --help` 查看完整的选项列表。该命令对 dry-run 友好，并为每次运行写入
+带时间戳的 `cleanup-*.log` 日志。
+
 ## 🔍 监控与日志
 
 在日志中查找恢复命令：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.73.9",
+  "version": "1.74.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -8,6 +8,7 @@
     "hive": "./src/hive.mjs",
     "solve": "./src/solve.mjs",
     "task": "./src/task.mjs",
+    "cleanup": "./src/cleanup.mjs",
     "review": "./src/review.mjs",
     "configure-claude": "./src/configure-claude.mjs",
     "start-screen": "./src/start-screen.mjs",

package/src/cleanup.lib.mjs

@@ -0,0 +1,359 @@
+/**
+ * Core, offline-testable logic for the `cleanup` command (issue #1848).
+ *
+ * This module deliberately avoids any top-level network access (no `use-m`
+ * fetch) and any side effects so it can be unit-tested without a network
+ * connection or a real filesystem. All OS interaction (reading /tmp, querying
+ * `$ --status`, scanning /proc, deleting paths, apt cleanup) lives in
+ * `cleanup.os.lib.mjs` / `cleanup.mjs`; this module only contains pure
+ * classification, parsing and formatting helpers.
+ *
+ * The classification mirrors the manual workflow described in the issue: list
+ * the temporary directories under the tmp root, figure out which ones belong to
+ * currently-running solve tasks (by branch name, the same way solve.mjs derives
+ * branches), and keep those while removing the rest. Protected system paths such
+ * as `/tmp/start-command/` are always preserved unless explicitly forced.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1848
+ */
+
+import { isValidIssueBranchName } from './solve.branch.lib.mjs';
+
+/**
+ * Directory names directly under the tmp root that must never be removed by
+ * default because deleting them would interfere with the system's ability to
+ * run or be debugged. `start-command` holds the isolation session logs that
+ * `$ --status`, /log and /terminal_watch rely on.
+ */
+export const DEFAULT_PROTECTED_NAMES = ['start-command'];
+
+/**
+ * System-owned temp entries that we never touch even in `--all` mode unless the
+ * user explicitly opts in. These are created by the OS / desktop / language
+ * runtimes and removing them mid-flight can break unrelated processes.
+ */
+export const SYSTEM_PROTECTED_PATTERNS = [/^\.X11-unix$/, /^\.XIM-unix$/, /^\.ICE-unix$/, /^\.font-unix$/, /^\.Test-unix$/, /^systemd-private-/, /^snap-private-tmp$/, /^snap\./, /^\.snap/, /^dbus-/, /^ssh-/, /^hsperfdata_/, /^\.org\.chromium\./, /^\.com\.google\.Chrome\./];
+
+/**
+ * Patterns for temporary entries that are unambiguously created by hive-mind
+ * (solve.mjs, github.lib.mjs, claude.lib.mjs, telegram-*, etc.). These are safe
+ * to delete when they are not tied to an active task. Each entry has a `name`
+ * (for reporting) and a `regex` matched against the basename under the tmp root.
+ *
+ * Sources are referenced inline so future maintainers can keep this list in
+ * sync with the code that produces the files.
+ */
+export const HIVE_MIND_TEMP_PATTERNS = [
+  // solve.repository.lib.mjs / solve.execution.lib.mjs workspace clones
+  { name: 'solve workspace clone', regex: /^gh-issue-solver-\d+$/ },
+  { name: 'solve resume workspace', regex: /^gh-issue-solver-resume-.+$/ },
+  // solve.repository.lib.mjs buildWorkspacePath parent dir
+  { name: 'solve workspace root', regex: /^hive-mind-solve-gh-/ },
+  // github.lib.mjs log download working dirs
+  { name: 'solution draft log dir', regex: /^log-tmp-solution-draft-log-/ },
+  // claude.lib.mjs MCP config temp files
+  { name: 'claude MCP config', regex: /^claude-mcp-no-useless-.+\.json$/ },
+  { name: 'claude MCP config', regex: /^claude-mcp-.+\.json$/ },
+  // github.lib.mjs comment / body temp files
+  { name: 'solution draft log', regex: /^solution-draft-log-.+\.txt$/ },
+  { name: 'log upload comment', regex: /^log-upload-comment-.+\.md$/ },
+  { name: 'log comment', regex: /^log-comment-.+\.md$/ },
+  // github-error-reporter.lib.mjs
+  { name: 'issue body temp', regex: /^hive-mind-issue-body-.+\.md$/ },
+  // solve.auto-pr.lib.mjs / solve.results.lib.mjs
+  { name: 'PR body temp', regex: /^pr-body-.+$/ },
+  { name: 'PR title temp', regex: /^pr-title-.+\.txt$/ },
+  // solve.progress-monitoring.lib.mjs
+  { name: 'PR progress temp', regex: /^pr-progress-.+$/ },
+  // telegram-top-command.lib.mjs
+  { name: 'telegram top output', regex: /^top-output-.+\.txt$/ },
+  // start-screen.mjs
+  { name: 'screen ready marker', regex: /^screen-ready-.+\.marker$/ },
+];
+
+/**
+ * Parse a GitHub issue/PR URL out of an arbitrary string (e.g. a solve command
+ * line). Self-contained so this module stays offline-safe (github.lib.mjs is
+ * not import-safe because of its top-level use-m fetch).
+ *
+ * @param {string} url
+ * @returns {{owner: string, repo: string, type: 'issue'|'pull', number: number}|null}
+ */
+export function parseTaskUrl(url) {
+  if (!url || typeof url !== 'string') return null;
+  const match = url.match(/github\.com[/:]([^/\s]+)\/([^/\s#]+?)(?:\.git)?\/(issues|issue|pull|pulls)\/(\d+)/i);
+  if (!match) return null;
+  const type = /^pull/i.test(match[3]) ? 'pull' : 'issue';
+  return {
+    owner: match[1],
+    repo: match[2],
+    type,
+    number: Number(match[4]),
+  };
+}
+
+/**
+ * Extract all GitHub issue/PR references from a command line string. A solve
+ * command typically takes the URL as its first positional argument, but we scan
+ * the whole string to be tolerant of flag ordering.
+ *
+ * @param {string} command
+ * @returns {Array<{owner: string, repo: string, type: 'issue'|'pull', number: number}>}
+ */
+export function extractTaskRefsFromCommand(command) {
+  if (!command || typeof command !== 'string') return [];
+  const refs = [];
+  const seen = new Set();
+  const re = /github\.com[/:]([^/\s]+)\/([^/\s#]+?)(?:\.git)?\/(issues|issue|pull|pulls)\/(\d+)/gi;
+  let m;
+  while ((m = re.exec(command)) !== null) {
+    const ref = parseTaskUrl(m[0]);
+    if (!ref) continue;
+    const key = `${ref.owner}/${ref.repo}#${ref.number}:${ref.type}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    refs.push(ref);
+  }
+  return refs;
+}
+
+/**
+ * Normalise an owner/repo pair extracted from a git remote URL.
+ *
+ * @param {string} remoteUrl
+ * @returns {{owner: string, repo: string}|null}
+ */
+export function parseRemoteUrl(remoteUrl) {
+  if (!remoteUrl || typeof remoteUrl !== 'string') return null;
+  // git@github.com:owner/repo.git  OR  https://github.com/owner/repo(.git)
+  const sshMatch = remoteUrl.match(/^[^@]+@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+  const httpMatch = remoteUrl.match(/^[a-z]+:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?$/i);
+  if (httpMatch) return { owner: httpMatch[1], repo: httpMatch[2] };
+  return null;
+}
+
+function sameRepo(a, b) {
+  if (!a || !b) return false;
+  return a.owner.toLowerCase() === b.owner.toLowerCase() && a.repo.toLowerCase() === b.repo.toLowerCase();
+}
+
+/**
+ * Build the set of "active task matchers" from the running session task list.
+ * For PR tasks the resolved head branch is matched exactly; for issue tasks we
+ * fall back to the `issue-{number}-{hex}` prefix (the random hex is unknown from
+ * the URL alone) combined with a repo match.
+ *
+ * @param {Array<{owner, repo, type, number, branch?: string|null}>} activeTasks
+ * @returns {Array<{owner, repo, type, issueNumber: number|null, branch: string|null}>}
+ */
+export function buildActiveMatchers(activeTasks) {
+  const matchers = [];
+  for (const task of activeTasks || []) {
+    if (!task) continue;
+    matchers.push({
+      owner: task.owner,
+      repo: task.repo,
+      type: task.type,
+      issueNumber: task.type === 'issue' ? task.number : (task.issueNumber ?? null),
+      branch: task.branch || null,
+    });
+  }
+  return matchers;
+}
+
+/**
+ * Decide whether a folder's git info matches one of the active task matchers.
+ *
+ * @param {{branch: string|null, remotes: Array<{owner, repo}>}|null} gitInfo
+ * @param {Array} matchers - from buildActiveMatchers
+ * @returns {Object|null} the matched matcher, or null
+ */
+export function folderMatchesActiveTask(gitInfo, matchers) {
+  if (!gitInfo || !Array.isArray(matchers)) return null;
+  const remotes = gitInfo.remotes || [];
+  for (const m of matchers) {
+    // 1. Exact branch match (covers PR continue-mode and any known branch).
+    if (m.branch && gitInfo.branch && gitInfo.branch === m.branch) {
+      return m;
+    }
+    // 2. issue-{number}-{hex} prefix match scoped to the same repository.
+    if (m.issueNumber != null && gitInfo.branch && isValidIssueBranchName(gitInfo.branch, m.issueNumber)) {
+      const repoMatches = remotes.length === 0 || remotes.some(r => sameRepo(r, m));
+      if (repoMatches) return m;
+    }
+  }
+  return null;
+}
+
+function matchesAny(name, patterns) {
+  return patterns.some(p => (p.regex || p).test(name));
+}
+
+/**
+ * Identify the hive-mind temp pattern a name matches, if any.
+ *
+ * @param {string} name
+ * @returns {{name: string}|null}
+ */
+export function matchHiveMindPattern(name) {
+  return HIVE_MIND_TEMP_PATTERNS.find(p => p.regex.test(name)) || null;
+}
+
+/**
+ * Pure classification of a single temp entry into keep/remove with a reason.
+ *
+ * Reason precedence (highest first): protected > self > active-process >
+ * active-task > dirty-worktree > hive-mind-temp (remove) > all-mode (remove) >
+ * unrecognized (keep).
+ *
+ * @param {{name: string, path: string, isDirectory: boolean}} entry
+ * @param {Object} ctx
+ * @param {string[]} ctx.protectedNames
+ * @param {boolean} ctx.forceStartCommand
+ * @param {boolean} ctx.includeSystem - allow classifying system entries in --all
+ * @param {boolean} ctx.includeAll - consider non-hive-mind entries for removal
+ * @param {boolean} ctx.keepDirty
+ * @param {Set<string>} ctx.selfPaths - absolute paths the cleanup process itself uses
+ * @param {Set<string>} ctx.heldPaths - absolute paths held by running processes
+ * @param {Array} ctx.matchers - active task matchers
+ * @param {Map<string,{branch, remotes, dirty}>} ctx.gitInfoByPath
+ * @returns {{action: 'keep'|'remove', reason: string}}
+ */
+export function classifyEntry(entry, ctx) {
+  const { protectedNames = DEFAULT_PROTECTED_NAMES, forceStartCommand = false, includeSystem = false, includeAll = false, keepDirty = true, selfPaths = new Set(), heldPaths = new Set(), matchers = [], gitInfoByPath = new Map() } = ctx || {};
+
+  const name = entry.name;
+
+  // 1. Protected names (start-command can be forced).
+  const isStartCommand = name === 'start-command';
+  if (protectedNames.includes(name)) {
+    if (isStartCommand && forceStartCommand) {
+      // fall through to deletion logic below
+    } else {
+      return { action: 'keep', reason: 'protected' };
+    }
+  }
+
+  // 1b. System-owned entries are protected unless explicitly included.
+  if (!includeSystem && matchesAny(name, SYSTEM_PROTECTED_PATTERNS)) {
+    return { action: 'keep', reason: 'system-protected' };
+  }
+
+  // 2. Paths the cleanup process itself depends on (its own clone / cwd).
+  if (selfPaths.has(entry.path)) {
+    return { action: 'keep', reason: 'self' };
+  }
+
+  // 3. Held open / used as cwd by a running process.
+  if (heldPaths.has(entry.path)) {
+    return { action: 'keep', reason: 'active-process' };
+  }
+
+  // 4. Matches an active solve task by branch / repo.
+  const gitInfo = gitInfoByPath.get(entry.path);
+  const matched = folderMatchesActiveTask(gitInfo, matchers);
+  if (matched) {
+    return { action: 'keep', reason: 'active-task' };
+  }
+
+  // 5. Dirty / unpushed worktree: keep by default to avoid losing work.
+  if (keepDirty && gitInfo && gitInfo.dirty) {
+    return { action: 'keep', reason: 'dirty-worktree' };
+  }
+
+  // 6. Recognised hive-mind temp artifact -> safe to remove.
+  if (matchHiveMindPattern(name)) {
+    return { action: 'remove', reason: isStartCommand ? 'forced-start-command' : 'hive-mind-temp' };
+  }
+
+  // start-command forced but not a hive-mind pattern: still remove when forced.
+  if (isStartCommand && forceStartCommand) {
+    return { action: 'remove', reason: 'forced-start-command' };
+  }
+
+  // 7. --all mode removes anything not otherwise kept.
+  if (includeAll) {
+    return { action: 'remove', reason: 'all-mode' };
+  }
+
+  // 8. Default: leave unrecognised entries alone.
+  return { action: 'keep', reason: 'unrecognized' };
+}
+
+/**
+ * Classify a list of temp entries.
+ *
+ * @param {Array<{name, path, isDirectory, size?: number}>} entries
+ * @param {Object} ctx - see classifyEntry
+ * @returns {{keep: Array, remove: Array}} each item: {name, path, size, reason}
+ */
+export function classifyEntries(entries, ctx) {
+  const keep = [];
+  const remove = [];
+  for (const entry of entries || []) {
+    const { action, reason } = classifyEntry(entry, ctx);
+    const record = { name: entry.name, path: entry.path, size: entry.size ?? null, reason };
+    if (action === 'remove') remove.push(record);
+    else keep.push(record);
+  }
+  return { keep, remove };
+}
+
+/**
+ * Human-readable, base-1024 byte formatting (matches `du -h` style closely
+ * enough for reporting).
+ *
+ * @param {number|null|undefined} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes == null || Number.isNaN(bytes)) return '?';
+  if (bytes < 1024) return `${bytes}B`;
+  const units = ['K', 'M', 'G', 'T', 'P'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  const rounded = value >= 10 || Number.isInteger(value) ? Math.round(value) : Math.round(value * 10) / 10;
+  return `${rounded}${units[unit]}`;
+}
+
+/**
+ * Aggregate totals for a classification result.
+ *
+ * @param {{keep: Array, remove: Array}} classified
+ * @returns {{keepCount, removeCount, keepBytes, removeBytes}}
+ */
+export function summarize(classified) {
+  const sum = list => list.reduce((acc, item) => acc + (item.size || 0), 0);
+  return {
+    keepCount: classified.keep.length,
+    removeCount: classified.remove.length,
+    keepBytes: sum(classified.keep),
+    removeBytes: sum(classified.remove),
+  };
+}
+
+/**
+ * Human-readable label for a keep/remove reason code.
+ * @param {string} reason
+ * @returns {string}
+ */
+export function describeReason(reason) {
+  const map = {
+    protected: 'protected path',
+    'system-protected': 'system-owned temp',
+    self: 'used by this cleanup process',
+    'active-process': 'in use by a running process',
+    'active-task': 'belongs to an active task',
+    'dirty-worktree': 'has uncommitted/unpushed changes',
+    'hive-mind-temp': 'hive-mind temporary artifact',
+    'forced-start-command': 'start-command (forced)',
+    'all-mode': 'removed by --all',
+    unrecognized: 'not a recognised hive-mind artifact',
+  };
+  return map[reason] || reason;
+}

package/src/cleanup.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * `cleanup` — free disk space by removing stale hive-mind temporary
+ * directories/files while preserving folders that belong to currently-running
+ * (active) tasks, protected system paths and any work that is not yet pushed.
+ *
+ * This is the standalone command requested in issue #1848. It reproduces, in a
+ * safe and automated way, the manual workflow the maintainer used to reclaim
+ * space without restarting the server:
+ *   - list temp entries (like `du -sh /tmp/*`),
+ *   - figure out which clones belong to active solve tasks (by branch name, the
+ *     same way solve.mjs derives branches), keeping those,
+ *   - keep protected paths such as `/tmp/start-command/`,
+ *   - delete the rest.
+ *
+ * Modes:
+ *   --dry-run                     show kept + deleted lists, delete nothing
+ *   --keep-active-tasks-folders   keep folders of running tasks (default: on)
+ *   --force / -f                  skip the confirmation prompt
+ *   --all                         also consider non-hive-mind temp entries
+ *   --force-start-command         allow deleting /tmp/start-command
+ *   --include-system              also consider system-owned temp entries
+ *   --no-keep-dirty               allow deleting clones with unpushed changes
+ *   --apt --journal --docker --npm   Ubuntu/system cleanup (opt-in)
+ *   --system                      shorthand for --apt --journal --npm
+ *   --sudo                        prefix package-manager commands with sudo
+ *   --verbose / -v
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1848
+ */
+
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+import { classifyEntries, summarize, formatBytes, describeReason, buildActiveMatchers, DEFAULT_PROTECTED_NAMES } from './cleanup.lib.mjs';
+import { getTempRoot, listTempEntries, getPathSize, readFolderGitInfo, listProcessHeldPaths, getActiveTasks, removePath, runSystemCleanup } from './cleanup.os.lib.mjs';
+
+const args = process.argv.slice(2);
+
+function hasFlag(...names) {
+  return names.some(n => args.includes(n));
+}
+
+// ---------------------------------------------------------------------------
+// Early --version / --help handling (no heavy imports).
+// ---------------------------------------------------------------------------
+if (hasFlag('--version')) {
+  const { getVersion } = await import('./version.lib.mjs');
+  try {
+    console.log(await getVersion());
+  } catch {
+    console.error('Error: Unable to determine version');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (hasFlag('--help', '-h')) {
+  console.log(`Usage: cleanup [options]
+
+Free disk space by removing stale hive-mind temporary directories/files while
+keeping folders that belong to active tasks and protected system paths.
+
+Options:
+  --dry-run, -n               Show what would be kept and deleted, delete nothing
+  --keep-active-tasks-folders Keep folders of currently-running tasks [default: on]
+  --no-keep-active-tasks-folders
+                              Disable active-task detection (only protected paths kept)
+  --force, -f                 Delete without the interactive confirmation prompt
+  --all                       Also consider non-hive-mind temp entries for deletion
+  --include-system            Also consider system-owned temp entries (.X11-unix, …)
+  --force-start-command       Allow deleting /tmp/start-command (kept by default)
+  --no-keep-dirty             Allow deleting clones with uncommitted/unpushed changes
+  --no-sessions               Do not query '$ --status' for active sessions
+  --no-resolve-branches       Do not resolve PR head branches via gh
+
+System / Ubuntu cleanup (opt-in):
+  --apt                       apt-get clean / autoclean / autoremove
+  --journal                   journalctl --vacuum-time=2weeks
+  --docker                    docker system prune -f
+  --npm                       npm cache clean --force
+  --system                    Shorthand for --apt --journal --npm
+  --sudo                      Prefix package-manager commands with sudo
+
+  --verbose, -v               Verbose logging
+  --version                   Show version number
+  --help, -h                  Show this help
+`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Options.
+// ---------------------------------------------------------------------------
+const options = {
+  dryRun: hasFlag('--dry-run', '-n'),
+  keepActiveTasks: !hasFlag('--no-keep-active-tasks-folders'),
+  force: hasFlag('--force', '-f'),
+  includeAll: hasFlag('--all'),
+  includeSystem: hasFlag('--include-system'),
+  forceStartCommand: hasFlag('--force-start-command'),
+  keepDirty: !hasFlag('--no-keep-dirty'),
+  useSessions: !hasFlag('--no-sessions'),
+  resolveBranches: !hasFlag('--no-resolve-branches'),
+  verbose: hasFlag('--verbose', '-v'),
+  apt: hasFlag('--apt', '--system'),
+  journal: hasFlag('--journal', '--system'),
+  docker: hasFlag('--docker'),
+  npm: hasFlag('--npm', '--system'),
+  sudo: hasFlag('--sudo'),
+};
+
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const scriptDir = path.dirname(process.argv[1]);
+const logFile = path.join(scriptDir, `cleanup-${timestamp}.log`);
+
+async function log(message, { level = 'info' } = {}) {
+  await fsp.appendFile(logFile, `[${new Date().toISOString()}] [${level.toUpperCase()}] ${message}\n`).catch(() => {});
+  if (level === 'error') console.error(message);
+  else if (level === 'warn' || level === 'warning') console.warn(message);
+  else console.log(message);
+}
+
+function vlog(message) {
+  if (options.verbose) return log(message);
+  return fsp.appendFile(logFile, `[${new Date().toISOString()}] [DEBUG] ${message}\n`).catch(() => {});
+}
+
+/**
+ * Compute the set of absolute top-level tmp entries that the cleanup process
+ * itself depends on, so we never delete our own running clone.
+ */
+function computeSelfPaths(tempRoot) {
+  const selfPaths = new Set();
+  const normalizedRoot = tempRoot.endsWith(path.sep) ? tempRoot : tempRoot + path.sep;
+  const add = candidate => {
+    if (candidate && (candidate === tempRoot || candidate.startsWith(normalizedRoot))) {
+      const first = candidate.slice(normalizedRoot.length).split(path.sep)[0];
+      if (first) selfPaths.add(path.join(tempRoot, first));
+    }
+  };
+  add(process.cwd());
+  add(path.resolve(scriptDir));
+  add(path.resolve(process.argv[1] || ''));
+  return selfPaths;
+}
+
+async function main() {
+  await fsp.writeFile(logFile, `# Cleanup Log - ${new Date().toISOString()}\n\n`).catch(() => {});
+
+  const tempRoot = getTempRoot();
+  await log('🧹 hive-mind cleanup');
+  await log('====================\n');
+  await log(`📂 Temp root: ${tempRoot}`);
+  if (options.dryRun) await log('📝 DRY RUN — nothing will be deleted\n');
+  else if (options.force) await log('⚠️  FORCE — deleting without confirmation\n');
+
+  // 1. Enumerate candidate entries.
+  const entries = listTempEntries(tempRoot);
+  await log(`🔍 Found ${entries.length} entries under ${tempRoot}`);
+
+  // 2. Gather signals for active-task detection.
+  const heldPaths = listProcessHeldPaths(tempRoot);
+  await vlog(`Process-held paths: ${[...heldPaths].join(', ') || '(none)'}`);
+
+  let matchers = [];
+  if (options.keepActiveTasks) {
+    const activeTasks = await getActiveTasks({ useSessions: options.useSessions, resolveBranches: options.resolveBranches });
+    matchers = buildActiveMatchers(activeTasks);
+    if (activeTasks.length > 0) {
+      await log(`🏃 Active tasks detected: ${activeTasks.length}`);
+      for (const t of activeTasks) {
+        await log(`   • ${t.owner}/${t.repo} ${t.type} #${t.number}${t.branch ? ` (branch ${t.branch})` : ''}`);
+      }
+    } else {
+      await log('🏃 No active tasks detected from running processes/sessions');
+    }
+  } else {
+    await log('⚠️  Active-task detection disabled (--no-keep-active-tasks-folders)');
+  }
+
+  // 3. Read git info for directory entries (used by branch / dirty matching).
+  const gitInfoByPath = new Map();
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    const info = readFolderGitInfo(entry.path);
+    if (info) gitInfoByPath.set(entry.path, info);
+  }
+
+  const selfPaths = computeSelfPaths(tempRoot);
+  await vlog(`Self paths: ${[...selfPaths].join(', ') || '(none)'}`);
+
+  // 4. Classify.
+  const ctx = {
+    protectedNames: DEFAULT_PROTECTED_NAMES,
+    forceStartCommand: options.forceStartCommand,
+    includeSystem: options.includeSystem,
+    includeAll: options.includeAll,
+    keepDirty: options.keepDirty,
+    selfPaths,
+    heldPaths,
+    matchers,
+    gitInfoByPath,
+  };
+  const classified = classifyEntries(entries, ctx);
+
+  // 5. Compute sizes (only for what we report, to keep it reasonably fast).
+  for (const item of [...classified.keep, ...classified.remove]) {
+    item.size = getPathSize(item.path);
+  }
+  const totals = summarize(classified);
+
+  // 6. Report.
+  await log('\n🟢 KEPT folders/files:');
+  if (classified.keep.length === 0) await log('   (none)');
+  for (const item of classified.keep.sort((a, b) => (b.size || 0) - (a.size || 0))) {
+    await log(`   ${formatBytes(item.size).padStart(7)}  ${item.path}  — ${describeReason(item.reason)}`);
+  }
+
+  await log(`\n🗑️  ${options.dryRun ? 'WOULD DELETE' : 'TO DELETE'} folders/files:`);
+  if (classified.remove.length === 0) await log('   (none)');
+  for (const item of classified.remove.sort((a, b) => (b.size || 0) - (a.size || 0))) {
+    await log(`   ${formatBytes(item.size).padStart(7)}  ${item.path}  — ${describeReason(item.reason)}`);
+  }
+
+  await log(`\n📊 Summary: keep ${totals.keepCount} (${formatBytes(totals.keepBytes)}), remove ${totals.removeCount} (${formatBytes(totals.removeBytes)})`);
+
+  // 7. Execute deletion (unless dry-run).
+  if (options.dryRun) {
+    await log('\n✅ Dry run complete. Re-run without --dry-run to delete.');
+  } else if (classified.remove.length === 0) {
+    await log('\n✅ Nothing to delete.');
+  } else {
+    if (!options.force) {
+      console.log(`\n⚠️  This will permanently delete ${classified.remove.length} entries (${formatBytes(totals.removeBytes)}).`);
+      console.log('Type "yes" to confirm, or Ctrl+C to cancel:');
+      process.stdout.write('> ');
+      let answer = '';
+      try {
+        answer = execSync('read answer && echo $answer', { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'], shell: '/bin/bash' }).trim();
+      } catch {
+        await log('\n❌ Cancelled');
+        return;
+      }
+      if (answer.toLowerCase() !== 'yes') {
+        await log('\n❌ Cancelled');
+        return;
+      }
+    }
+
+    await log('\n🗑️  Deleting...');
+    let deleted = 0;
+    let failed = 0;
+    for (const item of classified.remove) {
+      const ok = removePath(item.path);
+      if (ok) {
+        deleted++;
+        await vlog(`   removed ${item.path}`);
+      } else {
+        failed++;
+        await log(`   ⚠️  failed to remove ${item.path}`, { level: 'warn' });
+      }
+    }
+    await log(`\n✅ Deleted ${deleted} entries${failed ? `, ${failed} failed` : ''}.`);
+  }
+
+  // 8. System / Ubuntu cleanup (opt-in).
+  if (options.apt || options.journal || options.docker || options.npm) {
+    await log('\n🧴 System cleanup:');
+    runSystemCleanup({
+      apt: options.apt,
+      journal: options.journal,
+      docker: options.docker,
+      npm: options.npm,
+      dryRun: options.dryRun,
+      useSudo: options.sudo,
+      logFn: msg => log(msg),
+    });
+  }
+
+  await log(`\n📁 Log file: ${logFile}`);
+}
+
+main().catch(async error => {
+  await log(`❌ Error: ${error.message}`, { level: 'error' });
+  process.exit(1);
+});

package/src/cleanup.os.lib.mjs

@@ -0,0 +1,404 @@
+/**
+ * OS-interaction layer for the `cleanup` command (issue #1848).
+ *
+ * Everything that touches the real filesystem, the process table (/proc),
+ * isolation session state (`$ --status` from start-command), git metadata of a
+ * clone, GitHub (`gh`) and system package caches lives here. The pure
+ * classification logic lives in `cleanup.lib.mjs` and is unit-tested without any
+ * of this.
+ *
+ * Implemented with `node:` built-ins + `node:child_process` so it does not
+ * depend on `use-m` / `command-stream` being reachable, except for the optional
+ * `$ --status` session query which reuses isolation-runner.lib.mjs.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1848
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+import { extractTaskRefsFromCommand, parseRemoteUrl } from './cleanup.lib.mjs';
+
+/** Run a command, returning trimmed stdout or null on any failure. */
+function tryExec(cmd, args, options = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: options.timeout ?? 20000,
+      maxBuffer: 64 * 1024 * 1024,
+      ...options,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** The tmp root cleanup operates on (honours TMPDIR via os.tmpdir()). */
+export function getTempRoot() {
+  return os.tmpdir();
+}
+
+/**
+ * List immediate children of the tmp root as candidate entries.
+ *
+ * @param {string} tempRoot
+ * @returns {Array<{name: string, path: string, isDirectory: boolean}>}
+ */
+export function listTempEntries(tempRoot) {
+  let dirents;
+  try {
+    dirents = fs.readdirSync(tempRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return dirents.map(d => {
+    const full = path.join(tempRoot, d.name);
+    let isDirectory = d.isDirectory();
+    // Resolve symlinks defensively (don't follow into them for deletion though).
+    if (d.isSymbolicLink()) {
+      try {
+        isDirectory = fs.statSync(full).isDirectory();
+      } catch {
+        isDirectory = false;
+      }
+    }
+    return { name: d.name, path: full, isDirectory };
+  });
+}
+
+/**
+ * Size of a path in bytes. Uses `du -sk` (fast, handles dirs) with a small
+ * fs.statSync fallback for plain files.
+ *
+ * @param {string} targetPath
+ * @returns {number|null}
+ */
+export function getPathSize(targetPath) {
+  const out = tryExec('du', ['-sk', targetPath]);
+  if (out) {
+    const kb = parseInt(out.split(/\s+/)[0], 10);
+    if (!Number.isNaN(kb)) return kb * 1024;
+  }
+  try {
+    return fs.statSync(targetPath).size;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the git branch, remotes and dirty state of a clone directory.
+ *
+ * @param {string} dir
+ * @returns {{branch: string|null, remotes: Array<{owner, repo, url}>, dirty: boolean}|null}
+ */
+export function readFolderGitInfo(dir) {
+  // Cheap check: is it a git work tree?
+  const isRepo = tryExec('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree']);
+  if (isRepo !== 'true') return null;
+
+  const branch = tryExec('git', ['-C', dir, 'branch', '--show-current']) || null;
+
+  const remotesRaw = tryExec('git', ['-C', dir, 'remote', '-v']) || '';
+  const remotes = [];
+  const seen = new Set();
+  for (const line of remotesRaw.split('\n')) {
+    const m = line.match(/^\S+\s+(\S+)\s+\((?:fetch|push)\)/);
+    if (!m) continue;
+    const parsed = parseRemoteUrl(m[1]);
+    if (parsed) {
+      const key = `${parsed.owner}/${parsed.repo}`.toLowerCase();
+      if (!seen.has(key)) {
+        seen.add(key);
+        remotes.push({ ...parsed, url: m[1] });
+      }
+    }
+  }
+
+  // Dirty if there are uncommitted changes OR commits not present on any remote.
+  const status = tryExec('git', ['-C', dir, 'status', '--porcelain']);
+  let dirty = Boolean(status && status.length > 0);
+  if (!dirty && branch) {
+    // Unpushed local commits: branch exists but has no upstream, or is ahead.
+    const upstream = tryExec('git', ['-C', dir, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    if (!upstream) {
+      // No upstream tracking: check whether the branch commit exists on a remote.
+      const head = tryExec('git', ['-C', dir, 'rev-parse', 'HEAD']);
+      const onRemote = head ? tryExec('git', ['-C', dir, 'branch', '-r', '--contains', head]) : null;
+      dirty = !onRemote;
+    } else {
+      const counts = tryExec('git', ['-C', dir, 'rev-list', '--left-right', '--count', `${upstream}...HEAD`]);
+      if (counts) {
+        const ahead = parseInt(counts.split(/\s+/)[1] || '0', 10);
+        dirty = ahead > 0;
+      }
+    }
+  }
+
+  return { branch, remotes, dirty };
+}
+
+/**
+ * Scan /proc to find paths under tempRoot that are the cwd of, or an open fd /
+ * mapped file of, a running process. Linux-only; returns an empty set elsewhere.
+ *
+ * @param {string} tempRoot
+ * @returns {Set<string>} absolute top-level entry paths under tempRoot
+ */
+export function listProcessHeldPaths(tempRoot) {
+  const held = new Set();
+  let pids;
+  try {
+    pids = fs.readdirSync('/proc').filter(name => /^\d+$/.test(name));
+  } catch {
+    return held; // Not Linux / no procfs.
+  }
+
+  const normalizedRoot = tempRoot.endsWith(path.sep) ? tempRoot : tempRoot + path.sep;
+  const recordIfUnderRoot = target => {
+    if (!target) return;
+    if (target === tempRoot || target.startsWith(normalizedRoot)) {
+      // Reduce to the top-level entry directly under tempRoot.
+      const rest = target.slice(normalizedRoot.length);
+      const first = rest.split(path.sep)[0];
+      if (first) held.add(path.join(tempRoot, first));
+    }
+  };
+
+  for (const pid of pids) {
+    // cwd of the process (covers git/claude children that chdir into the clone).
+    try {
+      recordIfUnderRoot(fs.readlinkSync(`/proc/${pid}/cwd`));
+    } catch {
+      /* process gone or permission denied */
+    }
+    // open file descriptors.
+    try {
+      for (const fd of fs.readdirSync(`/proc/${pid}/fd`)) {
+        try {
+          recordIfUnderRoot(fs.readlinkSync(`/proc/${pid}/fd/${fd}`));
+        } catch {
+          /* fd vanished */
+        }
+      }
+    } catch {
+      /* no fd dir / permission */
+    }
+  }
+  return held;
+}
+
+/**
+ * Collect task references (owner/repo/number/type) from running solve/hive
+ * processes by scanning /proc/<pid>/cmdline.
+ *
+ * @returns {Array<{owner, repo, type, number}>}
+ */
+export function listActiveTaskRefsFromProc() {
+  const refs = [];
+  const seen = new Set();
+  let pids;
+  try {
+    pids = fs.readdirSync('/proc').filter(name => /^\d+$/.test(name));
+  } catch {
+    return refs;
+  }
+  for (const pid of pids) {
+    let cmdline;
+    try {
+      cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+    } catch {
+      continue;
+    }
+    if (!cmdline || !/github\.com/.test(cmdline)) continue;
+    for (const ref of extractTaskRefsFromCommand(cmdline)) {
+      const key = `${ref.owner}/${ref.repo}#${ref.number}:${ref.type}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        refs.push(ref);
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Discover currently-running isolation session UUIDs from start-command's live
+ * session managers (screen / tmux). These names are the session UUIDs.
+ *
+ * @returns {string[]}
+ */
+export function listLiveSessionIds() {
+  const ids = new Set();
+
+  const screenOut = tryExec('screen', ['-ls']);
+  if (screenOut) {
+    for (const m of screenOut.matchAll(/^\s*\d+\.([0-9a-f-]{8,})\s/gim)) {
+      ids.add(m[1]);
+    }
+  }
+
+  const tmuxOut = tryExec('tmux', ['ls', '-F', '#{session_name}']);
+  if (tmuxOut) {
+    for (const line of tmuxOut.split('\n')) {
+      const name = line.trim();
+      if (/^[0-9a-f-]{8,}$/i.test(name)) ids.add(name);
+    }
+  }
+
+  return [...ids];
+}
+
+/**
+ * Query `$ --status <uuid>` for each live session and extract task references
+ * from executing sessions' command lines. Optional; reuses isolation-runner.
+ *
+ * @param {string[]} sessionIds
+ * @returns {Promise<Array<{owner, repo, type, number}>>}
+ */
+export async function listActiveTaskRefsFromSessions(sessionIds) {
+  if (!sessionIds || sessionIds.length === 0) return [];
+  let querySessionStatus;
+  let isTerminalSessionStatus;
+  try {
+    ({ querySessionStatus, isTerminalSessionStatus } = await import('./isolation-runner.lib.mjs'));
+  } catch {
+    return [];
+  }
+  const refs = [];
+  const seen = new Set();
+  for (const id of sessionIds) {
+    let status;
+    try {
+      status = await querySessionStatus(id);
+    } catch {
+      continue;
+    }
+    if (!status || !status.exists) continue;
+    if (status.status && isTerminalSessionStatus(status.status)) continue;
+    if (!status.command) continue;
+    for (const ref of extractTaskRefsFromCommand(status.command)) {
+      const key = `${ref.owner}/${ref.repo}#${ref.number}:${ref.type}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        refs.push(ref);
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Resolve the head branch of a PR via `gh pr view`. Returns null on failure
+ * (offline, no gh, not found) — callers fall back to issue-prefix matching.
+ *
+ * @param {{owner, repo, number}} ref
+ * @returns {string|null}
+ */
+export function resolvePrHeadBranch(ref) {
+  const out = tryExec('gh', ['pr', 'view', String(ref.number), '--repo', `${ref.owner}/${ref.repo}`, '--json', 'headRefName', '--jq', '.headRefName']);
+  return out || null;
+}
+
+/**
+ * Build the full active-task list, resolving PR head branches where possible.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.useSessions=true] - also query `$ --status`
+ * @param {boolean} [options.resolveBranches=true] - resolve PR head branches via gh
+ * @returns {Promise<Array<{owner, repo, type, number, branch: string|null}>>}
+ */
+export async function getActiveTasks(options = {}) {
+  const { useSessions = true, resolveBranches = true } = options;
+  const refs = [...listActiveTaskRefsFromProc()];
+  const seen = new Set(refs.map(r => `${r.owner}/${r.repo}#${r.number}:${r.type}`));
+
+  if (useSessions) {
+    const sessionRefs = await listActiveTaskRefsFromSessions(listLiveSessionIds());
+    for (const ref of sessionRefs) {
+      const key = `${ref.owner}/${ref.repo}#${ref.number}:${ref.type}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        refs.push(ref);
+      }
+    }
+  }
+
+  return refs.map(ref => {
+    let branch = null;
+    if (ref.type === 'pull' && resolveBranches) {
+      branch = resolvePrHeadBranch(ref);
+    }
+    return { ...ref, branch };
+  });
+}
+
+/**
+ * Permanently remove a path (recursive, force). Returns true on success.
+ *
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function removePath(targetPath) {
+  try {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * System / Ubuntu cleanup actions. Each is opt-in. In dry-run mode the commands
+ * are only described, never executed.
+ *
+ * @param {Object} options
+ * @param {boolean} [options.apt] - apt-get clean / autoclean / autoremove
+ * @param {boolean} [options.journal] - journalctl --vacuum-time
+ * @param {boolean} [options.docker] - docker system prune
+ * @param {boolean} [options.npm] - npm cache clean --force
+ * @param {string} [options.journalVacuumTime='2weeks']
+ * @param {boolean} [options.dryRun]
+ * @param {boolean} [options.useSudo] - prefix package commands with sudo
+ * @param {(msg: string) => void} [options.logFn]
+ * @returns {Array<{command: string, executed: boolean, ok: boolean|null}>}
+ */
+export function runSystemCleanup(options = {}) {
+  const { apt = false, journal = false, docker = false, npm = false, journalVacuumTime = '2weeks', dryRun = false, useSudo = false, logFn = () => {} } = options;
+
+  const plan = [];
+  const sudo = useSudo ? ['sudo'] : [];
+  if (apt) {
+    plan.push([...sudo, 'apt-get', 'clean']);
+    plan.push([...sudo, 'apt-get', 'autoclean', '-y']);
+    plan.push([...sudo, 'apt-get', 'autoremove', '-y']);
+  }
+  if (journal) {
+    plan.push([...sudo, 'journalctl', `--vacuum-time=${journalVacuumTime}`]);
+  }
+  if (docker) {
+    plan.push(['docker', 'system', 'prune', '-f']);
+  }
+  if (npm) {
+    plan.push(['npm', 'cache', 'clean', '--force']);
+  }
+
+  const results = [];
+  for (const argv of plan) {
+    const display = argv.join(' ');
+    if (dryRun) {
+      logFn(`   [dry-run] would run: ${display}`);
+      results.push({ command: display, executed: false, ok: null });
+      continue;
+    }
+    logFn(`   running: ${display}`);
+    const out = tryExec(argv[0], argv.slice(1), { timeout: 180000, stdio: ['ignore', 'pipe', 'pipe'] });
+    const ok = out !== null;
+    logFn(ok ? `   ✓ ${display}` : `   ✗ ${display} (failed or unavailable)`);
+    results.push({ command: display, executed: true, ok });
+  }
+  return results;
+}