zigmini 0.9.0-beta.3 → 1.0.0-beta.1

package/src/engine/schema-guard.ts

@@ -2,6 +2,7 @@ import { Database } from "bun:sqlite";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
+import { say, type Text } from "../server-text.ts";
 
 /**
  * Bug 73 prevention (plan Todo 12). The gateway's OMO shares the user's agent folder, whose thread gateway store
@@ -17,7 +18,15 @@ export const STORE = join("gateway", "gateway.sqlite");
 export const GUARD_FILE = "schema-guard.json";
 export const GLOBAL_ENGINE_PACKAGE = join("install", "global", "node_modules", "omo-ai", "package.json");
 export const SCHEMA_TOO_NEW = "schema_too_new";
-export const NOTICE_TITLE = "엔진 스키마 충돌: 브리지를 멈췄습니다";
+export const NOTICE_TITLE: Text = { en: "Engine schema conflict: the bridge was stopped", ko: "엔진 스키마 충돌: 브리지를 멈췄습니다" };
+
+const TOO_NEW: Text = {
+	en: "The shared folder schema is {schema}, which this gateway engine cannot read (global OMO installed now: {version}; who raised the schema was not checked). " +
+		"Get a matching version with `zigmini update`, or use an agent folder only for this gateway (`zigmini setup --agent-dir`)",
+	ko: "공유 폴더 스키마가 {schema}이라 이 게이트웨이 엔진이 읽지 못합니다(지금 설치된 전역 OMO: {version}, 스키마를 올린 주체는 확인하지 않음). " +
+		"`zigmini update`로 맞는 버전을 받거나, 이 게이트웨이 전용 에이전트 폴더를 쓰세요(`zigmini setup --agent-dir`)",
+};
+const VERSION_UNKNOWN: Text = { en: "version unknown", ko: "버전 알 수 없음" };
 
 export type StoreReading =
 	| { readonly state: "ok"; readonly version: number }
@@ -128,8 +137,7 @@ export function compareVersions(a: string, b: string): number {
 
 /** Findings 214-217: the installed global version is an observation, not the proven actor of the schema change. */
 export function tooNewMessage(schema: number, globalVersion: string | null): string {
-	return `공유 폴더 스키마가 ${schema}이라 이 게이트웨이 엔진이 읽지 못합니다(지금 설치된 전역 OMO: ${globalVersion ?? "버전 알 수 없음"}, 스키마를 올린 주체는 확인하지 않음). ` +
-		"`zigmini update`로 맞는 버전을 받거나, 이 게이트웨이 전용 에이전트 폴더를 쓰세요(`zigmini setup --agent-dir`)";
+	return say(TOO_NEW, { schema, version: globalVersion ?? say(VERSION_UNKNOWN) });
 }
 
 export const SCHEMA_INCOMPATIBLE = "schema_incompatible";
@@ -210,7 +218,7 @@ export function healthOmo(status: string, saved: SavedGuard | null): string {
 /** The one notice per refusal (keyed by its time) the gateway sends to the web and app; null when already sent. */
 export function pendingNotice(saved: SavedGuard | null, status: string, sentAt: string | null): { readonly key: string; readonly title: string; readonly note: string } | null {
 	if (saved === null || healthOmo(status, saved) !== SCHEMA_TOO_NEW || saved.at === sentAt) return null;
-	return { key: saved.at, title: NOTICE_TITLE, note: saved.message ?? "" };
+	return { key: saved.at, title: say(NOTICE_TITLE), note: saved.message ?? "" };
 }
 
 /** Doctor: a global OMO newer than the gateway's pinned engine can migrate the shared store past it. */

package/src/engine/sdk.ts

@@ -0,0 +1,8 @@
+import { realpathSync } from "node:fs";
+import { runtimeHome } from "../runtime/paths.ts";
+import { omoAi } from "./omo-ai.ts";
+
+/** Load the public SDK of the installed engine. The module name stays inside the Docker-shipped engine boundary. */
+export function loadEngineSdk<T>(): Promise<T> {
+	return import(Bun.resolveSync("@code-yeongyu/senpi", realpathSync(omoAi.binPath(runtimeHome()))));
+}

package/src/formal-verification.ts

@@ -0,0 +1,366 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { say, type Text } from "./server-text.ts";
+
+/**
+ * Improvement 250 and bug 259: the formal verification setting. One switch per tool in FORMAL_TOOLS (only TLA+/TLC
+ * today; later tools are new registry entries); a switch means "use this tool in checks once it is installed" and never
+ * installs anything. Only the tool's Install action (POST FORMAL_TOOLS_PATH/<id>/install) installs it with Homebrew
+ * (`brew install <package>`, never `brew link`, so the system java stays as it is) and downloads its pinned files with a
+ * size and SHA-256 check. A failed install shows the cause on that tool and keeps its switch. The state is one JSON file
+ * in the data dir; installed files live in <home>/formal-tools.
+ */
+
+export const FORMAL_VERIFICATION_PATH = "/api/settings/formal-verification";
+export const FORMAL_TOOLS_PATH = `${FORMAL_VERIFICATION_PATH}/tools`;
+
+export interface FormalArtifact { readonly name: string; readonly url: string; readonly sha256: string; readonly size: number }
+export interface FormalTool {
+	readonly id: string;
+	readonly label: string;
+	readonly description: Text;
+	/** Homebrew formulas; each must provide `<brew --prefix formula>/bin/java` when `java` names it. */
+	readonly brew: readonly string[];
+	readonly java?: string;
+	readonly artifacts: readonly FormalArtifact[];
+	/** Default of the tool switch; the overall switch is off by default. */
+	readonly defaultOn: boolean;
+}
+
+export const FORMAL_TOOLS: readonly FormalTool[] = [{
+	id: "tla-tlc",
+	label: "TLA+ (TLC 1.7.4)",
+	description: {
+		en: "Checks every execution order of concurrent designs (such as session replacement). Installs Homebrew openjdk@21 and tla2tools.jar 1.7.4.",
+		ko: "동시 실행 설계(세션 교체 등)의 모든 실행 순서를 검사합니다. Homebrew openjdk@21과 tla2tools.jar 1.7.4를 설치합니다.",
+	},
+	brew: ["openjdk@21"],
+	java: "openjdk@21",
+	artifacts: [{
+		name: "tla2tools-1.7.4.jar",
+		url: "https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar",
+		sha256: "936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88",
+		size: 2274532,
+	}],
+	defaultOn: true,
+}];
+
+export interface FormalSettings { readonly tools: Readonly<Record<string, boolean>> }
+export type ToolStatus = "off" | "not_installed" | "installing" | "installed" | "failed";
+export interface ToolState {
+	readonly id: string; readonly label: string; readonly description: string;
+	readonly enabled: boolean; readonly status: ToolStatus; readonly error: string | null;
+}
+/**
+ * `enabled` (some tool switch is on) and `error` (always null) stay for apps from before bug 259, which read them and show
+ * an overall switch; the web and newer apps show only the tools. `revision` grows with every published change (it starts
+ * at the process start time in ms, so it also grows across a restart); a client drops a state older than the one it shows,
+ * because the answer to an Install request can arrive after the events of an install that already ended.
+ */
+export interface FormalState {
+	readonly enabled: boolean; readonly busy: boolean; readonly error: string | null; readonly revision: number; readonly tools: readonly ToolState[];
+}
+export interface Installed { readonly java: string | null; readonly files: Readonly<Record<string, string>> }
+
+export const FORMAL_ERRORS: Readonly<Record<string, Text>> = {
+	brew_missing: { en: "Homebrew (brew) was not found. Install Homebrew from https://brew.sh, then press Install again.", ko: "Homebrew(brew)를 찾지 못했습니다. https://brew.sh 에서 Homebrew를 설치한 뒤 설치를 다시 누르세요." },
+	brew_failed: { en: "brew install failed.", ko: "brew install이 실패했습니다." },
+	java_missing: { en: "The installed Java was not found.", ko: "설치한 Java를 찾지 못했습니다." },
+	download_failed: { en: "The tool files could not be downloaded.", ko: "도구 파일을 내려받지 못했습니다." },
+	size_mismatch: { en: "The size of the downloaded file differs from the pinned value.", ko: "내려받은 파일의 크기가 고정값과 다릅니다." },
+	hash_mismatch: { en: "The SHA-256 of the downloaded file differs from the pinned value.", ko: "내려받은 파일의 SHA-256이 고정값과 다릅니다." },
+};
+
+/** The error text of a code in the current language; an unknown code stays as the code. */
+function errorText(code: string): string {
+	const text = FORMAL_ERRORS[code];
+	return text === undefined ? code : say(text);
+}
+
+export function readFormalSettings(file: string, tools: readonly FormalTool[] = FORMAL_TOOLS): FormalSettings {
+	let raw: unknown = null;
+	try { raw = JSON.parse(readFileSync(file, "utf8")); } catch { raw = null; }
+	const body = typeof raw === "object" && raw !== null ? raw as { enabled?: unknown; tools?: unknown } : {};
+	const saved = typeof body.tools === "object" && body.tools !== null ? body.tools as Record<string, unknown> : {};
+	// A file from before bug 259 has the overall switch; when it was not on, no tool ran, so every tool stays off.
+	const legacyOff = "enabled" in body && body.enabled !== true;
+	const out: Record<string, boolean> = {};
+	for (const tool of tools) out[tool.id] = legacyOff ? false : typeof saved[tool.id] === "boolean" ? saved[tool.id] as boolean : tool.defaultOn;
+	return { tools: out };
+}
+
+export function writeFormalSettings(file: string, settings: FormalSettings): void {
+	const dir = dirname(file);
+	mkdirSync(dir, { recursive: true });
+	const temp = join(dir, `.${basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+	try {
+		writeFileSync(temp, `${JSON.stringify(settings)}\n`);
+		renameSync(temp, file);
+	} catch (error) {
+		rmSync(temp, { force: true });
+		throw error;
+	}
+}
+
+export function sha256File(path: string): string {
+	return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/** The installed files of one tool, or null when any pinned file or the recorded java is missing or does not match. */
+export function installedTool(tool: FormalTool, toolsDir: string): Installed | null {
+	const files: Record<string, string> = {};
+	for (const artifact of tool.artifacts) {
+		const path = join(toolsDir, tool.id, artifact.name);
+		if (!existsSync(path) || statSync(path).size !== artifact.size || sha256File(path) !== artifact.sha256) return null;
+		files[artifact.name] = path;
+	}
+	let java: string | null = null;
+	if (tool.java !== undefined) {
+		try { java = (JSON.parse(readFileSync(join(toolsDir, tool.id, "java.json"), "utf8")) as { java?: unknown }).java as string; }
+		catch { return null; }
+		if (typeof java !== "string" || !existsSync(java)) return null;
+	}
+	return { java, files };
+}
+
+export interface RunResult { readonly code: number; readonly stdout: string; readonly stderr: string }
+export interface FormalDeps {
+	/** The brew executable, or null when Homebrew is not installed. */
+	readonly brew: () => string | null;
+	readonly run: (cmd: string, args: readonly string[]) => Promise<RunResult>;
+	readonly fetch: (url: string) => Promise<Response>;
+}
+
+export function findBrew(env: Record<string, string | undefined> = process.env, exists: (path: string) => boolean = existsSync): string | null {
+	const candidates = env.ZGW_BREW_BIN !== undefined ? [env.ZGW_BREW_BIN] : ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"];
+	return candidates.find((path) => path.length > 0 && exists(path)) ?? null;
+}
+
+export function defaultFormalDeps(env: Record<string, string | undefined> = process.env): FormalDeps {
+	return {
+		brew: () => findBrew(env),
+		run: async (cmd, args) => {
+			const child = Bun.spawn([cmd, ...args], { stdout: "pipe", stderr: "pipe", env: { ...process.env, HOMEBREW_NO_AUTO_UPDATE: "1" } });
+			const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+			return { code, stdout, stderr };
+		},
+		fetch: (url) => fetch(url, { redirect: "follow" }),
+	};
+}
+
+class InstallError extends Error {
+	constructor(readonly code: string, readonly detail = "") { super(code); }
+}
+
+/** Installs one tool. Throws InstallError; leaves no partial download behind. */
+export async function installTool(tool: FormalTool, toolsDir: string, deps: FormalDeps): Promise<Installed> {
+	const brew = deps.brew();
+	if (brew === null) throw new InstallError("brew_missing");
+	for (const formula of tool.brew) {
+		const listed = await deps.run(brew, ["list", "--versions", formula]);
+		if (listed.code === 0 && listed.stdout.trim() !== "") continue;
+		const result = await deps.run(brew, ["install", formula]);
+		if (result.code !== 0) throw new InstallError("brew_failed", `${formula}: ${result.stderr.trim().split("\n").slice(-3).join(" ")}`);
+	}
+	const dir = join(toolsDir, tool.id);
+	mkdirSync(dir, { recursive: true });
+	if (tool.java !== undefined) {
+		const prefix = await deps.run(brew, ["--prefix", tool.java]);
+		const java = join(prefix.stdout.trim(), "bin/java");
+		if (prefix.code !== 0 || prefix.stdout.trim() === "" || !existsSync(java)) throw new InstallError("java_missing", tool.java);
+		writeFileSync(join(dir, "java.json"), `${JSON.stringify({ java })}\n`);
+	}
+	for (const artifact of tool.artifacts) {
+		const target = join(dir, artifact.name);
+		if (existsSync(target) && statSync(target).size === artifact.size && sha256File(target) === artifact.sha256) continue;
+		let bytes: Uint8Array;
+		try {
+			const response = await deps.fetch(artifact.url);
+			if (!response.ok) throw new InstallError("download_failed", `HTTP ${response.status}`);
+			bytes = new Uint8Array(await response.arrayBuffer());
+		} catch (error) {
+			if (error instanceof InstallError) throw error;
+			throw new InstallError("download_failed", error instanceof Error ? error.message : String(error));
+		}
+		if (bytes.byteLength !== artifact.size) throw new InstallError("size_mismatch", `${artifact.name}: ${bytes.byteLength}`);
+		const hash = createHash("sha256").update(bytes).digest("hex");
+		if (hash !== artifact.sha256) throw new InstallError("hash_mismatch", artifact.name);
+		const temp = `${target}.${process.pid}.tmp`;
+		writeFileSync(temp, bytes);
+		renameSync(temp, target);
+	}
+	const installed = installedTool(tool, toolsDir);
+	if (installed === null) throw new InstallError("java_missing", tool.id);
+	return installed;
+}
+
+function message(error: unknown): string {
+	if (error instanceof InstallError) return `${errorText(error.code)}${error.detail ? ` (${error.detail})` : ""}`;
+	return error instanceof Error ? error.message : String(error);
+}
+
+export class FormalVerification {
+	private settings: FormalSettings;
+	private readonly status = new Map<string, { status: ToolStatus; error: string | null }>();
+	private running: Promise<void> | null = null;
+	private revision = Date.now();
+
+	constructor(readonly file: string, readonly toolsDir: string, private readonly deps: FormalDeps,
+		private readonly publish: (state: FormalState) => void = () => {}, readonly tools: readonly FormalTool[] = FORMAL_TOOLS) {
+		this.settings = readFormalSettings(file, tools);
+	}
+
+	/** Resolves when the install started last has ended (tests and shutdown). */
+	idle(): Promise<void> { return this.running ?? Promise.resolve(); }
+
+	state(): FormalState {
+		return {
+			enabled: this.tools.some((tool) => this.settings.tools[tool.id] === true), busy: this.running !== null, error: null, revision: this.revision,
+			tools: this.tools.map((tool) => {
+				const enabled = this.settings.tools[tool.id] === true;
+				const known = this.status.get(tool.id);
+				const status: ToolStatus = known?.status === "installing" ? "installing"
+					: installedTool(tool, this.toolsDir) !== null ? "installed"
+					: known?.status === "failed" ? "failed" : "not_installed";
+				return { id: tool.id, label: tool.label, description: say(tool.description), enabled, status, error: status === "failed" ? known?.error ?? null : null };
+			}),
+		};
+	}
+
+	private save(settings: FormalSettings): void {
+		writeFormalSettings(this.file, settings);
+		this.settings = settings;
+	}
+
+	/**
+	 * The overall PUT that apps from before bug 259 still send: on installs every switched-on tool that is not installed,
+	 * off turns every tool switch off. Returns "busy" while an install runs, else the new state.
+	 */
+	setEnabled(enabled: boolean): FormalState | "busy" {
+		if (this.running) return "busy";
+		if (!enabled) {
+			this.save({ tools: Object.fromEntries(this.tools.map((tool) => [tool.id, false])) });
+			return this.emit();
+		}
+		this.start(this.tools.filter((tool) => this.settings.tools[tool.id] === true));
+		return this.emit();
+	}
+
+	/** Saves whether checks use the tool; installs nothing. "busy" while an install runs, "unknown_tool" for an id not in the registry. */
+	setTool(id: string, enabled: boolean): FormalState | "busy" | "unknown_tool" {
+		if (!this.tools.some((candidate) => candidate.id === id)) return "unknown_tool";
+		if (this.running) return "busy";
+		this.save({ tools: { ...this.settings.tools, [id]: enabled } });
+		return this.emit();
+	}
+
+	/** The Install action of one tool: installs it when it is not installed, whatever its switch. */
+	install(id: string): FormalState | "busy" | "unknown_tool" {
+		const tool = this.tools.find((candidate) => candidate.id === id);
+		if (tool === undefined) return "unknown_tool";
+		if (this.running) return "busy";
+		this.start([tool]);
+		return this.emit();
+	}
+
+	private start(tools: readonly FormalTool[]): void {
+		const pending = tools.filter((tool) => installedTool(tool, this.toolsDir) === null);
+		if (pending.length === 0) return;
+		for (const tool of pending) this.status.set(tool.id, { status: "installing", error: null });
+		this.running = (async () => {
+			for (const tool of pending) {
+				try {
+					await installTool(tool, this.toolsDir, this.deps);
+					this.status.set(tool.id, { status: "installed", error: null });
+				} catch (error) {
+					this.status.set(tool.id, { status: "failed", error: message(error) });
+				}
+				this.emit();
+			}
+		})().finally(() => {
+			this.running = null;
+			this.emit();
+		});
+	}
+
+	private emit(): FormalState {
+		this.revision++;
+		const state = this.state();
+		this.publish(state);
+		return state;
+	}
+}
+
+/**
+ * GET (both ports) of FORMAL_VERIFICATION_PATH; PUT (trusted web port) of it and of FORMAL_TOOLS_PATH/<id>; POST
+ * (trusted web port, no body) of FORMAL_TOOLS_PATH/<id>/install.
+ */
+export async function handleFormalVerification(req: Request, url: URL, trusted: boolean, formal: FormalVerification): Promise<Response | null> {
+	const root = url.pathname === FORMAL_VERIFICATION_PATH;
+	const toolId = url.pathname.startsWith(`${FORMAL_TOOLS_PATH}/`) ? decodeURIComponent(url.pathname.slice(FORMAL_TOOLS_PATH.length + 1)) : null;
+	if (!root && toolId === null) return null;
+	const json = (value: unknown, status = 200) => Response.json(value, { status, headers: { "Cache-Control": "no-store" } });
+	if (req.method === "GET" && root) return json(formal.state());
+	const install = req.method === "POST" && toolId !== null && toolId.endsWith("/install");
+	if (req.method !== "PUT" && !install) return null;
+	if (!trusted) return json({ error: "forbidden" }, 403);
+	if (install) {
+		const result = formal.install(toolId.slice(0, -"/install".length));
+		if (result === "busy") return json({ error: "busy", state: formal.state() }, 409);
+		if (result === "unknown_tool") return json({ error: "unknown_tool" }, 404);
+		return json(result);
+	}
+	const body = (await req.json().catch(() => null)) as { enabled?: unknown } | null;
+	if (typeof body?.enabled !== "boolean") return json({ error: "enabled_required" }, 400);
+	const result = root ? formal.setEnabled(body.enabled) : formal.setTool(toolId!, body.enabled);
+	if (result === "busy") return json({ error: "busy", state: formal.state() }, 409);
+	if (result === "unknown_tool") return json({ error: "unknown_tool" }, 404);
+	return json(result);
+}
+
+// ---- The check entry point (bun run formal:check) ----
+
+export interface CheckDeps {
+	readonly run: (cmd: string, args: readonly string[], cwd: string) => Promise<number>;
+	readonly log: (line: string) => void;
+}
+export type CheckExit = 0 | 1;
+export interface CheckOptions { readonly repo: string; readonly settingsFile: string; readonly toolsDir: string; readonly timeoutS: number }
+
+/** TLA+ models are specs/tla/<Name>.tla with a matching <Name>.cfg (the plan's first stage). */
+export function tlaModels(repo: string): { spec: string; cfg: string }[] {
+	const dir = join(repo, "specs/tla");
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((name) => name.endsWith(".cfg")).sort().flatMap((cfg) => {
+		const spec = `${cfg.replace(/_[^_]*\.cfg$|\.cfg$/, "")}.tla`;
+		return existsSync(join(dir, spec)) ? [{ spec: join(dir, spec), cfg: join(dir, cfg) }] : [];
+	});
+}
+
+/**
+ * 0: every enabled, installed tool passed or was skipped with a notice; 1: a check failed. Off, not installed and no
+ * model are skips, not failures, so a project without formal verification is not blocked.
+ */
+export async function formalCheck(options: CheckOptions, deps: CheckDeps, tools: readonly FormalTool[] = FORMAL_TOOLS): Promise<CheckExit> {
+	const settings = readFormalSettings(options.settingsFile, tools);
+	let failed = false;
+	for (const tool of tools) {
+		if (settings.tools[tool.id] !== true) { deps.log(`${tool.label}: 설정에서 꺼져 있어 건너뜁니다.`); continue; }
+		const installed = installedTool(tool, options.toolsDir);
+		if (installed === null) { deps.log(`${tool.label}: 설치되지 않아 건너뜁니다. 설정의 형식 검증에서 이 도구의 설치 버튼을 누르면 설치합니다.`); continue; }
+		if (tool.id !== "tla-tlc") continue;
+		const models = tlaModels(options.repo);
+		if (models.length === 0) { deps.log(`${tool.label}: 검사할 모델(specs/tla/*.tla + .cfg)이 없어 건너뜁니다.`); continue; }
+		const jar = installed.files[tool.artifacts[0]!.name]!;
+		for (const model of models) {
+			const meta = join(options.toolsDir, tool.id, "states", crypto.randomUUID());
+			const code = await deps.run("perl", ["-e", "alarm shift; exec @ARGV", String(options.timeoutS), installed.java!, "-XX:+UseParallelGC",
+				"-cp", jar, "tlc2.TLC", "-workers", "auto", "-metadir", meta, "-config", model.cfg, model.spec], dirname(model.spec));
+			rmSync(meta, { recursive: true, force: true });
+			deps.log(`${tool.label}: ${basename(model.cfg)} ${code === 0 ? "통과" : `실패(종료 코드 ${code})`}`);
+			if (code !== 0) failed = true;
+		}
+	}
+	return failed ? 1 : 0;
+}

package/src/gc.ts

@@ -1,6 +1,8 @@
 import { lstatSync, readdirSync, readFileSync, readlinkSync, rmSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, 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";
 
 /**
  * Improvement 66 (plan Todo 24): the gateway's resource cleanup (GC). `findCandidates` only reads and lists; `clean`
@@ -12,21 +14,30 @@ import type { InstallKind } from "./runtime/install-kind.ts";
  *   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.
  * 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).
  */
 
-export const GC_KINDS = ["db-backup", "omo-version", "update-file", "temp-dir", "rpc-daemon"] as const;
+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 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. */
@@ -52,6 +63,7 @@ export interface GcRoots {
 	readonly omo: string;
 	readonly update: string;
 	readonly tmp: string;
+	readonly agents: string;
 }
 
 type MaybeAsync<T> = T | Promise<T>;
@@ -104,7 +116,7 @@ export function backupCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
 		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: `최근 ${KEEP_BACKUPS}개 밖이고 ${BACKUP_KEEP_MS / DAY_MS}일 지남`, ageMs, bytes: null });
+		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;
 }
@@ -127,7 +139,7 @@ export async function omoCandidates(roots: GcRoots, deps: GcDeps): Promise<GcCan
 		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: `현재(${current})·직전 버전이 아니고 실행 중인 프로세스 없음`, ageMs: now - entry.mtimeMs, bytes: null });
+		out.push({ id: `omo-version:${target}`, kind: "omo-version", target, reason: say(REASON_OMO, { current }), ageMs: now - entry.mtimeMs, bytes: null });
 	}
 	return out;
 }
@@ -142,7 +154,7 @@ export function updateCandidates(roots: GcRoots, deps: GcDeps): GcCandidate[] {
 		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: `${UPDATE_MIN_AGE_MS / DAY_MS}일 지난 업데이트 로그·요청 파일`, ageMs, bytes: null });
+		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;
 }
@@ -160,7 +172,7 @@ export async function tempCandidates(roots: GcRoots, deps: GcDeps): Promise<GcCa
 		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: `${TEMP_MIN_AGE_MS / DAY_MS}일 지났고 쓰는 프로세스 없음`, ageMs: now - entry.mtimeMs, bytes: null });
+		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;
 }
@@ -170,15 +182,34 @@ export async function daemonCandidates(deps: GcDeps): Promise<GcCandidate[]> {
 	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: "이전 버전 RPC 호스트 데몬, 부모 없음, 연결된 클라이언트 없음", ageMs: unit.ageMs, bytes: unit.rssKb * 1024, pids: unit.pids,
+		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)));