@dinoxx/dinox-cli 2.5.2 → 2.7.0

package/dist/daemon/index.js

@@ -1,4 +1,3 @@
-import { spawn } from 'child_process';
 import { existsSync } from 'node:fs';
 import { DaemonServer } from './server.js';
 import { DEFAULT_DAEMON_PORT } from './types.js';
@@ -14,12 +13,33 @@ import { hydrateResolvedAuthIdentity } from '../auth/userInfo.js';
 import { withAsyncRelease } from '../utils/asyncRelease.js';
 import { remainingDeadlineMs } from '../utils/deadline.js';
 import { getPackageVersion } from '../utils/version.js';
+import { DAEMON_CHILD_ENV, daemonServiceSpec, envTokenOverridesLogin, launchDaemon } from './launch.js';
+import { getDaemonLogPath, rotateDaemonLog, writeDaemonLogLine } from './log.js';
+import { DAEMON_SERVICE_ENV, getDaemonService } from './supervisor.js';
+import { superviseCurrentDaemon } from './supervise.js';
+import { normalizeAuthToken } from '../utils/authToken.js';
 const DAEMON_STOP_POLL_INTERVAL_MS = 100;
 const DAEMON_STOP_TIMEOUT_MS = 5_000;
-const DAEMON_CHILD_ENV = 'DINOX_INTERNAL_DAEMON_CHILD';
+const DAEMON_SERVICE_READY_TIMEOUT_MS = 20_000;
+const DAEMON_CRASH_STOP_TIMEOUT_MS = 5_000;
 async function withDaemonStartLock(run) {
     return withAsyncRelease(() => acquireDaemonStartLock(), run);
 }
+function installedServiceKind() {
+    const service = getDaemonService();
+    return service?.isInstalled() ? service.kind : null;
+}
+function notRunningStatus(fields) {
+    return {
+        running: false,
+        transport: 'socket',
+        version: null,
+        service: installedServiceKind(),
+        supervised: null,
+        logPath: getDaemonLogPath(),
+        ...fields,
+    };
+}
 function runningDaemonStatus(info, pidInfo) {
     const pidFileMatches = Boolean(pidInfo
         && pidInfo.pid === info.pid
@@ -33,6 +53,9 @@ function runningDaemonStatus(info, pidInfo) {
         transport: 'socket',
         version: info.version,
         stalePidFile: Boolean(pidInfo && !pidFileMatches),
+        service: installedServiceKind(),
+        supervised: Boolean(info.supervisor),
+        logPath: getDaemonLogPath(),
     };
 }
 function parsePort(value) {
@@ -110,7 +133,7 @@ export async function startDaemonLocked(port, detached, options = {}) {
     const runningInfo = await getDaemonInfo(remainingStartTimeoutMs('initial-ping'));
     if (runningInfo) {
         if (matchesRuntimeTokenBinding(runningInfo, version, baseConfig)) {
-            return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: true };
+            return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: true, service: runningInfo.supervisor ?? null };
         }
         throw new DinoxError('A stale daemon is already responding. Run `dino daemon restart` and retry.', {
             code: 'DAEMON_STALE',
@@ -119,54 +142,78 @@ export async function startDaemonLocked(port, detached, options = {}) {
     }
     const expected = await expectedDaemonIdentity(baseConfig, remainingStartTimeoutMs('auth-hydration'));
     if (detached) {
-        const args = ['daemon', 'start', '--port', String(port), '--no-detach'];
-        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();
+        const launch = await launchDaemon(port);
         const ready = await waitForFreshDaemon(expected.version, expected.userId, expected.tokenFingerprint, expected.runtimeConfigFingerprint, remainingStartTimeoutMs('ready-poll'));
         if (!ready) {
-            child.kill('SIGTERM');
-            throw new DinoxError('Failed to start daemon');
+            launch.abort();
+            throw new DinoxError('Failed to start daemon', {
+                code: 'DAEMON_START_FAILED',
+                details: { service: launch.service, logPath: getDaemonLogPath() },
+                suggestion: `Inspect ${getDaemonLogPath()} for the daemon's startup error.`,
+            });
         }
-        return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false };
+        return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false, service: launch.service };
     }
     else {
+        await serveDaemonInForeground(port, options);
+    }
+    return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false, service: null };
+}
+/**
+ * Runs the daemon in this process until a signal or shutdown request. A crash
+ * is logged and exits non-zero, so a service manager restarts it; a clean
+ * stop exits 0 and stays stopped.
+ */
+async function serveDaemonInForeground(port, options) {
+    if (process.env[DAEMON_SERVICE_ENV]) {
+        // A service manager holds the log open in append mode; keep it bounded.
+        rotateDaemonLog();
+    }
+    if (!options.quiet) {
+        printHumanReadableLine(`Starting daemon on ${getDaemonSocketPath()}...`);
+    }
+    const server = new DaemonServer();
+    try {
+        await server.initialize();
+        await server.start(port);
+    }
+    catch (error) {
+        await server.stop().catch(() => undefined);
+        throw error;
+    }
+    if (!options.quiet) {
+        printHumanReadableLine(`Daemon running on ${getDaemonSocketPath()} (PID: ${process.pid})`);
+    }
+    writeDaemonLogLine('dinox-daemon', 'started', {
+        pid: process.pid,
+        version: getPackageVersion(),
+        supervisor: process.env[DAEMON_SERVICE_ENV] ?? null,
+    });
+    const stopAndExit = async (reason, exitCode) => {
+        writeDaemonLogLine('dinox-daemon', 'stopping', { reason });
+        const forceExit = setTimeout(() => process.exit(exitCode), DAEMON_CRASH_STOP_TIMEOUT_MS);
+        forceExit.unref();
+        await server.stop().catch(() => undefined);
+        process.exit(exitCode);
+    };
+    process.on('SIGINT', () => {
         if (!options.quiet) {
-            printHumanReadableLine(`Starting daemon on ${getDaemonSocketPath()}...`);
-        }
-        const server = new DaemonServer();
-        try {
-            await server.initialize();
-            await server.start(port);
-        }
-        catch (error) {
-            await server.stop().catch(() => undefined);
-            throw error;
-        }
-        if (!options.quiet) {
-            printHumanReadableLine(`Daemon running on ${getDaemonSocketPath()} (PID: ${process.pid})`);
+            printHumanReadableLine('');
+            printHumanReadableLine('Stopping daemon...');
         }
-        process.on('SIGINT', async () => {
-            if (!options.quiet) {
-                printHumanReadableLine('');
-                printHumanReadableLine('Stopping daemon...');
-            }
-            await server.stop();
-            process.exit(0);
-        });
-        process.on('SIGTERM', async () => {
-            await server.stop();
-            process.exit(0);
+        void stopAndExit('SIGINT', 0);
+    });
+    process.on('SIGTERM', () => void stopAndExit('SIGTERM', 0));
+    // No controlling terminal to lose; never let a hangup end the daemon.
+    process.on('SIGHUP', () => undefined);
+    const crash = (kind) => (error) => {
+        writeDaemonLogLine('dinox-daemon', kind, {
+            error: error instanceof Error ? error.stack ?? error.message : String(error),
         });
-    }
-    return { running: true, port, socketPath: getDaemonSocketPath(), transport: 'socket', detached, alreadyRunning: false };
+        void stopAndExit(kind, 1);
+    };
+    process.on('uncaughtException', crash('uncaught exception'));
+    process.on('unhandledRejection', crash('unhandled rejection'));
 }
 async function startDaemon(port, detached = true, options = {}) {
     const internalChild = process.env[DAEMON_CHILD_ENV] === '1';
@@ -241,7 +288,7 @@ async function daemonStatus() {
                 ? 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 };
+                return notRunningStatus({ unreachable: false, pid: null, port: null, socketPath: null, stalePidFile: true });
             }
             // A replacement rewrote the PID metadata after the initial snapshot.
             // Re-read once and leave the replacement instance untouched.
@@ -251,28 +298,22 @@ async function daemonStatus() {
                 return runningDaemonStatus(replacementInfo, replacementPidInfo);
             }
             const replacementSocketExists = process.platform !== 'win32' && existsSync(getDaemonSocketPath());
-            return {
-                running: false,
+            return notRunningStatus({
                 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,
+        return notRunningStatus({
             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 = {}) {
@@ -284,6 +325,77 @@ export async function restartDaemonLocked(port = DEFAULT_DAEMON_PORT, options =
 export async function restartDaemon(port = DEFAULT_DAEMON_PORT, options = {}) {
     return withDaemonStartLock(() => restartDaemonLocked(port, options));
 }
+/**
+ * Hands the daemon to the platform's service manager so it no longer belongs
+ * to whichever process first started it, then waits until the managed
+ * instance answers with the current identity.
+ */
+export async function installDaemonService(port = DEFAULT_DAEMON_PORT) {
+    const service = getDaemonService();
+    if (!service) {
+        throw new DinoxError(`No supported service manager on ${process.platform}; keep using \`dino daemon start\`.`, {
+            code: 'DAEMON_SERVICE_UNSUPPORTED',
+            details: { platform: process.platform },
+        });
+    }
+    const raw = await loadConfig();
+    if (!normalizeAuthToken(raw.auth?.authorization)) {
+        throw new DinoxError('The daemon service runs with the saved login, and none is saved.', {
+            code: 'AUTH_REQUIRED',
+            suggestion: 'Run `dino auth login`, then retry `dino daemon install`.',
+        });
+    }
+    if (envTokenOverridesLogin(raw)) {
+        throw new DinoxError('DINOX_TOKEN selects a different account than the saved login, and the daemon service only uses the saved login.', {
+            code: 'DAEMON_SERVICE_UNSUPPORTED',
+            details: { reason: 'env-token' },
+            suggestion: 'Unset DINOX_TOKEN, or save that token with `dino auth login`, then retry.',
+        });
+    }
+    return withDaemonStartLock(async () => {
+        const expected = await expectedDaemonIdentity(resolveConfig(raw));
+        const stopResult = await stopDaemonLocked();
+        await service.install(daemonServiceSpec(service, port));
+        const ready = await waitForFreshDaemon(expected.version, expected.userId, expected.tokenFingerprint, expected.runtimeConfigFingerprint, DAEMON_SERVICE_READY_TIMEOUT_MS);
+        if (!ready) {
+            throw new DinoxError(`The ${service.kind} service was installed, but the daemon did not become ready.`, {
+                code: 'DAEMON_START_FAILED',
+                details: { service: service.kind, definitionPath: service.definitionPath, logPath: getDaemonLogPath() },
+                suggestion: `Inspect ${getDaemonLogPath()}, then run \`dino daemon status\`.`,
+            });
+        }
+        return {
+            installed: true,
+            service: service.kind,
+            label: service.label,
+            definitionPath: service.definitionPath,
+            logPath: getDaemonLogPath(),
+            running: true,
+            replacedRunning: stopResult.stopped,
+        };
+    });
+}
+/** Stops the managed daemon and removes its service definition. */
+export async function uninstallDaemonService() {
+    const service = getDaemonService();
+    if (!service) {
+        return { uninstalled: false, service: null, definitionPath: null };
+    }
+    return withDaemonStartLock(async () => {
+        if (service.isInstalled()) {
+            // Stop through the socket first: a clean exit is not restarted, and
+            // deleting a Windows task does not end the process it started.
+            const info = await getDaemonInfo();
+            if (info?.supervisor === service.kind)
+                await stopDaemonLocked();
+        }
+        return {
+            uninstalled: await service.uninstall(),
+            service: service.kind,
+            definitionPath: service.definitionPath,
+        };
+    });
+}
 function printDaemonStartResult(result) {
     if (result.alreadyRunning) {
         printHumanReadableLine('Daemon is already running');
@@ -320,10 +432,40 @@ function printDaemonStatusResult(result) {
     printHumanReadableLine(`Transport: ${result.transport}`);
     printHumanReadableLine(`Socket: ${result.socketPath}`);
     printHumanReadableLine(`Version: ${result.version}`);
+    printHumanReadableLine(`Service: ${result.service ?? 'not installed'}${result.service && !result.supervised ? ' (running daemon is not managed by it)' : ''}`);
+    printHumanReadableLine(`Log: ${result.logPath}`);
+    if (!result.supervised) {
+        printHumanReadableLine('Note: this daemon belongs to the process that started it. Run `dino daemon install` to keep it (and agent gateways) running independently.');
+    }
+}
+function printDaemonInstallResult(result) {
+    printHumanReadableLine(`Installed ${result.service} service ${result.label}`);
+    printHumanReadableLine(`Definition: ${result.definitionPath}`);
+    printHumanReadableLine(`Log: ${result.logPath}`);
+    printHumanReadableLine(`The daemon now starts at ${result.service === 'schtasks' ? 'logon (Task Scheduler)' : 'login'} and restarts after a crash.`);
+    if (result.service === 'systemd') {
+        printHumanReadableLine('To keep it running after you log out, run `loginctl enable-linger`.');
+    }
+}
+function printDaemonUninstallResult(result) {
+    if (!result.service) {
+        printHumanReadableLine(`No supported service manager on ${process.platform}; nothing to uninstall.`);
+        return;
+    }
+    printHumanReadableLine(result.uninstalled
+        ? `Removed ${result.service} service; the daemon is stopped.`
+        : 'The daemon service is not installed.');
 }
 async function runDaemonStart(context) {
     const port = parsePort(context.options.port);
     const structured = Boolean(getRequestedStructuredOutputFormat());
+    if (context.options.detach === false && process.env[DAEMON_SERVICE_ENV]
+        && !resolveConfig(await loadConfig()).auth.authorization) {
+        // Started at login by the service while signed out: exit cleanly so the
+        // service does not retry; the next command after `dino auth login` starts it.
+        writeDaemonLogLine('dinox-daemon', 'not signed in; staying stopped until `dino auth login`');
+        return;
+    }
     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' });
@@ -350,6 +492,25 @@ async function runDaemonStatus() {
     }
     printDaemonStatusResult(result);
 }
+async function runDaemonSupervise(context) {
+    process.exitCode = await superviseCurrentDaemon(parsePort(context.options.port));
+}
+async function runDaemonInstall(context) {
+    const result = await installDaemonService(parsePort(context.options.port));
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess(result);
+        return;
+    }
+    printDaemonInstallResult(result);
+}
+async function runDaemonUninstall() {
+    const result = await uninstallDaemonService();
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess(result);
+        return;
+    }
+    printDaemonUninstallResult(result);
+}
 async function runDaemonRestart(context) {
     const structured = Boolean(getRequestedStructuredOutputFormat());
     const result = await restartDaemon(parsePort(context.options.port), { quiet: structured });
@@ -379,7 +540,7 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon start acknowledgement',
-                    fields: ['running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning'],
+                    fields: ['running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning', 'service'],
                 },
                 examples: ['dino daemon start', 'dino daemon start --port 17321', 'dino daemon start --no-detach'],
             },
@@ -413,7 +574,7 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon process status',
-                    fields: ['running', 'unreachable', 'pid', 'transport', 'socketPath', 'port', 'version', 'stalePidFile'],
+                    fields: ['running', 'unreachable', 'pid', 'transport', 'socketPath', 'port', 'version', 'stalePidFile', 'service', 'supervised', 'logPath'],
                 },
                 examples: ['dino daemon status'],
             },
@@ -431,12 +592,65 @@ export const daemonCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Daemon restart acknowledgement',
-                    fields: ['stopped', 'running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning'],
+                    fields: ['stopped', 'running', 'transport', 'socketPath', 'port', 'detached', 'alreadyRunning', 'service'],
                 },
                 examples: ['dino daemon restart', 'dino daemon restart --port 17321'],
             },
             action: runDaemonRestart,
         },
+        {
+            name: 'install',
+            description: 'Run the daemon as a login service (launchd / systemd) so it outlives the shell or agent that started it',
+            options: [{ flags: '--port <number>', description: 'Legacy compatibility field; daemon listens on a private local socket', type: 'number', defaultValue: DEFAULT_DAEMON_PORT }],
+            schema: {
+                path: 'daemon.install',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Installed daemon service',
+                    fields: ['installed', 'service', 'label', 'definitionPath', 'logPath', 'running', 'replacedRunning'],
+                },
+                examples: ['dino daemon install'],
+            },
+            action: runDaemonInstall,
+        },
+        {
+            name: 'uninstall',
+            description: 'Stop the daemon service and remove it from the login session',
+            schema: {
+                path: 'daemon.uninstall',
+                risk: 'write',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Daemon service removal acknowledgement',
+                    fields: ['uninstalled', 'service', 'definitionPath'],
+                },
+                examples: ['dino daemon uninstall'],
+            },
+            action: runDaemonUninstall,
+        },
+        {
+            name: 'supervise',
+            description: 'Run the daemon in the foreground and restart it after a crash (used by the Windows logon task)',
+            options: [{ flags: '--port <number>', description: 'Legacy compatibility field; daemon listens on a private local socket', type: 'number', defaultValue: DEFAULT_DAEMON_PORT }],
+            schema: {
+                path: 'daemon.supervise',
+                risk: 'write',
+                auth: 'none',
+                globalOptions: [],
+                output: {
+                    type: 'structured',
+                    summary: 'Runs until the daemon exits cleanly or the supervisor is stopped; no structured payload',
+                    fields: [],
+                },
+                examples: ['dino daemon supervise'],
+            },
+            action: runDaemonSupervise,
+        },
     ],
 };
 export function registerDaemonCommands(program) {

package/dist/daemon/launch.d.ts

@@ -0,0 +1,31 @@
+import type { DinoxConfig } from '../config/types.js';
+import { type DaemonService, type DaemonServiceKind, type DaemonServiceSpec } from './supervisor.js';
+/** Tells a daemon child its parent holds the start lock (or that it runs under a service). */
+export declare const DAEMON_CHILD_ENV = "DINOX_INTERNAL_DAEMON_CHILD";
+export type DaemonLaunch = {
+    /** The service manager that started it, or null for a detached child process. */
+    service: DaemonServiceKind | null;
+    /** Gives up on a launch that never became ready. */
+    abort(): void;
+};
+/**
+ * A service only knows the saved login. When DINOX_TOKEN selects a different
+ * account, the caller needs a daemon bound to that token, which only a child
+ * of its own environment can have.
+ */
+export declare function envTokenOverridesLogin(raw: DinoxConfig, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * What the service definition runs: this CLI, with no secrets written to disk.
+ * Task Scheduler cannot restart a crashed process, so on Windows the service
+ * runs the supervisor, which runs the daemon.
+ */
+export declare function daemonServiceSpec(service: DaemonService, port: number): DaemonServiceSpec;
+/** The installed service when this caller can use it, else null. */
+export declare function usableDaemonService(): Promise<DaemonService | null>;
+/**
+ * Starts a daemon. Caller must hold the daemon start lock and have stopped any
+ * stale daemon. Uses the installed service when there is one (refreshing its
+ * definition if this CLI's program, arguments or environment changed, e.g.
+ * after `dino update`), otherwise a detached child with a clean environment.
+ */
+export declare function launchDaemon(port: number): Promise<DaemonLaunch>;

package/dist/daemon/launch.js

@@ -0,0 +1,95 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import { loadConfig } from '../config/store.js';
+import { DINOX_TOKEN_ENV_VAR, normalizeAuthToken, readEnvAuthToken } from '../utils/authToken.js';
+import { DinoxError } from '../utils/errors.js';
+import { buildDaemonEnv } from './env.js';
+import { closeDaemonLogFd, getDaemonLogPath, openDaemonLogForChild } from './log.js';
+import { ensureDaemonDir } from './pid.js';
+import { DAEMON_SERVICE_ENV, getDaemonService, } from './supervisor.js';
+/** Tells a daemon child its parent holds the start lock (or that it runs under a service). */
+export const DAEMON_CHILD_ENV = 'DINOX_INTERNAL_DAEMON_CHILD';
+function daemonCommandLine(port, mode = 'start') {
+    const entrypoint = process.argv[1];
+    if (!entrypoint) {
+        throw new DinoxError('Cannot determine the CLI entrypoint for daemon startup', { code: 'DAEMON_START_FAILED' });
+    }
+    return {
+        program: process.execPath,
+        args: mode === 'supervise'
+            ? [...process.execArgv, entrypoint, 'daemon', 'supervise', '--port', String(port)]
+            : [...process.execArgv, entrypoint, 'daemon', 'start', '--port', String(port), '--no-detach'],
+    };
+}
+/**
+ * A service only knows the saved login. When DINOX_TOKEN selects a different
+ * account, the caller needs a daemon bound to that token, which only a child
+ * of its own environment can have.
+ */
+export function envTokenOverridesLogin(raw, env = process.env) {
+    const envToken = readEnvAuthToken(env);
+    return Boolean(envToken && envToken !== normalizeAuthToken(raw.auth?.authorization));
+}
+/**
+ * What the service definition runs: this CLI, with no secrets written to disk.
+ * Task Scheduler cannot restart a crashed process, so on Windows the service
+ * runs the supervisor, which runs the daemon.
+ */
+export function daemonServiceSpec(service, port) {
+    const { program, args } = daemonCommandLine(port, service.kind === 'schtasks' ? 'supervise' : 'start');
+    const env = buildDaemonEnv();
+    delete env[DINOX_TOKEN_ENV_VAR];
+    env[DAEMON_SERVICE_ENV] = service.kind;
+    env[DAEMON_CHILD_ENV] = '1';
+    return { program, args, env, workingDirectory: os.homedir(), logPath: getDaemonLogPath() };
+}
+/** The installed service when this caller can use it, else null. */
+export async function usableDaemonService() {
+    const service = getDaemonService();
+    if (!service?.isInstalled())
+        return null;
+    if (envTokenOverridesLogin(await loadConfig()))
+        return null;
+    return service;
+}
+function spawnDetached(port) {
+    const { program, args } = daemonCommandLine(port);
+    const log = openDaemonLogForChild();
+    try {
+        const child = spawn(program, args, {
+            detached: true,
+            stdio: ['ignore', log, log],
+            env: { ...buildDaemonEnv(), [DAEMON_CHILD_ENV]: '1' },
+            cwd: os.homedir(),
+            // A detached Windows child otherwise opens its own console window.
+            windowsHide: true,
+        });
+        child.unref();
+        return { service: null, abort: () => child.kill('SIGTERM') };
+    }
+    finally {
+        closeDaemonLogFd(log);
+    }
+}
+/**
+ * Starts a daemon. Caller must hold the daemon start lock and have stopped any
+ * stale daemon. Uses the installed service when there is one (refreshing its
+ * definition if this CLI's program, arguments or environment changed, e.g.
+ * after `dino update`), otherwise a detached child with a clean environment.
+ */
+export async function launchDaemon(port) {
+    const service = await usableDaemonService();
+    if (!service)
+        return spawnDetached(port);
+    ensureDaemonDir();
+    const spec = daemonServiceSpec(service, port);
+    if (!service.isCurrent(spec)) {
+        await service.install(spec);
+    }
+    else {
+        await service.start();
+    }
+    // The service manager owns the process; a launch that never becomes ready
+    // is reported with the log path rather than killed here.
+    return { service: service.kind, abort: () => undefined };
+}

package/dist/daemon/log.d.ts

@@ -0,0 +1,14 @@
+export declare function getDaemonLogPath(): string;
+/**
+ * Keeps one previous generation once the log grows past the limit. Copy then
+ * truncate (not rename): a service manager holds the log open in append mode,
+ * so the file must stay the same inode.
+ */
+export declare function rotateDaemonLog(limitBytes?: number): void;
+/** Opens the log for a daemon child's stdout/stderr; the caller closes it after spawning. */
+export declare function openDaemonLogForChild(): number | 'ignore';
+export declare function closeDaemonLogFd(fd: number | 'ignore'): void;
+/** One timestamped line on stderr, which a daemon child has pointed at its log. */
+export declare function writeDaemonLogLine(scope: string, message: string, details?: Record<string, unknown>): void;
+/** One timestamped line appended to the log file itself, for processes with no usable stderr. */
+export declare function appendDaemonLogLine(scope: string, message: string, details?: Record<string, unknown>): void;

package/dist/daemon/log.js

@@ -0,0 +1,57 @@
+import { appendFileSync, closeSync, copyFileSync, openSync, statSync, truncateSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDaemonDir, getDaemonDir } from './pid.js';
+const MAX_DAEMON_LOG_BYTES = 5 * 1024 * 1024;
+export function getDaemonLogPath() {
+    return join(getDaemonDir(), 'daemon.log');
+}
+/**
+ * Keeps one previous generation once the log grows past the limit. Copy then
+ * truncate (not rename): a service manager holds the log open in append mode,
+ * so the file must stay the same inode.
+ */
+export function rotateDaemonLog(limitBytes = MAX_DAEMON_LOG_BYTES) {
+    const logPath = getDaemonLogPath();
+    try {
+        if (statSync(logPath).size <= limitBytes)
+            return;
+        copyFileSync(logPath, `${logPath}.1`);
+        truncateSync(logPath, 0);
+    }
+    catch {
+        // Missing log or unwritable directory: logging is best effort.
+    }
+}
+/** Opens the log for a daemon child's stdout/stderr; the caller closes it after spawning. */
+export function openDaemonLogForChild() {
+    try {
+        ensureDaemonDir();
+        rotateDaemonLog();
+        return openSync(getDaemonLogPath(), 'a', 0o600);
+    }
+    catch {
+        return 'ignore';
+    }
+}
+export function closeDaemonLogFd(fd) {
+    if (fd !== 'ignore')
+        closeSync(fd);
+}
+function formatLogLine(scope, message, details) {
+    const suffix = details ? ` ${JSON.stringify(details)}` : '';
+    return `${new Date().toISOString()} [${scope}] ${message}${suffix}\n`;
+}
+/** One timestamped line on stderr, which a daemon child has pointed at its log. */
+export function writeDaemonLogLine(scope, message, details) {
+    process.stderr.write(formatLogLine(scope, message, details));
+}
+/** One timestamped line appended to the log file itself, for processes with no usable stderr. */
+export function appendDaemonLogLine(scope, message, details) {
+    try {
+        ensureDaemonDir();
+        appendFileSync(getDaemonLogPath(), formatLogLine(scope, message, details), { mode: 0o600 });
+    }
+    catch {
+        // Logging is best effort.
+    }
+}