@zq-silk/yui 0.6.6 → 0.6.8

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 });
         }
     }
@@ -763,7 +845,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 +878,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/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);
 }