@link-assistant/hive-mind 1.73.9 → 1.74.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @link-assistant/hive-mind
 
+## 1.74.1
+
+### Patch Changes
+
+- 59eee9a: feat(interactive-mode): display images the AI reads/writes inline in PR comments (#1843)
+
+  When `--interactive-mode` posts Claude/Codex tool activity as PR comments, any
+  images the AI reads or produces (the `Read` tool on a screenshot, Playwright
+  captures, MCP image results) were previously serialized as multi-kilobyte
+  base64 blobs inside the "Raw JSON" section — unreadable and pushing comments
+  toward GitHub's size limit.
+
+  Those base64 payloads are now uploaded to hidden custom Git refs
+  (`refs/hive-mind-media/pr-...`) via the Git Data API and embedded inline in the
+  comment as commit-SHA `![](…?raw=true)` blob URLs, so reviewers see the actual
+  image (GitHub's Camo proxy renders `?raw=true` blob URLs inline for both public
+  and private repos, whereas `data:` URIs are stripped by the comment sanitizer).
+  Uploads are content-hashed (SHA-256) for dedup, and the base64 is redacted from
+  the Raw JSON section with a `<image data: N base64 chars>` placeholder.
+
+  Enabled by default; use `--no-interactive-image-upload` to opt out, in which
+  case each image degrades to a compact metadata note instead of being embedded.
+  All comment bodies continue to pass through the token sanitizer (#1745).
+
+## 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.1",
   "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/claude.lib.mjs

@@ -687,6 +687,8 @@ export const executeClaudeCommand = async params => {
         // so the comment-posting path can honor them; flags default to false.
         skipOutputSanitization: argv['dangerously-skip-output-sanitization'] === true,
         skipActiveTokensOutputSanitization: argv['dangerously-skip-active-tokens-output-sanitization'] === true,
+        // Issue #1843: upload & embed images by default; --no-interactive-image-upload opts out.
+        imageUploadEnabled: argv['interactive-image-upload'] !== false,
       });
     } else if (argv.interactiveMode) {
       await log('⚠️ Interactive mode: Disabled - missing PR info (owner/repo/prNumber)', { verbose: true });

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;
+}