@zq-silk/yui 1.0.1 → 1.1.2

package/dist/core/controllerProcessIdentity.js

@@ -1,4 +1,6 @@
 import { readFileSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { nativeExecutable } from "../runtime/nativeExecutable.js";
 import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 import { readHomeFilesystemId, validateHomeFilesystemId } from "./homeFilesystemIdentity.js";
 /** Exact live-process fence used at Controller startup and handover. */
@@ -6,6 +8,22 @@ export function inspectLiveControllerProcess(pid, homeFilesystemId, expectedProc
     if (!Number.isSafeInteger(pid) || pid < 1 || pid === process.pid)
         return undefined;
     const expectedFilesystemId = validateHomeFilesystemId(homeFilesystemId);
+    if (process.platform === "darwin") {
+        const candidate = inspectDarwinController(pid);
+        if (candidate === undefined)
+            return undefined;
+        try {
+            if (readHomeFilesystemId(candidate.home) !== expectedFilesystemId)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        if (expectedProcessStartIdentity !== undefined
+            && candidate.processStartIdentity !== expectedProcessStartIdentity)
+            return undefined;
+        return Object.freeze({ pid, processStartIdentity: candidate.processStartIdentity });
+    }
     try {
         const uid = typeof process.getuid === "function" ? process.getuid() : 0;
         const status = readFileSync(`/proc/${pid}/status`, "utf8");
@@ -42,6 +60,20 @@ export function inspectLiveControllerProcess(pid, homeFilesystemId, expectedProc
 /** Finds a Controller whose discovery record was lost. */
 export function findLiveControllerProcessForHome(homeFilesystemId) {
     validateHomeFilesystemId(homeFilesystemId);
+    if (process.platform === "darwin") {
+        const output = runDarwinIdentityHelper(["--controllers"]);
+        if (output === undefined)
+            return undefined;
+        for (const line of output.trim().split("\n")) {
+            const candidate = parseDarwinController(line);
+            if (candidate === undefined)
+                continue;
+            const match = inspectLiveControllerProcess(candidate.pid, homeFilesystemId, candidate.processStartIdentity);
+            if (match !== undefined)
+                return match;
+        }
+        return undefined;
+    }
     if (process.platform !== "linux")
         return undefined;
     const entries = readdirSync("/proc", { encoding: "utf8" });
@@ -54,3 +86,25 @@ export function findLiveControllerProcessForHome(homeFilesystemId) {
     }
     return undefined;
 }
+function inspectDarwinController(pid) {
+    const output = runDarwinIdentityHelper(["--controller", String(pid)]);
+    return output === undefined ? undefined : parseDarwinController(output.trim());
+}
+function parseDarwinController(line) {
+    const match = /^([1-9][0-9]*)\t([1-9][0-9]{0,31})\t([^\t\n]+)$/u.exec(line);
+    if (match === null)
+        return undefined;
+    const pid = Number(match[1]);
+    if (!Number.isSafeInteger(pid))
+        return undefined;
+    return { pid, processStartIdentity: match[2], home: match[3] };
+}
+function runDarwinIdentityHelper(args) {
+    try {
+        return execFileSync(nativeExecutable("process-identity"), [...args], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/controllerServer.js

@@ -8,6 +8,7 @@ import { CONTROLLER_DISCOVERY_PATH, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_C
 import { controllerSocketPath } from "./controllerEndpoint.js";
 import { readHomeFilesystemId } from "./homeFilesystemIdentity.js";
 import { findLiveControllerProcessForHome } from "./controllerProcessIdentity.js";
+import { currentProcessStartIdentity, processGenerationIsLive } from "./fileLockOwner.js";
 import { validateHomeId } from "../repository/homeIdentity.js";
 import { readCurrentHomeIdentity } from "../storage/currentTaskStore.js";
 import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
@@ -98,7 +99,9 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
     eventLoopDelay.start();
     try {
         await chmod(socketPath, 0o600);
-        const processStartIdentity = await readLinuxProcessStartIdentity(process.pid);
+        const processStartIdentity = process.platform === "linux"
+            ? await readLinuxProcessStartIdentity(process.pid)
+            : currentProcessStartIdentity();
         const discovery = Object.freeze({
             schemaVersion: 1,
             protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
@@ -202,6 +205,14 @@ async function assertExistingDiscoveryReplaceable(discoveryPath) {
         || !/^[0-9]{1,32}$/u.test(value.processStartIdentity)) {
         throw unsafeExistingDiscovery(discoveryPath);
     }
+    if (process.platform !== "linux") {
+        // The native helper proves the exact macOS generation; a live PID with
+        // unreadable identity cannot authorize discovery replacement.
+        if (processGenerationIsLive(pid, value.processStartIdentity)) {
+            throw controllerAlreadyRunning();
+        }
+        return;
+    }
     let currentIdentity;
     try {
         currentIdentity = await readLinuxProcessStartIdentity(pid);
@@ -340,15 +351,7 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 releaseDrifted = true;
             }
         }
-        let processStartIdentity;
-        try {
-            processStartIdentity = readLinuxProcessStartIdentitySync(process.pid);
-        }
-        catch {
-            // Non-Linux or an unreadable /proc: the owner cannot be fenced, so the
-            // handover path treats it as absent. The rest of the identity stays
-            // available for read-only consumers.
-        }
+        const processStartIdentity = currentProcessStartIdentity();
         send({
             id: request.id,
             ok: true,
@@ -621,7 +624,9 @@ function currentHandoverOwner() {
     const release = detectRunningRelease(fileURLToPath(import.meta.url));
     return Object.freeze({
         pid: process.pid,
-        processStartIdentity: readLinuxProcessStartIdentitySync(process.pid),
+        processStartIdentity: process.platform === "linux"
+            ? readLinuxProcessStartIdentitySync(process.pid)
+            : currentProcessStartIdentity(),
         buildId: release?.manifest.buildId ?? "dev",
         version: YUI_VERSION
     });

package/dist/core/fileLockOwner.js

@@ -1,8 +1,41 @@
 import { lstatSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
+import { nativeExecutable } from "../runtime/nativeExecutable.js";
 /** One process generation, shared by file-lock producers and reclaim checks. */
 export function currentFileLockOwner() {
-    return `${process.pid}:${readProcessStart(process.pid)}`;
+    return `${process.pid}:${currentProcessStartIdentity()}`;
+}
+/**
+ * Identity of the current process. Linux reads the /proc start-time field,
+ * which survives PID reuse. macOS uses libproc's process start timestamp.
+ */
+export function currentProcessStartIdentity() {
+    const identity = readProcessStartIdentity(process.pid);
+    if (identity === undefined)
+        throw new Error(`Process start identity is unavailable for PID ${process.pid}.`);
+    return identity;
+}
+export function readProcessStartIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return undefined;
+    if (process.platform === "linux") {
+        try {
+            return readProcessStart(pid);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform !== "darwin")
+        return undefined;
+    try {
+        const identity = execFileSync(nativeExecutable("process-identity"), [String(pid)], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return /^(0|[1-9][0-9]{0,31})$/u.test(identity) ? identity : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 /**
  * False requires proof of absence or a different process generation.
@@ -42,20 +75,28 @@ export function processGenerationIsLive(pid, startIdentity) {
     if (!Number.isSafeInteger(pid) || pid < 1 || !/^(0|[1-9][0-9]{0,31})$/u.test(startIdentity)) {
         throw new Error(`Unverified process generation for PID ${pid}.`);
     }
+    const actual = readProcessStartIdentity(pid);
+    if (actual !== undefined)
+        return actual === startIdentity;
+    // PID liveness can prove a process is gone, never prove its generation.
     try {
-        return readProcessStart(pid) === startIdentity;
+        process.kill(pid, 0);
     }
-    catch {
-        // PID liveness can prove a process is gone, never prove its generation.
-        try {
-            process.kill(pid, 0);
-        }
-        catch (error) {
-            if (hasCode(error, "ESRCH"))
-                return false;
-        }
-        throw new Error(`Unverified process generation for PID ${pid}; OS identity could not be read.`);
+    catch (error) {
+        if (hasCode(error, "ESRCH"))
+            return false;
+    }
+    throw new Error(`Unverified process generation for PID ${pid}; OS identity could not be read.`);
+}
+/**
+ * Owner liveness used by reconciliation. An unreadable identity for a live
+ * PID is unknown and must not authorize cleanup or release of durable custody.
+ */
+export function processOwnerIsLive(pid, startIdentity) {
+    if (!Number.isSafeInteger(pid) || pid < 1 || !/^(0|[1-9][0-9]{0,31})$/u.test(startIdentity)) {
+        throw new Error(`Unverified process generation for PID ${pid}.`);
     }
+    return processGenerationIsLive(pid, startIdentity);
 }
 function readProcessStart(pid) {
     const stat = readFileSync(`/proc/${pid}/stat`, "utf8");

package/dist/doctor/doctor.js

@@ -1,10 +1,12 @@
-import { accessSync, constants, existsSync, lstatSync } from "node:fs";
+import { accessSync, constants, existsSync, lstatSync, realpathSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import Database from "better-sqlite3";
+import { inspectPty } from "./ptyProbe.js";
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { operationalAgentEnvironment } from "../agent/launchEnvironment.js";
 import { resolveTmuxBin } from "../config/yuiConfig.js";
 import { compileRoleSessionContext } from "../context/roleSessionContext.js";
+import { callController, ControllerClientError } from "../core/controllerClient.js";
 import { EPHEMERAL_DOMAIN_GRACE_MS, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 import { usageError } from "../errors/cliError.js";
 import { inspectAgentCapabilities, resolveAgentAdapter } from "../executor/agentAdapter.js";
@@ -12,6 +14,8 @@ import { assertCodexLaunchOverridesAvailable, inspectCodexLaunchConfig } from ".
 import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { nativeAdditionalDirectories, nativeAgentWorkspace, withNativeProjectDirectories } from "../executor/fileRoleLaunchPlanner.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
+import { codexAppNeedsRestart, codexAppProcessIds, codexAppWebSocketUrl, codexSharedSocketPath, findMacCodexAppExecutable, isCodexInspectionPermissionError } from "../runtime/codexSharedDaemon.js";
+import { codexAgentsInUse } from "../runtime/localStartup.js";
 import { CURRENT_DATABASE_FILENAME, openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
@@ -42,8 +46,8 @@ export function summarizeStorageHealth(checks) {
     return { healthy: blocking.length === 0, blocking };
 }
 /** Build the full machine-readable doctor report (checks + storage health). */
-export function buildDoctorReport(env, executor) {
-    const inspection = inspectDoctor(env, executor);
+export async function buildDoctorReport(env, executor) {
+    const inspection = await inspectDoctor(env, executor);
     const home = resolveYuiHome(env);
     return {
         checks: inspection.checks,
@@ -100,29 +104,30 @@ function inspectStorageDetails(home, env) {
     };
 }
 /** Runs the read-only current-storage diagnostics used by `yui doctor`. */
-export function runDoctorCommand(args, env, executor) {
+export async function runDoctorCommand(args, env, executor) {
     if (args.length !== 0)
         throw usageError("Doctor usage: yui doctor");
-    const inspection = inspectDoctor(env, executor);
+    const inspection = await inspectDoctor(env, executor);
     return renderDoctor(inspection.checks, inspection.review);
 }
-export function getDoctorChecks(env, executor) {
-    return inspectDoctor(env, executor).checks;
+export async function getDoctorChecks(env, executor) {
+    return (await inspectDoctor(env, executor)).checks;
 }
-function inspectDoctor(env, executor) {
+async function inspectDoctor(env, executor) {
     const home = resolveYuiHome(env);
     const homeCheck = checkHome(home);
     const schema = readSchema(home);
     const compatibility = inspectCompatibility(home, homeCheck, schema);
     const schemaCheck = checkSchema(schema);
     const storage = inspectState(home, homeCheck, schema, compatibility);
+    const controller = await checkController(home);
     const domain = checkEphemeralDomain(home);
     const durableConfig = readDurableConfigSafely(home);
     const toolChecks = [
         checkExecutable("git", durableConfig.gitBin, ["--version"], executor),
         checkExecutable("tmux", durableConfig.tmuxBin, ["-V"], executor)
     ];
-    const agentChecks = storage.agents.flatMap((agent) => checkAgent(agent, executor, env));
+    const agentChecks = storage.agents.flatMap((agent) => checkAgent(agent, executor, env, home, storage.activeCodexAgentIds.has(agent.id)));
     const review = inspectReview({ ...storage.review, home }, agentChecks, env);
     return {
         checks: [
@@ -130,14 +135,49 @@ function inspectDoctor(env, executor) {
             schemaCheck,
             compatibility.check,
             storage.check,
+            controller,
             ...(domain === undefined ? [] : [domain]),
             ...toolChecks,
+            ...inspectPty(),
             ...agentChecks,
             ...review.checks
         ],
         review: review.report
     };
 }
+/** Query the authenticated Controller endpoint without starting it. */
+export async function checkController(home, probe = callController) {
+    try {
+        const result = await probe(home, "controller.status", {}, { timeoutMs: 1_000 });
+        if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+            const status = result;
+            if (status.running === true && Number.isSafeInteger(status.pid) && Number(status.pid) > 0) {
+                return { name: "controller", status: "ok", detail: `Controller is running pid=${status.pid}.` };
+            }
+        }
+        return {
+            name: "controller", status: "invalid",
+            detail: "Controller returned an invalid status; inspect yui controller status --verbose."
+        };
+    }
+    catch (error) {
+        if (error instanceof ControllerClientError && error.code === "CONTROLLER_NOT_RUNNING") {
+            return { name: "controller", status: "missing", detail: `${error.message} Run yui start.` };
+        }
+        if (error instanceof ControllerClientError && error.code === "CONTROLLER_UNAVAILABLE") {
+            return {
+                name: "controller",
+                status: "invalid",
+                detail: `Controller is not reachable: ${error.message} Run yui start. Its process state is unverified.`
+            };
+        }
+        return {
+            name: "controller",
+            status: "invalid",
+            detail: `Controller status could not be verified: ${error instanceof Error ? error.message : String(error)}. Inspect yui controller status --verbose.`
+        };
+    }
+}
 function checkEphemeralDomain(home) {
     const identity = readEphemeralDomainIdentity(home);
     if (identity.status === "absent")
@@ -327,6 +367,7 @@ function inspectState(home, homeCheck, schema, compatibility) {
                 detail: `yui.db readable agents=${agents.length} tasks=${tasks.length} roles=${roleCount} globalRoles=${globalRoles.length} defaultAgent=${config.defaultAgent ?? "none"}`
             },
             agents,
+            activeCodexAgentIds: new Set(codexAgentsInUse(store).map((agent) => agent.id)),
             review: {
                 storageReady: true,
                 storageDetail: "yui.db is readable",
@@ -362,6 +403,7 @@ function blockedStorage(status, detail) {
     return {
         check: { name: "storage state", status, detail },
         agents: [],
+        activeCodexAgentIds: new Set(),
         review: {
             storageReady: false,
             storageDetail: detail
@@ -655,11 +697,14 @@ function checkExecutable(name, command, args, executor) {
         };
     }
 }
-function checkAgent(agent, executor, environment) {
+function checkAgent(agent, executor, environment, home, activeCodex) {
     let snapshot;
+    let baseArgs;
+    let launchEnvironment;
     try {
         const definition = configuredAgentToDefinition(agent);
-        const launchEnvironment = resolveDoctorAgentEnvironment(definition, environment);
+        baseArgs = definition.baseArgs;
+        launchEnvironment = resolveDoctorAgentEnvironment(definition, environment);
         snapshot = inspectAgentCapabilities(definition, {
             run: (command, args) => runAgentProbe(executor, command, args, launchEnvironment)
         });
@@ -686,6 +731,9 @@ function checkAgent(agent, executor, environment) {
     const available = snapshot.fields.filter((field) => field.status === "available").length;
     const degraded = snapshot.fields.filter((field) => field.status === "degraded").length;
     const unavailable = snapshot.fields.filter((field) => field.status === "unavailable").length;
+    const daemon = activeCodex && status === "ok"
+        ? checkCodexSharedDaemon(agent.command, baseArgs, launchEnvironment, executor, agent.id)
+        : undefined;
     return [
         { name: `agent:${agent.id}:command`, status, detail: commandDetail },
         {
@@ -698,9 +746,181 @@ function checkAgent(agent, executor, environment) {
                 "installation/help inspection only; no model or account capability query",
                 ...snapshot.warnings.map((warning) => `warning=${warning}`)
             ].join(" ")
-        }
+        },
+        ...(daemon === undefined ? [] : [daemon]),
+        ...(daemon !== undefined && process.platform === "darwin"
+            ? checkMacCodexApp(agent.id, launchEnvironment, home, daemon, executor)
+            : [])
     ];
 }
+export function checkMacCodexApp(agentId, environment, home, daemon, executor, appExecutable = findMacCodexAppExecutable(environment)) {
+    if (appExecutable === undefined)
+        return [{
+                name: `agent:${agentId}:mac-app`, status: "ok",
+                detail: "Codex App was not detected; App sharing is not configured on this Mac."
+            }];
+    const expectedUrl = codexAppWebSocketUrl(environment, home);
+    let appPids;
+    try {
+        appPids = codexAppProcessIds(executor.run("/bin/ps", ["-axo", "pid=,args="], {
+            timeoutMs: 5_000
+        }), appExecutable);
+    }
+    catch (error) {
+        return [{
+                name: `agent:${agentId}:mac-app`, status: "invalid",
+                detail: `Cannot inspect Codex App processes: ${commandFailure(error)}`
+            }];
+    }
+    const processCheck = {
+        name: `agent:${agentId}:mac-app`,
+        status: appPids.length > 0 ? "ok" : "missing",
+        detail: appPids.length > 0
+            ? `Codex App is running pid=${appPids.join(",")}.`
+            : "Codex App is installed but not running."
+    };
+    let launchCheck;
+    try {
+        const launchUrl = executor.run("/bin/launchctl", ["getenv", "CODEX_APP_SERVER_WS_URL"], {
+            timeoutMs: 5_000
+        }).trim();
+        launchCheck = launchUrl === expectedUrl
+            ? {
+                name: `agent:${agentId}:mac-app-launch`, status: "ok",
+                detail: "Future Codex App launches are configured for this shared app-server."
+            }
+            : {
+                name: `agent:${agentId}:mac-app-launch`, status: "missing",
+                detail: "This login is not prepared for App sharing. Run yui start before opening or restarting App."
+            };
+    }
+    catch (error) {
+        launchCheck = {
+            name: `agent:${agentId}:mac-app-launch`, status: "invalid",
+            detail: `Cannot inspect the App launch environment: ${commandFailure(error)}`
+        };
+    }
+    const connectionName = `agent:${agentId}:mac-app-connection`;
+    if (appPids.length === 0) {
+        return [processCheck, launchCheck, {
+                name: connectionName, status: "missing", detail: "No detected App process; connection is not verified."
+            }];
+    }
+    if (daemon.status !== "ok") {
+        return [processCheck, launchCheck, {
+                name: connectionName, status: daemon.status,
+                detail: "Shared daemon is unavailable or unverified; App connection to it cannot be confirmed."
+            }];
+    }
+    let configuredCount = 0;
+    for (const pid of appPids) {
+        try {
+            const command = executor.run("/bin/ps", ["eww", "-p", pid, "-o", "command="], {
+                timeoutMs: 5_000
+            });
+            if (!codexAppNeedsRestart(command, expectedUrl, false))
+                configuredCount += 1;
+        }
+        catch (error) {
+            return [processCheck, launchCheck, {
+                    name: connectionName, status: "invalid",
+                    detail: `Cannot inspect running Codex App: ${commandFailure(error)}`
+                }];
+        }
+    }
+    try {
+        const socketTarget = realpathSync(codexSharedSocketPath(environment, home));
+        const sockets = parseMacUnixSockets(executor.run("/usr/sbin/lsof", ["-nP", "-U", "-F", "pfdn"], {
+            timeoutMs: 5_000
+        }));
+        const daemonSockets = sockets.filter((socket) => socket.name === socketTarget);
+        if (daemonSockets.length === 0) {
+            return [processCheck, launchCheck, {
+                    name: connectionName, status: "invalid",
+                    detail: "Daemon reports running, but its Unix socket endpoint was not observable."
+                }];
+        }
+        const peer = sockets.find((socket) => appPids.includes(socket.pid)
+            && daemonSockets.some((daemonSocket) => socket.name === `->${daemonSocket.device}`));
+        return [processCheck, launchCheck, peer === undefined
+                ? {
+                    name: connectionName, status: "missing",
+                    detail: configuredCount > 0
+                        ? "App has the shared URL, but no live socket peer to this daemon was observed."
+                        : "No live App socket peer to this daemon was observed; reopen App after Yui prepares sharing."
+                }
+                : {
+                    name: connectionName, status: "ok",
+                    detail: `App pid=${peer.pid} has a live Unix socket peer on shared daemon pid=${daemonSockets[0].pid}.`
+                }];
+    }
+    catch (error) {
+        return [processCheck, launchCheck, {
+                name: connectionName, status: "invalid",
+                detail: `Cannot verify the live App-to-daemon socket: ${commandFailure(error)}`
+            }];
+    }
+}
+function parseMacUnixSockets(output) {
+    const sockets = [];
+    let pid = "";
+    let device = "";
+    let name = "";
+    const finish = () => {
+        if (pid !== "" && /^0x[0-9a-f]+$/iu.test(device) && name !== "") {
+            sockets.push({ pid, device, name });
+        }
+        device = "";
+        name = "";
+    };
+    for (const line of output.split("\n")) {
+        if (line.startsWith("p")) {
+            finish();
+            pid = line.slice(1);
+        }
+        else if (line.startsWith("f"))
+            finish();
+        else if (line.startsWith("d"))
+            device = line.slice(1);
+        else if (line.startsWith("n"))
+            name = line.slice(1);
+    }
+    finish();
+    return sockets;
+}
+export function checkCodexSharedDaemon(command, baseArgs, environment, executor, agentId) {
+    const name = `agent:${agentId}:daemon`;
+    const probe = runAgentProbe(executor, command, [...baseArgs, "app-server", "daemon", "version"], environment);
+    if (probe.status !== 0) {
+        const detail = probe.stderr.trim() || probe.error?.message || "The Codex daemon could not be inspected.";
+        if (isCodexInspectionPermissionError(detail))
+            return {
+                name,
+                status: "invalid",
+                detail: `Shared Codex app-server state is unverified: this process was denied access during the daemon probe (${detail}). Run Doctor from a local terminal with access to the Codex socket.`
+            };
+        return {
+            name,
+            status: /No such file or directory|Connection refused/iu.test(detail) ? "missing" : "invalid",
+            detail: `Shared Codex app-server probe failed: ${detail}`
+        };
+    }
+    try {
+        const version = JSON.parse(probe.stdout);
+        if (version === null || typeof version !== "object" || Array.isArray(version))
+            throw new Error();
+        const state = version;
+        if (state.status !== "running")
+            throw new Error();
+        return {
+            name, status: "ok",
+            detail: `Shared Codex app-server running version=${String(state.appServerVersion ?? "unknown")}`
+        };
+    }
+    catch {
+        return { name, status: "invalid", detail: "Codex daemon version did not confirm a running app-server." };
+    }
+}
 function runAgentProbe(executor, command, args, environment) {
     try {
         return {

package/dist/doctor/ptyProbe.js

@@ -0,0 +1,74 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+/** Native loading and spawn happen outside Doctor: a native abort cannot kill the CLI. */
+export function inspectPty(options = {}) {
+    const started = Date.now();
+    const checks = [];
+    const major = Number(process.versions.node.split(".")[0]);
+    if (![20, 22, 24, 26].includes(major)) {
+        checks.push({
+            name: "pty Node runtime", status: "unsupported",
+            detail: `Node ${process.versions.node} is outside Yui's supported Node 20/22/24/26 range; this is not evidence of a helper permission failure.`
+        });
+    }
+    let entry;
+    let identity;
+    try {
+        const require = createRequire(options.requireFrom ?? import.meta.url);
+        entry = require.resolve("node-pty");
+        const manifest = require.resolve("node-pty/package.json");
+        const version = JSON.parse(readFileSync(manifest, "utf8")).version;
+        identity = `node-pty ${version}; entry=${entry}; package=${manifest}`;
+    }
+    catch (error) {
+        return [...checks, {
+                name: "node-pty",
+                status: error.code === "MODULE_NOT_FOUND" ? "missing" : "invalid",
+                detail: `Dependency resolution failed: ${String(error)}`
+            }];
+    }
+    const timeoutMs = options.timeoutMs ?? 1_500;
+    const result = spawnSync(process.execPath, [
+        fileURLToPath(new URL("./ptyProbeChild.js", import.meta.url)),
+        entry, String(options.probeTimeoutMs ?? 750)
+    ], {
+        // No NODE_OPTIONS, shell startup files, preload hooks or user configuration.
+        env: { PATH: "/usr/bin:/bin", LANG: "C" },
+        cwd: "/",
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: 64 * 1024
+    });
+    for (const line of (result.stdout ?? "").split("\n").filter(Boolean)) {
+        try {
+            const check = JSON.parse(line);
+            if (["node-pty", "pty helper", "pty spawn"].includes(check.name)
+                && ["ok", "missing", "invalid"].includes(check.status)
+                && typeof check.detail === "string") {
+                checks.push({ ...check, detail: `${identity}; ${check.detail}` });
+            }
+        }
+        catch { /* Native diagnostics on stdout are retained below on failure. */ }
+    }
+    const completed = checks.some(check => check.name === "pty spawn")
+        || checks.some(check => check.status !== "ok" && check.name !== "pty Node runtime");
+    if (result.error || result.signal || result.status !== 0 || !completed) {
+        const timedOut = result.error?.code === "ETIMEDOUT";
+        // A partial success line is not success if the isolated process failed to finish.
+        for (let i = 0; i < checks.length; i += 1) {
+            if (checks[i].name === "pty spawn" && checks[i].status === "ok") {
+                checks[i] = { ...checks[i], status: "invalid", detail: `${checks[i].detail}; isolated probe did not finish successfully` };
+            }
+        }
+        checks.push({
+            name: "pty probe", status: "invalid",
+            detail: `${identity}; ${timedOut ? `timeout after ${timeoutMs}ms` : "isolated probe failed"}; exit=${result.status} signal=${result.signal}; ${result.error?.message ?? ""} ${(result.stderr || result.stdout || "").trim()}`
+        });
+    }
+    return checks.map(check => ({
+        ...check, detail: `${check.detail}; elapsed=${Date.now() - started}ms`
+    }));
+}