aiden-runtime 4.1.5 → 4.6.0

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

@@ -0,0 +1,651 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/bootstrap.ts — v4.5 Phase 1 follow-up: shared entry
+ * for daemon foundation initialization.
+ *
+ * Phase 1 wired the daemon init into `api/server.ts`. That path is
+ * only hit when the user starts the HTTP API server (Electron child,
+ * `aiden serve`-style invocation, OpenAI-compatible endpoint
+ * mode). The interactive REPL entry (`cli/v4/aidenCLI.ts`) is
+ * standalone and never imports api/server.ts, so AIDEN_DAEMON=1
+ * silently did nothing for REPL users.
+ *
+ * This module is the single bootstrap that BOTH entry points call.
+ * Idempotent — safe to invoke from multiple sites in the same
+ * process (the singleton guard returns the existing handle).
+ *
+ * When an Express app is supplied (api/server.ts path), health
+ * endpoints mount onto it. When omitted (CLI path), a minimal
+ * Express server is spun up on the configured port so
+ * `/health/live`, `/metrics`, etc. are reachable regardless of
+ * how the user invoked Aiden.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrapDaemon = bootstrapDaemon;
+exports._resetDaemonBootstrapForTests = _resetDaemonBootstrapForTests;
+exports.getDaemonHandle = getDaemonHandle;
+exports.bootstrapDaemonFoundation = bootstrapDaemonFoundation;
+exports.installDaemonAgentBuilder = installDaemonAgentBuilder;
+const express_1 = __importDefault(require("express"));
+const node_http_1 = __importDefault(require("node:http"));
+const daemonConfig_1 = require("./daemonConfig");
+const daemonConfig_2 = require("./daemonConfig");
+const paths_1 = require("../paths");
+const connection_1 = require("./db/connection");
+const runtimeLock_1 = require("./runtimeLock");
+const instanceTracker_1 = require("./instanceTracker");
+const cleanShutdown_1 = require("./cleanShutdown");
+const triggerBus_1 = require("./triggerBus");
+const idempotencyStore_1 = require("./idempotencyStore");
+const runStore_1 = require("./runStore");
+const restartFailureCounter_1 = require("./restartFailureCounter");
+const resourceRegistry_1 = require("./resourceRegistry");
+const eventLoopLag_1 = require("./eventLoopLag");
+const health_1 = require("./health");
+const signals_1 = require("./signals");
+// v4.5 Phase 2 — file watcher trigger.
+const fileObservationsStore_1 = require("./triggers/fileObservationsStore");
+const fileWatcher_1 = require("./triggers/fileWatcher");
+const reconcile_1 = require("./triggers/reconcile");
+const fileWatcherSpec_1 = require("./triggers/fileWatcherSpec");
+// v4.5 Phase 3 — webhook trigger.
+const webhook_1 = require("./triggers/webhook");
+// v4.5 Phase 4a — email trigger.
+const email_1 = require("./triggers/email");
+const emailSpec_1 = require("./triggers/email/emailSpec");
+const emailSeenStore_1 = require("./triggers/email/emailSeenStore");
+// v4.5 Phase 5a — trigger dispatcher.
+const dispatcher_1 = require("./dispatcher");
+// v4.5 Phase 5b — cron migration to SQLite + daemon-mode emitter.
+const migration_1 = require("./cron/migration");
+const cronEmitter_1 = require("./cron/cronEmitter");
+const playwrightBridge_1 = require("../../playwrightBridge");
+const version_1 = require("../../version");
+const NOOP_HANDLE = Object.freeze({
+    active: false,
+    instanceId: null,
+    ownsHttpServer: false,
+    triggerBus: null,
+    idempotencyStore: null,
+    runStore: null,
+    restartFailureCounter: null,
+    resourceRegistry: null,
+    instanceTracker: null,
+    runtimeLock: null,
+    dbPath: null,
+    markerPath: null,
+    httpServer: null,
+    fileWatchers: Object.freeze([]),
+    webhookRoutes: null,
+    emailTriggers: Object.freeze([]),
+    dispatcher: null,
+    cronMigration: null,
+});
+// Process-wide singleton — the second call returns the same handle.
+let _singleton = null;
+/**
+ * Initialize the daemon foundation IF AIDEN_DAEMON=1. Returns a
+ * handle describing what was wired (or a NOOP_HANDLE when the
+ * daemon is disabled).
+ *
+ * Idempotent: a second call returns the existing singleton.
+ *
+ * Failures during init log a loud error but do NOT throw — the
+ * agent loop should keep running even if daemon foundation init
+ * fails, so the user isn't blocked from chatting because (say)
+ * docker is dead. Health endpoints will simply be absent.
+ */
+function bootstrapDaemon(opts = {}) {
+    if (_singleton)
+        return _singleton;
+    const cfg = (0, daemonConfig_1.getDaemonConfig)();
+    const log = opts.log ?? ((level, msg) => {
+        if (level === 'error')
+            console.error(msg);
+        else if (level === 'warn')
+            console.warn(msg);
+        else
+            console.log(msg);
+    });
+    if (!cfg.enabled) {
+        _singleton = NOOP_HANDLE;
+        return NOOP_HANDLE;
+    }
+    try {
+        const aidenRoot = (0, paths_1.resolveAidenRoot)();
+        const dbPath = (0, daemonConfig_2.daemonDbPath)(aidenRoot);
+        const lockPath = (0, daemonConfig_2.daemonRuntimeLockPath)(aidenRoot);
+        const markerPath = (0, daemonConfig_2.daemonCleanShutdownMarkerPath)(aidenRoot);
+        // v4.6 Phase 3A — wire the spawn-pause singleton against the
+        // same `aidenRoot` the REPL uses. Daemon-fired turns that
+        // invoke `subagent_fanout` will read the same marker file the
+        // REPL writes via /spawn-pause. Cross-process coordination is
+        // the whole point of the file-marker design (in-process
+        // singletons in three runtimes would each have independent
+        // pause flags, which would defeat the operator control).
+        // The init is idempotent — if the REPL already ran initSpawnPause
+        // in this same process, this call replaces the singleton with
+        // an equivalent one pointing at the same path.
+        //
+        // Defensive try/catch: a pause-init failure must NOT prevent
+        // daemon bootstrap. Worst case the singleton stays uninit and
+        // tool handlers fall through to their `safeReadPause` path
+        // (treat as "not paused"). The daemon's startup probe below
+        // is best-effort.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { initSpawnPause } = require('../subagent/spawnPause');
+            const sp = initSpawnPause({ aidenHome: aidenRoot });
+            if (sp.isPaused()) {
+                const s = sp.status();
+                const reasonSuffix = s.reason ? ` (reason: ${s.reason})` : '';
+                log('warn', `[daemon] sub-agent spawning is PAUSED${reasonSuffix}. ` +
+                    'Daemon-fired subagent_fanout calls will reject until an operator ' +
+                    'runs /spawn-pause off in a REPL session.');
+            }
+        }
+        catch (e) {
+            log('warn', '[daemon] spawn-pause init failed (non-fatal): ' +
+                (e instanceof Error ? e.message : String(e)));
+        }
+        const db = (0, connection_1.openDaemonDb)(dbPath);
+        const tracker = (0, instanceTracker_1.createInstanceTracker)({ db, version: version_1.VERSION });
+        tracker.start();
+        // v4.6 Phase 3b — self-improvement loop singleton. Daemon-fired
+        // turns that classify failures via TCE write through to the
+        // shared failure ledger, so operator queries from a REPL see
+        // daemon-side failure patterns too. Defensive try/catch — init
+        // failure must not block daemon bootstrap; the TCE write-through
+        // path silently no-ops when the singleton is missing.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { initRecoveryStore } = require('../selfimprovement/recoveryStore');
+            initRecoveryStore({ db });
+        }
+        catch (e) {
+            log('warn', '[daemon] recovery-store init failed (non-fatal): ' +
+                (e instanceof Error ? e.message : String(e)));
+        }
+        // Race-safe runtime lock. EEXIST + live PID → DaemonAlreadyRunningError.
+        let runtimeLock;
+        try {
+            runtimeLock = (0, runtimeLock_1.acquireRuntimeLock)({
+                lockPath,
+                instanceId: tracker.instanceId,
+                log,
+            });
+        }
+        catch (e) {
+            tracker.stop();
+            if (e instanceof runtimeLock_1.DaemonAlreadyRunningError) {
+                log('error', '[daemon] ' + e.message);
+                // Fail-loud: AIDEN_DAEMON=1 + another daemon already running is
+                // an unambiguous error condition that should surface.
+                process.exit(1);
+            }
+            throw e;
+        }
+        // Boot-state evaluation: detects crashed prior instance, writes
+        // crash_reports, marks affected runs interrupted+resume_pending=1.
+        const boot = (0, cleanShutdown_1.evaluateBootState)({ db, markerPath, instanceId: tracker.instanceId });
+        if (boot.crashDetected) {
+            log('warn', '[daemon] crash recovery: prior instance crashed; affected runs marked resume_pending=1');
+        }
+        // Module singletons.
+        const triggerBus = (0, triggerBus_1.createTriggerBus)({ db });
+        const idempotencyStore = (0, idempotencyStore_1.createIdempotencyStore)({ db });
+        const runStore = (0, runStore_1.createRunStore)({ db });
+        const restartFailureCounter = (0, restartFailureCounter_1.createRestartFailureCounter)({ db, threshold: cfg.restartFailureThreshold });
+        const resourceRegistry = (0, resourceRegistry_1.getResourceRegistry)();
+        try {
+            idempotencyStore.reseed();
+        }
+        catch { /* best-effort */ }
+        (0, eventLoopLag_1.startEventLoopLagSampler)();
+        // Mount health endpoints. When the caller supplied an existing
+        // Express app (api/server.ts path), use it. Otherwise spin up a
+        // minimal Express server on the configured port (CLI path).
+        let app = opts.app;
+        let httpServer = null;
+        let ownsHttpServer = false;
+        if (!app) {
+            app = (0, express_1.default)();
+            // NOTE: deliberately DO NOT install express.json() globally.
+            // The daemon-only routes mounted below are:
+            //   - GET /health/{live,ready,degraded}   — no body
+            //   - GET /metrics                        — no body
+            //   - GET /api/daemon/{status,resources}  — no body
+            //   - POST /api/triggers/webhook/:id      — requires RAW body
+            //                                            (express.raw inline)
+            // If a global json parser were registered here, it would
+            // consume the webhook body BEFORE the route's express.raw
+            // could see it, making HMAC verification always fail.
+            ownsHttpServer = true;
+        }
+        (0, health_1.mountHealthEndpoints)(app, {
+            db,
+            triggerBus,
+            resourceRegistry,
+            instanceTracker: tracker,
+            version: version_1.VERSION,
+        });
+        // v4.5 Phase 3 — webhook routes mount on the same Express app.
+        // Single dispatch endpoint POST /api/triggers/webhook/:id resolves
+        // routes at request time, so no per-route Express handler bloat.
+        const webhookRoutes = (0, webhook_1.mountWebhookRoutes)({
+            app,
+            db,
+            triggerBus,
+            idempotencyStore,
+            resourceRegistry,
+            log,
+        });
+        // v4.5 Phase 3 — bind safety check. When AIDEN_DAEMON_BIND opts
+        // into a non-loopback interface, require AIDEN_API_KEY + refuse
+        // INSECURE_NO_AUTH webhook routes. Runs BEFORE the listener binds.
+        const bindHost = process.env.AIDEN_DAEMON_BIND ?? '127.0.0.1';
+        try {
+            (0, webhook_1.assertSafeBind)({
+                bindHost,
+                apiKeyConfigured: typeof process.env.AIDEN_API_KEY === 'string' && process.env.AIDEN_API_KEY.length > 0,
+                db,
+                log,
+            });
+        }
+        catch (e) {
+            // Refuse to bring up the HTTP listener but DO keep the foundation
+            // running (file watchers, daemon db, instance tracker) so the
+            // operator can see status via the daemon-already-running guard.
+            log('error', '[daemon] refusing to start HTTP listener due to bind-safety check failure');
+            throw e;
+        }
+        if (ownsHttpServer) {
+            httpServer = node_http_1.default.createServer(app);
+            httpServer.listen(cfg.port, bindHost, () => {
+                log('info', `[daemon] http server listening on http://${bindHost}:${cfg.port}`);
+            });
+            httpServer.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    log('warn', `[daemon] port ${cfg.port} in use — health endpoints unavailable (db / triggers still active)`);
+                }
+                else {
+                    log('error', `[daemon] http server error: ${err.message}`);
+                }
+            });
+        }
+        // v4.5 Phase 3 — webhook deliveries retention sweep. Runs once on
+        // boot then every 24h. Configurable via env (default 7 days).
+        const retentionDays = (() => {
+            const raw = process.env.AIDEN_DAEMON_WEBHOOK_RETENTION_DAYS;
+            const n = raw ? Number.parseInt(raw, 10) : NaN;
+            return Number.isFinite(n) && n > 0 ? n : 7;
+        })();
+        try {
+            const swept = webhookRoutes.sweepDeliveries(retentionDays);
+            if (swept.deleted > 0) {
+                log('info', `[webhook] retention sweep: deleted ${swept.deleted} delivery rows older than ${retentionDays}d`);
+            }
+        }
+        catch { /* best-effort */ }
+        const retentionTimer = setInterval(() => {
+            try {
+                webhookRoutes.sweepDeliveries(retentionDays);
+            }
+            catch { /* never let sweep crash */ }
+        }, 24 * 60 * 60 * 1000);
+        if (typeof retentionTimer.unref === 'function')
+            retentionTimer.unref();
+        // Drain context — same shape api/server.ts wires.
+        const getDrainCtx = () => ({
+            drainTimeoutMs: cfg.drainTimeoutMs,
+            reason: 'sigterm',
+            notifySessions: async () => { },
+            activeRuns: () => runStore.listActive().map((r) => r.id),
+            markResumePending: (runId, reason) => runStore.markResumePending(runId, reason),
+            interruptRun: async () => {
+                // v4.5 Phase 5a — the dispatcher's runner is the
+                // unit-of-interrupt. Phase 5a's runner is synchronous
+                // (placeholder); the real AidenAgent-backed runner will
+                // receive a per-run abort signal when wired.
+            },
+            killToolSubprocesses: async () => { },
+            closeBrowser: () => (0, playwrightBridge_1.pwClose)(),
+            closeCron: () => { },
+            closeIdempotency: () => idempotencyStore.close(),
+            closeResources: () => resourceRegistry.reapAll(3000),
+            touchCleanShutdown: () => (0, cleanShutdown_1.touchCleanShutdownMarker)(markerPath),
+            removePid: async () => {
+                // v4.5 Phase 5a — drain in-flight dispatcher claims before
+                // releasing the runtime lock so SIGTERM-replace doesn't
+                // duplicate trigger work on the incoming instance.
+                if (_singleton?.dispatcher) {
+                    try {
+                        await _singleton.dispatcher.stop(cfg.drainTimeoutMs);
+                    }
+                    catch { /* never block shutdown on dispatcher cleanup */ }
+                }
+                try {
+                    runtimeLock.release();
+                }
+                catch { /* noop */ }
+                (0, eventLoopLag_1.stopEventLoopLagSampler)();
+                tracker.stop();
+                if (httpServer) {
+                    try {
+                        httpServer.close();
+                    }
+                    catch { /* noop */ }
+                }
+            },
+            markShutdown: (reason, exitCode) => tracker.markShutdown(reason, exitCode),
+        });
+        (0, signals_1.installDaemonSignalHandlers)({ getDrainContext: getDrainCtx });
+        log('info', `[daemon] foundation initializing instance_id=${tracker.instanceId} db=${dbPath}`);
+        if (boot.crashDetected) {
+            log('warn', '[daemon] boot state: crash recovery applied');
+        }
+        else if (boot.cleanShutdown) {
+            log('info', '[daemon] boot state: clean (previous instance exited gracefully)');
+        }
+        else {
+            log('info', '[daemon] boot state: first boot / no prior daemon detected');
+        }
+        // ── v4.5 Phase 2 — load enabled file-watcher triggers ────────────────
+        const fileWatchers = [];
+        try {
+            const obsStore = (0, fileObservationsStore_1.createFileObservationsStore)({ db });
+            const rows = db
+                .prepare(`SELECT * FROM triggers WHERE source = 'file' AND enabled = 1 ORDER BY name`)
+                .all();
+            for (const t of rows) {
+                try {
+                    const spec = (0, fileWatcherSpec_1.parseFileWatcherSpec)(t.spec_json);
+                    // Boot-time reconciliation BEFORE the watcher starts so
+                    // the policy decision is deterministic.
+                    (0, reconcile_1.reconcileFileWatcher)({
+                        watcherId: t.id, spec, triggerBus, obsStore, log,
+                    });
+                    const handle = (0, fileWatcher_1.createFileWatcher)({
+                        watcherId: t.id, spec, triggerBus, obsStore,
+                        registry: resourceRegistry, log,
+                    });
+                    fileWatchers.push(handle);
+                    log('info', `[file-watcher] active: ${t.name} (${t.id}) paths=${spec.paths.length}`);
+                }
+                catch (e) {
+                    log('error', `[file-watcher] failed to start ${t.name}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (rows.length === 0) {
+                log('info', '[file-watcher] no file triggers registered');
+            }
+        }
+        catch (e) {
+            log('error', `[file-watcher] trigger registry scan failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // ── v4.5 Phase 4a — load enabled email-IMAP triggers ─────────────────
+        const emailTriggers = [];
+        try {
+            const seenStore = (0, emailSeenStore_1.createEmailSeenStore)({ db });
+            const rows = db
+                .prepare(`SELECT * FROM triggers WHERE source = 'email' AND enabled = 1 ORDER BY name`)
+                .all();
+            for (const t of rows) {
+                try {
+                    const spec = (0, emailSpec_1.parseEmailSpec)(t.spec_json);
+                    const handle = (0, email_1.createEmailTrigger)({
+                        watcherId: t.id,
+                        spec,
+                        triggerBus,
+                        emailSeenStore: seenStore,
+                        db,
+                        registry: resourceRegistry,
+                        log,
+                    });
+                    emailTriggers.push(handle);
+                    log('info', `[email] active: ${t.name} (${t.id}) host=${spec.imap.host} mailbox=${spec.mailbox}`);
+                }
+                catch (e) {
+                    log('error', `[email] failed to start ${t.name}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (rows.length === 0) {
+                log('info', '[email] no email triggers registered');
+            }
+            // Retention sweep on boot (and every 24h via unref'd interval).
+            const retentionDays = (() => {
+                const raw = process.env.AIDEN_DAEMON_EMAIL_RETENTION_DAYS;
+                const n = raw ? Number.parseInt(raw, 10) : NaN;
+                return Number.isFinite(n) && n > 0 ? n : 30;
+            })();
+            try {
+                const swept = seenStore.sweep(retentionDays);
+                if (swept.deleted > 0) {
+                    log('info', `[email] retention sweep: deleted ${swept.deleted} email_seen rows older than ${retentionDays}d`);
+                }
+            }
+            catch { /* best-effort */ }
+            const emailRetTimer = setInterval(() => {
+                try {
+                    seenStore.sweep(retentionDays);
+                }
+                catch { /* never let sweep crash */ }
+            }, 24 * 60 * 60 * 1000);
+            if (typeof emailRetTimer.unref === 'function')
+                emailRetTimer.unref();
+        }
+        catch (e) {
+            log('error', `[email] trigger registry scan failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // ── v4.5 Phase 5b — cron JSON → SQLite migration ─────────────────────
+        // Idempotent: only copies rows when scheduled_workflows is empty
+        // AND ~/.aiden/cron_jobs.json exists. Subsequent boots return
+        // {ran:false, reason:'already_migrated'}. Original JSON file is
+        // left in place so AIDEN_DAEMON=0 callers keep working.
+        let cronMigrationResult = null;
+        try {
+            const res = (0, migration_1.runCronMigration)({ db, log });
+            cronMigrationResult = {
+                ran: res.ran,
+                migrated: res.migrated,
+                skipped: res.skipped,
+                backupPath: res.backupPath,
+                reason: res.reason,
+            };
+        }
+        catch (e) {
+            log('error', `[cron-migration] unhandled failure: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // ── v4.5 Phase 5b — install daemon-mode cron emitter ─────────────────
+        // When AIDEN_DAEMON=1, cron fires go through the trigger bus
+        // (consumed by the Phase 5a dispatcher) instead of shelling out.
+        // We swap the cronManager's RunActionFn here so any cron heartbeat
+        // started by the CLI uses the daemon-mode path.
+        //
+        // Best-effort import — we don't pull cronManager into the daemon
+        // hot path unless the user actually runs cron. The import is
+        // lazy so non-cron CLIs don't pay the cost.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const cm = require('../cron/cronManager');
+            const emitter = (0, cronEmitter_1.createCronEmitter)({
+                triggerBus, db, log,
+            });
+            cm.setRunActionForTests(emitter);
+            log('info', `[cron-emitter] daemon-mode runAction installed`);
+        }
+        catch (e) {
+            log('warn', `[cron-emitter] install skipped: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // ── v4.5 Phase 5a — start the trigger dispatcher ─────────────────────
+        // The dispatcher is the bus consumer. It claims pending
+        // trigger_events and routes them through the agent loop (or
+        // the deliverOnly stub when spec.deliver_only=1). Phase 5a
+        // wires a placeholder runner that returns 'stop' immediately
+        // — the real AidenAgent-backed runner is wired by the CLI
+        // entry path in a follow-up (it owns provider/toolExecutor
+        // construction). The dispatcher infrastructure is fully
+        // functional NOW; the runner adapter is the last seam.
+        let dispatcher = null;
+        try {
+            // v4.5 Phase 7 — runner selection: real agent when builder
+            // injected, placeholder otherwise. Both paths exercise the
+            // full bus / claim / lease / markDone / run_events plumbing;
+            // the difference is whether real `AidenAgent.runConversation`
+            // fires or just an immediate stop.
+            const runnerFactory = opts.agentBuilder
+                ? () => (0, dispatcher_1.createRealAgentRunner)({
+                    db, runStore, resourceRegistry,
+                    log, agentBuilder: opts.agentBuilder,
+                    persistedDefault: opts.persistedDefaultModel,
+                })
+                : () => (0, dispatcher_1.makeRunner)(async (input) => {
+                    // Phase 5a placeholder runner — used when no AgentBuilder
+                    // is injected (e.g. user has no provider configured yet).
+                    // Marks the run completed with finishReason='stop' after
+                    // creating the run row + emitting a placeholder event.
+                    // The bus / dispatch / lease / markDone path is fully
+                    // exercised end-to-end so soak harness + tests still
+                    // work without a real model wired.
+                    const runId = runStore.create({
+                        sessionId: input.sessionId,
+                        instanceId: input.instanceId,
+                        triggerEventId: input.triggerEventId,
+                        status: 'running',
+                    });
+                    runStore.emitEvent(runId, 'dispatcher:invoked', {
+                        source: input.triggerContext.source,
+                        triggerId: input.triggerContext.triggerId,
+                        eventId: input.triggerEventId,
+                        templated: input.triggerContext.promptTemplate !== null,
+                        messageLen: input.initialMessage.length,
+                    });
+                    runStore.setStatus(runId, 'completed', { finishReason: 'stop' });
+                    const result = { runId, finishReason: 'stop' };
+                    return result;
+                });
+            dispatcher = (0, dispatcher_1.createDispatcher)({
+                triggerBus,
+                runStore,
+                db,
+                ownerId: tracker.instanceId,
+                instanceId: tracker.instanceId,
+                workerCount: 1, // Q-P5-1(a)
+                runnerFactory,
+                log,
+            });
+            dispatcher.start();
+            log('info', `[dispatcher] active workerCount=1 runner=${opts.agentBuilder ? 'real' : 'placeholder'}`);
+        }
+        catch (e) {
+            log('error', `[dispatcher] start failed: ${e instanceof Error ? e.message : String(e)}`);
+            dispatcher = null;
+        }
+        _singleton = {
+            active: true,
+            instanceId: tracker.instanceId,
+            ownsHttpServer,
+            triggerBus,
+            idempotencyStore,
+            runStore,
+            restartFailureCounter,
+            resourceRegistry,
+            instanceTracker: tracker,
+            runtimeLock,
+            dbPath,
+            markerPath,
+            httpServer,
+            fileWatchers,
+            webhookRoutes,
+            emailTriggers,
+            dispatcher,
+            cronMigration: cronMigrationResult,
+        };
+        return _singleton;
+    }
+    catch (e) {
+        // Fail-loud but non-fatal: the agent should keep running.
+        log('error', `[daemon] foundation init failed: ${e instanceof Error ? e.message : String(e)}`);
+        _singleton = NOOP_HANDLE;
+        return NOOP_HANDLE;
+    }
+}
+/** Test-only — clears the singleton so subsequent calls re-bootstrap. */
+function _resetDaemonBootstrapForTests() {
+    _singleton = null;
+}
+/** Diagnostic — returns the current handle (or null if not yet bootstrapped). */
+function getDaemonHandle() {
+    return _singleton;
+}
+/**
+ * v4.5 Phase 7c — boot the daemon foundation without any agent
+ * builder. Drop-in replacement for `bootstrapDaemon()` callers that
+ * want the rails (file watchers, webhook routes, email triggers,
+ * cron emitter, dispatcher with placeholder runner) up immediately,
+ * with the real-agent runner installed later via
+ * `installDaemonAgentBuilder()`.
+ *
+ * Use this at the top of REPL boot (before `buildAgentRuntime`)
+ * so the daemon foundation comes up regardless of whether the user
+ * has a provider configured. Once `buildAgentRuntime` returns, call
+ * `installDaemonAgentBuilder(handle, builder, persistedDefaultModel)`
+ * to swap in the real runner.
+ *
+ * Idempotent — second call returns the existing singleton.
+ */
+function bootstrapDaemonFoundation(opts = {}) {
+    return bootstrapDaemon(opts);
+}
+/**
+ * v4.5 Phase 7c — swap the dispatcher's placeholder runner for a
+ * real `AidenAgent`-backed one. Safe to call once the REPL's
+ * provider, toolRegistry, and prompt builder are constructed.
+ *
+ * Returns `false` when the foundation isn't active (AIDEN_DAEMON=0
+ * or `bootstrapDaemonFoundation` not called) — caller can decide
+ * what to do.
+ *
+ * Returns `true` when the swap succeeded. The dispatcher's next
+ * claim uses the new runner; any in-flight claim continues on the
+ * placeholder until completion (the placeholder's behavior is
+ * instant-stop, so this window is effectively zero).
+ */
+function installDaemonAgentBuilder(handle, agentBuilder, persistedDefaultModel, log) {
+    if (!handle.active || !handle.dispatcher || !handle.triggerBus || !handle.runStore) {
+        return false;
+    }
+    const logFn = log ?? ((level, msg) => {
+        if (level === 'error')
+            console.error(msg);
+        else if (level === 'warn')
+            console.warn(msg);
+        else
+            console.log(msg);
+    });
+    try {
+        const realRunner = (0, dispatcher_1.createRealAgentRunner)({
+            db: (0, connection_1.openDaemonDb)(handle.dbPath),
+            runStore: handle.runStore,
+            resourceRegistry: handle.resourceRegistry ?? undefined,
+            log: logFn,
+            agentBuilder,
+            persistedDefault: persistedDefaultModel,
+        });
+        handle.dispatcher.installRunner(realRunner);
+        return true;
+    }
+    catch (e) {
+        logFn('error', `[daemon] installDaemonAgentBuilder failed: ${e instanceof Error ? e.message : String(e)}`);
+        return false;
+    }
+}