zigmini 1.0.0-beta.3 → 1.1.0-beta.2

package/src/gc.ts

@@ -1,223 +1,44 @@
-import { lstatSync, readdirSync, readFileSync, readlinkSync, rmSync } from "node:fs";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lstatSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { join, sep } from "node:path";
 import type { InstallKind } from "./runtime/install-kind.ts";
-import { agentTrashTimestamp } from "./agent/files.ts";
-import { say, type Text } from "./server-text.ts";
+import { GC_COLLECTORS } from "./housekeeping/registry.ts";
+import { parseRpcUnits } from "./housekeeping/collectors/rpc-daemon.ts";
+import { GC_KINDS, type GcCandidate, type GcDeps, type GcEntry, type GcKind, type GcRoots, sized, toCandidate } from "./housekeeping/collectors/shared.ts";
+import { moveToTrash, type Trash } from "./housekeeping/trash.ts";
 
 /**
  * Improvement 66 (plan Todo 24): the gateway's resource cleanup (GC). `findCandidates` only reads and lists; `clean`
  * acts only on the candidates the user picked (by id or by kind) and finds them again right before it acts.
  *
- * Kinds and rules (a candidate must meet every rule of its kind):
- *   db-backup    `*.sqlite` file in the backups folder, not among the newest KEEP_BACKUPS and older than BACKUP_KEEP_MS.
- *   omo-version  folder in omo/ that is not the target of omo/current, not the previous engine, and no process runs from it.
- *   update-file  `*.log` or `request*.json` file in <home>/update/, older than UPDATE_MIN_AGE_MS.
- *   temp-dir     `zgw-*` or `zigmini-*` folder in $TMPDIR, older than TEMP_MIN_AGE_MS, named by no process, opened by none.
- *   rpc-daemon   old-version RPC host daemon that `rpc-host-gc.ts list --json` judges "stop" (rule of bug 62).
- *   agent-trash agent folders in agents/.trash, older than AGENT_TRASH_MIN_AGE_MS by name timestamp or mtime.
+ * Since housekeeping todo 3 each kind is a collector in src/housekeeping/collectors/ (rule, root check, act); this module
+ * keeps the old /api/gc surface on top of those collectors and re-exports their rules. `report` never acts; automatic
+ * SIGTERM of old rpc daemons happens only in the housekeeping engine's scan.
  * A checkout (this Mac's Docker gateway) cannot see host processes and folders, so it lists DB backups only.
  * A rule input that cannot be read (current link, process list, lsof) makes its kind list nothing. Daemons get SIGTERM only.
- * Work cards, worktrees and Docker are not part of this (the open decisions of improvement 66).
+ * Files and folders go to the macOS Trash (src/housekeeping/trash.ts), never deleted for good outside its checkout db-backup case.
  */
 
-export const GC_KINDS = ["db-backup", "omo-version", "update-file", "temp-dir", "rpc-daemon", "agent-trash"] as const;
-export type GcKind = (typeof GC_KINDS)[number];
-export const DAY_MS = 24 * 60 * 60 * 1000;
-export const KEEP_BACKUPS = 10;
-export const BACKUP_KEEP_MS = 30 * DAY_MS;
-export const UPDATE_MIN_AGE_MS = 7 * DAY_MS;
-export const TEMP_MIN_AGE_MS = 7 * DAY_MS;
-export const AGENT_TRASH_MIN_AGE_MS = 30 * DAY_MS;
+export { AGENT_TRASH_MIN_AGE_MS, BACKUP_KEEP_MS, DAY_MS, GC_KINDS, inside, KEEP_BACKUPS, linkTarget, TEMP_MIN_AGE_MS, UPDATE_MIN_AGE_MS } from "./housekeeping/collectors/shared.ts";
+export type { GcCandidate, GcDeps, GcEntry, GcKind, GcRoots, RpcUnit } from "./housekeeping/collectors/shared.ts";
+export { backupCandidates } from "./housekeeping/collectors/db-backup.ts";
+export { omoCandidates } from "./housekeeping/collectors/omo-version.ts";
+export { updateCandidates } from "./housekeeping/collectors/update-file.ts";
+export { tempCandidates } from "./housekeeping/collectors/temp-dir.ts";
+export { agentTrashCandidates, REASON_AGENT_TRASH } from "./housekeeping/collectors/agent-trash.ts";
+export { daemonCandidates, parseRpcUnits } from "./housekeeping/collectors/rpc-daemon.ts";
+
 export const GC_PATH = "/api/gc";
 export const GC_CLEAN_PATH = "/api/gc/clean";
 
-const REASON_BACKUP: Text = { en: "Outside the newest {keep} and older than {days} days", ko: "최근 {keep}개 밖이고 {days}일 지남" };
-const REASON_OMO: Text = { en: "Not the current ({current}) or previous version, and no process is running from it", ko: "현재({current})·직전 버전이 아니고 실행 중인 프로세스 없음" };
-const REASON_UPDATE: Text = { en: "Update log or request file older than {days} days", ko: "{days}일 지난 업데이트 로그·요청 파일" };
-const REASON_TEMP: Text = { en: "Older than {days} days and no process uses it", ko: "{days}일 지났고 쓰는 프로세스 없음" };
-const REASON_DAEMON: Text = { en: "RPC host daemon of an earlier version, no parent, no connected client", ko: "이전 버전 RPC 호스트 데몬, 부모 없음, 연결된 클라이언트 없음" };
-export const REASON_AGENT_TRASH: Text = { en: "Archived agent folder older than {days} days", ko: "{days}일 지난 에이전트 보관 폴더" };
-
-const TEMP_NAME = /^(?:zgw-|zigmini-)/;
-const UPDATE_NAME = /^(?:.+\.log|request.*\.json)$/;
-/** Never a candidate, whatever folder it is found in. */
-const PROTECTED_SEGMENTS = [`${sep}.omo${sep}evidence`, `${sep}secrets`];
-
-export interface GcCandidate {
-	readonly id: string;
-	readonly kind: GcKind;
-	readonly target: string;
-	readonly reason: string;
-	readonly ageMs: number;
-	readonly bytes: number | null;
-	readonly pids?: readonly number[];
-}
-
-export interface GcEntry { readonly name: string; readonly type: "file" | "dir" | "link" | "other"; readonly mtimeMs: number }
-export interface RpcUnit { readonly version: string; readonly verdict: string; readonly pids: readonly number[]; readonly ageMs: number; readonly rssKb: number }
-
-export interface GcRoots {
-	readonly kind: InstallKind;
-	readonly home: string;
-	readonly backups: string;
-	readonly omo: string;
-	readonly update: string;
-	readonly tmp: string;
-	readonly agents: string;
-}
-
-type MaybeAsync<T> = T | Promise<T>;
-export interface GcDeps {
-	readonly now: () => number;
-	/** Entries of a folder, or null when it cannot be read. */
-	readonly list: (dir: string) => GcEntry[] | null;
-	readonly size: (path: string) => MaybeAsync<number | null>;
-	readonly readlink: (path: string) => string | null;
-	readonly readText: (path: string) => string | null;
-	/** Command lines of every process, or null when ps failed. */
-	readonly commands: () => MaybeAsync<readonly string[] | null>;
-	/** Whether a process holds a file under `path`; null when lsof failed. */
-	readonly openBy: (path: string) => MaybeAsync<boolean | null>;
-	readonly rpcUnits: () => MaybeAsync<readonly RpcUnit[] | null>;
-	readonly remove: (path: string) => void;
-	readonly terminate: (pid: number) => void;
-}
-
 export interface GcReport { readonly kind: InstallKind; readonly total: number; readonly bytes: number; readonly counts: Readonly<Record<GcKind, number>>; readonly candidates: readonly GcCandidate[] }
 export interface GcSelection { readonly ids: readonly string[]; readonly kinds: readonly GcKind[] }
 export interface GcCleanResult { readonly cleaned: readonly GcCandidate[]; readonly failed: readonly { readonly id: string; readonly error: string }[]; readonly missing: readonly string[] }
 
-export function inside(root: string, path: string): boolean {
-	const rel = relative(resolve(root), resolve(path));
-	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}
-
-function guarded(root: string, path: string): boolean {
-	const full = resolve(path);
-	return inside(root, full) && !PROTECTED_SEGMENTS.some((segment) => full.includes(segment));
-}
-
-export function linkTarget(root: string, link: string, deps: Pick<GcDeps, "readlink">): string | null {
-	const target = deps.readlink(link);
-	if (target === null) return null;
-	const name = relative(root, resolve(root, target));
-	if (name === "" || name.startsWith("..") || name.includes(sep)) return null;
-	return name;
-}
-
-export function backupCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
-	const entries = deps.list(roots.backups);
-	if (entries === null) return [];
-	const backups = entries.filter((entry) => entry.type === "file" && entry.name.endsWith(".sqlite")).sort((a, b) => b.mtimeMs - a.mtimeMs);
-	const now = deps.now();
-	const out: GcCandidate[] = [];
-	for (const [index, entry] of backups.entries()) {
-		const ageMs = now - entry.mtimeMs;
-		if (index < KEEP_BACKUPS) continue;
-		if (ageMs <= BACKUP_KEEP_MS) continue;
-		const target = join(roots.backups, entry.name);
-		out.push({ id: `db-backup:${target}`, kind: "db-backup", target, reason: say(REASON_BACKUP, { keep: KEEP_BACKUPS, days: BACKUP_KEEP_MS / DAY_MS }), ageMs, bytes: null });
-	}
-	return out;
-}
-
-export async function omoCandidates(roots: GcRoots, deps: GcDeps): Promise<GcCandidate[]> {
-	const current = linkTarget(roots.omo, join(roots.omo, "current"), deps);
-	if (current === null) return [];
-	const entries = deps.list(roots.omo);
-	if (entries === null) return [];
-	const folders = entries.filter((entry) => entry.type === "dir" && !entry.name.startsWith(".") && entry.name !== "current");
-	const recorded = deps.readText(join(roots.update, "prev-engine"))?.trim() ?? "";
-	// The previous engine is what an update rollback relinks (Todo 23). Without a record, the newest other folder stands in.
-	const others = folders.filter((entry) => entry.name !== current).sort((a, b) => b.mtimeMs - a.mtimeMs);
-	const previous = recorded !== "" ? recorded : others[0]?.name ?? null;
-	const commands = await deps.commands();
-	if (commands === null) return [];
-	const now = deps.now();
-	const out: GcCandidate[] = [];
-	for (const entry of others) {
-		if (entry.name === previous) continue;
-		const target = join(roots.omo, entry.name);
-		if (commands.some((command) => command.includes(`${target}${sep}`))) continue;
-		out.push({ id: `omo-version:${target}`, kind: "omo-version", target, reason: say(REASON_OMO, { current }), ageMs: now - entry.mtimeMs, bytes: null });
-	}
-	return out;
-}
-
-export function updateCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
-	const entries = deps.list(roots.update);
-	if (entries === null) return [];
-	const now = deps.now();
-	const out: GcCandidate[] = [];
-	for (const entry of entries) {
-		if (entry.type !== "file" || !UPDATE_NAME.test(entry.name)) continue;
-		const ageMs = now - entry.mtimeMs;
-		if (ageMs <= UPDATE_MIN_AGE_MS) continue;
-		const target = join(roots.update, entry.name);
-		out.push({ id: `update-file:${target}`, kind: "update-file", target, reason: say(REASON_UPDATE, { days: UPDATE_MIN_AGE_MS / DAY_MS }), ageMs, bytes: null });
-	}
-	return out;
-}
-
-export async function tempCandidates(roots: GcRoots, deps: GcDeps): Promise<GcCandidate[]> {
-	const entries = deps.list(roots.tmp);
-	if (entries === null) return [];
-	const now = deps.now();
-	const old = entries.filter((entry) => entry.type === "dir" && TEMP_NAME.test(entry.name) && now - entry.mtimeMs > TEMP_MIN_AGE_MS);
-	if (old.length === 0) return [];
-	const commands = await deps.commands();
-	if (commands === null) return [];
-	const out: GcCandidate[] = [];
-	for (const entry of old) {
-		const target = join(roots.tmp, entry.name);
-		if (commands.some((command) => command.includes(target))) continue;
-		if (await deps.openBy(target) !== false) continue;
-		out.push({ id: `temp-dir:${target}`, kind: "temp-dir", target, reason: say(REASON_TEMP, { days: TEMP_MIN_AGE_MS / DAY_MS }), ageMs: now - entry.mtimeMs, bytes: null });
-	}
-	return out;
-}
-
-export async function daemonCandidates(deps: GcDeps): Promise<GcCandidate[]> {
-	const units = await deps.rpcUnits();
-	if (units === null) return [];
-	return units.filter((unit) => unit.verdict === "stop" && unit.pids.length > 0).map((unit) => ({
-		id: `rpc-daemon:${unit.version}:${unit.pids[0]}`, kind: "rpc-daemon" as const, target: `${unit.version} pid ${unit.pids.join(",")}`,
-		reason: say(REASON_DAEMON), ageMs: unit.ageMs, bytes: unit.rssKb * 1024, pids: unit.pids,
-	}));
-}
-
-export function agentTrashCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
-	const trash = join(roots.agents, ".trash");
-	const entries = deps.list(trash);
-	if (entries === null) return [];
-	const now = deps.now();
-	const out: GcCandidate[] = [];
-	for (const entry of entries) {
-		if (entry.type !== "dir") continue;
-		const namedAt = agentTrashTimestamp(entry.name);
-		if (namedAt !== null && !Number.isFinite(namedAt)) continue;
-		const ageMs = now - (namedAt ?? entry.mtimeMs);
-		if (ageMs <= AGENT_TRASH_MIN_AGE_MS) continue;
-		const target = join(trash, entry.name);
-		out.push({ id: `agent-trash:${target}`, kind: "agent-trash", target, reason: say(REASON_AGENT_TRASH, { days: AGENT_TRASH_MIN_AGE_MS / DAY_MS }), ageMs, bytes: null });
-	}
-	return out;
-}
-
 /** Read-only: every candidate, each path kept strictly inside its own root. */
 export async function findCandidates(roots: GcRoots, deps: GcDeps): Promise<GcCandidate[]> {
 	const found: GcCandidate[] = [];
-	found.push(...backupCandidates(roots, deps).filter((c) => guarded(roots.backups, c.target)));
-	if (roots.kind === "npm") {
-		found.push(...agentTrashCandidates(roots, deps).filter((c) => guarded(join(roots.agents, ".trash"), c.target)));
-		found.push(...(await omoCandidates(roots, deps)).filter((c) => guarded(roots.omo, c.target)));
-		found.push(...updateCandidates(roots, deps).filter((c) => guarded(roots.update, c.target)));
-		found.push(...(await tempCandidates(roots, deps)).filter((c) => guarded(roots.tmp, c.target)));
-		found.push(...await daemonCandidates(deps));
-	}
-	const sized: GcCandidate[] = [];
-	for (const candidate of found) sized.push(candidate.bytes === null ? { ...candidate, bytes: await deps.size(candidate.target) } : candidate);
-	return sized;
+	for (const collector of GC_COLLECTORS) found.push(...await collector.listed({ roots, deps }));
+	return sized(found, deps);
 }
 
 export async function report(roots: GcRoots, deps: GcDeps): Promise<GcReport> {
@@ -246,9 +67,10 @@ export async function clean(roots: GcRoots, deps: GcDeps, selection: GcSelection
 	const failed: { id: string; error: string }[] = [];
 	for (const candidate of picked) {
 		try {
-			if (candidate.kind === "rpc-daemon") for (const pid of candidate.pids ?? []) deps.terminate(pid);
-			else deps.remove(candidate.target);
-			cleaned.push(candidate);
+			const collector = GC_COLLECTORS.find((c) => c.name === candidate.kind)!;
+			const done = await collector.act(toCandidate(candidate), { roots, deps });
+			if (done.ok) cleaned.push(candidate);
+			else failed.push({ id: candidate.id, error: done.error ?? "act_failed" });
 		} catch (error) {
 			failed.push({ id: candidate.id, error: error instanceof Error ? error.message : String(error) });
 		}
@@ -256,25 +78,6 @@ export async function clean(roots: GcRoots, deps: GcDeps, selection: GcSelection
 	return { cleaned, failed, missing };
 }
 
-/** `rpc-host-gc.ts list --json` output; any malformed entry makes the whole list unreadable (null). */
-export function parseRpcUnits(text: string): RpcUnit[] | null {
-	let body: unknown;
-	try {
-		body = JSON.parse(text);
-	} catch {
-		return null;
-	}
-	if (!Array.isArray(body)) return null;
-	const units: RpcUnit[] = [];
-	for (const item of body as Record<string, unknown>[]) {
-		const { version, verdict, pids, ageMs, rssKb } = item ?? {};
-		if (typeof version !== "string" || typeof verdict !== "string" || typeof ageMs !== "number" || typeof rssKb !== "number") return null;
-		if (!Array.isArray(pids) || !pids.every((pid) => Number.isInteger(pid) && pid > 1)) return null;
-		units.push({ version, verdict, pids, ageMs, rssKb });
-	}
-	return units;
-}
-
 function entryType(path: string): GcEntry | null {
 	try {
 		const stat = lstatSync(path);
@@ -293,9 +96,10 @@ async function output(command: string[], env?: Record<string, string>): Promise<
 
 /**
  * Real file system and process access. `rpcEnv` is the environment of the `rpc-host-gc.ts` child, so it reads the same
- * home as the caller; `packageRoot` is where host/omo-bridge/rpc-host-gc.ts is.
+ * home as the caller; `packageRoot` is where host/omo-bridge/rpc-host-gc.ts is; `trash` moves a removed path away (tests
+ * inject one that stays inside their temp root).
  */
-export function systemGcDeps(packageRoot: string, rpcEnv: Record<string, string | undefined>): GcDeps {
+export function systemGcDeps(packageRoot: string, rpcEnv: Record<string, string | undefined>, trash: Trash = moveToTrash): GcDeps {
 	return {
 		now: Date.now,
 		list: (dir) => {
@@ -339,7 +143,11 @@ export function systemGcDeps(packageRoot: string, rpcEnv: Record<string, string
 			const run = await output([process.execPath, join(packageRoot, "host/omo-bridge/rpc-host-gc.ts"), "list", "--json"], env);
 			return run.code === 0 ? parseRpcUnits(run.out) : null;
 		},
-		remove: (path) => rmSync(path, { recursive: true }),
+		remove: async (path, kind) => {
+			const moved = await trash(path, kind);
+			if (!moved.ok) throw new Error(moved.error ?? "trash_failed");
+			return moved;
+		},
 		terminate: (pid) => process.kill(pid, "SIGTERM"),
 	};
 }

package/src/housekeeping/api.ts

@@ -0,0 +1,163 @@
+import { GC_CLEAN_PATH, GC_PATH, type GcCandidate, type GcCleanResult, type GcKind, type GcReport, parseSelection as parseGcSelection } from "../gc.ts";
+import type { InstallKind } from "../runtime/install-kind.ts";
+import { AUDIT_TAIL_DEFAULT, AUDIT_TAIL_MAX, type AuditLine } from "./audit.ts";
+import { GC_KINDS } from "./collectors/shared.ts";
+import type { CleanResult, CollectorReport, Housekeeping, Selection } from "./engine.ts";
+import type { Candidate, Confirmation, Reversibility, Role, Trigger, Verdict } from "./types.ts";
+
+/**
+ * Housekeeping todo 5: the web-port API of the engine and the /api/gc adapters kept for one released version (N-1).
+ * GET /api/housekeeping runs `scan("web_open")` (`?trigger=doctor` runs `scan("doctor")`) and returns the latest result of
+ * every collector by role; POST /api/housekeeping/clean acts only on the picked ids/collectors (operator).
+ */
+
+export const HOUSEKEEPING_PATH = "/api/housekeeping";
+export const HOUSEKEEPING_CLEAN_PATH = "/api/housekeeping/clean";
+export const HOUSEKEEPING_AUDIT_PATH = "/api/housekeeping/audit";
+
+export interface CandidateView extends Candidate { readonly verdict: Verdict; readonly confirmation: Confirmation; readonly reversibility: Reversibility }
+export interface KeptView { readonly id: string; readonly collector: string; readonly target: string; readonly why: string; readonly bytes: number | null; readonly reversibility: Reversibility }
+export interface CollectorView { readonly name: string; readonly confirmation: Confirmation; readonly reversibility: Reversibility; readonly scannedAt: string | null; readonly trigger: Trigger | null; readonly error: string | null }
+/** `candidates` are the open act/confirm verdicts (already acted items are left out); `kept` shows what a rule keeps, with why. */
+export interface RoleView {
+	readonly total: number;
+	readonly bytes: number;
+	readonly counts: Readonly<Record<string, number>>;
+	readonly candidates: readonly CandidateView[];
+	readonly kept: readonly KeptView[];
+	readonly collectors: readonly CollectorView[];
+}
+export interface HousekeepingReport { readonly kind: InstallKind; readonly roles: Readonly<Record<Role, RoleView>> }
+
+function roleView(reports: readonly CollectorReport[]): RoleView {
+	const candidates: CandidateView[] = [];
+	const kept: KeptView[] = [];
+	const counts: Record<string, number> = {};
+	for (const r of reports) {
+		let open = 0;
+		for (const item of r.items) {
+			if (item.result !== undefined) continue;
+			const c = item.candidate;
+			if (item.verdict.kind === "keep") {
+				kept.push({ id: c.id, collector: c.collector, target: c.target, why: item.verdict.why, bytes: c.bytes, reversibility: r.reversibility });
+				continue;
+			}
+			open += 1;
+			candidates.push({ ...c, verdict: item.verdict, confirmation: r.confirmation, reversibility: r.reversibility });
+		}
+		counts[r.name] = open;
+	}
+	return {
+		total: candidates.length,
+		bytes: candidates.reduce((sum, c) => sum + (c.bytes ?? 0), 0),
+		counts, candidates, kept,
+		collectors: reports.map((r) => ({ name: r.name, confirmation: r.confirmation, reversibility: r.reversibility, scannedAt: r.scannedAt, trigger: r.trigger, error: r.error })),
+	};
+}
+
+export function view(kind: InstallKind, reports: readonly CollectorReport[]): HousekeepingReport {
+	return { kind, roles: { reconcile: roleView(reports.filter((r) => r.role === "reconcile")), gc: roleView(reports.filter((r) => r.role === "gc")) } };
+}
+
+function oldCandidate(c: Candidate): GcCandidate {
+	const pids = c.details?.pids;
+	return { id: c.id, kind: c.collector as GcKind, target: c.target, reason: c.reason, ageMs: c.ageMs ?? 0, bytes: c.bytes, ...(Array.isArray(pids) ? { pids: pids as number[] } : {}) };
+}
+
+/** The old GcReport: the six kinds of improvement 66 only, built from the gc role. */
+export function gcView(report: HousekeepingReport): GcReport {
+	const candidates = report.roles.gc.candidates.filter((c) => (GC_KINDS as readonly string[]).includes(c.collector)).map(oldCandidate);
+	const counts = Object.fromEntries(GC_KINDS.map((kind) => [kind, candidates.filter((c) => c.kind === kind).length])) as Record<GcKind, number>;
+	return { kind: report.kind, total: candidates.length, bytes: candidates.reduce((sum, c) => sum + (c.bytes ?? 0), 0), counts, candidates };
+}
+
+/** The old GcCleanResult; a picked candidate a rule now keeps is reported failed with `kept:<why>`. */
+export function gcCleanResult(result: CleanResult): GcCleanResult {
+	return {
+		cleaned: result.cleaned.map(oldCandidate),
+		failed: [...result.failed, ...result.kept.map((k) => ({ id: k.id, error: `kept:${k.why}` }))],
+		missing: result.missing,
+	};
+}
+
+export type SelectionError = "selection_required" | "unknown_collector";
+
+/** The body of POST /api/housekeeping/clean: `{ ids?: string[], collectors?: string[] }` with at least one entry. */
+export function parseSelection(body: unknown, collectors: readonly string[]): Selection | SelectionError {
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return "selection_required";
+	const { ids = [], collectors: names = [] } = body as { ids?: unknown; collectors?: unknown };
+	if (!Array.isArray(ids) || !Array.isArray(names)) return "selection_required";
+	if (!ids.every((id) => typeof id === "string") || !names.every((name) => typeof name === "string")) return "selection_required";
+	if (ids.length + names.length === 0) return "selection_required";
+	if (!names.every((name) => collectors.includes(name))) return "unknown_collector";
+	return { ids: ids as string[], collectors: names as string[] };
+}
+
+/**
+ * Runs scans and cleans one at a time, in call order, so two triggers never run collectors at once (no timers: a promise
+ * chain). A scan asked for while a scan of the same trigger is still queued joins that queued scan.
+ */
+export function serialize(housekeeping: Housekeeping): Housekeeping {
+	let tail: Promise<unknown> = Promise.resolve();
+	const queued = new Map<Trigger, Promise<CollectorReport[]>>();
+	const run = <T>(task: () => Promise<T>): Promise<T> => {
+		const next = tail.then(task, task);
+		tail = next.catch(() => undefined);
+		return next;
+	};
+	return {
+		scan(trigger) {
+			const waiting = queued.get(trigger);
+			if (waiting !== undefined) return waiting;
+			const next = run(() => {
+				queued.delete(trigger);
+				return housekeeping.scan(trigger);
+			});
+			queued.set(trigger, next);
+			return next;
+		},
+		clean: (selection, actor) => run(() => housekeeping.clean(selection, actor)),
+		report: () => housekeeping.report(),
+	};
+}
+
+export interface HousekeepingApi {
+	readonly housekeeping: Housekeeping;
+	readonly kind: InstallKind;
+	readonly audit: { tail(limit?: number): AuditLine[] };
+	readonly collectors: readonly string[];
+}
+
+const bad = (error: string) => Response.json({ error }, { status: 400 });
+
+export async function handleHousekeeping(req: Request, api: HousekeepingApi): Promise<Response | null> {
+	const url = new URL(req.url);
+	const { housekeeping, kind } = api;
+	if (url.pathname === HOUSEKEEPING_PATH && req.method === "GET") {
+		const asked = url.searchParams.get("trigger");
+		if (asked !== null && asked !== "doctor") return bad("bad_trigger");
+		await housekeeping.scan(asked === "doctor" ? "doctor" : "web_open");
+		return Response.json(view(kind, housekeeping.report()));
+	}
+	if (url.pathname === HOUSEKEEPING_CLEAN_PATH && req.method === "POST") {
+		const selection = parseSelection(await req.json().catch(() => null), api.collectors);
+		if (typeof selection === "string") return bad(selection);
+		return Response.json(await housekeeping.clean(selection, "operator"));
+	}
+	if (url.pathname === HOUSEKEEPING_AUDIT_PATH && req.method === "GET") {
+		const asked = url.searchParams.get("limit");
+		if (asked !== null && !/^[1-9]\d*$/.test(asked)) return bad("bad_limit");
+		const limit = asked === null ? AUDIT_TAIL_DEFAULT : Math.min(Number(asked), AUDIT_TAIL_MAX);
+		return Response.json({ lines: api.audit.tail(limit) });
+	}
+	if (url.pathname === GC_PATH && req.method === "GET") {
+		await housekeeping.scan("web_open");
+		return Response.json(gcView(view(kind, housekeeping.report())));
+	}
+	if (url.pathname === GC_CLEAN_PATH && req.method === "POST") {
+		const selection = parseGcSelection(await req.json().catch(() => null));
+		if (selection === null) return bad("selection_required");
+		return Response.json(gcCleanResult(await housekeeping.clean({ ids: selection.ids, collectors: selection.kinds }, "operator")));
+	}
+	return null;
+}

package/src/housekeeping/audit.ts

@@ -0,0 +1,61 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ActResult, Trigger, Verdict } from "./types.ts";
+
+export type AuditActor = "auto" | "operator" | "reconcile";
+
+/** One line of `<home>/logs/housekeeping.jsonl`. `trigger` is null for an operator or reconcile clean; `verdict` "error" means find/judge threw. */
+export interface AuditLine {
+	at: string;
+	trigger: Trigger | null;
+	actor: AuditActor;
+	collector: string;
+	id: string | null;
+	target: string | null;
+	verdict: Verdict["kind"] | "error";
+	evidence: Record<string, unknown> | null;
+	method: ActResult["method"] | null;
+	ok: boolean;
+	error?: string;
+}
+
+export interface AuditSink {
+	append(line: AuditLine): void;
+}
+
+export const AUDIT_TAIL_DEFAULT = 100;
+export const AUDIT_TAIL_MAX = 1000;
+
+export function auditPath(home: string): string {
+	return join(home, "logs", "housekeeping.jsonl");
+}
+
+export function createAudit(file: string): AuditSink & { tail(limit?: number): AuditLine[] } {
+	return {
+		append(line) {
+			mkdirSync(dirname(file), { recursive: true });
+			appendFileSync(file, `${JSON.stringify(line)}\n`);
+		},
+		tail(limit = AUDIT_TAIL_DEFAULT) {
+			const count = Math.min(Math.max(Math.floor(limit), 0), AUDIT_TAIL_MAX);
+			if (count === 0) return [];
+			let text: string;
+			try {
+				text = readFileSync(file, "utf8");
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+				throw error;
+			}
+			const lines: AuditLine[] = [];
+			for (const raw of text.split("\n")) {
+				if (raw.trim() === "") continue;
+				try {
+					lines.push(JSON.parse(raw) as AuditLine);
+				} catch {
+					continue;
+				}
+			}
+			return lines.slice(-count);
+		},
+	};
+}

package/src/housekeeping/collectors/agent-collaboration.ts

@@ -0,0 +1,33 @@
+import { say, type Text } from "../../server-text.ts";
+import type { Candidate, Collector } from "../types.ts";
+
+export interface AgentCollaborationCleanupRow { readonly artifactId: string; readonly target: string; readonly state: string; readonly bytes: number }
+export interface AgentCollaborationCleanupDeps {
+	readonly list: () => readonly AgentCollaborationCleanupRow[];
+	/** Moves one artifact to the Trash after the Store repeats its reference checks; a kept reference throws. */
+	readonly cleanup: (artifactId: string) => Promise<void>;
+}
+
+const REASON: Text = { en: "Agent collaboration file no longer kept by a request ({state})", ko: "더 이상 요청이 보관하지 않는 에이전트 협업 파일입니다({state})" };
+const candidate = (row: AgentCollaborationCleanupRow): Candidate => ({ id: `agent-collaboration:${row.artifactId}`, collector: "agent-collaboration",
+	target: row.target, reason: say(REASON, { state: row.state }), ageMs: null, bytes: row.bytes, details: { artifactId: row.artifactId } });
+
+/** Only an operator-selected artifact moves to the Trash; time plays no part and a scan changes nothing. */
+export const agentCollaborationCleanup: Collector<AgentCollaborationCleanupDeps> = {
+	name: "agent-collaboration",
+	role: "gc",
+	triggers: ["web_open", "doctor"],
+	confirmation: "operator",
+	reversibility: "trash",
+	find: async deps => deps.list().map(candidate),
+	judge: async (c, deps) => {
+		const row = deps.list().find(item => item.artifactId === c.details?.artifactId);
+		if (!row) return { kind: "keep", why: "no_longer_a_candidate" };
+		return { kind: "act", why: "rule_holds", evidence: { state: row.state } };
+	},
+	act: async (c, deps) => {
+		try { await deps.cleanup(String(c.details?.artifactId)); }
+		catch (error) { return { ok: false, method: "trash", error: error instanceof Error ? error.message : String(error) }; }
+		return { ok: true, method: "trash" };
+	},
+};

package/src/housekeeping/collectors/agent-drafts.ts

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import { utcIsoTime } from "../../agent/files.ts";
+import { say, type Text } from "../../server-text.ts";
+import { AGENT_TRASH_MIN_AGE_MS, DAY_MS, type GcCandidate, gcCollector, type GcDeps, type GcRoots } from "./shared.ts";
+
+/**
+ * Agent drafts in agents/.drafts/ and archived drafts in agents/.drafts-trash/, unchanged for AGENT_TRASH_MIN_AGE_MS:
+ * the age comes from the draft's own `updatedAt` (a strict UTC ISO time), or from the file mtime when the draft cannot be
+ * read or the time is not one toISOString writes.
+ */
+
+export const REASON_AGENT_DRAFT: Text = { en: "Agent draft not changed for more than {days} days", ko: "{days}일 넘게 바뀌지 않은 에이전트 임시 저장" };
+
+function updatedAt(text: string | null): number | null {
+	if (text === null) return null;
+	let value: { readonly updatedAt?: unknown } | null;
+	try {
+		// Any JSON value: property access on a number, string or array yields undefined, and null is caught by ?.
+		value = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	const at = value?.updatedAt;
+	return typeof at === "string" ? utcIsoTime(at) : null;
+}
+
+export function agentDraftCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
+	const now = deps.now();
+	const out: GcCandidate[] = [];
+	for (const folder of [".drafts", ".drafts-trash"]) {
+		const dir = join(roots.agents, folder);
+		for (const entry of deps.list(dir) ?? []) {
+			if (entry.type !== "file" || !entry.name.endsWith(".json")) continue;
+			const target = join(dir, entry.name);
+			const ageMs = now - (updatedAt(deps.readText(target)) ?? entry.mtimeMs);
+			if (ageMs <= AGENT_TRASH_MIN_AGE_MS) continue;
+			out.push({ id: `agent-drafts:${target}`, kind: "agent-drafts", target, reason: say(REASON_AGENT_DRAFT, { days: AGENT_TRASH_MIN_AGE_MS / DAY_MS }), ageMs, bytes: null });
+		}
+	}
+	return out;
+}
+
+export const agentDrafts = gcCollector({ kind: "agent-drafts", npmOnly: true, root: (roots) => roots.agents, candidates: agentDraftCandidates });

package/src/housekeeping/collectors/agent-file-trash.ts

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+import { parseAgentFileTrashName } from "../../agent/files.ts";
+import { say, type Text } from "../../server-text.ts";
+import { AGENT_TRASH_MIN_AGE_MS, DAY_MS, type GcCandidate, gcCollector, type GcDeps, type GcRoots } from "./shared.ts";
+
+/**
+ * Deleted agent knowledge files in agents/.file-trash/<id>/, older than AGENT_TRASH_MIN_AGE_MS by the time in the
+ * entry name only (the store writes it; folder and file mtimes change when files move). Each file is one candidate; the
+ * per-agent folders stay for the next deletion.
+ */
+
+export const REASON_AGENT_FILE_TRASH: Text = { en: "Deleted agent knowledge file older than {days} days", ko: "삭제한 지 {days}일 지난 에이전트 지식 파일" };
+
+export function agentFileTrashCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
+	const trash = join(roots.agents, ".file-trash");
+	const agents = deps.list(trash);
+	if (agents === null) return [];
+	const now = deps.now();
+	const out: GcCandidate[] = [];
+	for (const agent of agents) {
+		if (agent.type !== "dir") continue;
+		const folder = join(trash, agent.name);
+		for (const entry of deps.list(folder) ?? []) {
+			if (entry.type !== "file") continue;
+			const parsed = parseAgentFileTrashName(entry.name);
+			if (parsed === null) continue;
+			const ageMs = now - parsed.deletedAt;
+			if (ageMs <= AGENT_TRASH_MIN_AGE_MS) continue;
+			const target = join(folder, entry.name);
+			out.push({ id: `agent-file-trash:${target}`, kind: "agent-file-trash", target, reason: say(REASON_AGENT_FILE_TRASH, { days: AGENT_TRASH_MIN_AGE_MS / DAY_MS }), ageMs, bytes: null });
+		}
+	}
+	return out;
+}
+
+export const agentFileTrash = gcCollector({ kind: "agent-file-trash", npmOnly: true, root: (roots) => join(roots.agents, ".file-trash"), candidates: agentFileTrashCandidates });