@dinoxx/dinox-cli 1.0.22 → 1.1.0

package/dist/daemon/index.js

@@ -1,15 +1,39 @@
 import { spawn } from 'child_process';
+import { existsSync } from 'node:fs';
 import { DaemonServer } from './server.js';
 import { DEFAULT_DAEMON_PORT } from './types.js';
-import { readPid, isProcessRunning, removePid } from './pid.js';
-import { isDaemonRunning } from './client.js';
-import { getPackageVersion } from '../utils/version.js';
+import { acquireDaemonStartLock, getDaemonSocketPath, isProcessRunning, readPid, removePid, } from './pid.js';
+import { getDaemonInfo, isLegacyDaemonInfo, requestDaemonShutdown, shutdownLegacyDaemon, waitForFreshDaemon, } from './client.js';
 import { DinoxError } from '../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableError, printHumanReadableLine, printSuccess, } from '../utils/output.js';
 import { registerCommandGroup } from '../commands/descriptor/register.js';
 import { FORMAT_OPTIONS } from '../commands/schema/globalOptions.js';
+import { loadConfig } from '../config/store.js';
+import { fingerprintDaemonRuntimeConfig, resolveConfig } from '../config/resolve.js';
+import { hydrateResolvedAuthIdentity } from '../auth/userInfo.js';
+import { withAsyncRelease } from '../utils/asyncRelease.js';
+import { getPackageVersion } from '../utils/version.js';
 const DAEMON_STOP_POLL_INTERVAL_MS = 100;
 const DAEMON_STOP_TIMEOUT_MS = 5_000;
+const DAEMON_CHILD_ENV = 'DINOX_INTERNAL_DAEMON_CHILD';
+async function withDaemonStartLock(run) {
+    return withAsyncRelease(() => acquireDaemonStartLock(), run);
+}
+function runningDaemonStatus(info, pidInfo) {
+    const pidFileMatches = Boolean(pidInfo
+        && pidInfo.pid === info.pid
+        && pidInfo.instanceId === info.instanceId);
+    return {
+        running: true,
+        unreachable: false,
+        pid: info.pid || pidInfo?.pid || null,
+        port: pidFileMatches ? pidInfo?.port ?? null : null,
+        socketPath: getDaemonSocketPath(),
+        transport: 'socket',
+        version: info.version,
+        stalePidFile: Boolean(pidInfo && !pidFileMatches),
+    };
+}
 function parsePort(value) {
     if (value === undefined || value === null || value === '') {
         return DEFAULT_DAEMON_PORT;
@@ -27,44 +51,84 @@ function parsePort(value) {
     }
     return Math.trunc(parsed);
 }
-async function waitForProcessExit(pid, timeoutMs) {
+async function waitForDaemonExit(instanceId, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (!isProcessRunning(pid)) {
+        const info = await getDaemonInfo();
+        if (!info || info.instanceId !== instanceId) {
             return true;
         }
         await new Promise((resolve) => setTimeout(resolve, DAEMON_STOP_POLL_INTERVAL_MS));
     }
-    return !isProcessRunning(pid);
+    const info = await getDaemonInfo();
+    return !info || info.instanceId !== instanceId;
 }
-async function startDaemon(port, detached = true, options = {}) {
-    if (await isDaemonRunning()) {
-        return { running: true, port, detached, alreadyRunning: true };
+async function expectedDaemonIdentity(baseConfig) {
+    const resolved = baseConfig ?? resolveConfig(await loadConfig());
+    const { config } = await hydrateResolvedAuthIdentity(resolved, { timeoutMs: resolved.sync.timeoutMs });
+    return {
+        version: getPackageVersion(),
+        userId: config.auth.userId ?? null,
+        tokenFingerprint: config.auth.tokenFingerprint ?? null,
+        runtimeConfigFingerprint: fingerprintDaemonRuntimeConfig(config),
+    };
+}
+function matchesRuntimeTokenBinding(info, version, config) {
+    return Boolean(config.auth.authorization
+        && info.authenticated
+        && info.version === version
+        && info.tokenFingerprint === (config.auth.tokenFingerprint ?? null)
+        && info.runtimeConfigFingerprint === fingerprintDaemonRuntimeConfig(config)
+        && (!config.auth.userId || info.userId === config.auth.userId));
+}
+export async function startDaemonLocked(port, detached, options = {}) {
+    const baseConfig = resolveConfig(await loadConfig());
+    const version = getPackageVersion();
+    const runningInfo = await getDaemonInfo();
+    if (runningInfo) {
+        if (matchesRuntimeTokenBinding(runningInfo, version, baseConfig)) {
+            return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: true };
+        }
+        throw new DinoxError('A stale daemon is already responding. Run `dino daemon restart` and retry.', {
+            code: 'DAEMON_STALE',
+            recoverable: true,
+        });
     }
+    const expected = await expectedDaemonIdentity(baseConfig);
     if (detached) {
         const args = ['daemon', 'start', '--port', String(port), '--no-detach'];
-        const child = spawn(process.argv[0], [process.argv[1], ...args], {
+        const entrypoint = process.argv[1];
+        if (!entrypoint) {
+            throw new DinoxError('Cannot determine the CLI entrypoint for daemon startup');
+        }
+        const child = spawn(process.execPath, [...process.execArgv, entrypoint, ...args], {
             detached: true,
             stdio: 'ignore',
+            env: { ...process.env, [DAEMON_CHILD_ENV]: '1' },
         });
         child.unref();
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-        if (await isDaemonRunning()) {
-            return { running: true, port, detached, alreadyRunning: false };
-        }
-        else {
-            return { running: false, port, detached, alreadyRunning: false };
+        const ready = await waitForFreshDaemon(expected.version, expected.userId, expected.tokenFingerprint, expected.runtimeConfigFingerprint);
+        if (!ready) {
+            child.kill('SIGTERM');
+            throw new DinoxError('Failed to start daemon');
         }
+        return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false };
     }
     else {
         if (!options.quiet) {
-            printHumanReadableLine(`Starting daemon on port ${port}...`);
+            printHumanReadableLine(`Starting daemon on ${getDaemonSocketPath()}...`);
         }
         const server = new DaemonServer();
-        await server.initialize();
-        await server.start(port);
+        try {
+            await server.initialize();
+            await server.start(port);
+        }
+        catch (error) {
+            await server.stop().catch(() => undefined);
+            throw error;
+        }
         if (!options.quiet) {
-            printHumanReadableLine(`Daemon running on port ${port} (PID: ${process.pid})`);
+            printHumanReadableLine(`Daemon running on ${getDaemonSocketPath()} (PID: ${process.pid})`);
         }
         process.on('SIGINT', async () => {
             if (!options.quiet) {
@@ -79,51 +143,131 @@ async function startDaemon(port, detached = true, options = {}) {
             process.exit(0);
         });
     }
-    return { running: true, port, detached, alreadyRunning: false };
+    return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false };
 }
-async function stopDaemon() {
+async function startDaemon(port, detached = true, options = {}) {
+    const internalChild = process.env[DAEMON_CHILD_ENV] === '1';
+    if (internalChild) {
+        return startDaemonLocked(port, detached, options);
+    }
+    return withDaemonStartLock(() => startDaemonLocked(port, detached, options));
+}
+/** Caller must hold the daemon start lock. */
+export async function stopDaemonLocked() {
     const pidInfo = readPid();
-    if (!pidInfo) {
+    const info = await getDaemonInfo();
+    if (!info) {
+        if (pidInfo && !isProcessRunning(pidInfo.pid)) {
+            const stalePidFile = pidInfo.instanceId
+                ? removePid(pidInfo.instanceId)
+                : removePid(undefined, { expectedPid: pidInfo.pid });
+            return { stopped: false, wasRunning: false, stalePidFile };
+        }
+        const socketExists = process.platform !== 'win32' && existsSync(getDaemonSocketPath());
+        if (pidInfo || socketExists) {
+            throw new DinoxError('Daemon artifacts exist, but the private socket is not responding; refusing to signal or delete unverified process state.', {
+                code: 'DAEMON_UNREACHABLE',
+                recoverable: true,
+                suggestion: 'Inspect the recorded process and socket ownership, then retry `dino daemon stop`.',
+            });
+        }
         return { stopped: false, wasRunning: false, stalePidFile: false };
     }
-    if (!isProcessRunning(pidInfo.pid)) {
-        removePid();
-        return { stopped: false, wasRunning: false, stalePidFile: true };
+    if (isLegacyDaemonInfo(info)) {
+        await shutdownLegacyDaemon(info, DAEMON_STOP_TIMEOUT_MS);
+        return { stopped: true, wasRunning: true, stalePidFile: false };
     }
     try {
-        process.kill(pidInfo.pid, 'SIGTERM');
+        await requestDaemonShutdown(info.instanceId, 2_000);
     }
     catch (error) {
-        throw new DinoxError(`Failed to stop daemon: ${error.message}`);
+        throw new DinoxError(`Failed to stop daemon through its private socket: ${error.message}`, {
+            code: 'DAEMON_STOP_FAILED',
+            suggestion: 'The daemon PID was not signaled because its process identity could not be verified safely.',
+        });
     }
-    const stopped = await waitForProcessExit(pidInfo.pid, DAEMON_STOP_TIMEOUT_MS);
+    const stopped = await waitForDaemonExit(info.instanceId, DAEMON_STOP_TIMEOUT_MS);
     if (!stopped) {
         throw new DinoxError(`Daemon did not stop within ${DAEMON_STOP_TIMEOUT_MS}ms. Try stopping it manually and rerun \`dino daemon status\`.`);
     }
-    removePid();
+    const replacement = await getDaemonInfo();
+    if (replacement) {
+        throw new DinoxError('A replacement daemon started while the requested daemon was stopping.', {
+            code: 'DAEMON_INSTANCE_CHANGED',
+            details: { stoppedInstanceId: info.instanceId, replacementInstanceId: replacement.instanceId },
+            suggestion: 'Retry after checking `dino daemon status`.',
+            recoverable: true,
+        });
+    }
+    removePid(info.instanceId);
     return { stopped: true, wasRunning: true, stalePidFile: false };
 }
+export async function stopDaemon() {
+    return withDaemonStartLock(() => stopDaemonLocked());
+}
 async function daemonStatus() {
     const pidInfo = readPid();
-    if (!pidInfo) {
-        return { running: false, pid: null, port: null, version: null, stalePidFile: false };
-    }
-    const running = await isDaemonRunning();
-    if (running) {
-        return { running: true, pid: pidInfo.pid, port: pidInfo.port, version: getPackageVersion(), stalePidFile: false };
+    const info = await getDaemonInfo();
+    if (info) {
+        // Report the daemon's handshake version, which can differ after a CLI update.
+        return runningDaemonStatus(info, pidInfo);
     }
     else {
-        removePid();
-        return { running: false, pid: null, port: null, version: null, stalePidFile: true };
+        if (pidInfo && !isProcessRunning(pidInfo.pid)) {
+            const stalePidFile = pidInfo.instanceId
+                ? removePid(pidInfo.instanceId)
+                : removePid(undefined, { expectedPid: pidInfo.pid });
+            if (stalePidFile) {
+                return { running: false, unreachable: false, pid: null, port: null, socketPath: null, transport: 'socket', version: null, stalePidFile: true };
+            }
+            // A replacement rewrote the PID metadata after the initial snapshot.
+            // Re-read once and leave the replacement instance untouched.
+            const replacementPidInfo = readPid();
+            const replacementInfo = await getDaemonInfo();
+            if (replacementInfo) {
+                return runningDaemonStatus(replacementInfo, replacementPidInfo);
+            }
+            const replacementSocketExists = process.platform !== 'win32' && existsSync(getDaemonSocketPath());
+            return {
+                running: false,
+                unreachable: Boolean(replacementPidInfo || replacementSocketExists),
+                pid: replacementPidInfo?.pid ?? null,
+                port: replacementPidInfo?.port ?? null,
+                socketPath: replacementSocketExists ? getDaemonSocketPath() : null,
+                transport: 'socket',
+                version: null,
+                stalePidFile: false,
+            };
+        }
+        const socketExists = process.platform !== 'win32' && existsSync(getDaemonSocketPath());
+        return {
+            running: false,
+            unreachable: Boolean(pidInfo || socketExists),
+            pid: pidInfo?.pid ?? null,
+            port: pidInfo?.port ?? null,
+            socketPath: socketExists ? getDaemonSocketPath() : null,
+            transport: 'socket',
+            version: null,
+            stalePidFile: false,
+        };
     }
 }
+export async function restartDaemonLocked(port = DEFAULT_DAEMON_PORT, options = {}) {
+    const stopResult = await stopDaemonLocked();
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    const startResult = await startDaemonLocked(port, true, options);
+    return { stopped: stopResult.stopped, ...startResult };
+}
+export async function restartDaemon(port = DEFAULT_DAEMON_PORT, options = {}) {
+    return withDaemonStartLock(() => restartDaemonLocked(port, options));
+}
 function printDaemonStartResult(result) {
     if (result.alreadyRunning) {
         printHumanReadableLine('Daemon is already running');
         return;
     }
     if (result.running) {
-        printHumanReadableLine(`Daemon started on port ${result.port}`);
+        printHumanReadableLine(`Daemon started on ${result.socketPath}`);
         return;
     }
     printHumanReadableError('Failed to start daemon');
@@ -141,18 +285,26 @@ function printDaemonStopResult(result) {
 }
 function printDaemonStatusResult(result) {
     if (!result.running) {
-        printHumanReadableLine(result.stalePidFile ? 'Status: Not running (stale PID file)' : 'Status: Not running');
+        printHumanReadableLine(result.unreachable
+            ? 'Status: Unreachable (process/socket ownership left intact)'
+            : result.stalePidFile
+                ? 'Status: Not running (stale PID file removed)'
+                : 'Status: Not running');
         return;
     }
     printHumanReadableLine('Status: Running');
     printHumanReadableLine(`PID: ${result.pid}`);
-    printHumanReadableLine(`Port: ${result.port}`);
+    printHumanReadableLine(`Transport: ${result.transport}`);
+    printHumanReadableLine(`Socket: ${result.socketPath}`);
     printHumanReadableLine(`Version: ${result.version}`);
 }
 async function runDaemonStart(context) {
     const port = parsePort(context.options.port);
     const structured = Boolean(getRequestedStructuredOutputFormat());
     const result = await startDaemon(port, context.options.detach !== false, { quiet: structured });
+    if (!result.running) {
+        throw new DinoxError('Failed to start daemon', { code: 'DAEMON_START_FAILED' });
+    }
     if (structured) {
         printSuccess(result);
         return;
@@ -177,15 +329,13 @@ async function runDaemonStatus() {
 }
 async function runDaemonRestart(context) {
     const structured = Boolean(getRequestedStructuredOutputFormat());
-    const stopResult = await stopDaemon();
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const startResult = await startDaemon(parsePort(context.options.port), true, { quiet: structured });
+    const result = await restartDaemon(parsePort(context.options.port), { quiet: structured });
     if (structured) {
-        printSuccess({ stopped: stopResult.stopped, ...startResult });
+        printSuccess(result);
         return;
     }
-    printDaemonStopResult(stopResult);
-    printDaemonStartResult(startResult);
+    printDaemonStopResult({ stopped: result.stopped, wasRunning: result.stopped, stalePidFile: false });
+    printDaemonStartResult(result);
 }
 export const daemonCommandGroup = {
     name: 'daemon',
@@ -195,7 +345,7 @@ export const daemonCommandGroup = {
             name: 'start',
             description: 'Start daemon process',
             options: [
-                { flags: '--port <number>', description: 'Daemon port', type: 'number', defaultValue: DEFAULT_DAEMON_PORT },
+                { flags: '--port <number>', description: 'Legacy compatibility field; daemon listens on a private local socket', type: 'number', defaultValue: DEFAULT_DAEMON_PORT },
                 { flags: '--no-detach', description: 'Run in foreground for debugging', type: 'boolean' },
             ],
             schema: {
@@ -206,7 +356,7 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon start acknowledgement',
-                    fields: ['running', 'port', 'detached', 'alreadyRunning'],
+                    fields: ['running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning'],
                 },
                 examples: ['dino daemon start', 'dino daemon start --port 17321', 'dino daemon start --no-detach'],
             },
@@ -240,7 +390,7 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon process status',
-                    fields: ['running', 'pid', 'port', 'version', 'stalePidFile'],
+                    fields: ['running', 'unreachable', 'pid', 'transport', 'socketPath', 'port', 'version', 'stalePidFile'],
                 },
                 examples: ['dino daemon status'],
             },
@@ -249,7 +399,7 @@ export const daemonCommandGroup = {
         {
             name: 'restart',
             description: 'Restart daemon process',
-            options: [{ flags: '--port <number>', description: 'Daemon port', type: 'number', defaultValue: DEFAULT_DAEMON_PORT }],
+            options: [{ flags: '--port <number>', description: 'Legacy compatibility field; daemon listens on a private local socket', type: 'number', defaultValue: DEFAULT_DAEMON_PORT }],
             schema: {
                 path: 'daemon.restart',
                 risk: 'write',
@@ -258,7 +408,7 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon restart acknowledgement',
-                    fields: ['stopped', 'running', 'port', 'detached', 'alreadyRunning'],
+                    fields: ['stopped', 'running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning'],
                 },
                 examples: ['dino daemon restart', 'dino daemon restart --port 17321'],
             },

package/dist/daemon/lifecycle.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedDinoxConfig } from '../config/types.js';
+import { printHumanReadableWarning } from '../utils/output.js';
+import { getPackageVersion } from '../utils/version.js';
+import { getDaemonInfo, shutdownDaemonForExclusiveAccess } from './client.js';
+import { startDaemonLocked } from './index.js';
+import { acquireDaemonStartLock, readPid, type DaemonPidInfo } from './pid.js';
+import { type DaemonPingResult } from './types.js';
+export type DaemonSnapshot = {
+    info: DaemonPingResult | null;
+    pidInfo: DaemonPidInfo | null;
+    socketExists: boolean;
+};
+export type SuspendedDaemon = {
+    snapshot: DaemonSnapshot;
+    wasStopped: boolean;
+    wasFresh: boolean;
+    port: number;
+};
+export type DaemonExclusiveAccessControl = {
+    suppressRestore(): void;
+};
+type DaemonLifecycleDependencies = {
+    acquireStartLock: typeof acquireDaemonStartLock;
+    getDaemonInfo: typeof getDaemonInfo;
+    readPid: typeof readPid;
+    shutdownDaemon: typeof shutdownDaemonForExclusiveAccess;
+    startDaemonLocked: typeof startDaemonLocked;
+    getPackageVersion: typeof getPackageVersion;
+    printWarning: typeof printHumanReadableWarning;
+};
+export declare function captureDaemonSnapshot(overrides?: Partial<DaemonLifecycleDependencies>): Promise<DaemonSnapshot>;
+export declare function daemonSnapshotIsFresh(config: ResolvedDinoxConfig, snapshot: DaemonSnapshot, version?: string): boolean;
+/** Caller must hold the daemon start lock until restore completes. */
+export declare function suspendDaemonForExclusiveAccessLocked(config: ResolvedDinoxConfig, timeoutMs: number, options?: {
+    snapshot?: DaemonSnapshot;
+    forceStop?: boolean;
+    dependencies?: Partial<DaemonLifecycleDependencies>;
+}): Promise<SuspendedDaemon>;
+/** Caller must hold the daemon start lock. */
+export declare function restoreSuspendedDaemonLocked(suspended: SuspendedDaemon, overrides?: Partial<DaemonLifecycleDependencies>): Promise<boolean>;
+export declare function withDaemonExclusiveAccess<T>(config: ResolvedDinoxConfig, timeoutMs: number, run: (control: DaemonExclusiveAccessControl) => Promise<T>, overrides?: Partial<DaemonLifecycleDependencies>): Promise<T>;
+export {};

package/dist/daemon/lifecycle.js

@@ -0,0 +1,115 @@
+import { existsSync } from 'node:fs';
+import { getPowerSyncDbPath } from '../config/paths.js';
+import { fingerprintDaemonRuntimeConfig } from '../config/resolve.js';
+import { printHumanReadableWarning } from '../utils/output.js';
+import { getPackageVersion } from '../utils/version.js';
+import { getDaemonInfo, isDaemonFresh, shutdownDaemonForExclusiveAccess, } from './client.js';
+import { startDaemonLocked } from './index.js';
+import { acquireDaemonStartLock, getDaemonSocketPath, readPid, } from './pid.js';
+import { DEFAULT_DAEMON_PORT } from './types.js';
+const daemonLifecycleDependencies = {
+    acquireStartLock: acquireDaemonStartLock,
+    getDaemonInfo,
+    readPid,
+    shutdownDaemon: shutdownDaemonForExclusiveAccess,
+    startDaemonLocked,
+    getPackageVersion,
+    printWarning: printHumanReadableWarning,
+};
+function dependencies(overrides) {
+    return { ...daemonLifecycleDependencies, ...overrides };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function snapshotPort(snapshot) {
+    const pidFileMatches = Boolean(snapshot.info
+        && snapshot.pidInfo
+        && snapshot.pidInfo.pid === snapshot.info.pid
+        && snapshot.pidInfo.instanceId === snapshot.info.instanceId);
+    return pidFileMatches ? snapshot.pidInfo?.port ?? DEFAULT_DAEMON_PORT : DEFAULT_DAEMON_PORT;
+}
+export async function captureDaemonSnapshot(overrides = {}) {
+    const deps = dependencies(overrides);
+    return {
+        info: await deps.getDaemonInfo(),
+        pidInfo: deps.readPid(),
+        socketExists: process.platform !== 'win32' && existsSync(getDaemonSocketPath()),
+    };
+}
+export function daemonSnapshotIsFresh(config, snapshot, version = getPackageVersion()) {
+    return Boolean(snapshot.info
+        && isDaemonFresh(snapshot.info, version, config.auth.userId ?? null, config.auth.tokenFingerprint ?? null, fingerprintDaemonRuntimeConfig(config)));
+}
+/** Caller must hold the daemon start lock until restore completes. */
+export async function suspendDaemonForExclusiveAccessLocked(config, timeoutMs, options = {}) {
+    const deps = dependencies(options.dependencies ?? {});
+    const snapshot = options.snapshot ?? await captureDaemonSnapshot(deps);
+    const wasFresh = daemonSnapshotIsFresh(config, snapshot, deps.getPackageVersion());
+    const daemonUsesTargetDatabase = !snapshot.info
+        || getPowerSyncDbPath(snapshot.info.userId) === getPowerSyncDbPath(config.auth.userId);
+    const wasStopped = options.forceStop || daemonUsesTargetDatabase
+        ? await deps.shutdownDaemon(Math.min(timeoutMs, 10_000), snapshot.info?.instanceId)
+        : false;
+    return {
+        snapshot,
+        wasStopped,
+        wasFresh,
+        port: snapshotPort(snapshot),
+    };
+}
+/** Caller must hold the daemon start lock. */
+export async function restoreSuspendedDaemonLocked(suspended, overrides = {}) {
+    if (!suspended.wasStopped || !suspended.wasFresh) {
+        return false;
+    }
+    const deps = dependencies(overrides);
+    await deps.startDaemonLocked(suspended.port, true, { quiet: true });
+    return true;
+}
+export async function withDaemonExclusiveAccess(config, timeoutMs, run, overrides = {}) {
+    const deps = dependencies(overrides);
+    const releaseStartLock = await deps.acquireStartLock(timeoutMs);
+    let suspended = null;
+    let restoreAllowed = true;
+    let outcome;
+    const control = {
+        suppressRestore() {
+            restoreAllowed = false;
+        },
+    };
+    try {
+        suspended = await suspendDaemonForExclusiveAccessLocked(config, timeoutMs, {
+            dependencies: deps,
+        });
+        try {
+            outcome = { ok: true, value: await run(control) };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+    }
+    catch (error) {
+        outcome = { ok: false, error };
+    }
+    finally {
+        if (suspended && restoreAllowed) {
+            try {
+                await restoreSuspendedDaemonLocked(suspended, deps);
+            }
+            catch (error) {
+                deps.printWarning(`warning: failed to restore daemon after local command: ${errorMessage(error)}`);
+            }
+        }
+        try {
+            await releaseStartLock();
+        }
+        catch (error) {
+            deps.printWarning(`warning: failed to release daemon lifecycle lock: ${errorMessage(error)}`);
+        }
+    }
+    if (!outcome.ok) {
+        throw outcome.error;
+    }
+    return outcome.value;
+}

package/dist/daemon/pid.d.ts

@@ -1,10 +1,23 @@
+export type DaemonPidInfo = {
+    pid: number;
+    port: number;
+    instanceId: string | null;
+    startedAt: string | null;
+};
 export declare function getDaemonDir(): string;
 export declare function getPidFilePath(): string;
 export declare function getPortFilePath(): string;
-export declare function savePid(pid: number, port: number): void;
-export declare function readPid(): {
-    pid: number;
-    port: number;
-} | null;
-export declare function removePid(): void;
+export declare function getSocketFilePath(): string;
+export declare function getDaemonSocketPath(): string;
+export declare function getTokenFilePath(): string;
+export declare function getStartLockFilePath(): string;
+export declare function ensureDaemonDir(): string;
+export declare function savePid(pid: number, port: number, instanceId: string): void;
+export declare function readPid(): DaemonPidInfo | null;
+export declare function removePid(expectedInstanceId?: string, options?: {
+    allowMissingOwner?: boolean;
+    expectedPid?: number;
+}): boolean;
 export declare function isProcessRunning(pid: number): boolean;
+export declare function isLegacyDaemonProcess(pid: number, daemonUptimeMs: number): Promise<boolean>;
+export declare function acquireDaemonStartLock(timeoutMs?: number): Promise<() => Promise<void>>;