baychat 0.8.2 → 0.9.0

package/dist/relay/daemon.js

@@ -0,0 +1,301 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayDaemon = void 0;
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const config_1 = require("../config");
+const adapters_1 = require("./adapters");
+const queue_1 = require("./queue");
+const registry_1 = require("./registry");
+const socket_1 = require("./socket");
+const updates_1 = require("./updates");
+class RelayDaemon {
+    registry = new registry_1.SessionRegistry();
+    queue;
+    abort = new AbortController();
+    /** Live attach sockets by session name. */
+    attached = new Map();
+    /** Per-conversation delivery watermark — the 409 catch-up baseline. */
+    watermarks = new Map();
+    pending = [];
+    server;
+    startedAt = new Date().toISOString();
+    cursor = null;
+    polls = 0;
+    delivered = 0;
+    lastError;
+    /** Live session names from the last poll, for pruning and for `relay status`. */
+    liveSessions = [];
+    log;
+    constructor(opts = {}) {
+        this.log = opts.log ?? ((line) => console.log(`[relay] ${line}`));
+        this.queue = new queue_1.SessionQueue((session, batch) => this.deliver(session, batch), (session, err) => {
+            this.lastError = `delivery failed for ${session}: ${errText(err)}`;
+            this.log(this.lastError);
+        });
+    }
+    async start() {
+        // The DEVICE credential, not an agent token. A laptop has one device login
+        // and its sessions mint their own agents when they join, so no single agent
+        // token can see them all — the server fans out across this device's live
+        // sessions and tags every event with the session it belongs to.
+        const device = (0, config_1.loadDeviceCredentials)();
+        if (!device) {
+            throw new Error("this machine is not logged in to BayChat — run `npx baychat login`");
+        }
+        if (new Date(device.expiresAt).getTime() <= Date.now()) {
+            throw new Error(`device credential expired ${device.expiresAt} — run \`npx baychat login\``);
+        }
+        const auth = { baseUrl: device.baseUrl, token: device.token };
+        this.registry.load();
+        const sockPath = (0, socket_1.socketPath)();
+        if (await (0, socket_1.probeSocket)(sockPath)) {
+            throw new Error(`a relay is already listening on ${sockPath} — run \`baychat relay status\``);
+        }
+        (0, socket_1.unlinkStaleSocket)(sockPath);
+        this.server = net.createServer((sock) => this.onConnection(sock));
+        await new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(sockPath, () => {
+                // 0600: the socket is a wake channel into this user's sessions. Anyone
+                // who can write to it can make a local agent take a turn.
+                try {
+                    fs.chmodSync(sockPath, 0o600);
+                }
+                catch {
+                    /* best effort — XDG_RUNTIME_DIR is already user-private */
+                }
+                resolve();
+            });
+        });
+        writePidFile();
+        this.log(`listening on ${sockPath} (pid ${process.pid}) as device "${device.user.name}"`);
+        this.log(`${this.registry.all().length} known session target(s)`);
+        await (0, updates_1.runUpdatesLoop)({
+            auth,
+            watermarks: this.watermarks,
+            onEvents: (events) => {
+                for (const e of events)
+                    this.onEvent(e);
+            },
+            onSessions: (names) => {
+                this.liveSessions = names;
+                const dropped = this.registry.pruneToLive(names);
+                for (const name of dropped)
+                    this.log(`session ended server-side, dropped: ${name}`);
+            },
+            onPoll: (cursor) => {
+                this.cursor = cursor;
+                this.polls += 1;
+            },
+            onError: (err, willRetry) => {
+                this.lastError = `${errText(err)}${willRetry ? " (retrying)" : ""}`;
+                this.log(this.lastError);
+            },
+            signal: this.abort.signal,
+        });
+    }
+    /**
+     * Route one event and record the conversation watermark.
+     *
+     * Routing is the SERVER's answer (`sessionName`), not a local guess: the
+     * device poll already knows which session agent each event was queued for.
+     * Deriving it here from a locally cached conversation list would go stale the
+     * moment a session joined another room — and a session that joins a room the
+     * relay has never heard of still gets woken, with no local bookkeeping.
+     */
+    onEvent(event) {
+        const { conversationId, sessionName, message } = event;
+        const prior = this.watermarks.get(conversationId);
+        if (!prior || message.createdAt > prior)
+            this.watermarks.set(conversationId, message.createdAt);
+        if (!sessionName) {
+            this.log(`event ${message.id} carries no session (renamed or ended mid-poll) — ignoring`);
+            return;
+        }
+        // No self-echo guard is needed: the bus never queues an agent its own
+        // message. The previous one compared a sender id to a session name and so
+        // could never have matched anything.
+        this.queue.push(sessionName, { ...message, conversationId });
+    }
+    /**
+     * Deliver one coalesced batch to one session. Runs under the queue's
+     * per-session lock, so an attach wake and a headless resume can never be in
+     * flight for the same session at once.
+     */
+    async deliver(session, batch) {
+        const target = this.registry.get(session);
+        if (!target) {
+            this.record({ kind: "ignored", reason: `unknown session ${session}` }, session, batch);
+            return;
+        }
+        const sock = this.attached.get(session);
+        if (sock && !sock.destroyed) {
+            // Live session: hand it the batch and let the harness re-invoke it. The
+            // attach client exits after one wake, which is what makes this a wake
+            // rather than a stream — and why the socket is dropped here.
+            (0, socket_1.writeFrame)(sock, { type: "wake", conversationId: batch[0].conversationId, messages: batch });
+            this.record({ kind: "woken", via: "attach", session }, session, batch);
+            return;
+        }
+        const adapter = (0, adapters_1.adapterFor)(target.runtime);
+        const check = adapter.canResume(target);
+        if (!check.ok) {
+            // The honest outcome: it reached this box, and nothing answered it.
+            this.record({ kind: "pending", session, reason: check.reason ?? "cannot resume" }, session, batch);
+            return;
+        }
+        const prompt = (0, adapters_1.buildWakePrompt)(session, batch[0].conversationId, batch);
+        const { file, args } = adapter.headlessCommand(target, prompt);
+        const { exitCode, stderr } = await (0, adapters_1.runHeadless)(file, args, { cwd: target.cwd });
+        if (exitCode !== 0) {
+            // A non-zero headless turn did not necessarily reply. Recording it as
+            // delivered would claim an answer we cannot evidence.
+            this.record({ kind: "pending", session, reason: `headless ${target.runtime} exited ${exitCode}: ${stderr.slice(0, 200)}` }, session, batch);
+            return;
+        }
+        this.record({ kind: "woken", via: "headless", session, exitCode }, session, batch);
+    }
+    record(outcome, session, batch) {
+        if (outcome.kind === "woken") {
+            this.delivered += batch.length;
+            this.log(`woke ${session} via ${outcome.via} with ${batch.length} message(s)`);
+            return;
+        }
+        if (outcome.kind === "pending") {
+            for (const m of batch) {
+                this.pending.push({
+                    session,
+                    conversationId: m.conversationId,
+                    messageId: m.id,
+                    reason: outcome.reason,
+                    at: new Date().toISOString(),
+                });
+            }
+            // Bounded: a session left detached for a week must not grow the heap.
+            while (this.pending.length > 200)
+                this.pending.shift();
+            this.log(`DELIVERY PENDING for ${session} (${batch.length} message(s)): ${outcome.reason}`);
+            return;
+        }
+        this.log(`ignored ${batch.length} message(s): ${outcome.reason}`);
+    }
+    onConnection(sock) {
+        let session;
+        const read = (0, socket_1.createFrameReader)((frame) => {
+            if (frame.type === "attach") {
+                session = frame.session;
+                this.registry.upsert({
+                    name: frame.session,
+                    runtime: frame.runtime,
+                    resumeId: frame.resumeId,
+                    cwd: frame.cwd,
+                });
+                this.attached.set(frame.session, sock);
+                this.registry.setAttached(frame.session, true);
+                (0, socket_1.writeFrame)(sock, { type: "attached", session: frame.session });
+                this.log(`attached: ${frame.session} (${frame.runtime})`);
+                return;
+            }
+            if (frame.type === "status") {
+                (0, socket_1.writeFrame)(sock, { type: "status-result", status: this.status() });
+                return;
+            }
+            if (frame.type === "stop") {
+                this.log("stop requested over socket");
+                (0, socket_1.writeFrame)(sock, { type: "status-result", status: this.status() });
+                setTimeout(() => void this.stop(), 50);
+                return;
+            }
+        }, (bad) => (0, socket_1.writeFrame)(sock, { type: "error", message: `bad frame: ${bad.slice(0, 80)}` }));
+        sock.on("data", read);
+        const drop = () => {
+            if (session && this.attached.get(session) === sock) {
+                this.attached.delete(session);
+                this.registry.setAttached(session, false);
+                this.log(`detached: ${session}`);
+            }
+        };
+        sock.on("close", drop);
+        sock.on("error", drop);
+    }
+    status() {
+        const sessions = this.registry.all().map((t) => ({
+            ...t,
+            attached: this.attached.has(t.name),
+        }));
+        return {
+            running: true,
+            pid: process.pid,
+            startedAt: this.startedAt,
+            cursor: this.cursor,
+            polls: this.polls,
+            delivered: this.delivered,
+            sessions,
+            pending: this.pending,
+            lastError: this.lastError,
+        };
+    }
+    async stop() {
+        this.abort.abort();
+        for (const sock of this.attached.values())
+            sock.destroy();
+        this.attached.clear();
+        await this.queue.idle();
+        await new Promise((resolve) => (this.server ? this.server.close(() => resolve()) : resolve()));
+        (0, socket_1.unlinkStaleSocket)((0, socket_1.socketPath)());
+        try {
+            fs.unlinkSync((0, socket_1.pidFilePath)());
+        }
+        catch {
+            /* already gone */
+        }
+        this.log("stopped");
+    }
+}
+exports.RelayDaemon = RelayDaemon;
+function writePidFile() {
+    try {
+        fs.writeFileSync((0, socket_1.pidFilePath)(), String(process.pid), { mode: 0o600 });
+    }
+    catch {
+        // The pid file is a convenience for `relay stop`; the socket is the real
+        // handle, so failing to write it is not fatal.
+    }
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/relay/queue.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionQueue = void 0;
+/**
+ * Per-session serialisation.
+ *
+ * The hard invariant: for any one session there is at most ONE delivery in
+ * flight at a time. Two concurrent wakes for the same session means two turns
+ * answering the same room from the same identity — an interactive turn and a
+ * headless resume racing, each unaware of the other, both replying. That is the
+ * failure this class exists to prevent, and it is why every wake path goes
+ * through `push` rather than calling the adapter directly.
+ *
+ * Messages that arrive while a turn is running are not dropped and do not
+ * spawn a second turn: they accumulate and are handed to the next delivery as
+ * one batch. Coalescing matters because a headless resume is expensive — three
+ * messages arriving during one run should produce one follow-up turn, not
+ * three.
+ */
+class SessionQueue {
+    deliver;
+    onError;
+    /** Buffered messages per session, awaiting the next free slot. */
+    buffers = new Map();
+    /** Sessions with a delivery currently in flight. */
+    running = new Set();
+    /** Resolvers for `idle()`, so tests and shutdown can await quiescence. */
+    idleWaiters = [];
+    constructor(
+    /**
+     * Delivers one batch. Must not throw for ordinary failures — a failed
+     * delivery is reported through DeliveryOutcome, not by rejecting. A
+     * rejection is treated as a crashed turn: it is logged by the caller's
+     * handler and the slot is freed so the session isn't wedged forever.
+     */
+    deliver, onError = () => { }) {
+        this.deliver = deliver;
+        this.onError = onError;
+    }
+    /** Queue a message for a session, starting a delivery if none is running. */
+    push(session, message) {
+        const buf = this.buffers.get(session) ?? [];
+        // De-dupe inside the buffer too: the same event can legitimately arrive
+        // twice across a cursor re-baseline (409 recovery re-reads from a
+        // watermark), and a batch must not show the room the same line twice.
+        if (!buf.some((m) => m.id === message.id)) {
+            buf.push(message);
+            this.buffers.set(session, buf);
+        }
+        void this.drain(session);
+    }
+    async drain(session) {
+        if (this.running.has(session))
+            return; // a turn owns this session — it will pick the buffer up
+        const buf = this.buffers.get(session);
+        if (!buf || buf.length === 0)
+            return;
+        this.running.add(session);
+        try {
+            // Loop rather than recurse: messages that land *during* the delivery are
+            // picked up here without releasing the slot in between, so there is no
+            // window where a second drain could start a concurrent turn.
+            while (true) {
+                const batch = this.buffers.get(session) ?? [];
+                if (batch.length === 0)
+                    break;
+                this.buffers.delete(session);
+                try {
+                    await this.deliver(session, batch);
+                }
+                catch (err) {
+                    // A thrown delivery must not strand the session. Report and move on:
+                    // the batch is already consumed, and retrying it blindly risks
+                    // double-answering if the turn actually ran.
+                    this.onError(session, err);
+                }
+            }
+        }
+        finally {
+            this.running.delete(session);
+            this.buffers.delete(session);
+            this.notifyIfIdle();
+        }
+    }
+    /** True while any session has a delivery in flight. */
+    get busy() {
+        return this.running.size > 0;
+    }
+    /** Sessions with a delivery in flight — surfaced by `relay status`. */
+    activeSessions() {
+        return [...this.running];
+    }
+    /** Resolves once every in-flight delivery has finished. */
+    idle() {
+        if (!this.busy)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve));
+    }
+    notifyIfIdle() {
+        if (this.busy)
+            return;
+        const waiters = this.idleWaiters;
+        this.idleWaiters = [];
+        for (const w of waiters)
+            w();
+    }
+}
+exports.SessionQueue = SessionQueue;

package/dist/relay/registry.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionRegistry = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const FILE = "relay-sessions.json";
+function registryPath() {
+    return path.join((0, config_1.configDir)(), FILE);
+}
+/**
+ * The set of local sessions the relay can wake, keyed by BayChat session name.
+ *
+ * Persisted because `resumeId` is the difference between a headless wake that
+ * continues the right conversation and one that is refused as `pending`. A
+ * daemon restart (or a reboot) must not silently downgrade every session to
+ * "cannot resume safely" — so what `attach` learned is written to disk.
+ *
+ * `attached` is deliberately NOT persisted: it describes a live socket, and a
+ * process that just started holds none. Loading it as `true` would make the
+ * daemon believe someone is listening and route wakes into nothing.
+ */
+class SessionRegistry {
+    filePath;
+    sessions = new Map();
+    constructor(filePath = registryPath()) {
+        this.filePath = filePath;
+    }
+    load() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+            if (!raw || typeof raw !== "object")
+                return;
+            for (const [name, value] of Object.entries(raw)) {
+                if (!value || typeof value !== "object")
+                    continue;
+                this.sessions.set(name, { ...value, name, attached: false });
+            }
+        }
+        catch {
+            // Missing or corrupt — an empty registry is the correct reading. Every
+            // wake then reports `pending` with a reason, which is visible in
+            // `relay status`, rather than failing silently.
+        }
+    }
+    save() {
+        const out = {};
+        for (const [name, target] of this.sessions) {
+            const { attached: _attached, ...persisted } = target;
+            out[name] = persisted;
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            fs.writeFileSync(this.filePath, JSON.stringify(out, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // A registry we cannot persist still works for this process's lifetime;
+            // losing it costs resume ids after a restart, not correctness now.
+        }
+    }
+    /**
+     * Record (or update) a target. Merges rather than replaces: an `attach` that
+     * omits `resumeId` must not erase one an earlier attach established, or the
+     * next detached wake would report `pending` for a session we can in fact
+     * resume.
+     */
+    upsert(target) {
+        const existing = this.sessions.get(target.name);
+        const merged = {
+            registeredAt: existing?.registeredAt ?? new Date().toISOString(),
+            ...existing,
+            ...stripUndefined(target),
+            name: target.name,
+            runtime: target.runtime,
+        };
+        this.sessions.set(target.name, merged);
+        this.save();
+        return merged;
+    }
+    get(name) {
+        return this.sessions.get(name);
+    }
+    all() {
+        return [...this.sessions.values()];
+    }
+    setAttached(name, attached) {
+        const t = this.sessions.get(name);
+        if (t)
+            t.attached = attached;
+    }
+    /**
+     * Drop targets whose session is no longer live server-side.
+     *
+     * A session ended from the app (Settings → Devices → Sessions → End) stops
+     * appearing in the device poll. Keeping a local target for it would leave a
+     * headless resume firing into a terminal the owner deliberately parked.
+     *
+     * Attached sessions are never pruned: a live socket outranks a poll, which
+     * may simply have raced a join that hasn't been stamped live yet.
+     */
+    pruneToLive(liveNames) {
+        const live = new Set(liveNames);
+        const dropped = [];
+        for (const [name, target] of this.sessions) {
+            if (!live.has(name) && !target.attached) {
+                this.sessions.delete(name);
+                dropped.push(name);
+            }
+        }
+        if (dropped.length > 0)
+            this.save();
+        return dropped;
+    }
+}
+exports.SessionRegistry = SessionRegistry;
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}

package/dist/relay/socket.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.socketPath = socketPath;
+exports.pidFilePath = pidFilePath;
+exports.createFrameReader = createFrameReader;
+exports.writeFrame = writeFrame;
+exports.probeSocket = probeSocket;
+exports.unlinkStaleSocket = unlinkStaleSocket;
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+/**
+ * Where the attach socket lives.
+ *
+ * `XDG_RUNTIME_DIR` is the right home: it is user-private (0700), on tmpfs, and
+ * cleared on logout, so a stale socket never outlives the session that made it.
+ * The config-dir fallback covers boxes without it (some containers, macOS).
+ */
+function socketPath() {
+    const override = process.env.BAYCHAT_RELAY_SOCKET;
+    if (override)
+        return override;
+    const runtimeDir = process.env.XDG_RUNTIME_DIR;
+    if (runtimeDir)
+        return path.join(runtimeDir, "baychat-relay.sock");
+    return path.join((0, config_1.configDir)(), "relay.sock");
+}
+function pidFilePath() {
+    return path.join((0, config_1.configDir)(), "relay.pid");
+}
+/** Frames are newline-delimited JSON; this splits a stream into whole ones. */
+function createFrameReader(onFrame, onBad) {
+    let buffer = "";
+    return (chunk) => {
+        buffer += chunk.toString();
+        // A peer that never sends a newline must not grow this unboundedly.
+        if (buffer.length > 1_000_000) {
+            buffer = "";
+            onBad?.("frame too large");
+            return;
+        }
+        let idx;
+        while ((idx = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, idx).trim();
+            buffer = buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            try {
+                onFrame(JSON.parse(line));
+            }
+            catch {
+                onBad?.(line);
+            }
+        }
+    };
+}
+function writeFrame(sock, frame) {
+    sock.write(JSON.stringify(frame) + "\n");
+}
+/**
+ * Is a daemon already listening?
+ *
+ * A socket file on disk proves nothing — a killed daemon leaves one behind. The
+ * only honest test is to connect: ECONNREFUSED means the file is stale and safe
+ * to unlink, which is what lets `relay start` recover from a hard kill without
+ * a human deleting files.
+ */
+function probeSocket(sockPath, timeoutMs = 1_000) {
+    return new Promise((resolve) => {
+        if (!fs.existsSync(sockPath))
+            return resolve(false);
+        const sock = net.createConnection(sockPath);
+        const done = (alive) => {
+            sock.destroy();
+            resolve(alive);
+        };
+        sock.setTimeout(timeoutMs, () => done(false));
+        sock.on("connect", () => done(true));
+        sock.on("error", () => done(false));
+    });
+}
+/** Remove a socket file we have already proven dead. */
+function unlinkStaleSocket(sockPath) {
+    try {
+        fs.unlinkSync(sockPath);
+    }
+    catch {
+        // Already gone, or not ours to remove — the listen() that follows will
+        // surface anything that actually matters.
+    }
+}