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

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

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { agentTrashTimestamp } 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 folders in agents/.trash, older than AGENT_TRASH_MIN_AGE_MS by name timestamp or mtime. */
+
+export const REASON_AGENT_TRASH: Text = { en: "Archived agent folder older than {days} days", ko: "{days}일 지난 에이전트 보관 폴더" };
+
+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;
+}
+
+export const agentTrash = gcCollector({ kind: "agent-trash", npmOnly: true, root: (roots) => join(roots.agents, ".trash"), candidates: agentTrashCandidates });

package/src/housekeeping/collectors/attachment-cleanup.ts

@@ -0,0 +1,35 @@
+import { say, type Text } from "../../server-text.ts";
+import type { Candidate, Collector } from "../types.ts";
+
+export interface AttachmentBusy { readonly grants: number; readonly readers: number; readonly preparing: number; readonly uncertain: number }
+export interface AttachmentCleanupRow { readonly attachmentId: string; readonly target: string; readonly state: string; readonly bytes: number; readonly busy: AttachmentBusy }
+export interface AttachmentCleanupDeps {
+	readonly list: () => readonly AttachmentCleanupRow[];
+	readonly cleanup: (attachmentId: string) => Promise<void>;
+}
+
+const REASON: Text = { en: "Attachment no longer in use ({state})", ko: "더 이상 쓰지 않는 첨부 파일입니다({state})" };
+const isBusy = (busy: AttachmentBusy) => busy.grants + busy.readers + busy.preparing + busy.uncertain > 0;
+const candidate = (row: AttachmentCleanupRow): Candidate => ({ id: `attachment-cleanup:${row.attachmentId}`, collector: "attachment-cleanup", target: row.target,
+	reason: say(REASON, { state: row.state }), ageMs: null, bytes: row.bytes, details: { attachmentId: row.attachmentId, busy: row.busy } });
+
+/** Only a selected id moves to the Trash: the operator confirmation keeps every scan read-only and time plays no part. */
+export const attachmentCleanup: Collector<AttachmentCleanupDeps> = {
+	name: "attachment-cleanup",
+	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.attachmentId === c.details?.attachmentId);
+		if (!row) return { kind: "keep", why: "no_longer_a_candidate" };
+		if (isBusy(row.busy)) return { kind: "keep", why: "in_use_by_process" };
+		return { kind: "act", why: "rule_holds", evidence: { state: row.state } };
+	},
+	act: async (c, deps) => {
+		try { await deps.cleanup(String(c.details?.attachmentId)); }
+		catch (error) { return { ok: false, method: "trash", error: error instanceof Error ? error.message : String(error) }; }
+		return { ok: true, method: "trash" };
+	},
+};

package/src/housekeeping/collectors/db-backup.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { say, type Text } from "../../server-text.ts";
+import { BACKUP_KEEP_MS, DAY_MS, type GcCandidate, gcCollector, type GcDeps, type GcRoots, KEEP_BACKUPS } from "./shared.ts";
+
+/** `*.sqlite` file in the backups folder, not among the newest KEEP_BACKUPS and older than BACKUP_KEEP_MS. */
+
+const REASON_BACKUP: Text = { en: "Outside the newest {keep} and older than {days} days", ko: "최근 {keep}개 밖이고 {days}일 지남" };
+
+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 const dbBackup = gcCollector({ kind: "db-backup", npmOnly: false, root: (roots) => roots.backups, candidates: backupCandidates });

package/src/housekeeping/collectors/docker-build-cache.ts

@@ -0,0 +1,29 @@
+import type { Collector } from "../types.ts";
+import { type DockerDeps, dockerUsable, jsonLines, parseDockerSize } from "./docker-image.ts";
+
+/** Info only: the build cache is shared with other projects, so its size is shown and it is never acted on. */
+export const dockerBuildCache: Collector<DockerDeps> = {
+	name: "docker-build-cache",
+	role: "gc",
+	triggers: ["web_open", "doctor"],
+	confirmation: "operator",
+	reversibility: "irreversible",
+
+	async find(deps) {
+		if (!(await dockerUsable(deps))) return [];
+		const out = await deps.run(["system", "df", "--format", "{{json .}}"]);
+		if (!out || out.code !== 0) return [];
+		const row = jsonLines(out.stdout).find((r) => r.Type === "Build Cache");
+		if (!row) return [];
+		const bytes = typeof row.Size === "string" ? parseDockerSize(row.Size) : null;
+		return [{ id: "docker-build-cache", collector: "docker-build-cache", target: "docker build cache", reason: "shared_build_cache", ageMs: null, bytes }];
+	},
+
+	async judge() {
+		return { kind: "keep", why: "shared_with_other_projects" };
+	},
+
+	async act() {
+		return { ok: false, method: "docker_rmi", error: "info_only" };
+	},
+};

package/src/housekeeping/collectors/docker-image.ts

@@ -0,0 +1,135 @@
+import type { InstallKind } from "../../runtime/install-kind.ts";
+import type { Candidate, Collector, Verdict } from "../types.ts";
+
+/** Runs `docker <args>` as an argument array (no shell). `null` = no docker CLI on PATH. */
+export type DockerRun = (args: readonly string[]) => Promise<{ code: number; stdout: string; stderr: string } | null>;
+export interface DockerDeps { installKind: InstallKind; run: DockerRun; now: () => number }
+
+export const REPOSITORY = "zigmini-gateway";
+const PROTECTED_TAGS = new Set(["dev", "previous", "<none>"]);
+const TAG = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+const UNITS: Record<string, number> = { b: 1, kb: 1e3, mb: 1e6, gb: 1e9, tb: 1e12 };
+
+/** Bug 324: a hung Docker must not hold GET /api/housekeeping past the web server's idle timeout. */
+export const DOCKER_TIMEOUT_MS = 5_000;
+export const DOCKER_TIMEOUT_CODE = 124;
+
+/**
+ * Runs the docker CLI in its own process group. After `timeoutMs` the whole group gets SIGKILL (no orphan
+ * docker child stays behind) and the call answers exit code 124, which every caller reads as "docker unusable".
+ */
+export function dockerRunner(bin = "docker", timeoutMs = DOCKER_TIMEOUT_MS): DockerRun {
+	return async (args) => {
+		let proc;
+		try {
+			proc = Bun.spawn([bin, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true });
+		} catch {
+			return null;
+		}
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			try { process.kill(-proc.pid, "SIGKILL"); } catch {}
+		}, timeoutMs);
+		try {
+			const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+			return timedOut ? { code: DOCKER_TIMEOUT_CODE, stdout: "", stderr: "docker_timeout" } : { code, stdout, stderr };
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+
+export const systemDockerRun: DockerRun = dockerRunner();
+
+/** Docker's human sizes are decimal (`1.5GB` = 1.5e9 bytes). */
+export function parseDockerSize(text: string): number | null {
+	const m = /^([\d.]+)\s*([kMGT]?B)$/i.exec(text.trim());
+	const unit = m && UNITS[m[2]!.toLowerCase()];
+	return m && unit ? Math.round(Number(m[1]) * unit) : null;
+}
+
+export function jsonLines(stdout: string): Record<string, unknown>[] {
+	const out: Record<string, unknown>[] = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const value = JSON.parse(line);
+			if (value && typeof value === "object") out.push(value as Record<string, unknown>);
+		} catch {}
+	}
+	return out;
+}
+
+export async function dockerUsable(deps: DockerDeps): Promise<boolean> {
+	if (deps.installKind !== "npm") return false;
+	const info = await deps.run(["info"]);
+	return info !== null && info.code === 0;
+}
+
+interface Image { tag: string; id: string; bytes: number | null; createdAt: number | null }
+
+async function images(deps: DockerDeps): Promise<Image[] | null> {
+	const out = await deps.run(["images", REPOSITORY, "--format", "{{json .}}"]);
+	if (!out || out.code !== 0) return null;
+	return jsonLines(out.stdout)
+		.filter((i) => i.Repository === REPOSITORY && typeof i.Tag === "string" && typeof i.ID === "string")
+		.map((i) => ({ tag: i.Tag as string, id: i.ID as string, bytes: typeof i.Size === "string" ? parseDockerSize(i.Size) : null, createdAt: created(i.CreatedAt) }));
+}
+
+/** `2026-10-04 16:00:00 +0900 KST` -> epoch ms. */
+function created(value: unknown): number | null {
+	if (typeof value !== "string") return null;
+	const m = /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) ([+-]\d{2})(\d{2})/.exec(value);
+	if (!m) return null;
+	const at = Date.parse(`${m[1]}T${m[2]}${m[3]}:${m[4]}`);
+	return Number.isNaN(at) ? null : at;
+}
+
+export const dockerImage: Collector<DockerDeps> = {
+	name: "docker-image",
+	role: "gc",
+	triggers: ["web_open", "doctor"],
+	confirmation: "operator",
+	reversibility: "irreversible",
+
+	async find(deps) {
+		if (!(await dockerUsable(deps))) return [];
+		const list = await images(deps);
+		if (!list) return [];
+		return list
+			.filter((i) => !PROTECTED_TAGS.has(i.tag) && TAG.test(i.tag))
+			.map((i): Candidate => ({
+				id: `docker-image:${i.tag}`,
+				collector: "docker-image",
+				target: `${REPOSITORY}:${i.tag}`,
+				reason: "old_tag",
+				ageMs: i.createdAt === null ? null : Math.max(0, deps.now() - i.createdAt),
+				bytes: i.bytes,
+				details: { tag: i.tag, imageId: i.id },
+			}));
+	},
+
+	async judge(c, deps): Promise<Verdict> {
+		const tag = c.details?.tag;
+		const imageId = c.details?.imageId;
+		if (typeof tag !== "string" || typeof imageId !== "string" || !TAG.test(tag)) return { kind: "keep", why: "unreadable_candidate" };
+		if (PROTECTED_TAGS.has(tag)) return { kind: "keep", why: "protected_tag" };
+		if (!(await dockerUsable(deps))) return { kind: "keep", why: "docker_unavailable" };
+		const list = await images(deps);
+		if (!list) return { kind: "keep", why: "docker_images_failed" };
+		if (!list.some((i) => i.tag === tag && i.id === imageId)) return { kind: "keep", why: "image_changed" };
+		const ps = await deps.run(["ps", "-a", "--filter", `ancestor=${imageId}`, "-q"]);
+		if (!ps || ps.code !== 0) return { kind: "keep", why: "docker_ps_failed" };
+		if (ps.stdout.trim() !== "") return { kind: "keep", why: "in_use" };
+		return { kind: "act", why: "unused_old_tag", evidence: { tag, imageId, containers: 0 } };
+	},
+
+	async act(c, deps) {
+		const tag = c.details?.tag;
+		if (typeof tag !== "string" || !TAG.test(tag) || PROTECTED_TAGS.has(tag)) return { ok: false, method: "docker_rmi", error: "bad_tag" };
+		const out = await deps.run(["image", "rm", `${REPOSITORY}:${tag}`]);
+		if (!out) return { ok: false, method: "docker_rmi", error: "docker_missing" };
+		return out.code === 0 ? { ok: true, method: "docker_rmi" } : { ok: false, method: "docker_rmi", error: out.stderr.trim() || `exit_${out.code}` };
+	},
+};

package/src/housekeeping/collectors/omo-version.ts

@@ -0,0 +1,32 @@
+import { join, sep } from "node:path";
+import { say, type Text } from "../../server-text.ts";
+import { type GcCandidate, gcCollector, type GcDeps, type GcRoots, linkTarget } from "./shared.ts";
+
+/** Folder in omo/ that is not the target of omo/current, not the previous engine, and no process runs from it. */
+
+const REASON_OMO: Text = { en: "Not the current ({current}) or previous version, and no process is running from it", ko: "현재({current})·직전 버전이 아니고 실행 중인 프로세스 없음" };
+
+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 const omoVersion = gcCollector({ kind: "omo-version", npmOnly: true, root: (roots) => roots.omo, candidates: omoCandidates });

package/src/housekeeping/collectors/orphan-test-process.ts

@@ -0,0 +1,205 @@
+import { lstatSync, readlinkSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import type { InstallKind } from "../../runtime/install-kind.ts";
+import { say, type Text } from "../../server-text.ts";
+import type { ActResult, Candidate, Collector, Verdict } from "../types.ts";
+
+/**
+ * Orphaned test processes (bug 65 type: fake docker and other helpers a test left running after its temp root was removed).
+ * A candidate is a process of the current user, not pid 1, whose command line names a `$TMPDIR/zgw-*` or `$TMPDIR/zigmini-*`
+ * folder. It is acted on only when its parent is launchd (ppid 1), every named temp folder is gone (stat ENOENT), and it is
+ * not the gateway, bridge or OMO of this home. ps, stat or launchctl failure -> keep. npm installs only. SIGTERM only.
+ */
+
+export const NAME = "orphan-test-process";
+const REASON: Text = { en: "Test process with no parent whose temp folder is gone", ko: "부모가 없고 임시 폴더가 사라진 시험 프로세스" };
+export const LAUNCHD_LABELS = ["com.zigmini.gateway", "com.zigmini.bridge"] as const;
+
+type MaybeAsync<T> = T | Promise<T>;
+export interface OrphanProcess { readonly pid: number; readonly ppid: number; readonly user: string; readonly args: string }
+export interface OrphanDeps {
+	readonly kind: InstallKind;
+	readonly tmp: string;
+	readonly user: string;
+	/** Every process, or null when ps failed. */
+	readonly processes: () => MaybeAsync<readonly OrphanProcess[] | null>;
+	/** false only for ENOENT; null when stat failed otherwise. */
+	readonly exists: (path: string) => MaybeAsync<boolean | null>;
+	/** Gateway, bridge and OMO pids of this home (and this process), or null when they cannot be read. */
+	readonly protectedPids: () => MaybeAsync<readonly number[] | null>;
+	/** Sends SIGTERM; throws when the signal fails. */
+	readonly terminate: (pid: number) => void;
+}
+
+function escape(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Temp folders (`<tmp>/zgw-*`, `<tmp>/zigmini-*`, also through /private on macOS) named in a command line. */
+export function tempPaths(args: string, tmp: string): string[] {
+	const root = tmp.endsWith(sep) ? tmp : tmp + sep;
+	const roots = root.startsWith("/var/") || root.startsWith("/tmp/") ? [root, `/private${root}`] : [root];
+	const found = new Set<string>();
+	for (const prefix of roots) {
+		const pattern = new RegExp(`(?:^|[\\s='"])(${escape(prefix)}(?:zgw-|zigmini-)[^/\\s'"]+)`, "g");
+		for (const match of args.matchAll(pattern)) if (match[1] !== undefined) found.add(match[1]);
+	}
+	return [...found];
+}
+
+function pidOf(c: Candidate): number {
+	return Number(c.id.slice(NAME.length + 1));
+}
+
+function keep(why: string): Verdict {
+	return { kind: "keep", why };
+}
+
+export const orphanTestProcess: Collector<OrphanDeps> = {
+	name: NAME,
+	role: "gc",
+	triggers: ["start", "update_end", "web_open", "doctor"],
+	confirmation: "auto",
+	reversibility: "process_none",
+
+	async find(deps) {
+		if (deps.kind !== "npm") return [];
+		const processes = await deps.processes();
+		if (processes === null) return [];
+		const out: Candidate[] = [];
+		for (const p of processes) {
+			if (p.pid <= 1 || p.user !== deps.user) continue;
+			const paths = tempPaths(p.args, deps.tmp);
+			if (paths.length === 0) continue;
+			out.push({ id: `${NAME}:${p.pid}`, collector: NAME, target: `pid ${p.pid}: ${p.args.slice(0, 200)}`, reason: say(REASON), ageMs: null, bytes: null, details: { pid: p.pid, ppid: p.ppid, args: p.args, paths } });
+		}
+		return out;
+	},
+
+	async judge(c, deps) {
+		if (deps.kind !== "npm") return keep("not_npm_install");
+		const pid = pidOf(c);
+		const processes = await deps.processes();
+		if (processes === null) return keep("ps_unreadable");
+		const live = processes.find((p) => p.pid === pid);
+		if (live === undefined) return keep("gone");
+		if (live.args !== c.details?.args) return keep("pid_reused");
+		if (live.user !== deps.user) return keep("other_user");
+		if (live.ppid !== 1) return keep("has_parent");
+		const paths = tempPaths(live.args, deps.tmp);
+		if (paths.length === 0) return keep("no_temp_path");
+		const guarded = await deps.protectedPids();
+		if (guarded === null) return keep("protected_unreadable");
+		if (guarded.includes(pid)) return keep("protected");
+		for (const path of paths) {
+			const exists = await deps.exists(path);
+			if (exists === null) return keep("stat_failed");
+			if (exists) return keep("temp_path_exists");
+		}
+		return { kind: "act", why: "orphaned_test_process", evidence: { pid, ppid: live.ppid, user: live.user, args: live.args, missing: paths } };
+	},
+
+	async act(c, deps): Promise<ActResult> {
+		try {
+			deps.terminate(pidOf(c));
+			return { ok: true, method: "sigterm" };
+		} catch (error) {
+			return { ok: false, method: "sigterm", error: error instanceof Error ? error.message : String(error) };
+		}
+	},
+};
+
+/** `ps -o pid=,ppid=,user=,args=` output; any line that does not parse makes the whole list unreadable (null). */
+export function parseProcesses(text: string): OrphanProcess[] | null {
+	const out: OrphanProcess[] = [];
+	for (const line of text.split("\n")) {
+		if (line.trim() === "") continue;
+		const match = /^\s*(\d+)\s+(\d+)\s+(\S+)(?:\s+(.*))?$/.exec(line);
+		if (match === null) return null;
+		out.push({ pid: Number(match[1]), ppid: Number(match[2]), user: match[3] ?? "", args: match[4] ?? "" });
+	}
+	return out;
+}
+
+/** The `"PID" = N;` entry of `launchctl list <label>`; null when the job is not running. */
+export function parseLaunchctlPid(text: string): number | null {
+	const match = /"PID"\s*=\s*(\d+);/.exec(text);
+	return match === null ? null : Number(match[1]);
+}
+
+export type Run = (argv: readonly string[]) => Promise<{ code: number; out: string }>;
+
+async function spawnRun(argv: readonly string[]): Promise<{ code: number; out: string }> {
+	const child = Bun.spawn([...argv], { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+	const out = await new Response(child.stdout).text();
+	return { code: await child.exited, out };
+}
+
+function systemReadlink(path: string): string | null {
+	try {
+		return readlinkSync(path);
+	} catch {
+		return null;
+	}
+}
+
+/** Real process access: ps and launchctl as argument arrays (no shell), lstat for temp folders, SIGTERM only. */
+export function systemOrphanDeps(options: {
+	home: string;
+	kind: InstallKind;
+	tmp?: string;
+	user?: string;
+	run?: Run;
+	readlink?: (path: string) => string | null;
+	selfPid?: number;
+}): OrphanDeps {
+	const run = options.run ?? spawnRun;
+	const readlink = options.readlink ?? systemReadlink;
+	const omo = join(options.home, "omo");
+	const processes = async (): Promise<OrphanProcess[] | null> => {
+		try {
+			const ps = await run(["ps", "-axww", "-o", "pid=,ppid=,user=,args="]);
+			return ps.code === 0 ? parseProcesses(ps.out) : null;
+		} catch {
+			return null;
+		}
+	};
+	return {
+		kind: options.kind,
+		tmp: options.tmp ?? process.env.TMPDIR ?? tmpdir(),
+		user: options.user ?? userInfo().username,
+		processes,
+		exists: (path) => {
+			try {
+				lstatSync(path);
+				return true;
+			} catch (error) {
+				return (error as NodeJS.ErrnoException).code === "ENOENT" ? false : null;
+			}
+		},
+		protectedPids: async () => {
+			const pids = [options.selfPid ?? process.pid];
+			try {
+				for (const label of LAUNCHD_LABELS) {
+					// launchctl exits non-zero when the job is not loaded: then it has no pid to protect.
+					const listed = await run(["launchctl", "list", label]);
+					const pid = listed.code === 0 ? parseLaunchctlPid(listed.out) : null;
+					if (pid !== null) pids.push(pid);
+				}
+			} catch {
+				return null;
+			}
+			const all = await processes();
+			if (all === null) return null;
+			const markers = [`${join(omo, "current")}${sep}`];
+			const target = readlink(join(omo, "current"));
+			if (target !== null) markers.push(`${isAbsolute(target) ? target : resolve(omo, target)}${sep}`);
+			for (const p of all) if (markers.some((marker) => p.args.includes(marker))) pids.push(p.pid);
+			return pids;
+		},
+		terminate: (pid) => {
+			process.kill(pid, "SIGTERM");
+		},
+	};
+}

package/src/housekeeping/collectors/reconcile-work.ts

@@ -0,0 +1,55 @@
+import type { WorkStatus } from "../../store.ts";
+import type { ReconcileConfirmReason, ReconcileReason } from "../reconcile/work.ts";
+import type { Candidate, Collector } from "../types.ts";
+
+/**
+ * One reconcile verdict the WorkRouter currently holds (src/work.ts): a work it closed from evidence, or an unfinished work
+ * whose confirm alert waits for main. Kept in the router's memory only; the work rows and alerts are the durable record.
+ */
+export interface ReconcileItem {
+	readonly workId: string;
+	readonly title: string;
+	readonly kind: "close" | "confirm";
+	readonly reason: ReconcileReason | ReconcileConfirmReason;
+	readonly status: WorkStatus;
+	readonly commandId: string;
+	readonly commandSeq: number;
+	readonly evidence: Record<string, unknown>;
+	readonly at: string;
+}
+
+export interface ReconcileWorkDeps {
+	/** Read through the WorkRouter (in-process); never the database from another process. */
+	items(): readonly ReconcileItem[];
+}
+
+export function reconcileWorkId(item: Pick<ReconcileItem, "reason" | "commandId">): string {
+	return `reconcile:${item.reason}:${item.commandId}`;
+}
+
+/**
+ * Role A (상태 정리) in the housekeeping list. The engine never writes work rows: closure and alerts happen in the
+ * WorkRouter, and a confirm is answered by main (cancel or a new instruct). An operator pick therefore returns
+ * `confirm_through_main` from the engine (confirmation operator_via_main) and `act` changes nothing.
+ */
+export const reconcileWork: Collector<ReconcileWorkDeps> = {
+	name: "reconcile-work",
+	role: "reconcile",
+	triggers: ["work_event", "start", "web_open"],
+	confirmation: "operator_via_main",
+	reversibility: "state_reopen",
+	async find(deps) {
+		return deps.items().map((item): Candidate => ({
+			id: reconcileWorkId(item), collector: "reconcile-work", target: item.workId, reason: item.reason, ageMs: null, bytes: null,
+			details: { kind: item.kind, workId: item.workId, title: item.title, status: item.status, commandSeq: item.commandSeq, at: item.at },
+		}));
+	},
+	async judge(candidate, deps) {
+		const item = deps.items().find((i) => reconcileWorkId(i) === candidate.id);
+		if (!item) return { kind: "keep", why: "no_longer_current" };
+		return { kind: "act", why: item.reason, evidence: item.evidence };
+	},
+	async act() {
+		return { ok: false, method: "state", error: "confirm_through_main" };
+	},
+};

package/src/housekeeping/collectors/rpc-daemon.ts

@@ -0,0 +1,39 @@
+import { say, type Text } from "../../server-text.ts";
+import { type GcCandidate, gcCollector, type GcDeps, type RpcUnit } from "./shared.ts";
+
+/**
+ * Old-version RPC host daemon that `rpc-host-gc.ts list --json` judges "stop" (rule of bug 62). The collector is auto:
+ * engine.scan sends SIGTERM (never SIGKILL) as soon as the rule holds; the old src/gc.ts report() never signals.
+ */
+
+const REASON_DAEMON: Text = { en: "RPC host daemon of an earlier version, no parent, no connected client", ko: "이전 버전 RPC 호스트 데몬, 부모 없음, 연결된 클라이언트 없음" };
+
+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,
+	}));
+}
+
+/** `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;
+}
+
+export const rpcDaemon = gcCollector({ kind: "rpc-daemon", npmOnly: true, root: null, candidates: (_roots, deps) => daemonCandidates(deps) });