@zq-silk/yui 1.0.1 → 1.1.2

package/dist/controller/handoverCandidate.js

@@ -14,11 +14,11 @@
  */
 import { fileURLToPath } from "node:url";
 import { buildRuntimeIdentityReceipt } from "../core/controllerServer.js";
+import { currentProcessStartIdentity } from "../core/fileLockOwner.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
 import { detectRunningRelease, isOwnerLive, readActiveReleasePointer, readHandoverFence, removeCandidateDiscovery, removeHandoverFence, writeCandidateDiscovery, writeHandoverFence, writeHandoverReceipt, writeRuntimeIdentity } from "../release/runtimeRelease.js";
 import { startFileTaskControllerRuntime } from "./runtime.js";
-import { readLinuxProcessStartIdentity } from "./domainIdentity.js";
 import { RELEASE_HANDOVER_OLD_OWNER_GRACE_MS } from "../runtime/runtimeDeadlines.js";
 export const CONTROLLER_CANDIDATE_ENV = "YUI_CONTROLLER_CANDIDATE";
 export const CONTROLLER_HANDOVER_ID_ENV = "YUI_CONTROLLER_HANDOVER_ID";
@@ -53,10 +53,7 @@ export async function runHandoverCandidate(home, handoverId, options = {}) {
     const dualOwnerGraceMs = options.dualOwnerGraceMs ?? DEFAULT_DUAL_OWNER_GRACE_MS;
     const now = options.now ?? (() => new Date());
     const release = detectRunningRelease(fileURLToPath(import.meta.url));
-    const startIdentity = readLinuxProcessStartIdentity(process.pid);
-    if (startIdentity === undefined) {
-        throw new Error(`Cannot read process start identity for handover candidate PID ${process.pid}.`);
-    }
+    const startIdentity = currentProcessStartIdentity();
     const fence = readHandoverFence(home);
     if (fence === null || fence.handoverId !== handoverId) {
         throw new Error(`Handover fence for ${handoverId} is missing or does not match; aborting candidate.`);

package/dist/controller/jobSupervisor.js

@@ -19,7 +19,7 @@ import { cancelQueuedDurableJob, completeDurableJob, isDurableJobTerminal, markD
 import { recordOperationEvidence } from "../kernel/operationFacts.js";
 import { wakeReason } from "../scheduler/wakeReason.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
-import { readLinuxProcessStartIdentity } from "./domainIdentity.js";
+import { readProcessStartIdentity } from "../core/fileLockOwner.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
 const HEARTBEAT_STALE_MS = 2 * 60_000;
 const SIGKILL_GRACE_MS = 30_000;
@@ -401,7 +401,7 @@ export function createLinuxProcessPort() {
         spawnJobRunner(specPath) {
             const child = spawn(process.execPath, [fileURLToPath(new URL("../job/jobRunner.js", import.meta.url)), specPath], { detached: true, stdio: "ignore" });
             child.unref();
-            const startIdentity = readLinuxProcessStartIdentity(child.pid);
+            const startIdentity = readProcessStartIdentity(child.pid);
             return {
                 pid: child.pid,
                 startIdentity,
@@ -416,7 +416,7 @@ export function createLinuxProcessPort() {
             };
         },
         processStartIdentity(pid) {
-            return readLinuxProcessStartIdentity(pid);
+            return readProcessStartIdentity(pid);
         },
         isProcessAlive(pid) {
             try {
@@ -428,7 +428,7 @@ export function createLinuxProcessPort() {
             }
         },
         signalIfOwned(pid, startIdentity, signal) {
-            if (readLinuxProcessStartIdentity(pid) !== startIdentity)
+            if (readProcessStartIdentity(pid) !== startIdentity)
                 return;
             try {
                 process.kill(pid, signal);

package/dist/controller/resourceCleanupLinux.js

@@ -1,5 +1,7 @@
 import { lstatSync, readFileSync, unlinkSync } from "node:fs";
+import { createConnection } from "node:net";
 import { basename, dirname, join, resolve } from "node:path";
+import { readProcessStartIdentity } from "../core/fileLockOwner.js";
 import { NodeCommandExecutor } from "../tmux/commandExecutor.js";
 import { TmuxManager } from "../tmux/tmuxManager.js";
 import { tmuxSocketDirectory, tmuxSocketEnvironment } from "../tmux/tmuxSocketEndpoint.js";
@@ -17,7 +19,7 @@ export async function cleanControllerResource(resource, options = {}) {
     const ports = options.ports ?? linuxCleanupPorts(environment, options.tmuxBin ?? "tmux");
     const cleanup = async () => {
         if (resource.artifact !== undefined) {
-            cleanArtifact(resource, ports, environment);
+            await cleanArtifact(resource, ports, environment);
             return;
         }
         if (resource.kind === "agent-session") {
@@ -88,7 +90,7 @@ function assertEphemeralDomainFence(resource) {
         throw new Error(`Resource changed since scan: ${resource.id}.`);
     }
 }
-function cleanArtifact(resource, ports, environment) {
+async function cleanArtifact(resource, ports, environment) {
     const artifact = resource.artifact;
     if (artifact === undefined)
         throw new Error(`Artifact is unavailable: ${resource.id}.`);
@@ -116,9 +118,15 @@ function cleanArtifact(resource, ports, environment) {
         return;
     }
     if (artifact.artifactKind.endsWith("-socket")
-        && ports.socketActive(artifact.path)) {
+        && await ports.socketActive(artifact.path)) {
         throw new Error(`Resource socket is active: ${artifact.path}.`);
     }
+    // The listener probe is asynchronous on macOS. A concurrent owner may
+    // replace the path while it runs; the pre-probe fingerprint no longer
+    // authorizes unlinking that new socket.
+    if (ports.artifactFingerprint(artifact.path) !== artifact.fingerprint) {
+        throw new Error(`Resource changed since scan: ${resource.id}.`);
+    }
     ports.removeArtifact(artifact.path);
 }
 function assertProcessIdentities(resource, ports) {
@@ -153,7 +161,7 @@ async function waitForProcesses(resource, ports, graceMs, pollMs) {
 }
 function linuxCleanupPorts(environment, tmuxBin) {
     return {
-        processStartIdentity: readProcessStartIdentity,
+        processStartIdentity: readOwnedProcessStartIdentity,
         signal: (pid, signal) => process.kill(pid, signal),
         sleep: (milliseconds) => new Promise((resolveSleep) => {
             setTimeout(resolveSleep, milliseconds);
@@ -166,7 +174,8 @@ function linuxCleanupPorts(environment, tmuxBin) {
                 return undefined;
             }
         },
-        socketActive: unixSocketIsActive,
+        socketActive: process.platform === "darwin"
+            ? darwinUnixSocketIsActive : unixSocketIsActive,
         removeArtifact: (path) => unlinkSync(path),
         inspectTmuxServerPanes: async (resource) => {
             const manager = tmuxManagerForResource(resource, environment, tmuxBin);
@@ -218,20 +227,8 @@ function tmuxManagerForResource(resource, environment, tmuxBin) {
         })
     }, { yuiHome: home });
 }
-function readProcessStartIdentity(pid) {
-    try {
-        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-        const closing = stat.lastIndexOf(")");
-        if (closing < 0)
-            return undefined;
-        const identity = stat.slice(closing + 1).trim().split(/\s+/u)[19];
-        return identity !== undefined && /^[0-9]{1,32}$/u.test(identity)
-            ? identity
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
+function readOwnedProcessStartIdentity(pid) {
+    return readProcessStartIdentity(pid);
 }
 function unixSocketIsActive(expectedPath) {
     try {
@@ -243,6 +240,25 @@ function unixSocketIsActive(expectedPath) {
         return true;
     }
 }
+function darwinUnixSocketIsActive(path) {
+    return new Promise((resolveActive) => {
+        const socket = createConnection(path);
+        let settled = false;
+        const finish = (active) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolveActive(active);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", (error) => {
+            finish(error.code !== "ENOENT" && error.code !== "ECONNREFUSED");
+        });
+        socket.once("close", () => finish(true));
+        socket.setTimeout(1_000, () => finish(true));
+    });
+}
 function assertOwnedArtifactPath(resource, environment) {
     const artifact = resource.artifact;
     if (artifact === undefined)

package/dist/controller/resourceInventoryLinux.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { createConnection } from "node:net";
 import { basename, join, resolve } from "node:path";
+import { processOwnerIsLive, readProcessStartIdentity } from "../core/fileLockOwner.js";
 import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
@@ -12,16 +14,31 @@ import { CONTROLLER_DISCOVERY_PATH } from "../core/protocol.js";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
 import { buildControllerResourceInventory, runtimeRoleProtectsDomain } from "./resourceInventory.js";
-import { CONTROLLER_DOMAIN_PATH, EPHEMERAL_DOMAIN_GRACE_MS, ephemeralDomainFingerprint, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "./domainIdentity.js";
+import { CONTROLLER_DOMAIN_PATH, EPHEMERAL_DOMAIN_GRACE_MS, ephemeralDomainFingerprint, readEphemeralDomainIdentity } from "./domainIdentity.js";
 const LINUX_PROCESS_SCAN_BATCH_SIZE = 64;
 export const INVENTORY_EVENT_LOOP_RUN_BUDGET_MS = 25;
 export async function scanControllerResourceInventory(options) {
+    if (options.scope === "all" && process.platform !== "linux") {
+        throw new Error("Controller inventory --all requires cross-Home process discovery, which is unavailable on this platform. Use the current-Home scope.");
+    }
     const currentHome = resolve(options.currentHome);
     const environment = options.environment ?? process.env;
     const observedAt = (options.now ?? (() => new Date()))();
     const warnings = [];
-    const activeSockets = readActiveUnixSocketPaths(warnings);
-    const processes = normalizePhysicalHomeAliases((await listLinuxProcesses(warnings)).filter(({ pid }) => pid !== process.pid), currentHome);
+    const tmuxDirectory = tmuxSocketDirectory(environment);
+    // /proc-backed process and socket enumeration is Linux-only. On macOS the
+    // current Controller is synthesized from its exact discovery identity.
+    let activeSockets;
+    let processes;
+    if (process.platform === "linux") {
+        activeSockets = readActiveUnixSocketPaths(warnings);
+        processes = normalizePhysicalHomeAliases((await listLinuxProcesses(warnings)).filter(({ pid }) => pid !== process.pid), currentHome);
+    }
+    else {
+        const observed = await observeCurrentController(currentHome, tmuxDirectory);
+        activeSockets = observed.activeSockets;
+        processes = observed.process;
+    }
     const homes = new Set([currentHome]);
     if (options.scope === "all") {
         for (const process of processes) {
@@ -29,7 +46,6 @@ export async function scanControllerResourceInventory(options) {
                 homes.add(process.yuiHome);
         }
     }
-    const tmuxDirectory = tmuxSocketDirectory(environment);
     const listTmuxSocketArtifacts = options.listTmuxSocketArtifacts
         ?? listSharedTmuxSocketArtifacts;
     // scope=current owns exactly one YUI_HOME, so only its exact tmux server
@@ -86,7 +102,7 @@ export async function scanControllerResourceInventory(options) {
                 // otherwise its own expired-domain pass would delete controller.json
                 // and strand the still-running server without a callable endpoint.
                 || (discovery.pid === process.pid
-                    && readLinuxProcessStartIdentity(process.pid) === discovery.processStartIdentity));
+                    && readProcessStartIdentity(process.pid) === discovery.processStartIdentity));
         const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
         const expectedControllerSocketPath = state.homeId === undefined
             ? undefined
@@ -179,6 +195,78 @@ export function classifyRuntimeProcess(args, command) {
         return "agent";
     return "other";
 }
+/**
+ * Non-Linux inventory observations. There is no /proc to enumerate, so the
+ * current Home's Controller is reconstructed from its discovery record when
+ * its process-generation identity is still live, and listening Unix sockets are proven with
+ * a direct connection (the equivalent of reading /proc/net/unix). Only the
+ * current Home is observable without /proc; scope=all is rejected at entry.
+ */
+async function observeCurrentController(currentHome, tmuxDirectory) {
+    const activeSockets = new Set();
+    for (const path of listProbeableSocketPaths(tmuxDirectory)) {
+        if (await unixSocketListens(path))
+            activeSockets.add(path);
+    }
+    let discovery;
+    try {
+        discovery = await readControllerDiscovery(currentHome);
+    }
+    catch {
+        return { activeSockets, process: [] };
+    }
+    if (await unixSocketListens(discovery.socketPath)) {
+        activeSockets.add(discovery.socketPath);
+    }
+    if (!processOwnerIsLive(discovery.pid, discovery.processStartIdentity)) {
+        return { activeSockets, process: [] };
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    const processFact = {
+        pid: discovery.pid,
+        ppid: 1,
+        uid,
+        startIdentity: discovery.processStartIdentity,
+        yuiHome: currentHome,
+        ...(discovery.homeFilesystemId === undefined
+            ? {}
+            : { homeFilesystemId: discovery.homeFilesystemId }),
+        kind: "controller",
+        command: "yui-controller",
+        args: [],
+        rssBytes: 0,
+        cpuTimeMs: 0,
+        ageMs: 0
+    };
+    return { activeSockets, process: [processFact] };
+}
+function listProbeableSocketPaths(tmuxDirectory) {
+    try {
+        return readdirSync(tmuxDirectory, { encoding: "utf8" })
+            .filter((entry) => /^yui-[a-f0-9]{24}$/u.test(entry))
+            .map((entry) => join(tmuxDirectory, entry));
+    }
+    catch {
+        return [];
+    }
+}
+function unixSocketListens(path) {
+    return new Promise((resolveProbe) => {
+        const socket = createConnection(path);
+        let settled = false;
+        const finish = (listens) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolveProbe(listens);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        const timer = setTimeout(() => finish(false), 200);
+        timer.unref();
+    });
+}
 async function listLinuxProcesses(warnings) {
     const uid = typeof process.getuid === "function" ? process.getuid() : 0;
     const clockTicks = readClockTicks();
@@ -497,8 +585,8 @@ function inspectRuntimeDomain(home, processes, roles, storageStatus, now) {
             graceMs: EPHEMERAL_DOMAIN_GRACE_MS
         };
     }
-    const hostStartIdentity = readLinuxProcessStartIdentity(identity.hostPid);
-    const hostPathExists = existsSync(`/proc/${identity.hostPid}`);
+    const hostStartIdentity = readProcessStartIdentity(identity.hostPid);
+    const hostPathExists = processExists(identity.hostPid);
     const hostActive = hostStartIdentity === identity.hostProcessStartIdentity;
     const storageSafe = storageStatus === "current";
     if (hostActive) {
@@ -607,6 +695,15 @@ function inspectRuntimeDomain(home, processes, roles, storageStatus, now) {
         graceMs: EPHEMERAL_DOMAIN_GRACE_MS
     };
 }
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
 function loadHomeState(home, warnings, options) {
     const schema = (options.inspectStorage ?? inspectStorageSchema)(home);
     if (schema.status !== "current") {

package/dist/controller/runtime.js

@@ -27,7 +27,6 @@ import { managedRuntimeRoot } from "../storage/homeLayout.js";
 import { SqliteTaskStore } from "../storage/sqliteStore.js";
 import { AsyncTaskStoreClient, resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 import { SurfaceContributions } from "../surface/surfaceContributions.js";
-import { taskOwnsManagedWorkspace } from "../task/task.js";
 import { openSchedulerTelemetry } from "../telemetry/telemetryWiring.js";
 import { NodeCommandExecutor } from "../tmux/commandExecutor.js";
 import { TmuxManager, yuiTmuxServerName } from "../tmux/tmuxManager.js";
@@ -817,13 +816,10 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             const planningDraft = request.scope === "task"
                 && activeRun?.purpose === "planning"
                 && task?.status === "draft";
-            // A Task activated with an empty environment plan owns no managed
-            // workspace, so there is nothing to prove ready. Every Task that does own
-            // one keeps the full ownership fence.
+            // Draft planning precedes workspace adoption; active Tasks need ownership.
             if (request.scope === "task"
                 && task !== null
-                && !planningDraft
-                && taskOwnsManagedWorkspace(task)) {
+                && !planningDraft) {
                 const taskWorkspace = store.getTaskWorkspace(task.id);
                 if (!isTaskOwnedWorkspace(taskWorkspace, task.id, task.cwd, task.projectBindings.map(({ projectId, directory }) => ({ projectId, directory })))) {
                     throw new Error(`Task workspace is not ready: ${task.id}.`);
@@ -849,16 +845,11 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 ? activeRun?.workspace
                     ?? currentDesiredManagedWorkspace(store, request.taskId, request.roleName)
                 : undefined;
-            // Distinguish "this Task owns no workspace by design" from "the
-            // authoritative workspace is missing". Only the former may launch without
-            // one. Two cases qualify: an empty plan binding no Project, and a Draft
-            // planning conversation, which may bind a Project but has not activated, so
-            // no worktree exists or is owed. Without the planning term a Project-bound
-            // Draft fails closed on a workspace activation was never asked to create.
+            // Only Draft planning may launch without an adopted delivery workspace.
             const workspaceFree = request.scope === "task"
                 && managedWorkspace === undefined
                 && task !== null
-                && (planningDraft || !taskOwnsManagedWorkspace(task));
+                && planningDraft;
             const sessions = request.scope === "task"
                 ? store.getTaskRoleSessionSet(request.taskId, request.roleName)
                 : store.getGlobalRoleSessionSet(request.roleName);

package/dist/controller/runtimeLaunchCoordinator.js

@@ -48,10 +48,8 @@ export class RuntimeLaunchCoordinator {
         let isolation;
         if (request.owner.scope === "task" && this.options.runtimeIsolation !== undefined) {
             const workspace = request.managedWorkspace;
-            // A Task that legitimately owns no workspace has nothing to isolate: an
-            // empty environment plan over no bound Project (S27). Skipping isolation
-            // here is what lets such a Leader launch at all; a *missing*
-            // authoritative workspace still fails closed below.
+            // Draft planning has no delivery workspace to isolate. Active Task
+            // launches require the exact authoritative ManagedWorkspace below.
             if (request.workspaceFree === true) {
                 if (workspace !== undefined) {
                     throw new Error("A workspace-free Task launch cannot carry a ManagedWorkspace.");

package/dist/controller/sessionOwnerReconciliation.js

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { processOwnerIsLive } from "../core/fileLockOwner.js";
 import { createTaskEvent } from "../event/taskEvent.js";
 import { createGlobalRoleMessage } from "../message/message.js";
-import { createSessionOwnerIdentity, isLinuxProcessLive, listOwnedProcessTree, readLinuxProcessIdentity, reconcileSessionOwners, terminateSessionOwners } from "../runtime/index.js";
+import { createSessionOwnerIdentity, isLinuxProcessLive, listOwnedProcessTree, readLinuxProcessIdentity, readProcessIdentity, reconcileSessionOwners, terminateSessionOwners } from "../runtime/index.js";
 import { sessionOwnerProcessKey } from "../runtime/sessionOwnerIdentity.js";
 import { AGENT_HOST_CONTROL_PROTOCOL, sendAgentHostCancelControl } from "../runtime/agentHost.js";
 import { settleProviderTurn, cancelQuiescentProviderInput, clearProviderGoal } from "../runtime/providerRuntimeIdentity.js";
@@ -45,7 +46,7 @@ export class SessionOwnerReconciliation {
      */
     recordHostOwner(input) {
         const observed = input.panePid !== undefined
-            ? readLinuxProcessIdentity(input.panePid)
+            ? readOwnerProcessIdentity(input.panePid)
             : undefined;
         const root = observed === undefined
             ? undefined
@@ -131,7 +132,10 @@ export class SessionOwnerReconciliation {
                 at: new Date() });
             throw error;
         }
-        const result = await terminateSessionOwners(owner, records, this.#terminationPorts(), options);
+        const result = await terminateSessionOwners(owner, records, this.#terminationPorts(), {
+            ...options,
+            requireProcessRecord: process.platform === "darwin"
+        });
         if (result.outcome === "stop-confirmed") {
             // A signalled Host exits into a retained tmux pane. Explicit release
             // removes that window too, after physical exit proof, not on observation.
@@ -158,15 +162,8 @@ export class SessionOwnerReconciliation {
                 }
                 return this.#tmux.probeRoleStatus(hostId, target.roleName) === "exited";
             },
-            processIdentity: readLinuxProcessIdentity,
-            procEntryExists: (pid) => {
-                try {
-                    return existsSync(`/proc/${pid}`);
-                }
-                catch {
-                    return false;
-                }
-            },
+            processIdentity: readOwnerProcessIdentity,
+            procEntryExists: processEntryExists,
             signalProcess: (pid, signal) => process.kill(pid, signal),
             sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
             emit: (event) => this.#recordTerminationEvent(event),
@@ -395,8 +392,10 @@ export function durableSessionFacts(store) {
 /** /proc observation for one owner record; undefined is a verification gap. */
 export function observeSessionOwnerPhysical(record) {
     const { pid, startIdentity } = record.providerRoot;
-    const current = readLinuxProcessIdentity(pid);
+    const current = readOwnerProcessIdentity(pid);
     if (current === undefined) {
+        if (processEntryExists(pid))
+            return undefined;
         return {
             alive: false,
             identityConflict: false,
@@ -432,7 +431,8 @@ export function observeSessionOwnerPhysical(record) {
             childCount: 0
         };
     }
-    const tree = listOwnedProcessTree(pid, current.processGroupId);
+    const tree = process.platform === "linux"
+        ? listOwnedProcessTree(pid, current.processGroupId) : [];
     return {
         alive: true,
         identityConflict: false,
@@ -440,9 +440,30 @@ export function observeSessionOwnerPhysical(record) {
         startIdentity,
         rssBytes: current.rssBytes,
         ageMs: 0,
-        childCount: Math.max(0, tree.length - 1)
+        childCount: process.platform === "linux" ? Math.max(0, tree.length - 1) : 0
     };
 }
+function readOwnerProcessIdentity(pid) {
+    if (process.platform === "linux")
+        return readLinuxProcessIdentity(pid);
+    try {
+        return readProcessIdentity(pid);
+    }
+    catch {
+        return undefined;
+    }
+}
+function processEntryExists(pid) {
+    if (process.platform === "linux")
+        return existsSync(`/proc/${pid}`);
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
 /** Reads the latest termination outcome recorded for one Role. */
 export function lastSessionTerminationOutcome(store, taskId, roleName) {
     if (taskId === undefined)
@@ -459,7 +480,10 @@ export function lastSessionTerminationOutcome(store, taskId, roleName) {
 }
 /** True when one owner record's Provider root is still the exact live process. */
 export function ownerRootIsLive(record) {
-    return isLinuxProcessLive(record.providerRoot.pid, record.providerRoot.startIdentity);
+    const { pid, startIdentity } = record.providerRoot;
+    return process.platform === "linux"
+        ? isLinuxProcessLive(pid, startIdentity)
+        : processOwnerIsLive(pid, startIdentity);
 }
 /** Exact tmux target for one owner, for reports and diagnostics. */
 export function ownerTmuxTarget(home, owner) {

package/dist/core/controllerClient.js

@@ -8,8 +8,8 @@ import { readHomeFilesystemId } from "./homeFilesystemIdentity.js";
 import { CONTROLLER_DISCOVERY_PATH, ControllerProtocolError, encodeControllerRequest, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
 export class ControllerClientError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, cause) {
+        super(message, { cause });
         this.code = code;
         this.name = "ControllerClientError";
     }
@@ -50,9 +50,12 @@ export async function readControllerDiscovery(home) {
         if (error instanceof ControllerClientError)
             throw error;
         if (isNodeError(error) && error.code === "ENOENT") {
-            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", "Controller is not running.");
+            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", withOriginalError("Controller is not running.", error), error);
         }
-        throw invalidDiscovery();
+        if (isNodeError(error) && (error.code === "EPERM" || error.code === "EACCES")) {
+            throw controllerAccessDenied(error, "discovery record");
+        }
+        throw invalidDiscovery(error);
     }
 }
 function discoverySocketPath(value) {
@@ -90,9 +93,9 @@ export async function callController(home, method, params = {}, options = {}) {
     }
     catch (error) {
         if (error instanceof ControllerProtocolError) {
-            throw new ControllerClientError(error.code, error.message);
+            throw new ControllerClientError(error.code, error.message, error);
         }
-        throw new ControllerClientError("INVALID_REQUEST", "Invalid controller request.");
+        throw new ControllerClientError("INVALID_REQUEST", withOriginalError("Invalid controller request.", error), error);
     }
     return exchange(discovery.socketPath, requestLine, id, timeoutMs);
 }
@@ -201,26 +204,51 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
                 else
                     fail(new ControllerClientError(response.error.code, response.error.message));
             }
-            catch {
-                fail(invalidResponse());
+            catch (error) {
+                fail(invalidResponse(error));
             }
         });
         socket.on("end", () => {
             if (!settled)
                 fail(invalidResponse());
         });
-        socket.on("error", () => {
-            fail(deliveryStarted
-                ? new ControllerClientError("CONTROLLER_DELIVERY_UNKNOWN", "Controller request delivery is unknown.")
-                : new ControllerClientError("CONTROLLER_UNAVAILABLE", "Controller is unavailable."));
+        socket.on("error", (error) => {
+            fail(classifyControllerSocketError(error, deliveryStarted));
         });
     });
 }
-function invalidDiscovery() {
-    return new ControllerClientError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery is invalid.");
+export function classifyControllerSocketError(error, deliveryStarted) {
+    if (deliveryStarted) {
+        return new ControllerClientError("CONTROLLER_DELIVERY_UNKNOWN", withOriginalError("Controller request delivery is unknown.", error), error);
+    }
+    if (isNodeError(error) && (error.code === "EPERM" || error.code === "EACCES")) {
+        return controllerAccessDenied(error, "socket");
+    }
+    return new ControllerClientError("CONTROLLER_UNAVAILABLE", withOriginalError("Controller is unavailable.", error), error);
+}
+function controllerAccessDenied(error, target) {
+    return new ControllerClientError("CONTROLLER_ACCESS_DENIED", `Controller ${target} access was denied (${error.code}) before any request was sent. `
+        + "In Codex, request sandbox escalation to rerun the same Yui CLI command outside the sandbox "
+        + `if authorized. If escalation is denied, report that to the user.${originalErrorDetail(error)}`, error);
+}
+function invalidDiscovery(error) {
+    return new ControllerClientError("CONTROLLER_DISCOVERY_INVALID", error === undefined
+        ? "Controller discovery is invalid."
+        : withOriginalError("Controller discovery is invalid.", error), error);
+}
+function invalidResponse(error) {
+    return new ControllerClientError("INVALID_RESPONSE", error === undefined
+        ? "Controller response is invalid."
+        : withOriginalError("Controller response is invalid.", error), error);
+}
+function withOriginalError(message, error) {
+    return `${message}${originalErrorDetail(error)}`;
 }
-function invalidResponse() {
-    return new ControllerClientError("INVALID_RESPONSE", "Controller response is invalid.");
+function originalErrorDetail(error) {
+    const code = isNodeError(error) && typeof error.code === "string"
+        ? ` (${error.code})`
+        : "";
+    return ` Original error${code}: ${error instanceof Error ? error.message : String(error)}`;
 }
 function isNodeError(error) {
     return error instanceof Error && "code" in error;

package/dist/core/controllerEndpoint.js

@@ -5,9 +5,10 @@ export function controllerSocketPath(homeId) {
     const identity = validateHomeId(homeId);
     const uid = typeof process.getuid === "function" ? process.getuid() : 0;
     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();
+    // Unix-socket paths have a small fixed budget (104 bytes on macOS, 108 on
+    // Linux). A stable per-uid system root is short and independent of each
+    // caller's isolated TMPDIR, which is a long /var/folders path on macOS.
+    const root = process.platform === "win32" ? tmpdir() : "/tmp";
     return join(root, `yui-${uid}`, socketName);
 }
 /**