@zq-silk/yui 0.6.7 → 0.6.9

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/commands/taskCommands.js

@@ -1802,7 +1802,7 @@ function dispatchWork(args, store, options) {
         if (item.assignee === undefined) {
             throw usageError(`Work Item has no Task Role assignee: ${item.id}. `
                 + `The Task Leader must run "yui task work update ${item.id} running", `
-                + "then execute it directly or create a native subagent in the Leader conversation.");
+                + "then execute it directly or create native subagents in the Leader Session.");
         }
         if (expanding && taskActor(options, task.id) !== "leader") {
             throw usageError("Only the Task Leader may expand a running ExecutionGroup.");

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/fileSchedulerStoreAdapter.js

@@ -26,7 +26,8 @@ import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { RUNTIME_CLEANUP_REQUIRED_REASON, RUNTIME_LAUNCH_RESERVED_REASON, RUNTIME_LIFECYCLE_OWNER, hasRuntimeCleanupObligation, hasRuntimeLifecycleWork, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
-import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationTaskEventPayload } from "../runtime/runtimeObservation.js";
+import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationRunFenceMatches, runtimeObservationTaskEventPayload } from "../runtime/runtimeObservation.js";
+import { projectRuntimeTaskEvents } from "../runtime/runtimeProjection.js";
 /** Maps the authoritative FileTaskStore records to the scheduler's narrow port. */
 export class FileSchedulerStoreAdapter {
     store;
@@ -80,6 +81,13 @@ export class FileSchedulerStoreAdapter {
                 const classification = this.classifyRuntimeTurnCompleted(completed);
                 if (classification !== "apply")
                     return classification;
+                if (this.runtimeTurnHasActiveNativeSubagents(input)) {
+                    // This is an intermediate provider Turn boundary, not the end of the
+                    // durable Yui Run. The provider will deliver child completion
+                    // notifications as later native Turns in the same Run generation.
+                    outcome = this.validateCanonicalRunObservation(input, now);
+                    break;
+                }
                 const result = this.observeRuntimeTurnCompleted(completed, now);
                 outcome = result.disposition === "obsolete" ? "obsolete" : "applied";
                 break;
@@ -180,6 +188,14 @@ export class FileSchedulerStoreAdapter {
             return "applied";
         });
     }
+    runtimeTurnHasActiveNativeSubagents(input) {
+        const taskId = input.fence.taskId;
+        const run = this.store.getAgentRun(taskId, input.fence.runId);
+        if (run === null)
+            return false;
+        const projection = projectRuntimeTaskEvents(input.fence, run.createdAt, this.store.listEvents(taskId));
+        return Object.values(projection.operations).some(({ kind }) => kind === "subagent");
+    }
     validateCanonicalSessionObservation(input, now) {
         return this.store.transaction((store) => {
             const run = store.getAgentRun(input.fence.taskId, input.fence.runId);
@@ -1249,7 +1265,8 @@ export class FileSchedulerStoreAdapter {
         });
     }
     /**
-     * Fast hook path: durably records the native Turn boundary and a two-second
+     * Fast hook path: validates the native Turn boundary before it is either
+     * retained as an intermediate child wait or given a two-second workflow
      * closure deadline. It never performs tmux, workspace, or Controller I/O.
      */
     classifyRuntimeTurnCompleted(input) {
@@ -2808,8 +2825,13 @@ function runtimeObservationTelemetryEntry(input) {
 function compactedRuntimeObservationIds(events, incoming) {
     const existing = events.flatMap((event) => {
         const observation = runtimeObservationFromTaskEvent(event);
+        const matches = incoming.kind.startsWith("operation.")
+            ? observation !== null
+                && runtimeObservationRunFenceMatches(observation.fence, incoming.fence)
+            : observation !== null
+                && runtimeObservationFenceMatches(observation.fence, incoming.fence);
         return observation !== null
-            && runtimeObservationFenceMatches(observation.fence, incoming.fence)
+            && matches
             ? [{ event, observation }]
             : [];
     });
@@ -2838,7 +2860,8 @@ function compactedRuntimeObservationIds(events, incoming) {
                 && observation.payload.sourceId === incoming.payload.sourceId;
         }
         if (["turn.completed", "turn.failed", "turn.cancelled"].includes(incoming.kind)) {
-            return observation.kind.startsWith("operation.")
+            return (observation.kind.startsWith("operation.")
+                && observation.payload.operation !== "subagent")
                 || observation.kind === "turn.waiting"
                 || observation.kind === "turn.completed"
                 || observation.kind === "turn.failed"

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