@link-assistant/hive-mind 1.73.8 → 1.74.0

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