@pellux/goodvibes-sdk 0.38.0 → 1.1.0

package/dist/platform/push/vapid.js

@@ -0,0 +1,113 @@
+/**
+ * push/vapid.ts
+ *
+ * VAPID (RFC 8292) key custody and request signing for browser push.
+ *
+ * KEY CUSTODY — the load-bearing rule of this file:
+ *  - The daemon generates one P-256 keypair on first need.
+ *  - The WHOLE keypair (including the private component) is persisted only
+ *    through the SecretsManager, exactly like any other credential — into the
+ *    secure store, or the plaintext secrets file, per the active secret policy.
+ *    It is NEVER written into the config, so it can never ride out in the
+ *    secret-free config snapshot.
+ *  - The private key is used only here, to sign the short-lived VAPID JWT that
+ *    authorizes one delivery. It is never logged and never returned by any read
+ *    verb.
+ *  - Only the PUBLIC key leaves the daemon: `getPublicKey()` feeds the
+ *    `push.vapid.get` verb and the `k=` parameter of the Authorization header.
+ */
+import { createPrivateKey, generateKeyPairSync, sign as cryptoSign } from 'node:crypto';
+/** The secret key under which the keypair is stored (a secrets-store key, not a config key). */
+export const VAPID_SECRET_KEY = 'push.vapid.keypair';
+const DEFAULT_SUBJECT = 'mailto:goodvibes-push@localhost';
+/** VAPID JWTs are short-lived; RFC 8292 caps `exp` at 24h. Use 12h. */
+const JWT_LIFETIME_SECONDS = 12 * 60 * 60;
+function base64UrlFromBuffer(buffer) {
+    return buffer.toString('base64url');
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+/** Derive the 65-byte uncompressed public point (base64url) from a P-256 JWK. */
+function publicKeyFromJwk(jwk) {
+    if (!jwk.x || !jwk.y)
+        throw new Error('VAPID JWK is missing its public coordinates');
+    const point = Buffer.concat([
+        Buffer.from([0x04]),
+        Buffer.from(jwk.x, 'base64url'),
+        Buffer.from(jwk.y, 'base64url'),
+    ]);
+    return base64UrlFromBuffer(point);
+}
+export class VapidManager {
+    store;
+    subject;
+    inflight = null;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.subject = options.subject && options.subject.length > 0 ? options.subject : DEFAULT_SUBJECT;
+    }
+    /** The public application-server key clients subscribe with. Generates on first call. */
+    async getPublicKey() {
+        const keypair = await this.ensureKeypair();
+        return keypair.publicKey;
+    }
+    /**
+     * Build the `Authorization: vapid ...` header value for one delivery to
+     * `endpoint`. The JWT's audience is the endpoint's origin (RFC 8292).
+     */
+    async buildAuthorizationHeader(endpoint) {
+        const keypair = await this.ensureKeypair();
+        const audience = new URL(endpoint).origin;
+        const jwt = this.signJwt(audience, keypair.privateJwk);
+        return `vapid t=${jwt}, k=${keypair.publicKey}`;
+    }
+    signJwt(audience, privateJwk) {
+        const header = base64UrlJson({ typ: 'JWT', alg: 'ES256' });
+        const payload = base64UrlJson({
+            aud: audience,
+            exp: Math.floor(Date.now() / 1000) + JWT_LIFETIME_SECONDS,
+            sub: this.subject,
+        });
+        const signingInput = `${header}.${payload}`;
+        const key = createPrivateKey({ key: privateJwk, format: 'jwk' });
+        // ieee-p1363 gives the raw r||s (64-byte) JOSE signature ES256 requires,
+        // not Node's default DER encoding.
+        const signature = cryptoSign('sha256', Buffer.from(signingInput, 'utf8'), {
+            key,
+            dsaEncoding: 'ieee-p1363',
+        });
+        return `${signingInput}.${base64UrlFromBuffer(signature)}`;
+    }
+    /**
+     * Load the keypair from the secrets store, or generate and persist one on
+     * first use. Concurrent callers share a single in-flight generation so two
+     * simultaneous first-time deliveries cannot mint two keypairs.
+     */
+    ensureKeypair() {
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.loadOrGenerate().catch((error) => {
+            // A failed attempt must not poison every later call.
+            this.inflight = null;
+            throw error;
+        });
+        return this.inflight;
+    }
+    async loadOrGenerate() {
+        const existing = await this.store.get(VAPID_SECRET_KEY);
+        if (existing) {
+            const parsed = JSON.parse(existing);
+            if (parsed.publicKey && parsed.privateJwk)
+                return parsed;
+        }
+        const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+        const privateJwk = privateKey.export({ format: 'jwk' });
+        const keypair = {
+            publicKey: publicKeyFromJwk(publicKey.export({ format: 'jwk' })),
+            privateJwk,
+        };
+        await this.store.set(VAPID_SECRET_KEY, JSON.stringify(keypair));
+        return keypair;
+    }
+}

package/dist/platform/runtime/bootstrap-services.d.ts

@@ -16,8 +16,49 @@ interface HttpListenerService {
     start(): Promise<void>;
     stop(): Promise<void>;
 }
+/**
+ * Options passed to the injectable detached-daemon spawn seam. Mirrors the subset
+ * of `child_process.SpawnOptions` the detached spawn relies on. `detached: true`
+ * and the caller's subsequent `unref()` are what let the daemon outlive this
+ * surface — tests assert both are present.
+ */
+export interface DetachedDaemonSpawnOptions {
+    readonly detached: boolean;
+    readonly stdio: 'ignore' | ReadonlyArray<'ignore' | number>;
+    readonly cwd?: string | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+}
+/** Minimal child-process shape the detached spawn seam must return. */
+export interface DetachedDaemonChild {
+    readonly pid?: number | undefined;
+    unref(): void;
+    once?(event: 'error' | 'exit', listener: (arg: unknown) => void): void;
+}
+/** One-time hint surfaced ONCE by the TUI after a successful detached spawn. */
+export declare const DETACHED_DAEMON_INSTALL_HINT = "daemon started for this session \u2014 install it as a service so it survives reboots: POST /api/service/install on the daemon HTTP API (admin token required)";
 interface ServiceFactories {
     createDaemonServer?: (runtimeBus: RuntimeEventBus, userAuth: RuntimeServices['localUserAuthManager'], runtimeServices: RuntimeServices) => DaemonService;
+    /**
+     * Injectable spawn seam for the detached standalone daemon (Layer 2 default).
+     * Defaults to `child_process.spawn`. Tests stub this to assert that detached
+     * spawn — not in-process embedding — is chosen by default, and that the options
+     * carry `detached: true` (the caller then `unref()`s the returned child).
+     */
+    spawnDetachedDaemon?: (command: string, args: readonly string[], options: DetachedDaemonSpawnOptions) => DetachedDaemonChild;
+    /** Command used to launch the detached daemon. Default: `GOODVIBES_DAEMON_BINARY` env or `goodvibes-daemon`. */
+    daemonLaunchCommand?: string | undefined;
+    /** Extra CLI args appended after the resolved `--daemon-home/--hostname/--port` flags. */
+    daemonLaunchArgs?: readonly string[] | undefined;
+    /** Daemon home directory passed via `--daemon-home`. Default: `os.homedir()`. */
+    daemonHomeDir?: string | undefined;
+    /** Directory where the detached daemon records pid/port + log. Default `<daemonHomeDir>/.goodvibes/daemon`. */
+    daemonRuntimeDir?: string | undefined;
+    /** Bounded time to wait for the detached daemon to bind + pass the identity probe. */
+    detachedSpawnProbeTimeoutMs?: number | undefined;
+    /** Poll interval while waiting for the detached daemon to become reachable. */
+    detachedSpawnProbeIntervalMs?: number | undefined;
+    /** Sleep function (injectable so tests drive the probe loop deterministically). */
+    sleep?: ((ms: number) => Promise<void>) | undefined;
     createHttpListener?: (hookDispatcher: HookDispatcher, userAuth: RuntimeServices['localUserAuthManager'], configManager: RuntimeServices['configManager']) => HttpListenerService;
     startupTimeoutMs?: number | undefined;
     probeDaemonPortInUse?: ((host: string, port: number) => Promise<boolean>) | undefined;
@@ -37,8 +78,20 @@ interface ServiceFactories {
      * different tokens, or both may share the same bearer.
      */
     sharedHttpListenerToken?: string | undefined;
+    /**
+     * This surface's own SDK version, used to band-check a daemon found on the
+     * configured port before adopting it. Defaults to the SDK `VERSION`. Injected
+     * mainly so tests can drive the compatibility gate deterministically.
+     */
+    localDaemonVersion?: string | undefined;
+    /**
+     * Override for the version-compatibility predicate. Defaults to the shared
+     * `isDaemonVersionCompatible` band policy. Tests inject a stub to exercise the
+     * incompatible-adoption refusal without constructing skewed daemons.
+     */
+    isDaemonVersionCompatible?: ((localVersion: string, remoteVersion: string | undefined) => boolean) | undefined;
 }
-export type HostServiceMode = 'disabled' | 'embedded' | 'external' | 'blocked' | 'unavailable';
+export type HostServiceMode = 'disabled' | 'embedded' | 'external' | 'blocked' | 'incompatible' | 'unavailable';
 export interface HostServiceStatus {
     readonly mode: HostServiceMode;
     readonly host: string;
@@ -60,11 +113,18 @@ export interface HostServicesHandle {
     readonly httpListener: HttpListenerService | null;
     readonly daemonStatus: HostServiceStatus;
     readonly httpListenerStatus: HostServiceStatus;
+    /**
+     * One-time, honest hint the surface can display ONCE after this host instance
+     * spawned a detached daemon for the session. Present only when a detached
+     * daemon was just started (Layer 2); undefined when a daemon was adopted,
+     * embedded, disabled, or unavailable. See {@link DETACHED_DAEMON_INSTALL_HINT}.
+     */
+    readonly daemonStartHint?: string | undefined;
     listRecentControlPlaneEvents(limit: number): readonly import('../control-plane/gateway.js').ControlPlaneRecentEvent[];
     stop(): Promise<void>;
 }
 export interface HostServicesConfig {
-    get(key: 'danger.daemon' | 'danger.httpListener' | 'controlPlane.host' | 'controlPlane.port' | 'httpListener.host' | 'httpListener.port'): boolean | string | number;
+    get(key: 'daemon.enabled' | 'daemon.embedInProcess' | 'danger.httpListener' | 'controlPlane.host' | 'controlPlane.port' | 'httpListener.host' | 'httpListener.port'): boolean | string | number | undefined;
 }
 export declare function startHostServices(config: HostServicesConfig, runtimeBus: RuntimeEventBus, hookDispatcher: HookDispatcher, runtimeServices: RuntimeServices, factories?: ServiceFactories): Promise<HostServicesHandle>;
 export {};

package/dist/platform/runtime/bootstrap-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap-services.d.ts","sourceRoot":"","sources":["../../../src/platform/runtime/bootstrap-services.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap-services.d.ts","sourceRoot":"","sources":["../../../src/platform/runtime/bootstrap-services.ts"],"names":[],"mappings":"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"}

package/dist/platform/runtime/bootstrap-services.js

@@ -1,8 +1,18 @@
 import { ConfigurationError } from '@pellux/goodvibes-errors';
 import { logger } from '../utils/logger.js';
 import net from 'node:net';
+import os from 'node:os';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
 import { summarizeError } from '../utils/error-display.js';
 import { createTimeoutController } from '../utils/fetch-with-timeout.js';
+import { VERSION } from '../version.js';
+import { isDaemonVersionCompatible, describeVersionIncompatibility } from './daemon-version-compat.js';
+import { resolveDaemonEnabled } from '../config/index.js';
+import { recordDetachedDaemonRuntime } from './detached-daemon-runtime.js';
+/** One-time hint surfaced ONCE by the TUI after a successful detached spawn. */
+export const DETACHED_DAEMON_INSTALL_HINT = 'daemon started for this session — install it as a service so it survives reboots: POST /api/service/install on the daemon HTTP API (admin token required)';
 const DEFAULT_SERVICE_START_TIMEOUT_MS = 1500;
 const TCP_PORT_PROBE_TIMEOUT_MS = 250;
 const DAEMON_IDENTITY_PROBE_TIMEOUT_MS = 750;
@@ -13,6 +23,14 @@ function readBooleanSetting(config, key) {
     }
     return value;
 }
+/**
+ * Whether the daemon should be hosted IN THIS PROCESS (Layer 3 opt-in). Default
+ * false: the surface spawns a detached daemon instead. Reads leniently so an
+ * unset value (undefined) means false rather than throwing.
+ */
+function readDaemonEmbedInProcess(config) {
+    return config.get('daemon.embedInProcess') === true;
+}
 function readHostSetting(config, key, fallback) {
     const value = config.get(key);
     if (value === undefined || value === null)
@@ -201,27 +219,152 @@ export async function startHostServices(config, runtimeBus, hookDispatcher, runt
     const probeDaemonPortInUse = factories.probeDaemonPortInUse ?? ((host, port) => isTcpPortInUse(host, port));
     const probeDaemonIdentity = factories.probeDaemonIdentity ?? probeGoodVibesDaemonIdentity;
     const probeHttpListenerPortInUse = factories.probeHttpListenerPortInUse ?? ((host, port) => isTcpPortInUse(host, port));
+    const localDaemonVersion = factories.localDaemonVersion ?? VERSION;
+    const versionCompatible = factories.isDaemonVersionCompatible ?? isDaemonVersionCompatible;
+    // A daemon whose identity probe says `goodvibes` has only proven it IS a
+    // GoodVibes daemon — not that it speaks a wire version this surface can adopt.
+    // Band-check the reported version and produce an honest `incompatible` status
+    // (never a second competing daemon) when it does not match this surface's band.
+    const resolveVerifiedDaemonStatus = (identity, reasonAdopted) => {
+        if (versionCompatible(localDaemonVersion, identity.version)) {
+            return createServiceStatus('external', daemonHost, daemonPort, {
+                authenticated: true,
+                status: identity.status,
+                version: identity.version,
+                reason: reasonAdopted,
+            });
+        }
+        const reason = describeVersionIncompatibility(daemonHost, daemonPort, localDaemonVersion, identity.version);
+        logger.warn('Daemon on configured port reports an incompatible version; refusing to adopt or start a competing daemon', {
+            host: daemonHost,
+            port: daemonPort,
+            foundVersion: identity.version,
+            localVersion: localDaemonVersion,
+        });
+        return createServiceStatus('incompatible', daemonHost, daemonPort, {
+            authenticated: true,
+            status: identity.status,
+            version: identity.version,
+            reason,
+        });
+    };
+    // Layer 2: spawn the daemon as a DETACHED standalone process (default), then
+    // poll (bounded) for it to bind and pass the identity probe. On success adopt
+    // it as 'external' with a one-time install-service hint. Returns an honest
+    // failure reason otherwise so the caller can fall back.
+    const attemptDetachedDaemonSpawn = async () => {
+        const spawnDetached = factories.spawnDetachedDaemon
+            ?? ((command, args, options) => spawn(command, [...args], {
+                detached: options.detached,
+                stdio: options.stdio,
+                ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                ...(options.env !== undefined ? { env: options.env } : {}),
+            }));
+        const command = (factories.daemonLaunchCommand ?? process.env.GOODVIBES_DAEMON_BINARY ?? 'goodvibes-daemon').trim()
+            || 'goodvibes-daemon';
+        const daemonHomeDir = factories.daemonHomeDir ?? os.homedir();
+        const runtimeDir = factories.daemonRuntimeDir ?? join(daemonHomeDir, '.goodvibes', 'daemon');
+        const logFilePath = join(runtimeDir, 'detached-daemon.log');
+        const args = [
+            '--daemon-home', daemonHomeDir,
+            '--hostname', daemonHost,
+            '--port', String(daemonPort),
+            ...(factories.daemonLaunchArgs ?? []),
+        ];
+        let stdio = 'ignore';
+        let closeStdio = null;
+        try {
+            mkdirSync(runtimeDir, { recursive: true });
+            const out = openSync(logFilePath, 'a');
+            const err = openSync(logFilePath, 'a');
+            stdio = ['ignore', out, err];
+            closeStdio = () => {
+                try {
+                    closeSync(out);
+                }
+                catch { /* already closed */ }
+                try {
+                    closeSync(err);
+                }
+                catch { /* already closed */ }
+            };
+        }
+        catch {
+            stdio = 'ignore';
+        }
+        let child;
+        try {
+            child = spawnDetached(command, args, {
+                detached: true,
+                stdio,
+                cwd: daemonHomeDir,
+                env: { ...process.env, GOODVIBES_DAEMON_HOME: daemonHomeDir },
+            });
+        }
+        catch (error) {
+            return { reason: `Detached daemon spawn failed to launch: ${summarizeError(error)}` };
+        }
+        finally {
+            // The child has inherited the fds; the parent's copies can be closed now.
+            closeStdio?.();
+        }
+        child.unref();
+        let processError = null;
+        child.once?.('error', (err) => { processError = summarizeError(err); });
+        recordDetachedDaemonRuntime(runtimeDir, {
+            pid: child.pid,
+            host: daemonHost,
+            port: daemonPort,
+            command,
+            startedAt: new Date().toISOString(),
+            logFilePath,
+        });
+        const timeoutMs = factories.detachedSpawnProbeTimeoutMs ?? 5000;
+        const intervalMs = factories.detachedSpawnProbeIntervalMs ?? 150;
+        const sleep = factories.sleep ?? ((ms) => new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+        }));
+        const deadline = Date.now() + timeoutMs;
+        let lastReason = 'Detached daemon did not become reachable before timeout';
+        // Probe at least once, then poll until the deadline.
+        for (;;) {
+            if (processError)
+                return { reason: `Detached daemon process error: ${processError}` };
+            const identity = await probeDaemonIdentity(daemonHost, daemonPort, factories.sharedDaemonToken);
+            if (identity.kind === 'goodvibes') {
+                const verified = resolveVerifiedDaemonStatus(identity, 'Spawned detached daemon for this session');
+                if (verified.mode === 'external') {
+                    return { status: verified, hint: DETACHED_DAEMON_INSTALL_HINT };
+                }
+                // Incompatible: do not keep a competing daemon around; report honestly.
+                return { reason: verified.reason ?? 'Spawned daemon reported an incompatible version' };
+            }
+            lastReason = identity.reason ?? lastReason;
+            if (Date.now() >= deadline)
+                return { reason: lastReason };
+            await sleep(intervalMs);
+        }
+    };
     let embeddedDaemonServer = null;
     let embeddedHttpListener = null;
-    let daemonStatus = createServiceStatus('disabled', daemonHost, daemonPort, { reason: 'danger.daemon is disabled' });
+    let daemonStartHint;
+    let daemonStatus = createServiceStatus('disabled', daemonHost, daemonPort, { reason: 'daemon.enabled is false' });
     let httpListenerStatus = createServiceStatus('disabled', httpListenerHost, httpListenerPort, {
         reason: 'danger.httpListener is disabled',
     });
-    if (readBooleanSetting(config, 'danger.daemon')) {
+    if (resolveDaemonEnabled(config)) {
         if (await probeDaemonPortInUse(daemonHost, daemonPort)) {
             const identity = await probeDaemonIdentity(daemonHost, daemonPort, factories.sharedDaemonToken);
             if (identity.kind === 'goodvibes') {
-                daemonStatus = createServiceStatus('external', daemonHost, daemonPort, {
-                    authenticated: true,
-                    status: identity.status,
-                    version: identity.version,
-                    reason: 'Existing GoodVibes daemon verified on configured host/port',
-                });
-                logger.info('Existing GoodVibes daemon detected; continuing without embedded daemon in this host instance', {
-                    host: daemonHost,
-                    port: daemonPort,
-                    version: identity.version,
-                });
+                daemonStatus = resolveVerifiedDaemonStatus(identity, 'Existing GoodVibes daemon verified on configured host/port');
+                if (daemonStatus.mode === 'external') {
+                    logger.info('Existing GoodVibes daemon detected; continuing without embedded daemon in this host instance', {
+                        host: daemonHost,
+                        port: daemonPort,
+                        version: identity.version,
+                    });
+                }
             }
             else {
                 daemonStatus = createServiceStatus('blocked', daemonHost, daemonPort, {
@@ -236,45 +379,68 @@ export async function startHostServices(config, runtimeBus, hookDispatcher, runt
             }
         }
         else {
-            const pendingDaemonServer = factories.createDaemonServer
-                ? factories.createDaemonServer(runtimeBus, sharedUserAuth, runtimeServices)
-                : await createDefaultDaemonServer(runtimeBus, sharedUserAuth, runtimeServices);
-            const service = pendingDaemonServer;
-            service.enable({ daemon: true }, factories.sharedDaemonToken);
-            const started = await startGuardedService({
-                label: 'Daemon server',
-                service,
-                timeoutMs: startupTimeoutMs,
-                timedOutStatus: () => createServiceStatus('unavailable', daemonHost, daemonPort, {
-                    reason: 'Daemon server startup timed out',
-                }),
-                startedStatus: () => createServiceStatus('embedded', daemonHost, daemonPort, {
-                    reason: 'Embedded daemon started in this host instance',
-                }),
-                bindConflictStatus: async (message) => {
-                    const identity = await probeDaemonIdentity(daemonHost, daemonPort, factories.sharedDaemonToken);
-                    if (identity.kind === 'goodvibes') {
-                        logger.info('Existing GoodVibes daemon detected after bind conflict; continuing without embedded daemon in this host instance', {
-                            host: daemonHost,
-                            port: daemonPort,
-                            version: identity.version,
-                        });
-                        return createServiceStatus('external', daemonHost, daemonPort, {
-                            authenticated: true,
-                            status: identity.status,
-                            version: identity.version,
-                            reason: 'Existing GoodVibes daemon verified after bind conflict',
+            // Port is free. Owner ruling (D7a): the daemon is a SYSTEM SERVICE, so
+            // starting a surface must NOT couple the daemon's lifetime to this process.
+            // DEFAULT (Layer 2): spawn the daemon as a detached standalone process and
+            // adopt it as 'external'. In-process embedding is an explicit opt-in
+            // (Layer 3: daemon.embedInProcess).
+            const startEmbeddedDaemon = async () => {
+                const pendingDaemonServer = factories.createDaemonServer
+                    ? factories.createDaemonServer(runtimeBus, sharedUserAuth, runtimeServices)
+                    : await createDefaultDaemonServer(runtimeBus, sharedUserAuth, runtimeServices);
+                const service = pendingDaemonServer;
+                service.enable({ daemon: true }, factories.sharedDaemonToken);
+                return startGuardedService({
+                    label: 'Daemon server',
+                    service,
+                    timeoutMs: startupTimeoutMs,
+                    timedOutStatus: () => createServiceStatus('unavailable', daemonHost, daemonPort, {
+                        reason: 'Daemon server startup timed out',
+                    }),
+                    startedStatus: () => createServiceStatus('embedded', daemonHost, daemonPort, {
+                        reason: 'Embedded daemon started in this host instance (daemon.embedInProcess opt-in)',
+                    }),
+                    bindConflictStatus: async (message) => {
+                        const identity = await probeDaemonIdentity(daemonHost, daemonPort, factories.sharedDaemonToken);
+                        if (identity.kind === 'goodvibes') {
+                            const verified = resolveVerifiedDaemonStatus(identity, 'Existing GoodVibes daemon verified after bind conflict');
+                            if (verified.mode === 'external') {
+                                logger.info('Existing GoodVibes daemon detected after bind conflict; continuing without embedded daemon in this host instance', { host: daemonHost, port: daemonPort, version: identity.version });
+                            }
+                            return verified;
+                        }
+                        logger.warn('Daemon server port already in use; continuing without local daemon in this host instance', { error: message });
+                        return createServiceStatus('blocked', daemonHost, daemonPort, {
+                            authenticated: identity.kind !== 'unauthorized' ? undefined : false,
+                            reason: identity.reason ?? message,
                         });
-                    }
-                    logger.warn('Daemon server port already in use; continuing without local daemon in this host instance', { error: message });
-                    return createServiceStatus('blocked', daemonHost, daemonPort, {
-                        authenticated: identity.kind !== 'unauthorized' ? undefined : false,
-                        reason: identity.reason ?? message,
+                    },
+                });
+            };
+            if (readDaemonEmbedInProcess(config)) {
+                logger.warn('daemon.embedInProcess is enabled: hosting the daemon in-process couples its lifetime to this surface (single point of failure)');
+                const started = await startEmbeddedDaemon();
+                embeddedDaemonServer = started.service;
+                daemonStatus = started.status;
+            }
+            else {
+                const detached = await attemptDetachedDaemonSpawn();
+                if ('status' in detached) {
+                    daemonStatus = detached.status;
+                    daemonStartHint = detached.hint;
+                    logger.info('Spawned detached GoodVibes daemon for this session', {
+                        host: daemonHost,
+                        port: daemonPort,
+                        version: detached.status.version,
                     });
-                },
-            });
-            embeddedDaemonServer = started.service;
-            daemonStatus = started.status;
+                }
+                else {
+                    logger.warn('Detached daemon spawn did not become reachable; falling back to in-process embedded daemon for this session', { reason: detached.reason });
+                    const started = await startEmbeddedDaemon();
+                    embeddedDaemonServer = started.service;
+                    daemonStatus = started.status;
+                }
+            }
         }
     }
     if (readBooleanSetting(config, 'danger.httpListener')) {
@@ -317,6 +483,7 @@ export async function startHostServices(config, runtimeBus, hookDispatcher, runt
         httpListener: embeddedHttpListener,
         daemonStatus,
         httpListenerStatus,
+        ...(daemonStartHint !== undefined ? { daemonStartHint } : {}),
         listRecentControlPlaneEvents(limit) {
             return embeddedDaemonServer?.listRecentControlPlaneEvents(limit) ?? [];
         },

package/dist/platform/runtime/daemon-version-compat.d.ts

@@ -0,0 +1,39 @@
+/**
+ * daemon-version-compat.ts
+ *
+ * The adopt-or-start path (bootstrap-services.ts) verifies that a daemon found
+ * on the configured port is a GoodVibes daemon via its `/status` identity probe,
+ * which reports the daemon's SDK `version`. Verifying identity is NOT the same as
+ * verifying that the daemon speaks the SAME wire shape this surface expects:
+ * adopting a daemon built from an incompatible SDK band produces silent
+ * wire-shape failures (a session method the surface calls that the daemon does
+ * not serve, a payload field that moved). This module answers the one question
+ * the probe leaves open — "may this surface safely adopt a daemon reporting
+ * version X?" — so the adopt path can refuse an incompatible occupant honestly
+ * instead of adopting it and failing later, and without ever starting a second
+ * competing daemon on an occupied port.
+ *
+ * Compatibility band policy (semver, https://semver.org/#spec-item-4):
+ *   - `0.y.z` releases treat the MINOR position as the breaking axis, so two
+ *     `0.y` versions are compatible only when `y` matches (0.38.x adopts 0.38.*
+ *     but not 0.37.*).
+ *   - `>=1.0.0` releases treat MAJOR as the breaking axis, so major must match
+ *     (1.4.x adopts any 1.*.* but not 2.*.*).
+ *   - A version string that cannot be parsed is treated as INCOMPATIBLE — the
+ *     conservative, honest default. An empty/absent remote version is likewise
+ *     incompatible: the surface must not adopt something it cannot band-check.
+ * Prerelease and build metadata (`-rc.1`, `+sha`) are ignored for banding.
+ */
+/**
+ * True when a surface reporting `localVersion` may safely adopt a daemon
+ * reporting `remoteVersion` — see the band policy in the file header.
+ * Unparseable or absent versions are never compatible.
+ */
+export declare function isDaemonVersionCompatible(localVersion: string | undefined | null, remoteVersion: string | undefined | null): boolean;
+/**
+ * Human-readable reason string for an incompatible adoption refusal, naming
+ * both the occupied endpoint's version and this surface's version so the
+ * operator can see the skew without guessing.
+ */
+export declare function describeVersionIncompatibility(host: string, port: number, localVersion: string | undefined | null, remoteVersion: string | undefined | null): string;
+//# sourceMappingURL=daemon-version-compat.d.ts.map

package/dist/platform/runtime/daemon-version-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-version-compat.d.ts","sourceRoot":"","sources":["../../../src/platform/runtime/daemon-version-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA0BH;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACvC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACvC,OAAO,CAQT;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACvC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACvC,MAAM,CAIR"}