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

package/src/housekeeping/collectors/shared.ts

@@ -0,0 +1,149 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { InstallKind } from "../../runtime/install-kind.ts";
+import type { TrashResult } from "../trash.ts";
+import type { ActResult, Candidate, Collector, Trigger, Verdict } from "../types.ts";
+
+/**
+ * Shared types, retention values and root checks of the six resource kinds of improvement 66 (src/gc.ts re-exports
+ * them). `gcCollector` turns one kind's rule into a housekeeping collector: `find` lists what the rule finds now, kept
+ * inside the kind's root and off protected folders; `judge` runs the rule again and acts only on a candidate it still
+ * finds; `act` moves a path to the Trash through `deps.remove` or sends SIGTERM to a daemon's pids.
+ */
+
+export const GC_KINDS = ["db-backup", "omo-version", "update-file", "temp-dir", "rpc-daemon", "agent-trash", "agent-file-trash", "agent-drafts"] 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;
+
+/** 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;
+}
+
+export 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>;
+	/** Moves `path` away (throws on failure); the trash result, when returned, names the method used. */
+	readonly remove: (path: string, kind: GcKind) => MaybeAsync<TrashResult | void>;
+	readonly terminate: (pid: number) => void;
+}
+
+export interface GcContext { readonly roots: GcRoots; readonly deps: GcDeps }
+
+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 async function sized(found: readonly GcCandidate[], deps: GcDeps): Promise<GcCandidate[]> {
+	const out: GcCandidate[] = [];
+	for (const candidate of found) out.push(candidate.bytes === null ? { ...candidate, bytes: await deps.size(candidate.target) } : candidate);
+	return out;
+}
+
+export function toCandidate(c: GcCandidate): Candidate {
+	const out: Candidate = { id: c.id, collector: c.kind, target: c.target, reason: c.reason, ageMs: c.ageMs, bytes: c.bytes };
+	if (c.pids !== undefined) out.details = { pids: [...c.pids] };
+	return out;
+}
+
+export interface GcRule {
+	readonly kind: GcKind;
+	/** A checkout (this Mac's Docker gateway) cannot see host processes and folders, so only db-backup runs there. */
+	readonly npmOnly: boolean;
+	/** The folder every candidate path must stay inside; null for daemons, which are processes, not paths. */
+	readonly root: ((roots: GcRoots) => string) | null;
+	readonly candidates: (roots: GcRoots, deps: GcDeps) => MaybeAsync<GcCandidate[]>;
+}
+
+export interface GcCollector extends Collector<GcContext> {
+	/** Read only: the rule's candidates now, unsized, each path kept inside its root. */
+	listed(ctx: GcContext): Promise<GcCandidate[]>;
+}
+
+const TRIGGERS: readonly Trigger[] = ["start", "update_end", "web_open", "doctor"];
+
+export function gcCollector(rule: GcRule): GcCollector {
+	const daemon = rule.root === null;
+	const listed = async ({ roots, deps }: GcContext): Promise<GcCandidate[]> => {
+		if (rule.npmOnly && roots.kind !== "npm") return [];
+		const found = await rule.candidates(roots, deps);
+		const root = rule.root;
+		return root === null ? found : found.filter((c) => guarded(root(roots), c.target));
+	};
+	return {
+		name: rule.kind,
+		role: "gc",
+		triggers: TRIGGERS,
+		confirmation: daemon ? "auto" : "operator",
+		reversibility: daemon ? "process_none" : "trash",
+		listed,
+		async find(ctx) {
+			return (await sized(await listed(ctx), ctx.deps)).map(toCandidate);
+		},
+		async judge(c, ctx): Promise<Verdict> {
+			const now = (await listed(ctx)).find((found) => found.id === c.id);
+			if (now === undefined) return { kind: "keep", why: "no_longer_a_candidate" };
+			const evidence: Record<string, unknown> = { rule: rule.kind, reason: now.reason, ageMs: now.ageMs };
+			if (now.pids !== undefined) evidence.pids = [...now.pids];
+			return { kind: "act", why: "rule_holds", evidence };
+		},
+		async act(c, { deps }): Promise<ActResult> {
+			if (daemon) {
+				const pids = c.details?.pids;
+				if (!Array.isArray(pids) || pids.length === 0) return { ok: false, method: "sigterm", error: "no_pids" };
+				for (const pid of pids as number[]) deps.terminate(pid);
+				return { ok: true, method: "sigterm" };
+			}
+			return (await deps.remove(c.target, rule.kind)) ?? { ok: true, method: "trash" };
+		},
+	};
+}

package/src/housekeeping/collectors/temp-dir.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { say, type Text } from "../../server-text.ts";
+import { DAY_MS, type GcCandidate, gcCollector, type GcDeps, type GcRoots, TEMP_MIN_AGE_MS } from "./shared.ts";
+
+/** `zgw-*` or `zigmini-*` folder in $TMPDIR, older than TEMP_MIN_AGE_MS, named by no process, opened by none. */
+
+const REASON_TEMP: Text = { en: "Older than {days} days and no process uses it", ko: "{days}일 지났고 쓰는 프로세스 없음" };
+const TEMP_NAME = /^(?:zgw-|zigmini-)/;
+
+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 const tempDir = gcCollector({ kind: "temp-dir", npmOnly: true, root: (roots) => roots.tmp, candidates: tempCandidates });

package/src/housekeeping/collectors/update-file.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { say, type Text } from "../../server-text.ts";
+import { DAY_MS, type GcCandidate, gcCollector, type GcDeps, type GcRoots, UPDATE_MIN_AGE_MS } from "./shared.ts";
+
+/** `*.log` or `request*.json` file in <home>/update/, older than UPDATE_MIN_AGE_MS. */
+
+const REASON_UPDATE: Text = { en: "Update log or request file older than {days} days", ko: "{days}일 지난 업데이트 로그·요청 파일" };
+const UPDATE_NAME = /^(?:.+\.log|request.*\.json)$/;
+
+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 const updateFile = gcCollector({ kind: "update-file", npmOnly: true, root: (roots) => roots.update, candidates: updateCandidates });

package/src/housekeeping/collectors/worktree.ts

@@ -0,0 +1,193 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { say, type Text } from "../../server-text.ts";
+import { moveToTrash, type Trash } from "../trash.ts";
+import type { ActResult, Candidate, Collector, Verdict } from "../types.ts";
+
+/**
+ * Worktree collector (plan housekeeping todo 6, improvement 66 row "worktree"). Repos are the distinct cwd values of works
+ * in the store. A linked worktree is offered when its branch (or detached commit) is merged into `dev`, it has no
+ * uncommitted or untracked change, no ignored file under `.omo/evidence` or `secrets`, no process uses it, no unfinished
+ * work runs inside it, and its folder is older than 7 days. Act moves the folder to the Trash and runs
+ * `git worktree prune`; it never runs `git worktree remove` and never deletes a branch. Any git failure keeps.
+ */
+
+export const WORKTREE_MIN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MERGE_TARGET = "dev";
+const REASON: Text = { en: "Merged into dev, no changes, unused, older than {days} days", ko: "dev에 병합됨, 변경 없음, 쓰는 곳 없음, {days}일 지남" };
+
+export interface GitRun { readonly code: number; readonly stdout: string }
+export interface WorktreeDeps {
+	readonly now: () => number;
+	/** Distinct cwd values of works in the store, read in-process. */
+	readonly workRepos: () => readonly string[];
+	readonly unfinishedWorkCwds: () => readonly string[];
+	readonly git: (args: readonly string[]) => Promise<GitRun>;
+	readonly mtimeMs: (path: string) => number | null;
+	/** Whether a process has its cwd, an open file or an argument inside `path`; null when lsof or ps failed. */
+	readonly usedByProcess: (path: string) => Promise<boolean | null>;
+	readonly trash: Trash;
+}
+
+interface Entry { readonly path: string; readonly head: string | null; readonly branch: string | null; readonly bare: boolean; readonly locked: boolean; readonly prunable: boolean }
+
+function real(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}
+
+function within(root: string, path: string): boolean {
+	const rel = relative(root, path);
+	return rel === "" || (rel.split(sep)[0] !== ".." && !isAbsolute(rel));
+}
+
+function parse(porcelain: string): Entry[] {
+	return porcelain
+		.split("\n\n")
+		.map((block) => block.split("\n").filter((line) => line !== ""))
+		.filter((lines) => lines[0]?.startsWith("worktree ") === true)
+		.map((lines) => {
+			const value = (key: string) => lines.find((line) => line === key || line.startsWith(`${key} `))?.slice(key.length + 1) ?? null;
+			const has = (key: string) => lines.some((line) => line === key || line.startsWith(`${key} `));
+			return { path: lines[0]!.slice("worktree ".length), head: value("HEAD"), branch: value("branch"), bare: has("bare"), locked: has("locked"), prunable: has("prunable") };
+		});
+}
+
+/** The main worktree path and the linked worktrees of the repo that contains `cwd`, or null when git fails. */
+async function worktrees(cwd: string, deps: WorktreeDeps): Promise<{ main: string; linked: Entry[] } | null> {
+	const run = await deps.git(["-C", cwd, "worktree", "list", "--porcelain"]);
+	if (run.code !== 0) return null;
+	const [main, ...linked] = parse(run.stdout);
+	if (main === undefined) return null;
+	return { main: main.path, linked: linked.filter((entry) => !entry.bare && !entry.prunable) };
+}
+
+function keep(why: string): Verdict {
+	return { kind: "keep", why };
+}
+
+async function judge(c: Candidate, deps: WorktreeDeps): Promise<Verdict> {
+	const repo = c.details?.repo;
+	if (typeof repo !== "string") return keep("git_failed");
+	const list = await worktrees(repo, deps);
+	if (list === null) return keep("git_failed");
+	const entry = list.linked.find((e) => e.path === c.target);
+	if (entry === undefined) return keep("not_a_worktree");
+	if (entry.locked) return keep("locked");
+	const mtime = deps.mtimeMs(entry.path);
+	if (mtime === null) return keep("stat_failed");
+	const ageMs = deps.now() - mtime;
+	if (ageMs <= WORKTREE_MIN_AGE_MS) return keep("younger_than_7_days");
+	const wt = real(entry.path);
+	if (deps.unfinishedWorkCwds().some((cwd) => within(wt, real(cwd)))) return keep("unfinished_work_inside");
+	const rev = entry.branch ?? entry.head;
+	if (rev === null) return keep("git_failed");
+	const merged = await deps.git(["-C", repo, "merge-base", "--is-ancestor", rev, MERGE_TARGET]);
+	if (merged.code === 1) return keep("not_merged_into_dev");
+	if (merged.code !== 0) return keep("git_failed");
+	const status = await deps.git(["-C", entry.path, "status", "--porcelain", "--untracked-files=all"]);
+	if (status.code !== 0) return keep("git_failed");
+	if (status.stdout.trim() !== "") return keep("uncommitted_changes");
+	const kept = await deps.git(["-C", entry.path, "status", "--porcelain", "--ignored", "--untracked-files=all", "--", ".omo/evidence", "secrets"]);
+	if (kept.code !== 0) return keep("git_failed");
+	if (kept.stdout.trim() !== "") return keep("evidence_or_secrets_present");
+	const used = await deps.usedByProcess(entry.path);
+	if (used === null) return keep("process_check_failed");
+	if (used) return keep("in_use_by_process");
+	return { kind: "act", why: "merged_clean_unused_old", evidence: { repo, branch: entry.branch, head: entry.head, mergedInto: MERGE_TARGET, ageMs } };
+}
+
+export const worktree: Collector<WorktreeDeps> = {
+	name: "worktree",
+	role: "gc",
+	triggers: ["web_open", "doctor"],
+	confirmation: "operator",
+	reversibility: "trash",
+
+	async find(deps) {
+		const seen = new Set<string>();
+		const out: Candidate[] = [];
+		for (const cwd of deps.workRepos()) {
+			const list = await worktrees(cwd, deps);
+			if (list === null || seen.has(list.main)) continue;
+			seen.add(list.main);
+			for (const entry of list.linked) {
+				const mtime = deps.mtimeMs(entry.path);
+				out.push({
+					id: `worktree:${entry.path}`,
+					collector: "worktree",
+					target: entry.path,
+					reason: say(REASON, { days: WORKTREE_MIN_AGE_MS / (24 * 60 * 60 * 1000) }),
+					ageMs: mtime === null ? null : deps.now() - mtime,
+					bytes: null,
+					details: { repo: list.main, branch: entry.branch, head: entry.head },
+				});
+			}
+		}
+		return out;
+	},
+
+	judge,
+
+	async act(c, deps): Promise<ActResult> {
+		const verdict = await judge(c, deps);
+		if (verdict.kind !== "act") return { ok: false, method: "trash", error: `kept:${verdict.why}` };
+		const moved = await deps.trash(c.target, "worktree");
+		if (!moved.ok) return { ok: false, method: "trash", error: moved.error ?? "trash_failed" };
+		const prune = await deps.git(["-C", String(c.details?.repo), "worktree", "prune"]);
+		if (prune.code !== 0) return { ok: false, method: "git_prune", error: "git_prune_failed" };
+		return { ok: true, method: "trash" };
+	},
+};
+
+async function output(argv: readonly string[], env?: Record<string, string | undefined>): Promise<{ code: number; out: string }> {
+	try {
+		const child = Bun.spawn([...argv], { env, stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+		const [out, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+		return { code, out };
+	} catch {
+		return { code: -1, out: "" };
+	}
+}
+
+function namedIn(line: string, path: string): boolean {
+	for (let at = line.indexOf(path); at !== -1; at = line.indexOf(path, at + 1)) {
+		const next = line[at + path.length];
+		if (next === undefined || next === sep || /\s/.test(next)) return true;
+	}
+	return false;
+}
+
+export function systemWorktreeDeps(options: { workRepos: () => readonly string[]; unfinishedWorkCwds: () => readonly string[]; trash?: Trash }): WorktreeDeps {
+	// GIT_OPTIONAL_LOCKS=0 keeps `git status` from refreshing the index, so find and judge stay read only.
+	const gitEnv = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+	return {
+		now: Date.now,
+		workRepos: options.workRepos,
+		unfinishedWorkCwds: options.unfinishedWorkCwds,
+		git: async (args) => {
+			const run = await output(["git", ...args], gitEnv);
+			return { code: run.code, stdout: run.out };
+		},
+		mtimeMs: (path) => {
+			try {
+				return statSync(path).mtimeMs;
+			} catch {
+				return null;
+			}
+		},
+		usedByProcess: async (path) => {
+			// lsof exits 1 with no output when nothing (cwd or open file) is under the folder.
+			const lsof = await output(["lsof", "-t", "+D", path]);
+			if (lsof.out.trim() !== "") return true;
+			if (lsof.code !== 1) return null;
+			const ps = await output(["ps", "-axww", "-o", "command="]);
+			if (ps.code !== 0) return null;
+			return ps.out.split("\n").some((line) => namedIn(line, path));
+		},
+		trash: options.trash ?? moveToTrash,
+	};
+}

package/src/housekeeping/engine.ts

@@ -0,0 +1,125 @@
+import type { AuditActor, AuditLine, AuditSink } from "./audit.ts";
+import type { ActResult, BoundCollector, Candidate, Confirmation, Reversibility, Role, Trigger, Verdict } from "./types.ts";
+
+/** An act that threw has no method. */
+export type ActOutcome = ActResult | { ok: false; method: null; error: string };
+export interface ScanItem { candidate: Candidate; verdict: Verdict; result?: ActOutcome }
+export interface CollectorReport {
+	name: string;
+	role: Role;
+	confirmation: Confirmation;
+	reversibility: Reversibility;
+	scannedAt: string | null;
+	trigger: Trigger | null;
+	items: ScanItem[];
+	error: string | null;
+}
+export interface Selection { ids?: readonly string[]; collectors?: readonly string[] }
+export interface CleanResult {
+	cleaned: Candidate[];
+	failed: { id: string; error: string }[];
+	kept: { id: string; why: string }[];
+	missing: string[];
+}
+export interface Housekeeping {
+	scan(trigger: Trigger): Promise<CollectorReport[]>;
+	clean(selection: Selection, actor: Exclude<AuditActor, "auto">): Promise<CleanResult>;
+	report(): CollectorReport[];
+}
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function createHousekeeping(options: { collectors: readonly BoundCollector[]; audit: AuditSink; now: () => number }): Housekeeping {
+	const { collectors, audit, now } = options;
+	const seen = new Set<string>();
+	for (const c of collectors) {
+		if (seen.has(c.name)) throw new Error(`duplicate_collector:${c.name}`);
+		seen.add(c.name);
+	}
+	const latest = new Map<string, CollectorReport>();
+	const at = () => new Date(now()).toISOString();
+
+	const empty = (c: BoundCollector): CollectorReport => ({ name: c.name, role: c.role, confirmation: c.confirmation, reversibility: c.reversibility, scannedAt: null, trigger: null, items: [], error: null });
+
+	/** find + judge; a throw yields no items and one audit error line. */
+	async function survey(c: BoundCollector, trigger: Trigger | null, actor: AuditActor): Promise<{ items: ScanItem[]; error: string | null }> {
+		try {
+			const items: ScanItem[] = [];
+			for (const candidate of await c.find()) items.push({ candidate, verdict: await c.judge(candidate) });
+			return { items, error: null };
+		} catch (error) {
+			const text = message(error);
+			audit.append({ at: at(), trigger, actor, collector: c.name, id: null, target: null, verdict: "error", evidence: null, method: null, ok: false, error: text });
+			return { items: [], error: text };
+		}
+	}
+
+	/** Acts on an `act` verdict and writes exactly one audit line, whatever the outcome. */
+	async function perform(c: BoundCollector, item: ScanItem & { verdict: { kind: "act" } }, trigger: Trigger | null, actor: AuditActor): Promise<ActOutcome> {
+		let result: ActOutcome;
+		try {
+			result = await c.act(item.candidate);
+		} catch (error) {
+			result = { ok: false, method: null, error: message(error) };
+		}
+		const line: AuditLine = { at: at(), trigger, actor, collector: c.name, id: item.candidate.id, target: item.candidate.target, verdict: "act", evidence: item.verdict.evidence, method: result.method, ok: result.ok };
+		if (result.error !== undefined) line.error = result.error;
+		audit.append(line);
+		return result;
+	}
+
+	return {
+		async scan(trigger) {
+			const out: CollectorReport[] = [];
+			for (const c of collectors) {
+				if (!c.triggers.includes(trigger)) continue;
+				const { items, error } = await survey(c, trigger, "auto");
+				if (c.confirmation === "auto") {
+					for (const item of items) {
+						if (item.verdict.kind !== "act") continue;
+						item.result = await perform(c, item as ScanItem & { verdict: { kind: "act" } }, trigger, "auto");
+					}
+				}
+				const entry: CollectorReport = { ...empty(c), scannedAt: at(), trigger, items, error };
+				latest.set(c.name, entry);
+				out.push(entry);
+			}
+			return out;
+		},
+
+		async clean(selection, actor) {
+			const ids = selection.ids ?? [];
+			const names = selection.collectors ?? [];
+			const result: CleanResult = { cleaned: [], failed: [], kept: [], missing: [] };
+			const found = new Set<string>();
+			for (const c of collectors) {
+				const { items } = await survey(c, null, actor);
+				for (const item of items) {
+					if (!ids.includes(item.candidate.id) && !names.includes(c.name)) continue;
+					found.add(item.candidate.id);
+					if (item.verdict.kind !== "act") {
+						result.kept.push({ id: item.candidate.id, why: item.verdict.why });
+						continue;
+					}
+					if (c.confirmation === "operator_via_main" && actor === "operator") {
+						const error = "confirm_through_main";
+						audit.append({ at: at(), trigger: null, actor, collector: c.name, id: item.candidate.id, target: item.candidate.target, verdict: "act", evidence: item.verdict.evidence, method: null, ok: false, error });
+						result.failed.push({ id: item.candidate.id, error });
+						continue;
+					}
+					const done = await perform(c, item as ScanItem & { verdict: { kind: "act" } }, null, actor);
+					if (done.ok) result.cleaned.push(item.candidate);
+					else result.failed.push({ id: item.candidate.id, error: done.error ?? "act_failed" });
+				}
+			}
+			result.missing = ids.filter((id) => !found.has(id));
+			return result;
+		},
+
+		report() {
+			return collectors.map((c) => latest.get(c.name) ?? empty(c));
+		},
+	};
+}

package/src/housekeeping/reconcile/work.ts

@@ -0,0 +1,130 @@
+import type { WorkCommand, WorkStatus } from "../../store.ts";
+
+/**
+ * Evidence-only reconcile classifier for unfinished works (bug 282, .omo/plans/submitted-work-gc.md "State transition
+ * table", renamed by .omo/plans/housekeeping.md "Names"). Pure: no clock, no store, no OMO client. Timestamps are
+ * compared only with each other, never with the current time, so no age can ever decide a closure.
+ */
+
+export type ReconcileReason = "reconcile_cancel_unreachable" | "reconcile_session_closed";
+export type ReconcileConfirmReason = "reconcile_confirm_undelivered" | "reconcile_confirm_no_report" | "reconcile_confirm_unreachable";
+
+export type ReconcileSession =
+	| { readonly kind: "readable"; readonly isStreaming: boolean; readonly stateReadAt: string }
+	| { readonly kind: "refused"; readonly retryable: boolean; readonly error: string }
+	| { readonly kind: "unread" };
+
+export interface ReconcileCommand extends Pick<WorkCommand, "id" | "seq" | "kind" | "delivery" | "error" | "createdAt" | "acceptedAt"> {
+	/** The admission of this command failed in the current OMO generation. */
+	readonly admissionFailed: boolean;
+	/** Found in the session queue or user entries; null when the session was not read. */
+	readonly inSession: boolean | null;
+	/** The work reported on this command's seq. */
+	readonly reported: boolean;
+}
+
+export interface ReconcileEvidence {
+	readonly status: WorkStatus;
+	readonly latest: ReconcileCommand | null;
+	/** The earlier `unknown` command a pending latest command waits behind (src/work.ts transmit), if any. */
+	readonly blockedBy: (Pick<WorkCommand, "id" | "seq" | "delivery"> & { readonly inSession: boolean | null }) | null;
+	readonly omoReady: boolean;
+	/** True only when this generation's dispatch for the work has settled. */
+	readonly evaluatedAfterDispatch: boolean;
+	readonly session: ReconcileSession;
+	/** A session_closed binding event of this generation (synthetic generation closes are never passed in). */
+	readonly lifecycle: { readonly kind: "closed"; readonly reason: string; readonly at: string } | null;
+	/** Active child tasks; null when unknown (e.g. right after a restart). */
+	readonly children: number | null;
+	readonly openDecisions: number;
+	readonly inFlight: boolean;
+}
+
+export type ReconcileVerdict =
+	| { readonly kind: "keep"; readonly why: string }
+	| { readonly kind: "close"; readonly status: "failed" | "cancelled"; readonly reason: ReconcileReason; readonly evidence: Record<string, unknown> }
+	| { readonly kind: "confirm"; readonly reason: ReconcileConfirmReason; readonly evidence: Record<string, unknown> };
+
+const RETRYABLE_CODES: ReadonlySet<string> = new Set(["host_memory_pressure", "session_closing"]);
+const NOT_LOSS: ReadonlySet<string> = new Set(["handoff_parked", "generation_ended"]);
+const SETTLED: ReadonlySet<WorkStatus> = new Set(["completed", "failed", "cancelled", "waiting_input"]);
+
+/** A refusal the existing retry paths own: it carries retry_after_ms or a known transient code. */
+export function retryableRefusal(code: string | null, retryAfterMs: number | null): boolean {
+	return retryAfterMs !== null || (code !== null && RETRYABLE_CODES.has(code));
+}
+
+const at = (iso: string) => Date.parse(iso);
+
+export function classify(e: ReconcileEvidence): ReconcileVerdict {
+	const latest = e.latest;
+	const closedAt = closeEvent(e, latest);
+	const state = e.session.kind === "readable" && (closedAt === null || at(e.session.stateReadAt) >= closedAt) ? e.session : null;
+
+	if (!e.omoReady) return keep("omo_not_ready");
+	if (!e.evaluatedAfterDispatch) return keep("dispatch_not_settled");
+	if (state?.isStreaming === true) return keep("streaming");
+	if (e.children !== null && e.children > 0) return keep("children_active");
+	if (e.openDecisions > 0) return keep("open_decisions");
+	if (e.inFlight) return keep("dispatch_in_flight");
+	if (SETTLED.has(e.status)) return keep("status_settled");
+	if (e.session.kind === "refused" && e.session.retryable) return keep("retryable_refusal");
+	if (latest === null) return keep("no_command");
+
+	const row = pick(e, latest, closedAt, state);
+	if (row === null) return keep("no_row");
+	if (e.children === null && row.name !== "A1" && row.name !== "A4") return keep("children_unknown");
+
+	const evidence: Record<string, unknown> = {
+		row: row.name,
+		commandId: latest.id,
+		commandSeq: latest.seq,
+		kind: latest.kind,
+		delivery: latest.delivery,
+		error: latest.error,
+		session: e.session,
+		lifecycle: e.lifecycle,
+		...(row.name === "A4" ? { blockedBy: e.blockedBy } : {}),
+	};
+	return row.verdict === "close"
+		? { kind: "close", status: row.status, reason: row.reason, evidence }
+		: { kind: "confirm", reason: row.reason, evidence };
+}
+
+type Row =
+	| { readonly name: "D1" | "D2"; readonly verdict: "close"; readonly status: "failed" | "cancelled"; readonly reason: ReconcileReason }
+	| { readonly name: "A1" | "A2" | "A3" | "A4"; readonly verdict: "confirm"; readonly reason: ReconcileConfirmReason };
+
+function pick(e: ReconcileEvidence, latest: ReconcileCommand, closedAt: number | null, state: Extract<ReconcileSession, { kind: "readable" }> | null): Row | null {
+	const closed = closedAt !== null;
+	const refusedHard = e.session.kind === "refused" && !e.session.retryable;
+	const idle = state !== null && !state.isStreaming && at(state.stateReadAt) > at(latest.acceptedAt ?? latest.createdAt);
+	const readAfterCreated = state !== null && at(state.stateReadAt) >= at(latest.createdAt);
+	const absent = (inSession: boolean | null) => inSession === false && readAfterCreated;
+
+	if (latest.kind === "cancel" && latest.delivery !== "accepted" && (idle || refusedHard || closed))
+		return { name: "D1", verdict: "close", status: "cancelled", reason: "reconcile_cancel_unreachable" };
+	if (closed && !latest.reported)
+		return latest.kind === "cancel"
+			? { name: "D2", verdict: "close", status: "cancelled", reason: "reconcile_cancel_unreachable" }
+			: { name: "D2", verdict: "close", status: "failed", reason: "reconcile_session_closed" };
+	if (refusedHard || latest.delivery === "rejected") return { name: "A3", verdict: "confirm", reason: "reconcile_confirm_unreachable" };
+	if (((latest.delivery === "pending" && latest.admissionFailed) || latest.delivery === "unknown") && absent(latest.inSession))
+		return { name: "A1", verdict: "confirm", reason: "reconcile_confirm_undelivered" };
+	if (latest.delivery === "pending" && latest.error === null && e.blockedBy?.delivery === "unknown" && absent(e.blockedBy.inSession))
+		return { name: "A4", verdict: "confirm", reason: "reconcile_confirm_undelivered" };
+	if (latest.delivery === "accepted" && latest.kind !== "cancel" && idle && !latest.reported)
+		return { name: "A2", verdict: "confirm", reason: "reconcile_confirm_no_report" };
+	return null;
+}
+
+/** The close event counts only when it is real loss and was observed after the latest command was created. */
+function closeEvent(e: ReconcileEvidence, latest: ReconcileCommand | null): number | null {
+	if (e.lifecycle === null || latest === null || NOT_LOSS.has(e.lifecycle.reason)) return null;
+	const closedAt = at(e.lifecycle.at);
+	return closedAt > at(latest.createdAt) ? closedAt : null;
+}
+
+function keep(why: string): ReconcileVerdict {
+	return { kind: "keep", why };
+}