@zq-silk/yui 0.2.0 → 0.4.2

package/dist/commands/agentCommands.js

@@ -1,6 +1,8 @@
+import { isDeepStrictEqual } from "node:util";
 import { agentNotFound, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
-import { createConfiguredAgent } from "../agent/agent.js";
+import { createConfiguredAgent, validateConfiguredAgent } from "../agent/agent.js";
+import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 const SUPPORTED_ADAPTERS = Object.freeze(["codex", "claude"]);
 export function runAgentCommand(args, store) {
     const [command, ...rest] = args;
@@ -95,7 +97,37 @@ function updateAgent(args, store) {
             ? { environment: parsed.many("--env").map(parseEnvironmentBinding) }
             : parsed.has("--clear-env") ? { environment: [] } : {})
     };
-    const result = store.updateConfiguredAgent(id, patch, new Date());
+    const now = new Date();
+    const result = store.transaction((tx) => {
+        const existing = tx.getConfiguredAgent(id);
+        if (existing === null)
+            return null;
+        const changes = actualAgentChanges(existing, patch);
+        if (!changes.operational) {
+            return { status: "unchanged", agent: existing };
+        }
+        const lifecycle = findRuntimeLifecycleReference(tx, id);
+        if (lifecycle !== null) {
+            throw usageError(`Agent ${id} cannot be updated because ${describeReference(lifecycle)} `
+                + "has pending runtime lifecycle launch or cleanup work. "
+                + "Wait for lifecycle reconciliation to finish before changing Agent launch settings.");
+        }
+        const liveSession = findNonStoppedSessionReference(tx, id);
+        if (liveSession !== null) {
+            throw usageError(`Agent ${id} cannot be updated because ${describeReference(liveSession)} `
+                + `retains a non-stopped native session (${liveSession.status}). `
+                + "Stop that Role session before changing Agent launch settings.");
+        }
+        if (changes.adapter) {
+            const binding = findRoleBindingReference(tx, id);
+            if (binding !== null) {
+                throw usageError(`Agent ${id} adapter cannot change because ${describeReference(binding)} references it. `
+                    + "Create a new Agent ID with the target adapter and bind the Role to it instead.");
+            }
+        }
+        assertValidAgentCandidate(existing, patch, now);
+        return tx.updateConfiguredAgent(id, patch, now);
+    });
     if (result === null)
         throw agentNotFound(id);
     return result.status === "unchanged"
@@ -106,10 +138,121 @@ function removeAgent(args, store) {
     const [rawId, ...rest] = args;
     const id = agentId(rawId);
     assertNoArguments(rest, "Agent remove usage: yui agent remove <agent-id>");
-    if (!store.removeConfiguredAgent(id))
+    const removed = store.transaction((tx) => {
+        if (tx.getConfiguredAgent(id) === null)
+            return false;
+        if (tx.getConfig().defaultAgent === id) {
+            throw usageError(`Agent ${id} cannot be removed because config.defaultAgent references it. `
+                + "Set another default Agent first.");
+        }
+        const lifecycle = findRuntimeLifecycleReference(tx, id);
+        if (lifecycle !== null) {
+            throw usageError(`Agent ${id} cannot be removed because ${describeReference(lifecycle)} `
+                + "has pending runtime lifecycle launch or cleanup work. "
+                + "Wait for lifecycle reconciliation to finish first.");
+        }
+        const binding = findRoleBindingReference(tx, id);
+        if (binding !== null) {
+            throw usageError(`Agent ${id} cannot be removed because ${describeReference(binding)} references it. `
+                + "Migrate or remove that Role binding before removing this Agent.");
+        }
+        const session = findNonStoppedSessionReference(tx, id);
+        if (session !== null) {
+            throw usageError(`Agent ${id} cannot be removed because ${describeReference(session)} `
+                + `retains a native session (${session.status}). Stop that Role session first.`);
+        }
+        return tx.removeConfiguredAgent(id);
+    });
+    if (!removed)
         throw agentNotFound(id);
     return `Removed agent ${id}\n`;
 }
+function actualAgentChanges(existing, patch) {
+    const adapter = patch.adapterId !== undefined && patch.adapterId !== existing.adapterId;
+    const operational = adapter
+        || (patch.command !== undefined && patch.command !== existing.command)
+        || (patch.baseArgs !== undefined && !isDeepStrictEqual(patch.baseArgs, existing.baseArgs))
+        || (patch.environment !== undefined
+            && !isDeepStrictEqual(patch.environment, existing.environment));
+    return { adapter, operational };
+}
+function assertValidAgentCandidate(existing, patch, now) {
+    try {
+        validateConfiguredAgent({
+            ...existing,
+            ...structuredClone(patch),
+            updatedAt: now.toISOString()
+        });
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
+function findRuntimeLifecycleReference(store, agentId) {
+    for (const role of store.listGlobalRoles()) {
+        if (role.activeAgentId === agentId
+            && hasRuntimeLifecycleWork(store.getWorkMailbox(runtimeLifecycleTarget({
+                scope: "global",
+                roleName: role.name
+            })))) {
+            return { scope: "global", roleName: role.name };
+        }
+    }
+    for (const task of store.listTasks()) {
+        for (const role of store.listRoles(task.id)) {
+            if (role.activeAgentId === agentId
+                && hasRuntimeLifecycleWork(store.getWorkMailbox(runtimeLifecycleTarget({
+                    scope: "task",
+                    taskId: task.id,
+                    roleName: role.name
+                })))) {
+                return { scope: "task", taskId: task.id, roleName: role.name };
+            }
+        }
+    }
+    return null;
+}
+function findRoleBindingReference(store, agentId) {
+    for (const role of store.listGlobalRoles()) {
+        if (Object.hasOwn(role.agentBindings, agentId)) {
+            return { scope: "global", roleName: role.name };
+        }
+    }
+    for (const task of store.listTasks()) {
+        for (const role of store.listRoles(task.id)) {
+            if (Object.hasOwn(role.agentBindings, agentId)) {
+                return { scope: "task", taskId: task.id, roleName: role.name };
+            }
+        }
+    }
+    return null;
+}
+function findNonStoppedSessionReference(store, agentId) {
+    for (const set of store.listGlobalRoleSessionSets()) {
+        const reference = sessionReference(set, agentId, { scope: "global", roleName: set.owner.roleName });
+        if (reference !== null)
+            return reference;
+    }
+    for (const task of store.listTasks()) {
+        for (const set of store.listRoleSessionSets(task.id)) {
+            const reference = sessionReference(set, agentId, { scope: "task", taskId: task.id, roleName: set.owner.roleName });
+            if (reference !== null)
+                return reference;
+        }
+    }
+    return null;
+}
+function sessionReference(set, agentId, reference) {
+    const session = set.sessions[agentId];
+    if (session === undefined || session.status === "stopped")
+        return null;
+    return { ...reference, status: session.status };
+}
+function describeReference(reference) {
+    return reference.scope === "global"
+        ? `Global Role ${reference.roleName}`
+        : `Task ${reference.taskId ?? "?"} Role ${reference.roleName}`;
+}
 function parseAgentOptions(args, mode) {
     const valueOptions = new Map([
         ["--adapter", { repeatable: false, allowOptionLikeValue: false }],

package/dist/commands/configCommands.js

@@ -0,0 +1,126 @@
+import { usageError } from "../errors/cliError.js";
+import { DEFAULT_RECONCILIATION_INTERVAL_SECONDS, reconciliationIntervalMilliseconds } from "../config/yuiConfig.js";
+import { resolveTimeZone } from "../output/timePresentation.js";
+import { REVIEW_TRIGGERS } from "../review/reviewConfig.js";
+const CONFIG_SET_USAGE = "Config set usage: yui config set "
+    + "<--time-zone <IANA timezone> | "
+    + "--reconciliation-interval-seconds <seconds>>.";
+export function runConfigCommand(args, store) {
+    const [command, ...rest] = args;
+    if (command === "review")
+        return runReviewConfigCommand(rest, store);
+    if (command === "show") {
+        if (rest.length !== 0)
+            throw usageError("Config show usage: yui config show.");
+        const config = store.getConfig();
+        const reconciliationIntervalSeconds = config.reconciliationIntervalSeconds
+            ?? DEFAULT_RECONCILIATION_INTERVAL_SECONDS;
+        reconciliationIntervalMilliseconds(reconciliationIntervalSeconds);
+        return [
+            `Time zone: ${resolveTimeZone(config.timeZone)}`,
+            `Reconciliation interval: ${reconciliationIntervalSeconds} seconds`,
+            ""
+        ].join("\n");
+    }
+    if (command === "set") {
+        if (rest.length !== 2) {
+            throw configSetUsageError();
+        }
+        if (rest[0] === "--time-zone") {
+            const timeZone = validatedConfigValue(() => resolveTimeZone(rest[1]));
+            store.transaction((tx) => {
+                tx.saveConfig({ ...tx.getConfig(), timeZone });
+            });
+            return `Time zone set to ${timeZone}\n`;
+        }
+        if (rest[0] === "--reconciliation-interval-seconds") {
+            const reconciliationIntervalSeconds = parseReconciliationIntervalSeconds(rest[1]);
+            validatedConfigValue(() => reconciliationIntervalMilliseconds(reconciliationIntervalSeconds));
+            store.transaction((tx) => {
+                tx.saveConfig({ ...tx.getConfig(), reconciliationIntervalSeconds });
+            });
+            return `Reconciliation interval set to ${reconciliationIntervalSeconds} seconds\n`;
+        }
+        throw configSetUsageError();
+    }
+    throw usageError(command === undefined
+        ? "Config command is required."
+        : `Unknown command: config ${command}`);
+}
+function runReviewConfigCommand(args, store) {
+    const [command, ...rest] = args;
+    if (command === "show") {
+        if (rest.length !== 0)
+            throw usageError("Config review show usage: yui config review show.");
+        const review = store.getConfig().review;
+        return review === undefined
+            ? "Review: disabled\n"
+            : `Review: ${review.roleName} (${review.trigger})\n`;
+    }
+    if (command === "clear") {
+        if (rest.length !== 0)
+            throw usageError("Config review clear usage: yui config review clear.");
+        store.transaction((tx) => {
+            const { review: _review, ...config } = tx.getConfig();
+            tx.saveConfig(config);
+        });
+        return "Review disabled\n";
+    }
+    if (command === "set") {
+        const usage = "Config review set usage: "
+            + "yui config review set --role <global-role> --trigger <always|leader|final>.";
+        if (rest.length !== 4)
+            throw usageError(usage);
+        const options = new Map();
+        for (let index = 0; index < rest.length; index += 2) {
+            const name = rest[index];
+            const value = rest[index + 1];
+            if (!["--role", "--trigger"].includes(name)
+                || value === undefined
+                || options.has(name)) {
+                throw usageError(usage);
+            }
+            options.set(name, value);
+        }
+        const roleName = options.get("--role")?.trim();
+        const rawTrigger = options.get("--trigger")?.trim();
+        if (roleName === undefined || roleName.length === 0
+            || rawTrigger === undefined
+            || !REVIEW_TRIGGERS.includes(rawTrigger)) {
+            throw usageError(usage);
+        }
+        if (store.getGlobalRole?.(roleName) === null) {
+            throw usageError(`Global Role not found: ${roleName}.`);
+        }
+        const trigger = rawTrigger;
+        store.transaction((tx) => {
+            tx.saveConfig({
+                ...tx.getConfig(),
+                review: { roleName, trigger }
+            });
+        });
+        return `Review set to ${roleName} (${trigger})\n`;
+    }
+    throw usageError(command === undefined
+        ? "Config review command is required."
+        : `Unknown command: config review ${command}`);
+}
+function parseReconciliationIntervalSeconds(value) {
+    if (!/^\d+$/.test(value))
+        return Number.NaN;
+    return Number(value);
+}
+function validatedConfigValue(validate) {
+    try {
+        return validate();
+    }
+    catch (error) {
+        if (error instanceof TypeError) {
+            throw usageError(error.message, CONFIG_SET_USAGE);
+        }
+        throw error;
+    }
+}
+function configSetUsageError() {
+    return usageError(CONFIG_SET_USAGE);
+}

package/dist/commands/controllerCommands.js

@@ -0,0 +1,365 @@
+import { usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { DEFAULT_RECONCILIATION_INTERVAL_SECONDS } from "../config/yuiConfig.js";
+export function parseControllerStatusOptions(args) {
+    const allowed = new Set(["--all", "--verbose"]);
+    if (args.some((argument) => !allowed.has(argument))
+        || new Set(args).size !== args.length) {
+        throw usageError("Controller status usage: yui controller status [--all] [--verbose].");
+    }
+    return {
+        scope: args.includes("--all") ? "all" : "current",
+        verbose: args.includes("--verbose")
+    };
+}
+export function parseControllerCleanupOptions(args) {
+    if (args.some((argument) => argument !== "--all")
+        || new Set(args).size !== args.length) {
+        throw usageError("Controller cleanup usage: yui controller cleanup [--all].");
+    }
+    return { scope: args.includes("--all") ? "all" : "current" };
+}
+export function renderControllerResourceStatus(snapshot, verbose, width = defaultTableWidth()) {
+    const warnings = snapshot.warnings ?? [];
+    const current = snapshot.resources.find((resource) => (resource.kind === "controller"
+        && resource.state === "current"
+        && resource.yuiHome === snapshot.currentHome));
+    const currentPid = current?.processes[0]?.pid;
+    const lines = [
+        currentPid === undefined
+            ? "Controller is not running."
+            : `Controller is running (PID ${currentPid}).`,
+        "",
+        `Observed ${snapshot.summary.domainCount} control domain(s), ${snapshot.summary.liveProcessCount} live process(es), ${formatBytes(snapshot.summary.rssBytes)} RSS.`
+    ];
+    if (snapshot.scope === "all"
+        || snapshot.domains.length > 1
+        || snapshot.domains.some(({ domainKind }) => domainKind !== undefined)) {
+        const visibleDomains = selectVisibleDomains(snapshot, verbose);
+        lines.push("", renderTable("Control domains", [
+            { header: "YUI_HOME", minWidth: 16, maxWidth: 54 },
+            { header: "Domain", minWidth: 10, maxWidth: 18 },
+            { header: "Lifetime", minWidth: 10, maxWidth: 18 },
+            { header: "Storage", minWidth: 8, maxWidth: 13 },
+            { header: "Resources", minWidth: 9, maxWidth: 9 },
+            { header: "Processes", minWidth: 9, maxWidth: 9 },
+            { header: "RSS", minWidth: 8, maxWidth: 11 },
+            { header: "Issues", minWidth: 6, maxWidth: 6 },
+            { header: "Reason", minWidth: 12, maxWidth: 30 }
+        ], visibleDomains.map((domain) => [
+            domain.yuiHome,
+            domain.domainKind ?? "legacy",
+            domain.liveness === undefined
+                ? "—"
+                : `${domain.liveness}/${domain.disposition ?? "review"}`,
+            domain.storageStatus,
+            String(domain.resourceCount),
+            String(domain.liveProcessCount),
+            formatBytes(domain.rssBytes),
+            String(domain.issueCount),
+            domain.reasonCode ?? "—"
+        ]), width));
+        lines.push("", `Automatic ephemeral reap: every ${DEFAULT_RECONCILIATION_INTERVAL_SECONDS}s; `
+            + "only expired marked test domains with matching identities are eligible.");
+        if (visibleDomains.length < snapshot.domains.length) {
+            lines.push("", `${snapshot.domains.length - visibleDomains.length} residual-only control domain(s) `
+                + "are summarized below; use --verbose to expand them.");
+        }
+    }
+    const sessions = snapshot.resources.filter((resource) => (resource.kind === "agent-session"
+        && (verbose || resource.disposition === "protected")));
+    if (sessions.length > 0) {
+        lines.push("", renderTable("Agent sessions", [
+            { header: "Task", minWidth: 8, maxWidth: 18 },
+            { header: "Role", minWidth: 12, maxWidth: 22 },
+            { header: "Agent", minWidth: 7, maxWidth: 14 },
+            { header: "State", minWidth: 8, maxWidth: 12 },
+            { header: "PID", minWidth: 5, maxWidth: 8 },
+            { header: "RSS", minWidth: 8, maxWidth: 11 }
+        ], sessions.map((resource) => sessionRow(resource)), width));
+    }
+    const residual = snapshot.resources.filter(({ disposition }) => disposition !== "protected");
+    if (residual.length > 0) {
+        lines.push("", renderTable("Residual resources", [
+            { header: "Reason", minWidth: 16, maxWidth: 34 },
+            { header: "Count", minWidth: 5, maxWidth: 5 },
+            { header: "Live", minWidth: 4, maxWidth: 4 },
+            { header: "RSS", minWidth: 8, maxWidth: 11 },
+            { header: "Oldest", minWidth: 7, maxWidth: 10 },
+            { header: "Action", minWidth: 10, maxWidth: 12 }
+        ], residualSummaryRows(residual), width));
+    }
+    const liveAnomalies = residual.filter((resource) => resource.processes.length > 0)
+        .sort((left, right) => right.rssBytes - left.rssBytes);
+    const visible = verbose ? liveAnomalies : liveAnomalies.slice(0, 5);
+    if (visible.length > 0) {
+        lines.push("", renderTable(verbose ? "Live anomalous resources" : "Largest live anomalies", [
+            { header: "Kind", minWidth: 10, maxWidth: 18 },
+            { header: "Reason", minWidth: 16, maxWidth: 30 },
+            { header: "PID", minWidth: 5, maxWidth: 8 },
+            { header: "RSS", minWidth: 8, maxWidth: 11 },
+            { header: "Age", minWidth: 7, maxWidth: 10 },
+            { header: "Owner", minWidth: 12, maxWidth: 30 }
+        ], visible.map((resource) => [
+            resource.kind,
+            resource.reasonCode,
+            processLabel(resource),
+            formatBytes(resource.rssBytes),
+            formatDuration(resource.ageMs),
+            ownerLabel(resource.owner)
+        ]), width));
+        if (!verbose && visible.length < liveAnomalies.length) {
+            lines.push("", `${liveAnomalies.length - visible.length} more live anomalous resource(s); `
+                + "use --verbose to expand them.");
+        }
+    }
+    if (warnings.length > 0) {
+        lines.push("", "Warnings", ...warnings.slice(0, verbose ? warnings.length : 5)
+            .map((warning) => `  ! ${warning}`));
+        if (!verbose && warnings.length > 5) {
+            lines.push(`  ! ${warnings.length - 5} more warning(s); use --verbose.`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function runInteractiveControllerCleanup(input) {
+    if (!input.io.interactive) {
+        throw usageError("Controller cleanup requires an interactive terminal.");
+    }
+    const initial = await input.scan();
+    const safe = initial.resources.filter(({ disposition }) => disposition === "safe");
+    const review = initial.resources.filter(({ disposition }) => disposition === "review");
+    const protectedCount = initial.resources.filter(({ disposition }) => disposition === "protected").length;
+    const reportOnlyCount = initial.resources.filter(({ disposition }) => disposition === "report-only").length;
+    input.io.write(renderCleanupPlan(safe, review, protectedCount, reportOnlyCount));
+    const selected = [];
+    if (safe.length > 0 && await confirmed(input.io, `Clean ${safe.length} safe resource(s), reclaiming up to ${formatBytes(totalRss(safe))}? [y/N]: `)) {
+        selected.push(...safe);
+    }
+    if (review.length > 0 && await confirmed(input.io, `Review ${review.length} live resource(s) individually? [y/N]: `)) {
+        for (const resource of review) {
+            input.io.write(`${cleanupResourceLabel(resource)}\n`);
+            if (await confirmed(input.io, `Clean ${resource.kind} ${resource.id}? This may interrupt running work. [y/N]: `)) {
+                selected.push(resource);
+            }
+        }
+    }
+    if (selected.length === 0) {
+        return cleanupResult("No resources were selected; nothing was changed.", [], [], [], [], initial);
+    }
+    if (selected.some(({ processes }) => processes.length > 0)
+        && (await input.io.question(`Type cleanup to stop ${selected.filter(({ processes }) => processes.length > 0).length} `
+            + `live resource(s) and clean ${selected.length} selected resource(s): `))?.trim().toLowerCase() !== "cleanup") {
+        return cleanupResult("Cancelled; nothing was changed.", selected, [], [], [], initial);
+    }
+    const revalidated = await input.scan();
+    const currentById = new Map(revalidated.resources.map((resource) => [resource.id, resource]));
+    const ready = [];
+    const skipped = [];
+    for (const resource of selected) {
+        const current = currentById.get(resource.id);
+        if (current === undefined
+            || current.fingerprint !== resource.fingerprint
+            || (current.disposition !== "safe" && current.disposition !== "review")
+            || (resource.disposition === "safe" && current.disposition !== "safe")) {
+            skipped.push({ id: resource.id, reason: "changed-since-scan" });
+            continue;
+        }
+        ready.push(current);
+    }
+    const cleaned = [];
+    const failed = [];
+    for (const resource of ready) {
+        try {
+            await input.clean(resource);
+            cleaned.push({ id: resource.id, rssBytes: resource.rssBytes });
+        }
+        catch (error) {
+            failed.push({
+                id: resource.id,
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    const after = await input.scan();
+    const output = [
+        `Cleaned ${cleaned.length} resource(s); skipped ${skipped.length}; failed ${failed.length}.`,
+        `Estimated reclaimed RSS: ${formatBytes(cleaned.reduce((total, resource) => total + resource.rssBytes, 0))}.`,
+        `Remaining issues: ${after.resources.filter(({ disposition }) => disposition !== "protected").length}.`,
+        ...failed.map((failure) => `Failed ${failure.id}: ${failure.message}`)
+    ].join("\n");
+    return cleanupResult(output, selected, cleaned, skipped, failed, after);
+}
+function sessionRow(resource) {
+    const pid = resource.processes[0]?.pid;
+    if (resource.owner.kind === "task-role") {
+        return [
+            resource.owner.taskId,
+            resource.owner.roleName,
+            resource.owner.agentId,
+            resource.state,
+            pid === undefined ? "—" : String(pid),
+            formatBytes(resource.rssBytes)
+        ];
+    }
+    if (resource.owner.kind === "global-role") {
+        return [
+            "global",
+            resource.owner.roleName,
+            resource.owner.agentId,
+            resource.state,
+            pid === undefined ? "—" : String(pid),
+            formatBytes(resource.rssBytes)
+        ];
+    }
+    return [
+        "—",
+        resource.target ?? resource.kind,
+        "—",
+        resource.state,
+        pid === undefined ? "—" : String(pid),
+        formatBytes(resource.rssBytes)
+    ];
+}
+function selectVisibleDomains(snapshot, verbose) {
+    if (verbose)
+        return snapshot.domains;
+    const activeHomes = new Set([
+        snapshot.currentHome,
+        ...snapshot.resources
+            .filter(({ disposition }) => disposition === "protected")
+            .flatMap(({ yuiHome }) => yuiHome === undefined ? [] : [yuiHome])
+    ]);
+    const active = snapshot.domains.filter(({ yuiHome }) => activeHomes.has(yuiHome));
+    const residual = snapshot.domains
+        .filter(({ yuiHome }) => !activeHomes.has(yuiHome))
+        .sort((left, right) => right.rssBytes - left.rssBytes)
+        .slice(0, 5);
+    return [...active, ...residual];
+}
+function residualSummaryRows(resources) {
+    const groups = new Map();
+    for (const resource of resources) {
+        const entries = groups.get(resource.reasonCode) ?? [];
+        entries.push(resource);
+        groups.set(resource.reasonCode, entries);
+    }
+    return [...groups.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([reason, entries]) => [
+        reason,
+        String(entries.length),
+        String(entries.filter(({ processes }) => processes.length > 0).length),
+        formatBytes(entries.reduce((total, resource) => total + resource.rssBytes, 0)),
+        formatDuration(Math.max(0, ...entries.map(({ ageMs }) => ageMs))),
+        strongestDisposition(entries)
+    ]);
+}
+function strongestDisposition(resources) {
+    if (resources.some(({ disposition }) => disposition === "review"))
+        return "review";
+    if (resources.some(({ disposition }) => disposition === "safe"))
+        return "safe";
+    return "report-only";
+}
+function ownerLabel(owner) {
+    switch (owner.kind) {
+        case "controller-domain": return owner.yuiHome;
+        case "task-role": return `${owner.taskId}/${owner.roleName}`;
+        case "global-role": return `global/${owner.roleName}`;
+        case "none": return "unattributed";
+    }
+}
+function processLabel(resource) {
+    const first = resource.processes[0]?.pid;
+    if (first === undefined)
+        return "—";
+    return resource.processes.length === 1
+        ? String(first)
+        : `${first} +${resource.processes.length - 1}`;
+}
+function renderCleanupPlan(safe, review, protectedCount, reportOnlyCount) {
+    const domains = [...safe, ...review].reduce((counts, resource) => {
+        const home = resource.yuiHome ?? "unattributed";
+        counts.set(home, (counts.get(home) ?? 0) + 1);
+        return counts;
+    }, new Map());
+    return [
+        "Controller cleanup plan",
+        "",
+        `  Safe          ${safe.length} resource(s), ${formatBytes(totalRss(safe))} RSS`,
+        `  Review        ${review.length} resource(s), ${formatBytes(totalRss(review))} RSS`,
+        `  Protected     ${protectedCount} resource(s)`,
+        `  Report only   ${reportOnlyCount} resource(s)`,
+        ...(domains.size === 0 ? [] : [
+            "",
+            "  Domains",
+            ...[...domains.entries()].map(([home, count]) => `    ${home}: ${count} candidate(s)`)
+        ]),
+        ""
+    ].join("\n");
+}
+function cleanupResourceLabel(resource) {
+    const pids = resource.processes.map(({ pid }) => pid).join(",") || "—";
+    const domain = resource.domain;
+    return [
+        `${resource.kind}: ${resource.reasonCode}`,
+        `  Home  ${resource.yuiHome ?? "unattributed"}`,
+        `  PID   ${pids}`,
+        `  RSS   ${formatBytes(resource.rssBytes)}`,
+        `  Age   ${formatDuration(resource.ageMs)}`,
+        `  Owner ${ownerLabel(resource.owner)}`,
+        ...(domain === undefined ? [] : [
+            `  Domain ${domain.kind}/${domain.liveness}/${domain.disposition}`,
+            `  Host  ${domain.hostPid === undefined ? "—" : `${domain.hostPid}:${domain.hostProcessStartIdentity ?? "?"}`}`,
+            `  Cost  ${formatBytes(resource.rssBytes)} RSS; tmux=${domain.tmuxTargets.length}`
+        ])
+    ].join("\n");
+}
+async function confirmed(io, prompt) {
+    const answer = (await io.question(prompt))?.trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+}
+function cleanupResult(output, selected, cleaned, skipped, failed, finalSnapshot) {
+    return {
+        output,
+        data: {
+            selected: selected.map(({ id }) => id),
+            cleaned,
+            skipped,
+            failed,
+            reclaimedRssBytes: cleaned.reduce((total, resource) => total + resource.rssBytes, 0),
+            remainingIssues: finalSnapshot.resources.filter(({ disposition }) => disposition !== "protected").length
+        }
+    };
+}
+function totalRss(resources) {
+    return resources.reduce((total, resource) => total + resource.rssBytes, 0);
+}
+function formatBytes(bytes) {
+    if (bytes <= 0)
+        return "—";
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const digits = value >= 10 || unit === 0 ? 0 : 1;
+    return `${value.toFixed(digits)} ${units[unit]}`;
+}
+function formatDuration(milliseconds) {
+    if (milliseconds <= 0)
+        return "—";
+    const seconds = Math.floor(milliseconds / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}