larkin 0.2.70

package/dist/app/local-control.mjs

@@ -0,0 +1,728 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import { RuntimePrerequisiteError } from "../runtime/runtime-readiness.mjs";
+import os from "node:os";
+import path from "node:path";
+import { readProcessState } from "../platform/process-state.mjs";
+import { currentProcessMetadata } from "../platform/process-inspect.cjs";
+import { processCommandToken } from "./internal-command.mjs";
+const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
+const OPERATION_ID = /^[A-Za-z0-9_-]{8,128}$/;
+const AUTHORIZATION = /^[A-Za-z0-9_-]{43,128}$/;
+const UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
+function socketPathsFit(root) {
+    return ["supervisor.sock", "daemon.sock"].every((name) => Buffer.byteLength(path.join(root, name)) <= UNIX_SOCKET_PATH_MAX_BYTES);
+}
+function controlSocketRoot(larkinHome) {
+    const owner = typeof process.getuid === "function" ? process.getuid() : "user";
+    const identity = crypto.createHash("sha256").update(path.resolve(larkinHome)).digest("hex").slice(0, 16);
+    const leaf = `lk-${owner}-${identity}`;
+    const preferred = path.join(path.resolve(os.tmpdir()), leaf);
+    if (socketPathsFit(preferred))
+        return preferred;
+    const fallback = path.join("/tmp", leaf);
+    if (socketPathsFit(fallback))
+        return fallback;
+    throw new Error("无法生成满足 Unix socket 长度限制的 control root");
+}
+function assertSecureSocketDirectory(root) {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o077) !== 0)
+        throw new Error("control socket root 不安全");
+    return root;
+}
+function ensureSecureSocketRoot(larkinHome) {
+    const root = controlSocketRoot(larkinHome);
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    return assertSecureSocketDirectory(root);
+}
+export function controlSocketPath(larkinHome) {
+    return path.join(controlSocketRoot(larkinHome), "daemon.sock");
+}
+export function controlAuthorityPath(larkinHome) {
+    return path.join(path.resolve(larkinHome), "daemon-control-auth.json");
+}
+export function supervisorControlSocketPath(larkinHome) {
+    return path.join(controlSocketRoot(larkinHome), "supervisor.sock");
+}
+function assertSecureRoot(root) {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o077) !== 0)
+        throw new Error("Larkin config root 必须由当前用户拥有且不可被其他用户访问");
+}
+function removeLegacyResetLedger(larkinHome) {
+    const file = path.join(path.resolve(larkinHome), "daemon-control-operations.json");
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid()) || (stat.mode & 0o077) !== 0) {
+        throw new Error("legacy daemon control operation ledger 不安全");
+    }
+    fs.unlinkSync(file);
+}
+function parseRequest(line) {
+    const value = JSON.parse(line);
+    if (!AGENT_ID.test(String(value.agentId || "")) || !AUTHORIZATION.test(String(value.authorization || ""))) {
+        throw new Error("invalid agent control request");
+    }
+    if (value.operation === "session-reset") {
+        if (value.waitReadyMs !== undefined && (!Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
+            throw new Error("invalid session reset waitReadyMs");
+        }
+        if (Object.keys(value).some((key) => !["agentId", "authorization", "operation", "waitReadyMs"].includes(key))) {
+            throw new Error("session reset control request 包含未知字段");
+        }
+        return value;
+    }
+    if (value.operation !== undefined || !OPERATION_ID.test(String(value.operationId || ""))) {
+        throw new Error("invalid agent upsert request");
+    }
+    if (value.waitReadyMs !== undefined) {
+        throw new Error("invalid session reset waitReadyMs");
+    }
+    if (Object.keys(value).some((key) => !["operationId", "agentId", "authorization"].includes(key))) {
+        throw new Error("agent control request 包含未知字段");
+    }
+    return value;
+}
+function atomicWritePrivateJson(file, value) {
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temporary, file);
+}
+function secureAuthority(larkinHome) {
+    assertSecureRoot(larkinHome);
+    const file = controlAuthorityPath(larkinHome);
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o077) !== 0)
+        throw new Error("daemon control authority 不安全");
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    const validBinding = (binding) => !!binding && Number.isSafeInteger(binding.pid) && binding.pid > 0
+        && typeof binding.processStartToken === "string" && binding.processStartToken.length > 0;
+    const validSocketBinding = (binding) => !!binding && /^\d+$/.test(binding.device) && /^\d+$/.test(binding.inode)
+        && /^\d+$/.test(binding.owner) && /^\d+$/.test(binding.changeTimeNs);
+    const socketRoot = String(value.socketRoot || "");
+    const supervisorSocket = String(value.supervisorSocketPath || "");
+    const daemonSocket = String(value.daemonSocketPath || "");
+    const validSocketPaths = path.isAbsolute(socketRoot)
+        && path.resolve(socketRoot) === socketRoot
+        && socketPathsFit(socketRoot)
+        && path.dirname(supervisorSocket) === socketRoot && path.basename(supervisorSocket) === "supervisor.sock"
+        && path.dirname(daemonSocket) === socketRoot && path.basename(daemonSocket) === "daemon.sock";
+    if (value.version !== 2 || !AUTHORIZATION.test(String(value.token || "")) || !validBinding(value.supervisor)
+        || !validSocketPaths
+        || (value.supervisorSocket !== undefined && !validSocketBinding(value.supervisorSocket))
+        || (value.daemon !== undefined && !validBinding(value.daemon))
+        || (value.daemonSocket !== undefined && (!value.daemon || !validSocketBinding(value.daemonSocket)))) {
+        throw new Error("daemon control authority 无效");
+    }
+    return value;
+}
+function sameSecret(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+function bindingMatches(binding, record) {
+    return binding.pid === Number(record.pid) && binding.processStartToken === record.processStartToken;
+}
+function socketBinding(stat) {
+    return {
+        device: String(stat.dev),
+        inode: String(stat.ino),
+        owner: String(stat.uid),
+        changeTimeNs: String(stat.ctimeNs),
+    };
+}
+function socketObjectMatches(binding, stat) {
+    return binding.device === String(stat.dev) && binding.inode === String(stat.ino)
+        && binding.owner === String(stat.uid);
+}
+function socketBindingMatches(binding, stat) {
+    return socketObjectMatches(binding, stat) && binding.changeTimeNs === String(stat.ctimeNs);
+}
+function inspectOwnedSocket(socket) {
+    const stat = fs.lstatSync(socket, { bigint: true });
+    if (!stat.isSocket() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== BigInt(process.getuid()))) {
+        throw new Error("control socket identity 不安全");
+    }
+    return { stat, binding: socketBinding(stat) };
+}
+function assertLiveAuthority(larkinHome, expectedToken) {
+    const authority = secureAuthority(larkinHome);
+    if (expectedToken && !sameSecret(authority.token, expectedToken))
+        throw new Error("daemon control authorization 已失效");
+    const { supervisor, daemon } = readProcessState(larkinHome);
+    if (supervisor.state !== "owned" || !bindingMatches(authority.supervisor, supervisor)) {
+        throw new Error("daemon control supervisor identity 已失效");
+    }
+    if (!authority.daemon || daemon.state !== "owned" || !bindingMatches(authority.daemon, daemon)) {
+        throw new Error("daemon control daemon identity 已失效");
+    }
+    return authority;
+}
+function assertSupervisorAuthority(larkinHome, expectedToken) {
+    const authority = secureAuthority(larkinHome);
+    if (expectedToken && !sameSecret(authority.token, expectedToken))
+        throw new Error("supervisor control authorization 已失效");
+    const supervisor = readProcessState(larkinHome).supervisor;
+    if (supervisor.state !== "owned" || !bindingMatches(authority.supervisor, supervisor)) {
+        throw new Error("supervisor control identity 已失效");
+    }
+    return authority;
+}
+function prepareSocket(socket) {
+    try {
+        const stat = fs.lstatSync(socket);
+        if (!stat.isSocket() || stat.isSymbolicLink()
+            || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+            throw new Error("control socket 路径被不安全文件占用");
+        }
+        fs.unlinkSync(socket);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function cleanupSocketRoot(root) {
+    try {
+        fs.rmdirSync(root);
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTEMPTY"].includes(String(error.code || "")))
+            throw error;
+    }
+}
+async function closePrivateServer(server, socket, identity) {
+    let shield = null;
+    let closeError;
+    try {
+        let current = null;
+        try {
+            current = fs.lstatSync(socket, { bigint: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (current && (!identity || !socketBindingMatches(identity, current))) {
+            // The runtime unlinks its original Unix pathname during server.close(). Move a
+            // replacement entry aside so closing the old server cannot delete it.
+            shield = `${socket}.replacement-${crypto.randomUUID()}`;
+            fs.renameSync(socket, shield);
+        }
+        if (server.listening) {
+            await new Promise((resolve) => server.close((error) => {
+                if (error)
+                    closeError = error;
+                resolve();
+            }));
+        }
+        if (!shield && identity) {
+            try {
+                const after = fs.lstatSync(socket, { bigint: true });
+                if (after.isSocket() && !after.isSymbolicLink() && socketBindingMatches(identity, after))
+                    fs.unlinkSync(socket);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+    finally {
+        if (shield) {
+            try {
+                fs.lstatSync(socket);
+                throw new Error(`replacement socket 恢复失败，原路径已被再次占用；保留于 ${shield}`);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    fs.renameSync(shield, socket);
+                else
+                    throw error;
+            }
+        }
+        cleanupSocketRoot(path.dirname(socket));
+    }
+    if (closeError)
+        throw closeError;
+}
+async function listenPrivate(server, socket) {
+    let identity = null;
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(socket, () => { server.off("error", reject); resolve(); });
+        });
+        identity = inspectOwnedSocket(socket).binding;
+        const deadline = Date.now() + 1_000;
+        for (;;) {
+            try {
+                fs.chmodSync(socket, 0o600);
+                break;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT" || Date.now() >= deadline)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        }
+        const secured = inspectOwnedSocket(socket);
+        if (!socketObjectMatches(identity, secured.stat)) {
+            throw new Error("control socket 在权限收紧期间被其他 server 替换");
+        }
+        identity = secured.binding;
+        return identity;
+    }
+    catch (error) {
+        await closePrivateServer(server, socket, identity);
+        throw error;
+    }
+}
+export function initializeControlAuthority(larkinHome, supervisor) {
+    fs.mkdirSync(larkinHome, { recursive: true, mode: 0o700 });
+    assertSecureRoot(larkinHome);
+    const socketRoot = ensureSecureSocketRoot(larkinHome);
+    const token = crypto.randomBytes(32).toString("base64url");
+    atomicWritePrivateJson(controlAuthorityPath(larkinHome), {
+        version: 2,
+        token,
+        socketRoot,
+        supervisorSocketPath: path.join(socketRoot, "supervisor.sock"),
+        daemonSocketPath: path.join(socketRoot, "daemon.sock"),
+        supervisor,
+    });
+    return token;
+}
+export function removeControlAuthority(larkinHome, expectedToken) {
+    try {
+        const authority = secureAuthority(larkinHome);
+        if (sameSecret(authority.token, expectedToken)) {
+            fs.unlinkSync(controlAuthorityPath(larkinHome));
+            cleanupSocketRoot(authority.socketRoot);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function createSupervisorControlServer({ larkinHome, authorityToken, ensureDashboard, }) {
+    let socket = "";
+    let socketRoot = "";
+    let socketIdentity = null;
+    const completed = new Map();
+    let server = null;
+    return {
+        async start() {
+            const authority = assertSupervisorAuthority(larkinHome, authorityToken);
+            socketRoot = assertSecureSocketDirectory(authority.socketRoot);
+            socket = authority.supervisorSocketPath;
+            prepareSocket(socket);
+            server = net.createServer((connection) => {
+                connection.setEncoding("utf8");
+                let input = "";
+                connection.on("data", (chunk) => {
+                    input += chunk;
+                    if (input.length > 4096)
+                        connection.destroy(new Error("control request too large"));
+                    const newline = input.indexOf("\n");
+                    if (newline < 0)
+                        return;
+                    const line = input.slice(0, newline);
+                    input = "";
+                    void (async () => {
+                        let request;
+                        try {
+                            request = JSON.parse(line);
+                            if (!OPERATION_ID.test(String(request.operationId || "")) || request.operation !== "ensure-dashboard"
+                                || !AUTHORIZATION.test(String(request.authorization || ""))
+                                || Object.keys(request).some((key) => !["operationId", "operation", "authorization"].includes(key))) {
+                                throw new Error("invalid supervisor control request");
+                            }
+                            const authority = assertSupervisorAuthority(larkinHome, authorityToken);
+                            if (!sameSecret(authority.token, request.authorization))
+                                throw new Error("unauthorized supervisor control request");
+                        }
+                        catch {
+                            connection.end(`${JSON.stringify({ ok: false, operationId: "invalid", error: "unauthorized supervisor control request" })}\n`);
+                            return;
+                        }
+                        const replay = completed.get(request.operationId);
+                        if (replay) {
+                            connection.end(`${JSON.stringify(replay)}\n`);
+                            return;
+                        }
+                        let response;
+                        try {
+                            response = { ok: true, operationId: request.operationId, state: await ensureDashboard() };
+                        }
+                        catch (error) {
+                            response = { ok: false, operationId: request.operationId, error: error instanceof Error ? error.message : String(error) };
+                        }
+                        completed.set(request.operationId, response);
+                        while (completed.size > 256)
+                            completed.delete(completed.keys().next().value);
+                        connection.end(`${JSON.stringify(response)}\n`);
+                    })();
+                });
+            });
+            try {
+                socketIdentity = await listenPrivate(server, socket);
+                const liveAuthority = secureAuthority(larkinHome);
+                if (!sameSecret(liveAuthority.token, authorityToken))
+                    throw new Error("supervisor control authorization 已失效");
+                atomicWritePrivateJson(controlAuthorityPath(larkinHome), {
+                    ...liveAuthority,
+                    supervisorSocket: socketIdentity,
+                });
+            }
+            catch (error) {
+                if (server && socketIdentity)
+                    await closePrivateServer(server, socket, socketIdentity);
+                server = null;
+                socketIdentity = null;
+                throw error;
+            }
+        },
+        async close() {
+            const active = server;
+            server = null;
+            if (active && socket)
+                await closePrivateServer(active, socket, socketIdentity);
+            else if (socketRoot)
+                cleanupSocketRoot(socketRoot);
+            socketIdentity = null;
+        },
+    };
+}
+export function createAgentControlServer({ larkinHome, authorityToken, upsert, resetSession, maxRememberedOperations = 256, }) {
+    let socket = "";
+    let socketRoot = "";
+    let socketIdentity = null;
+    const completed = new Map();
+    const inFlight = new Map();
+    const resetInFlight = new Map();
+    const agentQueues = new Map();
+    const upsertConflict = (operationId, agentId) => ({
+        ok: false, operationId, agentId, code: "operation_conflict", error: "operationId 已绑定其他 Agent 或操作",
+    });
+    let server = null;
+    return {
+        async start() {
+            fs.mkdirSync(larkinHome, { recursive: true, mode: 0o700 });
+            assertSecureRoot(larkinHome);
+            removeLegacyResetLedger(larkinHome);
+            const authority = secureAuthority(larkinHome);
+            if (!sameSecret(authority.token, authorityToken))
+                throw new Error("daemon control authorization 不匹配");
+            const supervisor = readProcessState(larkinHome).supervisor;
+            if (supervisor.state !== "owned" || !bindingMatches(authority.supervisor, supervisor)) {
+                throw new Error("daemon control supervisor identity 无效");
+            }
+            const daemonMetadata = currentProcessMetadata(processCommandToken("daemon", "app/runtime-process.mjs"));
+            if (!daemonMetadata.processStartToken)
+                throw new Error("daemon control 无法取得 daemon start identity");
+            atomicWritePrivateJson(controlAuthorityPath(larkinHome), {
+                ...authority,
+                daemon: { pid: process.pid, processStartToken: daemonMetadata.processStartToken },
+            });
+            socketRoot = assertSecureSocketDirectory(authority.socketRoot);
+            socket = authority.daemonSocketPath;
+            prepareSocket(socket);
+            server = net.createServer((connection) => {
+                connection.setEncoding("utf8");
+                let input = "";
+                connection.on("data", (chunk) => {
+                    input += chunk;
+                    if (input.length > 4096)
+                        connection.destroy(new Error("control request too large"));
+                    const newline = input.indexOf("\n");
+                    if (newline < 0)
+                        return;
+                    const line = input.slice(0, newline);
+                    input = "";
+                    void (async () => {
+                        let request;
+                        try {
+                            request = parseRequest(line);
+                        }
+                        catch (error) {
+                            connection.end(`${JSON.stringify({ ok: false, agentId: "invalid", error: error.message })}\n`);
+                            return;
+                        }
+                        try {
+                            const live = assertLiveAuthority(larkinHome, authorityToken);
+                            if (!sameSecret(live.token, request.authorization))
+                                throw new Error("unauthorized control request");
+                        }
+                        catch {
+                            connection.end(`${JSON.stringify({ ok: false, ...("operation" in request ? {} : { operationId: request.operationId }),
+                                agentId: request.agentId, error: "unauthorized control request" })}\n`);
+                            return;
+                        }
+                        if ("operation" in request) {
+                            const resetRequest = request;
+                            let operation = resetInFlight.get(resetRequest.agentId);
+                            if (!operation) {
+                                const executeReset = async () => {
+                                    try {
+                                        if (!resetSession)
+                                            throw new Error("session reset control unavailable");
+                                        return await resetSession({ agentId: resetRequest.agentId, waitReadyMs: resetRequest.waitReadyMs ?? 30_000 });
+                                    }
+                                    catch (error) {
+                                        const code = typeof error.code === "string"
+                                            ? String(error.code)
+                                            : error instanceof RuntimePrerequisiteError && error.readiness.state === "unavailable"
+                                                ? "runtime_unavailable" : "reset_refused";
+                                        const projection = error;
+                                        return { ok: false, agentId: resetRequest.agentId, code,
+                                            error: error instanceof Error ? error.message : String(error), resetCommitted: false,
+                                            generationChanged: false, sessionChanged: false,
+                                            turns: Math.max(0, Number(projection.turns) || 0), runtimeReady: projection.runtimeReady === true,
+                                            channelConnected: projection.channelConnected === true, reconnecting: projection.reconnecting === true,
+                                            pendingCount: Math.max(0, Number(projection.pendingCount) || 0),
+                                            readyForFreshScenario: false, inboundObserved: false,
+                                            ...(error instanceof RuntimePrerequisiteError ? { readiness: error.readiness } : {}) };
+                                    }
+                                };
+                                const prior = agentQueues.get(resetRequest.agentId) ?? Promise.resolve();
+                                const executing = prior.catch(() => { }).then(executeReset);
+                                let queued;
+                                queued = executing.finally(() => {
+                                    if (agentQueues.get(resetRequest.agentId) === queued)
+                                        agentQueues.delete(resetRequest.agentId);
+                                    if (resetInFlight.get(resetRequest.agentId) === queued)
+                                        resetInFlight.delete(resetRequest.agentId);
+                                });
+                                agentQueues.set(resetRequest.agentId, queued);
+                                resetInFlight.set(resetRequest.agentId, queued);
+                                operation = queued;
+                            }
+                            const response = await operation;
+                            connection.end(`${JSON.stringify(response)}\n`);
+                            return;
+                        }
+                        const upsertRequest = request;
+                        const replay = completed.get(upsertRequest.operationId);
+                        if (replay) {
+                            connection.end(`${JSON.stringify(replay.agentId === upsertRequest.agentId
+                                ? replay : upsertConflict(upsertRequest.operationId, upsertRequest.agentId))}\n`);
+                            return;
+                        }
+                        const existing = inFlight.get(upsertRequest.operationId);
+                        if (existing && existing.agentId !== upsertRequest.agentId) {
+                            connection.end(`${JSON.stringify(upsertConflict(upsertRequest.operationId, upsertRequest.agentId))}\n`);
+                            return;
+                        }
+                        const execute = async () => {
+                            try {
+                                await upsert({ operationId: upsertRequest.operationId, agentId: upsertRequest.agentId });
+                                return { ok: true, operationId: upsertRequest.operationId, agentId: upsertRequest.agentId };
+                            }
+                            catch (error) {
+                                return { ok: false, operationId: upsertRequest.operationId, agentId: upsertRequest.agentId,
+                                    error: error instanceof Error ? error.message : String(error),
+                                    ...(error instanceof RuntimePrerequisiteError ? { readiness: error.readiness } : {}) };
+                            }
+                        };
+                        let operation = existing?.response;
+                        if (!operation) {
+                            const prior = agentQueues.get(upsertRequest.agentId) ?? Promise.resolve();
+                            operation = prior.catch(() => { }).then(execute);
+                            const queued = operation.finally(() => {
+                                if (agentQueues.get(upsertRequest.agentId) === queued)
+                                    agentQueues.delete(upsertRequest.agentId);
+                            });
+                            agentQueues.set(upsertRequest.agentId, queued);
+                            inFlight.set(upsertRequest.operationId, { agentId: upsertRequest.agentId, response: operation });
+                        }
+                        const response = await operation;
+                        inFlight.delete(upsertRequest.operationId);
+                        completed.set(upsertRequest.operationId, response);
+                        while (completed.size > maxRememberedOperations)
+                            completed.delete(completed.keys().next().value);
+                        connection.end(`${JSON.stringify(response)}\n`);
+                    })();
+                });
+            });
+            try {
+                socketIdentity = await listenPrivate(server, socket);
+                const liveAuthority = secureAuthority(larkinHome);
+                if (!sameSecret(liveAuthority.token, authorityToken))
+                    throw new Error("daemon control authorization 已失效");
+                atomicWritePrivateJson(controlAuthorityPath(larkinHome), {
+                    ...liveAuthority,
+                    daemonSocket: socketIdentity,
+                });
+            }
+            catch (error) {
+                if (server && socketIdentity)
+                    await closePrivateServer(server, socket, socketIdentity);
+                server = null;
+                socketIdentity = null;
+                throw error;
+            }
+        },
+        async close() {
+            const active = server;
+            server = null;
+            if (active && socket)
+                await closePrivateServer(active, socket, socketIdentity);
+            else if (socketRoot)
+                cleanupSocketRoot(socketRoot);
+            socketIdentity = null;
+        },
+    };
+}
+async function sendSupervisorRecovery(larkinHome, operationId, timeoutMs) {
+    const authority = assertSupervisorAuthority(larkinHome);
+    assertSecureSocketDirectory(authority.socketRoot);
+    const socket = authority.supervisorSocketPath;
+    const stat = fs.lstatSync(socket);
+    if (!stat.isSocket() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o077) !== 0)
+        throw new Error("supervisor control socket 不安全");
+    return await new Promise((resolve, reject) => {
+        const client = net.createConnection(socket);
+        const timer = setTimeout(() => { client.destroy(); reject(new Error("dashboard recovery control timeout")); }, timeoutMs);
+        let input = "";
+        client.setEncoding("utf8");
+        client.once("error", (error) => { clearTimeout(timer); reject(error); });
+        client.once("connect", () => client.write(`${JSON.stringify({
+            operationId, operation: "ensure-dashboard", authorization: authority.token,
+        })}\n`));
+        client.on("data", (chunk) => {
+            input += chunk;
+            const newline = input.indexOf("\n");
+            if (newline < 0)
+                return;
+            clearTimeout(timer);
+            client.end();
+            try {
+                resolve(JSON.parse(input.slice(0, newline)));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+export async function requestDashboardRecovery({ larkinHome, operationId = crypto.randomUUID(), timeoutMs = 30_000, }) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            return await sendSupervisorRecovery(larkinHome, operationId, Math.max(100, deadline - Date.now()));
+        }
+        catch (error) {
+            lastError = error;
+            const code = error.code;
+            if (!code || !["ENOENT", "ECONNREFUSED"].includes(code))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("supervisor control unavailable");
+}
+async function requestAgentControl({ larkinHome, timeoutMs = 30_000, request, }) {
+    const { supervisor, daemon } = readProcessState(larkinHome);
+    if (supervisor.state !== "owned")
+        throw new Error(`supervisor control ownership=${supervisor.state}（${supervisor.reason}）`);
+    if (daemon.state !== "owned")
+        throw new Error(`daemon control ownership=${daemon.state}（${daemon.reason}）`);
+    const authority = assertLiveAuthority(larkinHome);
+    assertSecureSocketDirectory(authority.socketRoot);
+    const socket = authority.daemonSocketPath;
+    const stat = fs.lstatSync(socket);
+    if (!stat.isSocket() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o077) !== 0)
+        throw new Error("daemon control socket 不安全");
+    return await new Promise((resolve, reject) => {
+        const client = net.createConnection(socket);
+        const timer = setTimeout(() => { client.destroy(); reject(new Error("agent control timeout")); }, timeoutMs);
+        let input = "";
+        client.setEncoding("utf8");
+        client.once("error", (error) => { clearTimeout(timer); reject(error); });
+        client.once("connect", () => client.write(`${JSON.stringify({ ...request, authorization: authority.token })}\n`));
+        client.on("data", (chunk) => {
+            input += chunk;
+            const newline = input.indexOf("\n");
+            if (newline < 0)
+                return;
+            clearTimeout(timer);
+            client.end();
+            try {
+                resolve(JSON.parse(input.slice(0, newline)));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+export async function requestAgentUpsert(input) {
+    return requestAgentControl({ larkinHome: input.larkinHome, timeoutMs: input.timeoutMs,
+        request: { operationId: input.operationId ?? crypto.randomUUID(), agentId: input.agentId } });
+}
+export async function requestSessionReset({ larkinHome, agentId, waitReadyMs = 30_000, }) {
+    return requestAgentControl({
+        larkinHome, timeoutMs: Math.max(1_000, waitReadyMs + 1_000),
+        request: { operation: "session-reset", agentId, waitReadyMs },
+    });
+}
+export function cleanupStaleAgentControlSocket(larkinHome, expectedToken) {
+    const authority = secureAuthority(larkinHome);
+    if (!sameSecret(authority.token, expectedToken))
+        throw new Error("daemon control authorization 已失效");
+    const root = assertSecureSocketDirectory(authority.socketRoot);
+    const socket = authority.daemonSocketPath;
+    if (path.dirname(socket) !== root || path.basename(socket) !== "daemon.sock") {
+        throw new Error("daemon control socket 路径不属于认证 control root");
+    }
+    try {
+        const stat = fs.lstatSync(socket, { bigint: true });
+        if (!stat.isSocket() || stat.isSymbolicLink()
+            || (typeof process.getuid === "function" && stat.uid !== BigInt(process.getuid()))) {
+            throw new Error("拒绝清理不安全的 daemon control socket");
+        }
+        if (!authority.daemonSocket || !socketBindingMatches(authority.daemonSocket, stat)) {
+            throw new Error("拒绝清理已被其他 server 替换的 daemon control socket");
+        }
+        fs.unlinkSync(socket);
+        cleanupSocketRoot(root);
+        return "removed";
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        cleanupSocketRoot(root);
+        return "absent";
+    }
+}