@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/tools/browser.js

@@ -0,0 +1,394 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { integer, keys, string, validateRequest, TOOL_RESULT_BYTES, } from "./validation.js";
+const TIMEOUT = 4500;
+async function bounded(promise, timeout = TIMEOUT) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(Error("Browser operation timed out; mutation outcome may be unknown")), Math.max(1, timeout));
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** All ancestors are checked: mkdir recursive must never follow a planted profile symlink. */
+async function ownedDirectory(dir, privateMode = false) {
+    const absolute = path.resolve(dir);
+    const parts = absolute.split(path.sep).filter(Boolean);
+    let current = path.parse(absolute).root;
+    const uid = process.getuid?.();
+    let protectedByOwner = false;
+    for (const part of parts) {
+        current = path.join(current, part);
+        await fs.mkdir(current, { mode: 0o700 }).catch((e) => {
+            if (e.code !== "EEXIST")
+                throw e;
+        });
+        const stat = await fs.lstat(current);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            (!protectedByOwner &&
+                (stat.mode & 0o022) !== 0 &&
+                !(stat.mode & 0o1000)) ||
+            (protectedByOwner && uid !== undefined && stat.uid !== uid))
+            throw Error("Unsafe browser directory");
+        // An owned 0700 ancestor blocks other UIDs from reaching owned descendants,
+        // even if an existing config directory below that fence has group-write bits.
+        // Symlink and ownership checks still apply at every level.
+        if (uid !== undefined && stat.uid === uid && (stat.mode & 0o077) === 0)
+            protectedByOwner = true;
+    }
+    const stat = await fs.lstat(absolute);
+    if (process.getuid && stat.uid !== process.getuid())
+        throw Error("Browser directory is not owned by this user");
+    if (privateMode)
+        await fs.chmod(absolute, 0o700);
+}
+function allowedUrl(params) {
+    const url = string(params, "url", 8192, "about:blank");
+    if (url === "about:blank")
+        return url;
+    try {
+        const parsed = new URL(url);
+        if (["http:", "https:"].includes(parsed.protocol))
+            return parsed.href;
+    }
+    catch { }
+    throw Error("Invalid browser URL: use http(s) or about:blank");
+}
+function browserKey(params) {
+    const key = string(params, "key", 64);
+    if (!/^(?:(?:Control|Alt|Shift|Meta)\+)*(?:Enter|Backspace|Tab|Escape|ArrowUp|ArrowDown|ArrowLeft|ArrowRight|Delete|Home|End|PageUp|PageDown|[a-zA-Z0-9])$/.test(key))
+        throw Error("Invalid browser key");
+    return key;
+}
+export class BrowserCore {
+    options;
+    chromium;
+    error;
+    sessions = new Map();
+    queue = Promise.resolve();
+    disposed = false;
+    constructor(options, chromium, error) {
+        this.options = options;
+        this.chromium = chromium;
+        this.error = error;
+    }
+    static async create(options) {
+        try {
+            const { chromium } = await import("playwright-core");
+            const executablePath = options.executablePath ?? chromium.executablePath();
+            await fs.access(executablePath);
+            await ownedDirectory(options.home);
+            await ownedDirectory(options.profileRoot, true);
+            await ownedDirectory(path.join(options.home, "Downloads"));
+            return new BrowserCore({ ...options, executablePath }, chromium);
+        }
+        catch (error) {
+            return new BrowserCore(options, undefined, `Browser unavailable: ${error instanceof Error ? error.message : "missing optional browser dependency"}`);
+        }
+    }
+    dispatch(method, params = {}) {
+        const task = this.queue.then(async () => {
+            if (this.disposed)
+                throw Error("Browser supervisor stopped");
+            validateRequest(method, params);
+            const result = await this.execute(method, params);
+            if (Buffer.byteLength(JSON.stringify(result)) > TOOL_RESULT_BYTES - 1024)
+                throw Error("Browser frame exceeds reply limit");
+            return result;
+        });
+        this.queue = task.catch(() => { });
+        return task;
+    }
+    descriptor(s) {
+        return {
+            id: s.id,
+            name: s.name,
+            url: s.page.url(),
+            controllerId: s.controllerId,
+            exited: s.exited,
+        };
+    }
+    async navigate(s, url, deadline = Date.now() + TIMEOUT) {
+        try {
+            await s.page.goto(url, {
+                waitUntil: "domcontentloaded",
+                timeout: Math.max(1, Math.min(TIMEOUT, deadline - Date.now())),
+            });
+        }
+        catch (error) {
+            if (String(error).includes("Download is starting"))
+                return;
+            await s.page
+                .goto("about:blank", { waitUntil: "commit", timeout: 500 })
+                .catch(() => { });
+            throw error;
+        }
+    }
+    watch(s, page) {
+        page.on("dialog", (dialog) => {
+            s.notice = `${dialog.type()}: ${dialog.message().slice(0, 300)} (dismissed)`;
+            void dialog.dismiss().catch(() => { });
+        });
+        page.on("download", (download) => {
+            void this.download(s, download).catch((error) => {
+                s.notice = `Download failed: ${error.message}`;
+            });
+        });
+        page.on("close", () => {
+            if (s.page === page) {
+                const others = s.context.pages().filter((p) => !p.isClosed());
+                if (others.length) {
+                    s.page = others[others.length - 1];
+                    s.notice = "Active tab closed; switched to remaining tab";
+                }
+                else {
+                    s.exited = true;
+                    s.controllerId = null;
+                }
+            }
+        });
+        page.on("crash", () => {
+            if (s.page === page) {
+                s.exited = true;
+                s.notice = "Browser page crashed; close and create a new session";
+            }
+        });
+    }
+    async download(s, download) {
+        const downloads = path.join(this.options.home, "Downloads");
+        await ownedDirectory(downloads);
+        const before = await fs.lstat(downloads);
+        const staging = await fs.mkdtemp(path.join(downloads, ".axom-browser-"));
+        await fs.chmod(staging, 0o700);
+        const temporary = path.join(staging, "download");
+        const timer = setTimeout(() => {
+            void download.cancel().catch(() => { });
+        }, 30000);
+        try {
+            await download.saveAs(temporary);
+            const failure = await download.failure();
+            if (failure)
+                throw Error(failure);
+            await ownedDirectory(downloads);
+            const after = await fs.lstat(downloads);
+            if (before.ino !== after.ino || before.dev !== after.dev)
+                throw Error("Downloads directory changed");
+            let suggested = download
+                .suggestedFilename()
+                .replace(/[\\/\x00-\x1f\x7f]/g, "_")
+                .replace(/^\.+/, "")
+                .slice(0, 160) || "download";
+            while (Buffer.byteLength(suggested) > 180)
+                suggested = [...suggested].slice(0, -1).join("");
+            const ext = path.extname(suggested), stem = suggested.slice(0, suggested.length - ext.length);
+            for (let n = 0; n < 100; n++) {
+                const name = n ? `${stem} (${n})${ext}` : suggested;
+                try {
+                    await fs.link(temporary, path.join(downloads, name));
+                    s.notice = `Downloaded: ${name}`;
+                    return;
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                }
+            }
+            throw Error("Download filename collision limit reached");
+        }
+        finally {
+            clearTimeout(timer);
+            await fs.rm(staging, { recursive: true, force: true });
+        }
+    }
+    async execute(method, params) {
+        const deadline = Date.now() + 6000;
+        if (method === "tools.info") {
+            keys(params, []);
+            return {
+                browser: !!this.chromium,
+                ...(this.error ? { browserError: this.error } : {}),
+            };
+        }
+        if (!method.startsWith("browser."))
+            throw Error("Unsupported browser tool");
+        if (!this.chromium)
+            throw Error(this.error);
+        if (method === "browser.list") {
+            keys(params, []);
+            return {
+                sessions: [...this.sessions.values()].map((s) => this.descriptor(s)),
+            };
+        }
+        const id = string(params, "id", 128), clientId = string(params, "clientId", 128);
+        if (method === "browser.create") {
+            keys(params, ["id", "clientId", "url", "width", "height"]);
+            const url = allowedUrl(params), width = integer(params, "width", 320, 1600, 1024), height = integer(params, "height", 240, 1200, 768);
+            const existing = this.sessions.get(id);
+            if (existing)
+                return this.descriptor(existing);
+            if (this.sessions.size >= 2)
+                throw Error("Maximum browser session limit reached (2)");
+            await ownedDirectory(this.options.profileRoot, true);
+            const profile = path.join(this.options.profileRoot, createHash("sha256").update(id).digest("hex"));
+            await ownedDirectory(profile, true);
+            const context = await this.chromium.launchPersistentContext(profile, {
+                executablePath: this.options.executablePath,
+                headless: true,
+                acceptDownloads: true,
+                viewport: { width, height },
+                timeout: TIMEOUT,
+                ...(this.options.proxy
+                    ? { proxy: { server: this.options.proxy } }
+                    : {}),
+                args: process.platform === "linux" ? ["--no-sandbox"] : [],
+            });
+            context.setDefaultTimeout(TIMEOUT);
+            context.setDefaultNavigationTimeout(TIMEOUT);
+            const page = context.pages()[0] ?? (await context.newPage());
+            const s = {
+                id,
+                name: "Browser",
+                context,
+                page,
+                controllerId: clientId,
+                width,
+                height,
+                notice: "",
+                exited: false,
+            };
+            this.watch(s, page);
+            context.on("page", (newPage) => {
+                this.watch(s, newPage);
+                s.page = newPage;
+                s.exited = false;
+                s.notice = "Switched to new tab";
+                if (context.pages().length > 8)
+                    void context
+                        .pages()[0]
+                        .close()
+                        .catch(() => { });
+            });
+            context.on("close", () => {
+                s.exited = true;
+                s.controllerId = null;
+            });
+            this.sessions.set(id, s);
+            try {
+                await this.navigate(s, url, deadline);
+            }
+            catch (error) {
+                this.sessions.delete(id);
+                await context.close();
+                throw error;
+            }
+            return this.descriptor(s);
+        }
+        const s = this.sessions.get(id);
+        if (!s)
+            throw Error("Browser session not found");
+        if ([
+            "browser.attach",
+            "browser.takeover",
+            "browser.detach",
+            "browser.close",
+            "browser.frame",
+        ].includes(method))
+            keys(params, ["id", "clientId"]);
+        if (method === "browser.attach") {
+            if (!s.controllerId)
+                s.controllerId = clientId;
+            return {
+                session: this.descriptor(s),
+                control: s.controllerId === clientId,
+            };
+        }
+        if (method === "browser.takeover") {
+            s.controllerId = clientId;
+            return { ok: true };
+        }
+        if (method === "browser.detach") {
+            if (s.controllerId === clientId)
+                s.controllerId = null;
+            return { ok: true };
+        }
+        if (method === "browser.frame") {
+            const base = {
+                mime: "image/jpeg",
+                width: s.width,
+                height: s.height,
+                url: s.page.url(),
+                title: "",
+                control: s.controllerId === clientId,
+                exited: s.exited,
+                notice: s.notice,
+            };
+            if (s.exited)
+                return { ...base, data: "" };
+            const jpeg = await s.page.screenshot({
+                type: "jpeg",
+                quality: 70,
+                timeout: TIMEOUT,
+                animations: "disabled",
+            });
+            return {
+                ...base,
+                title: (await bounded(s.page.title(), 1000)).slice(0, 512),
+                data: jpeg.toString("base64"),
+            };
+        }
+        if (s.controllerId !== clientId)
+            throw Error("Browser is read-only; take control first");
+        if (method === "browser.close") {
+            await s.context.close();
+            this.sessions.delete(id);
+            return { ok: true };
+        }
+        if (s.exited)
+            throw Error("Browser exited");
+        if (method === "browser.navigate") {
+            keys(params, ["id", "clientId", "url"]);
+            await this.navigate(s, allowedUrl(params), deadline);
+            return { ok: true };
+        }
+        if (method === "browser.input") {
+            keys(params, [
+                "id",
+                "clientId",
+                "kind",
+                "x",
+                "y",
+                "deltaX",
+                "deltaY",
+                "key",
+                "text",
+            ]);
+            const kind = string(params, "kind", 16);
+            if (kind === "click")
+                await bounded(s.page.mouse.click(integer(params, "x", 0, s.width - 1), integer(params, "y", 0, s.height - 1)));
+            else if (kind === "scroll")
+                await bounded(s.page.mouse.wheel(integer(params, "deltaX", -4000, 4000, 0), integer(params, "deltaY", -4000, 4000, 0)));
+            else if (kind === "key")
+                await bounded(s.page.keyboard.press(browserKey(params)));
+            else if (kind === "text")
+                await bounded(s.page.keyboard.insertText(string(params, "text", 64 * 1024)));
+            else
+                throw Error("Invalid browser input kind");
+            return { ok: true };
+        }
+        throw Error("Unsupported browser tool");
+    }
+    async dispose() {
+        this.disposed = true;
+        await this.queue;
+        await Promise.all([...this.sessions.values()].map((s) => s.context.close().catch(() => { })));
+        this.sessions.clear();
+    }
+}

package/dist/workstation/tools/client.js

@@ -0,0 +1,277 @@
+import { resolveBrowserBinding, browserCapability } from '../desktop/binding.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { object, TOOL_REQUEST_BYTES, TOOL_RESULT_BYTES, validateRequest } from './validation.js';
+/** Unix socket paths must remain below macOS/Linux's ~104-byte sockaddr_un limit. */
+export function keeperPaths(options, temporaryDirectory = os.tmpdir(), platform = process.platform, kind = 'terminal') {
+    const identity = createHash('sha256').update(JSON.stringify([path.resolve(options.configDir), options.workstationId, options.server, ...(kind === 'browser' ? ['browser'] : [])])).digest('hex').slice(0, 32);
+    const namespace = `axom-${kind === 'browser' ? 'browser' : 'tools'}-${process.getuid?.() ?? 'user'}`;
+    // macOS /var/folders/.../T often exhausts sockaddr_un before adding a private namespace. Honor
+    // TMPDIR where it fits on Linux; the short system temporary root is checked for private ownership.
+    let dir = path.join(platform === 'darwin' ? '/tmp' : temporaryDirectory, namespace, identity);
+    if (Buffer.byteLength(path.join(dir, 'keeper.sock')) > 100)
+        dir = path.join('/tmp', namespace, identity);
+    // Browser ports are disjoint from terminal startup and the normal Linux ephemeral range.
+    return { dir, socket: path.join(dir, 'keeper.sock'), lock: path.join(dir, 'startup.lock'), pidFile: path.join(dir, 'keeper.pid.json'), lockPort: kind === 'browser' ? 10000 + Number.parseInt(identity.slice(0, 8), 16) % 8000 : 20000 + Number.parseInt(identity.slice(0, 8), 16) % 40000, unit: `axom-${kind === 'browser' ? 'browser' : 'tools'}-keeper-${identity}` };
+}
+export async function privateDirectory(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+        throw new Error('Unsafe keeper state directory');
+    await fs.chmod(dir, 0o700);
+}
+export function keeperRpc(socketPath, method, params, timeoutMs = 7000) {
+    const id = randomUUID();
+    const request = JSON.stringify({ id, method, params }) + '\n';
+    if (Buffer.byteLength(request) > TOOL_REQUEST_BYTES)
+        return Promise.reject(new Error('Tool request too large'));
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        let buffered = '';
+        let done = false;
+        const finish = (error, result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(result);
+        };
+        const timer = setTimeout(() => finish(new Error('Workstation tool request timed out; mutation outcome may be unknown')), timeoutMs);
+        socket.setEncoding('utf8');
+        socket.on('connect', () => socket.end(request));
+        socket.on('data', chunk => {
+            buffered += chunk;
+            if (Buffer.byteLength(buffered) > TOOL_RESULT_BYTES) {
+                finish(new Error('Keeper response too large'));
+                return;
+            }
+            const newline = buffered.indexOf('\n');
+            if (newline < 0)
+                return;
+            try {
+                const reply = JSON.parse(buffered.slice(0, newline));
+                if (!object(reply) || reply.id !== id || typeof reply.ok !== 'boolean' || !object(reply.result) || !(reply.error === null || typeof reply.error === 'string') || (reply.ok ? reply.error !== null : !reply.error))
+                    throw new Error('Invalid keeper response');
+                finish(reply.ok ? undefined : new Error(reply.error), reply.result);
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error('Invalid keeper response'));
+            }
+        });
+        socket.on('error', error => finish(error));
+        socket.on('close', () => finish(new Error('Workstation tools keeper disconnected')));
+    });
+}
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * A tools keeper client. The daemon only ever makes the browser kind (`browser`). The kind is required — no default — so nothing can
+ * start the retired terminal-kind tools keeper by accident (spec §9; terminals run in keeper-terminal, files in the daemon's files
+ * host); an explicit `terminal` client exists only for the tests that pin how the retired keeper's startup and tools.info behave.
+ * (`keeperPaths` keeps its terminal default: `keepers/legacy.ts` finds a legacy tools keeper an older CLI left running by it.)
+ */
+export class ToolsClient {
+    options;
+    kind;
+    paths;
+    starting;
+    browser;
+    constructor(options, kind) {
+        this.options = options;
+        this.kind = kind;
+        if (kind !== 'terminal' && kind !== 'browser')
+            throw new Error('ToolsClient needs an explicit kind (browser)');
+        this.paths = keeperPaths(options, undefined, undefined, kind);
+    }
+    async probe(timeoutMs = 250) {
+        try {
+            const reply = await keeperRpc(this.paths.socket, 'keeper.ping', {}, timeoutMs);
+            if (reply.identity !== this.paths.unit || !Number.isSafeInteger(reply.pid))
+                return null;
+            return { pid: reply.pid };
+        }
+        catch {
+            return null;
+        }
+    }
+    async request(method, params) {
+        validateRequest(method, params);
+        const binding = resolveBrowserBinding(this.options.browserBinding);
+        if (!binding && method === 'tools.info') {
+            // Desktop sharing is optional. Checking terminal/files must not start a
+            // separate browser or require its dependencies when no VNC was configured.
+            const metadata = { browser: false, browserMode: 'shared', browserBinding: browserCapability(undefined) };
+            return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+        }
+        if (binding && (method.startsWith('browser.') || method === 'tools.info')) {
+            const metadata = { browser: true, browserMode: 'shared', browserBinding: browserCapability(binding) };
+            if (method === 'browser.list')
+                return { ...metadata, sessions: [] };
+            if (method === 'tools.info')
+                return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+            throw new Error('Shared browser uses the live desktop viewer; legacy browser session operations are unavailable');
+        }
+        if (this.kind === 'terminal' && (method.startsWith('browser.') || method === 'tools.info')) {
+            this.browser ??= new ToolsClient(this.options, 'browser');
+            if (method.startsWith('browser.'))
+                return this.browser.request(method, params);
+            const [terminal, browser] = await Promise.all([this.localRequest(method, params), this.browser.request(method, params).catch(error => ({ browser: false, browserError: error.message }))]);
+            const result = { ...terminal, ...browser, browserMode: 'legacy', browserBinding: browserCapability(undefined) };
+            if (result.browser)
+                delete result.browserError;
+            return result;
+        }
+        return this.localRequest(method, params);
+    }
+    async localRequest(method, params) {
+        const deadline = Date.now() + 7500;
+        await this.ensure(deadline);
+        // Never automatically retry a request: terminal input and file mutations may have executed
+        // even if their response was lost. Chunk retry is a caller decision with exact offset/data.
+        return keeperRpc(this.paths.socket, method, params, Math.max(1, deadline - Date.now()));
+    }
+    ensure(deadline) {
+        if (!this.starting) {
+            this.starting = this.start(deadline).finally(() => { this.starting = undefined; });
+        }
+        return this.starting;
+    }
+    async start(deadline) {
+        await privateDirectory(path.dirname(this.paths.dir));
+        await privateDirectory(this.paths.dir);
+        if (await this.probe())
+            return;
+        while (Date.now() < deadline - 500) {
+            if (await this.probe())
+                return;
+            let lock;
+            try {
+                lock = await this.acquireStartupLock();
+            }
+            catch (error) {
+                if (error.code !== 'EADDRINUSE')
+                    throw error;
+                await delay(50);
+                continue;
+            }
+            try {
+                if (await this.probe())
+                    return;
+                // A probe timeout is not process death. A busy emulator can delay ping; unlinking its live
+                // socket would orphan every PTY. The startup PID manifest is written before initialization.
+                while (await this.liveManifest()) {
+                    if (await this.probe())
+                        return;
+                    if (Date.now() >= deadline - 300)
+                        throw new Error('Tools keeper is alive but busy or unavailable; retry later');
+                    await delay(50);
+                }
+                await fs.unlink(this.paths.socket).catch(error => { if (error.code !== 'ENOENT')
+                    throw error; });
+                const launchConfig = Buffer.from(JSON.stringify({ socket: this.paths.socket, identity: this.paths.unit, home: this.options.home, roots: this.options.roots ?? [], kind: this.kind, profileRoot: path.join(path.resolve(this.options.configDir), 'browser-profiles', this.paths.unit), executablePath: this.options.browserExecutable ?? process.env.AXOM_BROWSER_EXECUTABLE, proxy: this.options.browserProxy ?? process.env.AXOM_BROWSER_PROXY })).toString('base64');
+                const script = fileURLToPath(new URL('./keeperProcess.js', import.meta.url));
+                if (script.endsWith('/src/workstation/tools/keeperProcess.js'))
+                    throw new Error('Tools keeper requires built CLI distribution');
+                let isolated = false;
+                if (process.platform === 'linux' && this.options.useSystemd !== false && await this.systemdAvailable()) {
+                    // setsid/detached cannot escape systemd's KillMode=control-group. A separate user service
+                    // gives keeper/PTYS their own cgroup and allows the transport daemon to restart safely.
+                    isolated = await this.systemdLaunch(script, launchConfig, deadline);
+                    if (!isolated) {
+                        // An existing user unit may still be starting. Never spawn a same-cgroup fallback
+                        // on a systemd host, where a daemon restart would silently kill every live terminal.
+                        while (Date.now() < deadline - 100) {
+                            if (await this.probe())
+                                return;
+                            await delay(50);
+                        }
+                        throw new Error('Cannot start isolated tools keeper user service');
+                    }
+                }
+                if (!isolated) {
+                    const child = spawn(process.execPath, [script, launchConfig], { detached: true, stdio: 'ignore' });
+                    child.on('error', () => { });
+                    child.unref();
+                }
+                while (Date.now() < deadline - 100) {
+                    if (await this.probe())
+                        return;
+                    await delay(50);
+                }
+                throw new Error('Workstation tools keeper failed to start');
+            }
+            finally {
+                await new Promise(resolve => lock.close(() => resolve()));
+            }
+        }
+        throw new Error('Workstation tools keeper startup is busy or timed out');
+    }
+    /** A kernel bind is an atomic cross-process lock with automatic release on process death.
+     * It carries no requests, and needs no stale-file unlink or ownership-blind finally cleanup.
+     * Rare identity-port collisions only serialize startup; all data still uses the private socket. */
+    acquireStartupLock() {
+        return new Promise((resolve, reject) => {
+            const lock = net.createServer(socket => socket.destroy());
+            lock.once('error', reject);
+            lock.listen({ host: '127.0.0.1', port: this.paths.lockPort, exclusive: true }, () => resolve(lock));
+        });
+    }
+    async liveManifest() {
+        try {
+            const stat = await fs.lstat(this.paths.pidFile);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096)
+                throw new Error('Invalid tools keeper PID manifest');
+            const value = JSON.parse(await fs.readFile(this.paths.pidFile, 'utf8'));
+            if (value.identity !== this.paths.unit)
+                throw new Error('Tools keeper identity mismatch');
+            return pidAlive(value.pid);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async systemdAvailable() {
+        return new Promise(resolve => {
+            const child = spawn('systemctl', ['--user', 'show-environment'], { stdio: 'ignore' });
+            let done = false;
+            const finish = (ok) => { if (done)
+                return; done = true; clearTimeout(timer); resolve(ok); };
+            const timer = setTimeout(() => { child.kill(); finish(false); }, 500);
+            child.on('error', () => finish(false));
+            child.on('exit', code => finish(code === 0));
+        });
+    }
+    async systemdLaunch(script, config, deadline) {
+        return new Promise(resolve => {
+            const child = spawn('systemd-run', ['--user', '--quiet', '--collect', `--unit=${this.paths.unit}`, '--property=Type=exec', '--property=Restart=on-failure', '--property=RestartSec=1', '--', process.execPath, script, config], { stdio: 'ignore' });
+            let done = false;
+            const finish = (ok) => { if (done)
+                return; done = true; clearTimeout(timer); resolve(ok); };
+            const timer = setTimeout(() => { child.kill(); finish(false); }, Math.max(1, Math.min(2000, deadline - Date.now() - 500)));
+            child.on('error', () => finish(false));
+            child.on('exit', code => finish(code === 0));
+        });
+    }
+}