@agentplate/cli 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to Agentplate are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
 [Semantic Versioning](https://semver.org/).
 
+## [1.4.0] — 2026-06-02
+
+### Added
+
+- **Full purge of reaped agents** (`agentplate reap --purge`, `agentplate stop
+  <agent> --purge`) — beyond stopping an agent and removing its worktree, purge
+  erases every trace it left behind: mail, events, queued merges, the on-disk
+  `.agentplate/agents/<name>/` state dir, the task spec (only once no sibling
+  session still references it), and the session row itself. A `PurgeReport` records
+  what was removed.
+- **`agents.purgeOnReap`** (default `false`) — when set, the `agentplate serve`
+  idle-reaper loop purges idle agents automatically (not just marks them stopped).
+  Surfaced as a gated toggle in `agentplate setup`.
+- **Store deletion APIs** backing the purge: `SessionStore.deleteSession`,
+  `EventStore.deleteByAgent`, and `MergeQueue.deleteByAgent`.
+
+### Changed
+
+- Plain `reap` / `serve` behavior is unchanged — reaping still keeps records for
+  history by default. Full erasure is strictly opt-in via `--purge` / `purgeOnReap`.
+
 ## [1.3.0] — 2026-06-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentplate/cli",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"publishConfig": {
 		"access": "public"
 	},

package/src/commands/reap.ts

@@ -6,6 +6,11 @@
  * live process, and removes its worktree + branch. The coordinator is never
  * reaped. Run it manually or on a cron; `agentplate serve` also reaps on its own
  * loop. Use `--dry-run` to preview and `--keep-worktrees` to leave worktrees.
+ *
+ * `--purge` goes further than a normal reap: it erases every trace of each reaped
+ * agent — mail, events, queued merges, the on-disk `.agentplate/agents/<name>/`
+ * state dir, and the session row itself — so the workspace is fully cleared. The
+ * plain reap keeps those records for history; purge is the opt-in clean slate.
  */
 
 import { Command } from "commander";
@@ -22,11 +27,21 @@ export function createReapCommand(): Command {
 		.description("Terminate agents idle past the timeout (stop + kill + remove worktree)")
 		.option("--minutes <n>", "idle timeout in minutes (default: config.agents.idleTimeoutMinutes)")
 		.option("--keep-worktrees", "mark stopped + kill process but keep worktrees/branches")
+		.option(
+			"--purge",
+			"fully erase each reaped agent (mail, events, merges, state dir, session row)",
+		)
 		.option("--dry-run", "list which agents would be reaped without changing anything")
 		.option("--json", "output JSON")
 		.action(
 			async (
-				opts: { minutes?: string; keepWorktrees?: boolean; dryRun?: boolean; json?: boolean },
+				opts: {
+					minutes?: string;
+					keepWorktrees?: boolean;
+					purge?: boolean;
+					dryRun?: boolean;
+					json?: boolean;
+				},
 				command: Command,
 			) => {
 				const useJson = command.optsWithGlobals().json === true;
@@ -51,11 +66,12 @@ export function createReapCommand(): Command {
 							now: Date.now(),
 						}).map((s) => ({ agent: s.agentName, capability: s.capability, state: s.state }));
 						if (useJson) {
-							jsonOutput({ dryRun: true, minutes, candidates });
+							jsonOutput({ dryRun: true, minutes, purge: opts.purge === true, candidates });
 						} else if (candidates.length === 0) {
 							printInfo(`No agents idle longer than ${minutes}m.`);
 						} else {
-							printInfo(`Would reap ${candidates.length} agent(s) idle >${minutes}m:`);
+							const how = opts.purge ? "reap + purge" : "reap";
+							printInfo(`Would ${how} ${candidates.length} agent(s) idle >${minutes}m:`);
 							for (const c of candidates) {
 								process.stdout.write(`  ${c.agent} ${muted(`(${c.capability}, ${c.state})`)}\n`);
 							}
@@ -66,17 +82,24 @@ export function createReapCommand(): Command {
 					const reaped = await reapIdleSessions(store, root, {
 						idleMs,
 						removeWorktrees: opts.keepWorktrees !== true,
+						purge: opts.purge === true,
 					});
 
 					if (useJson) {
-						jsonOutput({ minutes, reapedCount: reaped.length, reaped });
+						jsonOutput({ minutes, purge: opts.purge === true, reapedCount: reaped.length, reaped });
 					} else if (reaped.length === 0) {
 						printInfo(`No agents idle longer than ${minutes}m.`);
 					} else {
-						printSuccess(`Reaped ${reaped.length} idle agent(s) (>${minutes}m):`);
+						const verb = opts.purge ? "Reaped + purged" : "Reaped";
+						printSuccess(`${verb} ${reaped.length} idle agent(s) (>${minutes}m):`);
 						for (const r of reaped) {
 							const wt = r.worktreeRemoved ? "worktree removed" : "worktree kept";
-							process.stdout.write(`  ${r.agentName} ${muted(`(${r.capability}, ${wt})`)}\n`);
+							const extra = r.purged
+								? `, purged ${r.purged.mailDeleted} mail/${r.purged.eventsDeleted} events/${r.purged.mergeDeleted} merges`
+								: "";
+							process.stdout.write(
+								`  ${r.agentName} ${muted(`(${r.capability}, ${wt}${extra})`)}\n`,
+							);
 						}
 					}
 				} finally {

package/src/commands/stop.ts

@@ -7,22 +7,30 @@
 import { Command } from "commander";
 import { findProjectRoot, isInitialized } from "../config.ts";
 import { NotFoundError, ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
 import { printSuccess, printWarning } from "../logging/color.ts";
-import { sessionsDbPath } from "../paths.ts";
+import { createMailStore } from "../mail/store.ts";
+import { createMergeQueue } from "../merge/queue.ts";
+import { eventsDbPath, mailDbPath, mergeDbPath, sessionsDbPath } from "../paths.ts";
+import { type PurgeReport, purgeAgentData } from "../sessions/purge.ts";
 import { createSessionStore } from "../sessions/store.ts";
-import { removeWorktree } from "../worktree/manager.ts";
+import { deleteBranch, removeWorktree } from "../worktree/manager.ts";
 
 export function createStopCommand(): Command {
 	return new Command("stop")
 		.description("Terminate an agent session")
 		.argument("<agent>", "agent name")
 		.option("--clean-worktree", "also remove the agent's worktree")
+		.option(
+			"--purge",
+			"fully erase the agent (worktree + mail, events, merges, state dir, session row)",
+		)
 		.option("--json", "output JSON")
 		.action(
 			async (
 				agent: string,
-				opts: { cleanWorktree?: boolean; json?: boolean },
+				opts: { cleanWorktree?: boolean; purge?: boolean; json?: boolean },
 				command: Command,
 			) => {
 				const useJson = command.optsWithGlobals().json === true;
@@ -30,6 +38,8 @@ export function createStopCommand(): Command {
 				if (!isInitialized(root)) {
 					throw new ValidationError("Not initialized. Run `agentplate setup` first.");
 				}
+				// --purge implies removing the worktree: a full wipe leaves no worktree.
+				const cleanWorktree = opts.cleanWorktree || opts.purge === true;
 				const store = createSessionStore(sessionsDbPath(root));
 				try {
 					const session = store.getSessionByAgent(agent);
@@ -37,17 +47,44 @@ export function createStopCommand(): Command {
 					store.updateSessionState(session.id, "stopped");
 
 					let worktreeRemoved = false;
-					if (opts.cleanWorktree) {
+					if (cleanWorktree) {
 						try {
 							await removeWorktree(root, session.worktreePath, { force: true });
 							worktreeRemoved = true;
+							// Best-effort branch cleanup (may be merged/shared — leave it then).
+							try {
+								await deleteBranch(root, session.branchName);
+							} catch {
+								// Branch kept; not fatal.
+							}
 						} catch (error) {
 							printWarning(`Could not remove worktree: ${(error as Error).message}`);
 						}
 					}
 
-					if (useJson) jsonOutput({ agent, stopped: true, worktreeRemoved });
-					else printSuccess(`Stopped ${agent}${worktreeRemoved ? " (worktree removed)" : ""}`);
+					let purged: PurgeReport | null = null;
+					if (opts.purge) {
+						const events = createEventStore(eventsDbPath(root));
+						const merge = createMergeQueue(mergeDbPath(root));
+						const mail = createMailStore(mailDbPath(root));
+						try {
+							purged = purgeAgentData(root, session, { sessions: store, events, merge, mail });
+						} finally {
+							events.close();
+							merge.close();
+							mail.close();
+						}
+					}
+
+					if (useJson) {
+						jsonOutput({ agent, stopped: true, worktreeRemoved, purged });
+					} else if (purged) {
+						printSuccess(
+							`Purged ${agent} (worktree removed, ${purged.mailDeleted} mail/${purged.eventsDeleted} events/${purged.mergeDeleted} merges erased)`,
+						);
+					} else {
+						printSuccess(`Stopped ${agent}${worktreeRemoved ? " (worktree removed)" : ""}`);
+					}
 				} finally {
 					store.close();
 				}

package/src/config.ts

@@ -48,6 +48,7 @@ export const DEFAULT_CONFIG: AgentplateConfig = {
 		skipReview: false,
 		skipGates: false,
 		skipSkills: false,
+		purgeOnReap: false,
 	},
 	merge: {
 		aiResolveEnabled: true,

package/src/events/store.test.ts

@@ -180,4 +180,26 @@ describe("createEventStore", () => {
 		// Newest two builder events.
 		expect(limited.map((e) => e.type)).toEqual(["c", "b"]);
 	});
+
+	test("deleteByAgent removes only that agent's rows and returns the count", () => {
+		store.record({ agentName: "builder", type: "a" });
+		store.record({ agentName: "builder", type: "b" });
+		store.record({ agentName: "scout", type: "a" });
+
+		expect(store.deleteByAgent("builder")).toBe(2);
+		expect(store.list({ agentName: "builder" })).toEqual([]);
+		expect(store.list({ agentName: "scout" }).length).toBe(1);
+	});
+
+	test("deleteByAgent scoped to a run leaves the agent's other runs intact", () => {
+		store.record({ agentName: "builder", runId: "r1", type: "a" });
+		store.record({ agentName: "builder", runId: "r2", type: "b" });
+
+		expect(store.deleteByAgent("builder", "r1")).toBe(1);
+		expect(store.list({ agentName: "builder" }).map((e) => e.runId)).toEqual(["r2"]);
+	});
+
+	test("deleteByAgent on an unknown agent returns 0", () => {
+		expect(store.deleteByAgent("nobody")).toBe(0);
+	});
 });

package/src/events/store.ts

@@ -42,6 +42,12 @@ export interface ListEventsFilter {
 export interface EventStore {
 	record(event: RecordEventInput): EventRecord;
 	list(filter?: ListEventsFilter): EventRecord[];
+	/**
+	 * Delete every event logged by `agentName` (optionally scoped to one run);
+	 * returns the number of rows removed. Used when fully purging a reaped agent's
+	 * data. The log is otherwise append-only — this is the sole deletion path.
+	 */
+	deleteByAgent(agentName: string, runId?: string): number;
 	close(): void;
 }
 
@@ -193,9 +199,26 @@ export function createEventStore(dbPath: string): EventStore {
 		return rows.map(rowToRecord);
 	}
 
+	function deleteByAgent(agentName: string, runId?: string): number {
+		// Count first so we can report how many rows were removed (bun:sqlite's
+		// run() does not surface a changes count through this query API uniformly).
+		const where =
+			runId !== undefined
+				? "agent_name = $agent_name AND run_id = $run_id"
+				: "agent_name = $agent_name";
+		const params: Record<string, string> = { $agent_name: agentName };
+		if (runId !== undefined) params.$run_id = runId;
+		const countRow = db.query(`SELECT COUNT(*) AS n FROM events WHERE ${where}`).get(params) as {
+			n: number;
+		} | null;
+		const n = countRow?.n ?? 0;
+		if (n > 0) db.query(`DELETE FROM events WHERE ${where}`).run(params);
+		return n;
+	}
+
 	function close(): void {
 		db.close();
 	}
 
-	return { record, list, close };
+	return { record, list, deleteByAgent, close };
 }

package/src/merge/queue.test.ts

@@ -133,4 +133,19 @@ describe("createMergeQueue", () => {
 			queue = createMergeQueue(join(dir, "merge-queue.db"));
 		}
 	});
+
+	test("deleteByAgent removes every entry for the agent and returns the count", () => {
+		add({ agentName: "builder-1", branchName: "agent/a" });
+		add({ agentName: "builder-1", branchName: "agent/b" });
+		add({ agentName: "builder-2", branchName: "agent/c" });
+
+		expect(queue.deleteByAgent("builder-1")).toBe(2);
+		const pending = queue.listPending();
+		expect(pending).toHaveLength(1);
+		expect(pending[0]?.agentName).toBe("builder-2");
+	});
+
+	test("deleteByAgent on an unknown agent returns 0", () => {
+		expect(queue.deleteByAgent("nobody")).toBe(0);
+	});
 });

package/src/merge/queue.ts

@@ -36,6 +36,12 @@ export interface MergeQueue {
 	 * The returned object reflects its pre-removal `status` ("pending").
 	 */
 	dequeue(): MergeEntry | null;
+	/**
+	 * Delete every queue entry belonging to `agentName` regardless of status;
+	 * returns the number removed. Used when fully purging a reaped agent's data so
+	 * no stale pending merge survives the agent it came from.
+	 */
+	deleteByAgent(agentName: string): number;
 	/** Close the underlying database connection. */
 	close(): void;
 }
@@ -131,6 +137,14 @@ export function createMergeQueue(dbPath: string): MergeQueue {
 		"DELETE FROM merge_queue WHERE seq = $seq",
 	);
 
+	const countByAgentStmt = db.query<{ n: number }, { $agent: string }>(
+		"SELECT COUNT(*) AS n FROM merge_queue WHERE agent_name = $agent",
+	);
+
+	const deleteByAgentStmt = db.query<void, { $agent: string }>(
+		"DELETE FROM merge_queue WHERE agent_name = $agent",
+	);
+
 	return {
 		enqueue(entry): MergeEntry {
 			const row = insertStmt.get({
@@ -170,6 +184,12 @@ export function createMergeQueue(dbPath: string): MergeQueue {
 			return rowToEntry(row);
 		},
 
+		deleteByAgent(agentName): number {
+			const n = countByAgentStmt.get({ $agent: agentName })?.n ?? 0;
+			if (n > 0) deleteByAgentStmt.run({ $agent: agentName });
+			return n;
+		},
+
 		close(): void {
 			db.close();
 		},

package/src/serve/server.ts

@@ -221,23 +221,25 @@ export function startServer(opts: ServeOptions): ServeHandle {
 	// Idle-agent reaper: terminate workers idle past the configured timeout. Runs
 	// independently of connected clients (serve running = reaping active). Disabled
 	// when idleTimeoutMinutes is 0. Config is read once at startup.
-	const idleMinutes = (() => {
+	const { idleMinutes, purgeOnReap } = (() => {
 		try {
-			return loadConfig(opts.root).agents.idleTimeoutMinutes;
+			const agents = loadConfig(opts.root).agents;
+			return { idleMinutes: agents.idleTimeoutMinutes, purgeOnReap: agents.purgeOnReap };
 		} catch {
-			return 0;
+			return { idleMinutes: 0, purgeOnReap: false };
 		}
 	})();
 	const reapTimer =
 		idleMinutes > 0
 			? setInterval(() => {
 					const store = createSessionStore(sessionsDbPath(opts.root));
-					reapIdleSessions(store, opts.root, { idleMs: idleMinutes * 60_000 })
+					reapIdleSessions(store, opts.root, { idleMs: idleMinutes * 60_000, purge: purgeOnReap })
 						.then((reaped) => {
 							if (reaped.length > 0) {
 								const names = reaped.map((r) => r.agentName).join(", ");
+								const how = purgeOnReap ? "reaped + purged" : "reaped";
 								console.error(
-									`[agentplate] reaped ${reaped.length} idle agent(s) (>${idleMinutes}m): ${names}`,
+									`[agentplate] ${how} ${reaped.length} idle agent(s) (>${idleMinutes}m): ${names}`,
 								);
 							}
 						})

package/src/sessions/purge.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Tests for the full agent-data purge ("clear the Office").
+ *
+ * Per project policy nothing is mocked: a real temp project root holds real
+ * SQLite stores (sessions/events/merge/mail) at their canonical paths, plus a
+ * real on-disk agent state dir and spec file. We seed each store, run
+ * `purgeAgentData`, and assert that every trace of the agent is gone while a
+ * second agent's data is untouched.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createEventStore } from "../events/store.ts";
+import { createMailStore } from "../mail/store.ts";
+import { createMergeQueue } from "../merge/queue.ts";
+import {
+	agentStateDir,
+	eventsDbPath,
+	mailDbPath,
+	mergeDbPath,
+	sessionsDbPath,
+	specPath,
+} from "../paths.ts";
+import type { AgentSession } from "../types.ts";
+import { type PurgeStores, purgeAgentData } from "./purge.ts";
+import { createSessionStore } from "./store.ts";
+
+function mk(root: string, overrides: Partial<AgentSession>): AgentSession {
+	const now = new Date().toISOString();
+	return {
+		id: `s-${overrides.agentName ?? "a"}`,
+		agentName: "a",
+		capability: "builder",
+		taskId: "task-1",
+		runId: "run-1",
+		worktreePath: join(root, ".agentplate", "worktrees", overrides.agentName ?? "a"),
+		branchName: "agentplate/a",
+		state: "stopped",
+		parentAgent: null,
+		depth: 1,
+		pid: null,
+		runtimeSessionId: null,
+		startedAt: now,
+		lastActivity: now,
+		...overrides,
+	};
+}
+
+describe("purgeAgentData", () => {
+	let root: string;
+	let stores: PurgeStores;
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "ap-purge-"));
+		stores = {
+			sessions: createSessionStore(sessionsDbPath(root)),
+			events: createEventStore(eventsDbPath(root)),
+			merge: createMergeQueue(mergeDbPath(root)),
+			mail: createMailStore(mailDbPath(root)),
+		};
+	});
+
+	afterEach(() => {
+		stores.sessions.close();
+		stores.events.close();
+		stores.merge.close();
+		stores.mail.close();
+		rmSync(root, { recursive: true, force: true });
+	});
+
+	test("erases every trace of the agent and reports the counts", () => {
+		const session = mk(root, { id: "s-doomed", agentName: "doomed" });
+		stores.sessions.upsertSession(session);
+
+		// Seed each store + on-disk artifact for the doomed agent.
+		stores.events.record({ agentName: "doomed", runId: "run-1", type: "tool-start" });
+		stores.events.record({ agentName: "doomed", runId: "run-1", type: "tool-end" });
+		stores.mail.send({ from: "doomed", to: "lead", subject: "s", body: "b", type: "status" });
+		stores.mail.send({ from: "lead", to: "doomed", subject: "s", body: "b", type: "dispatch" });
+		stores.merge.enqueue({
+			branchName: "agentplate/doomed",
+			agentName: "doomed",
+			taskId: "task-1",
+			targetBranch: "main",
+		});
+		mkdirSync(agentStateDir(root, "doomed"), { recursive: true });
+		writeFileSync(join(agentStateDir(root, "doomed"), "identity.yaml"), "sessions: 1\n");
+		mkdirSync(join(root, ".agentplate", "specs"), { recursive: true });
+		writeFileSync(specPath(root, "task-1"), "# spec\n");
+
+		const report = purgeAgentData(root, session, stores);
+
+		expect(report).toEqual({
+			mailDeleted: 2,
+			eventsDeleted: 2,
+			mergeDeleted: 1,
+			stateDirRemoved: true,
+			specRemoved: true,
+			sessionDeleted: true,
+		});
+		// Nothing of the agent remains.
+		expect(stores.sessions.getSession("s-doomed")).toBeNull();
+		expect(stores.events.list({ agentName: "doomed" })).toEqual([]);
+		expect(stores.mail.list({ to: "doomed" })).toEqual([]);
+		expect(stores.mail.list({ from: "doomed" })).toEqual([]);
+		expect(stores.merge.listPending()).toEqual([]);
+		expect(existsSync(agentStateDir(root, "doomed"))).toBe(false);
+		expect(existsSync(specPath(root, "task-1"))).toBe(false);
+	});
+
+	test("leaves a second agent's data untouched", () => {
+		const doomed = mk(root, { id: "s-doomed", agentName: "doomed", taskId: "task-1" });
+		const keeper = mk(root, { id: "s-keeper", agentName: "keeper", taskId: "task-2" });
+		stores.sessions.upsertSession(doomed);
+		stores.sessions.upsertSession(keeper);
+		stores.events.record({ agentName: "keeper", runId: "run-1", type: "tool-start" });
+		stores.mail.send({ from: "keeper", to: "lead", subject: "s", body: "b", type: "status" });
+
+		purgeAgentData(root, doomed, stores);
+
+		expect(stores.sessions.getSession("s-keeper")).not.toBeNull();
+		expect(stores.events.list({ agentName: "keeper" }).length).toBe(1);
+		expect(stores.mail.list({ from: "keeper" }).length).toBe(1);
+	});
+
+	test("keeps the spec file while another session still references the task", () => {
+		const a = mk(root, { id: "s-a", agentName: "agent-a", taskId: "shared" });
+		const b = mk(root, { id: "s-b", agentName: "agent-b", taskId: "shared" });
+		stores.sessions.upsertSession(a);
+		stores.sessions.upsertSession(b);
+		mkdirSync(join(root, ".agentplate", "specs"), { recursive: true });
+		writeFileSync(specPath(root, "shared"), "# shared spec\n");
+
+		// Purging the first sibling keeps the spec (b still uses it).
+		const first = purgeAgentData(root, a, stores);
+		expect(first.specRemoved).toBe(false);
+		expect(existsSync(specPath(root, "shared"))).toBe(true);
+
+		// Purging the last sibling finally removes the spec.
+		const second = purgeAgentData(root, b, stores);
+		expect(second.specRemoved).toBe(true);
+		expect(existsSync(specPath(root, "shared"))).toBe(false);
+	});
+
+	test("is resilient when there is nothing to purge", () => {
+		const session = mk(root, { id: "s-empty", agentName: "empty" });
+		stores.sessions.upsertSession(session);
+
+		const report = purgeAgentData(root, session, stores);
+		expect(report.mailDeleted).toBe(0);
+		expect(report.eventsDeleted).toBe(0);
+		expect(report.mergeDeleted).toBe(0);
+		expect(report.stateDirRemoved).toBe(false); // dir never existed
+		expect(report.sessionDeleted).toBe(true);
+		expect(stores.sessions.getSession("s-empty")).toBeNull();
+	});
+});

package/src/sessions/purge.ts

@@ -0,0 +1,138 @@
+/**
+ * Full data purge for a terminated agent — "clear the Office".
+ *
+ * Reaping (see {@link ./reaper.ts}) stops an idle agent and removes its worktree,
+ * but deliberately leaves its records behind for history: the session row stays
+ * (marked `stopped`), and its mail / events / queued merges / on-disk state dir
+ * all persist. That is the right default for auditability, but it accumulates —
+ * a long-running project fills up with the debris of agents that came and went.
+ *
+ * This module is the opt-in opposite: given a session, erase *everything* that
+ * agent left behind so nothing of it remains. It is intentionally thorough and
+ * destructive; callers gate it behind an explicit `--purge` / `purgeOnReap`.
+ *
+ * Design: the orchestrator is handed already-open stores (the reaper opens them
+ * once per sweep; tests pass in-memory ones) and is responsible only for the
+ * deletions, not store lifecycle. Every step is best-effort and isolated — a
+ * failure to clear one store never aborts the rest — and a {@link PurgeReport}
+ * records exactly what was removed.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import type { EventStore } from "../events/store.ts";
+import type { MailStore } from "../mail/store.ts";
+import type { MergeQueue } from "../merge/queue.ts";
+import { agentStateDir, specPath } from "../paths.ts";
+import type { AgentSession } from "../types.ts";
+import type { SessionStore } from "./store.ts";
+
+/** The open stores a purge needs. The session store is the one the reaper holds. */
+export interface PurgeStores {
+	sessions: SessionStore;
+	events: EventStore;
+	merge: MergeQueue;
+	mail: MailStore;
+}
+
+/** What a single agent purge removed. Counts are best-effort (0 on failure). */
+export interface PurgeReport {
+	/** Mail messages deleted (sent or received by the agent). */
+	mailDeleted: number;
+	/** Event-log rows deleted for the agent. */
+	eventsDeleted: number;
+	/** Merge-queue entries deleted for the agent. */
+	mergeDeleted: number;
+	/** Whether the on-disk `.agentplate/agents/<name>/` state dir was removed. */
+	stateDirRemoved: boolean;
+	/** Whether the task spec file was removed (only when no session still uses it). */
+	specRemoved: boolean;
+	/** Whether the session row itself was deleted. */
+	sessionDeleted: boolean;
+}
+
+/**
+ * Erase all data belonging to `session`'s agent. Assumes the agent is already
+ * terminated (pid killed, worktree removed) — this only clears records, not
+ * processes or git state. Returns a {@link PurgeReport} of what was removed.
+ *
+ * Ordering note: the session row is deleted last and the spec check runs against
+ * the *remaining* sessions, so the agent's own row never keeps its spec alive.
+ */
+export function purgeAgentData(
+	root: string,
+	session: AgentSession,
+	stores: PurgeStores,
+): PurgeReport {
+	const report: PurgeReport = {
+		mailDeleted: 0,
+		eventsDeleted: 0,
+		mergeDeleted: 0,
+		stateDirRemoved: false,
+		specRemoved: false,
+		sessionDeleted: false,
+	};
+
+	// Mail: everything the agent sent or received.
+	try {
+		report.mailDeleted = stores.mail.purge({ agent: session.agentName });
+	} catch {
+		// Best-effort: a store error here must not block the rest of the purge.
+	}
+
+	// Events: the agent's slice of the append-only log (scoped to its run so a
+	// reused agent name in a later run keeps its own history).
+	try {
+		report.eventsDeleted = stores.events.deleteByAgent(session.agentName, session.runId);
+	} catch {
+		// Best-effort.
+	}
+
+	// Merge queue: any pending/merged/failed entries it enqueued.
+	try {
+		report.mergeDeleted = stores.merge.deleteByAgent(session.agentName);
+	} catch {
+		// Best-effort.
+	}
+
+	// On-disk state dir: identity CV + applied-skills.json. Guarded so we only ever
+	// remove a path that resolves inside `.agentplate/agents/` (defence in depth;
+	// the path is already derived from a constant, not user input).
+	try {
+		const dir = resolve(agentStateDir(root, session.agentName));
+		const agentsRoot = resolve(agentStateDir(root, ""));
+		// Only report a removal when a dir actually existed: rmSync with force:true
+		// is a silent no-op for a missing path, which would otherwise read as "removed".
+		if (dir.startsWith(agentsRoot + sep) && dir !== agentsRoot && existsSync(dir)) {
+			rmSync(dir, { recursive: true, force: true });
+			report.stateDirRemoved = true;
+		}
+	} catch {
+		// Best-effort.
+	}
+
+	// Session row: delete it before checking the spec so this agent's own row is
+	// not counted as "still using" the task.
+	try {
+		stores.sessions.deleteSession(session.id);
+		report.sessionDeleted = true;
+	} catch {
+		// Best-effort.
+	}
+
+	// Spec file: shared by task id, so only remove it once no remaining session
+	// references the task. (A multi-agent task keeps its spec until the last one
+	// is purged.)
+	try {
+		const stillUsed = stores.sessions.listSessions().some((s) => s.taskId === session.taskId);
+		const spec = specPath(root, session.taskId);
+		if (!stillUsed && existsSync(spec)) {
+			rmSync(spec, { force: true });
+			report.specRemoved = true;
+		}
+	} catch {
+		// Best-effort.
+	}
+
+	return report;
+}

package/src/sessions/reaper.test.ts

@@ -1,8 +1,11 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { sessionsDbPath } from "../paths.ts";
+import { createEventStore } from "../events/store.ts";
+import { createMailStore } from "../mail/store.ts";
+import { createMergeQueue } from "../merge/queue.ts";
+import { agentStateDir, eventsDbPath, mailDbPath, mergeDbPath, sessionsDbPath } from "../paths.ts";
 import type { AgentSession } from "../types.ts";
 import { reapIdleSessions, selectIdleSessions } from "./reaper.ts";
 import { createSessionStore } from "./store.ts";
@@ -159,4 +162,83 @@ describe("reapIdleSessions", () => {
 			store.close();
 		}
 	});
+
+	test("purge:true erases the reaped agent's data; default reap keeps it", async () => {
+		// Seed the auxiliary stores at their canonical paths, then close them so the
+		// reaper opens its own handles (matching production). The `.agentplate` dir
+		// must exist first — only the session store mkdirs it, and these open earlier.
+		mkdirSync(join(root, ".agentplate"), { recursive: true });
+		const events = createEventStore(eventsDbPath(root));
+		const merge = createMergeQueue(mergeDbPath(root));
+		const mail = createMailStore(mailDbPath(root));
+		// Same runId as the session (mk defaults to "r1") so the run-scoped purge matches.
+		events.record({ agentName: "old", runId: "r1", type: "tool-start" });
+		mail.send({ from: "old", to: "lead", subject: "s", body: "b", type: "status" });
+		merge.enqueue({
+			branchName: "agentplate/old",
+			agentName: "old",
+			taskId: "t",
+			targetBranch: "main",
+		});
+		events.close();
+		merge.close();
+		mail.close();
+		mkdirSync(agentStateDir(root, "old"), { recursive: true });
+		writeFileSync(join(agentStateDir(root, "old"), "identity.yaml"), "sessions: 1\n");
+
+		const store = createSessionStore(sessionsDbPath(root));
+		try {
+			store.upsertSession(
+				mk({ id: "s-old", agentName: "old", taskId: "t", lastActivity: minsAgo(30) }),
+			);
+
+			const reaped = await reapIdleSessions(store, root, {
+				idleMs: IDLE_MS,
+				now: NOW,
+				purge: true,
+			});
+
+			// The report carries the purge counts...
+			expect(reaped[0]?.purged).toEqual({
+				mailDeleted: 1,
+				eventsDeleted: 1,
+				mergeDeleted: 1,
+				stateDirRemoved: true,
+				specRemoved: false, // no spec file was created
+				sessionDeleted: true,
+			});
+			// ...and the session row is gone, not merely stopped.
+			expect(store.getSession("s-old")).toBeNull();
+			expect(existsSync(agentStateDir(root, "old"))).toBe(false);
+
+			// Verify the aux stores were actually cleared (reopen fresh handles).
+			const ev = createEventStore(eventsDbPath(root));
+			const mq = createMergeQueue(mergeDbPath(root));
+			const ml = createMailStore(mailDbPath(root));
+			try {
+				expect(ev.list({ agentName: "old" })).toEqual([]);
+				expect(mq.listPending()).toEqual([]);
+				expect(ml.list({ from: "old" })).toEqual([]);
+			} finally {
+				ev.close();
+				mq.close();
+				ml.close();
+			}
+		} finally {
+			store.close();
+		}
+	});
+
+	test("default reap (no purge) keeps the session row and reports purged: null", async () => {
+		const store = createSessionStore(sessionsDbPath(root));
+		try {
+			store.upsertSession(mk({ id: "s-old", agentName: "old", lastActivity: minsAgo(30) }));
+			const reaped = await reapIdleSessions(store, root, { idleMs: IDLE_MS, now: NOW });
+			expect(reaped[0]?.purged).toBeNull();
+			// Row kept for history, just marked stopped.
+			expect(store.getSession("s-old")?.state).toBe("stopped");
+		} finally {
+			store.close();
+		}
+	});
 });

package/src/sessions/reaper.ts

@@ -15,9 +15,13 @@
  * worktree IS the project root, and it does not stream per-turn events).
  */
 
-import { worktreesDir } from "../paths.ts";
+import { createEventStore } from "../events/store.ts";
+import { createMailStore } from "../mail/store.ts";
+import { createMergeQueue } from "../merge/queue.ts";
+import { eventsDbPath, mailDbPath, mergeDbPath, worktreesDir } from "../paths.ts";
 import type { AgentSession, SessionState } from "../types.ts";
 import { deleteBranch, removeWorktree, worktreeExists } from "../worktree/manager.ts";
+import { type PurgeReport, purgeAgentData } from "./purge.ts";
 import type { SessionStore } from "./store.ts";
 
 /** States that can be reaped — the pre-terminal (still-counted) ones. */
@@ -62,6 +66,8 @@ export interface ReapedAgent {
 	idleMs: number;
 	/** Whether its worktree was removed (false if kept, missing, or removal failed). */
 	worktreeRemoved: boolean;
+	/** What a full data purge removed, or null when purge was not requested. */
+	purged: PurgeReport | null;
 }
 
 export interface ReapOptions {
@@ -71,6 +77,13 @@ export interface ReapOptions {
 	now?: number;
 	/** Remove the reaped agent's worktree + branch (default true). */
 	removeWorktrees?: boolean;
+	/**
+	 * Fully erase each reaped agent's data — mail, events, queued merges, on-disk
+	 * state dir, and the session row itself — so nothing of it remains ("clear the
+	 * Office"). Default false: reaping keeps records for history. When true, the
+	 * auxiliary stores are opened from `root` for the sweep and closed afterward.
+	 */
+	purge?: boolean;
 	/** Capabilities to skip (defaults to `["coordinator"]`). */
 	excludeCapabilities?: readonly string[];
 }
@@ -88,52 +101,80 @@ export async function reapIdleSessions(
 ): Promise<ReapedAgent[]> {
 	const now = opts.now ?? Date.now();
 	const removeWorktrees = opts.removeWorktrees !== false;
+	const purge = opts.purge === true;
 	const stale = selectIdleSessions(store.listSessions(), {
 		idleMs: opts.idleMs,
 		now,
 		excludeCapabilities: opts.excludeCapabilities,
 	});
 
-	const reaped: ReapedAgent[] = [];
-	for (const s of stale) {
-		// 1. Kill any live process (spawn-per-turn workers usually have no pid).
-		if (s.pid != null) {
-			try {
-				process.kill(s.pid, "SIGTERM");
-			} catch {
-				// Already gone / not ours — nothing to do.
+	// Open the auxiliary stores once for the whole sweep, only when purging. They
+	// share the session store's `root` and are closed in `finally` below.
+	const aux = purge
+		? {
+				events: createEventStore(eventsDbPath(root)),
+				merge: createMergeQueue(mergeDbPath(root)),
+				mail: createMailStore(mailDbPath(root)),
 			}
-		}
+		: null;
 
-		// 2. Remove the worktree + branch (guarded against the project root).
-		let worktreeRemoved = false;
-		if (removeWorktrees && isRemovableWorktree(root, s.worktreePath)) {
-			try {
-				if (await worktreeExists(root, s.worktreePath)) {
-					await removeWorktree(root, s.worktreePath, { force: true });
+	const reaped: ReapedAgent[] = [];
+	try {
+		for (const s of stale) {
+			// 1. Kill any live process (spawn-per-turn workers usually have no pid).
+			if (s.pid != null) {
+				try {
+					process.kill(s.pid, "SIGTERM");
+				} catch {
+					// Already gone / not ours — nothing to do.
 				}
-				worktreeRemoved = true;
-				// Branch delete is separate and best-effort (no-op if already gone).
+			}
+
+			// 2. Remove the worktree + branch (guarded against the project root).
+			let worktreeRemoved = false;
+			if (removeWorktrees && isRemovableWorktree(root, s.worktreePath)) {
 				try {
-					await deleteBranch(root, s.branchName);
+					if (await worktreeExists(root, s.worktreePath)) {
+						await removeWorktree(root, s.worktreePath, { force: true });
+					}
+					worktreeRemoved = true;
+					// Branch delete is separate and best-effort (no-op if already gone).
+					try {
+						await deleteBranch(root, s.branchName);
+					} catch {
+						// Branch may be merged away or shared — leave it.
+					}
 				} catch {
-					// Branch may be merged away or shared — leave it.
+					worktreeRemoved = false;
 				}
-			} catch {
-				worktreeRemoved = false;
 			}
-		}
 
-		// 3. Mark the session terminated so it stops counting and shows as stopped.
-		store.updateSessionState(s.id, "stopped");
+			// 3. Mark the session terminated so it stops counting and shows as stopped.
+			//    (When purging, the row is deleted in step 4 — but we still transition it
+			//    first so any concurrent reader observes a terminal state, never a gap.)
+			store.updateSessionState(s.id, "stopped");
+
+			// 4. Optionally erase every trace of the agent so the workspace is cleared.
+			let purged: PurgeReport | null = null;
+			if (aux) {
+				purged = purgeAgentData(root, s, { sessions: store, ...aux });
+			}
 
-		reaped.push({
-			id: s.id,
-			agentName: s.agentName,
-			capability: s.capability,
-			idleMs: now - Date.parse(s.lastActivity),
-			worktreeRemoved,
-		});
+			reaped.push({
+				id: s.id,
+				agentName: s.agentName,
+				capability: s.capability,
+				idleMs: now - Date.parse(s.lastActivity),
+				worktreeRemoved,
+				purged,
+			});
+		}
+	} finally {
+		if (aux) {
+			aux.events.close();
+			aux.merge.close();
+			aux.mail.close();
+		}
 	}
 	return reaped;
 }

package/src/sessions/store.test.ts

@@ -344,6 +344,24 @@ describe("createSessionStore — file-backed database", () => {
 		rmSync(dir, { recursive: true, force: true });
 	});
 
+	test("deleteSession removes the row entirely (not just a state change)", () => {
+		const store = createSessionStore(":memory:");
+		try {
+			const run = store.createRun();
+			const session = makeSession({ runId: run.id, state: "idle" });
+			store.upsertSession(session);
+			expect(store.getSession(session.id)).not.toBeNull();
+
+			store.deleteSession(session.id);
+			expect(store.getSession(session.id)).toBeNull();
+			expect(store.countActive(run.id)).toBe(0);
+			// Deleting a missing id is a no-op (no throw).
+			expect(() => store.deleteSession("does-not-exist")).not.toThrow();
+		} finally {
+			store.close();
+		}
+	});
+
 	test("creates the parent directory and persists across reopen", () => {
 		// Point at a NON-existent nested path to exercise the mkdir-parent logic.
 		const dbPath = join(dir, "nested", "sessions.db");

package/src/sessions/store.ts

@@ -56,6 +56,12 @@ export interface SessionStore {
 	updateSessionState(id: string, state: SessionState): void;
 	setRuntimeSessionId(id: string, runtimeSessionId: string): void;
 	touch(id: string): void;
+	/**
+	 * Permanently delete a session row by id (no-op if absent). Unlike
+	 * {@link updateSessionState}(id, "stopped") — which keeps the row for history —
+	 * this removes it entirely, used when fully purging a reaped agent's data.
+	 */
+	deleteSession(id: string): void;
 	countActive(runId?: string): number;
 	countActiveByParent(parentAgent: string, runId?: string): number;
 	// --- Lifecycle ---
@@ -312,6 +318,11 @@ export function createSessionStore(dbPath: string): SessionStore {
 		db.query("UPDATE sessions SET last_activity = ? WHERE id = ?").run(now, id);
 	}
 
+	function deleteSession(id: string): void {
+		// Hard delete. Safe to call for a missing id (DELETE simply affects 0 rows).
+		db.query("DELETE FROM sessions WHERE id = ?").run(id);
+	}
+
 	function countActive(runId?: string): number {
 		// Active = booting | working | idle (see ACTIVE_STATES). Used by schedulers
 		// to enforce per-run / global concurrency caps.
@@ -363,6 +374,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 		updateSessionState,
 		setRuntimeSessionId,
 		touch,
+		deleteSession,
 		countActive,
 		countActiveByParent,
 		close,

package/src/types.ts

@@ -167,6 +167,14 @@ export interface AgentsConfig {
 	skipGates: boolean;
 	/** Skip the post-turn skill-distillation loop. */
 	skipSkills: boolean;
+	/**
+	 * When the idle reaper fires (in `agentplate serve`'s loop), also fully erase
+	 * each reaped agent — mail, events, queued merges, on-disk state dir, and the
+	 * session row — so the workspace is cleared, not just stopped. Default false
+	 * (reaping keeps records for history). The `agentplate reap --purge` flag does
+	 * the same on demand regardless of this setting.
+	 */
+	purgeOnReap: boolean;
 }
 
 /**

package/src/version.ts

@@ -4,4 +4,4 @@
  * Kept as a plain constant (not read from package.json at runtime) so the value
  * is available without filesystem access and survives bundling.
  */
-export const VERSION = "1.3.0";
+export const VERSION = "1.4.0";

package/src/wizard/setup.ts

@@ -384,6 +384,13 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		agents.skipReview = skips.includes("skipReview");
 		agents.skipGates = skips.includes("skipGates");
 		agents.skipSkills = skips.includes("skipSkills");
+
+		agents.purgeOnReap = ensure(
+			await p.confirm({
+				message: "Fully erase idle agents when reaped (mail, events, merges, files, session)?",
+				initialValue: agents.purgeOnReap,
+			}),
+		);
 	}
 
 	// 7. Summary -----------------------------------------------------------
@@ -403,6 +410,7 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 			previewProvider.baseUrl ? `base URL:  ${previewProvider.baseUrl}` : undefined,
 			`gates:     ${qualityGates.length ? qualityGates.map((g) => g.name).join(", ") : "none"}`,
 			`auto-merge:${autoMerge}`,
+			agents.purgeOnReap ? "purge-on-reap: on (idle agents fully erased)" : undefined,
 			modelsByCapability?.scout
 				? `fast model: ${modelsByCapability.scout} (scout, reviewer)`
 				: undefined,