@ask-llm/plugin 0.17.0 → 0.19.0

package/scripts/lib/broker-lifecycle.mjs

@@ -0,0 +1,677 @@
+// Source of truth: broker-lifecycle.mts. The sibling .mjs is generated by `yarn workspace @ask-llm/plugin build:hooks`; never edit it.
+// Broker lifecycle (ADR-090, ADR-093, ADR-168): the descriptor is written only after `initialize` succeeds.
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { rename, unlink, writeFile } from "node:fs/promises";
+import { connect as netConnect } from "node:net";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BROKER_PROTOCOL_VERSION, initializeBroker } from "./broker.mjs";
+import { IS_WINDOWS, terminateProcessTree } from "./process.mjs";
+import { stateRoot } from "./state.mjs";
+const BROKER_LOCK_DIR = "broker.lock";
+const LOCK_OWNER_FILE = "owner.json";
+const LOCK_SPAWN_FILE = "spawn.json";
+// Far longer than a bootstrap (5s budget) or teardown (1.5s grace) can hold the lock.
+const LOCK_STALE_MS = 30_000;
+const BROKER_LOG_FILE = "broker.log";
+const BROKER_SOCKET_FILE = "broker.sock";
+// macOS sun_path is 104 bytes including the terminator; Linux allows 108.
+const MAX_UNIX_SOCKET_PATH_BYTES = 103;
+const BOOTSTRAP_BUDGET_MS_DEFAULT = 5000;
+const SOCKET_POLL_INTERVAL_MS = 100;
+const ISOLATED_HOME_PREFIX = "codex-pair-broker-";
+const BROKER_OWNER_TTL_MS = 24 * 60 * 60 * 1000;
+function sourceCodexHome(sourceHome) {
+    return sourceHome ?? process.env.CODEX_HOME ?? join(homedir(), ".codex");
+}
+export function hasCurrentBrokerAuth(isolatedHome, sourceHome) {
+    if (!isolatedHome)
+        return false;
+    const auth = join(sourceCodexHome(sourceHome), "auth.json");
+    try {
+        return existsSync(auth) && readlinkSync(join(isolatedHome, "auth.json")) === auth;
+    }
+    catch {
+        return false;
+    }
+}
+// Link auth.json so token refreshes update the source credentials.
+export function createIsolatedBrokerHome(options = {}) {
+    const sourceHome = sourceCodexHome(options.sourceHome);
+    const home = mkdtempSync(join(options.tempRoot ?? tmpdir(), ISOLATED_HOME_PREFIX));
+    try {
+        chmodSync(home, 0o700);
+        const auth = join(sourceHome, "auth.json");
+        if (existsSync(auth))
+            symlinkSync(auth, join(home, "auth.json"));
+        writeFileSync(join(home, "config.toml"), "[features]\napps = false\n", { mode: 0o600 });
+        return home;
+    }
+    catch (error) {
+        rmSync(home, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function isIsolatedBrokerHome(home) {
+    if (typeof home !== "string")
+        return false;
+    try {
+        const actual = realpathSync(home);
+        const tempRoot = realpathSync(tmpdir());
+        return (basename(actual).startsWith(ISOLATED_HOME_PREFIX) &&
+            actual.startsWith(`${tempRoot}${sep}`) &&
+            (statSync(actual).mode & 0o777) === 0o700);
+    }
+    catch {
+        return false;
+    }
+}
+export function removeIsolatedBrokerHome(home) {
+    if (isIsolatedBrokerHome(home))
+        rmSync(home, { recursive: true, force: true });
+}
+// The socket lives in the private broker home so its path stays short however deep the project is.
+export function chooseTransport(isolatedHome) {
+    if (IS_WINDOWS) {
+        throw new Error("broker-lifecycle: Windows transport not implemented yet (see ADR-090)");
+    }
+    const socketPath = join(isolatedHome, BROKER_SOCKET_FILE);
+    if (Buffer.byteLength(socketPath) > MAX_UNIX_SOCKET_PATH_BYTES) {
+        throw new Error(`broker-lifecycle: socket path exceeds ${MAX_UNIX_SOCKET_PATH_BYTES} bytes`);
+    }
+    return `unix://${socketPath}`;
+}
+// Path resolvers for the lifecycle's filesystem state.
+export function brokerLockPath(markerDir) {
+    return join(stateRoot(markerDir), BROKER_LOCK_DIR);
+}
+export function brokerLogPath(markerDir) {
+    return join(stateRoot(markerDir), BROKER_LOG_FILE);
+}
+// Atomic lock creation lets the next start reclaim a dead holder.
+export function acquireBrokerLock(markerDir) {
+    const lockPath = brokerLockPath(markerDir);
+    mkdirSync(stateRoot(markerDir), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            mkdirSync(lockPath);
+            writeFileSync(join(lockPath, LOCK_OWNER_FILE), JSON.stringify({ pid: process.pid, at: Date.now() }));
+            return lockPath;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            if (attempt > 0 || !reclaimAbandonedLock(lockPath))
+                return null;
+        }
+    }
+    return null;
+}
+function readLockFile(lockPath, file) {
+    try {
+        return readFileSync(join(lockPath, file), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+// Return a lock if another reclaimer replaced it after our stale check.
+function reclaimAbandonedLock(lockPath) {
+    const owner = readLockFile(lockPath, LOCK_OWNER_FILE);
+    if (!isAbandonedLock(lockPath, owner))
+        return false;
+    // Look the orphan up before claiming, so an unknown ps leaves the lock and its record in place.
+    const orphan = findAbandonedBroker(lockPath);
+    if (!orphan)
+        return false;
+    const claimed = `${lockPath}.abandoned.${process.pid}.${Date.now()}`;
+    try {
+        renameSync(lockPath, claimed);
+    }
+    catch {
+        return false;
+    }
+    if (readLockFile(claimed, LOCK_OWNER_FILE) !== owner) {
+        try {
+            renameSync(claimed, lockPath);
+        }
+        catch { }
+        return false;
+    }
+    stopAbandonedBroker(orphan);
+    rmSync(claimed, { recursive: true, force: true });
+    return true;
+}
+function isAbandonedLock(lockPath, owner) {
+    try {
+        if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS)
+            return true;
+        return owner !== null && !isPidAlive(JSON.parse(owner)?.pid);
+    }
+    catch {
+        return false;
+    }
+}
+// The transport is recorded before spawning, so a broker orphaned at any point is found by it; null means ps failed.
+function findAbandonedBroker(lockPath) {
+    let spawned;
+    try {
+        const record = readLockFile(lockPath, LOCK_SPAWN_FILE) ?? readLockFile(lockPath, `${LOCK_SPAWN_FILE}.tmp`);
+        spawned = JSON.parse(record ?? "");
+        if (!isIsolatedBrokerHome(spawned.isolatedHome))
+            return { pids: [] };
+        if (spawned.transportUrl !== chooseTransport(spawned.isolatedHome))
+            return { pids: [] };
+    }
+    catch {
+        return { pids: [] };
+    }
+    const pids = findBrokerPids(spawned.transportUrl);
+    return pids && { pids, isolatedHome: spawned.isolatedHome };
+}
+function stopAbandonedBroker({ pids, isolatedHome }) {
+    for (const pid of pids) {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { }
+        }
+    }
+    removeIsolatedBrokerHome(isolatedHome);
+}
+function recordBootstrapSpawn(lockPath, spawned) {
+    const file = join(lockPath, LOCK_SPAWN_FILE);
+    writeFileSync(`${file}.tmp`, JSON.stringify(spawned));
+    renameSync(`${file}.tmp`, file);
+}
+export function releaseBrokerLock(lockPath) {
+    if (!lockPath)
+        return;
+    try {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort; an abandoned lock is reclaimed by the next acquireBrokerLock.
+    }
+}
+// Socket reachability is only a precondition; initialize still proves broker health.
+export async function pollSocketReachable(transportUrl, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    while (Date.now() < deadline) {
+        const reachable = await probeOnce(transportUrl);
+        if (reachable)
+            return true;
+        await sleep(SOCKET_POLL_INTERVAL_MS);
+    }
+    return false;
+}
+function probeOnce(transportUrl) {
+    return new Promise((resolve) => {
+        let connectOptions;
+        if (transportUrl.startsWith("unix://")) {
+            const path = transportUrl.slice("unix://".length);
+            try {
+                statSync(path);
+            }
+            catch {
+                resolve(false);
+                return;
+            }
+            connectOptions = { path };
+        }
+        else if (transportUrl.startsWith("ws://")) {
+            const rest = transportUrl.slice("ws://".length);
+            const slashIdx = rest.indexOf("/");
+            const authority = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+            const colonIdx = authority.lastIndexOf(":");
+            const host = colonIdx === -1 ? authority : authority.slice(0, colonIdx);
+            const port = colonIdx === -1 ? 80 : Number(authority.slice(colonIdx + 1));
+            connectOptions = { host, port };
+        }
+        else {
+            resolve(false);
+            return;
+        }
+        const sock = netConnect(connectOptions);
+        const settle = (ok) => {
+            sock.removeAllListeners();
+            try {
+                sock.destroy();
+            }
+            catch { }
+            resolve(ok);
+        };
+        sock.once("connect", () => settle(true));
+        sock.once("error", () => settle(false));
+        sock.once("timeout", () => settle(false));
+        sock.setTimeout(SOCKET_POLL_INTERVAL_MS);
+    });
+}
+// Keep this timer referenced so SessionStart cannot exit mid-bootstrap and orphan the broker.
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Detach app-server across SessionStart exit; persist its descriptor only after handshake.
+export function spawnBroker(markerDir, transportUrl, isolatedHome) {
+    if (!isIsolatedBrokerHome(isolatedHome))
+        throw new Error("broker requires an isolated Codex home");
+    const logFd = openSync(brokerLogPath(markerDir), "a");
+    const child = spawn("codex", ["app-server", "--listen", transportUrl], {
+        detached: true,
+        env: { ...process.env, CODEX_HOME: isolatedHome },
+        stdio: ["ignore", logFd, logFd],
+    });
+    // Handle asynchronous spawn errors so a missing Codex binary cannot crash the hook.
+    child.on("error", () => { });
+    // Detach so the broker outlives SessionStart.
+    child.unref();
+    return child;
+}
+export function readCodexVersion() {
+    try {
+        const out = execFileSync("codex", ["--version"], { timeout: 2000, encoding: "utf-8" });
+        return (out || "").trim() || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// Rename atomically after the lock creates the state root.
+export async function writeBrokerDescriptor(markerDir, descriptor) {
+    const finalPath = join(stateRoot(markerDir), "broker.json");
+    const tmpPath = `${finalPath}.tmp.${process.pid}`;
+    await writeFile(tmpPath, JSON.stringify(descriptor, null, 2));
+    await rename(tmpPath, finalPath);
+    return finalPath;
+}
+export async function unlinkBrokerDescriptor(markerDir) {
+    const finalPath = join(stateRoot(markerDir), "broker.json");
+    try {
+        await unlink(finalPath);
+    }
+    catch {
+        // best-effort
+    }
+}
+let cachedPluginVersion = null;
+export function readPluginVersion() {
+    if (cachedPluginVersion)
+        return cachedPluginVersion;
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // scripts/lib/*.mjs → packages/claude-plugin/package.json
+        const manifest = join(here, "..", "..", "package.json");
+        // Use the static ESM import; require is unavailable in generated .mjs.
+        const text = readFileSync(manifest, "utf-8");
+        cachedPluginVersion = (JSON.parse(text)?.version || "unknown").trim();
+    }
+    catch {
+        cachedPluginVersion = "unknown";
+    }
+    return cachedPluginVersion;
+}
+// Any failure terminates the spawned child and returns null so the session keeps direct reviews (ADR-077).
+export async function bootstrapBroker(markerDir, options = {}) {
+    const { budgetMs = BOOTSTRAP_BUDGET_MS_DEFAULT, injectDeps } = options;
+    const spawnFn = injectDeps?.spawnBroker ?? spawnBroker;
+    const initFn = injectDeps?.initializeBroker ?? initializeBroker;
+    const pollFn = injectDeps?.pollSocketReachable ?? pollSocketReachable;
+    const versionFn = injectDeps?.readCodexVersion ?? readCodexVersion;
+    // Without shared file credentials (keyring or environment keys) a broker could only fail its turns.
+    const hasCredentials = existsSync(join(sourceCodexHome(options.sourceHome), "auth.json"));
+    const lockPath = acquireBrokerLock(markerDir);
+    if (!lockPath)
+        return null; // another SessionStart holds the lock
+    const deadline = Date.now() + budgetMs;
+    let child = null;
+    let isolatedHome = null;
+    let connection = null; // hoisted so the catch block can close on descriptor-write failure
+    try {
+        const previous = readBrokerDescriptorSync(markerDir);
+        if (previous) {
+            const startedAt = Date.parse(previous.startedAt ?? "");
+            const ageMs = Date.now() - startedAt;
+            const expired = !Number.isFinite(ageMs) || ageMs >= BROKER_OWNER_TTL_MS || ageMs < -5 * 60 * 1000;
+            const liveness = expired ? null : (injectDeps?.brokerLiveness ?? brokerLiveness)(previous);
+            // Unverifiable liveness keeps the recorded broker and starts no second one; edits fall back to direct if it fails.
+            if (liveness === "unknown")
+                return null;
+            const live = liveness === "live";
+            if (hasCredentials && live && hasCurrentBrokerAuth(previous.isolatedHome, options.sourceHome)) {
+                return previous;
+            }
+            const retired = await teardownBroker(markerDir, {
+                lockHeld: true,
+                injectDeps,
+                onlyIfCredentialMissing: !hasCredentials && live,
+            });
+            if (!retired)
+                return null;
+        }
+        if (!hasCredentials)
+            return null;
+        isolatedHome = createIsolatedBrokerHome({ sourceHome: options.sourceHome });
+        const transportUrl = chooseTransport(isolatedHome);
+        recordBootstrapSpawn(lockPath, { isolatedHome, transportUrl });
+        child = spawnFn(markerDir, transportUrl, isolatedHome);
+        // Never extend the bootstrap deadline with a minimum timeout floor.
+        const pollBudget = deadline - Date.now() - 1000;
+        if (pollBudget <= 0)
+            throw new Error("broker bootstrap budget exhausted before poll");
+        const reachable = await pollFn(transportUrl, pollBudget);
+        if (!reachable)
+            throw new Error("broker did not become reachable within budget");
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error("broker bootstrap budget exhausted before initialize");
+        const clientInfo = {
+            name: "codex-pair",
+            title: `codex-pair plugin v${readPluginVersion()}`,
+            version: readPluginVersion(),
+        };
+        const initResult = await initFn(transportUrl, clientInfo, {
+            handshakeTimeoutMs: remaining,
+            initializeTimeoutMs: remaining,
+        });
+        connection = initResult.connection;
+        const initializeResult = initResult.initializeResult;
+        if (typeof initializeResult?.codexHome !== "string" ||
+            realpathSync(initializeResult.codexHome) !== realpathSync(isolatedHome)) {
+            throw new Error("broker reported an unexpected Codex home");
+        }
+        const descriptor = {
+            pid: child.pid,
+            transportUrl,
+            codexVersion: versionFn(),
+            codexHome: initializeResult?.codexHome ?? null,
+            isolatedHome,
+            sessionId: options.sessionId ?? null,
+            // Record the shared protocol constant so stale detection cannot drift.
+            protocolVersion: BROKER_PROTOCOL_VERSION,
+            pluginVersion: readPluginVersion(),
+            startedAt: new Date().toISOString(),
+            logPath: brokerLogPath(markerDir),
+        };
+        await writeBrokerDescriptor(markerDir, descriptor);
+        // Per-edit hooks open their own RPC connections.
+        try {
+            connection.close(1000, "bootstrap done");
+        }
+        catch {
+            // best-effort
+        }
+        return descriptor;
+    }
+    catch {
+        // Close a partially initialized connection and remove the child on any bootstrap failure.
+        if (connection) {
+            try {
+                connection.close(1011, "bootstrap failed");
+            }
+            catch { }
+        }
+        if (child) {
+            try {
+                terminateProcessTree(child, "SIGTERM");
+            }
+            catch { }
+        }
+        if (isolatedHome)
+            removeIsolatedBrokerHome(isolatedHome);
+        return null;
+    }
+    finally {
+        releaseBrokerLock(lockPath);
+    }
+}
+// ──── SessionEnd teardown (M2 PR 3) ────────────────────────────────────
+export function readBrokerDescriptorSync(markerDir) {
+    const descPath = join(stateRoot(markerDir), "broker.json");
+    try {
+        const text = readFileSync(descPath, "utf-8");
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (typeof parsed.pid !== "number" || typeof parsed.transportUrl !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// PID liveness is only a hint; Windows relies on process-tree termination.
+export function isPidAlive(pid) {
+    if (typeof pid !== "number" || pid <= 0)
+        return false;
+    if (IS_WINDOWS)
+        return true; // best-effort; rely on terminateProcessTree
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM still means the process may be alive; only ESRCH proves absence.
+        if (err?.code === "EPERM")
+            return true;
+        return false;
+    }
+}
+// Descriptors outlive crashes and reboots, so a recorded pid may since belong to an unrelated process.
+export function brokerLiveness(descriptor) {
+    if (IS_WINDOWS || !isPidAlive(descriptor.pid) || typeof descriptor.transportUrl !== "string")
+        return "dead";
+    try {
+        const args = execFileSync("ps", ["-ww", "-o", "args=", "-p", String(descriptor.pid)], {
+            encoding: "utf-8",
+            timeout: 2000,
+        });
+        return isBrokerCommand(args, descriptor.transportUrl) ? "live" : "dead";
+    }
+    catch {
+        // ps also exits non-zero when the pid exited after the liveness probe.
+        return isPidAlive(descriptor.pid) ? "unknown" : "dead";
+    }
+}
+function isBrokerCommand(args, transportUrl) {
+    const argv = args.trim().split(/\s+/);
+    const at = argv.indexOf("app-server");
+    return (at > 0 &&
+        /^codex(\.\w+)?$/.test(basename(argv[at - 1])) &&
+        argv.slice(at + 1).join(" ") === `--listen ${transportUrl}`);
+}
+function findBrokerPids(transportUrl) {
+    if (IS_WINDOWS)
+        return [];
+    try {
+        const table = execFileSync("ps", ["-ax", "-ww", "-o", "pid=,args="], { encoding: "utf-8", timeout: 2000 });
+        return table.split("\n").flatMap((line) => {
+            const row = line.match(/^\s*(\d+)\s+(.*)$/);
+            return row && isBrokerCommand(row[2], transportUrl) ? [Number(row[1])] : [];
+        });
+    }
+    catch {
+        return null;
+    }
+}
+async function killPidGracefully(pid, graceMs) {
+    if (!isPidAlive(pid))
+        return false;
+    try {
+        if (IS_WINDOWS) {
+            // Windows has no graceful SIGTERM path.
+            terminateProcessTree({ pid, killed: false, exitCode: null }, "SIGTERM");
+            return true;
+        }
+        // The detached POSIX process group receives SIGTERM.
+        try {
+            process.kill(-pid, "SIGTERM");
+        }
+        catch {
+            // Group gone — try direct pid signal.
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch {
+                return false;
+            }
+        }
+        // Poll for exit
+        const deadline = Date.now() + graceMs;
+        while (Date.now() < deadline) {
+            if (!isPidAlive(pid))
+                return true;
+            await sleep(50);
+        }
+        // Still alive — escalate to SIGKILL via terminateProcessTree
+        terminateProcessTree({ pid, killed: false, exitCode: null }, "SIGKILL");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Validate socket ancestry before unlinking a descriptor-provided path.
+async function unlinkTransportArtifact(transportUrl, markerDir) {
+    const safePath = extractSafeSocketPath(transportUrl, markerDir);
+    if (safePath === null)
+        return;
+    try {
+        await unlink(safePath);
+    }
+    catch {
+        // already gone — fine
+    }
+}
+// Reclaim stale descriptors after dead PIDs, protocol changes, or missing sockets.
+export function clearStaleBrokerState(markerDir) {
+    const descriptor = readBrokerDescriptorSync(markerDir);
+    if (!descriptor)
+        return "absent";
+    const alive = isPidAlive(descriptor.pid);
+    const protoOk = descriptor.protocolVersion === BROKER_PROTOCOL_VERSION;
+    // Reject unknown transports and Unix sockets outside the recorded state boundary.
+    let socketOk;
+    let sockPath = null;
+    if (typeof descriptor.transportUrl !== "string") {
+        socketOk = false;
+    }
+    else if (descriptor.transportUrl.startsWith("unix://")) {
+        sockPath = extractSafeSocketPath(descriptor.transportUrl, markerDir, descriptor.isolatedHome);
+        if (sockPath === null) {
+            socketOk = false; // unix:// outside bounds — descriptor was tampered
+        }
+        else {
+            try {
+                statSync(sockPath);
+                socketOk = true;
+            }
+            catch {
+                socketOk = false;
+            }
+        }
+    }
+    else if (descriptor.transportUrl.startsWith("ws://")) {
+        socketOk = true; // assume live; per-edit probeBrokerHealth validates
+    }
+    else {
+        socketOk = false; // unrecognized scheme
+    }
+    if (alive && protoOk && socketOk)
+        return "live";
+    // Stale — clean up. Best-effort; failures are silent per ADR-077.
+    try {
+        unlinkSync(join(stateRoot(markerDir), "broker.json"));
+    }
+    catch { }
+    if (sockPath !== null) {
+        try {
+            unlinkSync(sockPath);
+        }
+        catch { }
+    }
+    return "stale";
+}
+// Only unlink sockets under the isolated home or legacy marker state root.
+function extractSafeSocketPath(transportUrl, markerDir, isolatedHome) {
+    if (typeof transportUrl !== "string" || !transportUrl.startsWith("unix://")) {
+        return null;
+    }
+    const sockPath = transportUrl.slice("unix://".length);
+    if (!sockPath)
+        return null;
+    const resolvedSock = resolvePath(sockPath);
+    const roots = [resolvePath(stateRoot(markerDir))];
+    if (isIsolatedBrokerHome(isolatedHome))
+        roots.push(resolvePath(isolatedHome));
+    return roots.some((root) => resolvedSock.startsWith(`${root}/`)) ? resolvedSock : null;
+}
+// SessionEnd teardown is best-effort and must not fail the hook.
+export async function teardownBroker(markerDir, options = {}) {
+    const { graceMs = 1500, injectDeps } = options;
+    const unlinkSockFn = injectDeps?.unlinkSock ?? unlinkTransportArtifact;
+    const lockPath = options.lockHeld ? brokerLockPath(markerDir) : acquireBrokerLock(markerDir);
+    if (!lockPath)
+        return null;
+    try {
+        const descriptor = readBrokerDescriptorSync(markerDir);
+        if (!descriptor || ("sessionId" in options && (!options.sessionId || descriptor.sessionId !== options.sessionId))) {
+            return null;
+        }
+        if (options.onlyIfCredentialMissing) {
+            if (!isIsolatedBrokerHome(descriptor.isolatedHome))
+                return null;
+            let source = null;
+            try {
+                source = readlinkSync(join(descriptor.isolatedHome, "auth.json"));
+                statSync(resolvePath(descriptor.isolatedHome, source));
+                return null;
+            }
+            catch (error) {
+                if (!source || error.code !== "ENOENT")
+                    return null;
+            }
+        }
+        // An unverified pid is never signaled, and its state is kept so the broker is not orphaned.
+        const liveness = (injectDeps?.brokerLiveness ?? brokerLiveness)(descriptor);
+        if (liveness === "unknown")
+            return null;
+        try {
+            if (liveness === "live")
+                await (injectDeps?.killPid ?? killPidGracefully)(descriptor.pid, graceMs);
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            await unlinkSockFn(descriptor.transportUrl, markerDir);
+        }
+        catch {
+            // best-effort
+        }
+        await unlinkBrokerDescriptor(markerDir);
+        removeIsolatedBrokerHome(descriptor.isolatedHome);
+        return descriptor;
+    }
+    finally {
+        if (!options.lockHeld)
+            releaseBrokerLock(lockPath);
+    }
+}
+// Test-only exports
+export const __testing__ = {
+    BROKER_LOCK_DIR,
+    BROKER_LOG_FILE,
+    BROKER_SOCKET_FILE,
+    MAX_UNIX_SOCKET_PATH_BYTES,
+    BOOTSTRAP_BUDGET_MS_DEFAULT,
+    isPidAlive,
+    killPidGracefully,
+    unlinkTransportArtifact,
+};