paracosm 0.7.409 → 0.7.431

package/dist/cli/server-app.js

@@ -3,7 +3,10 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, statSync, unlinkS
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { normalizeSimulationConfig, applyDemoCaps } from './sim-config.js';
-import { runPairSimulations, runForkSimulation } from './pair-runner.js';
+import { runPairSimulations, runForkSimulation, runBatchSimulations } from './pair-runner.js';
+import { handleFetchSeed, handleCompileFromSeed, handleGenerateLeaders, } from './quickstart-routes.js';
+import { handleSimulate } from './simulate-route.js';
+import { compileScenario as compileScenarioReal } from '../engine/compiler/index.js';
 import { marsScenario } from '../engine/mars/index.js';
 import { lunarScenario } from '../engine/lunar/index.js';
 import { describeCustomScenarioSource, isRunnableScenarioPackage, loadDiskCustomScenarios, } from './custom-scenarios.js';
@@ -14,9 +17,13 @@ import { openSessionStore } from './session-store.js';
 import { generateSessionTitle } from './session-title.js';
 import { resolveServerMode } from './server/server-mode.js';
 import { createRunRecord, hashLeaderConfig } from './server/run-record.js';
+import { enrichRunRecordFromArtifact } from './server/enrich-run-record.js';
 import { createNoopRunHistoryStore } from './server/run-history-store.js';
+import { createSqliteRunHistoryStore } from './server/sqlite-run-history-store.js';
 import { handlePublicDemoRoute } from './server/routes/public-demo.js';
 import { handlePlatformApiRoute } from './server/routes/platform-api.js';
+import { validateForkSetupPreconditions } from './fork-preconditions.js';
+import { fetchSeedFromUrl } from './fetch-seed-url.js';
 function projectScenarioForClient(sc) {
     return {
         id: sc.id,
@@ -58,14 +65,167 @@ const PARACOSM_VERSION = (() => {
         return 'unknown';
     }
 })();
-function readBody(req) {
+class RequestBodyTooLargeError extends Error {
+    statusCode = 413;
+    constructor(maxBytes) {
+        super(`Request body too large. Maximum ${maxBytes} bytes.`);
+    }
+}
+function writeJsonError(res, error, fallbackStatus = 400) {
+    const status = error instanceof RequestBodyTooLargeError
+        ? error.statusCode
+        : fallbackStatus;
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: String(error) }));
+}
+function readBody(req, maxBytes) {
     return new Promise((resolveBody, reject) => {
         let body = '';
-        req.on('data', chunk => { body += chunk; });
-        req.on('end', () => resolveBody(body));
-        req.on('error', reject);
+        let receivedBytes = 0;
+        let settled = false;
+        let tooLarge = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        };
+        req.on('data', chunk => {
+            if (tooLarge)
+                return;
+            receivedBytes += Buffer.isBuffer(chunk)
+                ? chunk.length
+                : Buffer.byteLength(String(chunk));
+            if (receivedBytes > maxBytes) {
+                tooLarge = true;
+                body = '';
+                fail(new RequestBodyTooLargeError(maxBytes));
+                return;
+            }
+            body += chunk;
+        });
+        req.on('end', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolveBody(body);
+        });
+        req.on('error', fail);
     });
 }
+/**
+ * Resolve the production run-history store. SQLite by default at
+ * `${APP_DIR}/data/runs.db`; env override `PARACOSM_RUN_HISTORY_DB_PATH`.
+ * Set `PARACOSM_DISABLE_RUN_HISTORY=1` to fall back to the noop store
+ * (useful for ephemeral test environments and CLI smoke tests).
+ */
+function resolveRunHistoryStore(env) {
+    if (env.PARACOSM_DISABLE_RUN_HISTORY === '1') {
+        return createNoopRunHistoryStore();
+    }
+    const dbPath = env.PARACOSM_RUN_HISTORY_DB_PATH
+        ?? resolve(env.APP_DIR || '.', 'data', 'runs.db');
+    return createSqliteRunHistoryStore({ dbPath });
+}
+export function buildResultsPayloadFromEventBuffer(eventBuffer) {
+    const simEvents = eventBuffer
+        .filter(msg => msg.startsWith('event: sim\n') || msg.startsWith('event: result\n') || msg.startsWith('event: verdict\n') || msg.startsWith('event: complete\n'))
+        .map(msg => {
+        const lines = msg.split('\n');
+        const eventType = lines[0]?.replace('event: ', '') || '';
+        try {
+            return { event: eventType, data: JSON.parse(lines[1]?.replace('data: ', '') || '{}') };
+        }
+        catch {
+            return { event: eventType, data: {} };
+        }
+    });
+    const results = simEvents.filter(e => e.event === 'result').map(e => e.data);
+    const verdict = simEvents.find(e => e.event === 'verdict')?.data || null;
+    const isComplete = simEvents.some(e => e.event === 'complete');
+    const turns = simEvents.filter(e => e.event === 'sim' && e.data?.type === 'turn_start').length / 2;
+    // Reconstruct per-leader timelines from the sim event stream.
+    // Group every sim event by leader name, then bucket interesting
+    // payload types into typed lists so consumers can pull turn-by-turn
+    // crisis info, dept reports, decisions, forges, citations, reactions.
+    const byLeader = new Map();
+    const ensureLeader = (name) => {
+        if (!byLeader.has(name))
+            byLeader.set(name, { events: [], decisions: [], forges: [], citations: [], deptReports: [], agentReactions: [], promotions: [], systemsSnapshots: [] });
+        return byLeader.get(name);
+    };
+    // Track decision pending state so we can attach it to outcomes per event.
+    const pendingDecision = new Map();
+    for (const e of simEvents) {
+        if (e.event !== 'sim')
+            continue;
+        const inner = e.data;
+        const type = String(inner.type || '');
+        const leader = String(inner.leader || '');
+        if (!leader)
+            continue;
+        const slot = ensureLeader(leader);
+        const data = inner.data ?? {};
+        const turn = data.turn;
+        const time = data.time;
+        const eventIndex = data.eventIndex;
+        const pendKey = `${leader}-${turn}-${eventIndex ?? 0}`;
+        if (type === 'event_start') {
+            slot.events.push({ turn, time, eventIndex, title: data.title, category: data.category, description: data.description, emergent: data.emergent });
+        }
+        else if (type === 'turn_start' && data.title && data.title !== 'Director generating...') {
+            slot.events.push({ turn, time, title: data.title, category: data.category, description: data.crisis, emergent: data.emergent });
+        }
+        else if (type === 'decision_made') {
+            pendingDecision.set(pendKey, {
+                decision: data.decision,
+                rationale: data.rationale,
+                selectedPolicies: data.selectedPolicies,
+            });
+        }
+        else if (type === 'outcome') {
+            const p = pendingDecision.get(pendKey);
+            slot.decisions.push({ turn, time, eventIndex, ...p, outcome: data.outcome });
+            pendingDecision.delete(pendKey);
+        }
+        else if (type === 'specialist_done') {
+            const dept = data.department;
+            const cites = data.citationList || [];
+            slot.deptReports.push({
+                turn, time, eventIndex, department: dept,
+                summary: data.summary,
+                risks: data.risks,
+                recommendedActions: data.recommendedActions,
+                citations: cites.length,
+                toolCount: Array.isArray(data.forgedTools) ? data.forgedTools.length : 0,
+            });
+            for (const c of cites) {
+                slot.citations.push({ ...c, department: dept, turn });
+            }
+        }
+        else if (type === 'forge_attempt') {
+            slot.forges.push({ turn, time, eventIndex, ...data });
+        }
+        else if (type === 'agent_reactions') {
+            slot.agentReactions.push({ turn, time, reactions: data.reactions, totalReactions: data.totalReactions });
+        }
+        else if (type === 'promotion') {
+            slot.promotions.push({ ...data });
+        }
+        else if (type === 'systems_snapshot') {
+            slot.systemsSnapshots.push({ turn, time, ...data });
+        }
+    }
+    const leaders = [...byLeader.entries()].map(([name, slot]) => ({ name, ...slot }));
+    return {
+        results,
+        verdict,
+        isComplete,
+        turnsCompleted: Math.floor(turns),
+        totalEvents: simEvents.length,
+        leaders,
+    };
+}
 export function createMarsServer(options = {}) {
     const env = options.env ?? process.env;
     const serverMode = resolveServerMode(env);
@@ -77,6 +237,11 @@ export function createMarsServer(options = {}) {
     // env var or maxSimsPerDay option when hosting on your own infra.
     const maxSims = options.maxSimsPerDay ?? parseInt(env.RATE_LIMIT || '1', 10);
     const adminWrite = (env.ADMIN_WRITE || 'false').toLowerCase() === 'true';
+    const parsedMaxRequestBodyBytes = Number.parseInt(env.MAX_REQUEST_BODY_BYTES || '', 10);
+    const defaultMaxRequestBodyBytes = Number.isFinite(parsedMaxRequestBodyBytes)
+        ? parsedMaxRequestBodyBytes
+        : 5 * 1024 * 1024;
+    const maxRequestBodyBytes = options.maxRequestBodyBytes ?? defaultMaxRequestBodyBytes;
     const scenarioDir = options.scenarioDir ?? resolve(__dirname, '..', '..', 'scenarios');
     // Rate-limit state survives pm2 restarts via a JSON file alongside
     // the repo. Without this, a restart gives every blocked IP a full
@@ -197,7 +362,7 @@ export function createMarsServer(options = {}) {
             // routes just return 503.
             console.log(`  [sessions] Failed to open session store: ${err}`);
         }
-    const runHistoryStore = options.runHistoryStore ?? createNoopRunHistoryStore();
+    const runHistoryStore = options.runHistoryStore ?? resolveRunHistoryStore(env);
     // Coalesce disk writes so a burst of broadcasts (e.g. 50 forge_attempt
     // events during a turn) only triggers one persist call. 500ms debounce
     // is short enough that a crash loses at most a half-second of events
@@ -563,7 +728,17 @@ export function createMarsServer(options = {}) {
         if (handlePublicDemoRoute(serverMode, req, res, corsHeaders)) {
             return;
         }
-        if (await handlePlatformApiRoute(serverMode, req, res, { runHistoryStore, corsHeaders })) {
+        const runHistoryRoutesDefault = serverMode !== 'hosted_demo';
+        const runHistoryEnvFlag = (env.PARACOSM_ENABLE_RUN_HISTORY_ROUTES ?? '').toLowerCase();
+        const paracosmRoutesEnabled = runHistoryEnvFlag === 'true' ? true :
+            runHistoryEnvFlag === 'false' ? false :
+                runHistoryRoutesDefault;
+        if (await handlePlatformApiRoute(req, res, {
+            runHistoryStore,
+            corsHeaders,
+            paracosmRoutesEnabled,
+            scenarioLookup: (id) => customScenarioCatalog.get(id)?.scenario,
+        })) {
             return;
         }
         if (req.url === '/events') {
@@ -681,7 +856,7 @@ export function createMarsServer(options = {}) {
         // Store a scenario in memory (always allowed) or save to disk (requires ADMIN_WRITE)
         if (req.url === '/scenario/store' && req.method === 'POST') {
             try {
-                const { scenario: scenarioJson, saveToDisk } = JSON.parse(await readBody(req));
+                const { scenario: scenarioJson, saveToDisk } = JSON.parse(await readBody(req, maxRequestBodyBytes));
                 if (!scenarioJson || !scenarioJson.id) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'scenario with id required' }));
@@ -714,8 +889,7 @@ export function createMarsServer(options = {}) {
                 res.end(JSON.stringify({ stored: true, id: scenarioJson.id, savedToDisk, adminWrite, switchable }));
             }
             catch (err) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: String(err) }));
+                writeJsonError(res, err);
             }
             return;
         }
@@ -726,35 +900,166 @@ export function createMarsServer(options = {}) {
         // were /scenario/store'd but never compiled get a specific
         // "needs compile" error instead of the misleading "Unknown".
         if (req.url === '/scenario/switch' && req.method === 'POST') {
-            const { id } = JSON.parse(await readBody(req));
-            const entry = customScenarioCatalog.get(id);
-            if (entry) {
-                activeScenario = entry.scenario;
+            try {
+                const { id } = JSON.parse(await readBody(req, maxRequestBodyBytes));
+                const entry = customScenarioCatalog.get(id);
+                if (entry) {
+                    activeScenario = entry.scenario;
+                }
+                else if (memoryScenarios.has(id)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: `Scenario "${id}" is stored but not runnable — it's a source JSON (missing hooks, world, or canonical policies shape). Click Compile in the Scenario Editor to generate hooks before switching to it.`,
+                        storedButUnrunnable: true,
+                        id,
+                    }));
+                    return;
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Unknown scenario: ${id}. Use /compile or /scenario/store for custom scenarios.` }));
+                    return;
+                }
+                clearEventBuffer();
+                simConfig = null;
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+                res.end(JSON.stringify({ active: activeScenario.id, name: activeScenario.labels?.name }));
             }
-            else if (memoryScenarios.has(id)) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: `Scenario "${id}" is stored but not runnable — it's a source JSON (missing hooks, world, or canonical policies shape). Click Compile in the Scenario Editor to generate hooks before switching to it.`,
-                    storedButUnrunnable: true,
-                    id,
-                }));
-                return;
+            catch (err) {
+                writeJsonError(res, err);
             }
-            else {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: `Unknown scenario: ${id}. Use /compile or /scenario/store for custom scenarios.` }));
-                return;
+            return;
+        }
+        // Tier 5 Quickstart onboarding endpoints.
+        if (req.url?.startsWith('/api/quickstart/') && req.method === 'POST') {
+            try {
+                const body = JSON.parse(await readBody(req, maxRequestBodyBytes));
+                const quickstartDeps = {
+                    setActiveScenario: (sc) => {
+                        activeScenario = sc;
+                        // Quickstart-compiled scenarios reuse the 'compiled' source
+                        // tag; same post-compile semantics, no new source state
+                        // required.
+                        customScenarioCatalog.set(sc.id, { scenario: sc, source: 'compiled' });
+                    },
+                    getScenarioById: (id) => {
+                        if (id === activeScenario.id)
+                            return activeScenario;
+                        return customScenarioCatalog.get(id)?.scenario;
+                    },
+                    fetchSeedFromUrl,
+                    defaultProvider: 'anthropic',
+                    defaultModel: 'claude-sonnet-4-6',
+                };
+                if (req.url === '/api/quickstart/fetch-seed') {
+                    await handleFetchSeed(req, res, body, quickstartDeps);
+                    return;
+                }
+                if (req.url === '/api/quickstart/compile-from-seed') {
+                    await handleCompileFromSeed(req, res, body, quickstartDeps);
+                    return;
+                }
+                if (req.url === '/api/quickstart/generate-leaders') {
+                    await handleGenerateLeaders(req, res, body, quickstartDeps);
+                    return;
+                }
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: `Unknown quickstart route: ${req.url}` }));
+            }
+            catch (err) {
+                writeJsonError(res, err);
+            }
+            return;
+        }
+        // Tier 4 T4.2: POST /simulate one-shot HTTP endpoint. Gated behind
+        // `PARACOSM_ENABLE_SIMULATE_ENDPOINT=true` so the hosted demo's
+        // SSE path stays the default; self-hosted deployments flip the
+        // flag on to expose the sync request-response surface.
+        if (req.url === '/simulate' &&
+            req.method === 'POST' &&
+            (env.PARACOSM_ENABLE_SIMULATE_ENDPOINT || '').toLowerCase() === 'true') {
+            try {
+                const body = JSON.parse(await readBody(req, maxRequestBodyBytes));
+                const userApiKey = typeof req.headers['x-api-key'] === 'string' ? req.headers['x-api-key'] : undefined;
+                const userAnthropicKey = typeof req.headers['x-anthropic-key'] === 'string' ? req.headers['x-anthropic-key'] : undefined;
+                const hasUserKeys = !!(userApiKey || userAnthropicKey);
+                // Rate limit with BYO-key bypass, matching the /setup pattern.
+                // `.check()` alone is advisory; `.record()` consumes the slot.
+                if (rateLimiter && !hasUserKeys) {
+                    const ip = IpRateLimiter.getIp(req);
+                    const { allowed, remaining, limit } = rateLimiter.check(ip);
+                    if (!allowed) {
+                        res.writeHead(429, {
+                            ...corsHeaders,
+                            'Content-Type': 'application/json',
+                            'Retry-After': '86400',
+                            'X-RateLimit-Limit': String(limit),
+                            'X-RateLimit-Remaining': '0',
+                        });
+                        res.end(JSON.stringify({
+                            error: `Rate limit exceeded. Maximum ${limit} simulations per day. Set X-API-Key or X-Anthropic-Key to bypass.`,
+                            limit,
+                            remaining: 0,
+                        }));
+                        return;
+                    }
+                    rateLimiter.record(ip);
+                    console.log(`  [rate-limit] /simulate ${ip}: ${remaining - 1} remaining of ${limit}`);
+                }
+                else if (hasUserKeys) {
+                    console.log(`  [rate-limit] /simulate bypassed. BYO key present.`);
+                }
+                // Scope user-supplied API keys into the env for the duration of
+                // the simulate call. The orchestrator's downstream LLM providers
+                // read `process.env.OPENAI_API_KEY` / `ANTHROPIC_API_KEY`; passing
+                // the keys through `RunOptions` does nothing because RunOptions
+                // does not declare those fields. Mirrors the inline `scopeKey`
+                // pattern used at the /setup handler around line 1732.
+                const simulateEnvSnapshot = [];
+                const scopeSimulateKey = (envName, userValue) => {
+                    if (!userValue || userValue.includes('...'))
+                        return;
+                    simulateEnvSnapshot.push([envName, env[envName]]);
+                    env[envName] = userValue;
+                };
+                scopeSimulateKey('OPENAI_API_KEY', userApiKey);
+                scopeSimulateKey('ANTHROPIC_API_KEY', userAnthropicKey);
+                const restoreSimulateEnv = () => {
+                    for (const [name, prior] of simulateEnvSnapshot) {
+                        if (prior === undefined)
+                            delete env[name];
+                        else
+                            env[name] = prior;
+                    }
+                };
+                const deps = {
+                    compileScenario: (raw, opts) => {
+                        const userCompile = options.compileScenario;
+                        if (userCompile)
+                            return userCompile(raw, opts);
+                        return compileScenarioReal(raw, opts);
+                    },
+                    runSimulation: async (leader, keyPersonnel, runOpts) => {
+                        const { runSimulation } = await import('../runtime/orchestrator.js');
+                        return runSimulation(leader, keyPersonnel, runOpts);
+                    },
+                };
+                try {
+                    await handleSimulate(req, res, body, deps);
+                }
+                finally {
+                    restoreSimulateEnv();
+                }
+            }
+            catch (err) {
+                writeJsonError(res, err);
             }
-            clearEventBuffer();
-            simConfig = null;
-            res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
-            res.end(JSON.stringify({ active: activeScenario.id, name: activeScenario.labels?.name }));
             return;
         }
         // Compile a custom scenario JSON into a ScenarioPackage
         if (req.url === '/compile' && req.method === 'POST') {
             try {
-                const body = JSON.parse(await readBody(req));
+                const body = JSON.parse(await readBody(req, maxRequestBodyBytes));
                 const { scenario: scenarioJson, provider: requestedProvider, model: requestedModel, seedText, seedUrl, webSearch, maxSearches, apiKey, anthropicKey } = body;
                 if (!scenarioJson || typeof scenarioJson !== 'object') {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -893,8 +1198,7 @@ export function createMarsServer(options = {}) {
             }
             catch (err) {
                 if (!res.headersSent) {
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: String(err) }));
+                    writeJsonError(res, err, 500);
                 }
                 else {
                     res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
@@ -934,7 +1238,7 @@ export function createMarsServer(options = {}) {
                 }
             };
             try {
-                const { agentId, message, apiKey, anthropicKey } = JSON.parse(await readBody(req));
+                const { agentId, message, apiKey, anthropicKey } = JSON.parse(await readBody(req, maxRequestBodyBytes));
                 if (!agentId || !message) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'agentId and message required' }));
@@ -1069,8 +1373,7 @@ export function createMarsServer(options = {}) {
                     restoreChatEnv();
                 }
                 catch { }
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: String(err) }));
+                writeJsonError(res, err, 500);
             }
             return;
         }
@@ -1079,105 +1382,8 @@ export function createMarsServer(options = {}) {
         // get the same rich data the dashboard sees, without having to scrape
         // raw events themselves.
         if (req.url === '/results' && req.method === 'GET') {
-            const simEvents = eventBuffer
-                .filter(msg => msg.startsWith('event: sim\n') || msg.startsWith('event: result\n') || msg.startsWith('event: verdict\n') || msg.startsWith('event: complete\n'))
-                .map(msg => {
-                const lines = msg.split('\n');
-                const eventType = lines[0]?.replace('event: ', '') || '';
-                try {
-                    return { event: eventType, data: JSON.parse(lines[1]?.replace('data: ', '') || '{}') };
-                }
-                catch {
-                    return { event: eventType, data: {} };
-                }
-            });
-            const results = simEvents.filter(e => e.event === 'result').map(e => e.data);
-            const verdict = simEvents.find(e => e.event === 'verdict')?.data || null;
-            const isComplete = simEvents.some(e => e.event === 'complete');
-            const turns = simEvents.filter(e => e.event === 'sim' && e.data?.type === 'turn_start').length / 2;
-            // Reconstruct per-leader timelines from the sim event stream.
-            // Group every sim event by leader name, then bucket interesting
-            // payload types into typed lists so consumers can pull turn-by-turn
-            // crisis info, dept reports, decisions, forges, citations, reactions.
-            const byLeader = new Map();
-            const ensureLeader = (name) => {
-                if (!byLeader.has(name))
-                    byLeader.set(name, { events: [], decisions: [], forges: [], citations: [], deptReports: [], agentReactions: [], promotions: [], systemsSnapshots: [] });
-                return byLeader.get(name);
-            };
-            // Track decision pending state so we can attach it to outcomes per event
-            const pendingDecision = new Map();
-            for (const e of simEvents) {
-                if (e.event !== 'sim')
-                    continue;
-                const inner = e.data;
-                const type = String(inner.type || '');
-                const leader = String(inner.leader || '');
-                if (!leader)
-                    continue;
-                const slot = ensureLeader(leader);
-                const data = inner.data ?? {};
-                const turn = data.turn;
-                const time = data.time;
-                const eventIndex = data.eventIndex;
-                const pendKey = `${leader}-${turn}-${eventIndex ?? 0}`;
-                if (type === 'event_start') {
-                    slot.events.push({ turn, time, eventIndex, title: data.title, category: data.category, description: data.description, emergent: data.emergent });
-                }
-                else if (type === 'turn_start' && data.title && data.title !== 'Director generating...') {
-                    slot.events.push({ turn, time, title: data.title, category: data.category, description: data.crisis, emergent: data.emergent });
-                }
-                else if (type === 'commander_decided') {
-                    pendingDecision.set(pendKey, {
-                        decision: data.decision,
-                        rationale: data.rationale,
-                        selectedPolicies: data.selectedPolicies,
-                    });
-                }
-                else if (type === 'outcome') {
-                    const p = pendingDecision.get(pendKey);
-                    slot.decisions.push({ turn, time, eventIndex, ...p, outcome: data.outcome });
-                    pendingDecision.delete(pendKey);
-                }
-                else if (type === 'dept_done') {
-                    const dept = data.department;
-                    const cites = data.citationList || [];
-                    slot.deptReports.push({
-                        turn, time, eventIndex, department: dept,
-                        summary: data.summary,
-                        risks: data.risks,
-                        recommendedActions: data.recommendedActions,
-                        citations: cites.length,
-                        toolCount: Array.isArray(data.forgedTools) ? data.forgedTools.length : 0,
-                    });
-                    for (const c of cites) {
-                        slot.citations.push({ ...c, department: dept, turn });
-                    }
-                }
-                else if (type === 'forge_attempt') {
-                    slot.forges.push({ turn, time, eventIndex, ...data });
-                }
-                else if (type === 'agent_reactions') {
-                    slot.agentReactions.push({ turn, time, reactions: data.reactions, totalReactions: data.totalReactions });
-                }
-                else if (type === 'promotion') {
-                    slot.promotions.push({ ...data });
-                }
-                else if (type === 'systems_snapshot') {
-                    slot.systemsSnapshots.push({ turn, time, ...data });
-                }
-            }
-            const leaders = [...byLeader.entries()].map(([name, slot]) => ({ name, ...slot }));
             res.writeHead(200, { ...corsHeaders, 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                results,
-                verdict,
-                isComplete,
-                turnsCompleted: Math.floor(turns),
-                totalEvents: simEvents.length,
-                // New: structured per-leader payloads built from the SSE buffer
-                leaders,
-            }));
+            res.end(JSON.stringify(buildResultsPayloadFromEventBuffer(eventBuffer)));
             return;
         }
         if (req.url === '/rate-limit' && req.method === 'GET') {
@@ -1386,7 +1592,7 @@ export function createMarsServer(options = {}) {
         }
         if (req.url === '/setup' && req.method === 'POST') {
             try {
-                const config = JSON.parse(await readBody(req));
+                const config = JSON.parse(await readBody(req, maxRequestBodyBytes));
                 // Rate limit check: bypass when user provides their own API keys
                 const hasUserKeys = !!(config.apiKey || config.anthropicKey);
                 if (rateLimiter && !hasUserKeys) {
@@ -1433,22 +1639,22 @@ export function createMarsServer(options = {}) {
                 // parent artifact before spinning up the orchestrator.
                 if (simConfig.forkFrom) {
                     const { parentArtifact } = simConfig.forkFrom;
-                    const parentScenarioId = parentArtifact?.metadata?.scenario?.id;
-                    if (parentScenarioId !== activeScenario.id) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({
-                            error: `Fork parent scenario '${parentScenarioId}' does not match active scenario '${activeScenario.id}'. Cross-scenario forks are not supported.`,
-                        }));
-                        return;
-                    }
-                    const snapshots = parentArtifact?.scenarioExtensions?.kernelSnapshotsPerTurn;
-                    if (!Array.isArray(snapshots) || snapshots.length === 0) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                    const forkTurn = simConfig.forkFrom.atTurn;
+                    const forkValidation = validateForkSetupPreconditions({
+                        parentArtifact,
+                        atTurn: forkTurn,
+                        activeScenarioId: activeScenario.id,
+                        activeRunInProgress: simRunning && !!activeSimAbortController,
+                    });
+                    if (!forkValidation.ok) {
+                        res.writeHead(forkValidation.statusCode, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
-                            error: 'Fork parent has no embedded kernel snapshots. Re-run the parent simulation with `captureSnapshots: true` to enable forking.',
+                            error: forkValidation.error,
+                            issues: forkValidation.issues,
                         }));
                         return;
                     }
+                    simConfig.forkFrom.parentArtifact = forkValidation.parentArtifact;
                     // Force captureSnapshots on for forked children so they are
                     // themselves forkable.
                     simConfig.captureSnapshots = true;
@@ -1465,6 +1671,13 @@ export function createMarsServer(options = {}) {
                     console.log(`  [demo-mode] Capped run: turns=${simConfig.turns} pop=${simConfig.initialPopulation} ` +
                         `depts=${simConfig.activeDepartments.length} models=${simConfig.models.commander}`);
                 }
+                // Build a base RunRecord for the /setup response (line ~1830). The
+                // record is NOT inserted at run-start; instead, server-app inserts
+                // one enriched record per completed artifact via the onArtifact
+                // callback wired into the runner functions below. That callback
+                // captures artifact-derived fields (artifactPath, costUSD,
+                // durationMs, mode, leaderName, leaderArchetype) which the Library
+                // tab needs to render gallery cards and to load full artifacts.
                 const runRecord = createRunRecord({
                     scenarioId: activeScenario.id,
                     scenarioVersion: activeScenario.version,
@@ -1477,12 +1690,32 @@ export function createMarsServer(options = {}) {
                     sourceMode: serverMode,
                     createdBy: hasUserKeys ? 'user' : 'anonymous',
                 });
-                try {
-                    await runHistoryStore.insertRun(runRecord);
-                }
-                catch (error) {
-                    console.warn('[run-history] insert failed:', error);
-                }
+                // Insert a per-artifact RunRecord at run-end: the runner fires
+                // `onArtifact` for each completed leader, we enrich the base
+                // record with artifact fields and use the artifact's own runId
+                // so the Library tab links each card to a specific artifact.
+                // Capture the resolved simConfig values now so the closure does
+                // not depend on the (nullable) closure-level `simConfig` later.
+                const persistTurns = simConfig.turns;
+                const persistSeed = simConfig.seed;
+                const onArtifactPersist = async (artifact, leader) => {
+                    try {
+                        const perArtifactBase = {
+                            ...runRecord,
+                            runId: artifact.metadata.runId,
+                            leaderConfigHash: hashLeaderConfig({
+                                leader,
+                                turns: persistTurns,
+                                seed: persistSeed,
+                            }),
+                        };
+                        const enriched = enrichRunRecordFromArtifact(perArtifactBase, artifact);
+                        await runHistoryStore.insertRun(enriched);
+                    }
+                    catch (error) {
+                        console.warn('[run-history] per-artifact insert failed:', error);
+                    }
+                };
                 // Key-scope safety: snapshot the env values we're about to mutate
                 // so we can restore them when THIS sim ends. Without this, user A's
                 // key persists in process.env after their sim completes; user B's
@@ -1546,7 +1779,7 @@ export function createMarsServer(options = {}) {
                 // Start the sim and restore env when it finishes — prevents the
                 // caller's keys from leaking into any subsequent /setup from a
                 // different user that doesn't pass their own keys.
-                marsServer.startWithConfig(simConfig).finally(restoreEnv);
+                marsServer.startWithConfig(simConfig, { onArtifact: onArtifactPersist }).finally(restoreEnv);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
                     redirect: '/sim',
@@ -1560,8 +1793,7 @@ export function createMarsServer(options = {}) {
                 }));
             }
             catch (error) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: String(error) }));
+                writeJsonError(res, error);
             }
             return;
         }
@@ -1581,6 +1813,19 @@ export function createMarsServer(options = {}) {
                 return;
             }
         }
+        // Serve demo videos (Remotion-rendered loops shown on the landing page).
+        // Long cache: rendered output is content-addressable enough that the
+        // landing's <video src> changes when content changes.
+        if (req.url?.split('?')[0].startsWith('/demo/')) {
+            const demoPath = resolve(__dirname, '..', '..', 'assets', 'demo', req.url.split('?')[0].replace('/demo/', ''));
+            if (existsSync(demoPath)) {
+                const ext = demoPath.split('.').pop() || '';
+                const types = { mp4: 'video/mp4', webm: 'video/webm', png: 'image/png', jpg: 'image/jpeg' };
+                res.writeHead(200, { 'Content-Type': types[ext] || 'application/octet-stream', 'Cache-Control': 'public, max-age=86400' });
+                res.end(readFileSync(demoPath));
+                return;
+            }
+        }
         if (req.url === '/favicon.svg' || req.url === '/favicon.png' || req.url === '/favicon.ico' || req.url === '/icon.svg' || req.url === '/apple-touch-icon.png') {
             try {
                 const assetsDir = resolve(__dirname, '..', '..', 'assets');
@@ -1843,7 +2088,7 @@ export function createMarsServer(options = {}) {
     server.on('close', () => { if (rateLimiter)
         rateLimiter.destroy(); });
     const marsServer = Object.assign(server, {
-        async startWithConfig(config) {
+        async startWithConfig(config, hooks) {
             // Clear previous run data
             clearEventBuffer();
             simConfig = config;
@@ -1864,10 +2109,15 @@ export function createMarsServer(options = {}) {
                 // runForkSimulation instead of the pair runner when the
                 // config carries a forkFrom reference.
                 if (config.forkFrom) {
-                    await runForkSimulation(config, broadcast, controller.signal, activeScenario);
+                    await runForkSimulation(config, broadcast, controller.signal, activeScenario, hooks?.onArtifact);
+                }
+                else if (config.leaders.length >= 3) {
+                    // Tier 5 Quickstart dispatches N >= 3 leaders to the batch
+                    // runner (same SSE contract per leader, no verdict).
+                    await runBatchSimulations(config, broadcast, controller.signal, activeScenario, hooks?.onArtifact);
                 }
                 else {
-                    await startSimulations(config, broadcast, controller.signal, activeScenario);
+                    await startSimulations(config, broadcast, controller.signal, activeScenario, hooks?.onArtifact);
                 }
             }
             finally {