appduct 0.10.0 → 0.11.0

package/dist/rpc/client.js

@@ -1,819 +0,0 @@
-/**
- * The auto-spawning RPC client library (ARCHITECTURE.md §4, §5) used by the CLI, MCP server, and
- * tests to talk to `daemon.sock`. On `ENOENT`/`ECONNREFUSED` it takes an exclusive spawn-lock,
- * spawns `daemon run` detached, polls the socket until ready, then retries the request once.
- */
-import { connect } from "node:net";
-import { spawn as spawnChildProcess } from "node:child_process";
-import { open, readFile, rm, stat } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { RPC_METHODS } from "@appduct/shared";
-import { ensureDaemonLogMode, resolveDaemonLogMaxBytes, rotateDaemonLogIfNeeded, } from "../daemon/log-rotation.js";
-import { isProcessAlive } from "../daemon/pidfile.js";
-import { isSocketConnectable } from "../daemon/socket-probe.js";
-import { getStateDirPaths } from "../daemon/state-dir.js";
-import { DAEMON_VERSION_OVERRIDE_ENV } from "../package-version.js";
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const defaultBinPath = join(packageRoot, "bin.js");
-export class DaemonRpcError extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.code = code;
-        this.data = data;
-        this.name = "DaemonRpcError";
-    }
-}
-/**
- * `reason` distinguishes outcomes that look identical to a caller but mean opposite things to the
- * version-drift restart (issue #30): `"closed"` is the daemon dropping the connection — expected
- * while it tears itself down — whereas `"timeout"` is a daemon that is very much alive and simply
- * not answering, which must never be mistaken for "it is gone, spawn another one".
- */
-export class DaemonUnavailableError extends Error {
-    reason;
-    constructor(message, reason = "unreachable") {
-        super(message);
-        this.reason = reason;
-        this.name = "DaemonUnavailableError";
-    }
-}
-/** A request that ran out of time against a daemon that never dropped the connection. */
-const isRequestTimeoutError = (error) => {
-    return error instanceof DaemonUnavailableError && error.reason === "timeout";
-};
-const describeLiveState = (state) => {
-    const parts = [];
-    if (state.sessions > 0) {
-        parts.push(`${state.sessions} connected session(s)`);
-    }
-    if (state.pendingLinks > 0) {
-        parts.push(`${state.pendingLinks} unclaimed link(s)`);
-    }
-    return parts.join(" and ");
-};
-/**
- * Raised when the daemon this client reached is running a different Appduct version and could
- * not be replaced (issue #30). The common case is live state a restart would destroy: sessions
- * (resume tokens are in-daemon memory, so a restart makes the app's resume fail closed with 1008)
- * or pending links (a deep link or QR code someone is about to scan). The caller is told rather
- * than silently paying that cost.
- */
-export class DaemonVersionMismatchError extends Error {
-    daemonVersion;
-    clientVersion;
-    sessionCount;
-    pendingLinkCount;
-    constructor(daemonVersion, clientVersion, live, message) {
-        super(message ??
-            `The running Appduct daemon is version ${daemonVersion}, but this client is version ${clientVersion}. ` +
-                `It was not restarted automatically because ${describeLiveState(live)} would be lost. ` +
-                `Run "appduct daemon stop" once that state is expendable, or force it with "--daemon-restart".`);
-        this.daemonVersion = daemonVersion;
-        this.clientVersion = clientVersion;
-        this.name = "DaemonVersionMismatchError";
-        this.sessionCount = live.sessions;
-        this.pendingLinkCount = live.pendingLinks;
-    }
-}
-/**
- * Raised when the daemon *was* restarted and the daemon now answering still reports a different
- * version. Retrying would just kill daemon after daemon, so the check stops after one restart and
- * reports what it actually observed rather than guessing at a cause.
- */
-export class DaemonVersionRestartIneffectiveError extends DaemonVersionMismatchError {
-    constructor(daemonVersion, clientVersion, live) {
-        super(daemonVersion, clientVersion, live, `The Appduct daemon was restarted to match this client (version ${clientVersion}), but the daemon now answering still reports version ${daemonVersion}. ` +
-            `Either the old daemon never exited (compare "daemon.pid" with what "appduct daemon status" reports), ` +
-            `or another process spawned an older daemon in the meantime. ` +
-            `Run "appduct daemon stop", then retry.`);
-        this.name = "DaemonVersionRestartIneffectiveError";
-    }
-}
-/** Parses `1.2.3`, `1.2.3-beta.1`, `1.2.3+build`; `undefined` for anything else. */
-const parseVersion = (value) => {
-    const match = /^(\d+(?:\.\d+)*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value.trim());
-    if (!match) {
-        return undefined;
-    }
-    return {
-        numbers: match[1].split(".").map(Number),
-        // Build metadata (`+…`) is dropped, per semver: it never affects precedence, so two versions
-        // differing only there are the same version and neither restarts nor warns about the other.
-        prerelease: match[2]?.split("."),
-    };
-};
-const isNumericIdentifier = (identifier) => /^\d+$/u.test(identifier);
-/**
- * Semver §11's prerelease precedence, which a plain string compare gets wrong in both directions:
- * numeric identifiers compare as numbers (`rc.2` < `rc.10`, where `"rc.2" > "rc.10"` as strings),
- * a numeric identifier always ranks below an alphanumeric one, and when one side runs out of
- * identifiers first the shorter one ranks lower (`1.0.0-rc` < `1.0.0-rc.1`).
- */
-const comparePrerelease = (left, right) => {
-    const length = Math.max(left.length, right.length);
-    for (let index = 0; index < length; index += 1) {
-        const a = left[index];
-        const b = right[index];
-        if (a === undefined) {
-            return -1;
-        }
-        if (b === undefined) {
-            return 1;
-        }
-        if (a === b) {
-            continue;
-        }
-        const aNumeric = isNumericIdentifier(a);
-        const bNumeric = isNumericIdentifier(b);
-        if (aNumeric && bNumeric) {
-            return Number(a) < Number(b) ? -1 : 1;
-        }
-        if (aNumeric !== bNumeric) {
-            return aNumeric ? -1 : 1;
-        }
-        return a < b ? -1 : 1;
-    }
-    return 0;
-};
-/**
- * `-1` when `a` is older, `1` when newer, `0` when they are the same version; `undefined` when
- * either side is not a version this can order. A prerelease sorts before its release
- * (`1.0.0-rc.1` < `1.0.0`), which is what keeps an `-rc` build from restarting the release it is
- * testing.
- */
-const compareVersions = (a, b) => {
-    const left = parseVersion(a);
-    const right = parseVersion(b);
-    if (!left || !right) {
-        return undefined;
-    }
-    const length = Math.max(left.numbers.length, right.numbers.length);
-    for (let index = 0; index < length; index += 1) {
-        const difference = (left.numbers[index] ?? 0) - (right.numbers[index] ?? 0);
-        if (difference !== 0) {
-            return difference < 0 ? -1 : 1;
-        }
-    }
-    if (left.prerelease === undefined && right.prerelease === undefined) {
-        return 0;
-    }
-    if (left.prerelease === undefined) {
-        return 1;
-    }
-    if (right.prerelease === undefined) {
-        return -1;
-    }
-    return comparePrerelease(left.prerelease, right.prerelease);
-};
-/**
- * True when two version strings name the same version even though the strings differ — `1.2` and
- * `1.2.0`, or two builds differing only in `+metadata`. Comparing the raw strings would report
- * drift that does not exist and, worse, print a "the daemon is newer" notice about a daemon that
- * is exactly this version.
- */
-export const isSameVersion = (a, b) => {
-    return a === b || compareVersions(a, b) === 0;
-};
-const isConnectionMissingError = (error) => {
-    const code = error.code;
-    return code === "ENOENT" || code === "ECONNREFUSED";
-};
-/**
- * True when `error` indicates the daemon is not reachable at all — no listener at the socket
- * path (`ENOENT`/`ECONNREFUSED`), or a `DaemonUnavailableError` from a request that timed out or
- * had its connection drop mid-flight. Callers use this to decide whether a fallback (e.g. `daemon
- * stop`'s SIGTERM-via-pidfile path) applies, as opposed to a `DaemonRpcError` from a daemon that
- * is very much running but rejected the request.
- */
-export const isDaemonUnreachableError = (error) => {
-    return error instanceof DaemonUnavailableError || isConnectionMissingError(error);
-};
-let nextRequestId = 1;
-const sendRequest = (socketPath, method, params, timeoutMs) => {
-    return new Promise((resolve, reject) => {
-        const id = nextRequestId;
-        nextRequestId += 1;
-        let socket;
-        let settled = false;
-        let buffer = "";
-        const finish = (fn) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            clearTimeout(timeout);
-            socket.destroy();
-            fn();
-        };
-        const timeout = setTimeout(() => {
-            finish(() => reject(new DaemonUnavailableError(`Timed out waiting for a response to "${method}".`, "timeout")));
-        }, timeoutMs);
-        socket = connect(socketPath);
-        socket.on("error", (error) => {
-            finish(() => reject(error));
-        });
-        socket.on("connect", () => {
-            socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
-        });
-        socket.on("data", (chunk) => {
-            buffer += chunk.toString("utf8");
-            let newlineIndex = buffer.indexOf("\n");
-            while (newlineIndex !== -1) {
-                const line = buffer.slice(0, newlineIndex);
-                buffer = buffer.slice(newlineIndex + 1);
-                newlineIndex = buffer.indexOf("\n");
-                if (line.length === 0) {
-                    continue;
-                }
-                let message;
-                try {
-                    message = JSON.parse(line);
-                }
-                catch {
-                    continue;
-                }
-                if (message.id !== id) {
-                    continue;
-                }
-                if (message.error) {
-                    finish(() => reject(new DaemonRpcError(message.error.code, message.error.message, message.error.data)));
-                    return;
-                }
-                finish(() => resolve(message.result));
-                return;
-            }
-        });
-        socket.on("close", () => {
-            finish(() => reject(new DaemonUnavailableError("Connection to the Appduct daemon closed.", "closed")));
-        });
-    });
-};
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const pollForSocket = async (socketPath, timeoutMs, pollIntervalMs) => {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (await isSocketConnectable(socketPath)) {
-            return true;
-        }
-        await sleep(pollIntervalMs);
-    }
-    return isSocketConnectable(socketPath);
-};
-const unlinkStaleSocketIfDaemonDead = async (paths) => {
-    let pid;
-    try {
-        pid = Number.parseInt((await readFile(paths.pidFilePath, "utf8")).trim(), 10);
-    }
-    catch {
-        pid = undefined;
-    }
-    if (pid === undefined || Number.isNaN(pid) || !isProcessAlive(pid)) {
-        await rm(paths.socketPath, { force: true });
-    }
-};
-const defaultSpawn = async (args, context) => {
-    // Rotate before the new daemon's log fd is opened (issue #32). This is the only safe moment:
-    // afterwards the daemon holds the fd for its whole life. `appduct daemon start` spawns
-    // through this same path, so it rotates too. Reaching here means nothing answered the socket,
-    // which is *usually* but not always the same as "no daemon is writing this log" — hence the
-    // pidfile and socket guards inside, which decline to rotate under a daemon that is still there.
-    const paths = getStateDirPaths(context.stateDir);
-    await rotateDaemonLogIfNeeded({
-        logFilePath: context.logFilePath,
-        maxBytes: await resolveDaemonLogMaxBytes(context.stateDir),
-        pidFilePath: paths.pidFilePath,
-        socketPath: paths.socketPath,
-    });
-    const logFd = await open(context.logFilePath, "a", 0o600);
-    try {
-        // Best-effort, never fatal: this is the auto-spawn path, and a log mode that cannot be
-        // tightened is not a reason to fail every command that needs a daemon. See the helper.
-        await ensureDaemonLogMode(context.logFilePath);
-        const childEnv = { ...process.env, APPDUCT_STATE_DIR: context.stateDir };
-        // A daemon this client spawns must report its real version, whatever this process inherited.
-        // Otherwise a stray `APPDUCT_DAEMON_VERSION_OVERRIDE` in the operator's shell would be
-        // copied into the replacement, which would then mismatch too — an endless restart loop.
-        delete childEnv[DAEMON_VERSION_OVERRIDE_ENV];
-        const child = spawnChildProcess(process.execPath, [defaultBinPath, ...args], {
-            detached: true,
-            stdio: ["ignore", logFd.fd, logFd.fd],
-            env: childEnv,
-        });
-        child.unref();
-    }
-    finally {
-        await logFd.close();
-    }
-};
-/**
- * How long a spawn-lock may be held before another process treats it as abandoned. A restart holds
- * the lock across a status read, a `daemon.shutdown`, and a wait for the daemon to disappear, so
- * the ceiling has to be generous — but a Ctrl-C in that window used to leave the lock behind
- * forever, and every later command would then quietly skip spawning and time out on a socket that
- * was never going to appear.
- */
-const SPAWN_LOCK_STALE_MS = 30_000;
-/** `false` when the lock was still held when the wait ran out. */
-const pollUntilLockReleased = async (lockPath, timeoutMs, pollIntervalMs) => {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (!(await pathExists(lockPath))) {
-            return true;
-        }
-        await sleep(pollIntervalMs);
-    }
-    return !(await pathExists(lockPath));
-};
-/** The pid the pidfile currently names, or `undefined` when there is no readable one. */
-const readPidfilePid = async (paths) => {
-    try {
-        const pid = Number.parseInt((await readFile(paths.pidFilePath, "utf8")).trim(), 10);
-        return Number.isNaN(pid) ? undefined : pid;
-    }
-    catch {
-        return undefined;
-    }
-};
-const pathExists = async (target) => {
-    try {
-        await stat(target);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-/**
- * Takes the exclusive spawn-lock, reclaiming one that has been held past
- * {@link SPAWN_LOCK_STALE_MS} (its owner died without cleaning up). The takeover is itself racy
- * only in the sense that two processes could reclaim the same abandoned lock in the same instant —
- * which lands them exactly where the plain double-spawn race already does, and the pidfile's
- * `O_EXCL` still decides the winner.
- */
-const acquireSpawnLock = async (lockPath) => {
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            const lockHandle = await open(lockPath, "wx", 0o600);
-            await lockHandle.close();
-            return true;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST") {
-                throw error;
-            }
-        }
-        let heldForMs;
-        try {
-            heldForMs = Date.now() - (await stat(lockPath)).mtimeMs;
-        }
-        catch {
-            // Released between the failed create and the stat — go straight back and take it.
-            continue;
-        }
-        if (heldForMs < SPAWN_LOCK_STALE_MS) {
-            return false;
-        }
-        await rm(lockPath, { force: true });
-    }
-    return false;
-};
-/**
- * Takes the exclusive spawn-lock, spawns `daemon run` detached if this caller wins the race
- * (the loser just polls), then waits for the socket to become ready.
- */
-const spawnDaemonAndWait = async (paths, spawn, waitTimeoutMs, pollIntervalMs, options = {}) => {
-    const acquiredLock = await acquireSpawnLock(paths.spawnLockPath);
-    let lockWaitTimedOut = false;
-    if (acquiredLock) {
-        try {
-            const shouldSpawn = options.beforeSpawn ? await options.beforeSpawn() : true;
-            if (shouldSpawn) {
-                await unlinkStaleSocketIfDaemonDead(paths);
-                await spawn(["daemon", "run"], { stateDir: paths.root, logFilePath: paths.logFilePath });
-            }
-        }
-        finally {
-            await rm(paths.spawnLockPath, { force: true });
-        }
-    }
-    else if (options.awaitLockRelease) {
-        lockWaitTimedOut = !(await pollUntilLockReleased(paths.spawnLockPath, waitTimeoutMs, pollIntervalMs));
-    }
-    const ready = await pollForSocket(paths.socketPath, waitTimeoutMs, pollIntervalMs);
-    if (!ready) {
-        // A lock still sitting there is the single most useful thing to say here: it means another
-        // process is (or died) mid-spawn, and this one deliberately did not spawn a second daemon.
-        const lockHint = (await pathExists(paths.spawnLockPath))
-            ? ` Another process holds the spawn-lock at "${paths.spawnLockPath}"; if no "appduct daemon" is starting, delete it and retry.`
-            : "";
-        throw new DaemonUnavailableError(`Timed out waiting for the Appduct daemon socket at "${paths.socketPath}".${lockHint}`);
-    }
-    return { ownedLock: acquiredLock, lockWaitTimedOut };
-};
-// ---------------------------------------------------------------------------------------------
-// Daemon/client version drift (issue #30, ARCHITECTURE.md §4)
-// ---------------------------------------------------------------------------------------------
-/**
- * One in-flight-or-settled check per daemon socket path, so the extra `daemon.status` costs one
- * round-trip per process and concurrent callers (e.g. the MCP server's stream plus a first
- * `tools.list`) share a single check and a single restart rather than racing each other.
- */
-const versionChecks = new Map();
-/** Test seam: drops the per-process check cache so each test case starts from a clean slate. */
-export const resetDaemonVersionChecks = () => {
-    versionChecks.clear();
-};
-/**
- * Per-call timeout for the `daemon.status` and `daemon.shutdown` requests issued *while the
- * spawn-lock is held*. Deliberately much shorter than the general request timeout: everything
- * between taking the lock and releasing it is time in which no other process can spawn a daemon,
- * and an unresponsive daemon must not stretch that into tens of seconds.
- */
-const RESTART_REQUEST_TIMEOUT_MS = 3000;
-/**
- * `daemon.status`, auto-spawning a daemon first when nothing is listening. Returns `undefined`
- * when nothing is listening and auto-spawn is off — there is no daemon to drift from, and any
- * daemon this process spawns later is by definition this process's own build.
- */
-const readStatusSpawningIfNeeded = async (context) => {
-    try {
-        return await sendRequest(context.paths.socketPath, RPC_METHODS.daemonStatus, {}, context.requestTimeoutMs);
-    }
-    catch (error) {
-        if (!isConnectionMissingError(error)) {
-            throw error;
-        }
-        if (!context.autoSpawn) {
-            return undefined;
-        }
-        await spawnDaemonAndWait(context.paths, context.spawn, context.waitTimeoutMs, context.pollIntervalMs);
-        return sendRequest(context.paths.socketPath, RPC_METHODS.daemonStatus, {}, context.requestTimeoutMs);
-    }
-};
-/**
- * `daemon.status` against whatever is listening right now; `undefined` only when nothing is
- * listening at all. A *timeout* is not "gone" — it is a daemon that is alive and busy, and
- * spawning a second one over it would be the worst possible response — so it aborts the restart
- * with a message that says so.
- */
-const readStatusIfReachable = async (context) => {
-    try {
-        return await sendRequest(context.paths.socketPath, RPC_METHODS.daemonStatus, {}, RESTART_REQUEST_TIMEOUT_MS);
-    }
-    catch (error) {
-        if (isConnectionMissingError(error)) {
-            return undefined;
-        }
-        if (isRequestTimeoutError(error)) {
-            throw new DaemonUnavailableError(`The Appduct daemon at "${context.paths.socketPath}" did not answer "daemon.status" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was not replaced. ` +
-                `It is running but unresponsive — run "appduct daemon stop" and retry.`, "timeout");
-        }
-        throw error;
-    }
-};
-/**
- * True once nothing can answer at the socket *and* the pidfile no longer names a live process.
- * Both halves matter: the daemon closes its listener before releasing the pidfile, so a fresh
- * daemon spawned on "socket is gone" alone can lose the pidfile's `O_EXCL` race against the
- * outgoing one and die with `DaemonAlreadyRunningError`.
- */
-const isDaemonGone = async (paths) => {
-    if (await isSocketConnectable(paths.socketPath)) {
-        return false;
-    }
-    let pid;
-    try {
-        pid = Number.parseInt((await readFile(paths.pidFilePath, "utf8")).trim(), 10);
-    }
-    catch {
-        return true;
-    }
-    return pid === undefined || Number.isNaN(pid) || !isProcessAlive(pid);
-};
-/**
- * What a restart of this daemon would destroy. Defensive about both fields' presence rather than
- * indexing them blindly: `pendingLinks` is absent from daemons that predate the field (and drift with an
- * older daemon is the whole point of this code path), and a `TypeError` from deep inside the
- * version check would be a far worse diagnosis than the drift it was trying to report.
- */
-const readLiveState = (status) => {
-    return {
-        sessions: Array.isArray(status.sessions) ? status.sessions.length : 0,
-        pendingLinks: typeof status.pendingLinks === "number" ? status.pendingLinks : 0,
-    };
-};
-const isSafeToRestart = (live) => {
-    return live.sessions === 0 && live.pendingLinks === 0;
-};
-const pollUntilDaemonGone = async (paths, timeoutMs, pollIntervalMs) => {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (await isDaemonGone(paths)) {
-            return true;
-        }
-        await sleep(pollIntervalMs);
-    }
-    return isDaemonGone(paths);
-};
-/**
- * Replaces the running daemon with one spawned from this client's build. Runs under the same
- * exclusive spawn-lock as a cold-start spawn, so two upgraded CLIs starting at once produce one
- * replacement daemon, not two — and the loser waits for the lock rather than for a socket that
- * may still be the outgoing daemon's.
- */
-const restartDaemon = async (context) => {
-    // Which daemon was in charge before this attempt. Only used for the lock-contention case below,
-    // where this process never got to run the replacement itself and has to tell "the other process
-    // replaced it" apart from "nothing happened at all".
-    const pidBefore = await readPidfilePid(context.paths);
-    const outcome = await spawnDaemonAndWait(context.paths, context.spawn, context.waitTimeoutMs, context.pollIntervalMs, {
-        awaitLockRelease: true,
-        beforeSpawn: async () => {
-            // Re-read under the lock: another process may have replaced the daemon while this one was
-            // queued, and a session or link may have appeared since the status read that decided a
-            // restart was safe. (Not fully atomic — the daemon has no compare-and-shutdown — but it
-            // closes the window that a slow lock wait would otherwise leave wide open.)
-            const status = await readStatusIfReachable(context);
-            if (status === undefined) {
-                return true;
-            }
-            if (isSameVersion(status.version, context.check.clientVersion)) {
-                return false;
-            }
-            const live = readLiveState(status);
-            if (!isSafeToRestart(live) && !context.check.forceRestart) {
-                throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
-            }
-            try {
-                await sendRequest(context.paths.socketPath, RPC_METHODS.daemonShutdown, {}, RESTART_REQUEST_TIMEOUT_MS);
-            }
-            catch (error) {
-                if (isRequestTimeoutError(error)) {
-                    throw new DaemonUnavailableError(`The Appduct daemon at "${context.paths.socketPath}" did not acknowledge "daemon.shutdown" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was left running. ` +
-                        `Run "appduct daemon stop" and retry.`, "timeout");
-                }
-                // The daemon answers `shutdown` before teardown finishes, so a connection that is
-                // already gone (or drops mid-reply) is an ordinary outcome; the poll below is what
-                // actually establishes it left.
-                if (!isDaemonUnreachableError(error)) {
-                    throw error;
-                }
-            }
-            if (!(await pollUntilDaemonGone(context.paths, context.waitTimeoutMs, context.pollIntervalMs))) {
-                throw new DaemonUnavailableError(`The Appduct daemon at "${context.paths.socketPath}" did not shut down in time; run "appduct daemon stop" and retry.`);
-            }
-            return true;
-        },
-    });
-    if (!outcome.ownedLock && outcome.lockWaitTimedOut && (await readPidfilePid(context.paths)) === pidBefore) {
-        // Another process has held the spawn-lock past the wait and the daemon is still the same one.
-        // `pollForSocket` happily connected to it, but nothing was replaced — reporting that as a
-        // restart that "did not take effect" would blame the wrong thing entirely.
-        throw new DaemonUnavailableError(`The Appduct daemon at "${context.paths.socketPath}" did not shut down in time: another process has held the spawn-lock at ` +
-            `"${context.paths.spawnLockPath}" for longer than this command waited. Retry, or run "appduct daemon stop" if nothing is starting a daemon.`);
-    }
-};
-const warnOlderClient = (context, daemonVersion) => {
-    const message = `appduct: the running daemon is version ${daemonVersion}, newer than this client (${context.check.clientVersion}). ` +
-        `Continuing without restarting it — a newer daemon serves an older client, and replacing it would downgrade whatever started it. ` +
-        `Run "appduct daemon stop" if you want this client's daemon instead.\n`;
-    const warn = context.check.onWarning ?? ((text) => void process.stderr.write(text));
-    warn(message);
-};
-/**
- * Compares the daemon's version with this client's and, at most **once** per process, replaces a
- * daemon this client has outgrown.
- *
- * One restart, never a loop: each restart destroys whatever the daemon was holding, so retrying a
- * restart that did not take effect just kills daemon after daemon while reporting a cause that was
- * never true. If the replacement still disagrees, that is a different problem with a different
- * answer ({@link DaemonVersionRestartIneffectiveError}).
- */
-const runVersionCheck = async (context) => {
-    const status = await readStatusSpawningIfNeeded(context);
-    if (status === undefined) {
-        return;
-    }
-    if (isSameVersion(status.version, context.check.clientVersion)) {
-        return;
-    }
-    // Direction matters. Restarting is only ever right when this client has outgrown the daemon;
-    // a *newer* daemon already speaks everything this client knows, and replacing it would
-    // downgrade the daemon out from under whichever newer install started it — two installs on one
-    // machine would otherwise take turns killing each other's daemon on every command.
-    if ((compareVersions(context.check.clientVersion, status.version) ?? -1) <= 0) {
-        warnOlderClient(context, status.version);
-        return;
-    }
-    const live = readLiveState(status);
-    if (!isSafeToRestart(live) && !context.check.forceRestart) {
-        throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
-    }
-    await restartDaemon(context);
-    const replacement = await readStatusIfReachable(context);
-    if (replacement === undefined) {
-        throw new DaemonUnavailableError(`The Appduct daemon was restarted but nothing is listening at "${context.paths.socketPath}"; check "${context.paths.logFilePath}".`);
-    }
-    if (isSameVersion(replacement.version, context.check.clientVersion)) {
-        return;
-    }
-    if ((compareVersions(context.check.clientVersion, replacement.version) ?? -1) <= 0) {
-        warnOlderClient(context, replacement.version);
-        return;
-    }
-    throw new DaemonVersionRestartIneffectiveError(replacement.version, context.check.clientVersion, readLiveState(replacement));
-};
-/**
- * Runs {@link runVersionCheck} at most once per process per daemon socket. A mismatch that could
- * not be resolved stays cached (every later call in this process would reach the same daemon and
- * fail the same way); a transient failure does not, so a retry can still succeed.
- */
-const ensureDaemonVersion = async (paths, options, spawn) => {
-    const check = options.checkVersion;
-    if (!check) {
-        return;
-    }
-    const cached = versionChecks.get(paths.socketPath);
-    if (cached) {
-        return cached;
-    }
-    const pending = runVersionCheck({
-        paths,
-        spawn,
-        autoSpawn: options.autoSpawn ?? true,
-        requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
-        waitTimeoutMs: options.spawnWaitTimeoutMs ?? 5000,
-        pollIntervalMs: options.spawnPollIntervalMs ?? 100,
-        check,
-    }).catch((error) => {
-        if (!(error instanceof DaemonVersionMismatchError)) {
-            versionChecks.delete(paths.socketPath);
-        }
-        throw error;
-    });
-    versionChecks.set(paths.socketPath, pending);
-    return pending;
-};
-/**
- * Runs the version check on its own, without issuing a command RPC — the CLI dispatcher's seam
- * (issue #30). Pass `autoSpawn: false` (the default here) when the caller does not want a daemon
- * started just to be checked: nothing listening means nothing to drift from.
- */
-export const ensureDaemonVersionMatches = async (options) => {
-    const paths = getStateDirPaths(options.stateDir);
-    await ensureDaemonVersion(paths, { ...options, autoSpawn: options.autoSpawn ?? false }, options.spawn ?? defaultSpawn);
-};
-/** Calls a daemon RPC method, auto-spawning the daemon on a missing/refused connection. */
-export const callDaemon = async (method, params, options) => {
-    const paths = getStateDirPaths(options.stateDir);
-    const autoSpawn = options.autoSpawn ?? true;
-    const spawn = options.spawn ?? defaultSpawn;
-    const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
-    // Runs before the request so this call is answered by a daemon of the right version — never
-    // half-answered by the outgoing one.
-    await ensureDaemonVersion(paths, options, spawn);
-    try {
-        return await sendRequest(paths.socketPath, method, params, requestTimeoutMs);
-    }
-    catch (error) {
-        if (!autoSpawn || !isConnectionMissingError(error)) {
-            throw error;
-        }
-        await spawnDaemonAndWait(paths, spawn, options.spawnWaitTimeoutMs ?? 5000, options.spawnPollIntervalMs ?? 100);
-        return sendRequest(paths.socketPath, method, params, requestTimeoutMs);
-    }
-};
-/**
- * Opens a persistent connection to the daemon (auto-spawning as needed) for use cases that need
- * server→client notifications, e.g. `events.subscribe`.
- */
-export const openDaemonStream = async (options) => {
-    const paths = getStateDirPaths(options.stateDir);
-    const autoSpawn = options.autoSpawn ?? true;
-    const spawn = options.spawn ?? defaultSpawn;
-    const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
-    const connectSocket = () => {
-        return new Promise((resolve, reject) => {
-            const socket = connect(paths.socketPath);
-            socket.once("connect", () => {
-                socket.off("error", onError);
-                resolve(socket);
-            });
-            const onError = (error) => {
-                reject(error);
-            };
-            socket.once("error", onError);
-        });
-    };
-    // Resolved before the stream's socket is opened, so the connection this stream keeps for its
-    // whole life belongs to a daemon of the right version and no caller ever observes two daemons.
-    await ensureDaemonVersion(paths, options, spawn);
-    let socket;
-    try {
-        socket = await connectSocket();
-    }
-    catch (error) {
-        if (!autoSpawn || !isConnectionMissingError(error)) {
-            throw error;
-        }
-        await spawnDaemonAndWait(paths, spawn, options.spawnWaitTimeoutMs ?? 5000, options.spawnPollIntervalMs ?? 100);
-        socket = await connectSocket();
-    }
-    socket.on("error", () => {
-        // A stream consumer observes loss via `close`; never let a socket error crash the process.
-    });
-    const notificationListeners = new Set();
-    const closeListeners = new Set();
-    const pendingCalls = new Map();
-    let buffer = "";
-    socket.on("data", (chunk) => {
-        buffer += chunk.toString("utf8");
-        let newlineIndex = buffer.indexOf("\n");
-        while (newlineIndex !== -1) {
-            const line = buffer.slice(0, newlineIndex);
-            buffer = buffer.slice(newlineIndex + 1);
-            newlineIndex = buffer.indexOf("\n");
-            if (line.length === 0) {
-                continue;
-            }
-            let message;
-            try {
-                message = JSON.parse(line);
-            }
-            catch {
-                continue;
-            }
-            if (message.method === "event") {
-                for (const listener of notificationListeners) {
-                    try {
-                        listener(message.params);
-                    }
-                    catch {
-                        // A misbehaving subscriber (e.g. a throwing `waitForEvent` match predicate) must never
-                        // crash this loop — it would drop every other listener's notification, and any RPC
-                        // response batched in the same chunk, for the rest of this connection's lifetime.
-                    }
-                }
-                continue;
-            }
-            const pending = typeof message.id === "number" ? pendingCalls.get(message.id) : undefined;
-            if (!pending) {
-                continue;
-            }
-            pendingCalls.delete(message.id);
-            clearTimeout(pending.timeout);
-            if (message.error) {
-                pending.reject(new DaemonRpcError(message.error.code, message.error.message, message.error.data));
-            }
-            else {
-                pending.resolve(message.result);
-            }
-        }
-    });
-    socket.on("close", () => {
-        for (const [, pending] of pendingCalls) {
-            clearTimeout(pending.timeout);
-            pending.reject(new DaemonUnavailableError("Connection to the Appduct daemon closed.", "closed"));
-        }
-        pendingCalls.clear();
-        for (const listener of closeListeners) {
-            listener();
-        }
-    });
-    return {
-        call: (method, params, timeoutMs) => {
-            return new Promise((resolve, reject) => {
-                const id = nextRequestId;
-                nextRequestId += 1;
-                const timeout = setTimeout(() => {
-                    pendingCalls.delete(id);
-                    reject(new DaemonUnavailableError(`Timed out waiting for a response to "${method}".`, "timeout"));
-                }, timeoutMs ?? requestTimeoutMs);
-                pendingCalls.set(id, {
-                    resolve: resolve,
-                    reject,
-                    timeout,
-                });
-                socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
-            });
-        },
-        onNotification: (callback) => {
-            notificationListeners.add(callback);
-            return () => {
-                notificationListeners.delete(callback);
-            };
-        },
-        onClose: (callback) => {
-            closeListeners.add(callback);
-            return () => {
-                closeListeners.delete(callback);
-            };
-        },
-        close: () => {
-            socket.destroy();
-        },
-    };
-};