@zq-silk/yui 0.6.6 → 0.6.7

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/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);
+}

package/dist/core/controllerServer.js

@@ -763,7 +763,7 @@ function safeErrorMessage(message) {
         .slice(0, 512);
     return safe.length === 0 ? undefined : safe;
 }
-async function acquireHomeLifecycleLock(home) {
+export async function acquireHomeLifecycleLock(home, options = {}) {
     const lockPath = homeLifecycleLockPath(home);
     await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
     const owner = Object.freeze({
@@ -796,6 +796,12 @@ async function acquireHomeLifecycleLock(home) {
         if (isProcessAlive(existing.pid)) {
             throw new Error(`Another Yui home lifecycle operation is already running (${ownerDescription}): ${lockPath}`);
         }
+        if (options.removeStaleOwner === true) {
+            // The token comparison in releaseHomeLifecycleLock is the CAS fence: a
+            // replacement owner that appeared after the read is never removed.
+            await releaseHomeLifecycleLock(lockPath, existing);
+            continue;
+        }
         throw new Error(`A previous Yui home lifecycle operation left a stale lock `
             + `(${ownerDescription}): ${lockPath}. `
             + "If no Controller startup or development reset is running, "

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,