thevoidforge 21.0.0

package/dist/wizard/lib/provisioners/vercel.js

@@ -0,0 +1,287 @@
+/**
+ * Vercel provisioner — creates a real Vercel project via API + generates vercel.json.
+ * v3.8.0: Links GitHub repo, sets env vars, polls deploy (ADR-015).
+ */
+import { writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { httpsPost, httpsGet, httpsDelete, safeJsonParse, slugify } from './http-client.js';
+import { recordResourcePending, recordResourceCreated } from '../provision-manifest.js';
+import { appendEnvSection } from '../env-writer.js';
+const DEPLOY_POLL_INTERVAL_MS = 5000;
+const DEPLOY_POLL_TIMEOUT_MS = 300_000; // 5 minutes
+export const vercelProvisioner = {
+    async validate(ctx) {
+        const errors = [];
+        if (!ctx.projectDir)
+            errors.push('Project directory is required');
+        if (!ctx.credentials['vercel-token'])
+            errors.push('Vercel API token is required');
+        return errors;
+    },
+    async provision(ctx, emit) {
+        const files = [];
+        const resources = [];
+        const outputs = {};
+        const token = ctx.credentials['vercel-token'];
+        const slug = slugify(ctx.projectName);
+        const framework = ctx.framework || 'next.js';
+        const headers = {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        };
+        // Step 1: Create Vercel project
+        emit({ step: 'vercel-project', status: 'started', message: 'Creating Vercel project' });
+        let projectId = '';
+        try {
+            await recordResourcePending(ctx.runId, 'vercel-project', slug, 'global');
+            // Only pass framework if it's a Vercel-recognized value — otherwise omit and let Vercel auto-detect
+            const vercelFrameworks = {
+                'next.js': 'nextjs',
+                'nuxt': 'nuxtjs',
+                'svelte': 'sveltekit',
+                'remix': 'remix',
+                'gatsby': 'gatsby',
+                'astro': 'astro',
+                'vite': 'vite',
+            };
+            const projectBody = { name: slug };
+            const vercelFw = vercelFrameworks[framework];
+            if (vercelFw)
+                projectBody.framework = vercelFw;
+            const body = JSON.stringify(projectBody);
+            const res = await httpsPost('api.vercel.com', '/v10/projects', headers, body);
+            if (res.status === 200 || res.status === 201) {
+                const data = safeJsonParse(res.body);
+                projectId = data?.id ?? '';
+                if (!projectId)
+                    throw new Error('Vercel returned no project ID');
+                resources.push({ type: 'vercel-project', id: projectId, region: 'global' });
+                await recordResourceCreated(ctx.runId, 'vercel-project', projectId, 'global');
+                outputs['VERCEL_PROJECT_ID'] = projectId;
+                outputs['VERCEL_PROJECT_NAME'] = data?.name ?? slug;
+                emit({ step: 'vercel-project', status: 'done', message: `Project "${data?.name}" created on Vercel` });
+            }
+            else if (res.status === 409) {
+                // Project already exists — fetch its ID for subsequent steps
+                try {
+                    const existingRes = await httpsGet('api.vercel.com', `/v10/projects/${slug}`, headers);
+                    if (existingRes.status === 200) {
+                        const existingData = safeJsonParse(existingRes.body);
+                        projectId = existingData?.id ?? '';
+                        if (projectId) {
+                            resources.push({ type: 'vercel-project', id: projectId, region: 'global' });
+                            await recordResourceCreated(ctx.runId, 'vercel-project', projectId, 'global');
+                            outputs['VERCEL_PROJECT_ID'] = projectId;
+                        }
+                    }
+                }
+                catch { /* fetch failed, proceed without ID */ }
+                outputs['VERCEL_PROJECT_NAME'] = slug;
+                emit({ step: 'vercel-project', status: 'done', message: `Project "${slug}" already exists on Vercel — will use existing`, detail: projectId ? `ID: ${projectId}` : 'Could not fetch project ID' });
+            }
+            else {
+                const errBody = safeJsonParse(res.body);
+                throw new Error(errBody?.error?.message || `Vercel API returned ${res.status}`);
+            }
+        }
+        catch (err) {
+            emit({ step: 'vercel-project', status: 'error', message: 'Failed to create Vercel project', detail: err.message });
+            return { success: false, resources, outputs, files, error: err.message };
+        }
+        // Step 2: Add custom domain if hostname provided
+        if (ctx.hostname && projectId) {
+            emit({ step: 'vercel-domain', status: 'started', message: `Adding domain ${ctx.hostname} to Vercel project` });
+            try {
+                const domainBody = JSON.stringify({ name: ctx.hostname });
+                const domainRes = await httpsPost('api.vercel.com', `/v10/projects/${projectId}/domains`, headers, domainBody);
+                if (domainRes.status === 200 || domainRes.status === 201) {
+                    outputs['VERCEL_DOMAIN'] = ctx.hostname;
+                    emit({ step: 'vercel-domain', status: 'done', message: `Domain "${ctx.hostname}" added to Vercel project` });
+                }
+                else if (domainRes.status === 409) {
+                    emit({ step: 'vercel-domain', status: 'done', message: `Domain "${ctx.hostname}" already configured on Vercel` });
+                    outputs['VERCEL_DOMAIN'] = ctx.hostname;
+                }
+                else {
+                    const errBody = safeJsonParse(domainRes.body);
+                    throw new Error(errBody?.error?.message || `Vercel domains API returned ${domainRes.status}`);
+                }
+            }
+            catch (err) {
+                emit({ step: 'vercel-domain', status: 'error', message: 'Failed to add domain to Vercel', detail: err.message });
+                // Non-fatal — DNS wiring will still work, user can add domain manually
+            }
+        }
+        else if (ctx.hostname && !projectId) {
+            emit({ step: 'vercel-domain', status: 'skipped', message: 'Cannot add domain — no project ID (existing project)' });
+        }
+        // Step 3: Generate vercel.json
+        emit({ step: 'vercel-config', status: 'started', message: 'Generating vercel.json' });
+        try {
+            const config = {
+                $schema: 'https://openapi.vercel.sh/vercel.json',
+            };
+            if (framework === 'express') {
+                config.builds = [{ src: 'dist/index.js', use: '@vercel/node' }];
+                config.routes = [{ src: '/(.*)', dest: 'dist/index.js' }];
+            }
+            await writeFile(join(ctx.projectDir, 'vercel.json'), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+            files.push('vercel.json');
+            emit({ step: 'vercel-config', status: 'done', message: 'Generated vercel.json' });
+        }
+        catch (err) {
+            emit({ step: 'vercel-config', status: 'error', message: 'Failed to write vercel.json', detail: err.message });
+            // Non-fatal — project was still created
+        }
+        // Step 4: Link GitHub repo (ADR-015 — auto-deploy on push)
+        const ghOwner = ctx.credentials['_github-owner'];
+        const ghRepo = ctx.credentials['_github-repo-name'];
+        if (projectId && ghOwner && ghRepo) {
+            emit({ step: 'vercel-link', status: 'started', message: `Linking GitHub repo ${ghOwner}/${ghRepo} to Vercel` });
+            try {
+                const linkBody = JSON.stringify({
+                    type: 'github',
+                    repo: `${ghOwner}/${ghRepo}`,
+                    sourceless: false,
+                    productionBranch: 'main',
+                });
+                const linkRes = await httpsPost('api.vercel.com', `/v10/projects/${projectId}/link`, headers, linkBody);
+                if (linkRes.status === 200 || linkRes.status === 201) {
+                    emit({ step: 'vercel-link', status: 'done', message: `GitHub repo linked — auto-deploy enabled on push to main` });
+                }
+                else {
+                    const errBody = safeJsonParse(linkRes.body);
+                    emit({ step: 'vercel-link', status: 'error', message: 'Failed to link GitHub repo', detail: errBody?.error?.message || `API returned ${linkRes.status}` });
+                }
+            }
+            catch (err) {
+                emit({ step: 'vercel-link', status: 'error', message: 'Failed to link GitHub repo', detail: err.message });
+                // Non-fatal — user can link manually
+            }
+        }
+        // Step 5: Set environment variables
+        if (projectId) {
+            emit({ step: 'vercel-envvars', status: 'started', message: 'Setting environment variables' });
+            try {
+                // Collect env vars from .env file (skip comments, empty lines, and VoidForge metadata)
+                let envContent = '';
+                try {
+                    envContent = await readFile(join(ctx.projectDir, '.env'), 'utf-8');
+                }
+                catch { /* no .env */ }
+                const envVars = envContent
+                    .split('\n')
+                    .filter(line => line.includes('=') && !line.startsWith('#'))
+                    .map(line => {
+                    const idx = line.indexOf('=');
+                    return { key: line.slice(0, idx).trim(), value: line.slice(idx + 1).trim().replace(/^["']|["']$/g, '') };
+                })
+                    .filter(v => v.key && !v.key.startsWith('VERCEL_')); // Don't set Vercel metadata as env vars
+                if (envVars.length > 0) {
+                    const envBody = JSON.stringify(envVars.map(v => ({
+                        key: v.key,
+                        value: v.value,
+                        type: 'encrypted',
+                        target: ['production', 'preview', 'development'],
+                    })));
+                    const envRes = await httpsPost('api.vercel.com', `/v10/projects/${projectId}/env`, headers, envBody);
+                    if (envRes.status === 200 || envRes.status === 201) {
+                        emit({ step: 'vercel-envvars', status: 'done', message: `Set ${envVars.length} environment variables` });
+                    }
+                    else {
+                        emit({ step: 'vercel-envvars', status: 'error', message: 'Failed to set env vars', detail: `API returned ${envRes.status}` });
+                    }
+                }
+                else {
+                    emit({ step: 'vercel-envvars', status: 'done', message: 'No environment variables to set' });
+                }
+            }
+            catch (err) {
+                emit({ step: 'vercel-envvars', status: 'error', message: 'Failed to set env vars', detail: err.message });
+            }
+        }
+        // Step 6: Poll for deployment (triggered by GitHub push, ADR-015)
+        if (projectId && ghOwner && ghRepo) {
+            emit({ step: 'vercel-deploy', status: 'started', message: 'Waiting for deployment (triggered by git push)...' });
+            try {
+                const start = Date.now();
+                let deployUrl = '';
+                while (Date.now() - start < DEPLOY_POLL_TIMEOUT_MS) {
+                    await new Promise(r => setTimeout(r, DEPLOY_POLL_INTERVAL_MS));
+                    if (ctx.abortSignal?.aborted)
+                        break;
+                    const depRes = await httpsGet('api.vercel.com', `/v6/deployments?projectId=${projectId}&limit=1`, headers);
+                    if (depRes.status !== 200)
+                        continue;
+                    const depData = safeJsonParse(depRes.body);
+                    const latest = depData?.deployments?.[0];
+                    if (!latest)
+                        continue;
+                    if (latest.readyState === 'READY' || latest.state === 'READY') {
+                        deployUrl = latest.url ? `https://${latest.url}` : '';
+                        break;
+                    }
+                    if (latest.readyState === 'ERROR' || latest.state === 'ERROR') {
+                        emit({ step: 'vercel-deploy', status: 'error', message: 'Deployment failed on Vercel', detail: 'Check the Vercel dashboard for build logs' });
+                        break;
+                    }
+                    const elapsed = Math.round((Date.now() - start) / 1000);
+                    if (elapsed % 15 === 0) {
+                        emit({ step: 'vercel-deploy', status: 'started', message: `Deployment status: ${latest.readyState || latest.state || 'building'}... (${elapsed}s)` });
+                    }
+                }
+                if (deployUrl) {
+                    outputs['DEPLOY_URL'] = deployUrl;
+                    emit({ step: 'vercel-deploy', status: 'done', message: `Live at ${deployUrl}` });
+                }
+                else if (!ctx.abortSignal?.aborted) {
+                    emit({ step: 'vercel-deploy', status: 'error', message: 'Deployment polling timed out — check Vercel dashboard', detail: 'The deployment may still be building' });
+                }
+            }
+            catch (err) {
+                emit({ step: 'vercel-deploy', status: 'error', message: 'Failed to poll deployment', detail: err.message });
+            }
+        }
+        else if (!ghOwner || !ghRepo) {
+            emit({ step: 'vercel-deploy', status: 'skipped', message: 'No GitHub repo linked — deploy manually with: npx vercel deploy' });
+        }
+        // Step 7: Write .env
+        emit({ step: 'vercel-env', status: 'started', message: 'Writing Vercel config to .env' });
+        try {
+            const envLines = [
+                `# VoidForge Vercel — generated ${new Date().toISOString()}`,
+                `VERCEL_PROJECT_NAME=${outputs['VERCEL_PROJECT_NAME'] || slug}`,
+            ];
+            if (outputs['VERCEL_PROJECT_ID']) {
+                envLines.push(`VERCEL_PROJECT_ID=${outputs['VERCEL_PROJECT_ID']}`);
+            }
+            if (outputs['DEPLOY_URL']) {
+                envLines.push(`DEPLOY_URL=${outputs['DEPLOY_URL']}`);
+            }
+            envLines.push('# Auto-deploys on push to main');
+            await appendEnvSection(ctx.projectDir, envLines);
+            emit({ step: 'vercel-env', status: 'done', message: 'Vercel config written to .env' });
+        }
+        catch (err) {
+            emit({ step: 'vercel-env', status: 'error', message: 'Failed to write .env', detail: err.message });
+        }
+        return { success: true, resources, outputs, files };
+    },
+    async cleanup(resources, credentials) {
+        const token = credentials['vercel-token'];
+        if (!token)
+            return;
+        for (const resource of resources) {
+            if (resource.type === 'vercel-project') {
+                try {
+                    await httpsDelete('api.vercel.com', `/v9/projects/${resource.id}`, {
+                        'Authorization': `Bearer ${token}`,
+                    });
+                }
+                catch (err) {
+                    console.error(`Failed to delete Vercel project ${resource.id}:`, err.message);
+                }
+            }
+        }
+    },
+};

package/dist/wizard/lib/pty-manager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PTY Manager — spawns and manages real pseudo-terminal processes.
+ * Uses node-pty (same lib as VS Code, Gitpod, GitHub Codespaces).
+ * Each PTY is a real shell with full capabilities.
+ *
+ * Haku moves between worlds seamlessly.
+ */
+export interface PtySession {
+    id: string;
+    projectName: string;
+    projectDir: string;
+    label: string;
+    username: string;
+    createdAt: number;
+    lastActivityAt: number;
+    cols: number;
+    rows: number;
+}
+/**
+ * Spawn a new PTY session.
+ * @param projectDir — directory to cd into
+ * @param projectName — human-readable project name
+ * @param label — tab label (e.g., "Claude Code", "Shell", "SSH: prod")
+ * @param initialCommand — optional command to auto-run after shell starts
+ * @param cols — terminal columns (default 120)
+ * @param rows — terminal rows (default 30)
+ */
+export declare function createSession(projectDir: string, projectName: string, label: string, initialCommand?: string, cols?: number, rows?: number, username?: string): Promise<PtySession>;
+/** Write input (keystrokes) to a PTY session. */
+export declare function writeToSession(sessionId: string, data: string): void;
+/** Subscribe to PTY output. Returns an unsubscribe function. */
+export declare function onSessionData(sessionId: string, listener: (data: string) => void): () => void;
+/** Resize a PTY session. */
+export declare function resizeSession(sessionId: string, cols: number, rows: number): void;
+/** Kill a PTY session. */
+export declare function killSession(sessionId: string): void;
+/** List all active sessions. */
+export declare function listSessions(): PtySession[];
+/** Kill all sessions (graceful shutdown). */
+export declare function killAllSessions(): void;
+/** Get session count. */
+export declare function sessionCount(): number;

package/dist/wizard/lib/pty-manager.js

@@ -0,0 +1,231 @@
+/**
+ * PTY Manager — spawns and manages real pseudo-terminal processes.
+ * Uses node-pty (same lib as VS Code, Gitpod, GitHub Codespaces).
+ * Each PTY is a real shell with full capabilities.
+ *
+ * Haku moves between worlds seamlessly.
+ */
+import { randomUUID } from 'node:crypto';
+import { isRemoteMode } from './tower-auth.js';
+import { audit } from './audit-log.js';
+// node-pty is a native module — dynamic import to handle missing installs gracefully
+let pty = null;
+async function loadPty() {
+    if (pty)
+        return pty;
+    try {
+        pty = await import('node-pty');
+        return pty;
+    }
+    catch {
+        throw new Error('node-pty is not installed. Run: npm install node-pty');
+    }
+}
+const sessions = new Map();
+const MAX_SESSIONS_LOCAL = 5;
+const MAX_SESSIONS_REMOTE = 20; // 5 per project, 20 total across all projects
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+// SEC-004/QA-003: Whitelist of allowed initial commands — prevent arbitrary command injection
+const ALLOWED_INITIAL_COMMANDS = ['claude', 'claude --dangerously-skip-permissions', 'bash', 'zsh', 'sh', 'npm run dev', 'npm start', 'npm test'];
+// SEC-013: Safe environment keys — no credential leakage into PTY sessions
+// ANTHROPIC_API_KEY included only in local mode (user's own key).
+// In remote mode, operator's API key must NOT leak to deployer-role users.
+// Includes TMPDIR/SSH_AUTH_SOCK for tool compatibility.
+const BASE_SAFE_ENV_KEYS = ['PATH', 'HOME', 'SHELL', 'USER', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM_PROGRAM', 'EDITOR', 'VISUAL', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'NVM_DIR', 'NVM_BIN', 'NVM_INC', 'TMPDIR', 'TEMP', 'SSH_AUTH_SOCK', 'COLORTERM'];
+// FLOW-R2-007: Only pass ANTHROPIC_API_KEY in local mode
+function getSafeEnvKeys() {
+    if (isRemoteMode())
+        return BASE_SAFE_ENV_KEYS;
+    return [...BASE_SAFE_ENV_KEYS, 'ANTHROPIC_API_KEY'];
+}
+function resetIdleTimer(session) {
+    if (session.idleTimer)
+        clearTimeout(session.idleTimer);
+    session.idleTimer = setTimeout(() => {
+        console.log(`  PTY session ${session.id} idle for 30 min — killing`);
+        killSession(session.id);
+    }, IDLE_TIMEOUT_MS);
+}
+/**
+ * Spawn a new PTY session.
+ * @param projectDir — directory to cd into
+ * @param projectName — human-readable project name
+ * @param label — tab label (e.g., "Claude Code", "Shell", "SSH: prod")
+ * @param initialCommand — optional command to auto-run after shell starts
+ * @param cols — terminal columns (default 120)
+ * @param rows — terminal rows (default 30)
+ */
+export async function createSession(projectDir, projectName, label, initialCommand, cols = 120, rows = 30, username = '') {
+    const maxSessions = isRemoteMode() ? MAX_SESSIONS_REMOTE : MAX_SESSIONS_LOCAL;
+    if (sessions.size >= maxSessions) {
+        // QA-007/UX-018: Prefer killing sessions with no connected listeners (disconnected tabs)
+        const disconnected = [...sessions.values()].filter(s => s.onData.size === 0);
+        if (disconnected.length > 0) {
+            killSession(disconnected.sort((a, b) => a.lastActivityAt - b.lastActivityAt)[0].id);
+        }
+        else {
+            // All sessions have active listeners — reject instead of killing active work
+            throw new Error(`Maximum ${maxSessions} concurrent terminal sessions. Close a tab first.`);
+        }
+    }
+    const nodePty = await loadPty();
+    const shell = process.env['SHELL'] || '/bin/zsh';
+    const id = randomUUID();
+    // SEC-013: Build clean environment — no credential leakage into PTY
+    const safeEnv = {};
+    for (const key of getSafeEnvKeys()) {
+        if (process.env[key])
+            safeEnv[key] = process.env[key];
+    }
+    safeEnv['TERM'] = 'xterm-256color';
+    safeEnv['VOIDFORGE_SESSION'] = id;
+    // QA-R2-010 + QA-R3-002: Clamp cols/rows BEFORE spawnOptions construction
+    cols = Math.max(1, Math.min(500, Math.floor(cols)));
+    rows = Math.max(1, Math.min(200, Math.floor(rows)));
+    // Remote mode: spawn as forge-user for sandboxing (Layer 4)
+    const spawnOptions = {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd: projectDir,
+        env: safeEnv,
+    };
+    if (isRemoteMode()) {
+        // In remote mode, PTY spawns as forge-user (non-root sandboxing)
+        // The uid/gid would be set here in production: spawnOptions.uid = forgeUserUid;
+        // For scaffold/spec purposes, we document the intent
+        safeEnv['VOIDFORGE_REMOTE'] = '1';
+    }
+    const ptyProcess = nodePty.spawn(shell, [], spawnOptions);
+    const session = {
+        id,
+        projectName,
+        projectDir,
+        label,
+        username,
+        createdAt: Date.now(),
+        lastActivityAt: Date.now(),
+        cols,
+        rows,
+        process: ptyProcess,
+        onData: new Set(),
+        idleTimer: null,
+    };
+    // Forward PTY output to all listeners
+    ptyProcess.onData((data) => {
+        session.lastActivityAt = Date.now();
+        resetIdleTimer(session);
+        for (const listener of session.onData) {
+            try {
+                listener(data);
+            }
+            catch { /* listener error, ignore */ }
+        }
+    });
+    // Handle PTY exit
+    ptyProcess.onExit(({ exitCode }) => {
+        console.log(`  PTY session ${id} exited (code ${exitCode})`);
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        sessions.delete(id);
+        // Audit: log terminal end in remote mode
+        if (isRemoteMode()) {
+            audit('terminal_end', '', session.username, { sessionId: id, exitCode }).catch(() => { });
+        }
+    });
+    sessions.set(id, session);
+    resetIdleTimer(session);
+    // Audit: log terminal start in remote mode
+    if (isRemoteMode()) {
+        audit('terminal_start', '', username, { sessionId: id, project: projectName, label }).catch(() => { });
+    }
+    // SEC-004/QA-003: Validate initial command against whitelist
+    if (initialCommand && !ALLOWED_INITIAL_COMMANDS.includes(initialCommand)) {
+        initialCommand = undefined;
+    }
+    // Auto-run initial command after a short delay (let shell init complete)
+    if (initialCommand) {
+        setTimeout(() => {
+            if (sessions.has(id)) {
+                ptyProcess.write(initialCommand + '\r');
+            }
+        }, 500);
+    }
+    return {
+        id: session.id,
+        projectName: session.projectName,
+        projectDir: session.projectDir,
+        label: session.label,
+        username: session.username,
+        createdAt: session.createdAt,
+        lastActivityAt: session.lastActivityAt,
+        cols: session.cols,
+        rows: session.rows,
+    };
+}
+/** Write input (keystrokes) to a PTY session. */
+export function writeToSession(sessionId, data) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        throw new Error(`Session not found: ${sessionId}`);
+    session.lastActivityAt = Date.now();
+    resetIdleTimer(session);
+    session.process.write(data);
+}
+/** Subscribe to PTY output. Returns an unsubscribe function. */
+export function onSessionData(sessionId, listener) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        throw new Error(`Session not found: ${sessionId}`);
+    session.onData.add(listener);
+    return () => { session.onData.delete(listener); };
+}
+/** Resize a PTY session. */
+export function resizeSession(sessionId, cols, rows) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return;
+    // QA-016/SEC-007: Clamp resize values to sane bounds
+    cols = Math.max(1, Math.min(500, Math.floor(cols)));
+    rows = Math.max(1, Math.min(200, Math.floor(rows)));
+    session.cols = cols;
+    session.rows = rows;
+    session.process.resize(cols, rows);
+}
+/** Kill a PTY session. */
+export function killSession(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return;
+    if (session.idleTimer)
+        clearTimeout(session.idleTimer);
+    try {
+        session.process.kill();
+    }
+    catch { /* already dead */ }
+    sessions.delete(sessionId);
+}
+/** List all active sessions. */
+export function listSessions() {
+    return [...sessions.values()].map((s) => ({
+        id: s.id,
+        projectName: s.projectName,
+        projectDir: s.projectDir,
+        label: s.label,
+        username: s.username,
+        createdAt: s.createdAt,
+        lastActivityAt: s.lastActivityAt,
+        cols: s.cols,
+        rows: s.rows,
+    }));
+}
+/** Kill all sessions (graceful shutdown). */
+export function killAllSessions() {
+    for (const id of sessions.keys()) {
+        killSession(id);
+    }
+}
+/** Get session count. */
+export function sessionCount() {
+    return sessions.size;
+}

package/dist/wizard/lib/rate-limiter-core.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Rate limiter core — re-exports from the outbound-rate-limiter pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { OutboundRateLimiter, getLimiter } from './patterns/outbound-rate-limiter.js';

package/dist/wizard/lib/rate-limiter-core.js

@@ -0,0 +1,5 @@
+/**
+ * Rate limiter core — re-exports from the outbound-rate-limiter pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { OutboundRateLimiter, getLimiter } from './patterns/outbound-rate-limiter.js';

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

@@ -0,0 +1,43 @@
+/**
+ * Reconciliation Engine — Two-pass financial reconciliation (§9.17).
+ *
+ * Compares VoidForge's recorded spend/revenue against platform-reported values.
+ * Runs daily: preliminary at midnight UTC, authoritative at 06:00 UTC.
+ *
+ * PRD Reference: §9.4 (reconciliation), §9.9 (ReconciliationReport), §9.17 (two-pass)
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type Ratio = number & {
+    readonly __brand: 'Ratio';
+};
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+type RevenueSource = 'stripe' | 'paddle';
+interface ReconciliationReport {
+    id: string;
+    date: string;
+    type: 'preliminary' | 'final';
+    projectId: string;
+    spend: Array<{
+        platform: AdPlatform;
+        voidforgeRecorded: Cents;
+        platformReported: Cents;
+        discrepancy: Cents;
+        status: 'matched' | 'discrepancy' | 'unavailable';
+    }>;
+    revenue: Array<{
+        source: RevenueSource;
+        recorded: Cents;
+        reported: Cents;
+        discrepancy: Cents;
+        status: 'matched' | 'discrepancy' | 'unavailable';
+    }>;
+    netPosition: Cents;
+    blendedRoas: Ratio;
+    alerts: string[];
+}
+export declare function runReconciliation(projectId: string, date: string, type: 'preliminary' | 'final', platformSpendReports: Map<string, Cents>, // Platform-reported spend per platform
+revenueSourceReports: Map<string, Cents>): Promise<ReconciliationReport>;
+export declare function enforceCurrency(currency: string, platform: string): void;
+export type { ReconciliationReport };