aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/daemon/runStore.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runStore.ts — v4.5 Phase 1: runs + run_events writers.
+ *
+ * Daemon-fired runs are persisted in `runs` (one row per turn) with
+ * a stream of `run_events` rows for per-event detail (tool calls,
+ * verifications, classifications, recovery actions, log lines).
+ *
+ * CLI-fired turns continue using in-memory trace structures — zero
+ * overhead for interactive use. The daemon path opts in by creating
+ * a run row + emitting events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRunStore = createRunStore;
+function rowToTs(r) {
+    return {
+        id: r.id,
+        triggerEventId: r.trigger_event_id,
+        sessionId: r.session_id,
+        instanceId: r.instance_id,
+        status: r.status,
+        finishReason: r.finish_reason,
+        startedAt: r.started_at,
+        completedAt: r.completed_at,
+        resumePending: r.resume_pending === 1,
+        resumeReason: r.resume_reason,
+    };
+}
+function createRunStore(opts) {
+    const db = opts.db;
+    return {
+        create({ sessionId, instanceId, triggerEventId, status, startedAt, spawnedFromRunId, spawnedFromSessionId }) {
+            const now = startedAt ?? Date.now();
+            // v4.6 Phase 1 — explicit 8-column INSERT including the two
+            // sub-agent lineage columns. Top-level runs pass NULL for both;
+            // sub-agent runs pass the parent run_id + session_id. Single
+            // insert path keeps the code simple at the cost of two extra
+            // bound NULLs on the common (top-level) case.
+            const r = db.prepare(`INSERT INTO runs
+           (trigger_event_id, session_id, instance_id, status, started_at,
+            resume_pending, spawned_from_run_id, spawned_from_session_id)
+         VALUES (?, ?, ?, ?, ?, 0, ?, ?)`).run(triggerEventId ?? null, sessionId, instanceId, status ?? 'queued', now, spawnedFromRunId ?? null, spawnedFromSessionId ?? null);
+            return Number(r.lastInsertRowid);
+        },
+        setStatus(runId, status, opts2 = {}) {
+            const completedAt = opts2.completedAt
+                ?? (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'interrupted'
+                    ? Date.now()
+                    : null);
+            db.prepare(`UPDATE runs
+            SET status        = ?,
+                finish_reason = COALESCE(?, finish_reason),
+                completed_at  = COALESCE(?, completed_at)
+          WHERE id = ?`).run(status, opts2.finishReason ?? null, completedAt, runId);
+        },
+        markResumePending(runId, reason) {
+            db.prepare(`UPDATE runs SET resume_pending = 1, resume_reason = ? WHERE id = ?`).run(reason, runId);
+        },
+        emitEvent(runId, kind, payload) {
+            const json = JSON.stringify(payload).slice(0, 4096);
+            db.prepare(`INSERT INTO run_events (run_id, ts, kind, payload) VALUES (?, ?, ?, ?)`).run(runId, Date.now(), kind, json);
+        },
+        listActive() {
+            const rows = db
+                .prepare(`SELECT * FROM runs WHERE status IN ('queued','running')`)
+                .all();
+            return rows.map(rowToTs);
+        },
+        get(runId) {
+            const r = db
+                .prepare('SELECT * FROM runs WHERE id = ?')
+                .get(runId);
+            return r ? rowToTs(r) : null;
+        },
+        countEvents(runId) {
+            const r = db
+                .prepare('SELECT COUNT(*) AS c FROM run_events WHERE run_id = ?')
+                .get(runId);
+            return r.c;
+        },
+        listRecent(opts2 = {}) {
+            const limit = Math.max(1, Math.min(opts2.limit ?? 50, 1000));
+            const whereParts = [];
+            const params = [];
+            if (opts2.status) {
+                whereParts.push('r.status = ?');
+                params.push(opts2.status);
+            }
+            if (opts2.source) {
+                whereParts.push('te.source = ?');
+                params.push(opts2.source);
+            }
+            if (opts2.sessionIdPrefix) {
+                whereParts.push('r.session_id LIKE ?');
+                params.push(`${opts2.sessionIdPrefix}%`);
+            }
+            // v4.6 Phase 2Q-B — default to top-level rows only. Children
+            // (rows with non-NULL `spawned_from_run_id`) clutter the list
+            // when you really want "what user-triggered runs happened
+            // recently". The partial index `idx_runs_spawned_from` makes
+            // the negated predicate cheap (children indexed; parents NOT
+            // indexed but the predicate is `IS NULL` — table scan, but
+            // the planner uses the limit + ORDER BY started_at to cap
+            // work). `--include-children` flips the flag for flat view.
+            if (opts2.topLevelOnly !== false) {
+                whereParts.push('r.spawned_from_run_id IS NULL');
+            }
+            const where = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
+            const sql = `
+        SELECT r.* FROM runs r
+        LEFT JOIN trigger_events te ON r.trigger_event_id = te.id
+        ${where}
+        ORDER BY r.started_at DESC
+        LIMIT ?`;
+            params.push(limit);
+            const rows = db.prepare(sql).all(...params);
+            return rows.map(rowToTs);
+        },
+        countChildren(parentRunId) {
+            // Single round-trip via conditional COUNT — sqlite handles
+            // this fine even with a few thousand children per parent,
+            // which we'll never see in practice (fanout caps at 5).
+            const r = db.prepare(`SELECT
+           COUNT(*) AS total,
+           SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS completed
+         FROM runs
+        WHERE spawned_from_run_id = ?`).get(parentRunId);
+            return {
+                total: r.total,
+                completed: r.completed ?? 0,
+            };
+        },
+        listEvents(runId, limit = 200) {
+            const rows = db.prepare(`SELECT ts, kind, payload FROM run_events WHERE run_id = ? ORDER BY ts ASC LIMIT ?`).all(runId, Math.max(1, Math.min(limit, 5000)));
+            return rows;
+        },
+    };
+}

package/dist/core/v4/daemon/runtimeLock.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runtimeLock.ts — v4.5 Phase 1: race-safe daemon
+ * runtime lock.
+ *
+ * Replaces the plain `fs.writeFileSync(PID_FILE, pid)` in
+ * `core/backgroundService.ts:21` which has a TOCTOU race window
+ * (two daemons racing to write the PID file both succeed, then
+ * step on each other's adapters).
+ *
+ * Mechanism: `fs.openSync(lockPath, 'wx')` — the `wx` flag opens
+ * with O_CREAT | O_EXCL, throwing EEXIST atomically if the file
+ * already exists. We write the instance metadata into the locked
+ * file and rely on `atexit`-style cleanup + signal handlers to
+ * release.
+ *
+ * Stale-lock recovery: when EEXIST fires, we read the existing
+ * file, parse out the PID, and probe it with `process.kill(pid, 0)`.
+ * If the owner is dead, we unlink the stale file and retry once.
+ * If alive, we throw `DaemonAlreadyRunningError` carrying the PID
+ * so the caller can surface a clear error.
+ *
+ * Cross-platform: Node's `wx` flag works identically on Windows
+ * (where the underlying call is CreateFile with FILE_FLAG_OPEN_NO_RECALL
+ * + CREATE_NEW). No fcntl/msvcrt fallbacks needed.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DaemonAlreadyRunningError = void 0;
+exports.acquireRuntimeLock = acquireRuntimeLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+class DaemonAlreadyRunningError extends Error {
+    constructor(pid, lockPath) {
+        super(`Daemon already running (pid ${pid}). Lock file: ${lockPath}. ` +
+            `Use \`aiden daemon stop\` to stop the running instance, or set ` +
+            `AIDEN_DAEMON=0 to skip daemon mode.`);
+        this.name = 'DaemonAlreadyRunningError';
+        this.pid = pid;
+        this.lockPath = lockPath;
+    }
+}
+exports.DaemonAlreadyRunningError = DaemonAlreadyRunningError;
+function readLockFile(lockPath) {
+    try {
+        const raw = node_fs_1.default.readFileSync(lockPath, 'utf-8').trim();
+        if (!raw)
+            return null;
+        // Format: 3 lines (instance_id, pid, started_at_ms).
+        const lines = raw.split(/\r?\n/);
+        if (lines.length < 2)
+            return null;
+        const pid = Number.parseInt(lines[1], 10);
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        return {
+            instanceId: lines[0],
+            pid,
+            startedAt: Number.parseInt(lines[2] ?? '0', 10) || 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process → dead. EPERM = exists but not ours → treat as alive.
+        const code = err.code;
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+function writeLockFile(fd, contents) {
+    const body = `${contents.instanceId}\n${contents.pid}\n${contents.startedAt}\n`;
+    node_fs_1.default.writeSync(fd, body, 0, 'utf-8');
+    node_fs_1.default.fsyncSync(fd);
+    node_fs_1.default.closeSync(fd);
+}
+/**
+ * Atomically acquire the daemon's runtime lock at `lockPath`.
+ * Throws `DaemonAlreadyRunningError` when another live daemon
+ * already holds it. Recovers automatically from stale locks left
+ * by crashed daemons.
+ */
+function acquireRuntimeLock(opts) {
+    const lockPath = opts.lockPath;
+    const pid = opts.pid ?? process.pid;
+    const startedAt = opts.startedAt ?? Date.now();
+    const contents = {
+        instanceId: opts.instanceId,
+        pid,
+        startedAt,
+    };
+    // Ensure parent dir exists.
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(lockPath), { recursive: true });
+    }
+    catch { /* will surface on open */ }
+    const attempt = () => {
+        try {
+            const fd = node_fs_1.default.openSync(lockPath, 'wx');
+            return { ok: true, fd };
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === 'EEXIST')
+                return { ok: false, reason: 'eexist', err };
+            return { ok: false, reason: 'other', err };
+        }
+    };
+    let r = attempt();
+    if (r.ok === false && r.reason === 'eexist') {
+        // Stale-lock recovery — read existing contents, probe the PID.
+        const existing = readLockFile(lockPath);
+        if (existing && isPidAlive(existing.pid)) {
+            throw new DaemonAlreadyRunningError(existing.pid, lockPath);
+        }
+        opts.log?.('warn', `Daemon: removing stale runtime lock (pid ${existing?.pid ?? '?'} dead)`);
+        try {
+            node_fs_1.default.unlinkSync(lockPath);
+        }
+        catch { /* race-safe: ignore */ }
+        r = attempt();
+    }
+    if (r.ok === false) {
+        throw new Error(`Failed to acquire daemon runtime lock at ${lockPath}: ${r.err.message}`);
+    }
+    writeLockFile(r.fd, contents);
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            node_fs_1.default.unlinkSync(lockPath);
+        }
+        catch { /* best-effort */ }
+    };
+    // Defense-in-depth: also clean up on process exit even if the
+    // caller forgets. Drain handler calls release() explicitly.
+    const onExit = () => { release(); };
+    process.once('exit', onExit);
+    return {
+        release: () => {
+            release();
+            try {
+                process.removeListener('exit', onExit);
+            }
+            catch { /* noop */ }
+        },
+        lockPath,
+    };
+}

package/dist/core/v4/daemon/signals.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/signals.ts — v4.5 Phase 1: signal handler installation.
+ *
+ * Installs SIGUSR1 → graceful restart (exit code 75) and
+ * SIGTERM/SIGINT → graceful shutdown (exit code 0). All three
+ * routes go through the same `performDrain` so cleanup ordering
+ * stays uniform.
+ *
+ * SIGUSR1 is unavailable on Windows; the install is a no-op
+ * there. The CLI's `aiden daemon restart` falls back to stop+start
+ * sequentially on Windows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installDaemonSignalHandlers = installDaemonSignalHandlers;
+exports._resetDaemonSignalHandlersForTests = _resetDaemonSignalHandlersForTests;
+const drain_1 = require("./drain");
+const restartCode_1 = require("./restartCode");
+let _installed = false;
+function installDaemonSignalHandlers(opts) {
+    if (_installed)
+        return;
+    _installed = true;
+    const supportsSIGUSR1 = opts.installRestartSignal ?? (process.platform !== 'win32');
+    process.once('SIGTERM', () => {
+        void (0, drain_1.performDrain)({ ...opts.getDrainContext(), reason: 'sigterm', exitCode: 0 });
+    });
+    process.once('SIGINT', () => {
+        void (0, drain_1.performDrain)({ ...opts.getDrainContext(), reason: 'sigint', exitCode: 0 });
+    });
+    if (supportsSIGUSR1) {
+        process.once('SIGUSR1', () => {
+            void (0, drain_1.performDrain)({
+                ...opts.getDrainContext(),
+                reason: 'sigusr1_restart',
+                exitCode: restartCode_1.DAEMON_RESTART_EXIT_CODE,
+            });
+        });
+    }
+}
+/** Test helper: rearm the installer guard. */
+function _resetDaemonSignalHandlersForTests() {
+    _installed = false;
+}

package/dist/core/v4/daemon/supervisor.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/supervisor.ts — v4.5 Phase 1: internal supervisor +
+ * OS service template generators.
+ *
+ * Two-tier supervision strategy:
+ *
+ *   1. **OS service is the primary supervisor** wherever available.
+ *      systemd (Linux), launchd (macOS), and third-party tools on
+ *      Windows do this better than any in-process supervisor — they
+ *      survive logout, integrate with reboots, and surface in OS
+ *      tooling. `aiden daemon install` writes the appropriate unit
+ *      via the template generators in this module.
+ *
+ *   2. **Internal supervisor is the fallback** for environments
+ *      that lack an OS service manager OR where the user prefers to
+ *      keep things simple. Parent process spawns the daemon child,
+ *      watches for exits, and respawns with exponential backoff.
+ *      Graceful-restart exit code (75) triggers immediate respawn
+ *      without backoff.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSupervisor = startSupervisor;
+exports.generateSystemdUnit = generateSystemdUnit;
+exports.generateLaunchdPlist = generateLaunchdPlist;
+exports.windowsServiceGuidance = windowsServiceGuidance;
+const node_child_process_1 = require("node:child_process");
+const restartCode_1 = require("./restartCode");
+function startSupervisor(opts) {
+    const initialMs = opts.backoff?.initialMs ?? 1000;
+    const maxMs = opts.backoff?.maxMs ?? 60000;
+    const multiplier = opts.backoff?.multiplier ?? 2;
+    const maxFailures = opts.backoff?.maxConsecutiveFailures ?? 5;
+    const graceful = new Set(opts.gracefulExitCodes ?? [restartCode_1.DAEMON_RESTART_EXIT_CODE]);
+    const drainGrace = opts.drainTimeoutMs ?? 30000;
+    let child = null;
+    let consecutiveFailures = 0;
+    let respawnTimer = null;
+    let stopping = false;
+    let stopResolve = null;
+    const stopPromise = new Promise((res) => { stopResolve = res; });
+    const respawn = (delayMs) => {
+        if (stopping)
+            return;
+        if (respawnTimer)
+            return;
+        opts.onRespawn?.(consecutiveFailures, delayMs);
+        respawnTimer = setTimeout(() => {
+            respawnTimer = null;
+            launch();
+        }, delayMs);
+        if (typeof respawnTimer.unref === 'function')
+            respawnTimer.unref();
+    };
+    const launch = () => {
+        if (stopping)
+            return;
+        const cmd = opts.childCmd[0];
+        const args = opts.childCmd.slice(1);
+        child = (0, node_child_process_1.spawn)(cmd, args, {
+            cwd: opts.cwd,
+            env: { ...process.env, ...(opts.env ?? {}) },
+            stdio: 'inherit',
+        });
+        child.on('exit', (code, signal) => {
+            opts.onChildExit?.(code, signal);
+            const wasGraceful = code != null && graceful.has(code);
+            if (stopping) {
+                // We requested the stop; resolve the promise.
+                stopResolve?.();
+                return;
+            }
+            if (wasGraceful) {
+                // Graceful restart — respawn immediately, no backoff.
+                consecutiveFailures = 0;
+                respawn(0);
+                return;
+            }
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= maxFailures) {
+                opts.onGiveUp?.(`Child exited ${consecutiveFailures} consecutive times (last: ` +
+                    `code=${code} signal=${signal}). Giving up.`);
+                stopping = true;
+                stopResolve?.();
+                return;
+            }
+            const delay = Math.min(maxMs, initialMs * Math.pow(multiplier, consecutiveFailures - 1));
+            respawn(delay);
+        });
+        child.on('error', () => {
+            // 'error' fires before 'exit' in spawn-failure cases. Let
+            // 'exit' handle the backoff; just keep the supervisor alive.
+        });
+    };
+    launch();
+    return {
+        async stop() {
+            if (stopping)
+                return stopPromise;
+            stopping = true;
+            if (respawnTimer) {
+                clearTimeout(respawnTimer);
+                respawnTimer = null;
+            }
+            if (!child) {
+                stopResolve?.();
+                return stopPromise;
+            }
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* noop */ }
+            // Hard cap so a stuck child doesn't hang the supervisor.
+            const killer = setTimeout(() => {
+                try {
+                    child?.kill('SIGKILL');
+                }
+                catch { /* noop */ }
+            }, drainGrace + 5000);
+            if (typeof killer.unref === 'function')
+                killer.unref();
+            return stopPromise;
+        },
+        childPid() {
+            return child?.pid ?? null;
+        },
+    };
+}
+/**
+ * Render a systemd user-unit suitable for
+ * `~/.config/systemd/user/aiden.service`.
+ *
+ * Key invariants:
+ *   - `RestartForceExitStatus=75` triggers an immediate respawn on
+ *     the daemon's graceful-restart exit code.
+ *   - `TimeoutStopSec = max(60, ceil(drainTimeoutMs/1000)) + 30` so
+ *     post-interrupt cleanup has headroom beyond the drain. Without
+ *     this, the cgroup SIGKILLs in-flight tool subprocesses and
+ *     attribution is lost.
+ *   - `ExecReload=/bin/kill -USR1 $MAINPID` lets `aiden daemon
+ *     restart` (or `systemctl --user reload aiden`) trigger a
+ *     drain-aware graceful restart.
+ */
+function generateSystemdUnit(ctx) {
+    const drainSec = Math.max(60, Math.ceil(ctx.drainTimeoutMs / 1000));
+    const stopSec = drainSec + 30;
+    const envLines = Object.entries({
+        AIDEN_DAEMON: '1',
+        AIDEN_PORT: String(ctx.port),
+        AIDEN_DAEMON_AUTO_RESTART: '0', // OS-service primary; disable internal supervisor
+        ...(ctx.env ?? {}),
+    }).map(([k, v]) => `Environment="${k}=${v}"`).join('\n');
+    return `[Unit]
+Description=Aiden local-first AI agent (daemon mode)
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${ctx.nodeBin} ${ctx.bundlePath}
+WorkingDirectory=${ctx.workingDir}
+${envLines}
+Restart=always
+RestartSec=60
+RestartMaxDelaySec=300
+RestartSteps=5
+RestartForceExitStatus=${restartCode_1.DAEMON_RESTART_EXIT_CODE}
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=${stopSec}
+ExecReload=/bin/kill -USR1 $MAINPID
+
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * Render a launchd plist for
+ * `~/Library/LaunchAgents/com.aiden.daemon.plist`.
+ *
+ * `KeepAlive.SuccessfulExit=false` is the launchd analog of
+ * systemd's `RestartForceExitStatus=75`: respawn on ANY non-zero
+ * exit; do not respawn on exit 0. The graceful-restart path
+ * always exits with 75, which is non-zero, so the daemon respawns
+ * automatically.
+ *
+ * `userPath` should be the captured login-shell PATH so Homebrew /
+ * nvm / cargo / etc. are reachable.
+ */
+function generateLaunchdPlist(ctx) {
+    const envEntries = Object.entries({
+        AIDEN_DAEMON: '1',
+        AIDEN_PORT: String(ctx.port),
+        AIDEN_DAEMON_AUTO_RESTART: '0',
+        ...(ctx.userPath ? { PATH: ctx.userPath } : {}),
+        ...(ctx.env ?? {}),
+    });
+    const envXml = envEntries
+        .map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(v)}</string>`)
+        .join('\n');
+    const stdoutXml = ctx.stdoutPath
+        ? `  <key>StandardOutPath</key>\n  <string>${escapeXml(ctx.stdoutPath)}</string>\n`
+        : '';
+    const stderrXml = ctx.stderrPath
+        ? `  <key>StandardErrorPath</key>\n  <string>${escapeXml(ctx.stderrPath)}</string>\n`
+        : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.aiden.daemon</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(ctx.nodeBin)}</string>
+    <string>${escapeXml(ctx.bundlePath)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(ctx.workingDir)}</string>
+${stdoutXml}${stderrXml}</dict>
+</plist>
+`;
+}
+function escapeXml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+// ── Windows guidance (docs-only) ───────────────────────────────────────────
+/**
+ * Phase 1 deliberately does NOT auto-generate Scheduled Task /
+ * Windows Service entries. NSSM/SCM variance + admin requirements
+ * make an automatic installer too risky for the v4.5 ship. The CLI
+ * `aiden daemon install` on Windows prints this guidance and exits
+ * with code 0 without writing anything.
+ */
+function windowsServiceGuidance() {
+    return [
+        'Aiden v4.5 does not auto-install a Windows service in Phase 1.',
+        '',
+        'Recommended approaches:',
+        '  - Foreground:     aiden daemon start',
+        '                    (the internal supervisor keeps the daemon running',
+        '                    until you close the terminal)',
+        '  - Background:     Use a third-party supervisor like `pm2` or `nssm`.',
+        '                    Example with pm2:',
+        '                      npm install -g pm2',
+        '                      pm2 start aiden -- daemon start',
+        '                      pm2 save && pm2 startup',
+        '',
+        'See docs/v4.5/daemon-windows.md for details.',
+    ].join('\n');
+}