feat(sessions): add prune command to delete closed sessions

src/cli/command-handlers.ts

@@ -33,6 +33,7 @@ import {
   type PromptFlags,
   type SessionsHistoryFlags,
   type SessionsNewFlags,
+  type SessionsPruneFlags,
   type StatusFlags,
 } from "./flags.js";
 import { emitJsonResult } from "./output/json-output.js";
@@ -874,4 +875,30 @@ export async function handleSessionsHistory(
   printSessionHistoryByFormat(record, flags.limit, globalFlags.format);
 }
 
+export async function handleSessionsPrune(
+  explicitAgentName: string | undefined,
+  flags: SessionsPruneFlags,
+  command: Command,
+  config: ResolvedAcpxConfig,
+): Promise<void> {
+  const globalFlags = resolveGlobalFlags(command, config);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags, config);
+  const [{ pruneSessions }, { printPruneResultByFormat }] = await Promise.all([
+    loadSessionModule(),
+    loadOutputRenderModule(),
+  ]);
+
+  const olderThanMs = flags.olderThan != null ? flags.olderThan * 24 * 60 * 60 * 1000 : undefined;
+
+  const result = await pruneSessions({
+    agentCommand: agent.agentCommand,
+    before: flags.before,
+    olderThanMs,
+    includeHistory: flags.includeHistory,
+    dryRun: flags.dryRun,
+  });
+
+  printPruneResultByFormat(result, globalFlags.format);
+}
+
 export { parseHistoryLimit, NoSessionError, loadSessionModule };

src/cli/command-registration.ts

@@ -9,6 +9,7 @@ import {
   handleSessionsHistory,
   handleSessionsList,
   handleSessionsNew,
+  handleSessionsPrune,
   handleSessionsShow,
   handleSetConfigOption,
   handleSetMode,
@@ -20,11 +21,14 @@ import {
   addPromptInputOption,
   addSessionNameOption,
   addSessionOption,
+  parseDaysOlderThan,
   parseNonEmptyValue,
+  parsePruneBeforeDate,
   parseSessionName,
   type PromptFlags,
   type SessionsHistoryFlags,
   type SessionsNewFlags,
+  type SessionsPruneFlags,
   type StatusFlags,
 } from "./flags.js";
 import { registerStatusCommand } from "./status-command.js";
@@ -134,6 +138,17 @@ export function registerSessionsCommand(
         config,
       );
     });
+
+  sessionsCommand
+    .command("prune")
+    .description("Delete closed sessions and free disk space")
+    .option("--dry-run", "Preview what would be pruned without deleting anything")
+    .option("--before <date>", "Prune sessions closed before this date", parsePruneBeforeDate)
+    .option("--older-than <days>", "Prune sessions closed more than N days ago", parseDaysOlderThan)
+    .option("--include-history", "Also delete event stream files (.stream.ndjson)")
+    .action(async function (this: Command, flags: SessionsPruneFlags) {
+      await handleSessionsPrune(explicitAgentName, flags, this, config);
+    });
 }
 
 export function registerSharedAgentSubcommands(

src/cli/flags.ts

@@ -68,6 +68,13 @@ export type StatusFlags = {
   session?: string;
 };
 
+export type SessionsPruneFlags = {
+  dryRun?: boolean;
+  before?: Date;
+  olderThan?: number;
+  includeHistory?: boolean;
+};
+
 export function parseOutputFormat(value: string): OutputFormat {
   if (!OUTPUT_FORMATS.includes(value as OutputFormat)) {
     throw new InvalidArgumentError(
@@ -135,6 +142,24 @@ export function parseHistoryLimit(value: string): number {
   return parsed;
 }
 
+export function parseDaysOlderThan(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new InvalidArgumentError("--older-than must be a positive integer number of days");
+  }
+  return parsed;
+}
+
+export function parsePruneBeforeDate(value: string): Date {
+  const date = new Date(value);
+  if (isNaN(date.getTime())) {
+    throw new InvalidArgumentError(
+      `--before must be a valid date (e.g. 2026-01-01 or 2026-01-01T00:00:00Z)`,
+    );
+  }
+  return date;
+}
+
 export function parseAllowedTools(value: string): string[] {
   const trimmed = value.trim();
   if (trimmed.length === 0) {

src/cli/output/render.ts

@@ -205,6 +205,64 @@ export function printCreatedSessionBanner(
   process.stderr.write(`[acpx] cwd: ${record.cwd}\n`);
 }
 
+function formatBytes(bytes: number): string {
+  if (bytes >= 1_073_741_824) {
+    return `${(bytes / 1_073_741_824).toFixed(1)} GB`;
+  }
+  if (bytes >= 1_048_576) {
+    return `${(bytes / 1_048_576).toFixed(1)} MB`;
+  }
+  if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${bytes} B`;
+}
+
+export function printPruneResultByFormat(
+  result: { pruned: SessionRecord[]; bytesFreed: number; dryRun: boolean },
+  format: OutputFormat,
+): void {
+  const count = result.pruned.length;
+
+  if (
+    emitJsonResult(format, {
+      action: result.dryRun ? "sessions_prune_dry_run" : "sessions_pruned",
+      dryRun: result.dryRun,
+      count,
+      bytesFreed: result.bytesFreed,
+      pruned: result.pruned.map((r) => r.acpxRecordId),
+    })
+  ) {
+    return;
+  }
+
+  if (format === "quiet") {
+    for (const record of result.pruned) {
+      process.stdout.write(`${record.acpxRecordId}\n`);
+    }
+    return;
+  }
+
+  if (count === 0) {
+    process.stdout.write(
+      result.dryRun ? "[DRY RUN] No sessions to prune\n" : "No sessions pruned\n",
+    );
+    return;
+  }
+
+  const prefix = result.dryRun ? "[DRY RUN] Would prune" : "Pruned";
+  const bytesSuffix =
+    !result.dryRun && result.bytesFreed > 0 ? `, freed ${formatBytes(result.bytesFreed)}` : "";
+  process.stdout.write(`${prefix} ${count} session${count === 1 ? "" : "s"}${bytesSuffix}\n`);
+
+  for (const record of result.pruned) {
+    const label = record.name ? ` (${record.name})` : "";
+    process.stdout.write(
+      `  ${record.acpxRecordId}${label}\t${record.closedAt ?? record.lastUsedAt}\n`,
+    );
+  }
+}
+
 export function agentSessionIdPayload(agentSessionId: string | undefined): {
   agentSessionId?: string;
 } {

src/session/persistence.ts

@@ -10,6 +10,8 @@ export {
   listSessions,
   listSessionsForAgent,
   normalizeName,
+  pruneSessions,
   resolveSessionRecord,
   writeSessionRecord,
 } from "./persistence/repository.js";
+export type { PruneOptions, PruneResult } from "./persistence/repository.js";

src/session/persistence/repository.ts

@@ -297,6 +297,102 @@ function killSignalCandidates(signal: NodeJS.Signals | undefined): NodeJS.Signal
   return [normalized, "SIGKILL"];
 }
 
+export type PruneOptions = {
+  agentCommand?: string;
+  before?: Date;
+  olderThanMs?: number;
+  includeHistory?: boolean;
+  dryRun?: boolean;
+};
+
+export type PruneResult = {
+  pruned: SessionRecord[];
+  bytesFreed: number;
+  dryRun: boolean;
+};
+
+export async function pruneSessions(options: PruneOptions = {}): Promise<PruneResult> {
+  await ensureSessionDir();
+  const entries = await loadSessionIndexEntries();
+
+  let eligible = entries.filter((entry) => entry.closed);
+
+  if (options.agentCommand) {
+    eligible = eligible.filter((entry) => entry.agentCommand === options.agentCommand);
+  }
+
+  const cutoff =
+    options.before ??
+    (options.olderThanMs != null ? new Date(Date.now() - options.olderThanMs) : undefined);
+
+  if (cutoff) {
+    const cutoffIso = cutoff.toISOString();
+    eligible = eligible.filter((entry) => entry.lastUsedAt < cutoffIso);
+  }
+
+  const records: SessionRecord[] = [];
+  for (const entry of eligible) {
+    const record = await loadRecordFromIndexEntry(entry);
+    if (record) {
+      records.push(record);
+    }
+  }
+
+  if (options.dryRun) {
+    return { pruned: records, bytesFreed: 0, dryRun: true };
+  }
+
+  const sessionDir = sessionBaseDir();
+  let bytesFreed = 0;
+
+  // Read the directory once upfront so stream-file matching doesn't re-read
+  // it for every session in the loop.
+  let dirEntries: string[] = [];
+  if (options.includeHistory) {
+    try {
+      dirEntries = await fs.readdir(sessionDir);
+    } catch {
+      // ignore
+    }
+  }
+
+  for (const record of records) {
+    const safeId = encodeURIComponent(record.acpxRecordId);
+    const jsonFile = path.join(sessionDir, `${safeId}.json`);
+
+    try {
+      const stat = await fs.stat(jsonFile);
+      bytesFreed += stat.size;
+    } catch {
+      // file already gone
+    }
+    await fs.unlink(jsonFile).catch(() => undefined);
+
+    if (options.includeHistory) {
+      const prefix = `${safeId}.stream`;
+      for (const name of dirEntries) {
+        if (!name.startsWith(prefix)) {
+          continue;
+        }
+        const filePath = path.join(sessionDir, name);
+        try {
+          const stat = await fs.stat(filePath);
+          bytesFreed += stat.size;
+        } catch {
+          // ignore
+        }
+        await fs.unlink(filePath).catch(() => undefined);
+      }
+    }
+  }
+
+  await rebuildSessionIndex(sessionDir).catch(() => {
+    // best effort cache rebuild
+  });
+
+  return { pruned: records, bytesFreed, dryRun: false };
+}
+
 export async function closeSession(id: string): Promise<SessionRecord> {
   const record = await resolveSessionRecord(id);
   const now = isoNow();

src/session/session.ts

@@ -10,5 +10,7 @@ export {
   findSessionByDirectoryWalk,
   listSessions,
   listSessionsForAgent,
+  pruneSessions,
 } from "./persistence.js";
+export type { PruneOptions, PruneResult } from "./persistence.js";
 export { isProcessAlive } from "../cli/queue/ipc.js";