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

package/web/decisions.js

@@ -343,6 +343,7 @@ export function sourceContext(payload) {
 
 export function presentation(decision) {
 	if (decision.security) return { kind: "security", mode: null, form: false, recheck: false, terminal: false };
+	if (isArtifactReview(decision)) return { kind: "artifact-review", mode: null, form: false, recheck: false, terminal: false };
 	const actions = decision.allowedActions ?? [];
 	const terminal = TERMINAL_WORK.has(decision.work?.status ?? "");
 	let kind = "terminal";
@@ -366,7 +367,7 @@ export function dismissMode(decision) {
 }
 
 export function canDismiss(decision) {
-	if (decision.security) return false;
+	if (decision.security || isArtifactReview(decision)) return false;
 	return isUnresolved(decision) && decision.status !== "submitted";
 }
 
@@ -397,6 +398,7 @@ export function questionTitle(q) {
  * Empty for free-text methods, whose question is the title and detail.
  */
 export function originalChoices(decision) {
+	if (isToolGrant(decision)) return [];
 	const payload = record(decision.payload) ? decision.payload : {};
 	const options = (list) => (Array.isArray(list) ? list : []).map((o) => (record(o)
 		? { label: typeof o.label === "string" ? o.label : "", description: typeof o.description === "string" ? o.description : "" }
@@ -418,6 +420,8 @@ export function originalChoices(decision) {
 
 /** Builds the typed response for the decision's method; grouped questions need every required answer. */
 export function composeResponse(decision, form = {}) {
+	// A tool grant (294 C3) takes only the structured toolGrant answer; a confirm, value or free text never becomes one.
+	if (isToolGrant(decision)) return { ok: false, reason: "unsupported" };
 	const payload = record(decision.payload) ? decision.payload : {};
 	switch (decision.method) {
 		case "select": {
@@ -455,7 +459,7 @@ export function composeResponse(decision, form = {}) {
 
 /** An unchanged response replays its pending request verbatim, even after the current presentation mode changes. */
 export function buildRequest(inbox, decision, mode, response, newId = () => crypto.randomUUID()) {
-	if (decision.security) return null;
+	if (decision.security || isArtifactReview(decision)) return null;
 	if (inbox.reviewRequired.has(decision.id)) return null;
 	const draft = inbox.drafts.get(decision.id);
 	const payload = response === undefined ? null : response;
@@ -606,3 +610,351 @@ export function waitReason(decision) {
 	if (work) parts.push(t("decisions.wait.work_status", { status: WORK_STATUS_LABELS[work.status] ?? work.status, reason: work.statusReason ? ` (${work.statusReason})` : "" }));
 	return parts.join(" ");
 }
+
+// Agent tool grants (plan 294 item 9, C3/C7/C8): the inbox card of a decision whose payload the gateway built with purpose
+// agent_tool_grant. The answer is the server's choice plus the proposal digest; the owner calls carry the page nonce the
+// gateway issued to this screen (POST /api/agent-tool-client) and the CSRF custom header.
+export const TOOL_GRANT_PURPOSE = "agent_tool_grant";
+/** C8: the one-shot confirmation of one click/fill; same structured answer, no lasting grant. */
+const TOOL_ACTION_PURPOSE = "agent_tool_action";
+/** Every 294 tool card the gateway answers only for the verified owner (src/agent/tool-permissions.ts TOOL_PURPOSES). */
+const OWNER_ANSWER_PURPOSES = new Set([TOOL_GRANT_PURPOSE, TOOL_ACTION_PURPOSE, "agent_tool_migration"]);
+export const AGENT_TOOL_FEATURE = "agent-tool-permissions-v1";
+export const AGENT_TOOL_CLIENT_PATH = "/api/agent-tool-client";
+export const AGENT_TOOL_CLIENT_HEADER = "x-zigmini-agent-tool-client";
+export const AGENT_TOOL_NONCE_HEADER = "x-zigmini-page-nonce";
+export const AGENT_TOOL_FEATURE_HEADER = "x-zigmini-features";
+const PROPOSAL_DIGEST = /^[0-9a-f]{64}$/;
+const EXPIRED_CLIENT = new Set(["agent_tool_client_required", "page_nonce_invalid"]);
+const BROWSER_TOOL = "zgw_aside";
+const OWNED_TAB_OPERATIONS = new Set(["open_owned"]);
+const READ_OPERATIONS = new Set(["read", "screenshot", "list", "search", "fetch"]);
+const OPAQUE_SCOPE_KEYS = new Set(["kind", "selection", "targetHandle", "targetId", "targetLabel", "targetTitle", "account", "host"]);
+const TOOL_ERROR_KEYS = {
+	tool_grant_response_required: "response", tool_grant_principal_required: "principal", proposal_digest_mismatch: "digest", agent_access_blocked: "blocked",
+	grant_conflict: "grant", grant_not_found: "gone", policy_conflict: "policy", cursor_stale: "policy", cursor_invalid: "policy",
+	page_nonce_invalid: "expired", agent_tool_client_required: "expired", forbidden: "forbidden", forbidden_origin: "forbidden", forbidden_host: "forbidden",
+	custom_header_required: "forbidden", operation_conflict: "operation", tool_request_invalid: "invalid", lifecycle_epoch_mismatch: "epoch",
+	authority_epoch_mismatch: "epoch", tool_request_conflict: "duplicate", decision_not_found: "missing", not_found: "missing",
+};
+
+export function featureHeaders() {
+	return { [AGENT_TOOL_FEATURE_HEADER]: AGENT_TOOL_FEATURE };
+}
+
+/** The headers of an owner call (answer, list, revoke, edit): the CSRF header, this page's nonce and the feature mark. */
+export function ownerHeaders(client) {
+	if (!record(client) || typeof client.pageNonce !== "string" || client.pageNonce === "") return null;
+	return { [AGENT_TOOL_CLIENT_HEADER]: "1", [AGENT_TOOL_NONCE_HEADER]: client.pageNonce, [AGENT_TOOL_FEATURE_HEADER]: AGENT_TOOL_FEATURE };
+}
+
+export function interpretClientIssue(status, body) {
+	if (status === 200 && record(body) && body.client === "web" && typeof body.pageNonce === "string" && body.pageNonce !== "" && typeof body.generation === "string") {
+		return { kind: "ready", client: { pageNonce: body.pageNonce, generation: body.generation } };
+	}
+	if (status === 401 || status === 403) return { kind: "refused", status };
+	return { kind: "unavailable", status };
+}
+
+/** A 403 whose session or page nonce is gone: the screen takes a new token, and the refused POST is never replayed by itself. */
+export function clientExpired(error) {
+	return typeof error === "string" && EXPIRED_CLIENT.has(error);
+}
+
+export function toolGrantPayload(decision) {
+	const payload = record(decision?.payload) ? decision.payload : null;
+	if (!payload || (payload.purpose !== TOOL_GRANT_PURPOSE && payload.purpose !== TOOL_ACTION_PURPOSE) || typeof payload.proposalDigest !== "string" || !PROPOSAL_DIGEST.test(payload.proposalDigest)) return null;
+	return payload;
+}
+
+export function isToolGrant(decision) {
+	return toolGrantPayload(decision) !== null;
+}
+
+/** The answer of this card carries the owner client headers (cookie, page nonce, x-zigmini-agent-tool-client). */
+export function ownerAnswerRequired(decision) {
+	return record(decision?.payload) && OWNER_ANSWER_PURPOSES.has(decision.payload.purpose);
+}
+
+function toolIdentifier(toolKey) {
+	return record(toolKey) && typeof toolKey.originalName === "string" ? toolKey.originalName : "";
+}
+
+function dictionaryText(key) {
+	const text = t(key);
+	return text === key ? null : text;
+}
+
+/** The display name of a tool: the dictionary's name for the tools it knows, else the registered identifier. */
+export function toolName(toolKey) {
+	const name = toolIdentifier(toolKey);
+	return name ? dictionaryText(`decisions.tool.name.${name}`) ?? name : "";
+}
+
+export function operationLabel(toolKey, operation) {
+	if (typeof operation !== "string" || operation === "") return "";
+	const name = toolIdentifier(toolKey);
+	return (name ? dictionaryText(`decisions.tool.op.${name}.${operation}`) : null) ?? dictionaryText(`decisions.tool.op.${operation}`) ?? operation;
+}
+
+function operationDescription(toolKey, operation) {
+	const name = toolIdentifier(toolKey);
+	return (name && operation ? dictionaryText(`decisions.tool.desc.${name}.${operation}`) : null) ?? operationLabel(toolKey, operation);
+}
+
+/** The readable lines of a scope: the user's target label first, then every string or string-list value; opaque handles never show. */
+export function scopeLines(scope) {
+	if (!record(scope)) return [];
+	if (scope.kind === "exact_args") return [{ key: "exact", label: t("decisions.tool.label.target"), value: t("decisions.tool.target.exact") }];
+	const lines = [];
+	const label = typeof scope.targetLabel === "string" ? scope.targetLabel : typeof scope.targetTitle === "string" ? scope.targetTitle : "";
+	if (label) lines.push({ key: "target", label: t("decisions.tool.label.target"), value: label });
+	for (const [key, value] of Object.entries(scope)) {
+		if (OPAQUE_SCOPE_KEYS.has(key)) continue;
+		if (typeof value === "string" && value) lines.push({ key, label: key, value });
+		else if (Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string")) lines.push({ key, label: key, value: value.join(", ") });
+	}
+	return lines;
+}
+
+/** One line for a scope: "label (other values)", the values alone, or the no-scope text. */
+export function scopeText(scope) {
+	const lines = scopeLines(scope);
+	if (lines.length === 0) return t("decisions.tool.target.none");
+	const target = lines.find((line) => line.key === "target");
+	const rest = lines.filter((line) => line !== target).map((line) => line.value);
+	if (!target) return rest.join(", ");
+	return rest.length ? `${target.value} (${rest.join(", ")})` : target.value;
+}
+
+/** C7: a borrowed browser tab must be chosen by the user before allow; an owned tab the agent opens itself needs none. */
+export function targetSelectionNeeded(payload) {
+	if (!record(payload)) return false;
+	const scope = record(payload.scope) ? payload.scope : null;
+	if (scope?.selection === "user") return true;
+	const browser = toolIdentifier(payload.toolKey) === BROWSER_TOOL || scope?.kind === "browser_target";
+	if (!browser || OWNED_TAB_OPERATIONS.has(payload.operation)) return false;
+	return typeof scope?.targetHandle !== "string" || scope.targetHandle === "";
+}
+
+export function toolGrantView(decision, { agentName = (id) => id } = {}) {
+	const payload = toolGrantPayload(decision) ?? {};
+	const action = payload.purpose === TOOL_ACTION_PURPOSE;
+	const targetNeeded = targetSelectionNeeded(payload);
+	const operation = typeof payload.operation === "string" ? payload.operation : "";
+	const tool = toolName(payload.toolKey);
+	const op = operationLabel(payload.toolKey, operation);
+	// F3 D4: a collaboration the owner started has no origin agent; it is named as the owner's own request, never as an unnamed peer.
+	const originAgentId = typeof payload.originAgentId === "string" ? payload.originAgentId : "";
+	const source = payload.originKind !== "agent_collaboration" ? t("decisions.tool.source.user")
+		: originAgentId === "" ? t("decisions.tool.source.owner")
+		: t("decisions.tool.source.peer", { name: agentName(originAgentId) || originAgentId });
+	const rows = [
+		{ key: "agent", label: t("decisions.tool.label.agent"), value: agentName(typeof payload.agentId === "string" ? payload.agentId : "") },
+		{ key: "source", label: t("decisions.tool.label.source"), value: source },
+		{ key: "tool", label: t("decisions.tool.label.tool"), value: op ? `${tool} - ${op}` : tool },
+		{ key: "target", label: t("decisions.tool.label.target"), value: targetNeeded ? t("decisions.tool.target.select") : scopeText(payload.scope) },
+		{ key: "operation", label: t("decisions.tool.label.operation"), value: operationDescription(payload.toolKey, operation) },
+		{ key: "duration", label: t("decisions.tool.label.duration"), value: t(action ? "decisions.tool.action.duration" : "decisions.tool.duration") },
+	];
+	return {
+		title: t(action ? "decisions.tool.action.title" : "decisions.tool.title"),
+		rows,
+		note: t(action ? "decisions.tool.action.note" : "decisions.tool.note"),
+		restriction: t(action ? "decisions.tool.action.restriction" : READ_OPERATIONS.has(operation) ? "decisions.tool.restriction.read" : "decisions.tool.restriction.other"),
+		choices: [{ choice: "allow", label: t("decisions.tool.allow"), cls: "ok" }, { choice: "deny", label: t("decisions.tool.deny"), cls: "danger" }],
+		targetNeeded,
+	};
+}
+
+/** The structured answer (C3): exactly the choice and the digest. Allow needs the chosen tab first; deny never does. */
+export function composeToolGrantResponse(decision, form = {}) {
+	const payload = toolGrantPayload(decision);
+	if (!payload) return { ok: false, reason: "unsupported" };
+	const choice = form.choice;
+	if (choice !== "allow" && choice !== "deny") return { ok: false, reason: "incomplete" };
+	if (choice === "allow" && targetSelectionNeeded(payload)) return { ok: false, reason: "target_required" };
+	return { ok: true, response: { toolGrant: { choice, proposalDigest: payload.proposalDigest } } };
+}
+
+export function toolGrantOutcome(decision) {
+	if (!isToolGrant(decision) || !record(decision.answer)) return null;
+	if (decision.answer.cancelled === true) return "cancelled";
+	const grant = record(decision.answer.toolGrant) ? decision.answer.toolGrant : null;
+	if (grant?.choice === "allow") return "allowed";
+	if (grant?.choice === "deny") return "denied";
+	return null;
+}
+
+export function toolGrantOutcomeText(decision) {
+	const outcome = toolGrantOutcome(decision);
+	return outcome === null ? null : t(`decisions.tool.outcome.${outcome}`);
+}
+
+/** A gateway refusal in the user's words; the code itself never reaches the screen. */
+export function toolErrorText(error, status = 0) {
+	const key = typeof error === "string" ? TOOL_ERROR_KEYS[error] : undefined;
+	return t(`decisions.tool.error.${key ?? (status === 403 && error ? "forbidden" : "generic")}`);
+}
+
+function httpOrigin(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+/** The open tabs the gateway listed for the user's screen (never for the model): suggested ones first, no local or non-web pages. */
+export function targetCandidates(body) {
+	if (!record(body) || !Array.isArray(body.candidates)) return [];
+	const list = [];
+	for (const entry of body.candidates) {
+		if (!record(entry) || typeof entry.id !== "string" || entry.id === "" || typeof entry.url !== "string") continue;
+		const parsed = httpOrigin(entry.url);
+		if (!parsed || parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]" || parsed.hostname === "0.0.0.0") continue;
+		const title = typeof entry.title === "string" && entry.title.trim() ? entry.title.trim() : parsed.hostname;
+		list.push({ id: entry.id, title, url: entry.url, origin: parsed.origin, suggested: entry.suggested === true });
+	}
+	return [...list.filter((entry) => entry.suggested), ...list.filter((entry) => !entry.suggested)];
+}
+
+export function candidatesPath(decision) {
+	return `/api/decisions/${encodeURIComponent(decision.id)}/aside-targets`;
+}
+
+/** Binds the chosen tab to the proposal; the gateway answers with the re-proposed decision whose digest allow then confirms. */
+export function designateRequest(decision, candidateId, newId = () => crypto.randomUUID()) {
+	return { method: "POST", path: `/api/decisions/${encodeURIComponent(decision.id)}/aside-target`, body: { operationId: newId(), expectedRevision: decision.revision, candidateId } };
+}
+
+export function interpretDesignate(status, body) {
+	const decision = record(body) && typeof body.id === "string" && typeof body.revision === "number" ? body : null;
+	const latest = record(body) && record(body.decision) ? body.decision : null;
+	const error = record(body) && typeof body.error === "string" ? body.error : null;
+	if (status === 200 && decision) return { kind: "accepted", decision };
+	if (status === 409) return { kind: "conflict", decision: latest };
+	if (status === 404) return { kind: "unsupported", error, status };
+	if (status === 400 || status === 401 || status === 403 || status === 410) return { kind: "refused", error, status };
+	return { kind: "unavailable", error, status };
+}
+
+// Artifact review holds (agent-collaboration-292 owner gap, hold UI): the inbox card of a security decision whose payload
+// the files.read track built with purpose collaboration_artifact_review. The gateway's DecisionInfo carries
+// `artifactReview` (the hold state, the reading agent, the file, the part asked for and the finding summary: kinds and
+// counts only, never a flagged value). Allow and deny go to the owner hold route with the revision on screen and a fresh
+// submissionId per click; the generic answer route refuses these decisions (security_endpoint_required), so no draft,
+// recheck or dismiss is built for them.
+export const ARTIFACT_REVIEW_PURPOSE = "collaboration_artifact_review";
+export const ARTIFACT_HOLDS_PATH = "/api/agent-collaboration/holds";
+const REVIEW_STATES = new Set(["pending", "allowed", "denied", "cancelled", "invalidated"]);
+const REVIEW_VIEWS = new Set(["raw", "text", "pages"]);
+
+/** The validated owner view of a held read, or null when the decision carries none (an ordinary or message-hold decision). */
+export function artifactReview(decision) {
+	const review = record(decision?.artifactReview) ? decision.artifactReview : null;
+	if (!review || typeof review.holdId !== "string" || review.holdId === "" || !Number.isSafeInteger(review.revision) || review.revision < 1 ||
+		!REVIEW_STATES.has(review.state) || !REVIEW_VIEWS.has(review.view) || !record(review.range) ||
+		!Number.isSafeInteger(review.range.start) || !Number.isSafeInteger(review.range.end)) return null;
+	return review;
+}
+
+export function isArtifactReview(decision) {
+	return artifactReview(decision) !== null;
+}
+
+/** The finding summary line: each kind with its count, never a value; the words for no finding and for a hold without a summary. */
+export function reviewFindingsText(summary) {
+	if (!record(summary) || !Array.isArray(summary.findings)) return t("decisions.artifact.findings.unknown");
+	const items = summary.findings.filter((f) => record(f) && typeof f.kind === "string" && Number.isSafeInteger(f.count) && f.count > 0);
+	if (items.length === 0) return t("decisions.artifact.findings.none");
+	return items.map((f) => t("decisions.artifact.findings.item", { kind: dictionaryText(`decisions.artifact.kind.${f.kind}`) ?? f.kind, count: f.count })).join(", ");
+}
+
+/** The pages the reader could not check (no text layer) as the card's warning; null when every page was scanned. */
+export function reviewUnscannedText(summary) {
+	const pages = record(summary) && Array.isArray(summary.unscannedPages) ? summary.unscannedPages.filter((p) => Number.isSafeInteger(p) && p > 0) : [];
+	return pages.length ? t("decisions.artifact.unscanned", { pages: pages.join(", ") }) : null;
+}
+
+function reviewPartText(review) {
+	if (review.view === "raw") return t("decisions.artifact.part.raw");
+	if (review.view === "text") return t("decisions.artifact.part.text");
+	return review.range.end > review.range.start
+		? t("decisions.artifact.part.pages", { start: review.range.start, end: review.range.end })
+		: t("decisions.artifact.part.page", { page: review.range.start });
+}
+
+/** The outcome of a reviewed hold in the owner's words (allowed splits by how far the resume got); null while it is pending. */
+export function reviewOutcomeText(review) {
+	switch (review.state) {
+		case "allowed": {
+			const resume = review.resumeState;
+			if (resume === "released") return t("decisions.artifact.outcome.allowed.released");
+			if (resume === "queued" || resume === "dispatched") return t("decisions.artifact.outcome.allowed.resumed");
+			if (resume === "unrequested") return t("decisions.artifact.outcome.allowed.waiting");
+			return t("decisions.artifact.outcome.allowed.stopped", { state: typeof resume === "string" ? resume : "unknown" });
+		}
+		case "denied": return t("decisions.artifact.outcome.denied");
+		case "cancelled": return t("decisions.artifact.outcome.cancelled");
+		case "invalidated": return t("decisions.artifact.outcome.invalidated");
+		default: return null;
+	}
+}
+
+/** What the card shows: title, the four rows, the unscanned warning, the question while pending, the outcome once reviewed, and the two choices. */
+export function artifactReviewView(decision, { agentName = (id) => id, mainName = "main" } = {}) {
+	const review = artifactReview(decision);
+	if (!review) return null;
+	const actions = Array.isArray(decision.allowedActions) ? decision.allowedActions : [];
+	const pending = review.state === "pending" && actions.includes("answer");
+	return {
+		holdId: review.holdId, revision: review.revision, state: review.state, resumeState: review.resumeState,
+		title: t("decisions.artifact.title"),
+		chip: review.state === "pending" ? null : t(`decisions.artifact.chip.${review.state}`),
+		rows: [
+			{ key: "agent", label: t("decisions.artifact.label.agent"), value: review.agentId === null ? t("decisions.artifact.agent.main", { name: mainName }) : agentName(review.agentId) },
+			{ key: "file", label: t("decisions.artifact.label.file"), value: typeof review.fileName === "string" && review.fileName ? review.fileName : review.artifactId },
+			{ key: "part", label: t("decisions.artifact.label.part"), value: reviewPartText(review) },
+			{ key: "findings", label: t("decisions.artifact.label.findings"), value: reviewFindingsText(review.summary) },
+		],
+		warning: reviewUnscannedText(review.summary),
+		question: pending ? t("decisions.artifact.question") : null,
+		outcome: reviewOutcomeText(review),
+		pending,
+		choices: [{ choice: "allow", label: t("decisions.artifact.allow"), cls: "ok" }, { choice: "deny", label: t("decisions.artifact.deny"), cls: "danger" }],
+	};
+}
+
+/** The owner call of one click: the revision on screen and a fresh submissionId every time; null unless the hold still takes an answer. */
+export function artifactReviewRequest(decision, choice, newId = () => crypto.randomUUID()) {
+	const review = artifactReview(decision);
+	if (!review || (choice !== "allow" && choice !== "deny")) return null;
+	const actions = Array.isArray(decision.allowedActions) ? decision.allowedActions : [];
+	if (review.state !== "pending" || !actions.includes("answer")) return null;
+	return { method: "POST", path: `${ARTIFACT_HOLDS_PATH}/${encodeURIComponent(review.holdId)}`, headers: { "content-type": "application/json" },
+		body: JSON.stringify({ choice, expectedRevision: review.revision, submissionId: newId() }) };
+}
+
+/**
+ * What the hold route's answer means. 200 carries the review receipt (reviewState, revision, resumeState) and reads as
+ * the outcome; every refusal is a sentence: 409 is a conflict with the latest state (the card reloads it), 401/403 mean
+ * the gateway did not accept this browser as the owner, 503 owner_auth_unavailable means the action is not available
+ * yet, 404 means the hold is gone, 0 is the network. Nothing here ever claims a success the gateway did not report.
+ */
+export function artifactReviewOutcome(status, body) {
+	const code = record(body) && typeof body.error === "string" ? body.error : null;
+	const refusal = (kind, line) => ({ ok: false, kind, revision: null, resumeState: null, line });
+	if (status === 200 && record(body) && (body.reviewState === "allowed" || body.reviewState === "denied" || body.reviewState === "cancelled")) {
+		const resumeState = typeof body.resumeState === "string" ? body.resumeState : "unknown";
+		return { ok: true, kind: body.reviewState, revision: Number.isSafeInteger(body.revision) ? body.revision : null, resumeState,
+			line: reviewOutcomeText({ state: body.reviewState, resumeState }) };
+	}
+	if (status === 0) return refusal("network", t("decisions.artifact.error.network"));
+	if (status === 503 && code === "owner_auth_unavailable") return refusal("unavailable", t("decisions.artifact.error.unavailable"));
+	if (status === 401 || status === 403) return refusal("owner", t("decisions.artifact.error.ownerRequired"));
+	if (status === 404) return refusal("gone", t("decisions.artifact.error.gone"));
+	if (status === 409) return refusal("conflict", t("decisions.artifact.error.conflict"));
+	return refusal("failed", t("decisions.artifact.error.failed", { reason: code ?? `HTTP ${status}` }));
+}

package/web/gc.d.ts

@@ -1,15 +1,36 @@
-export interface GcCandidateBody { id: string; kind: string; target: string; reason: string; ageMs: number; bytes: number | null }
-export interface GcRow { id: string; label: string; sub: string; title: string }
+export type GcRole = "reconcile" | "gc";
+export interface GcCandidateBody {
+	id: string;
+	collector: string;
+	target: string;
+	reason: string;
+	ageMs: number | null;
+	bytes: number | null;
+	details?: Record<string, unknown>;
+	verdict?: { kind: string; why: string };
+	confirmation?: string;
+	reversibility?: string;
+}
+export interface GcKeptBody { id: string; collector: string; target: string; why: string; bytes: number | null; reversibility?: string }
+export interface GcRow { id: string; role: GcRole; selectable: boolean; label: string; sub: string; title: string; badge: string | null; note: string | null }
+export interface GcGroup { role: GcRole; title: string; count: number; hidden: boolean; rows: GcRow[] }
+export interface AuditRow { at: string; text: string; title: string; error: boolean }
 
-export const GC_PATH: string;
-export const GC_CLEAN_PATH: string;
+export const HOUSEKEEPING_PATH: string;
+export const HOUSEKEEPING_CLEAN_PATH: string;
+export const HOUSEKEEPING_AUDIT_PATH: string;
+export const AUDIT_LINES: number;
+export const ROLES: readonly GcRole[];
 export const KIND_LABELS: Readonly<Record<string, string>>;
 export const GC_EMPTY_LINE: string;
 export const GC_FAILED_LINE: string;
 export function formatBytes(bytes: unknown): string;
 export function formatAge(ms: number): string;
-export function gcView(report: unknown): { summary: string; rows: GcRow[]; error: boolean };
+export function reasonLabel(reason: string): string;
+export function rowFlags(role: string, kept: boolean, reversibility: string | undefined): { selectable: boolean; irreversible: boolean };
+export function gcView(report: unknown): { summary: string; groups: GcGroup[]; error: boolean };
 export function selectAllState(ticked: number, total: number): { hidden: boolean; checked: boolean; indeterminate: boolean };
 export function selectAllTarget(ticked: number, total: number): boolean;
 export function cleanRequest(ids: Iterable<string>): { method: "POST"; headers: { "content-type": "application/json" }; body: string };
 export function cleanResultLine(result: unknown): string;
+export function auditView(body: unknown): { line: string; error: boolean; rows: AuditRow[] };

package/web/gc.js

@@ -3,14 +3,22 @@ import strings from "./i18n/gc.js";
 
 registerStrings(strings);
 
-// Improvement 66 (plan Todo 24): the settings cleanup area. Only decisions live here, with no DOM, so test/unit/gc-web.test.ts
-// can exercise them. The gateway lists candidates at GET /api/gc and cleans only the ids the user ticked.
+// Improvement 66 and housekeeping todo 13: the settings cleanup area. Only decisions live here, with no DOM, so
+// test/unit/gc-web.test.ts can exercise them. The gateway lists candidates by role at GET /api/housekeeping (상태 정리 rows
+// wait for main, 회수 rows can be ticked, kept items are information) and cleans only the ids the user ticked.
 
-export const GC_PATH = "/api/gc";
-export const GC_CLEAN_PATH = "/api/gc/clean";
+export const HOUSEKEEPING_PATH = "/api/housekeeping";
+export const HOUSEKEEPING_CLEAN_PATH = "/api/housekeeping/clean";
+export const HOUSEKEEPING_AUDIT_PATH = "/api/housekeeping/audit";
+export const AUDIT_LINES = 20;
+export const ROLES = Object.freeze(["reconcile", "gc"]);
 export let KIND_LABELS;
 export let GC_EMPTY_LINE = t("gc.empty");
 export let GC_FAILED_LINE = t("gc.failed");
+let REASON_LABELS;
+// Every code with a `gc.reason.<code>` entry in the dictionary; test/unit/gc-web.test.ts checks that every code the
+// collectors, the engine and the API emit has one.
+const REASON_CODES = Object.keys(strings.en).filter((key) => key.startsWith("gc.reason.")).map((key) => key.slice("gc.reason.".length));
 function refreshStrings() {
 	KIND_LABELS = Object.freeze({
 		"db-backup": t("gc.dbBackup"),
@@ -19,7 +27,16 @@ function refreshStrings() {
 		"temp-dir": t("gc.tempDir"),
 		"rpc-daemon": t("gc.rpcDaemon"),
 		"agent-trash": t("gc.agentTrash"),
+		"agent-file-trash": t("gc.agentFileTrash"),
+		"agent-drafts": t("gc.agentDrafts"),
+		"orphan-test-process": t("gc.orphanTestProcess"),
+		worktree: t("gc.worktree"),
+		"docker-image": t("gc.dockerImage"),
+		"docker-build-cache": t("gc.dockerBuildCache"),
+		"reconcile-work": t("gc.reconcileWork"),
+		"attachment-cleanup": t("gc.attachmentCleanup"),
 	});
+	REASON_LABELS = Object.freeze(Object.fromEntries(REASON_CODES.map((code) => [code, t(`gc.reason.${code}`)])));
 	GC_EMPTY_LINE = t("gc.empty");
 	GC_FAILED_LINE = t("gc.failed");
 }
@@ -40,16 +57,79 @@ export function formatAge(ms) {
 	return t("gc.ageMinutes", { count: minutes });
 }
 
-export function gcView(report) {
-	if (report === null || typeof report !== "object" || !Array.isArray(report.candidates)) return { summary: t("gc.failed"), rows: [], error: true };
-	const rows = report.candidates.map((c) => ({
+// A reason is either a sentence the gateway already wrote in the UI language (the six old kinds) or a code of a newer
+// collector (`old_tag`, `reconcile_confirm_no_report`); a code the dictionary does not know is shown as written.
+// `kept:<why>` (a picked item a rule now keeps, in a failed clean or the log) reads as the kept line with the label of <why>.
+export function reasonLabel(reason) {
+	if (reason.startsWith("kept:")) return t("gc.keptReason", { why: reasonLabel(reason.slice("kept:".length)) });
+	return REASON_LABELS[reason] ?? reason;
+}
+
+function kindLabel(collector) {
+	return KIND_LABELS[collector] ?? collector;
+}
+
+// The last segment of a path, or the tag of an image reference (`zigmini-gateway:0.7.0-beta.3`); a target with spaces is
+// a description, not a name.
+function shortName(target) {
+	if (target.includes(" ")) return null;
+	return target.slice((target.includes("/") ? target.lastIndexOf("/") : target.lastIndexOf(":")) + 1);
+}
+
+function rowLabel(collector, name) {
+	return name === null ? kindLabel(collector) : `${kindLabel(collector)} · ${name}`;
+}
+
+// Only an open 회수 candidate can be ticked: a 상태 정리 row waits for main and a kept item is information. "Cannot be
+// undone" marks a tickable row whose collector cannot restore what it removes (Docker images).
+export function rowFlags(role, kept, reversibility) {
+	const selectable = role === "gc" && !kept;
+	return { selectable, irreversible: selectable && reversibility === "irreversible" };
+}
+
+function candidateRow(role, c) {
+	const flags = rowFlags(role, false, c.reversibility);
+	const reconcile = role === "reconcile";
+	const parts = [reasonLabel(c.reason)];
+	if (!reconcile) parts.push(...(typeof c.ageMs === "number" ? [formatAge(c.ageMs)] : []), formatBytes(c.bytes));
+	return {
 		id: c.id,
-		label: `${KIND_LABELS[c.kind] ?? c.kind} · ${c.target.slice(c.target.lastIndexOf("/") + 1)}`,
-		sub: `${c.reason} · ${formatAge(c.ageMs)} · ${formatBytes(c.bytes)}`,
+		role,
+		selectable: flags.selectable,
+		label: rowLabel(c.collector, reconcile ? c.details?.title ?? c.target : shortName(c.target)),
+		sub: parts.join(" · "),
 		title: c.target,
-	}));
-	const summary = rows.length === 0 ? t("gc.empty") : t("gc.summary", { count: rows.length, bytes: formatBytes(report.bytes) });
-	return { summary, rows, error: false };
+		badge: flags.irreversible ? t("gc.irreversible") : null,
+		note: reconcile ? t(c.details?.kind === "close" ? "gc.reconcileClosed" : "gc.reconcileNote") : null,
+	};
+}
+
+function keptRow(role, k) {
+	return {
+		id: k.id,
+		role,
+		selectable: false,
+		label: rowLabel(k.collector, shortName(k.target)),
+		sub: `${reasonLabel(k.why)} · ${formatBytes(k.bytes)}`,
+		title: k.target,
+		badge: null,
+		note: null,
+	};
+}
+
+// One group per role, 상태 정리 first. `count` is the open candidates; kept items follow them as read-only rows and a group
+// with no rows at all is hidden. The summary counts both roles and shows the 회수 bytes.
+export function gcView(report) {
+	const roles = report?.roles;
+	if (roles === null || typeof roles !== "object" || !ROLES.every((role) => Array.isArray(roles[role]?.candidates))) return { summary: t("gc.failed"), groups: [], error: true };
+	const groups = ROLES.map((role) => {
+		const kept = Array.isArray(roles[role].kept) ? roles[role].kept : [];
+		const rows = [...roles[role].candidates.map((c) => candidateRow(role, c)), ...kept.map((k) => keptRow(role, k))];
+		return { role, title: t(`gc.role.${role}`), count: roles[role].candidates.length, hidden: rows.length === 0, rows };
+	});
+	const count = groups.reduce((sum, group) => sum + group.count, 0);
+	const summary = count === 0 ? t("gc.empty") : t("gc.summary", { count, bytes: formatBytes(roles.gc.bytes) });
+	return { summary, groups, error: false };
 }
 
 // Improvement 142: the select-all box beside the summary. It is hidden with no rows, checked when every row is ticked and
@@ -70,6 +150,26 @@ export function cleanRequest(ids) {
 export function cleanResultLine(result) {
 	const cleaned = result?.cleaned?.length ?? 0;
 	const failed = result?.failed?.length ?? 0;
+	const kept = result?.kept?.length ?? 0;
 	const missing = result?.missing?.length ?? 0;
-	return t("gc.cleanResult", { cleaned, failed: failed > 0 ? t("gc.failedCount", { count: failed }) : "", missing: missing > 0 ? t("gc.missingCount", { count: missing }) : "" });
+	return t("gc.cleanResult", {
+		cleaned,
+		failed: failed > 0 ? t("gc.failedCount", { count: failed }) : "",
+		kept: kept > 0 ? t("gc.keptCount", { count: kept }) : "",
+		missing: missing > 0 ? t("gc.missingCount", { count: missing }) : "",
+	});
+}
+
+function auditRow(line) {
+	const what = rowLabel(line.collector, line.target === null ? null : shortName(line.target));
+	const error = reasonLabel(line.error ?? "");
+	const outcome = line.verdict === "error" ? t("gc.audit.error", { error }) : line.ok ? t(`gc.method.${line.method}`) : t("gc.audit.failedLine", { error });
+	return { at: line.at, text: `${t(`gc.actor.${line.actor}`)} · ${what} · ${outcome}`, title: line.target ?? "", error: !line.ok };
+}
+
+// 기록 보기: the audit lines GET /api/housekeeping/audit returned (oldest first), newest first for reading.
+export function auditView(body) {
+	if (body === null || typeof body !== "object" || !Array.isArray(body.lines)) return { line: t("gc.audit.failed"), error: true, rows: [] };
+	const rows = body.lines.map(auditRow).reverse();
+	return { line: rows.length === 0 ? t("gc.audit.empty") : "", error: false, rows };
 }

package/web/i18n/agents.d.ts

@@ -0,0 +1,4 @@
+import type { Dictionary } from "../i18n.js";
+
+declare const strings: Dictionary;
+export default strings;