voidforge-build 23.9.1

package/dist/wizard/lib/heartbeat.js

@@ -0,0 +1,538 @@
+/**
+ * Heartbeat Daemon — The single-writer for all financial state (ADR-1).
+ *
+ * This module implements the heartbeat daemon: a background Node.js process
+ * that owns all financial state mutations. The CLI and Danger Room are clients
+ * that communicate via the Unix domain socket API.
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.4, §9.20.11
+ *
+ * Structure (v23.2 split):
+ *   heartbeat.ts            — daemon entry point, state, request handling, orchestration
+ *   heartbeat-lifecycle.ts  — daemon startup/shutdown, WAL, campaign persistence types
+ *   heartbeat-scheduler.ts  — scheduled job definitions
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync } from 'node:fs';
+import { readFile, mkdir } from 'node:fs/promises';
+import { writeState, JobScheduler, createLogger, } from './daemon-core.js';
+import { financialVaultLock, financialVaultUnlock } from './financial-vault.js';
+import { totpVerify, totpSessionInvalidate } from './totp.js';
+import { classifyTier } from './safety-tiers.js';
+import { projectVaultLockAll } from './project-vault.js';
+import { appendToLog, atomicWrite, getTreasuryDir, getSpendLog, getRevenueLog } from './financial-core.js';
+import { TREASURY_SUMMARY_FILE, readTreasurySummaryFromLogs } from './treasury-reader.js';
+import { registerTreasuryJobs, handleTreasuryRequest, executeTreasuryFreeze, getTreasuryStateSnapshot, isStablecoinConfigured, } from './treasury-heartbeat.js';
+import { getCampaignAdapter } from './financial/adapter-factory.js';
+import { transition } from './campaign-state-machine.js';
+import { startDaemon, writePendingOp, getLastLogHash, validateCampaignId, } from './heartbeat-lifecycle.js';
+import { registerJobs } from './heartbeat-scheduler.js';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+// ── Daemon State ──────────────────────────────────────
+let daemonState = 'starting';
+let vaultKey = null;
+let sessionTokenState = null;
+let eventId = 0;
+const logger = createLogger(join(VOIDFORGE_DIR, 'heartbeat.log'));
+const daemonStartedAt = new Date().toISOString();
+let daemonProjectId = 'global';
+let daemonProjectDir;
+function activeTreasuryDir() { return getTreasuryDir(daemonProjectDir); }
+function activeSpendLog() { return getSpendLog(daemonProjectDir); }
+function activeRevenueLog() { return getRevenueLog(daemonProjectDir); }
+function activeCampaignsDir() { return join(activeTreasuryDir(), 'campaigns'); }
+const platformFailures = {};
+const platformHealth = {};
+// ── Campaign Persistence ─────────────────────────────
+async function writeCampaignRecord(record) {
+    if (!validateCampaignId(record.campaignId)) {
+        throw new Error(`Invalid campaign ID format: ${record.campaignId.slice(0, 20)}`);
+    }
+    await mkdir(activeCampaignsDir(), { recursive: true });
+    await atomicWrite(join(activeCampaignsDir(), `${record.campaignId}.json`), JSON.stringify(record, null, 2));
+}
+async function readCampaignRecord(campaignId) {
+    if (!validateCampaignId(campaignId))
+        return null;
+    const filePath = join(activeCampaignsDir(), `${campaignId}.json`);
+    try {
+        return JSON.parse(await readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function getActiveCampaignRecords() {
+    return (await readCampaigns()).filter(c => c.status === 'active');
+}
+async function getSuspendedCampaignRecords() {
+    return (await readCampaigns()).filter(c => c.status === 'suspended');
+}
+// ── State Management ──────────────────────────────────
+async function readCampaigns() {
+    try {
+        const { readdir } = await import('node:fs/promises');
+        if (!existsSync(activeCampaignsDir()))
+            return [];
+        const files = await readdir(activeCampaignsDir());
+        const campaigns = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                campaigns.push(JSON.parse(await readFile(join(activeCampaignsDir(), file), 'utf-8')));
+            }
+            catch { /* skip malformed */ }
+        }
+        return campaigns;
+    }
+    catch {
+        return [];
+    }
+}
+async function readTreasurySummary() {
+    try {
+        let totalSpendCents = 0;
+        let totalRevenueCents = 0;
+        if (existsSync(activeSpendLog())) {
+            for (const line of (await readFile(activeSpendLog(), 'utf-8')).trim().split('\n').filter(Boolean)) {
+                try {
+                    totalSpendCents += Math.max(0, JSON.parse(line).amountCents ?? 0);
+                }
+                catch { /* skip */ }
+            }
+        }
+        if (existsSync(activeRevenueLog())) {
+            for (const line of (await readFile(activeRevenueLog(), 'utf-8')).trim().split('\n').filter(Boolean)) {
+                try {
+                    totalRevenueCents += JSON.parse(line).amountCents ?? 0;
+                }
+                catch { /* skip */ }
+            }
+        }
+        const net = totalRevenueCents - totalSpendCents;
+        const roas = totalSpendCents > 0 ? totalRevenueCents / totalSpendCents : 0;
+        return { revenue: totalRevenueCents, spend: totalSpendCents, net, roas, budgetRemaining: 0 };
+    }
+    catch {
+        return { revenue: 0, spend: 0, net: 0, roas: 0, budgetRemaining: 0 };
+    }
+}
+async function buildStateSnapshot() {
+    const campaigns = await readCampaigns();
+    const activeCampaigns = campaigns.filter((c) => c.status === 'active').length;
+    const summary = await readTreasurySummary();
+    const treasurySnapshot = isStablecoinConfigured() ? getTreasuryStateSnapshot() : undefined;
+    const alerts = [];
+    if (treasurySnapshot?.fundingFrozen) {
+        alerts.push(`Funding frozen: ${treasurySnapshot.freezeReason ?? 'unknown reason'}`);
+    }
+    return {
+        pid: process.pid, state: daemonState, startedAt: daemonStartedAt,
+        lastHeartbeat: new Date().toISOString(), lastEventId: eventId,
+        cultivationState: daemonState === 'starting' ? 'inactive' : 'active',
+        activePlatforms: Object.keys(platformHealth), activeCampaigns,
+        todaySpend: summary.spend, dailyBudget: 0,
+        alerts, tokenHealth: platformHealth,
+        ...(treasurySnapshot ? {
+            stablecoinBalanceCents: treasurySnapshot.stablecoinBalanceCents,
+            bankBalanceCents: treasurySnapshot.bankBalanceCents,
+            runwayDays: treasurySnapshot.runwayDays,
+            fundingFrozen: treasurySnapshot.fundingFrozen,
+            pendingTransferCount: treasurySnapshot.pendingTransferCount,
+        } : {}),
+    };
+}
+async function writeCurrentState() {
+    await writeState(await buildStateSnapshot());
+    await writeTreasurySummaryFile();
+}
+async function writeTreasurySummaryFile() {
+    try {
+        const treasuryDir = activeTreasuryDir();
+        await mkdir(treasuryDir, { recursive: true });
+        const snap = isStablecoinConfigured() ? getTreasuryStateSnapshot() : null;
+        const hb = snap ? {
+            stablecoinBalanceCents: snap.stablecoinBalanceCents,
+            bankAvailableCents: snap.bankBalanceCents, bankReservedCents: 0,
+            runwayDays: snap.runwayDays,
+            fundingState: snap.fundingFrozen ? 'frozen'
+                : snap.runwayDays > 0 && snap.runwayDays < 7 ? 'degraded'
+                    : snap.runwayDays > 0 ? 'healthy' : null,
+            nextTreasuryEvent: null,
+        } : undefined;
+        const summary = await readTreasurySummaryFromLogs(treasuryDir, hb);
+        await atomicWrite(join(treasuryDir, TREASURY_SUMMARY_FILE), JSON.stringify({ ...summary, timestamp: new Date().toISOString() }));
+    }
+    catch { /* Non-fatal — summary is a cache */ }
+}
+// ── Command Handlers ──────────────────────────────────
+async function handleFreeze() {
+    logger.log('FREEZE command received — pausing all active campaigns');
+    const activeCampaigns = await getActiveCampaignRecords();
+    let pausedCount = 0;
+    const errors = [];
+    for (const campaign of activeCampaigns) {
+        try {
+            const adapter = await getCampaignAdapter(campaign.platform, vaultKey, logger);
+            await adapter.pauseCampaign(campaign.externalId);
+            campaign.status = transition(campaign.status, 'suspended', 'cli', 'freeze').newStatus;
+            campaign.updatedAt = new Date().toISOString();
+            await writeCampaignRecord(campaign);
+            pausedCount++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`${campaign.campaignId}: ${msg}`);
+            logger.log(`Freeze: failed to pause campaign ${campaign.campaignId}: ${msg}`);
+        }
+    }
+    daemonState = 'degraded';
+    eventId++;
+    await writeCurrentState();
+    const allPaused = errors.length === 0;
+    logger.log(`Freeze complete: ${pausedCount}/${activeCampaigns.length} campaigns paused${allPaused ? '' : ` (${errors.length} failures)`}`);
+    return {
+        status: allPaused ? 200 : 207,
+        body: {
+            ok: allPaused,
+            message: allPaused ? `Freeze complete: ${pausedCount} campaigns paused`
+                : `Freeze partial: ${pausedCount}/${activeCampaigns.length} campaigns paused, ${errors.length} failed`,
+            pausedCount, totalCampaigns: activeCampaigns.length,
+            errors: errors.length > 0 ? errors : undefined,
+        },
+    };
+}
+async function handleUnfreeze() {
+    logger.log('UNFREEZE command received — resuming suspended campaigns');
+    const suspended = await getSuspendedCampaignRecords();
+    let resumedCount = 0;
+    const errors = [];
+    for (const campaign of suspended) {
+        try {
+            const adapter = await getCampaignAdapter(campaign.platform, vaultKey, logger);
+            await adapter.resumeCampaign(campaign.externalId);
+            campaign.status = transition(campaign.status, 'active', 'cli', 'unfreeze').newStatus;
+            campaign.updatedAt = new Date().toISOString();
+            await writeCampaignRecord(campaign);
+            resumedCount++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`${campaign.campaignId}: ${msg}`);
+            logger.log(`Unfreeze: failed to resume campaign ${campaign.campaignId}: ${msg}`);
+        }
+    }
+    daemonState = 'healthy';
+    eventId++;
+    await writeCurrentState();
+    logger.log(`Unfreeze complete: ${resumedCount}/${suspended.length} campaigns resumed`);
+    return { status: 200, body: { ok: true, message: `Spending resumed: ${resumedCount} campaigns unfrozen`, resumedCount, errors: errors.length > 0 ? errors : undefined } };
+}
+async function handleUnlock(body) {
+    if (!body.password)
+        return { status: 400, body: { ok: false, error: 'Password required' } };
+    const valid = await financialVaultUnlock(body.password);
+    if (!valid) {
+        logger.log('Vault unlock failed — wrong password');
+        return { status: 403, body: { ok: false, error: 'Invalid vault password' } };
+    }
+    vaultKey = body.password;
+    if (daemonState === 'degraded')
+        daemonState = 'healthy';
+    logger.log('Vault unlocked');
+    eventId++;
+    await writeCurrentState();
+    return { status: 200, body: { ok: true, message: 'Vault session renewed' } };
+}
+async function handleCampaignPause(id) {
+    logger.log(`Campaign ${id} pause requested`);
+    const record = await readCampaignRecord(id);
+    if (!record)
+        return { status: 404, body: { ok: false, error: `Campaign not found: ${id}` } };
+    try {
+        const adapter = await getCampaignAdapter(record.platform, vaultKey, logger);
+        await adapter.pauseCampaign(record.externalId);
+        record.status = transition(record.status, 'paused', 'cli', 'user_paused').newStatus;
+        record.updatedAt = new Date().toISOString();
+        await writeCampaignRecord(record);
+        eventId++;
+        await appendToLog(activeSpendLog(), { type: 'campaign_pause', campaignId: id, projectId: daemonProjectId, timestamp: record.updatedAt }, await getLastLogHash(activeSpendLog()));
+        logger.log(`Campaign ${id} paused on ${record.platform}`);
+        return { status: 200, body: { ok: true, campaignId: id, status: 'paused' } };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.log(`Campaign ${id} pause failed: ${msg}`);
+        return { status: 500, body: { ok: false, error: `Pause failed: ${msg}` } };
+    }
+}
+async function handleCampaignResume(id) {
+    logger.log(`Campaign ${id} resume requested`);
+    const record = await readCampaignRecord(id);
+    if (!record)
+        return { status: 404, body: { ok: false, error: `Campaign not found: ${id}` } };
+    try {
+        const adapter = await getCampaignAdapter(record.platform, vaultKey, logger);
+        await adapter.resumeCampaign(record.externalId);
+        record.status = transition(record.status, 'active', 'cli', 'user_resumed').newStatus;
+        record.updatedAt = new Date().toISOString();
+        await writeCampaignRecord(record);
+        eventId++;
+        await appendToLog(activeSpendLog(), { type: 'campaign_resume', campaignId: id, projectId: daemonProjectId, timestamp: record.updatedAt }, await getLastLogHash(activeSpendLog()));
+        logger.log(`Campaign ${id} resumed on ${record.platform}`);
+        return { status: 200, body: { ok: true, campaignId: id, status: 'active' } };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.log(`Campaign ${id} resume failed: ${msg}`);
+        return { status: 500, body: { ok: false, error: `Resume failed: ${msg}` } };
+    }
+}
+async function handleCampaignLaunch(body) {
+    logger.log('Campaign launch requested');
+    const config = body;
+    if (!config.name || !config.platform || !config.dailyBudgetCents || !config.idempotencyKey) {
+        return { status: 400, body: { ok: false, error: 'Missing required fields: name, platform, dailyBudgetCents, idempotencyKey' } };
+    }
+    if (!Number.isFinite(config.dailyBudgetCents) || config.dailyBudgetCents <= 0 || !Number.isInteger(config.dailyBudgetCents)) {
+        return { status: 400, body: { ok: false, error: 'dailyBudgetCents must be a positive integer' } };
+    }
+    const activeCampaigns = await getActiveCampaignRecords();
+    const aggregateDailySpend = activeCampaigns.reduce((sum, c) => (sum + (c.dailyBudgetCents || 0)), 0);
+    const tierResult = classifyTier(config.dailyBudgetCents, aggregateDailySpend);
+    if (tierResult.tier !== 'auto_approve') {
+        logger.log(`Campaign launch: budget $${(config.dailyBudgetCents / 100).toFixed(2)} + aggregate $${(aggregateDailySpend / 100).toFixed(2)}/day → ${tierResult.tier} (${tierResult.reason})`);
+        if (tierResult.requiresTotp)
+            return { status: 403, body: { ok: false, error: `Budget tier: ${tierResult.tier}. ${tierResult.reason}. Requires TOTP.` } };
+    }
+    try {
+        const adapter = await getCampaignAdapter(config.platform, vaultKey, logger);
+        const campaignConfig = {
+            name: config.name, platform: config.platform,
+            objective: config.objective ?? 'traffic',
+            dailyBudget: config.dailyBudgetCents,
+            targeting: config.targeting ?? { audiences: [], locations: [] },
+            creative: config.creative ?? { headlines: [], descriptions: [], callToAction: '', landingUrl: '' },
+            idempotencyKey: config.idempotencyKey, complianceStatus: 'passed',
+        };
+        await writePendingOp({ intentId: config.idempotencyKey, operation: 'campaign_launch', platform: config.platform, params: campaignConfig, status: 'pending', createdAt: new Date().toISOString() }, activeTreasuryDir());
+        const result = await adapter.createCampaign(campaignConfig);
+        const campaignId = config.idempotencyKey;
+        const now = new Date().toISOString();
+        const record = {
+            campaignId, externalId: result.externalId, platform: config.platform,
+            status: result.status === 'pending_review' ? 'pending_approval' : 'active',
+            name: config.name, dailyBudgetCents: config.dailyBudgetCents, createdAt: now, updatedAt: now,
+        };
+        await writeCampaignRecord(record);
+        await appendToLog(activeSpendLog(), { type: 'campaign_launch', campaignId, projectId: daemonProjectId, externalId: result.externalId, platform: config.platform, dailyBudgetCents: config.dailyBudgetCents, timestamp: now }, await getLastLogHash(activeSpendLog()));
+        eventId++;
+        logger.log(`Campaign launched: ${campaignId} → ${result.externalId} on ${config.platform} (status: ${record.status})`);
+        return { status: 200, body: { ok: true, campaignId, externalId: result.externalId, platform: config.platform, status: record.status, dashboardUrl: result.dashboardUrl } };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.log(`Campaign launch failed: ${msg}`);
+        return { status: 500, body: { ok: false, error: `Launch failed: ${msg}` } };
+    }
+}
+async function handleBudgetChange(body) {
+    logger.log('Budget change requested');
+    const params = body;
+    if (!params.campaignId || params.newBudgetCents === undefined)
+        return { status: 400, body: { ok: false, error: 'Missing required fields: campaignId, newBudgetCents' } };
+    if (!Number.isFinite(params.newBudgetCents) || params.newBudgetCents <= 0 || !Number.isInteger(params.newBudgetCents))
+        return { status: 400, body: { ok: false, error: 'newBudgetCents must be a positive integer' } };
+    const activeBudgets = await getActiveCampaignRecords();
+    const currentAggregate = activeBudgets.reduce((sum, c) => (sum + (c.dailyBudgetCents || 0)), 0);
+    const tierResult = classifyTier(params.newBudgetCents, currentAggregate);
+    if (tierResult.requiresTotp)
+        return { status: 403, body: { ok: false, error: `Budget tier: ${tierResult.tier}. ${tierResult.reason}. Requires TOTP.` } };
+    await writePendingOp({ intentId: `budget_${params.campaignId}_${Date.now()}`, operation: 'budget_change', platform: 'unknown', params, status: 'pending', createdAt: new Date().toISOString() }, activeTreasuryDir());
+    const record = await readCampaignRecord(params.campaignId);
+    if (!record)
+        return { status: 404, body: { ok: false, error: `Campaign not found: ${params.campaignId}` } };
+    try {
+        const adapter = await getCampaignAdapter(record.platform, vaultKey, logger);
+        await adapter.updateBudget(record.externalId, params.newBudgetCents);
+        const oldBudget = record.dailyBudgetCents;
+        record.dailyBudgetCents = params.newBudgetCents;
+        record.updatedAt = new Date().toISOString();
+        await writeCampaignRecord(record);
+        await appendToLog(activeSpendLog(), { type: 'budget_change', campaignId: params.campaignId, projectId: daemonProjectId, oldBudgetCents: oldBudget, newBudgetCents: params.newBudgetCents, timestamp: record.updatedAt }, await getLastLogHash(activeSpendLog()));
+        eventId++;
+        logger.log(`Budget changed: ${params.campaignId} $${(oldBudget / 100).toFixed(2)} → $${(params.newBudgetCents / 100).toFixed(2)}`);
+        return { status: 200, body: { ok: true, campaignId: params.campaignId, newBudgetCents: params.newBudgetCents } };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.log(`Budget change failed: ${msg}`);
+        return { status: 500, body: { ok: false, error: `Budget change failed: ${msg}` } };
+    }
+}
+async function handleCreativeUpdate(id, body) {
+    logger.log(`Creative update for campaign ${id}`);
+    const record = await readCampaignRecord(id);
+    if (!record)
+        return { status: 404, body: { ok: false, error: `Campaign not found: ${id}` } };
+    const creative = body;
+    try {
+        const adapter = await getCampaignAdapter(record.platform, vaultKey, logger);
+        await adapter.updateCreative(record.externalId, creative);
+        record.updatedAt = new Date().toISOString();
+        await writeCampaignRecord(record);
+        eventId++;
+        logger.log(`Creative updated for campaign ${id} on ${record.platform}`);
+        return { status: 200, body: { ok: true, campaignId: id, message: 'Creative updated' } };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.log(`Creative update failed for ${id}: ${msg}`);
+        return { status: 500, body: { ok: false, error: `Creative update failed: ${msg}` } };
+    }
+}
+async function handleReconcile() {
+    logger.log('Manual reconciliation requested');
+    eventId++;
+    try {
+        const { runReconciliation } = await import('./reconciliation.js');
+        const today = new Date().toISOString().slice(0, 10);
+        const hour = new Date().getUTCHours();
+        const type = hour >= 6 ? 'final' : 'preliminary';
+        const report = await runReconciliation('default', today, type, new Map(), new Map());
+        return { status: 200, body: { ok: true, message: `Reconciliation (${type}) completed`, report } };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Reconciliation failed';
+        logger.log(`Reconciliation error: ${message}`);
+        return { status: 500, body: { ok: false, error: `Reconciliation failed: ${message}` } };
+    }
+}
+// ── Socket API Request Handler (§9.20.11) ─────────────
+async function handleRequest(method, path, body, auth) {
+    if (!auth.hasToken)
+        return { status: 401, body: { ok: false, error: 'Session token required' } };
+    // SEC-001 + R4-MAUL-001: HMAC vault password comparison (constant-time)
+    let vaultVerified = false;
+    if (auth.vaultPassword && vaultKey) {
+        const { createHmac, timingSafeEqual } = await import('node:crypto');
+        const HMAC_KEY = 'voidforge-vault-password-comparison-v1';
+        const providedMac = createHmac('sha256', HMAC_KEY).update(auth.vaultPassword).digest();
+        const expectedMac = createHmac('sha256', HMAC_KEY).update(vaultKey).digest();
+        vaultVerified = timingSafeEqual(providedMac, expectedMac);
+    }
+    let totpVerified = false;
+    if (auth.totpCode) {
+        try {
+            totpVerified = await totpVerify(auth.totpCode);
+        }
+        catch { /* not configured */ }
+    }
+    // ── Treasury routes ──
+    const treasuryFreeze = async (reason) => {
+        await executeTreasuryFreeze(reason, logger);
+        daemonState = 'degraded';
+        eventId++;
+        await writeCurrentState();
+    };
+    if (path.startsWith('/treasury/')) {
+        const result = await handleTreasuryRequest(method, path, body, { vaultVerified, totpVerified }, logger, treasuryFreeze, vaultKey);
+        if (result) {
+            eventId++;
+            return result;
+        }
+    }
+    // ── GET ──
+    if (method === 'GET') {
+        if (path === '/status')
+            return { status: 200, body: { ok: true, data: await buildStateSnapshot() } };
+        if (path === '/campaigns')
+            return { status: 200, body: { ok: true, data: await readCampaigns() } };
+        if (path === '/treasury')
+            return { status: 200, body: { ok: true, data: await readTreasurySummary() } };
+        return { status: 404, body: { ok: false, error: 'Unknown endpoint' } };
+    }
+    // ── POST ──
+    if (method === 'POST') {
+        if (path === '/freeze')
+            return await handleFreeze();
+        if (path === '/unfreeze') {
+            if (!vaultVerified || !totpVerified)
+                return { status: 403, body: { ok: false, error: 'Unfreeze requires valid vault password + TOTP code' } };
+            return await handleUnfreeze();
+        }
+        if (path === '/unlock')
+            return await handleUnlock(body);
+        if (path.match(/^\/campaigns\/[^/]+\/pause$/))
+            return await handleCampaignPause(path.split('/')[2]);
+        if (path.match(/^\/campaigns\/[^/]+\/creative$/))
+            return await handleCreativeUpdate(path.split('/')[2], body);
+        if (path.match(/^\/campaigns\/[^/]+\/resume$/)) {
+            if (!vaultVerified)
+                return { status: 403, body: { ok: false, error: 'Resume requires valid vault password' } };
+            return await handleCampaignResume(path.split('/')[2]);
+        }
+        if (path === '/campaigns/launch') {
+            if (!vaultVerified)
+                return { status: 403, body: { ok: false, error: 'Campaign launch requires valid vault password' } };
+            return await handleCampaignLaunch(body);
+        }
+        if (path === '/budget') {
+            if (!vaultVerified)
+                return { status: 403, body: { ok: false, error: 'Budget changes require valid vault password' } };
+            return await handleBudgetChange(body);
+        }
+        if (path === '/reconcile')
+            return await handleReconcile();
+        return { status: 404, body: { ok: false, error: 'Unknown endpoint' } };
+    }
+    return { status: 405, body: { ok: false, error: 'Method not allowed' } };
+}
+// ── Main Entry Point ──────────────────────────────────
+export async function startHeartbeat(vaultPassword) {
+    const { server: _server } = await startDaemon(vaultPassword, {
+        logger,
+        getDaemonState: () => daemonState,
+        setDaemonState: (s) => { daemonState = s; },
+        setVaultKey: (k) => { vaultKey = k; },
+        setSessionTokenState: (s) => { sessionTokenState = s; },
+        getDaemonProjectDir: () => daemonProjectDir,
+        writeCurrentState,
+        onShutdown: async () => {
+            logger.log('Shutting down gracefully');
+            daemonState = 'shutting_down';
+            await writeCurrentState();
+            financialVaultLock();
+            projectVaultLockAll();
+            totpSessionInvalidate();
+            logger.close();
+        },
+        handleRequest,
+        activeTreasuryDir,
+    });
+    // Start job scheduler
+    const scheduler = new JobScheduler();
+    registerJobs(scheduler, {
+        logger, get vaultKey() { return vaultKey; },
+        activeTreasuryDir, writeCurrentState, readCampaigns, readTreasurySummary,
+    }, platformHealth, platformFailures);
+    // Register treasury heartbeat jobs
+    const treasuryFreeze = async (reason) => {
+        await executeTreasuryFreeze(reason, logger);
+        daemonState = 'degraded';
+        eventId++;
+        await writeCurrentState();
+    };
+    registerTreasuryJobs(scheduler, logger, writeCurrentState, treasuryFreeze, vaultKey);
+    scheduler.start();
+    // Transition to healthy
+    daemonState = daemonState === 'recovering' ? 'degraded' : 'healthy';
+    await writeCurrentState();
+    logger.log(`Heartbeat daemon running (PID ${process.pid}, state: ${daemonState})`);
+}
+// SEC-007: vaultKey is NOT exported
+function setDaemonProjectId(id) { daemonProjectId = id; }
+function setDaemonProjectDir(dir) { daemonProjectDir = dir; }
+export { daemonState, readCampaigns, readTreasurySummary, setDaemonProjectId, setDaemonProjectDir };

package/dist/wizard/lib/herald.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Herald — intelligent agent dispatch via Haiku pre-scan.
+ *
+ * Before every major slash command, a single Haiku call selects the optimal
+ * agent roster from all agents based on the current context. ADR-048.
+ */
+export interface HeraldInput {
+    command: string;
+    userArgs: string;
+    focus?: string;
+    fileTree: string[];
+    prdFrontmatter?: string;
+    gitDiffSummary?: string;
+}
+export interface AgentEntry {
+    id: string;
+    name: string;
+    description: string;
+    model: string;
+    tags?: string[];
+}
+export interface HeraldResult {
+    roster: string[];
+    reasoning: string;
+    estimatedAgents: number;
+}
+export declare function runHerald(input: HeraldInput, agents: AgentEntry[]): Promise<HeraldResult>;
+export declare function gatherHeraldContext(commandName: string, userArgs: string, focus?: string): Promise<HeraldInput>;