@zq-silk/yui 0.6.0 → 0.6.2

package/dist/core/controllerServer.js

@@ -1,11 +1,26 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { readFileSync, realpathSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { CONTROLLER_DISCOVERY_PATH, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, controllerFailure, encodeControllerResponse, isEmptyParams, parseControllerRequest } from "./protocol.js";
 import { controllerSocketPath } from "./controllerEndpoint.js";
 import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
-import { removeEphemeralDomainIdentity, readEphemeralDomainIdentity, writeEphemeralDomainIdentity } from "../controller/domainIdentity.js";
+import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
+import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { CommandExecutionError } from "../tmux/commandExecutor.js";
+import { detectRunningRelease, readActiveReleasePointer, readHandoverFence, verifyReleaseIntegrity, writeHandoverFence, writeRuntimeIdentity } from "../release/runtimeRelease.js";
+import { isBuiltinControllerMethod, ControllerCommandObserver, ControllerEventLoopDelay } from "./controllerTelemetry.js";
+import { parseLinuxProcessStartIdentity, removeEphemeralDomainIdentity, readEphemeralDomainIdentity, writeEphemeralDomainIdentity } from "../controller/domainIdentity.js";
+/** Methods that stay available while a handover fence is active. */
+const HANDOVER_ALLOWED_METHODS = new Set([
+    "controller.identity",
+    "controller.status",
+    "controller.handover-state",
+    "controller.commit-handover",
+    "controller.rollback-handover"
+]);
 export async function startControllerServer(home, dispatcher, beforeDiscoveryRemoval, options = {}) {
     const releaseLifecycleLock = await acquireHomeLifecycleLock(home);
     try {
@@ -26,8 +41,32 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
     await chmod(socketDirectory, 0o700);
     const token = randomBytes(32).toString("hex");
     let closeRunning = async () => undefined;
+    const commandObserver = new ControllerCommandObserver();
+    const eventLoopDelay = new ControllerEventLoopDelay();
+    const telemetry = Object.freeze({
+        commandObserver,
+        eventLoopDelay
+    });
+    const handover = { fence: null };
+    const release = options.release === undefined
+        ? detectRunningRelease(fileURLToPath(import.meta.url))
+        : options.release;
+    // Issue 01: the Home decides the backend. The receipt reports the truthful
+    // Home-decided backend (SQLite for a layout-7 Home with yui.db, file store
+    // for older layouts) instead of deriving it from YUI_STORE_BACKEND, which is
+    // reserved for tests and explicit recovery commands.
+    const storageBackend = options.storageBackend
+        ?? resolveTaskStoreBackendForHome(home, process.env);
+    const workerEnabled = options.workerEnabled
+        ?? resolveStoreWorkerEnabledForHome(home, process.env);
+    // The primary identity receipt is captured at startup and re-published on a
+    // handover rollback: the candidate overwrites runtime-identity.json while it
+    // runs, and after the rollback kills the candidate the file must not keep
+    // pointing at the dead candidate's release/PID. The old Controller is still
+    // the live primary, so its startup identity is still truthful.
+    let primaryIdentity = null;
     const netServer = createServer((socket) => {
-        receiveRequest(socket, token, dispatcher, () => closeRunning());
+        receiveRequest(socket, token, dispatcher, () => closeRunning(), options.status, telemetry, handover, home, () => primaryIdentity);
     });
     try {
         await listen(netServer, socketPath);
@@ -47,6 +86,7 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
             throw retryError;
         }
     }
+    eventLoopDelay.start();
     try {
         await chmod(socketPath, 0o600);
         const processStartIdentity = await readLinuxProcessStartIdentity(process.pid);
@@ -60,6 +100,19 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
             writeEphemeralDomainIdentity(home, options.domainIdentity);
         }
         await writeDiscoveryAtomically(discoveryPath, discovery);
+        // Issue 02: every Controller start publishes its provenance. The receipt
+        // is the stable, file-based identity that survives a Controller stop and
+        // backs the read-only `controller identity --json` command.
+        primaryIdentity = buildRuntimeIdentityReceipt({
+            home,
+            release,
+            storageBackend,
+            workerEnabled,
+            processStartIdentity,
+            mode: "primary",
+            dualOwner: false
+        });
+        writeRuntimeIdentity(home, primaryIdentity);
         let resolveClosed = () => undefined;
         const closed = new Promise((resolve) => {
             resolveClosed = resolve;
@@ -69,6 +122,7 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
             if (closePromise !== undefined)
                 return closePromise;
             closePromise = (async () => {
+                eventLoopDelay.stop();
                 await beforeDiscoveryRemoval?.();
                 await closeNetServer(netServer);
                 await removeOwnedDiscovery(discoveryPath, token);
@@ -88,9 +142,16 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
             })();
             return closePromise;
         };
-        return Object.freeze({ discovery, closed, close: closeRunning });
+        return Object.freeze({
+            discovery,
+            closed,
+            close: closeRunning,
+            commandObserver,
+            eventLoopDelay
+        });
     }
     catch (error) {
+        eventLoopDelay.stop();
         await closeNetServer(netServer);
         throw error;
     }
@@ -110,7 +171,7 @@ async function writeDiscoveryAtomically(discoveryPath, discovery) {
         throw error;
     }
 }
-function receiveRequest(socket, token, dispatcher, stop) {
+function receiveRequest(socket, token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity) {
     let buffer = Buffer.alloc(0);
     let complete = false;
     const fail = (code, message, id = "invalid") => {
@@ -139,7 +200,7 @@ function receiveRequest(socket, token, dispatcher, stop) {
             return;
         }
         complete = true;
-        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop);
+        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity);
     });
     socket.on("end", () => {
         if (!complete)
@@ -147,7 +208,7 @@ function receiveRequest(socket, token, dispatcher, stop) {
     });
     socket.on("error", () => undefined);
 }
-async function routeRequest(socket, line, token, dispatcher, stop) {
+async function routeRequest(socket, line, token, dispatcher, stop, status, telemetry, handover, home, getPrimaryIdentity) {
     let request;
     try {
         request = parseControllerRequest(line);
@@ -163,40 +224,108 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
         sendResponse(socket, controllerFailure(request.id, "UNAUTHORIZED", "Controller authentication failed."));
         return;
     }
+    // Every authenticated request is observed once at the routing layer. The
+    // observation completes when the response is handed to the socket, so a
+    // later status snapshot sees prior built-in completions and the dispatcher
+    // service-time metric stays a distinct observation.
+    const observation = telemetry.commandObserver.start();
+    const send = (response, onFlushed) => {
+        observation.complete(isBuiltinControllerMethod(request.method) ? "builtin" : "dispatched", response.ok ? "success" : "failure");
+        sendResponse(socket, response, onFlushed);
+    };
+    // Issue 02: a fenced Controller is mid-handover. It stops accepting new
+    // mutations and only answers the handover control methods plus read-only
+    // identity/status queries until the candidate promotes or the handover
+    // rolls back.
+    if (handover.fence !== null && !HANDOVER_ALLOWED_METHODS.has(request.method)) {
+        send(controllerFailure(request.id, "CONTROLLER_HANDOVER_FENCED", "Controller is fenced for a release handover; retry after the handover completes."));
+        return;
+    }
     if (request.method === "controller.identity") {
         if (!isEmptyParams(request.params)) {
-            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
             return;
         }
         // This is an authenticated, private lifecycle response. Unlike the public
         // resource inventory, it retains the exact executable/argv that the socket
         // owner was launched with so an update can restore that same Controller.
-        sendResponse(socket, {
+        // Issue 02 extends it with the release provenance the handover and the
+        // exact control-plane gate consume.
+        // The pid + process start identity let `release activate` fence this exact
+        // owner as the old Controller during a handover; without them the
+        // activator cannot distinguish a live owner from an empty Home and would
+        // bypass the handover sequence.
+        const release = detectRunningRelease(fileURLToPath(import.meta.url));
+        // Verify the running release's integrity so a drifted Controller can be
+        // refused by a handover activator. The Controller stays alive; the flag
+        // lets the activator fail closed without killing the serving process.
+        let releaseDrifted = false;
+        if (release !== null) {
+            try {
+                verifyReleaseIntegrity(release.releaseDir);
+            }
+            catch {
+                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.
+        }
+        send({
             id: request.id,
             ok: true,
             result: {
                 executablePath: process.execPath,
                 args: process.argv.slice(1),
-                version: YUI_VERSION
+                version: YUI_VERSION,
+                buildId: release?.manifest.buildId ?? "dev",
+                packageDigest: release?.manifest.packageDigest ?? null,
+                sourceCommit: release?.manifest.sourceCommit ?? null,
+                cliRealpath: controllerCliRealpath(),
+                controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
+                controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+                storageBackend: resolveTaskStoreBackendForHome(home, process.env),
+                workerEnabled: resolveStoreWorkerEnabledForHome(home, process.env),
+                mode: "primary",
+                dualOwner: false,
+                ...(releaseDrifted ? { releaseDrifted: true } : {}),
+                // A corrupted pointer file must not kill the serving Controller with
+                // an unhandled rejection; surface a degraded identity so the caller
+                // can diagnose, and let `release activate` fail on its own read.
+                activeRelease: readActiveReleasePointerSafe(home),
+                pid: process.pid,
+                ...(processStartIdentity === undefined
+                    ? {}
+                    : { processStartIdentity })
             }
         });
         return;
     }
     if (request.method === "controller.status") {
         if (!isEmptyParams(request.params)) {
-            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
             return;
         }
-        sendResponse(socket, {
+        send({
             id: request.id,
             ok: true,
             result: {
                 pid: process.pid,
                 running: true,
+                // Issue 11: process identity facts for status/audit. Read-only.
+                uptimeMs: Math.round(process.uptime() * 1000),
+                rssBytes: process.memoryUsage().rss,
                 protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
                 version: YUI_VERSION,
                 storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion
+                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+                ...(status === undefined ? {} : { runtime: status(telemetry) })
             }
         });
         return;
@@ -204,14 +333,14 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
     if (request.method === "controller.stop") {
         const expectedPid = expectedControllerStopPid(request.params);
         if (expectedPid === null) {
-            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
             return;
         }
         if (expectedPid !== undefined && expectedPid !== process.pid) {
-            sendResponse(socket, controllerFailure(request.id, "CONTROLLER_OWNERSHIP_MISMATCH", `Controller PID ${process.pid} does not match the expected PID ${expectedPid}.`));
+            send(controllerFailure(request.id, "CONTROLLER_OWNERSHIP_MISMATCH", `Controller PID ${process.pid} does not match the expected PID ${expectedPid}.`));
             return;
         }
-        sendResponse(socket, {
+        send({
             id: request.id,
             ok: true,
             result: {
@@ -221,21 +350,275 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
         }, () => void stop());
         return;
     }
+    if (request.method === "controller.begin-handover") {
+        const params = parseBeginHandoverParams(request.params);
+        if (params === null) {
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        if (handover.fence !== null) {
+            send(controllerFailure(request.id, "CONTROLLER_HANDOVER_ACTIVE", "Controller is already fenced for a release handover."));
+            return;
+        }
+        const fencedAt = new Date().toISOString();
+        const owner = currentHandoverOwner();
+        const fence = Object.freeze({
+            schemaVersion: 1,
+            handoverId: params.handoverId,
+            phase: "fenced",
+            old: owner,
+            candidate: null,
+            fromReleaseId: params.fromReleaseId,
+            toReleaseId: params.toReleaseId,
+            createdAt: fencedAt,
+            updatedAt: fencedAt
+        });
+        // Write the durable fence BEFORE setting the in-memory fence. If the
+        // durable write fails, the Controller must not be left permanently fenced
+        // in memory (retry would get CONTROLLER_HANDOVER_ACTIVE with no durable
+        // state to roll back).
+        try {
+            writeHandoverFence(home, fence);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? safeErrorMessage(error.message) : undefined;
+            send(controllerFailure(request.id, "INTERNAL_ERROR", `Failed to write the handover fence${detail === undefined ? "" : `: ${detail}`}`));
+            return;
+        }
+        handover.fence = { handoverId: params.handoverId, fencedAt };
+        send({
+            id: request.id,
+            ok: true,
+            result: handoverFenceResult(fence)
+        });
+        return;
+    }
+    if (request.method === "controller.commit-handover") {
+        const handoverId = parseHandoverIdParam(request.params);
+        if (handoverId === null) {
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        if (handover.fence === null || handover.fence.handoverId !== handoverId) {
+            send(controllerFailure(request.id, "CONTROLLER_HANDOVER_MISMATCH", "Controller handover fence does not match the requested handover."));
+            return;
+        }
+        const committedAt = new Date().toISOString();
+        const existing = readHandoverFenceOrNull(home);
+        if (existing !== null) {
+            try {
+                writeHandoverFence(home, Object.freeze({
+                    ...existing,
+                    phase: "committed",
+                    updatedAt: committedAt
+                }));
+            }
+            catch (error) {
+                const detail = error instanceof Error ? safeErrorMessage(error.message) : undefined;
+                send(controllerFailure(request.id, "INTERNAL_ERROR", `Failed to commit the handover fence${detail === undefined ? "" : `: ${detail}`}`));
+                return;
+            }
+        }
+        // Keep the in-memory fence set until this process exits. The pointer has
+        // switched and the Controller is draining; clearing the fence here would
+        // reopen the mutation window on the old release before stop() completes.
+        // The in-memory state dies with the process.
+        send({
+            id: request.id,
+            ok: true,
+            result: { committed: true, pid: process.pid }
+        }, () => void stop());
+        return;
+    }
+    if (request.method === "controller.rollback-handover") {
+        const handoverId = parseHandoverIdParam(request.params);
+        if (handoverId === null) {
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        if (handover.fence === null || handover.fence.handoverId !== handoverId) {
+            send(controllerFailure(request.id, "CONTROLLER_HANDOVER_MISMATCH", "Controller handover fence does not match the requested handover."));
+            return;
+        }
+        const rolledBackAt = new Date().toISOString();
+        const existing = readHandoverFenceOrNull(home);
+        if (existing !== null) {
+            writeHandoverFence(home, Object.freeze({
+                ...existing,
+                phase: "rolled-back",
+                updatedAt: rolledBackAt
+            }));
+        }
+        handover.fence = null;
+        // The candidate overwrote runtime-identity.json while it ran; now that the
+        // handover is rolled back and the candidate is dead, restore this
+        // Controller's primary identity so the file does not keep pointing at the
+        // dead candidate's release/PID.
+        const primaryIdentity = getPrimaryIdentity();
+        if (primaryIdentity !== null) {
+            writeRuntimeIdentity(home, primaryIdentity);
+        }
+        send({
+            id: request.id,
+            ok: true,
+            result: { resumed: true, pid: process.pid }
+        });
+        return;
+    }
+    if (request.method === "controller.handover-state") {
+        if (!isEmptyParams(request.params)) {
+            send(controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        const fence = readHandoverFenceOrNull(home);
+        send({
+            id: request.id,
+            ok: true,
+            result: {
+                fenced: handover.fence !== null,
+                ...(handover.fence === null ? {} : { handoverId: handover.fence.handoverId }),
+                ...(fence === null ? {} : { phase: fence.phase })
+            }
+        });
+        return;
+    }
     if (dispatcher === undefined) {
-        sendResponse(socket, controllerFailure(request.id, "METHOD_NOT_FOUND", "Controller method was not found."));
+        send(controllerFailure(request.id, "METHOD_NOT_FOUND", "Controller method was not found."));
         return;
     }
     try {
         const result = await dispatcher(request.method, request.params);
-        sendResponse(socket, { id: request.id, ok: true, result });
+        send({ id: request.id, ok: true, result });
     }
     catch (error) {
         const safeError = safeDispatcherError(error);
-        sendResponse(socket, safeError === undefined
+        send(safeError === undefined
             ? controllerFailure(request.id, "INTERNAL_ERROR", "Controller request failed.")
             : controllerFailure(request.id, safeError.code, safeError.message));
     }
 }
+function parseBeginHandoverParams(value) {
+    if (typeof value !== "object"
+        || value === null
+        || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const handoverId = record.handoverId;
+    const toReleaseId = record.toReleaseId;
+    if (typeof handoverId !== "string"
+        || handoverId.length === 0
+        || handoverId.length > 128
+        || typeof toReleaseId !== "string"
+        || toReleaseId.length === 0
+        || toReleaseId.length > 256) {
+        return null;
+    }
+    const fromReleaseId = record.fromReleaseId;
+    if (fromReleaseId !== undefined
+        && (typeof fromReleaseId !== "string" || fromReleaseId.length > 256)) {
+        return null;
+    }
+    return {
+        handoverId,
+        fromReleaseId: typeof fromReleaseId === "string" ? fromReleaseId : null,
+        toReleaseId
+    };
+}
+function parseHandoverIdParam(value) {
+    if (typeof value !== "object"
+        || value === null
+        || Array.isArray(value)) {
+        return null;
+    }
+    const handoverId = value.handoverId;
+    return typeof handoverId === "string" && handoverId.length > 0 && handoverId.length <= 128
+        ? handoverId
+        : null;
+}
+function currentHandoverOwner() {
+    const release = detectRunningRelease(fileURLToPath(import.meta.url));
+    return Object.freeze({
+        pid: process.pid,
+        processStartIdentity: readLinuxProcessStartIdentitySync(process.pid),
+        buildId: release?.manifest.buildId ?? "dev",
+        version: YUI_VERSION
+    });
+}
+function handoverFenceResult(fence) {
+    return {
+        handoverId: fence.handoverId,
+        phase: fence.phase,
+        old: {
+            pid: fence.old.pid,
+            processStartIdentity: fence.old.processStartIdentity,
+            buildId: fence.old.buildId,
+            version: fence.old.version
+        },
+        toReleaseId: fence.toReleaseId
+    };
+}
+function readHandoverFenceOrNull(home) {
+    try {
+        return readHandoverFence(home);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the active release pointer without letting a corrupted file kill the Controller. */
+function readActiveReleasePointerSafe(home) {
+    try {
+        return readActiveReleasePointer(home);
+    }
+    catch {
+        return null;
+    }
+}
+function readLinuxProcessStartIdentitySync(pid) {
+    // The async /proc reader is used at startup; handover RPCs need a sync
+    // identity to keep the request handler simple. Both parse the same field.
+    const processStartIdentity = parseLinuxProcessStartIdentity(readFileSync(`/proc/${pid}/stat`, "utf8"));
+    if (processStartIdentity === undefined) {
+        throw new Error(`Cannot read Controller process identity for PID ${pid}.`);
+    }
+    return processStartIdentity;
+}
+function controllerCliRealpath() {
+    return realpathSync(fileURLToPath(new URL("../cli.js", import.meta.url)));
+}
+export function buildRuntimeIdentityReceipt(input) {
+    const activeRelease = (() => {
+        try {
+            return readActiveReleasePointer(input.home);
+        }
+        catch {
+            return null;
+        }
+    })();
+    return Object.freeze({
+        schemaVersion: 1,
+        version: YUI_VERSION,
+        executablePath: process.execPath,
+        args: process.argv.slice(1),
+        buildId: input.release?.manifest.buildId ?? "dev",
+        packageDigest: input.release?.manifest.packageDigest ?? null,
+        sourceCommit: input.release?.manifest.sourceCommit ?? null,
+        cliRealpath: controllerCliRealpath(),
+        controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
+        controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+        storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
+        aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+        storageBackend: input.storageBackend,
+        workerEnabled: input.workerEnabled,
+        pid: process.pid,
+        processStartIdentity: input.processStartIdentity,
+        mode: input.mode,
+        dualOwner: input.dualOwner,
+        activeRelease,
+        writtenAt: new Date().toISOString()
+    });
+}
 /**
  * `controller.stop` is public with `{}` params, but update's replacement
  * mismatch path may provide one exact PID fence.  `null` means malformed;
@@ -337,6 +720,18 @@ function safeDispatcherError(error) {
                 return { code: "SERVICE_ERROR", message };
             case "CoreJobError":
                 return { code: "JOB_ERROR", message };
+            case "CommandExecutionError": {
+                // Transient tmux/process launch failures (e.g. under CI load) carry
+                // the real stderr; surface it instead of the generic fallback so the
+                // caller can distinguish a retryable infrastructure failure from a
+                // permanent contract violation.
+                if (error instanceof CommandExecutionError && error.stderr.length > 0) {
+                    const detail = safeErrorMessage(error.stderr);
+                    if (detail !== undefined)
+                        return { code: "SERVICE_ERROR", message: detail };
+                }
+                return { code: "SERVICE_ERROR", message };
+            }
             default:
                 return undefined;
         }
@@ -350,6 +745,7 @@ function safeApplicationErrorCode(code) {
         case "INVALID_PARAMS":
         case "METHOD_NOT_FOUND":
         case "NOT_FOUND":
+        case "UNAUTHORIZED":
             return code;
         default:
             return undefined;
@@ -453,15 +849,8 @@ function isProcessAlive(pid) {
     }
 }
 async function readLinuxProcessStartIdentity(pid) {
-    const stat = await readFile(`/proc/${pid}/stat`, "utf8");
-    const closingParenthesis = stat.lastIndexOf(")");
-    if (closingParenthesis < 0) {
-        throw new Error(`Cannot read Controller process identity for PID ${pid}.`);
-    }
-    const fieldsAfterCommand = stat.slice(closingParenthesis + 1).trim().split(/\s+/u);
-    const processStartIdentity = fieldsAfterCommand[19];
-    if (processStartIdentity === undefined
-        || !/^[0-9]{1,32}$/u.test(processStartIdentity)) {
+    const processStartIdentity = parseLinuxProcessStartIdentity(await readFile(`/proc/${pid}/stat`, "utf8"));
+    if (processStartIdentity === undefined) {
         throw new Error(`Cannot read Controller process identity for PID ${pid}.`);
     }
     return processStartIdentity;