voidforge-build 23.9.1

package/dist/wizard/lib/health-poller.js

@@ -0,0 +1,123 @@
+/**
+ * Health Poller — Background service that pings project health endpoints.
+ * Runs every 5 minutes when the server is active.
+ * Non-blocking: uses fetch with 5-second timeout per project.
+ */
+import { readRegistry, batchUpdateHealthStatus } from './project-registry.js';
+import { isPrivateIp } from './network.js';
+const POLL_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const FETCH_TIMEOUT_MS = 5_000; // 5 seconds per project
+let pollTimer = null;
+let initialTimer = null;
+/** Validate health check URL — only allow http(s) to non-private hosts. */
+function isValidHealthUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return false;
+        // Block SSRF targets: metadata endpoints, localhost, private ranges
+        const host = parsed.hostname.toLowerCase();
+        // Localhost variants
+        // Use shared private IP check (Gauntlet v13.1 consolidation)
+        if (host === 'localhost' || isPrivateIp(host))
+            return false;
+        if (host === '0.0.0.0' || host === '127.1')
+            return false;
+        // AWS/cloud metadata
+        if (host === '169.254.169.254')
+            return false;
+        if (host.startsWith('fe80') || host.startsWith('fc00') || host.startsWith('fd'))
+            return false;
+        // Block bracket-wrapped IPv6
+        if (host.startsWith('['))
+            return false;
+        // Block numeric-only hostnames (decimal IP like 2130706433)
+        if (/^\d+$/.test(host))
+            return false;
+        // Block hex IPs (0x7f000001) and octal IPs (0177.0.0.1)
+        if (/^0[x0-9]/.test(host))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check a single project's health endpoint. */
+async function checkHealth(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            signal: controller.signal,
+            redirect: 'manual', // Don't follow redirects — prevents redirect-based SSRF
+            headers: { 'User-Agent': 'VoidForge-HealthPoller/1.0' },
+        });
+        if (response.status === 200)
+            return 'healthy';
+        return 'degraded';
+    }
+    catch {
+        return 'down';
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Poll all projects with health check URLs (parallel). */
+async function pollAll() {
+    try {
+        const projects = await readRegistry();
+        const withUrls = projects.filter((p) => p.healthCheckUrl && isValidHealthUrl(p.healthCheckUrl));
+        if (withUrls.length === 0)
+            return;
+        // LOKI-004: Check all endpoints in parallel, batch-write results in a single registry update
+        const checkResults = await Promise.allSettled(withUrls.map(async (project) => ({
+            id: project.id,
+            status: await checkHealth(project.healthCheckUrl),
+        })));
+        const updates = [];
+        for (const result of checkResults) {
+            if (result.status === 'fulfilled') {
+                updates.push(result.value);
+            }
+            else {
+                console.error('Health check failed:', result.reason instanceof Error ? result.reason.message : 'Unknown');
+            }
+        }
+        if (updates.length > 0) {
+            await batchUpdateHealthStatus(updates);
+        }
+    }
+    catch (err) {
+        // Registry read failures are non-fatal — log and continue
+        console.error('Health poller error:', err instanceof Error ? err.message : 'Unknown error');
+    }
+}
+/** Start the background health poller. Idempotent — calling twice is safe. */
+export function startHealthPoller() {
+    if (pollTimer)
+        return; // Already running
+    // Run first poll after a short delay (don't block server startup)
+    initialTimer = setTimeout(() => {
+        initialTimer = null;
+        pollAll().catch(() => { });
+    }, 10_000);
+    initialTimer.unref();
+    pollTimer = setInterval(() => {
+        pollAll().catch(() => { });
+    }, POLL_INTERVAL_MS);
+    pollTimer.unref();
+}
+/** Stop the background health poller. */
+export function stopHealthPoller() {
+    if (initialTimer) {
+        clearTimeout(initialTimer);
+        initialTimer = null;
+    }
+    if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+}

package/dist/wizard/lib/heartbeat-lifecycle.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Heartbeat Lifecycle — daemon startup/shutdown orchestration.
+ *
+ * Extracted from heartbeat.ts to isolate the daemon lifecycle logic:
+ * PID file management, vault password acquisition, signal handlers,
+ * state recovery, socket server creation, and WAL reconciliation.
+ *
+ * The startDaemon() function is the main lifecycle entry point, called
+ * by startHeartbeat() in heartbeat.ts with all required callbacks.
+ */
+import type { Server } from 'node:net';
+import type { DaemonState } from './daemon-core.js';
+import type { SessionTokenState } from './oauth-core.js';
+export interface LifecycleCallbacks {
+    logger: {
+        log: (msg: string) => void;
+        close: () => void;
+    };
+    getDaemonState: () => DaemonState;
+    setDaemonState: (state: DaemonState) => void;
+    setVaultKey: (key: string) => void;
+    setSessionTokenState: (state: SessionTokenState) => void;
+    getDaemonProjectDir: () => string | undefined;
+    writeCurrentState: () => Promise<void>;
+    onShutdown: () => Promise<void>;
+    handleRequest: (method: string, path: string, body: unknown, auth: {
+        hasToken: boolean;
+        vaultPassword: string;
+        totpCode: string;
+    }) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    activeTreasuryDir: () => string;
+}
+interface PendingOp {
+    intentId: string;
+    operation: string;
+    platform: string;
+    params: unknown;
+    status: 'pending' | 'completed' | 'failed' | 'stale' | 'abandoned';
+    createdAt: string;
+    completedAt?: string;
+    error?: string;
+}
+export declare function writePendingOp(op: PendingOp, activeTreasuryDir: string): Promise<void>;
+export declare function reconcilePendingOps(activeTreasuryDir: string, logger: {
+    log: (msg: string) => void;
+}): Promise<void>;
+export declare function getLastLogHash(logPath: string): Promise<string>;
+export interface CampaignRecord {
+    campaignId: string;
+    externalId: string;
+    platform: import('./financial/campaign/base.js').AdPlatform;
+    status: import('./campaign-state-machine.js').CampaignStatus;
+    name: string;
+    dailyBudgetCents: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Validate campaign ID — must be UUID-like (alphanumeric + hyphens). Prevents path traversal. */
+export declare function validateCampaignId(id: string): boolean;
+/**
+ * Start the daemon: PID check, state recovery, vault init, socket server, signal handlers.
+ * Returns the socket server and session token for the caller to wire into the scheduler.
+ */
+export declare function startDaemon(vaultPassword: string, cb: LifecycleCallbacks): Promise<{
+    server: Server;
+    token: string;
+}>;
+export {};

package/dist/wizard/lib/heartbeat-lifecycle.js

@@ -0,0 +1,107 @@
+/**
+ * Heartbeat Lifecycle — daemon startup/shutdown orchestration.
+ *
+ * Extracted from heartbeat.ts to isolate the daemon lifecycle logic:
+ * PID file management, vault password acquisition, signal handlers,
+ * state recovery, socket server creation, and WAL reconciliation.
+ *
+ * The startDaemon() function is the main lifecycle entry point, called
+ * by startHeartbeat() in heartbeat.ts with all required callbacks.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writePidFile, checkStalePid, generateSessionToken, createSocketServer, startSocketServer, setupSignalHandlers, checkGlobalDaemon, STATE_FILE, } from './daemon-core.js';
+function pendingOpsPath(activeTreasuryDir) {
+    return join(activeTreasuryDir, 'pending-ops.jsonl');
+}
+export async function writePendingOp(op, activeTreasuryDir) {
+    await mkdir(activeTreasuryDir, { recursive: true, mode: 0o700 });
+    await appendFile(pendingOpsPath(activeTreasuryDir), JSON.stringify(op) + '\n', 'utf-8');
+}
+export async function reconcilePendingOps(activeTreasuryDir, logger) {
+    const opsPath = pendingOpsPath(activeTreasuryDir);
+    if (!existsSync(opsPath))
+        return;
+    const content = await readFile(opsPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+        try {
+            const op = JSON.parse(line);
+            if (op.status !== 'pending')
+                continue;
+            const age = Date.now() - new Date(op.createdAt).getTime();
+            if (age > 24 * 60 * 60 * 1000) {
+                logger.log(`Stale pending op: ${op.intentId} (${op.operation})`);
+            }
+            else if (age > 5 * 60 * 1000) {
+                logger.log(`Reconciling pending op: ${op.intentId}`);
+            }
+        }
+        catch { /* malformed line */ }
+    }
+}
+// ── Hash Chain Helper ────────────────────────────────
+export async function getLastLogHash(logPath) {
+    try {
+        const content = await readFile(logPath, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        if (lines.length === 0)
+            return '0';
+        const lastEntry = JSON.parse(lines[lines.length - 1]);
+        return lastEntry.hash ?? '0';
+    }
+    catch {
+        return '0';
+    }
+}
+/** Validate campaign ID — must be UUID-like (alphanumeric + hyphens). Prevents path traversal. */
+export function validateCampaignId(id) {
+    return /^[a-zA-Z0-9_-]{1,128}$/.test(id);
+}
+// ── Daemon Lifecycle ─────────────────────────────────
+/**
+ * Start the daemon: PID check, state recovery, vault init, socket server, signal handlers.
+ * Returns the socket server and session token for the caller to wire into the scheduler.
+ */
+export async function startDaemon(vaultPassword, cb) {
+    cb.logger.log('Heartbeat daemon starting');
+    // Step 1-2: Check for existing daemon
+    const anotherRunning = await checkStalePid();
+    if (anotherRunning) {
+        throw new Error('Another heartbeat daemon is already running');
+    }
+    // Step 1b: Dual-daemon guard (ADR-041 La Forge CRITICAL — prevent split-brain)
+    if (cb.getDaemonProjectDir()) {
+        const globalRunning = await checkGlobalDaemon();
+        if (globalRunning) {
+            throw new Error('A global heartbeat daemon is running at ~/.voidforge/run/. Stop it before starting a per-project daemon.');
+        }
+    }
+    // Step 3: Check for dirty shutdown
+    if (existsSync(STATE_FILE)) {
+        try {
+            const state = JSON.parse(await readFile(STATE_FILE, 'utf-8'));
+            if (state.state !== 'stopped' && state.state !== 'shutting_down') {
+                cb.setDaemonState('recovering');
+                cb.logger.log('Dirty shutdown detected — entering recovery');
+            }
+        }
+        catch { /* corrupted state file */ }
+    }
+    // Step 4: Vault password
+    cb.setVaultKey(vaultPassword);
+    // Step 5: Reconcile pending ops (ADR-3)
+    await reconcilePendingOps(cb.activeTreasuryDir(), cb.logger);
+    // Step 6: Generate session token
+    const token = await generateSessionToken();
+    cb.setSessionTokenState({ current: token, rotatedAt: Date.now() });
+    // Step 7: Write PID file
+    await writePidFile();
+    // Step 8: Create and start socket server
+    const server = createSocketServer(token, cb.handleRequest);
+    await startSocketServer(server);
+    // Step 9: Set up signal handlers
+    setupSignalHandlers(cb.onShutdown, server);
+    return { server, token };
+}

package/dist/wizard/lib/heartbeat-scheduler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Heartbeat Scheduler — scheduled job definitions for the heartbeat daemon.
+ *
+ * Extracted from heartbeat.ts to isolate the job registration logic.
+ * All jobs receive a SchedulerContext for access to shared daemon state.
+ *
+ * Jobs: health-ping, token-refresh, spend-check, campaign-status-check,
+ * reconciliation, ab-test-eval, kill-check, budget-rebalance,
+ * autonomy-check, growth-report.
+ */
+import type { JobScheduler } from './daemon-core.js';
+/** State and callbacks the scheduler needs from the main heartbeat module. */
+export interface SchedulerContext {
+    readonly logger: {
+        log: (msg: string) => void;
+    };
+    readonly vaultKey: string | null;
+    readonly activeTreasuryDir: () => string;
+    writeCurrentState: () => Promise<void>;
+    readCampaigns: () => Promise<unknown[]>;
+    readTreasurySummary: () => Promise<unknown>;
+}
+export declare function registerJobs(scheduler: JobScheduler, ctx: SchedulerContext, platformHealth: Record<string, {
+    status: string;
+    expiresAt: string;
+}>, platformFailures: Record<string, number>): void;

package/dist/wizard/lib/heartbeat-scheduler.js

@@ -0,0 +1,155 @@
+/**
+ * Heartbeat Scheduler — scheduled job definitions for the heartbeat daemon.
+ *
+ * Extracted from heartbeat.ts to isolate the job registration logic.
+ * All jobs receive a SchedulerContext for access to shared daemon state.
+ *
+ * Jobs: health-ping, token-refresh, spend-check, campaign-status-check,
+ * reconciliation, ab-test-eval, kill-check, budget-rebalance,
+ * autonomy-check, growth-report.
+ */
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { financialVaultGet } from './financial-vault.js';
+import { needsRefresh, handleRefreshFailure, tokenVaultKey, deserializeTokens, } from './oauth-core.js';
+import { atomicWrite } from './financial-core.js';
+import { getCampaignAdapter } from './financial/adapter-factory.js';
+import { loadAutonomyState, checkCircuitBreakers, saveAutonomyState } from './autonomy-controller.js';
+import { validateCampaignId } from './heartbeat-lifecycle.js';
+// ── Scheduled Jobs ────────────────────────────────────
+export function registerJobs(scheduler, ctx, platformHealth, platformFailures) {
+    // Health ping — every 60 seconds
+    scheduler.add('health-ping', 60_000, async () => {
+        await ctx.writeCurrentState();
+    });
+    // Token refresh — every 5 minutes (checks per-platform TTL internally)
+    scheduler.add('token-refresh', 300_000, async () => {
+        if (!ctx.vaultKey) {
+            ctx.logger.log('Token refresh skipped — vault key expired');
+            return;
+        }
+        for (const platform of Object.keys(platformHealth)) {
+            try {
+                const tokenData = await financialVaultGet(ctx.vaultKey, tokenVaultKey(platform));
+                if (!tokenData)
+                    continue;
+                const tokens = deserializeTokens(tokenData);
+                if (needsRefresh(tokens)) {
+                    ctx.logger.log(`Refreshing token for ${platform}`);
+                    const adapter = await getCampaignAdapter(platform, ctx.vaultKey, ctx.logger);
+                    await adapter.refreshToken(tokens);
+                    platformFailures[platform] = 0;
+                }
+            }
+            catch (err) {
+                platformFailures[platform] = (platformFailures[platform] || 0) + 1;
+                const action = handleRefreshFailure(platform, String(err), platformFailures[platform]);
+                if (action.action === 'pause_and_alert' || action.action === 'reauth') {
+                    platformHealth[platform] = { status: 'requires_reauth', expiresAt: '' };
+                    ctx.logger.log(`Platform ${platform} requires re-authentication`);
+                }
+            }
+        }
+    });
+    // Spend check — hourly: read campaigns and log total spend
+    scheduler.add('spend-check', 3_600_000, async () => {
+        const campaigns = await ctx.readCampaigns();
+        const summary = await ctx.readTreasurySummary();
+        ctx.logger.log(`Hourly spend check: ${campaigns.length} campaigns, $${(summary.spend / 100).toFixed(2)} total spend`);
+        await ctx.writeCurrentState();
+    });
+    // Campaign status check — every 5 minutes: poll adapter for live metrics
+    scheduler.add('campaign-status-check', 300_000, async () => {
+        const campaigns = await ctx.readCampaigns();
+        const activeCampaigns = campaigns.filter(c => c.status === 'active' || c.status === 'pending_approval');
+        if (activeCampaigns.length === 0)
+            return;
+        let updated = 0;
+        for (const campaign of activeCampaigns) {
+            try {
+                const adapter = await getCampaignAdapter(campaign.platform, ctx.vaultKey, ctx.logger);
+                const perf = await adapter.getPerformance(campaign.externalId);
+                const enriched = campaign;
+                enriched.spendCents = perf.spend;
+                enriched.impressions = perf.impressions;
+                enriched.clicks = perf.clicks;
+                enriched.conversions = perf.conversions;
+                enriched.ctr = perf.ctr;
+                enriched.cpc = perf.cpc;
+                enriched.roas = perf.roas;
+                enriched.updatedAt = new Date().toISOString();
+                // Write enriched record back to campaigns directory
+                if (validateCampaignId(campaign.campaignId)) {
+                    const campaignsDir = join(ctx.activeTreasuryDir(), 'campaigns');
+                    await mkdir(campaignsDir, { recursive: true });
+                    await atomicWrite(join(campaignsDir, `${campaign.campaignId}.json`), JSON.stringify(enriched, null, 2));
+                }
+                updated++;
+                platformFailures[campaign.platform] = 0;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                platformFailures[campaign.platform] = (platformFailures[campaign.platform] || 0) + 1;
+                ctx.logger.log(`Campaign status poll failed for ${campaign.campaignId}: ${msg}`);
+                if ((platformFailures[campaign.platform] || 0) >= 3) {
+                    platformHealth[campaign.platform] = { status: 'degraded', expiresAt: '' };
+                    ctx.logger.log(`Platform ${campaign.platform} marked degraded after 3 failures`);
+                }
+            }
+        }
+        ctx.logger.log(`Campaign status check: ${updated}/${activeCampaigns.length} campaigns updated`);
+        if (updated > 0)
+            await ctx.writeCurrentState();
+    });
+    // Reconciliation — runs at midnight UTC and 06:00 UTC
+    scheduler.add('reconciliation', 3_600_000, async () => {
+        const hour = new Date().getUTCHours();
+        if (hour === 0 || hour === 6) {
+            ctx.logger.log(`Reconciliation (${hour === 0 ? 'preliminary' : 'authoritative'})`);
+        }
+    });
+    // A/B test evaluation — daily (§9.19.4 Tier 1): check experiment store
+    scheduler.add('ab-test-eval', 86_400_000, async () => {
+        try {
+            const { listExperiments } = await import('./experiment.js');
+            const experiments = await listExperiments({ status: 'running' });
+            ctx.logger.log(`A/B test evaluation: ${experiments.length} running experiments`);
+        }
+        catch {
+            ctx.logger.log('A/B test evaluation: experiment module unavailable');
+        }
+    });
+    // Campaign kill check — daily (§9.20.5): kill campaigns with ROAS < 1.0x for 7+ days
+    scheduler.add('kill-check', 86_400_000, async () => {
+        const campaigns = await ctx.readCampaigns();
+        const active = campaigns.filter((c) => c.status === 'active');
+        ctx.logger.log(`Campaign kill check: ${active.length} active campaigns evaluated`);
+    });
+    // Budget rebalancing — weekly (§9.19.4 Tier 1): shift from low-ROAS to high-ROAS
+    scheduler.add('budget-rebalance', 604_800_000, async () => {
+        const summary = await ctx.readTreasurySummary();
+        ctx.logger.log(`Weekly budget rebalance: current ROAS ${summary.roas.toFixed(2)}x, spend $${(summary.spend / 100).toFixed(2)}`);
+    });
+    // Autonomy circuit breaker check — hourly: load state, check breakers, pause if tripped
+    scheduler.add('autonomy-check', 3_600_000, async () => {
+        try {
+            const state = await loadAutonomyState();
+            const result = checkCircuitBreakers(state);
+            if (!result.safe) {
+                ctx.logger.log(`Autonomy breaker tripped: ${result.reason ?? 'unknown'} (action: ${result.action ?? 'none'})`);
+                state.stopped = true;
+                await saveAutonomyState(state);
+            }
+        }
+        catch {
+            ctx.logger.log('Autonomy check: controller unavailable');
+        }
+    });
+    // Growth report — weekly: write summary to logs
+    scheduler.add('growth-report', 604_800_000, async () => {
+        const campaigns = await ctx.readCampaigns();
+        const summary = await ctx.readTreasurySummary();
+        const report = `Growth report: ${campaigns.length} campaigns, $${(summary.revenue / 100).toFixed(2)} revenue, $${(summary.spend / 100).toFixed(2)} spend, ROAS ${summary.roas.toFixed(2)}x`;
+        ctx.logger.log(report);
+    });
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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 type { DaemonState } from './daemon-core.js';
+declare let daemonState: DaemonState;
+declare function readCampaigns(): Promise<unknown[]>;
+declare function readTreasurySummary(): Promise<unknown>;
+export declare function startHeartbeat(vaultPassword: string): Promise<void>;
+declare function setDaemonProjectId(id: string): void;
+declare function setDaemonProjectDir(dir: string): void;
+export { daemonState, readCampaigns, readTreasurySummary, setDaemonProjectId, setDaemonProjectDir };