@zq-silk/yui 0.6.7 → 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/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/core/controllerClient.js

@@ -1,9 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { lstat, readFile } from "node:fs/promises";
 import { createConnection } from "node:net";
-import { join } from "node:path";
-import { CONTROLLER_DISCOVERY_PATH, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, encodeControllerRequest, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { CONTROLLER_DISCOVERY_PATH, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, encodeControllerRequest, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
 import { isControllerSocketPathForHome } from "./controllerEndpoint.js";
+import { readHomeFilesystemId } from "./homeFilesystemIdentity.js";
+import { findLiveControllerProcessForHome, inspectLiveControllerProcess } from "./controllerProcessIdentity.js";
 export class ControllerClientError extends Error {
     code;
     constructor(code, message) {
@@ -24,8 +26,11 @@ export async function readControllerDiscovery(home) {
             throw invalidDiscovery();
         }
         const value = JSON.parse(await readFile(discoveryPath, "utf8"));
-        const socketPath = discoverySocketPath(home, value);
-        return parseControllerDiscovery(value, socketPath);
+        const socketPath = discoverySocketPath(value);
+        return parseControllerDiscovery(value, {
+            homeFilesystemId: readHomeFilesystemId(home),
+            socketPath
+        });
     }
     catch (error) {
         if (error instanceof ControllerClientError)
@@ -36,13 +41,15 @@ export async function readControllerDiscovery(home) {
         throw invalidDiscovery();
     }
 }
-function discoverySocketPath(home, value) {
+function discoverySocketPath(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw invalidDiscovery();
     }
+    const homeId = Reflect.get(value, "homeId");
     const socketPath = Reflect.get(value, "socketPath");
-    if (typeof socketPath !== "string"
-        || !isControllerSocketPathForHome(home, socketPath)) {
+    if (typeof homeId !== "string"
+        || typeof socketPath !== "string"
+        || !isControllerSocketPathForHome(homeId, socketPath)) {
         throw invalidDiscovery();
     }
     return socketPath;
@@ -59,6 +66,10 @@ export async function callController(home, method, params = {}, options = {}) {
         requestLine = encodeControllerRequest({
             id,
             token: discovery.token,
+            protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+            homeId: discovery.homeId,
+            homeFilesystemId: discovery.homeFilesystemId,
+            controllerInstanceId: discovery.controllerInstanceId,
             method,
             params
         });
@@ -71,6 +82,129 @@ export async function callController(home, method, params = {}, options = {}) {
     }
     return exchange(discovery.socketPath, requestLine, id, timeoutMs);
 }
+/**
+ * One-generation transition used only by the documented `controller restart`
+ * upgrade path from the last released protocol (v3). Ordinary calls never
+ * accept or dispatch through this legacy shape.
+ */
+export async function stopPreviousFileTaskController(home, timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+        throw new TypeError("Controller timeout must be a positive integer.");
+    }
+    const discovery = await readPreviousControllerDiscovery(home);
+    const homeFilesystemId = readHomeFilesystemId(home);
+    if (inspectLiveControllerProcess(discovery.pid, homeFilesystemId, discovery.processStartIdentity) === undefined)
+        throw invalidDiscovery();
+    const id = randomUUID();
+    const requestLine = `${JSON.stringify({
+        id,
+        token: discovery.token,
+        method: "controller.stop",
+        params: { expectedPid: discovery.pid }
+    })}\n`;
+    const deadline = Date.now() + timeoutMs;
+    await exchange(discovery.socketPath, requestLine, id, timeoutMs);
+    while (inspectLiveControllerProcess(discovery.pid, homeFilesystemId, discovery.processStartIdentity) !== undefined) {
+        if (Date.now() >= deadline) {
+            throw new ControllerClientError("CONTROLLER_TIMEOUT", `Previous Controller did not stop within ${timeoutMs} ms.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    return Object.freeze({ pid: discovery.pid });
+}
+/**
+ * Explicit restart recovery for an exact Controller whose discovery record
+ * was lost. The signal is fenced by same UID, controller entrypoint, physical
+ * Home identity, PID, and process-start identity; an unprovable process is
+ * never touched.
+ */
+export async function stopOrphanedFileTaskController(home, timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+        throw new TypeError("Controller timeout must be a positive integer.");
+    }
+    const homeFilesystemId = readHomeFilesystemId(home);
+    const candidate = findLiveControllerProcessForHome(homeFilesystemId);
+    if (candidate === undefined)
+        return undefined;
+    if (inspectLiveControllerProcess(candidate.pid, homeFilesystemId, candidate.processStartIdentity) === undefined)
+        return undefined;
+    try {
+        process.kill(candidate.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ESRCH")
+            return undefined;
+        throw error;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (inspectLiveControllerProcess(candidate.pid, homeFilesystemId, candidate.processStartIdentity) !== undefined) {
+        if (Date.now() >= deadline) {
+            throw new ControllerClientError("CONTROLLER_TIMEOUT", `Orphaned Controller did not stop within ${timeoutMs} ms.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    return Object.freeze({ pid: candidate.pid });
+}
+async function readPreviousControllerDiscovery(home) {
+    const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
+    try {
+        const metadata = await lstat(discoveryPath);
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+        if (!metadata.isFile()
+            || (metadata.mode & 0o077) !== 0
+            || metadata.size > 4_096
+            || (uid !== undefined && metadata.uid !== uid))
+            throw invalidDiscovery();
+        const value = JSON.parse(await readFile(discoveryPath, "utf8"));
+        if (typeof value !== "object"
+            || value === null
+            || Array.isArray(value)
+            || !hasExactStringKeys(value, [
+                "pid",
+                "processStartIdentity",
+                "socketPath",
+                "token"
+            ]))
+            throw invalidDiscovery();
+        const record = value;
+        if (!Number.isSafeInteger(record.pid)
+            || record.pid < 1
+            || typeof record.processStartIdentity !== "string"
+            || !/^[0-9]{1,32}$/u.test(record.processStartIdentity)
+            || typeof record.socketPath !== "string"
+            || !isPreviousControllerSocketPath(record.socketPath)
+            || typeof record.token !== "string"
+            || !/^[a-f0-9]{64}$/u.test(record.token))
+            throw invalidDiscovery();
+        return Object.freeze({
+            pid: record.pid,
+            processStartIdentity: record.processStartIdentity,
+            socketPath: record.socketPath,
+            token: record.token
+        });
+    }
+    catch (error) {
+        if (error instanceof ControllerClientError)
+            throw error;
+        if (isNodeError(error) && error.code === "ENOENT") {
+            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", "Controller is not running.");
+        }
+        throw invalidDiscovery();
+    }
+}
+function hasExactStringKeys(value, expected) {
+    const keys = Reflect.ownKeys(value);
+    return keys.length === expected.length
+        && keys.every((key) => typeof key === "string")
+        && expected.every((key) => Object.hasOwn(value, key));
+}
+function isPreviousControllerSocketPath(candidate) {
+    if (!isAbsolute(candidate) || resolve(candidate) !== candidate)
+        return false;
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return basename(dirname(candidate)) === `yui-${uid}`
+        && /^[a-f0-9]{24}\.sock$/u.test(basename(candidate));
+}
 function exchange(socketPath, requestLine, expectedId, timeoutMs) {
     return new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);

package/dist/core/controllerEndpoint.js

@@ -1,37 +1,25 @@
-import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-const LINUX_UNIX_SOCKET_PATH_BUDGET = 100;
-export function controllerSocketPath(home) {
+import { join } from "node:path";
+import { validateHomeId } from "../repository/homeIdentity.js";
+export function controllerSocketPath(homeId) {
+    const identity = validateHomeId(homeId);
     const uid = typeof process.getuid === "function" ? process.getuid() : 0;
-    const socketName = `${controllerSocketIdentity(home)}.sock`;
-    const isolatedPath = join(tmpdir(), `yui-${uid}`, socketName);
-    if (process.platform !== "linux"
-        || Buffer.byteLength(isolatedPath) < LINUX_UNIX_SOCKET_PATH_BUDGET) {
-        return isolatedPath;
-    }
-    // Linux limits Unix-socket paths to a small fixed budget. Managed Task
-    // runtimes intentionally use isolated TMPDIR roots, which may themselves
-    // be nested deeply enough to exhaust that budget. Keep the Home/uid/name
-    // fence while using the compact system temporary root only for this
-    // exceptional path; clients follow the Home-owned discovery record.
-    return join("/tmp", `yui-${uid}`, socketName);
+    const socketName = `${identity}.sock`;
+    // Linux Unix-socket paths have a small fixed budget. A stable per-uid system
+    // root is both short and independent of each caller's isolated TMPDIR.
+    const root = process.platform === "linux" ? "/tmp" : tmpdir();
+    return join(root, `yui-${uid}`, socketName);
 }
 /**
- * A protected Home discovery record owns the Controller endpoint. Clients may
- * run with an isolated TMPDIR, so validate the published Home/uid identity
- * without recomputing the Controller process's temporary root.
+ * A protected Home discovery record owns the Controller endpoint. Linux uses
+ * one fixed root, so every caller validates the exact Home/uid endpoint
+ * independently of its own TMPDIR.
  */
-export function isControllerSocketPathForHome(home, candidate) {
-    if (!isAbsolute(candidate) || resolve(candidate) !== candidate)
+export function isControllerSocketPathForHome(homeId, candidate) {
+    try {
+        return candidate === controllerSocketPath(validateHomeId(homeId));
+    }
+    catch {
         return false;
-    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
-    return basename(dirname(candidate)) === `yui-${uid}`
-        && basename(candidate) === `${controllerSocketIdentity(home)}.sock`;
-}
-function controllerSocketIdentity(home) {
-    return createHash("sha256")
-        .update(resolve(home))
-        .digest("hex")
-        .slice(0, 24);
+    }
 }

package/dist/core/controllerProcessIdentity.js

@@ -0,0 +1,56 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
+import { readHomeFilesystemId, validateHomeFilesystemId } from "./homeFilesystemIdentity.js";
+/** Exact live-process fence used only at Controller startup and v3 handoff. */
+export function inspectLiveControllerProcess(pid, homeFilesystemId, expectedProcessStartIdentity) {
+    if (!Number.isSafeInteger(pid) || pid < 1 || pid === process.pid)
+        return undefined;
+    const expectedFilesystemId = validateHomeFilesystemId(homeFilesystemId);
+    try {
+        const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+        const status = readFileSync(`/proc/${pid}/status`, "utf8");
+        const processUid = /^Uid:\s+([0-9]+)/mu.exec(status)?.[1];
+        if (processUid === undefined || Number(processUid) !== uid)
+            return undefined;
+        const args = readFileSync(`/proc/${pid}/cmdline`)
+            .toString("utf8")
+            .split("\0")
+            .filter((argument) => argument.length > 0);
+        if (!args.some((argument) => /(?:^|\/)controllerMain\.js$/u.test(argument))) {
+            return undefined;
+        }
+        const environment = readFileSync(`/proc/${pid}/environ`)
+            .toString("utf8")
+            .split("\0");
+        const yuiHome = environment
+            .find((entry) => entry.startsWith("YUI_HOME="))
+            ?.slice("YUI_HOME=".length);
+        if (yuiHome === undefined || readHomeFilesystemId(yuiHome) !== expectedFilesystemId) {
+            return undefined;
+        }
+        const processStartIdentity = readLinuxProcessStartIdentity(pid);
+        if (processStartIdentity === undefined
+            || (expectedProcessStartIdentity !== undefined
+                && processStartIdentity !== expectedProcessStartIdentity))
+            return undefined;
+        return Object.freeze({ pid, processStartIdentity });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Finds an older/current Controller whose discovery record was lost. */
+export function findLiveControllerProcessForHome(homeFilesystemId) {
+    validateHomeFilesystemId(homeFilesystemId);
+    if (process.platform !== "linux")
+        return undefined;
+    const entries = readdirSync("/proc", { encoding: "utf8" });
+    for (const entry of entries) {
+        if (!/^[1-9][0-9]*$/u.test(entry))
+            continue;
+        const match = inspectLiveControllerProcess(Number(entry), homeFilesystemId);
+        if (match !== undefined)
+            return match;
+    }
+    return undefined;
+}

package/dist/core/controllerServer.js

@@ -6,6 +6,10 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONTROLLER_DISCOVERY_PATH, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, controllerFailure, encodeControllerResponse, isEmptyParams, parseControllerRequest } from "./protocol.js";
 import { controllerSocketPath } from "./controllerEndpoint.js";
+import { readHomeFilesystemId } from "./homeFilesystemIdentity.js";
+import { findLiveControllerProcessForHome } from "./controllerProcessIdentity.js";
+import { validateHomeId } from "../repository/homeIdentity.js";
+import { readCompatibleHomeIdentity } from "../storage/compatibleTaskStore.js";
 import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
@@ -32,7 +36,14 @@ export async function startControllerServer(home, dispatcher, beforeDiscoveryRem
 }
 async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemoval, options = {}) {
     const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
-    const socketPath = controllerSocketPath(home);
+    const homeId = validateHomeId(readCompatibleHomeIdentity(home).homeId);
+    const homeFilesystemId = readHomeFilesystemId(home);
+    await assertExistingDiscoveryReplaceable(discoveryPath);
+    if (findLiveControllerProcessForHome(homeFilesystemId) !== undefined) {
+        throw controllerAlreadyRunning();
+    }
+    const controllerInstanceId = randomBytes(16).toString("hex");
+    const socketPath = controllerSocketPath(homeId);
     const runtimeDirectory = dirname(discoveryPath);
     const socketDirectory = dirname(socketPath);
     await mkdir(runtimeDirectory, { recursive: true, mode: 0o700 });
@@ -66,7 +77,7 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
     // the live primary, so its startup identity is still truthful.
     let primaryIdentity = null;
     const netServer = createServer((socket) => {
-        receiveRequest(socket, token, dispatcher, () => closeRunning(), options.status, telemetry, handover, home, () => primaryIdentity);
+        receiveRequest(socket, token, dispatcher, () => closeRunning(), options.status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, () => primaryIdentity);
     });
     try {
         await listen(netServer, socketPath);
@@ -91,6 +102,11 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
         await chmod(socketPath, 0o600);
         const processStartIdentity = await readLinuxProcessStartIdentity(process.pid);
         const discovery = Object.freeze({
+            schemaVersion: 1,
+            protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+            homeId,
+            homeFilesystemId,
+            controllerInstanceId,
             pid: process.pid,
             processStartIdentity,
             socketPath,
@@ -125,7 +141,7 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
                 eventLoopDelay.stop();
                 await beforeDiscoveryRemoval?.();
                 await closeNetServer(netServer);
-                await removeOwnedDiscovery(discoveryPath, token);
+                await removeOwnedDiscovery(discoveryPath, token, controllerInstanceId);
                 if (options.domainIdentity !== undefined) {
                     // Keep the exact target fence while detached Role panes survive a
                     // Controller stop/restart. The owning test teardown or an expired
@@ -156,6 +172,54 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
         throw error;
     }
 }
+/**
+ * Fence an older Controller whose socket name was derived by another protocol.
+ * A dead or PID-reused owner is stale and may be replaced; an unverifiable
+ * live owner fails closed so an endpoint migration can never create dual
+ * writers for one durable Home.
+ */
+async function assertExistingDiscoveryReplaceable(discoveryPath) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(discoveryPath, "utf8"));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return;
+        throw unsafeExistingDiscovery(discoveryPath, error);
+    }
+    if (typeof value !== "object"
+        || value === null
+        || Array.isArray(value)
+        || !("pid" in value)
+        || !Number.isSafeInteger(value.pid)
+        || value.pid < 1) {
+        throw unsafeExistingDiscovery(discoveryPath);
+    }
+    const pid = value.pid;
+    if (!isProcessAlive(pid))
+        return;
+    if (!("processStartIdentity" in value)
+        || typeof value.processStartIdentity !== "string"
+        || !/^[0-9]{1,32}$/u.test(value.processStartIdentity)) {
+        throw unsafeExistingDiscovery(discoveryPath);
+    }
+    let currentIdentity;
+    try {
+        currentIdentity = await readLinuxProcessStartIdentity(pid);
+    }
+    catch (error) {
+        if (!isProcessAlive(pid))
+            return;
+        throw unsafeExistingDiscovery(discoveryPath, error);
+    }
+    if (currentIdentity === value.processStartIdentity) {
+        throw controllerAlreadyRunning();
+    }
+}
+function unsafeExistingDiscovery(discoveryPath, cause) {
+    return new Error(`Cannot safely replace existing Controller discovery: ${discoveryPath}.`, cause === undefined ? undefined : { cause });
+}
 async function writeDiscoveryAtomically(discoveryPath, discovery) {
     const temporaryPath = `${discoveryPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
     try {
@@ -171,7 +235,7 @@ async function writeDiscoveryAtomically(discoveryPath, discovery) {
         throw error;
     }
 }
-function receiveRequest(socket, token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity) {
+function receiveRequest(socket, token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity) {
     let buffer = Buffer.alloc(0);
     let complete = false;
     const fail = (code, message, id = "invalid") => {
@@ -200,7 +264,7 @@ function receiveRequest(socket, token, dispatcher, stop, status, telemetry, hand
             return;
         }
         complete = true;
-        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity);
+        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity);
     });
     socket.on("end", () => {
         if (!complete)
@@ -208,7 +272,7 @@ function receiveRequest(socket, token, dispatcher, stop, status, telemetry, hand
     });
     socket.on("error", () => undefined);
 }
-async function routeRequest(socket, line, token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity) {
+async function routeRequest(socket, line, token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity) {
     let request;
     try {
         request = parseControllerRequest(line);
@@ -224,6 +288,16 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
         sendResponse(socket, controllerFailure(request.id, "UNAUTHORIZED", "Controller authentication failed."));
         return;
     }
+    if (request.protocolVersion !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION) {
+        sendResponse(socket, controllerFailure(request.id, "CONTROLLER_PROTOCOL_MISMATCH", "Controller protocol version does not match the running Controller."));
+        return;
+    }
+    if (request.homeId !== homeId
+        || request.homeFilesystemId !== homeFilesystemId
+        || request.controllerInstanceId !== controllerInstanceId) {
+        sendResponse(socket, controllerFailure(request.id, "CONTROLLER_IDENTITY_MISMATCH", "Controller request identity does not match the running Controller."));
+        return;
+    }
     // Every authenticated request is observed once at the routing layer. The
     // observation completes when the response is handed to the socket, so a
     // later status snapshot sees prior built-in completions and the dispatcher
@@ -290,6 +364,9 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 cliRealpath: controllerCliRealpath(),
                 controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
                 controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+                homeId,
+                homeFilesystemId,
+                controllerInstanceId,
                 storageBackend: resolveTaskStoreBackendForHome(home, process.env),
                 workerEnabled: resolveStoreWorkerEnabledForHome(home, process.env),
                 mode: "primary",
@@ -322,6 +399,9 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 uptimeMs: Math.round(process.uptime() * 1000),
                 rssBytes: process.memoryUsage().rss,
                 protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+                homeId,
+                homeFilesystemId,
+                controllerInstanceId,
                 version: YUI_VERSION,
                 storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
                 aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
@@ -688,13 +768,15 @@ function closeNetServer(server) {
         server.close((error) => error === undefined ? resolve() : reject(error));
     });
 }
-async function removeOwnedDiscovery(path, token) {
+async function removeOwnedDiscovery(path, token, controllerInstanceId) {
     try {
         const value = JSON.parse(await readFile(path, "utf8"));
         if (typeof value === "object"
             && value !== null
             && "token" in value
-            && value.token === token) {
+            && value.token === token
+            && "controllerInstanceId" in value
+            && value.controllerInstanceId === controllerInstanceId) {
             await rm(path, { force: true });
         }
     }

package/dist/core/homeFilesystemIdentity.js

@@ -0,0 +1,24 @@
+import { statSync } from "node:fs";
+const HOME_FILESYSTEM_ID_PATTERN = /^[0-9]{1,32}:[0-9]{1,32}$/u;
+/**
+ * Runtime-only identity of the physical Home directory.
+ *
+ * Durable `homeId` names the logical Home. Device + inode distinguishes an
+ * accidental filesystem copy while allowing symlink aliases of the same
+ * directory to share one Controller. It is deliberately not persisted in the
+ * Home aggregate because replacing or copying the directory must change this
+ * runtime fence.
+ */
+export function readHomeFilesystemId(home) {
+    const metadata = statSync(home, { bigint: true });
+    if (!metadata.isDirectory()) {
+        throw new Error("YUI_HOME is not a directory.");
+    }
+    return `${metadata.dev}:${metadata.ino}`;
+}
+export function validateHomeFilesystemId(value) {
+    if (typeof value !== "string" || !HOME_FILESYSTEM_ID_PATTERN.test(value)) {
+        throw new Error("Home filesystem identity is invalid.");
+    }
+    return value;
+}

package/dist/core/protocol.js

@@ -1,7 +1,9 @@
+import { validateHomeId } from "../repository/homeIdentity.js";
+import { validateHomeFilesystemId } from "./homeFilesystemIdentity.js";
 export const MAX_CONTROLLER_MESSAGE_BYTES = 1_048_576;
 export const CONTROLLER_DISCOVERY_PATH = "runtime/controller.json";
 /** Bump when a running Controller cannot safely share one YUI_HOME with this CLI. */
-export const FILE_TASK_CONTROLLER_PROTOCOL_VERSION = 3;
+export const FILE_TASK_CONTROLLER_PROTOCOL_VERSION = 4;
 export class ControllerProtocolError extends Error {
     code;
     id;
@@ -18,12 +20,27 @@ export function parseControllerRequest(line) {
     }
     try {
         const value = JSON.parse(line);
-        if (!isRecord(value) || !hasExactKeys(value, ["id", "token", "method", "params"])) {
+        if (!isRecord(value) || !hasExactKeys(value, [
+            "id",
+            "token",
+            "protocolVersion",
+            "homeId",
+            "homeFilesystemId",
+            "controllerInstanceId",
+            "method",
+            "params"
+        ])) {
             throw new Error("shape");
         }
         if (!isIdentifier(value.id)
             || typeof value.token !== "string"
             || !/^[a-f0-9]{64}$/u.test(value.token)
+            || !Number.isSafeInteger(value.protocolVersion)
+            || value.protocolVersion < 1
+            || !isHomeId(value.homeId)
+            || !isHomeFilesystemId(value.homeFilesystemId)
+            || typeof value.controllerInstanceId !== "string"
+            || !/^[a-f0-9]{32}$/u.test(value.controllerInstanceId)
             || typeof value.method !== "string"
             || value.method.length > 128
             || !/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/u.test(value.method)
@@ -33,6 +50,10 @@ export function parseControllerRequest(line) {
         return Object.freeze({
             id: value.id,
             token: value.token,
+            protocolVersion: value.protocolVersion,
+            homeId: value.homeId,
+            homeFilesystemId: value.homeFilesystemId,
+            controllerInstanceId: value.controllerInstanceId,
             method: value.method,
             params: value.params
         });
@@ -96,19 +117,41 @@ export function controllerFailure(id, code, message) {
         error: Object.freeze({ code, message })
     });
 }
-export function parseControllerDiscovery(value, expectedSocketPath) {
+export function parseControllerDiscovery(value, expected) {
     if (!isRecord(value)
-        || !hasExactKeys(value, ["pid", "processStartIdentity", "socketPath", "token"])
+        || !hasExactKeys(value, [
+            "schemaVersion",
+            "protocolVersion",
+            "homeId",
+            "homeFilesystemId",
+            "controllerInstanceId",
+            "pid",
+            "processStartIdentity",
+            "socketPath",
+            "token"
+        ])
+        || value.schemaVersion !== 1
+        || value.protocolVersion !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION
+        || !isHomeId(value.homeId)
+        || value.homeFilesystemId !== expected.homeFilesystemId
+        || !isHomeFilesystemId(value.homeFilesystemId)
+        || typeof value.controllerInstanceId !== "string"
+        || !/^[a-f0-9]{32}$/u.test(value.controllerInstanceId)
         || !Number.isSafeInteger(value.pid)
         || value.pid < 1
         || typeof value.processStartIdentity !== "string"
         || !/^[0-9]{1,32}$/u.test(value.processStartIdentity)
-        || value.socketPath !== expectedSocketPath
+        || value.socketPath !== expected.socketPath
         || typeof value.token !== "string"
         || !/^[a-f0-9]{64}$/u.test(value.token)) {
         throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery is invalid.");
     }
     return Object.freeze({
+        schemaVersion: 1,
+        protocolVersion: value.protocolVersion,
+        homeId: value.homeId,
+        homeFilesystemId: value.homeFilesystemId,
+        controllerInstanceId: value.controllerInstanceId,
         pid: value.pid,
         processStartIdentity: value.processStartIdentity,
         socketPath: value.socketPath,
@@ -131,6 +174,26 @@ function isIdentifier(value) {
     return typeof value === "string"
         && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value);
 }
+function isHomeId(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        validateHomeId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isHomeFilesystemId(value) {
+    try {
+        validateHomeFilesystemId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/integration/gitIntegrationService.js

@@ -59,7 +59,7 @@ export class GitIntegrationService {
     environment;
     runtimeIsolation;
     #resourceRegistrarValue;
-    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home), jobPort) {
+    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home, store.getHomeIdentity().homeId), jobPort) {
         this.store = store;
         this.git = git;
         this.now = now;
@@ -883,14 +883,14 @@ function isNodeCode(error, code) {
         && "code" in error
         && error.code === code;
 }
-function defaultIntegrationRuntimeIsolation(home) {
+function defaultIntegrationRuntimeIsolation(home, homeId) {
     const controlHome = resolve(home);
     return new FileTaskRuntimeIsolation({
         runtimeRoot: integrationRuntimeRoot(),
         pathLayout: "compact",
         controlPlane: {
             yuiHome: controlHome,
-            controllerSocketPath: controllerSocketPath(controlHome),
+            controllerSocketPath: controllerSocketPath(homeId),
             tmuxNamespace: yuiTmuxServerName(controlHome),
             globalInstallPaths: [process.execPath]
         }

package/dist/repository/homeIdentity.js

@@ -1,6 +1,12 @@
 import { randomBytes } from "node:crypto";
 export const HOME_IDENTITY_PATTERN = /^home-[a-f0-9]{16}$/;
 const HOME_ENTROPY_BYTES = 16;
+export function validateHomeId(homeId) {
+    if (typeof homeId !== "string" || !HOME_IDENTITY_PATTERN.test(homeId)) {
+        throw new Error("Home identity id is invalid.");
+    }
+    return homeId;
+}
 export function generateHomeIdentity(now, source = () => randomBytes(HOME_ENTROPY_BYTES)) {
     const entropy = source().toString("hex");
     const homeId = `home-${randomBytes(8).toString("hex")}`;
@@ -15,9 +21,7 @@ export function validateHomeIdentity(identity) {
     if (identity.schemaVersion !== 1) {
         throw new Error("Home identity must use schemaVersion 1.");
     }
-    if (typeof identity.homeId !== "string" || !HOME_IDENTITY_PATTERN.test(identity.homeId)) {
-        throw new Error("Home identity id is invalid.");
-    }
+    validateHomeId(identity.homeId);
     if (typeof identity.entropy !== "string" || !/^[a-f0-9]{32}$/.test(identity.entropy)) {
         throw new Error("Home identity entropy is invalid.");
     }

package/dist/resources/liveReferences.js

@@ -12,6 +12,9 @@ import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { parseExactTaskRuntimeDescriptor } from "../runtime/exactControlPlane.js";
 import { readRuntimeIdentity, releasesDirectory, resolveActiveRelease } from "../release/runtimeRelease.js";
+import { isControllerSocketPathForHome } from "../core/controllerEndpoint.js";
+import { parseControllerDiscovery } from "../core/protocol.js";
+import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
 const executeFile = promisify(execFile);
 /**
  * Collect every live reference for the given paths. The scan is fail-closed:
@@ -481,7 +484,11 @@ export function readControllerDiscovery(home) {
     }
     let record;
     try {
-        record = JSON.parse(readFileSync(path, "utf8"));
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            throw new Error("controller.json is not an object");
+        }
+        record = value;
     }
     catch (error) {
         return Object.freeze({
@@ -537,9 +544,35 @@ export function readControllerDiscovery(home) {
             }
         });
     }
+    let discovery;
+    try {
+        const homeId = record.homeId;
+        const socketPath = record.socketPath;
+        if (typeof homeId !== "string"
+            || typeof socketPath !== "string"
+            || !isControllerSocketPathForHome(homeId, socketPath)) {
+            throw new Error("Controller endpoint identity is invalid.");
+        }
+        discovery = parseControllerDiscovery(record, {
+            homeFilesystemId: readHomeFilesystemId(home),
+            socketPath
+        });
+    }
+    catch (error) {
+        return Object.freeze({
+            protects: false,
+            token: "",
+            protectedPaths: Object.freeze([]),
+            diagnostic: {
+                source: "controller",
+                severity: "error",
+                message: `controller.json identity is invalid: ${error instanceof Error ? error.message : "unknown error"}`
+            }
+        });
+    }
     return Object.freeze({
         protects: true,
-        token: `controller:${record.pid}`,
+        token: `controller:${discovery.homeId}:${discovery.controllerInstanceId}:${record.pid}`,
         protectedPaths: Object.freeze([path])
     });
 }

package/dist/storage/compatibleTaskStore.js

@@ -3,8 +3,9 @@ import { join } from "node:path";
 import { StorageCompatibilityError, loadCompatibleSnapshot } from "./migration/index.js";
 import { createProductionStorageRegistry } from "./migration/productionRegistry.js";
 import { FileTaskStore, STORAGE_STATE_FILE, stateFileFingerprint, StorageRecordError, validateCurrentStorageStateSnapshot } from "./taskStore.js";
-import { SqliteTaskStore } from "./sqliteStore.js";
+import { readSqliteHomeIdentity, SqliteTaskStore } from "./sqliteStore.js";
 import { COMMITTED_DATABASE_FILENAME } from "./upgrade/sqliteStateMigration.js";
+import { validateHomeIdentity } from "../repository/homeIdentity.js";
 import { ensureStorageSchema, inspectStorageSchema, readStorageSchemaManifest, STORAGE_SCHEMA_FILE } from "./storageSchema.js";
 import { classifyHome } from "./upgrade/homeClassification.js";
 import { inspectSnapshotVersionState } from "./upgrade/homeMigrationTarget.js";
@@ -81,6 +82,40 @@ export function openCompatibleFileTaskStore(home, options = {}) {
             throw new StorageCompatibilityError(describeUnsupported(classification.classification));
     }
 }
+/**
+ * Read the one authoritative durable Home identity without creating runtime
+ * state. SQLite is opened read-only; file-backed Homes read only the immutable
+ * identity field, so an aggregate that requires offline migration can still
+ * authenticate its already-running Controller before the migration stops it.
+ */
+export function readCompatibleHomeIdentity(home, options = {}) {
+    const schema = inspectStorageSchema(home);
+    if (!options.forceStateSource
+        && (schema.status === "current" || schema.status === "unsupported")
+        && schema.currentLayoutVersion >= 7
+        && existsSync(join(home, COMMITTED_DATABASE_FILENAME))) {
+        return readSqliteHomeIdentity(home, COMMITTED_DATABASE_FILENAME);
+    }
+    if (!existsSync(join(home, STORAGE_STATE_FILE))) {
+        throw new StorageRecordError("Durable Home identity is missing.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(home, STORAGE_STATE_FILE), "utf8"));
+    }
+    catch {
+        throw new StorageRecordError("Durable Home identity state is invalid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new StorageRecordError("Durable Home identity state is invalid.");
+    }
+    try {
+        return validateHomeIdentity(parsed.homeIdentity);
+    }
+    catch {
+        throw new StorageRecordError("Durable Home identity is invalid.");
+    }
+}
 /**
  * The one-snapshot open for a Home whose manifest is already current. A single
  * fingerprint-fenced read of `state.json` supplies:

package/dist/storage/sqliteStore.js

@@ -43,7 +43,7 @@ import { mailboxTargetKey } from "../coordination/workMailbox.js";
 import { validatePendingTurnCompletion } from "../executor/turnCompletion.js";
 import { compareRuntimeSessionCandidates, projectRuntimeSessionCandidate } from "../runtime/runtimeSessionCandidate.js";
 import { validateReviewFinding } from "../review/reviewFinding.js";
-import { generateHomeIdentity } from "../repository/homeIdentity.js";
+import { generateHomeIdentity, validateHomeIdentity } from "../repository/homeIdentity.js";
 import { validateIntegrationQueueEntry } from "../integration/integrationQueueEntry.js";
 import { validDurableJobTransition, validateDurableJob } from "../job/durableJob.js";
 import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
@@ -53,6 +53,30 @@ import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_PENDING_WAKEUP_SCHEMA_VERSION, C
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
 import { migrateSqliteSchema, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
 import { inspectStorageSchema } from "./storageSchema.js";
+/** Read the immutable Home identity without opening a writable Store connection. */
+export function readSqliteHomeIdentity(rootDir, databaseFilename = "yui.db") {
+    const database = new Database(join(rootDir, databaseFilename), {
+        readonly: true,
+        fileMustExist: true
+    });
+    try {
+        const row = database.prepare("SELECT home_identity FROM home_meta WHERE id = 1").get();
+        if (typeof row?.home_identity !== "string") {
+            throw new StorageRecordError("SQLite Home identity is missing.");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(row.home_identity);
+        }
+        catch {
+            throw new StorageRecordError("SQLite Home identity is invalid JSON.");
+        }
+        return validateHomeIdentity(parsed);
+    }
+    finally {
+        database.close();
+    }
+}
 const DEFAULT_CONFIG = { schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION };
 function numericCompare(left, right) {
     return left.localeCompare(right, undefined, { numeric: true });

package/dist/storage/taskStore.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { validateConfiguredAgent } from "../agent/agent.js";
 import { validateCapabilityGrant } from "../grant/capabilityGrant.js";
@@ -1735,11 +1735,56 @@ export class StorageCancelledError extends Error {
     constructor(message) { super(message); this.name = "StorageCancelledError"; }
 }
 export function resolveYuiHome(env) {
-    return env.YUI_HOME === undefined || env.YUI_HOME.length === 0
+    const requested = env.YUI_HOME === undefined || env.YUI_HOME.length === 0
         ? join(homedir(), ".yui")
         : resolve(env.YUI_HOME);
+    return canonicalizeYuiHome(requested);
 }
 export function ensureYuiHome(rootDir) { mkdirSync(rootDir, { recursive: true, mode: 0o700 }); }
+/**
+ * YUI_HOME is a runtime identity, not only a storage path. Resolve every
+ * existing symlink component before Controller/tmux namespaces or exact
+ * descriptors derive identity from it. A Home may not exist before `setup`,
+ * so retain proven-missing trailing components below the longest existing
+ * physical ancestor. Existing-but-unresolvable paths fail closed.
+ */
+function canonicalizeYuiHome(value) {
+    const absolute = resolve(value);
+    let current = absolute;
+    const trailing = [];
+    for (;;) {
+        try {
+            const physical = realpathSync(current);
+            return trailing.length === 0 ? physical : join(physical, ...trailing);
+        }
+        catch (realpathError) {
+            if (!isErrno(realpathError, "ENOENT")) {
+                throw unstableYuiHome(absolute, realpathError);
+            }
+            try {
+                lstatSync(current);
+            }
+            catch (lstatError) {
+                if (!isErrno(lstatError, "ENOENT")) {
+                    throw unstableYuiHome(absolute, lstatError);
+                }
+                const parent = dirname(current);
+                if (parent === current)
+                    return absolute;
+                trailing.unshift(basename(current));
+                current = parent;
+                continue;
+            }
+            throw unstableYuiHome(absolute, realpathError);
+        }
+    }
+}
+function unstableYuiHome(path, cause) {
+    return new Error(`YUI_HOME cannot be resolved to a stable physical path: ${path}.`, { cause });
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
 function emptyState() {
     return {
         schemaVersion: CURRENT_STORAGE_STATE_SCHEMA_VERSION,

package/package.json

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