@realqiyan/agent-task 0.0.1-rc.1 → 0.0.1-rc.2

package/README.md

@@ -9,7 +9,7 @@
 | 目的 | 入口 |
 | --- | --- |
 | 安装、认证、后台运行、卸载 | [部署说明](docs/deployment.md) |
-| 本机控制台、配置保存与手动重启 | [控制台说明](docs/web-console.md) |
+| 本机控制台、配置保存与 Web/CLI 重启 | [控制台说明](docs/web-console.md) |
 | 理解产品目标和架构选择 | [总体方案](docs/design-proposal.md) |
 | 查找实现与对应测试 | [代码导航](docs/technical-design.md) |
 | 查询测试命令、真实验收及缺口 | [验证说明](docs/validation.md) |
@@ -20,7 +20,7 @@
 
 ## 使用入口
 
-Linux/macOS，Node.js **22.19+**。安装包自带运行产物，无需克隆或编译。发布目标为 `0.0.1-rc.1`，使用 `latest`；实际发布与平台验收状态见[发布证据](docs/validation.md#npm-发布候选验证)。
+Linux/macOS，Node.js **22.19+**。安装包自带运行产物，无需克隆或编译。`latest` 指向的已发布版本及平台验收范围见[发布证据](docs/validation.md#npm-发布候选验证)。
 
 ```bash
 npm install -g @realqiyan/agent-task
@@ -28,6 +28,8 @@ agent-task setup
 agent-task start
 # 另一个终端进行带认证的健康检查：
 agent-task status
+# 应用已保存配置并确认新实例可用：
+agent-task restart
 ```
 
 npm 包名为 `@realqiyan/agent-task`，安装后的命令仍为 `agent-task`。setup 提供交互配置；启动后可使用本机 Web 控制台。先停止前台实例，再用 `agent-task service install` 安装并启动用户后台服务。安装器不会替用户登录或批准执行端；详细操作见[部署说明](docs/deployment.md)。

package/bin/agent-task.mjs

@@ -4,8 +4,7 @@ import { readFileSync } from "node:fs";
 const help = `Usage: agent-task <command>
   setup [options]           Interactive configuration (setup --help for flags)
   start [--home PATH]        Foreground service using the private installation
-  start --config PATH --environment PATH
-                            Foreground service with explicit private files
+  restart [--home PATH]      Restart foreground or managed runtime; verify readiness
   status [--home PATH]       Authenticated MCP health check; no token printed
   service install [--home PATH]
                             Install/start systemd user service or LaunchAgent
@@ -26,14 +25,10 @@ try {
   } else if (command === "setup" || command === "uninstall") {
     process.argv = [process.execPath, command, ...args];
     await import(`../scripts/${command}.mjs`);
-  } else if (command === "start" && args[0] === "--config") {
-    if (args.length !== 4 || args[2] !== "--environment") throw new Error("Use start --config PATH --environment PATH");
-    process.argv = [process.execPath, "agent-task", ...args];
-    await import("../dist/main.js");
   } else {
     const lib = await import("../scripts/install-lib.mjs");
     const action = command === "service" ? args.shift() : undefined;
-    if (!["start", "status", "service"].includes(command) || (command === "service" && !["install", "remove"].includes(action))) throw new Error(help);
+    if (!["start", "status", "restart", "service"].includes(command) || (command === "service" && !["install", "remove"].includes(action))) throw new Error(help);
     const options = lib.argumentsFor(args);
     if (Object.keys(options).some(key => key !== "home")) throw new Error("Only --home is accepted here");
     const root = lib.installRoot(options);
@@ -45,19 +40,19 @@ try {
       const unlock = lib.operationLock(root);
       try {
         const manifest = lib.readManifest(root);
-        lib.deactivate(manifest);
+        await lib.deactivate(manifest);
         manifest.serviceInstalled = false;
         lib.saveManifest(root, manifest);
         console.log("Owned service removed; configuration, credentials, components and data preserved.");
       } finally { unlock(); }
     } else if (command === "start") {
+      if (lib.readManifest(root).serviceInstalled) throw new Error("Remove the managed service before starting a foreground instance");
       process.argv = [process.execPath, "service-runner", root];
       await import("../scripts/service-runner.mjs");
     } else {
-      const manifest = lib.readManifest(root);
-      if (manifest.phase !== "ready") throw new Error("Installation is not ready");
-      await lib.checkHealth(lib.json(root + "/config.json"), lib.runtimeEnv(manifest));
-      console.log("Authenticated MCP health check passed.");
+      const { controlService } = await import("../dist/launcher.js");
+      const ready = await controlService(root, command);
+      console.log(JSON.stringify({ event: command === "restart" ? "restarted" : "healthy", ...ready }));
     }
   }
 } catch (error) {

package/deploy/agent-task.service.example

@@ -6,10 +6,10 @@ StartLimitBurst=3
 [Service]
 Type=simple
 WorkingDirectory=/absolute/path/to/agent-task
-ExecStart=/absolute/path/to/node /absolute/path/to/agent-task/dist/main.js --config %h/.config/agent-task/config.json --environment %h/.config/agent-task/environment.json
+ExecStart=/absolute/path/to/node /absolute/path/to/agent-task/scripts/service-runner.mjs %h/.local/share/agent-task
 Restart=on-failure
 RestartSec=5
-TimeoutStopSec=15
+TimeoutStopSec=45
 KillMode=control-group
 UMask=0077
 

package/dist/acp.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { setTimeout as delay } from "node:timers/promises";
 import * as acp from "@agentclientprotocol/sdk";
-import { executorEnv } from "./config.js";
+import { executorCommand } from "./executor-runtime.js";
 import { readInputFile } from "./results.js";
 import { permissionDecision } from "./permissions.js";
 import { version } from "./version.js";
@@ -47,10 +47,11 @@ export async function terminateGroup(child) {
     child.stdout?.destroy();
     child.stderr?.destroy();
 }
-export async function openAcp(executor, signal, emit, inputFiles = []) {
+export async function openAcp(executor, signal, emit, resultsRoot, inputFiles = []) {
     signal.throwIfAborted();
-    const child = spawn(executor.command, executor.args, {
-        cwd: executor.cwd, env: executorEnv(executor.envKeys), detached: true, stdio: ["pipe", "pipe", "pipe"],
+    const launch = executorCommand(executor.type, process.env);
+    const child = spawn(launch.command, launch.args, {
+        cwd: executor.cwd, env: process.env, detached: true, stdio: ["pipe", "pipe", "pipe"],
     });
     const controller = new AbortController();
     const cancel = AbortSignal.any([signal, controller.signal]);
@@ -102,7 +103,7 @@ export async function openAcp(executor, signal, emit, inputFiles = []) {
             cancel.throwIfAborted();
             if (ctx.params.sessionId !== sessionId)
                 throw new Error("Wrong input-file session");
-            return { content: readInputFile(executor, inputFiles, ctx.params.path, ctx.params.line ?? 1, ctx.params.limit ?? undefined) };
+            return { content: readInputFile(resultsRoot, inputFiles, ctx.params.path, ctx.params.line ?? 1, ctx.params.limit ?? undefined) };
         }
         catch (error) {
             controller.abort(error);
@@ -111,7 +112,7 @@ export async function openAcp(executor, signal, emit, inputFiles = []) {
     })
         .onRequest(acp.methods.client.session.requestPermission, async (ctx) => {
         const request = ctx.params;
-        const response = permissionDecision(request, executor.permissionAllowlist, cancel.aborted || request.sessionId !== sessionId);
+        const response = permissionDecision(request, cancel.aborted || request.sessionId !== sessionId);
         await report("permission", { tool: request.toolCall.name ?? null, outcome: response.outcome });
         return response;
     })

package/dist/admin.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { loadConfig, validateConfig } from "./config.js";
 import { replacePrivateText } from "./private-files.js";
 import { executorSchema } from "./model.js";
@@ -10,10 +10,10 @@ if (!configPath || !["register", "list"].includes(action ?? "") || (action === "
     throw new Error("Usage: node dist/admin.js list CONFIG | register CONFIG PROFILE.json (service stopped)");
 }
 const path = resolve(configPath), config = loadConfig(path);
-const release = await acquireLock(config.dataDir);
+const release = await acquireLock(dirname(path));
 try {
     if (action === "list") {
-        console.log(JSON.stringify(config.executors.map(({ id, command, args, cwd, envKeys, permissionAllowlist, unattendedApproved, resultReadRoots }) => ({ id, transport: "stdio", command, args, cwd, envKeys, permissionAllowlist, unattendedApproved, resultReadRoots })), null, 2));
+        console.log(JSON.stringify(config.executors.map(executor => ({ ...executor, transport: "stdio" })), null, 2));
     }
     else {
         const profile = executorSchema.parse(JSON.parse(readFileSync(resolve(profilePath), "utf8")));

package/dist/config.js

@@ -1,10 +1,11 @@
-import { readFileSync, realpathSync, statSync, accessSync, constants } from "node:fs";
-import { basename, delimiter, isAbsolute, join } from "node:path";
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { executorSchema } from "./model.js";
+import { readPrivateText } from "./private-files.js";
 export const ADMIN_TOKEN_ENV = "AGENT_TASK_ADMIN_TOKEN";
 const envKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
-const baseEnvKeys = ["PATH", "LANG", "LC_ALL", "TZ"];
+const baseEnvKeys = ["HOME", "PATH", "LANG", "LC_ALL", "TZ", "TMPDIR", "NODE_OPTIONS", "NODE_PATH", "__proto__", "constructor", "prototype"];
 const modelId = z.string().min(1).max(200);
 const coordinatorSchema = z.discriminatedUnion("provider", [
     z.object({ provider: z.enum(["openai", "anthropic", "deepseek"]), model: modelId }).strict(),
@@ -36,22 +37,22 @@ export function coordinatorCredentialEnv(config) {
         case "openai-compatible": return config.apiKeyEnv;
     }
 }
-export function loadConfig(path, environment = process.env) {
+export function loadConfig(path) {
     let value;
     try {
-        value = JSON.parse(readFileSync(path, "utf8"));
+        value = JSON.parse(readPrivateText(path));
     }
     catch {
         throw new Error("Cannot read configuration JSON");
     }
-    return validateConfig(value, environment);
+    return validateConfig(value);
 }
-export function validateConfig(value, environment = process.env) {
+export function validateConfig(value) {
     const config = configSchema.parse(value);
-    if (!isAbsolute(config.dataDir))
-        throw new Error("dataDir must be absolute");
+    if (!isAbsolute(config.dataDir) || /[\x00-\x1f\x7f]/.test(config.dataDir))
+        throw new Error("dataDir must be absolute without control characters");
     const coordinatorKey = config.coordinator ? coordinatorCredentialEnv(config.coordinator) : undefined;
-    if ([...baseEnvKeys, ADMIN_TOKEN_ENV, "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY", coordinatorKey].includes(config.tokenEnv))
+    if (/^(NODE_|LD_|DYLD_)/.test(config.tokenEnv) || [...baseEnvKeys, ADMIN_TOKEN_ENV, "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY", coordinatorKey].includes(config.tokenEnv))
         throw new Error("tokenEnv must be separate from base environment, administrator and model credentials");
     if (coordinatorKey === ADMIN_TOKEN_ENV)
         throw new Error("Administrator token must not be used as a model credential");
@@ -60,54 +61,12 @@ export function validateConfig(value, environment = process.env) {
         if (ids.has(executor.id))
             throw new Error("Duplicate executor ID");
         ids.add(executor.id);
-        if (!isAbsolute(executor.command) || !isAbsolute(executor.cwd))
-            throw new Error("Executor command and cwd must be absolute");
-        if (basename(executor.command) === "pi") {
-            throw new Error(`Executor ${executor.id}: pi CLI is not an ACP server (including --mode rpc). Install pi-acp with npm install -g pi-acp@0.0.34 and configure its absolute executable path.`);
-        }
-        const piCommandOverride = executor.envKeys.includes("PI_ACP_PI_COMMAND") && environment.PI_ACP_PI_COMMAND;
-        if (basename(executor.command) === "pi-acp" && !piCommandOverride && !(environment.PATH ?? "").split(delimiter).some(directory => {
-            if (!isAbsolute(directory))
-                return false;
-            try {
-                const file = join(directory, "pi");
-                accessSync(file, constants.X_OK);
-                return statSync(file).isFile();
-            }
-            catch {
-                return false;
-            }
-        })) {
-            throw new Error(`Executor ${executor.id}: pi-acp requires pi on the executor PATH. Install/configure pi before starting the service.`);
-        }
-        try {
-            executor.command = realpathSync(executor.command);
-            accessSync(executor.command, constants.X_OK);
-        }
-        catch {
-            throw new Error(`Executor ${executor.id}: ACP executable is missing or not executable. Check the administrator-configured absolute command path. For Pi, install npm install -g pi-acp@0.0.34 and use command -v pi-acp to locate it; pi must also be on the executor PATH.`);
-        }
+        if (!isAbsolute(executor.cwd))
+            throw new Error("Executor cwd must be absolute");
         executor.cwd = realpathSync(executor.cwd);
-        if (!statSync(executor.command).isFile() || !statSync(executor.cwd).isDirectory())
-            throw new Error("Invalid executor command or cwd");
-        for (const root of executor.resultReadRoots) {
-            if (!isAbsolute(root) || realpathSync(root) !== root || !statSync(root).isDirectory())
-                throw new Error("Result read roots must be canonical absolute directories");
-        }
-        if (executor.envKeys.includes(config.tokenEnv) || executor.envKeys.includes(ADMIN_TOKEN_ENV))
-            throw new Error("Service or administrator token must not be passed to executors");
-        if (coordinatorKey && executor.envKeys.includes(coordinatorKey))
-            throw new Error("Coordinator credential must not be passed to executors; use separate executor credentials");
+        if (!statSync(executor.cwd).isDirectory())
+            throw new Error("Invalid executor cwd");
     }
     return config;
 }
-/** No shell or wholesale inheritance; secrets are references to administrator-selected environment keys. */
-export function executorEnv(keys, source = process.env) {
-    const env = {};
-    for (const key of new Set(["PATH", "LANG", "LC_ALL", "TZ", ...keys])) {
-        if (key !== ADMIN_TOKEN_ENV && source[key] !== undefined)
-            env[key] = source[key];
-    }
-    return env;
-}
 //# sourceMappingURL=config.js.map

package/dist/environment.js

@@ -1,3 +1,4 @@
+import { ADMIN_TOKEN_ENV, coordinatorCredentialEnv } from "./config.js";
 import { readPrivateText } from "./private-files.js";
 export function parseEnvironment(text) {
     let value;
@@ -15,6 +16,18 @@ export function parseEnvironment(text) {
 export function readEnvironment(path) {
     return parseEnvironment(readPrivateText(path));
 }
+/** Credential names and values must stay separate, including historical token aliases. */
+export function validateServiceEnvironment(config, environment) {
+    const token = environment[config.tokenEnv], adminToken = environment[ADMIN_TOKEN_ENV];
+    if (!token || !/^[!-~]{32,256}$/.test(token))
+        throw new Error("A private service token of 32–256 visible ASCII characters is required");
+    if (adminToken !== undefined && (!/^[!-~]{32,256}$/.test(adminToken) || adminToken === token))
+        throw new Error("Invalid or reused administrator token");
+    const credential = config.coordinator ? environment[coordinatorCredentialEnv(config.coordinator)] : undefined;
+    if (credential && (credential === token || credential === adminToken))
+        throw new Error("Model credentials must be distinct from service and administrator tokens");
+    return { token, adminToken };
+}
 /** Explicit file mode never falls back to inherited shell credentials. */
 export function baseEnvironment(source) {
     return Object.fromEntries(["HOME", "PATH", "LANG", "LC_ALL", "TZ", "TMPDIR"]

package/dist/executor-runtime.js

@@ -0,0 +1,37 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { ADMIN_TOKEN_ENV, coordinatorCredentialEnv } from "./config.js";
+const commands = {
+    pi: { command: "pi-acp", args: [] },
+    codex: { command: "codex-acp", args: [] },
+    claude: { command: "claude-agent-acp", args: [] },
+    opencode: { command: "opencode", args: ["acp"] },
+};
+/** Fixed ACP adapters, resolved in the OS user's native PATH. Never a shell command. */
+export function executorCommand(type, environment) {
+    const find = (name) => {
+        for (const directory of (environment.PATH ?? "").split(delimiter).filter(isAbsolute)) {
+            try {
+                const path = realpathSync(join(directory, name));
+                accessSync(path, constants.X_OK);
+                if (statSync(path).isFile())
+                    return path;
+            }
+            catch { /* Try the next native PATH entry. */ }
+        }
+        throw new Error("Missing ACP dependency on native PATH: " + name);
+    };
+    const entry = commands[type];
+    if (type === "pi")
+        find("pi");
+    return { command: find(entry.command), args: [...entry.args] };
+}
+/** Private service inputs never enter workers, even through an alias with the same value. */
+export function executorEnvironment(native, privateValues, config) {
+    const blocked = new Set([...Object.keys(privateValues), config.tokenEnv, ADMIN_TOKEN_ENV,
+        ...(config.coordinator ? [coordinatorCredentialEnv(config.coordinator)] : [])]);
+    const secrets = new Set([...Object.values(privateValues), ...[...blocked].map(key => native[key])].filter(Boolean));
+    return Object.fromEntries(Object.entries(native).filter(([key, value]) => value !== undefined && !blocked.has(key) && !secrets.has(value) &&
+        !/^(AGENT_TASK_|NODE_|LD_|DYLD_)/.test(key) && key !== "PI_ACP_PI_COMMAND"));
+}
+//# sourceMappingURL=executor-runtime.js.map

package/dist/launcher.js

@@ -0,0 +1,238 @@
+import { fork } from "node:child_process";
+import { createServer, request } from "node:http";
+import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, lstatSync, openSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { acquireLauncherLock } from "./lock.js";
+import { prepareStartup, startupPaths } from "./startup.js";
+import { readEnvironment } from "./environment.js";
+import { loadConfig } from "./config.js";
+function message(child, type, timeout = 30_000) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); child.off("message", receive); child.off("exit", exit); child.off("error", fail); };
+        const fail = () => { cleanup(); reject(new Error("Service process failed before " + type)); };
+        const exit = () => fail();
+        const receive = (value) => { if (value.type === type) {
+            cleanup();
+            resolve(value);
+        } };
+        const timer = setTimeout(() => { cleanup(); reject(new Error("Service timed out before " + type)); }, timeout);
+        child.on("message", receive);
+        child.once("exit", exit);
+        child.once("error", fail);
+    });
+}
+async function stop(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const closed = new Promise(resolve => child.once("close", () => resolve()));
+    child.kill("SIGTERM");
+    const timer = setTimeout(() => child.kill("SIGKILL"), 12_000);
+    try {
+        await closed;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function health(ready, token) {
+    const response = await fetch(ready.url, {
+        method: "POST", headers: { Authorization: "Bearer " + token, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "service_status", arguments: {} } }),
+        signal: AbortSignal.timeout(5000),
+    });
+    const body = await response.json();
+    if (!response.ok || !body.result?.structuredContent?.data?.running)
+        throw new Error("Authenticated health check failed");
+}
+function removeSocket(path) {
+    if (!existsSync(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isSocket() || stat.uid !== process.getuid())
+        throw new Error("Refusing to remove an unowned control socket path");
+    unlinkSync(path);
+}
+function logFile(path) {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.uid !== process.getuid() || (stat.mode & 0o077)) {
+        closeSync(fd);
+        throw new Error("Invalid private log file");
+    }
+    return fd;
+}
+/** Stable owner for foreground and service managers. Only explicit requests restart a child. */
+export async function launch(home, nativeEnvironment) {
+    process.umask(0o077);
+    startupPaths(home); // Also checks private ownership of the locator.
+    const unlock = acquireLauncherLock(home);
+    const socket = join(home, "control.sock"), children = new Set();
+    let current, ready, restarting = true, closing = false;
+    let release;
+    const finished = new Promise(resolve => { release = resolve; });
+    const control = createServer(async (req, res) => {
+        try {
+            if (req.method !== "POST" || !["/status", "/restart"].includes(req.url ?? "")) {
+                res.writeHead(404).end();
+                return;
+            }
+            const result = req.url === "/restart" ? await restart() : await status();
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(result));
+        }
+        catch {
+            res.writeHead(503).end(JSON.stringify({ error: "Service unavailable; inspect private logs and startup files" }));
+        }
+    });
+    const shutdown = async () => {
+        if (closing)
+            return;
+        closing = true;
+        control.close();
+        control.closeAllConnections();
+        await Promise.all([...children].map(stop));
+        try {
+            removeSocket(socket);
+        }
+        finally {
+            unlock();
+            release();
+        }
+    };
+    const signal = () => { void shutdown(); };
+    process.on("SIGINT", signal);
+    process.on("SIGTERM", signal);
+    const start = async () => {
+        const inputs = await prepareStartup(home);
+        if (closing)
+            throw new Error("Launcher is closing");
+        const log = logFile(join(inputs.dataDir, "service.log"));
+        const child = fork(fileURLToPath(new URL("./main.js", import.meta.url)), ["--config", inputs.configPath, "--environment", inputs.environmentPath], {
+            env: { ...nativeEnvironment, AGENT_TASK_INSTANCE_ID: randomUUID() }, execArgv: [], stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+        children.add(child);
+        const output = (chunk) => { appendFileSync(log, chunk); process.stdout.write(chunk); };
+        child.stdout.on("data", output);
+        child.stderr.on("data", output);
+        child.once("close", () => {
+            closeSync(log);
+            children.delete(child);
+            if (current === child && !restarting && !closing) {
+                ready = undefined;
+                process.exitCode = 1;
+                void shutdown();
+            }
+        });
+        child.on("message", (value) => {
+            if (value.type !== "restart")
+                return;
+            if (child !== current || restarting || closing) {
+                child.send({ type: "restarted", error: "Restart already in progress or unavailable" }, () => { });
+                return;
+            }
+            void restart(child).then(value => {
+                if (child.connected)
+                    child.send({ type: "restarted", ready: value }, () => { });
+            }, () => {
+                if (child.connected)
+                    child.send({ type: "restarted", error: "Restart failed; inspect private logs and use CLI restart after correcting startup files" }, () => { });
+            });
+        });
+        try {
+            const value = (await message(child, "ready")).ready;
+            await health(value, inputs.environment[inputs.config.tokenEnv]);
+            current = child;
+            ready = value;
+            return value;
+        }
+        catch (error) {
+            await stop(child);
+            throw error;
+        }
+    };
+    const status = async () => {
+        if (!ready || restarting || closing)
+            throw new Error("Service unavailable");
+        const paths = startupPaths(home), config = loadConfig(paths.configPath), env = readEnvironment(paths.environmentPath);
+        await health(ready, env[config.tokenEnv]);
+        return ready;
+    };
+    const restart = async (requester) => {
+        if (restarting || closing)
+            throw new Error("Restart already in progress or closed");
+        restarting = true;
+        const old = current;
+        current = undefined;
+        ready = undefined;
+        try {
+            if (old) {
+                const drained = message(old, "drained");
+                old.send({ type: "drain" });
+                try {
+                    await drained;
+                }
+                catch (error) {
+                    await stop(old);
+                    throw error;
+                }
+                // Keep only the authenticated Web response alive until the new process is verified.
+                if (old !== requester)
+                    await stop(old);
+            }
+            const value = await start();
+            return value;
+        }
+        finally {
+            restarting = false;
+            if (requester) {
+                const timer = setTimeout(() => { void stop(requester); }, 5000);
+                requester.once("close", () => clearTimeout(timer));
+            }
+        }
+    };
+    try {
+        removeSocket(socket); // Stale socket only, under exclusive launcher ownership.
+        await new Promise((resolve, reject) => { control.once("error", reject); control.listen(socket, resolve); });
+        chmodSync(socket, 0o600);
+        await start();
+        restarting = false;
+        await finished;
+    }
+    finally {
+        await shutdown();
+        process.off("SIGINT", signal);
+        process.off("SIGTERM", signal);
+    }
+}
+/** Local administrator capability: the socket lives in the private launcher directory. */
+export function controlService(home, action) {
+    startupPaths(home);
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const req = request({ socketPath: join(home, "control.sock"), path: "/" + action, method: "POST" }, res => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", chunk => { body += chunk; });
+            res.on("end", () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error("Service unavailable; inspect private logs and startup files"));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    reject(new Error("Invalid launcher response"));
+                }
+            });
+        });
+        req.setTimeout(60_000, () => { timedOut = true; req.destroy(); });
+        req.once("error", () => reject(new Error(timedOut
+            ? "Service control timed out; outcome is unknown, check status before another restart"
+            : "Cannot contact launcher; start the foreground or managed service first")));
+        req.end();
+    });
+}
+//# sourceMappingURL=launcher.js.map

package/dist/lock.js

@@ -1,6 +1,22 @@
 import { DatabaseSync } from "node:sqlite";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+/** The stable installation lock prevents two launchers or uninstall during a directory switch. */
+export function acquireLauncherLock(home) {
+    const db = new DatabaseSync(join(home, "launcher-lock.sqlite"));
+    try {
+        db.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE");
+    }
+    catch {
+        db.close();
+        throw new Error("Another launcher owns this installation");
+    }
+    let released = false;
+    return () => { if (!released) {
+        db.close();
+        released = true;
+    } };
+}
 /** A dedicated SQLite transaction owns an OS lock until close or process death.
  * Local filesystems only. Never unlink this file: that would create a second lock identity.
  */