@ag-eco/agentplate-cli 0.13.0

package/src/commands/clean.ts

@@ -0,0 +1,791 @@
+/**
+ * CLI command: ap clean [--all] [--mail] [--sessions] [--metrics]
+ *   [--logs] [--worktrees] [--branches] [--agents] [--specs]
+ *
+ * Nuclear cleanup of agentplate runtime state.
+ * --all does everything. Individual flags allow selective cleanup.
+ *
+ * Execution order for --all (processes → filesystem → databases):
+ *   0. Run loam health checks (informational, non-destructive):
+ *      - Check domains approaching governance limits
+ *      - Run loam prune --dry-run (report stale record counts)
+ *      - Run loam doctor (report health issues)
+ *   1. Kill all agentplate tmux sessions
+ *   2. Remove all worktrees
+ *   3. Delete orphaned agentplate/* branches
+ *   4. Delete SQLite databases (mail.db, metrics.db)
+ *   5. Wipe sessions.db, merge-queue.db
+ *   6. Clear directory contents (logs/, agents/, specs/)
+ *   7. Delete nudge-state.json
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { AgentError, ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { createLoamClient } from "../loam/client.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import type { AgentSession, LoamDoctorResult, LoamPruneResult, LoamStatus } from "../types.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "../utils/fs.ts";
+import { listWorktrees, removeWorktree } from "../worktree/manager.ts";
+import {
+	isProcessAlive,
+	isSessionAlive,
+	killProcessTree,
+	killSession,
+	listSessions,
+	sanitizeTmuxName,
+} from "../worktree/tmux.ts";
+
+export interface CleanOptions {
+	agent?: string;
+	all?: boolean;
+	mail?: boolean;
+	sessions?: boolean;
+	metrics?: boolean;
+	logs?: boolean;
+	worktrees?: boolean;
+	branches?: boolean;
+	agents?: boolean;
+	specs?: boolean;
+	json?: boolean;
+}
+
+/**
+ * Load active agent sessions from SessionStore for session-end event logging.
+ * Returns sessions that are in an active state (booting, working, stalled).
+ *
+ * Checks for sessions.db or sessions.json existence first to avoid creating
+ * an empty database file as a side effect (which would interfere with
+ * the "Nothing to clean" detection later in the pipeline).
+ */
+function loadActiveSessions(agentplateDir: string): AgentSession[] {
+	try {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const jsonPath = join(agentplateDir, "sessions.json");
+		if (!existsSync(dbPath) && !existsSync(jsonPath)) {
+			return [];
+		}
+		const { store } = openSessionStore(agentplateDir);
+		try {
+			return store.getActive();
+		} finally {
+			store.close();
+		}
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Log synthetic session-end events for all active agents before killing tmux sessions.
+ *
+ * When clean --all or --worktrees kills tmux sessions, the Stop hook never fires
+ * because the process is killed externally. This function writes session_end events
+ * to the EventStore with reason='clean' so observability records are complete.
+ */
+async function logSyntheticSessionEndEvents(agentplateDir: string): Promise<number> {
+	let logged = 0;
+	try {
+		const activeSessions = loadActiveSessions(agentplateDir);
+		if (activeSessions.length === 0) {
+			return 0;
+		}
+
+		const eventsDbPath = join(agentplateDir, "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+		try {
+			for (const session of activeSessions) {
+				eventStore.insert({
+					runId: session.runId,
+					agentName: session.agentName,
+					sessionId: session.id,
+					eventType: "session_end",
+					toolName: null,
+					toolArgs: null,
+					toolDurationMs: null,
+					level: "info",
+					data: JSON.stringify({ reason: "clean", capability: session.capability }),
+				});
+				logged++;
+			}
+		} finally {
+			eventStore.close();
+		}
+	} catch {
+		// Best effort: event logging should not block cleanup
+	}
+	return logged;
+}
+
+interface CleanResult {
+	sessionEndEventsLogged: number;
+	tmuxKilled: number;
+	orphanPidsReaped: number;
+	worktreesCleaned: number;
+	branchesDeleted: number;
+	mailWiped: boolean;
+	sessionsCleared: boolean;
+	mergeQueueCleared: boolean;
+	metricsWiped: boolean;
+	logsCleared: boolean;
+	agentsCleared: boolean;
+	specsCleared: boolean;
+	nudgeStateCleared: boolean;
+	currentRunCleared: boolean;
+	loamHealth: {
+		checked: boolean;
+		domainsNearLimit: Array<{ domain: string; recordCount: number; warnThreshold: number }>;
+		stalePruneCandidates: number;
+		doctorIssues: number;
+		doctorWarnings: number;
+	} | null;
+}
+
+/**
+ * Kill agentplate tmux sessions registered in THIS project's SessionStore.
+ *
+ * Project-scoped: only kills tmux sessions whose names appear in the
+ * project's sessions.db (or sessions.json). This prevents cross-project
+ * kills during dogfooding, where `bun test` might run inside a live swarm.
+ *
+ * Falls back to killing all "agentplate-{projectName}-" prefixed tmux sessions
+ * only if the SessionStore is unavailable (graceful degradation for broken state).
+ */
+async function killAllTmuxSessions(agentplateDir: string, projectName: string): Promise<number> {
+	let killed = 0;
+	const projectPrefix = `agentplate-${sanitizeTmuxName(projectName)}-`;
+	try {
+		const tmuxSessions = await listSessions();
+		const agentPlateSessions = tmuxSessions.filter((s) => s.name.startsWith(projectPrefix));
+		if (agentPlateSessions.length === 0) {
+			return 0;
+		}
+
+		// Build a set of tmux session names registered in this project's SessionStore.
+		const registeredNames = loadRegisteredTmuxNames(agentplateDir);
+
+		// If we got registered names, only kill those. Otherwise fall back to all
+		// agentplate-{projectName}-* sessions.
+		const toKill =
+			registeredNames !== null
+				? agentPlateSessions.filter((s) => registeredNames.has(s.name))
+				: agentPlateSessions;
+
+		for (const session of toKill) {
+			try {
+				await killSession(session.name);
+				killed++;
+			} catch {
+				// Best effort
+			}
+		}
+	} catch {
+		// tmux not available or no server running
+	}
+	return killed;
+}
+
+/**
+ * Load the set of tmux session names registered in this project's SessionStore.
+ *
+ * Returns null if the SessionStore cannot be opened (signals the caller to
+ * fall back to the legacy "kill all agentplate-*" behavior).
+ */
+function loadRegisteredTmuxNames(agentplateDir: string): Set<string> | null {
+	try {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const jsonPath = join(agentplateDir, "sessions.json");
+		if (!existsSync(dbPath) && !existsSync(jsonPath)) {
+			// No session data at all -- return empty set (not null).
+			// This is distinct from "store unavailable": it means the project
+			// has no registered sessions, so nothing should be killed.
+			return new Set();
+		}
+		const { store } = openSessionStore(agentplateDir);
+		try {
+			const allSessions = store.getAll();
+			return new Set(allSessions.map((s) => s.tmuxSession));
+		} finally {
+			store.close();
+		}
+	} catch {
+		// SessionStore is broken -- fall back to legacy behavior
+		return null;
+	}
+}
+
+/**
+ * Reap any spawn PIDs in sessions.db that survived tmux teardown.
+ *
+ * `killAllTmuxSessions` walks descendants of the live tmux pane PID and is
+ * sufficient for sessions whose tmux container is still up. This handles the
+ * leftover case: a stored pid that is still alive but its tmux session is
+ * gone (claude was reparented to init when its bash wrapper got SIGHUP) or
+ * the session is in a terminal state but the spawn never exited. Best-effort.
+ * (agentplate-505d)
+ */
+async function reapOrphanedPids(agentplateDir: string): Promise<number> {
+	let reaped = 0;
+	try {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const jsonPath = join(agentplateDir, "sessions.json");
+		if (!existsSync(dbPath) && !existsSync(jsonPath)) {
+			return 0;
+		}
+		const { store } = openSessionStore(agentplateDir);
+		try {
+			for (const session of store.getAll()) {
+				if (session.pid === null) continue;
+				if (!isProcessAlive(session.pid)) continue;
+				try {
+					await killProcessTree(session.pid);
+					reaped++;
+				} catch {
+					// Best effort
+				}
+			}
+		} finally {
+			store.close();
+		}
+	} catch {
+		// Best effort
+	}
+	return reaped;
+}
+
+/**
+ * Remove all agentplate worktrees (force remove with branch deletion).
+ */
+async function cleanAllWorktrees(root: string): Promise<number> {
+	let cleaned = 0;
+	try {
+		const worktrees = await listWorktrees(root);
+		const agentplateWts = worktrees.filter((wt) => wt.branch.startsWith("agentplate/"));
+		for (const wt of agentplateWts) {
+			try {
+				await removeWorktree(root, wt.path, { force: true, forceBranch: true });
+				cleaned++;
+			} catch {
+				// Best effort
+			}
+		}
+	} catch {
+		// No worktrees or git error
+	}
+	return cleaned;
+}
+
+/**
+ * Delete orphaned agentplate/* branch refs not tied to a worktree.
+ */
+async function deleteOrphanedBranches(root: string): Promise<number> {
+	let deleted = 0;
+	try {
+		const proc = Bun.spawn(
+			["git", "for-each-ref", "refs/heads/agentplate/", "--format=%(refname:short)"],
+			{ cwd: root, stdout: "pipe", stderr: "pipe" },
+		);
+		const stdout = await new Response(proc.stdout).text();
+		await proc.exited;
+
+		const branches = stdout
+			.trim()
+			.split("\n")
+			.filter((b) => b.length > 0);
+		for (const branch of branches) {
+			try {
+				const del = Bun.spawn(["git", "branch", "-D", branch], {
+					cwd: root,
+					stdout: "pipe",
+					stderr: "pipe",
+				});
+				const exitCode = await del.exited;
+				if (exitCode === 0) deleted++;
+			} catch {
+				// Best effort
+			}
+		}
+	} catch {
+		// Git error
+	}
+	return deleted;
+}
+
+/**
+ * Check loam repository health and return diagnostic information.
+ *
+ * Governance limits warn threshold (based on loam defaults):
+ * - Max records per domain: 500 (warn at 400 = 80%)
+ *
+ * This is informational only — no data is modified.
+ */
+async function checkLoamHealth(repoRoot: string): Promise<{
+	domainsNearLimit: Array<{ domain: string; recordCount: number; warnThreshold: number }>;
+	stalePruneCandidates: number;
+	doctorIssues: number;
+	doctorWarnings: number;
+} | null> {
+	try {
+		const loam = createLoamClient(repoRoot);
+
+		// 1. Check domain sizes against governance limits
+		let status: LoamStatus;
+		try {
+			status = await loam.status();
+		} catch {
+			// Loam not available or no .loam directory
+			return null;
+		}
+
+		const warnThreshold = 400; // 80% of 500 max
+		const domainsNearLimit = status.domains
+			.filter((d) => d.recordCount >= warnThreshold)
+			.map((d) => ({ domain: d.name, recordCount: d.recordCount, warnThreshold }));
+
+		// 2. Run prune --dry-run to count stale records
+		let pruneResult: LoamPruneResult;
+		try {
+			pruneResult = await loam.prune({ dryRun: true });
+		} catch {
+			// Prune failed — skip this check
+			pruneResult = { success: false, command: "prune", dryRun: true, totalPruned: 0, results: [] };
+		}
+
+		const stalePruneCandidates = pruneResult.totalPruned;
+
+		// 3. Run doctor to check repository health
+		let doctorResult: LoamDoctorResult;
+		try {
+			doctorResult = await loam.doctor({ fix: false });
+		} catch {
+			// Doctor failed — skip this check
+			doctorResult = {
+				success: false,
+				command: "doctor",
+				checks: [],
+				summary: { pass: 0, warn: 0, fail: 0 },
+			};
+		}
+
+		const doctorIssues = doctorResult.summary.fail;
+		const doctorWarnings = doctorResult.summary.warn;
+
+		return {
+			domainsNearLimit,
+			stalePruneCandidates,
+			doctorIssues,
+			doctorWarnings,
+		};
+	} catch {
+		// Loam not available or other error — skip health checks
+		return null;
+	}
+}
+
+interface AgentCleanResult {
+	agentName: string;
+	tmuxKilled: boolean;
+	pidKilled: boolean;
+	worktreeRemoved: boolean;
+	branchDeleted: boolean;
+	agentDirCleared: boolean;
+	logsDirCleared: boolean;
+	sessionEndEventLogged: boolean;
+	markedCompleted: boolean;
+}
+
+/**
+ * Delete a git branch (best-effort).
+ */
+async function deleteBranch(repoRoot: string, branch: string): Promise<boolean> {
+	try {
+		const proc = Bun.spawn(["git", "branch", "-D", branch], {
+			cwd: repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		return exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Perform targeted cleanup of a single agent.
+ *
+ * Kills its tmux session or process, removes its worktree, deletes its branch,
+ * clears its agent and log directories, logs a synthetic session-end event,
+ * and marks the session as completed.
+ */
+async function cleanSingleAgent(
+	agentName: string,
+	agentplateDir: string,
+	projectRoot: string,
+): Promise<AgentCleanResult> {
+	const result: AgentCleanResult = {
+		agentName,
+		tmuxKilled: false,
+		pidKilled: false,
+		worktreeRemoved: false,
+		branchDeleted: false,
+		agentDirCleared: false,
+		logsDirCleared: false,
+		sessionEndEventLogged: false,
+		markedCompleted: false,
+	};
+
+	const { store } = openSessionStore(agentplateDir);
+	let session: AgentSession | undefined;
+	try {
+		const found = store.getByName(agentName);
+		if (!found) {
+			throw new AgentError(`Agent "${agentName}" not found`, { agentName });
+		}
+		session = found;
+
+		// Log synthetic session-end event for non-completed agents
+		if (session.state !== "completed") {
+			try {
+				const eventsDbPath = join(agentplateDir, "events.db");
+				const eventStore = createEventStore(eventsDbPath);
+				try {
+					eventStore.insert({
+						runId: session.runId,
+						agentName: session.agentName,
+						sessionId: session.id,
+						eventType: "session_end",
+						toolName: null,
+						toolArgs: null,
+						toolDurationMs: null,
+						level: "info",
+						data: JSON.stringify({ reason: "clean --agent", capability: session.capability }),
+					});
+					result.sessionEndEventLogged = true;
+				} finally {
+					eventStore.close();
+				}
+			} catch {
+				// Best effort
+			}
+		}
+
+		const isHeadless = session.tmuxSession === "" && session.pid !== null;
+
+		// Kill tmux session or process
+		if (isHeadless && session.pid !== null) {
+			try {
+				if (isProcessAlive(session.pid)) {
+					await killProcessTree(session.pid);
+					result.pidKilled = true;
+				}
+			} catch {
+				// Best effort
+			}
+		} else if (session.tmuxSession) {
+			try {
+				if (await isSessionAlive(session.tmuxSession)) {
+					await killSession(session.tmuxSession);
+					result.tmuxKilled = true;
+				}
+			} catch {
+				// Best effort
+			}
+		}
+
+		// Remove worktree (force)
+		if (session.worktreePath) {
+			try {
+				await removeWorktree(projectRoot, session.worktreePath, {
+					force: true,
+					forceBranch: false,
+				});
+				result.worktreeRemoved = true;
+			} catch {
+				// Best effort
+			}
+		}
+
+		// Delete branch
+		if (session.branchName) {
+			result.branchDeleted = await deleteBranch(projectRoot, session.branchName);
+		}
+
+		// Mark completed
+		if (session.state !== "completed") {
+			store.updateState(agentName, "completed");
+			store.updateLastActivity(agentName);
+			result.markedCompleted = true;
+		}
+	} finally {
+		store.close();
+	}
+
+	// Clear agent identity directory
+	if (session) {
+		const agentDir = join(agentplateDir, "agents", agentName);
+		result.agentDirCleared = await clearDirectory(agentDir);
+
+		// Clear agent logs directory
+		const logsDir = join(agentplateDir, "logs", agentName);
+		result.logsDirCleared = await clearDirectory(logsDir);
+	}
+
+	return result;
+}
+
+/**
+ * Entry point for `ap clean [flags]`.
+ *
+ * @param opts - Command options
+ */
+export async function cleanCommand(opts: CleanOptions): Promise<void> {
+	const json = opts.json ?? false;
+	const all = opts.all ?? false;
+	const agentName = opts.agent;
+
+	// --agent and --all are mutually exclusive
+	if (agentName && all) {
+		throw new ValidationError(
+			"--agent and --all are mutually exclusive. Use --agent <name> for single-agent cleanup or --all for full cleanup.",
+			{ field: "flags" },
+		);
+	}
+
+	const doWorktrees = all || (opts.worktrees ?? false);
+	const doBranches = all || (opts.branches ?? false);
+	const doMail = all || (opts.mail ?? false);
+	const doSessions = all || (opts.sessions ?? false);
+	const doMetrics = all || (opts.metrics ?? false);
+	const doLogs = all || (opts.logs ?? false);
+	const doAgents = all || (opts.agents ?? false);
+	const doSpecs = all || (opts.specs ?? false);
+
+	const anySelected =
+		agentName ||
+		doWorktrees ||
+		doBranches ||
+		doMail ||
+		doSessions ||
+		doMetrics ||
+		doLogs ||
+		doAgents ||
+		doSpecs;
+
+	if (!anySelected) {
+		throw new ValidationError(
+			"No cleanup targets specified. Use --all for full cleanup, --agent <name> for single-agent cleanup, or individual flags (--mail, --sessions, --metrics, --logs, --worktrees, --branches, --agents, --specs).",
+			{ field: "flags" },
+		);
+	}
+
+	const config = await loadConfig(process.cwd());
+	const root = config.project.root;
+	const agentplateDir = join(root, ".agentplate");
+
+	// Per-agent cleanup: targeted single-agent cleanup
+	if (agentName) {
+		const agentResult = await cleanSingleAgent(agentName, agentplateDir, root);
+		if (json) {
+			jsonOutput("clean", { agent: agentResult });
+		} else {
+			printSuccess("Agent cleaned", agentName);
+			if (agentResult.tmuxKilled) process.stdout.write(`  Tmux session killed\n`);
+			if (agentResult.pidKilled) process.stdout.write(`  Process killed (PID)\n`);
+			if (agentResult.worktreeRemoved) process.stdout.write(`  Worktree removed\n`);
+			if (agentResult.branchDeleted)
+				process.stdout.write(`  Branch deleted: ${agentResult.agentName}\n`);
+			if (agentResult.agentDirCleared) process.stdout.write(`  Cleared agents/${agentName}/\n`);
+			if (agentResult.logsDirCleared) process.stdout.write(`  Cleared logs/${agentName}/\n`);
+		}
+		return;
+	}
+
+	const result: CleanResult = {
+		sessionEndEventsLogged: 0,
+		tmuxKilled: 0,
+		orphanPidsReaped: 0,
+		worktreesCleaned: 0,
+		branchesDeleted: 0,
+		mailWiped: false,
+		sessionsCleared: false,
+		mergeQueueCleared: false,
+		metricsWiped: false,
+		logsCleared: false,
+		agentsCleared: false,
+		specsCleared: false,
+		nudgeStateCleared: false,
+		currentRunCleared: false,
+		loamHealth: null,
+	};
+
+	// 0. Run loam health checks BEFORE cleanup operations (when --all is set).
+	// This is informational only — no data is modified.
+	if (all) {
+		const healthCheck = await checkLoamHealth(root);
+		if (healthCheck) {
+			result.loamHealth = {
+				checked: true,
+				domainsNearLimit: healthCheck.domainsNearLimit,
+				stalePruneCandidates: healthCheck.stalePruneCandidates,
+				doctorIssues: healthCheck.doctorIssues,
+				doctorWarnings: healthCheck.doctorWarnings,
+			};
+		}
+	}
+
+	// 1. Log synthetic session-end events BEFORE killing tmux sessions.
+	// When processes are killed externally, the Stop hook never fires,
+	// so session_end events would be lost without this step.
+	if (doWorktrees || all) {
+		result.sessionEndEventsLogged = await logSyntheticSessionEndEvents(agentplateDir);
+	}
+
+	// 2. Kill tmux sessions (must happen before worktree removal)
+	if (doWorktrees || all) {
+		result.tmuxKilled = await killAllTmuxSessions(agentplateDir, config.project.name);
+	}
+
+	// 2b. Reap any orphaned spawn PIDs that survived tmux teardown.
+	// Must run after killAllTmuxSessions (which collects descendants of live
+	// panes) but before sessions.db is wiped (we need pid records to find
+	// orphans). (agentplate-505d)
+	if (doWorktrees || all) {
+		result.orphanPidsReaped = await reapOrphanedPids(agentplateDir);
+	}
+
+	// 3. Remove worktrees
+	if (doWorktrees) {
+		result.worktreesCleaned = await cleanAllWorktrees(root);
+	}
+
+	// 4. Delete orphaned branches
+	if (doBranches) {
+		result.branchesDeleted = await deleteOrphanedBranches(root);
+	}
+
+	// 5. Wipe databases
+	if (doMail) {
+		result.mailWiped = await wipeSqliteDb(join(agentplateDir, "mail.db"));
+	}
+	if (doMetrics) {
+		result.metricsWiped = await wipeSqliteDb(join(agentplateDir, "metrics.db"));
+	}
+
+	// 6. Wipe sessions.db + legacy sessions.json
+	if (doSessions) {
+		result.sessionsCleared = await wipeSqliteDb(join(agentplateDir, "sessions.db"));
+		// Also clean legacy sessions.json if it still exists
+		await resetJsonFile(join(agentplateDir, "sessions.json"));
+	}
+	if (all) {
+		result.mergeQueueCleared = await wipeSqliteDb(join(agentplateDir, "merge-queue.db"));
+	}
+
+	// 7. Clear directories
+	if (doLogs) {
+		result.logsCleared = await clearDirectory(join(agentplateDir, "logs"));
+	}
+	if (doAgents) {
+		result.agentsCleared = await clearDirectory(join(agentplateDir, "agents"));
+	}
+	if (doSpecs) {
+		result.specsCleared = await clearDirectory(join(agentplateDir, "specs"));
+	}
+
+	// 8. Delete nudge state + pending nudge markers + current-run.txt
+	if (all) {
+		result.nudgeStateCleared = await deleteFile(join(agentplateDir, "nudge-state.json"));
+		await clearDirectory(join(agentplateDir, "pending-nudges"));
+		result.currentRunCleared = await deleteFile(join(agentplateDir, "current-run.txt"));
+	}
+
+	// Output
+	if (json) {
+		jsonOutput("clean", { ...result });
+		return;
+	}
+
+	const lines: string[] = [];
+	if (result.sessionEndEventsLogged > 0) {
+		lines.push(
+			`Logged ${result.sessionEndEventsLogged} synthetic session-end event${result.sessionEndEventsLogged === 1 ? "" : "s"}`,
+		);
+	}
+	if (result.tmuxKilled > 0) {
+		lines.push(`Killed ${result.tmuxKilled} tmux session${result.tmuxKilled === 1 ? "" : "s"}`);
+	}
+	if (result.orphanPidsReaped > 0) {
+		lines.push(
+			`Reaped ${result.orphanPidsReaped} orphaned spawn process${result.orphanPidsReaped === 1 ? "" : "es"}`,
+		);
+	}
+	if (result.worktreesCleaned > 0) {
+		lines.push(
+			`Removed ${result.worktreesCleaned} worktree${result.worktreesCleaned === 1 ? "" : "s"}`,
+		);
+	}
+	if (result.branchesDeleted > 0) {
+		lines.push(
+			`Deleted ${result.branchesDeleted} orphaned branch${result.branchesDeleted === 1 ? "" : "es"}`,
+		);
+	}
+	if (result.mailWiped) lines.push("Wiped mail.db");
+	if (result.metricsWiped) lines.push("Wiped metrics.db");
+	if (result.sessionsCleared) lines.push("Wiped sessions.db");
+	if (result.mergeQueueCleared) lines.push("Wiped merge-queue.db");
+	if (result.logsCleared) lines.push("Cleared logs/");
+	if (result.agentsCleared) lines.push("Cleared agents/");
+	if (result.specsCleared) lines.push("Cleared specs/");
+	if (result.nudgeStateCleared) lines.push("Cleared nudge-state.json");
+	if (result.currentRunCleared) lines.push("Cleared current-run.txt");
+
+	// Loam health diagnostics (shown before cleanup results)
+	if (result.loamHealth?.checked) {
+		const health = result.loamHealth;
+		const healthLines: string[] = [];
+
+		if (health.domainsNearLimit.length > 0) {
+			healthLines.push("\nWarning: Loam domains approaching governance limits:");
+			for (const d of health.domainsNearLimit) {
+				healthLines.push(
+					`   ${d.domain}: ${d.recordCount} records (warn threshold: ${d.warnThreshold})`,
+				);
+			}
+		}
+
+		if (health.stalePruneCandidates > 0) {
+			healthLines.push(
+				`\nStale records found: ${health.stalePruneCandidates} candidate${health.stalePruneCandidates === 1 ? "" : "s"} (run 'loam prune' to remove)`,
+			);
+		}
+
+		if (health.doctorWarnings > 0 || health.doctorIssues > 0) {
+			healthLines.push(
+				`\nLoam health check: ${health.doctorWarnings} warning${health.doctorWarnings === 1 ? "" : "s"}, ${health.doctorIssues} issue${health.doctorIssues === 1 ? "" : "s"} (run 'loam doctor' for details)`,
+			);
+		}
+
+		if (healthLines.length > 0) {
+			for (const line of healthLines) {
+				process.stdout.write(`${line}\n`);
+			}
+		}
+	}
+
+	if (lines.length === 0) {
+		printHint("Nothing to clean");
+	} else {
+		if (result.loamHealth?.checked) {
+			process.stdout.write("\n--- Cleanup Results ---\n");
+		}
+		for (const line of lines) {
+			process.stdout.write(`${line}\n`);
+		}
+		printSuccess("Clean complete");
+	}
+}