@zq-silk/yui 0.6.6 → 0.6.8

package/README.md

@@ -735,7 +735,7 @@ process cleanup explicitly, and revalidates process, tmux pane, and socket
 identity immediately before acting. Partial failures are reported without
 hiding the resources that remain. Use `--all` to include discovered Yui homes.
 
-`controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It does not stop or restart managed tmux/Agent sessions.
+`controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It can recover a lost discovery record only when the old process still matches the current UID, Controller entrypoint, physical Home, PID, and process-start identity. It does not stop or restart managed tmux/Agent sessions.
 
 Successful `setup`, `upgrade`, and `update` commands ensure that the current
 Home has a running Controller, starting one when the Home was previously idle.
@@ -927,9 +927,13 @@ make install-local
 
 `make install-local` writes a self-contained launcher at `output/dev/bin/yui`
 and never touches the user-level `yui` command. The launcher resolves its own
-checkout and defaults `YUI_HOME` to this checkout's `output/dev/home`, so every
-instance identity that Yui derives from `YUI_HOME`—Controller socket, tmux
-server, and state—stays separate from any other checkout or the global install.
+checkout and defaults `YUI_HOME` to this checkout's `output/dev/home`. The
+Controller socket is derived from that Home's durable `homeId` at the fixed
+Linux path `/tmp/yui-<uid>/<homeId>.sock`; discovery also binds the physical
+Home directory, so caller `TMPDIR`, path aliases, and copied runtime records
+cannot redirect control requests. The tmux server namespace and state remain
+scoped to the selected Home, so the checkout stays separate from other
+checkouts and the global install.
 It is idempotent, so re-run it after pulling new code (then run
 `./output/dev/bin/yui controller restart` if a Controller is already running).
 Call the launcher by its absolute path for a stable per-checkout entry point;

package/dist/cli/commandCatalog.js

@@ -849,7 +849,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [{
                     id: "lifecycle",
                     title: "Commands",
-                    entries: ["status", "cleanup", "identity", "stop", "restart"]
+                    entries: ["status", "cleanup", "identity", "live-identity", "stop", "restart"]
                 }],
             children: [
                 {
@@ -869,6 +869,11 @@ export const ROOT_COMMAND = buildNode({
                     summary: "Read the stable runtime identity receipt (build, backend, worker).",
                     hidden: true
                 },
+                {
+                    name: "live-identity",
+                    summary: "Read the authenticated live Controller launch identity.",
+                    hidden: true
+                },
                 { name: "stop", summary: "Stop the Controller." },
                 { name: "restart", summary: "Restart internal services without stopping tmux sessions." }
             ]

package/dist/cli/invocationRouter.js

@@ -33,7 +33,8 @@ function resolveExecutionPath(args) {
         const internalExecutable = child !== undefined && ((node === ROOT_COMMAND && child.name === "internal")
             || (node.path.join(" ") === "yui completion" && child.name === "candidates")
             || (node.path.join(" ") === "yui task run" && child.name === "checkpoint")
-            || (node.path.join(" ") === "yui controller" && child.name === "identity"));
+            || (node.path.join(" ") === "yui controller"
+                && (child.name === "identity" || child.name === "live-identity")));
         if (child === undefined || (child.hidden && !internalExecutable)) {
             if (node.kind === "hybrid" && node.acceptsArguments)
                 break;

package/dist/cli/updatePorts.js

@@ -261,10 +261,12 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             }
         },
         // `runUpdate` is intentionally synchronous because the npm/staged-binary
-        // ports use spawnSync. Keep Controller ownership in this same owner by
-        // using the CLI's structured lifecycle commands; tests can replace these
-        // seams with deterministic fakes without touching a real Controller.
+        // ports use spawnSync. A short-lived child owns the async, exactly fenced
+        // reconciliation first; lifecycle capture then uses structured live
+        // Controller commands. Tests can replace these seams with deterministic
+        // fakes without touching a real Controller.
         controllerStatus(home) {
+            reconcileControllerResourcesForUpdate(home, environment, spawn);
             return readControllerLifecycle(home, environment, spawn);
         },
         stopController(home, expectedPid) {
@@ -285,6 +287,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
 }
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
+const UPDATE_CONTROLLER_RECONCILIATION_PATH = fileURLToPath(new URL("../controller/updateReconciliation.js", import.meta.url));
 /**
  * Capture running state plus an authenticated exact process identity before
  * stopping. Public `controller status` is an inventory and intentionally
@@ -330,18 +333,18 @@ function readControllerLifecycle(home, environment, spawn, cliBinary) {
         if (current !== undefined) {
             throw new Error("Controller inventory is current but has no process proof; treating ownership as unknown-active.");
         }
-        return proveControllerAbsent(home, environment, spawn);
+        return proveControllerAbsent(home, environment, spawn, cliBinary);
     }
-    const identity = parseControllerIdentity(runControllerCommand(home, environment, spawn, "identity", cliBinary));
+    const identity = parseControllerIdentity(runControllerCommand(home, environment, spawn, "live-identity", cliBinary));
     return {
         running: true,
         ...(isPositivePid(processInfo.pid) ? { pid: processInfo.pid } : {}),
         identity
     };
 }
-function proveControllerAbsent(home, environment, spawn) {
+function proveControllerAbsent(home, environment, spawn, cliBinary) {
     try {
-        runControllerCommand(home, environment, spawn, "identity");
+        runControllerCommand(home, environment, spawn, "live-identity", cliBinary);
     }
     catch (error) {
         if (controllerErrorCode(error) === "CONTROLLER_NOT_RUNNING") {
@@ -349,7 +352,7 @@ function proveControllerAbsent(home, environment, spawn) {
         }
         throw new Error(`Controller absence could not be authenticated: ${messageOf(error)}`, { cause: error });
     }
-    throw new Error("Controller identity is reachable but inventory is currentless; treating ownership as unknown-active.");
+    throw new Error("A live Controller identity is reachable but inventory is currentless; treating ownership as unknown-active.");
 }
 function stopControllerForUpdate(home, expectedPid, environment, spawn) {
     // Parent update owns this lifecycle boundary. Invoke the runtime client
@@ -464,7 +467,7 @@ function restartControllerForUpdate(home, environment, spawn, activatedBinary, a
     const replacementPid = parseReplacementPid(restart.data);
     let identityFailure;
     try {
-        const identity = parseControllerIdentity(runControllerCommand(home, environment, spawn, "identity", activatedBinary));
+        const identity = parseControllerIdentity(runControllerCommand(home, environment, spawn, "live-identity", activatedBinary));
         assertActivatedControllerIdentity(identity, activatedBinary, activatedVersion);
     }
     catch (error) {
@@ -586,6 +589,57 @@ function runControllerCommand(home, environment, spawn, method, cliBinary) {
     }
     return parsed.data;
 }
+function reconcileControllerResourcesForUpdate(home, environment, spawn) {
+    const helper = [
+        "const values = process.argv.slice(1);",
+        "const home = values.pop();",
+        "const reconciliationModule = values.pop();",
+        "(async () => {",
+        "  const { reconcileControllerResourcesForUpdate } = await import(reconciliationModule);",
+        "  const data = await reconcileControllerResourcesForUpdate(home, process.env);",
+        "  process.stdout.write(JSON.stringify({ ok: true, data }));",
+        "})().catch((error) => {",
+        "  const message = error instanceof Error ? error.message : String(error);",
+        "  process.stderr.write(JSON.stringify({ ok: false, code: 'RUNTIME_ERROR', message }));",
+        "  process.exitCode = 5;",
+        "});"
+    ].join(" ");
+    const result = spawn(process.execPath, ["-e", helper, UPDATE_CONTROLLER_RECONCILIATION_PATH, home], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    if (result.error !== undefined || result.status !== 0) {
+        const detail = structuredErrorMessage(result) ?? result.stderr.toString("utf8").trim();
+        throw new Error(`Controller reconciliation failed (exit ${result.status ?? "null"})${detail.length === 0 ? "." : `: ${detail}`}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout.toString("utf8"));
+    }
+    catch (error) {
+        throw new Error("Controller reconciliation returned an invalid structured result.", {
+            cause: error
+        });
+    }
+    if (!isRecord(parsed)
+        || parsed.ok !== true
+        || !isRecord(parsed.data)
+        || !Array.isArray(parsed.data.cleaned)
+        || parsed.data.cleaned.some((id) => typeof id !== "string")) {
+        throw new Error("Controller reconciliation returned an invalid structured result.");
+    }
+}
+function structuredErrorMessage(result) {
+    for (const buffer of [result.stderr, result.stdout]) {
+        try {
+            const value = JSON.parse(buffer.toString("utf8"));
+            if (isRecord(value) && typeof value.message === "string" && value.message.length > 0) {
+                return value.message;
+            }
+        }
+        catch {
+            // Fall back to the child's raw stderr below.
+        }
+    }
+    return undefined;
+}
 function parseControllerIdentity(value) {
     if (typeof value.executablePath !== "string"
         || value.executablePath.length === 0

package/dist/cli.js

@@ -301,6 +301,29 @@ export async function main() {
     }
     if (args[0] === "controller") {
         const method = args[1];
+        if (method === "live-identity" && args.length === 2) {
+            try {
+                const identity = await callController(home, "controller.identity", {});
+                emit("", false, identity);
+            }
+            catch (error) {
+                if (!(error instanceof ControllerClientError))
+                    throw error;
+                if (jsonOutput) {
+                    process.stderr.write(`${JSON.stringify({
+                        ok: false,
+                        code: error.code,
+                        message: error.message,
+                        details: {}
+                    })}\n`);
+                }
+                else {
+                    process.stderr.write(`RUNTIME_ERROR: ${error.message}\n`);
+                }
+                process.exitCode = 5;
+            }
+            return;
+        }
         if (method === "identity" && args.length === 2) {
             // Issue 02: the stable, read-only runtime identity receipt. It survives
             // a Controller stop and answers build ID, package digest, backend, and

package/dist/controller/clientRuntime.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { callController, readControllerDiscovery } from "../core/controllerClient.js";
+import { callController, readControllerDiscovery, stopOrphanedFileTaskController, stopPreviousFileTaskController } from "../core/controllerClient.js";
 import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
@@ -227,8 +227,26 @@ export async function restartFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
     const shutdownTimeoutMs = positive(options.shutdownTimeoutMs, SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
-    const current = await readOptionalControllerStatus(home, call);
-    const previousPid = controllerPid(current);
+    let current = null;
+    let previousPid;
+    try {
+        current = await readOptionalControllerStatus(home, call);
+        previousPid = controllerPid(current);
+    }
+    catch (error) {
+        if (options.call !== undefined || !isInvalidDiscovery(error))
+            throw error;
+        // Protocol v3 is the immediately previous released Controller. Keep its
+        // parser and transport confined to this explicit replacement operation;
+        // no ordinary request can fall back to it.
+        const previous = await stopPreviousFileTaskController(home, shutdownTimeoutMs);
+        previousPid = previous.pid;
+    }
+    if (!controllerRunning(current) && options.call === undefined) {
+        const orphan = await stopOrphanedFileTaskController(home, shutdownTimeoutMs);
+        if (orphan !== undefined)
+            previousPid = orphan.pid;
+    }
     if (controllerRunning(current)) {
         await callFileTaskController(home, "controller.stop", {}, options);
         const deadline = Date.now() + shutdownTimeoutMs;
@@ -555,6 +573,11 @@ function isDefinitelyNotRunning(error) {
     const code = error.code;
     return code === "CONTROLLER_NOT_RUNNING";
 }
+function isInvalidDiscovery(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "CONTROLLER_DISCOVERY_INVALID";
+}
 async function readOptionalControllerStatus(home, call) {
     try {
         return await call(home, "controller.status", {});

package/dist/controller/resourceCleanupLinux.js

@@ -257,8 +257,9 @@ function assertOwnedArtifactPath(resource, environment) {
     }
     const home = resource.yuiHome;
     if (home !== undefined
+        && resource.homeId !== undefined
         && artifact.artifactKind === "controller-socket"
-        && path === controllerSocketPath(home)) {
+        && path === controllerSocketPath(resource.homeId)) {
         return;
     }
     if (home !== undefined

package/dist/controller/resourceInventory.js

@@ -174,7 +174,7 @@ export function buildControllerResourceInventory(facts) {
             ? homeFact.artifacts
             : [discoveryArtifact, ...homeFact.artifacts.filter((artifact) => (artifact.path !== discoveryArtifact.path))];
         for (const artifact of artifacts) {
-            resources.push(artifactResource(artifact, yuiHome, homeFact.domain));
+            resources.push(artifactResource(artifact, yuiHome, homeFact.domain, homeFact.homeId));
         }
     }
     for (const artifact of facts.globalArtifacts) {
@@ -186,6 +186,7 @@ export function buildControllerResourceInventory(facts) {
         const owned = ordered.filter((resource) => resource.yuiHome === yuiHome);
         return {
             yuiHome,
+            ...(home.homeId === undefined ? {} : { homeId: home.homeId }),
             storageStatus: home.storageStatus,
             resourceCount: owned.length,
             liveProcessCount: uniqueProcesses(owned).length,
@@ -332,7 +333,7 @@ function processResource(input) {
         ...(input.domain === undefined ? {} : { domain: input.domain })
     };
 }
-function artifactResource(artifact, yuiHome, domain) {
+function artifactResource(artifact, yuiHome, domain, homeId) {
     const stale = !artifact.active;
     const baseDisposition = stale ? "safe" : "report-only";
     const disposition = domainDisposition(baseDisposition, undefined, domain);
@@ -346,6 +347,7 @@ function artifactResource(artifact, yuiHome, domain) {
         disposition,
         reasonCode: domainReason(stale ? `stale-${artifact.artifactKind}` : `active-unmapped-${artifact.artifactKind}`, domain, disposition),
         ...(yuiHome === undefined ? {} : { yuiHome }),
+        ...(homeId === undefined ? {} : { homeId }),
         owner: yuiHome === undefined
             ? { kind: "none" }
             : { kind: "controller-domain", yuiHome },

package/dist/controller/resourceInventoryLinux.js

@@ -10,6 +10,7 @@ import { tmuxSocketDirectory, tmuxSocketEnvironment } from "../tmux/tmuxSocketEn
 import { readControllerDiscovery } from "../core/controllerClient.js";
 import { CONTROLLER_DISCOVERY_PATH } from "../core/protocol.js";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
+import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
 import { buildControllerResourceInventory } from "./resourceInventory.js";
 import { CONTROLLER_DOMAIN_PATH, EPHEMERAL_DOMAIN_GRACE_MS, ephemeralDomainFingerprint, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "./domainIdentity.js";
 const LINUX_PROCESS_SCAN_BATCH_SIZE = 64;
@@ -20,8 +21,7 @@ export async function scanControllerResourceInventory(options) {
     const observedAt = (options.now ?? (() => new Date()))();
     const warnings = [];
     const activeSockets = readActiveUnixSocketPaths(warnings);
-    const processes = (await listLinuxProcesses(warnings))
-        .filter(({ pid }) => pid !== process.pid);
+    const processes = normalizePhysicalHomeAliases((await listLinuxProcesses(warnings)).filter(({ pid }) => pid !== process.pid), currentHome);
     const homes = new Set([currentHome]);
     if (options.scope === "all") {
         for (const process of processes) {
@@ -88,19 +88,23 @@ export async function scanControllerResourceInventory(options) {
                 || (discovery.pid === process.pid
                     && readLinuxProcessStartIdentity(process.pid) === discovery.processStartIdentity));
         const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
-        const expectedControllerSocketPath = controllerSocketPath(home);
+        const expectedControllerSocketPath = state.homeId === undefined
+            ? undefined
+            : controllerSocketPath(state.homeId);
         if (discovery.status === "valid"
             && !validDiscoveryProcess
             && existsSync(discoveryPath)) {
             artifacts.push(fileArtifact(discoveryPath, "controller-discovery", false));
         }
-        if (existsSync(expectedControllerSocketPath)
+        if (expectedControllerSocketPath !== undefined
+            && existsSync(expectedControllerSocketPath)
             && !activeSockets.has(expectedControllerSocketPath)
             && !validDiscoveryProcess) {
             artifacts.push(fileArtifact(expectedControllerSocketPath, "controller-socket", false));
         }
         homeFacts.push({
             yuiHome: home,
+            ...(state.homeId === undefined ? {} : { homeId: state.homeId }),
             exists: existsSync(home),
             storageStatus: state.storageStatus,
             discovery,
@@ -203,6 +207,9 @@ async function listLinuxProcesses(warnings) {
                 const args = splitNullDelimited(readFileSync(`/proc/${pid}/cmdline`));
                 const command = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
                 const yuiHome = readYuiHome(pid);
+                const homeFilesystemId = yuiHome === undefined
+                    ? undefined
+                    : optionalHomeFilesystemId(yuiHome);
                 const io = readProcessIo(pid);
                 result.push({
                     pid,
@@ -210,6 +217,7 @@ async function listLinuxProcesses(warnings) {
                     uid: processUid,
                     startIdentity: parsed.startIdentity,
                     ...(yuiHome === undefined ? {} : { yuiHome }),
+                    ...(homeFilesystemId === undefined ? {} : { homeFilesystemId }),
                     kind: classifyRuntimeProcess(args, command),
                     command,
                     args,
@@ -227,6 +235,47 @@ async function listLinuxProcesses(warnings) {
     });
     return result;
 }
+/**
+ * Process environments retain their launch-time path spelling. Collapse
+ * symlink and bind-mount aliases by physical directory identity so inventory,
+ * update reconciliation, and cleanup all attribute them to one Home.
+ */
+function normalizePhysicalHomeAliases(processes, currentHome) {
+    const currentFilesystemId = optionalHomeFilesystemId(currentHome);
+    const representatives = new Map();
+    if (currentFilesystemId !== undefined) {
+        representatives.set(currentFilesystemId, currentHome);
+    }
+    for (const processFact of processes) {
+        const filesystemId = processFact.homeFilesystemId;
+        const yuiHome = processFact.yuiHome;
+        if (filesystemId === undefined
+            || yuiHome === undefined
+            || filesystemId === currentFilesystemId)
+            continue;
+        const existing = representatives.get(filesystemId);
+        if (existing === undefined || yuiHome.localeCompare(existing) < 0) {
+            representatives.set(filesystemId, yuiHome);
+        }
+    }
+    return processes.map((processFact) => {
+        const filesystemId = processFact.homeFilesystemId;
+        const representative = filesystemId === undefined
+            ? undefined
+            : representatives.get(filesystemId);
+        return representative === undefined || representative === processFact.yuiHome
+            ? processFact
+            : { ...processFact, yuiHome: representative };
+    });
+}
+function optionalHomeFilesystemId(home) {
+    try {
+        return readHomeFilesystemId(home);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Cooperatively visits synchronous inventory entries in bounded turns. */
 export async function forEachInEventLoopBatches(entries, batchSize, visit, timing = {}) {
     if (!Number.isSafeInteger(batchSize) || batchSize < 1) {
@@ -372,6 +421,10 @@ async function inspectDiscovery(home, processes, activeSockets) {
         const discovery = await readControllerDiscovery(home);
         return {
             status: "valid",
+            protocolVersion: discovery.protocolVersion,
+            homeId: discovery.homeId,
+            homeFilesystemId: discovery.homeFilesystemId,
+            controllerInstanceId: discovery.controllerInstanceId,
             pid: discovery.pid,
             processStartIdentity: discovery.processStartIdentity,
             socketPath: discovery.socketPath,
@@ -659,7 +712,11 @@ function loadHomeState(home, warnings, options) {
                 }
             }
         }
-        return { storageStatus: schema.status, roles };
+        return {
+            storageStatus: schema.status,
+            homeId: store.getHomeIdentity().homeId,
+            roles
+        };
     }
     catch (error) {
         warnings.push(`Cannot load runtime ownership for ${home}: ${message(error)}`);

package/dist/controller/runtime.js

@@ -84,6 +84,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             // the same WAL db and serialize via BEGIN IMMEDIATE + busy_timeout.
             ? new SqliteTaskStore(home)
             : openCompatibleFileTaskStore(home));
+    const homeId = store.getHomeIdentity().homeId;
     // When the worker backend is active, the db-touching observer folds run in
     // the worker (off the main event loop). The client is closed on shutdown.
     const asyncStoreClient = useWorker
@@ -147,7 +148,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             runtimeRoot: `${resolve(home)}.task-runtimes`,
             controlPlane: {
                 yuiHome: home,
-                controllerSocketPath: controllerSocketPath(home),
+                controllerSocketPath: controllerSocketPath(homeId),
                 tmuxNamespace: yuiTmuxServerName(home),
                 globalInstallPaths: [process.execPath]
             }

package/dist/controller/updateReconciliation.js

@@ -0,0 +1,113 @@
+import { resolve } from "node:path";
+import { acquireHomeLifecycleLock } from "../core/controllerServer.js";
+import { cleanControllerResource } from "./resourceCleanupLinux.js";
+import { scanControllerResourceInventory } from "./resourceInventoryLinux.js";
+const MAX_RECONCILIATION_PASSES = 4;
+/**
+ * Reconcile only Controller-owned resources for the Home being updated.
+ *
+ * A current Controller is preserved for the update orchestrator's exact
+ * capture/stop handoff. Superseded/orphaned Controller processes and stale
+ * discovery/socket artifacts are cleaned using their existing process-start
+ * and inode fingerprints. Agent, tmux, app, and foreign-Home resources are
+ * deliberately outside this operation.
+ */
+export async function reconcileControllerResourcesForUpdate(home, environment = process.env) {
+    const resolvedHome = resolve(home);
+    const releaseLock = await acquireHomeLifecycleLock(resolvedHome, {
+        removeStaleOwner: true
+    });
+    const cleaned = new Set();
+    try {
+        for (let pass = 0; pass < MAX_RECONCILIATION_PASSES; pass += 1) {
+            const snapshot = await scanControllerResourceInventory({
+                currentHome: resolvedHome,
+                scope: "current",
+                environment
+            });
+            assertCertainSnapshot(snapshot, resolvedHome);
+            const resources = controllerResources(snapshot, resolvedHome);
+            const controllers = resources.filter(({ kind }) => kind === "controller");
+            const current = controllers.filter(({ state }) => state === "current");
+            if (current.length > 1) {
+                throw reconciliationBlocked(`multiple current Controllers were reported (${resourceLabels(current)})`);
+            }
+            const historical = controllers.filter(({ state }) => state !== "current");
+            const historicalCleanup = historical.filter(isCleanupEligible);
+            const unsafeHistorical = historical.filter((resource) => !isCleanupEligible(resource));
+            if (unsafeHistorical.length > 0) {
+                throw reconciliationBlocked(`historical Controller ownership is not safely cleanable (${resourceLabels(unsafeHistorical)})`);
+            }
+            const artifacts = resources.filter(isControllerArtifact);
+            const staleArtifactCleanup = artifacts.filter((resource) => (resource.state === "stale" && isCleanupEligible(resource)));
+            const unresolvedArtifacts = artifacts.filter((resource) => (!staleArtifactCleanup.includes(resource)));
+            // A corrupt discovery is conservatively marked active while an orphan
+            // Controller still exists. Remove the exactly fenced historical process
+            // first; the next scan can then reclassify and remove the stale artifact.
+            if (unresolvedArtifacts.length > 0 && historicalCleanup.length === 0) {
+                throw reconciliationBlocked(`a Controller artifact is active or ownership is unknown (${resourceLabels(unresolvedArtifacts)})`);
+            }
+            const candidates = [...historicalCleanup, ...staleArtifactCleanup];
+            if (candidates.length === 0) {
+                return { cleaned: [...cleaned] };
+            }
+            for (const candidate of candidates) {
+                try {
+                    await cleanControllerResource(candidate, { environment });
+                    cleaned.add(candidate.id);
+                }
+                catch (error) {
+                    // A concurrent exact cleanup that already reached the desired state
+                    // is harmless. Anything still present or reclassified is a real
+                    // ownership change and must remain a user-visible blocker.
+                    const afterFailure = await scanControllerResourceInventory({
+                        currentHome: resolvedHome,
+                        scope: "current",
+                        environment
+                    });
+                    assertCertainSnapshot(afterFailure, resolvedHome);
+                    if (!controllerResources(afterFailure, resolvedHome).some(({ id }) => id === candidate.id)) {
+                        cleaned.add(candidate.id);
+                        continue;
+                    }
+                    throw reconciliationBlocked(`resource ${candidate.id} changed or could not be cleaned: ${messageOf(error)}`);
+                }
+            }
+        }
+        throw reconciliationBlocked("Controller resources did not converge after bounded cleanup");
+    }
+    finally {
+        await releaseLock();
+    }
+}
+function assertCertainSnapshot(snapshot, resolvedHome) {
+    if (snapshot.scope !== "current"
+        || resolve(snapshot.currentHome) !== resolvedHome) {
+        throw reconciliationBlocked("the Controller inventory returned a mismatched Home or scope");
+    }
+    if (snapshot.warnings.length > 0) {
+        throw reconciliationBlocked(`the Controller inventory is uncertain: ${snapshot.warnings.join("; ")}`);
+    }
+}
+function controllerResources(snapshot, resolvedHome) {
+    return snapshot.resources.filter((resource) => (resource.yuiHome === resolvedHome
+        && (resource.kind === "controller" || isControllerArtifact(resource))));
+}
+function isControllerArtifact(resource) {
+    return resource.kind === "artifact"
+        && (resource.artifact?.artifactKind === "controller-discovery"
+            || resource.artifact?.artifactKind === "controller-socket");
+}
+function isCleanupEligible(resource) {
+    return resource.disposition === "safe" || resource.disposition === "review";
+}
+function resourceLabels(resources) {
+    return resources.map((resource) => `${resource.id}:${resource.reasonCode}`).join(", ");
+}
+function reconciliationBlocked(reason) {
+    return new Error(`Automatic Controller reconciliation is blocked because ${reason}. `
+        + "Run `yui controller status --verbose` and resolve only the reported current-Home resource before retrying.");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}