@avi770/testteam 2.0.0 → 3.2.0

package/dist/bridge/server.js

@@ -0,0 +1,1103 @@
+/**
+ * Bridge HTTP Server
+ *
+ * Exposes the BridgeRouter over HTTP using Node's built-in http module.
+ * No external dependencies required — keeps TestTeam dependency-light.
+ *
+ * Endpoints:
+ *   GET  /health     — liveness check
+ *   GET  /agents     — full agent capability list with executor types
+ *   GET  /runs       — summaries of past runs read from the .run/ directory
+ *   GET  /runs/:id   — full detail (summary + agent results) for one run
+ *   POST /execute    — execute a BridgeTask and return BridgeResult
+ */
+import { createServer } from 'node:http';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import * as path from 'node:path';
+import { BridgeRouter } from './router.js';
+import { PlaywrightPool } from './playwright-pool.js';
+import { ShellExecutor } from './shell-executor.js';
+import { FileScanner } from './file-scanner.js';
+import { buildSystemMapSnapshot } from './knowledge-reader.js';
+import { buildSecurityPostureSnapshot } from './sentinel-reader.js';
+import { buildCompliancePostureSnapshot } from './compliance-reader.js';
+import { buildApiContractSnapshot } from './api-contract-reader.js';
+import { buildDesignPostureSnapshot } from './design-reader.js';
+import { buildTechDebtSnapshot } from './tech-debt-reader.js';
+import { buildDataIntegritySnapshot } from './data-integrity-reader.js';
+import { buildReliabilityPostureSnapshot } from './reliability-reader.js';
+import { buildLoopEngineCockpit } from './loop-engine-reader.js';
+import { HttpClient } from './http-client.js';
+import { RateLimiter } from './rate-limiter.js';
+import { AGENT_REGISTRY } from './agent-registry.js';
+import { getAgentTier } from '../agents/registry.js';
+import { listRuns, readRun } from './runs-reader.js';
+import { CanvasStore, CanvasPathError } from '../core/canvas/store.js';
+import { CanvasValidationError } from '../core/canvas/schema.js';
+import { RunEventEmitter, SseRunEventSink, SseFrameSink, SseLoopEventSink, initSse } from '../core/run-events/index.js';
+import { FrameStreamer } from '../core/run-mode/index.js';
+import { runLoopEngineDemo } from '../core/loop-engine/index.js';
+import { PauseGate } from '../core/escalation/pause-gate.js';
+import { FeatureArtifactStore, FeatureStorePathError, FeatureStoreValidationError, } from '../core/feature-bdd/store.js';
+import { FeatureBddValidationError } from '../core/feature-bdd/schema.js';
+import { generateBdd, generateTests } from '../core/feature-bdd/generate.js';
+import { runFeatureTests, FEATURE_BDD_AGENT_ID } from '../core/feature-bdd/run.js';
+import { fixFeature } from '../core/feature-bdd/fix.js';
+import { AnthropicProvider, LLMProviderError, } from '../core/feature-bdd/llm-provider.js';
+import { FEATURE_PROVENANCE_VERSION } from '../core/feature-bdd/schema.js';
+function toSafeLogMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.replace(/[\r\n]+/g, ' ');
+}
+/** Build the agent capability list from the registry. */
+function buildAgentList() {
+    return AGENT_REGISTRY.map((entry) => ({
+        agentId: entry.agentId,
+        name: entry.name,
+        executorType: entry.executorType,
+        squad: entry.squad,
+        licenseTier: getAgentTier(entry.agentId),
+    }));
+}
+/** Maximum accepted request-body size (bytes). Canvas graphs cap ~1.5 MB; 5 MB is generous. */
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/** Read the full request body as a string, rejecting bodies over MAX_BODY_BYTES. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                req.destroy();
+                reject(new Error('request body too large'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+/** Send a JSON response. */
+function jsonResponse(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+/**
+ * Strip CR/LF + control chars from a (possibly user-derived) value before
+ * logging it — prevents forged / multi-line log entries (CodeQL js/log-injection).
+ */
+function logSafe(v) {
+    const s = v instanceof Error ? v.message : String(v);
+    // Remove CR/LF first (the log-forging vector — the explicit newline-removal
+    // pattern CodeQL's js/log-injection recognises as a sanitizer), then strip any
+    // remaining control chars and cap the length.
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\r\n]/g, '').replace(/[\t\x00-\x1f\x7f]/g, ' ').slice(0, 500);
+}
+/** Return a stable, non-user-derived error category for logging. */
+function logErrorKind(err) {
+    if (err && typeof err === 'object') {
+        const ctor = err.constructor;
+        if (ctor && typeof ctor.name === 'string' && ctor.name.length > 0) {
+            return logSafe(ctor.name);
+        }
+    }
+    return 'UnknownError';
+}
+/** Validate that a parsed body conforms to the minimal BridgeTask shape. */
+function isValidBridgeTask(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const obj = body;
+    const validExecutors = ['playwright', 'shell', 'file-scan', 'http', 'hybrid'];
+    return (typeof obj['agentId'] === 'number' &&
+        typeof obj['agentName'] === 'string' &&
+        typeof obj['executorType'] === 'string' &&
+        validExecutors.includes(obj['executorType']) &&
+        typeof obj['config'] === 'object' &&
+        obj['config'] !== null);
+}
+/**
+ * Validate the executor-specific `config` shape at the route boundary so a
+ * structurally-wrong task (e.g. a shell task with no `command`, an http task
+ * with no `url`) returns a clear 400 rather than crashing the executor into a
+ * generic 500 (or, worse, calling ShellExecutor.execute(undefined, …)).
+ * Returns an error string, or null when the shape is valid for the executor.
+ */
+function configShapeError(task) {
+    const c = task.config;
+    const needsString = (key) => typeof c[key] === 'string' && c[key].length > 0;
+    switch (task.executorType) {
+        case 'playwright':
+            return needsString('url') ? null : 'playwright config requires a non-empty string url';
+        case 'http':
+            return needsString('url') ? null : 'http config requires a non-empty string url';
+        case 'shell':
+            return needsString('command') ? null : 'shell config requires a non-empty string command';
+        case 'file-scan':
+            if (!needsString('rootDir'))
+                return 'file-scan config requires a non-empty string rootDir';
+            if (!Array.isArray(c['patterns']))
+                return 'file-scan config requires a patterns array';
+            return null;
+        case 'hybrid':
+            return Array.isArray(c['steps']) && c['steps'].length > 0
+                ? null
+                : 'hybrid config requires a non-empty steps array';
+        default:
+            return null;
+    }
+}
+/**
+ * Resource-intensive routes that must be rate-limited even though they are GET:
+ * the unauthenticated SSE run-triggers START full pipeline runs / spawn child
+ * processes / run an in-process kernel demo, so an enabled limiter must cover them
+ * — not just mutating POSTs. Matches GET /runs/stream, GET /loop-engine/stream, and
+ * GET /canvas/:id/bdd/{run,fix}. Cheap read-only GETs (/health, /agents, /runs,
+ * /runs/:id, /loop-engine/cockpit, canvas load) stay unthrottled.
+ */
+function isExpensiveGet(method, url) {
+    if (method !== 'GET')
+        return false;
+    const p = url.split('?')[0];
+    if (p === '/runs/stream')
+        return true;
+    // Runs an in-process kernel demo (bounded, but CPU) — throttle it like the other SSE GETs.
+    if (p === '/loop-engine/stream')
+        return true;
+    const segs = p.split('/').filter(Boolean); // ['canvas', id, 'bdd', sub]
+    return segs[0] === 'canvas' && segs[2] === 'bdd' && (segs[3] === 'run' || segs[3] === 'fix');
+}
+/** Valid phase values accepted on the query string for GET /runs/stream. */
+const VALID_PHASES = new Set(['alpha', 'beta', 'uat', 'release', 'exploratory']);
+/**
+ * Per-run registry of active gate + emitter pairs, used by POST /runs/answer to
+ * route answers back to the correct in-flight run.
+ */
+const runRegistry = new Map();
+/**
+ * Returns true and sets the appropriate ACAO header if the origin is allowed;
+ * returns false and sets no ACAO header otherwise.
+ */
+function applyCors(req, res, allowed) {
+    const origin = req.headers['origin'];
+    if (typeof origin === 'string' && allowed.includes(origin)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, x-bridge-token');
+}
+/**
+ * Check the x-bridge-token header when a token is configured.
+ * Returns true if auth passes (or no token is configured).
+ * Returns false after sending a 401 response.
+ */
+/** Constant-time string compare — avoids leaking the token via comparison timing. */
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    // timingSafeEqual throws on length mismatch; the length check is not secret.
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+function checkAuth(req, res, token) {
+    if (token === '')
+        return true;
+    const provided = req.headers['x-bridge-token'];
+    if (typeof provided === 'string' && safeEqual(provided, token))
+        return true;
+    jsonResponse(res, 401, { error: 'unauthorized' });
+    return false;
+}
+/**
+ * Stricter auth for CODE-WRITING routes (BDD scenario/test generation): these persist
+ * LLM-generated code to disk which the runner later executes via vitest. Unlike the
+ * read routes, they must NEVER be open — so when no TESTTEAM_BRIDGE_TOKEN is configured
+ * they are refused outright (503), closing the unauthenticated write→execute (RCE) chain
+ * even in the bridge's dev-default unauth posture. The SSE run/fix routes (which
+ * EventSource cannot add a header to) then only ever execute already-authored artifacts.
+ */
+function requireConfiguredAuth(req, res, token) {
+    if (token === '') {
+        jsonResponse(res, 503, {
+            error: 'this route generates+persists executable code and requires TESTTEAM_BRIDGE_TOKEN to be configured',
+        });
+        return false;
+    }
+    return checkAuth(req, res, token);
+}
+/**
+ * Create and return the HTTP server without starting it.
+ * Useful for testing — call `server.listen(port)` yourself.
+ */
+export function createBridgeServer(options = {}) {
+    const router = options.router ??
+        new BridgeRouter(new PlaywrightPool(), new ShellExecutor(), new FileScanner(), new HttpClient());
+    const runsDir = options.runsDir ?? path.join(process.cwd(), '.run');
+    const runStreamDriver = options.runStreamDriver;
+    const agentRunner = options.agentRunner;
+    const canvasStore = new CanvasStore(options.canvasDir ?? path.join(process.cwd(), '.testteam', 'canvases'));
+    const llmProvider = options.llmProvider ?? new AnthropicProvider();
+    const featureStore = new FeatureArtifactStore(options.featuresDir ?? path.join(process.cwd(), '.testteam', 'features'));
+    const shellExecutor = options.shellExecutor ?? new ShellExecutor();
+    const allowed = options.allowedOrigins ??
+        process.env['TESTTEAM_BRIDGE_ORIGINS']?.split(',').map((s) => s.trim()).filter(Boolean) ??
+        ['http://localhost:5173'];
+    const authToken = options.authToken ?? process.env['TESTTEAM_BRIDGE_TOKEN'] ?? '';
+    if (authToken === '') {
+        console.warn('[bridge] WARNING: no auth token set (TESTTEAM_BRIDGE_TOKEN); mutating routes are unauthenticated');
+    }
+    // Rate limiter for mutating requests — OFF by default. Enable via options.rateLimit
+    // or TESTTEAM_BRIDGE_RATE_LIMIT (set to "1"/"true" for the default 60/min, or a number
+    // for a custom per-minute cap).
+    const rlEnv = process.env['TESTTEAM_BRIDGE_RATE_LIMIT'];
+    const rlEnvOn = rlEnv === '1' || rlEnv === 'true' || (rlEnv !== undefined && Number(rlEnv) > 0);
+    const limiter = (options.rateLimit?.enabled ?? rlEnvOn)
+        ? new RateLimiter({
+            max: options.rateLimit?.max ?? (rlEnv && Number(rlEnv) > 1 ? Number(rlEnv) : 60),
+            windowMs: options.rateLimit?.windowMs ?? 60_000,
+        })
+        : null;
+    const server = createServer(async (req, res) => {
+        const url = req.url ?? '/';
+        const method = req.method ?? 'GET';
+        // CORS headers for all responses (allowlist-based)
+        applyCors(req, res, allowed);
+        // Handle OPTIONS preflight
+        if (method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Rate limit mutating (non-GET/HEAD) requests AND the resource-intensive SSE
+        // run-trigger GETs (/runs/stream, /canvas/:id/bdd/{run,fix}) — which spawn
+        // processes / start pipeline runs — when the limiter is enabled. Cheap read-only
+        // GETs (/health, /agents, /runs, canvas load) stay unthrottled.
+        if (limiter && ((method !== 'GET' && method !== 'HEAD') || isExpensiveGet(method, url))) {
+            const key = req.socket.remoteAddress ?? 'unknown';
+            const verdict = limiter.check(key, Date.now());
+            if (!verdict.allowed) {
+                res.setHeader('Retry-After', String(Math.ceil(verdict.retryAfterMs / 1000)));
+                jsonResponse(res, 429, { error: 'rate limit exceeded', retryAfterMs: verdict.retryAfterMs });
+                return;
+            }
+        }
+        try {
+            // GET /health
+            if (method === 'GET' && url === '/health') {
+                jsonResponse(res, 200, { healthy: true, agents: AGENT_REGISTRY.length, product: 'testteam' });
+                return;
+            }
+            // GET /agents
+            if (method === 'GET' && url === '/agents') {
+                jsonResponse(res, 200, { agents: buildAgentList() });
+                return;
+            }
+            // GET /features — list persisted BDD feature keys (browse independent of a canvas).
+            if (method === 'GET' && url.split('?')[0] === '/features') {
+                jsonResponse(res, 200, { features: await featureStore.list() });
+                return;
+            }
+            // GET /knowledge/system-map — the Master-Knowledge dependency graph (agents +
+            // phases, phase→agent dispatch edges) for the dashboard blast-radius view.
+            // Read-only + derived from the registry, so unauth like /agents (dashboard S2).
+            if (method === 'GET' && url.split('?')[0] === '/knowledge/system-map') {
+                jsonResponse(res, 200, buildSystemMapSnapshot());
+                return;
+            }
+            // GET /security/posture — The Sentinel's security posture (score, attack
+            // paths, ranked findings) derived from the latest run's security-squad
+            // findings. Read-only + derived from persisted run artifacts, so unauth
+            // like /agents and /knowledge/system-map (dashboard S3).
+            if (method === 'GET' && url.split('?')[0] === '/security/posture') {
+                jsonResponse(res, 200, buildSecurityPostureSnapshot(runsDir));
+                return;
+            }
+            // GET /compliance/posture — The Inspector's compliance posture (per-control
+            // status, gaps, drift, per-framework %) derived from the latest run's
+            // compliance-agent findings. Read-only + run-derived → unauth like the
+            // sibling posture/knowledge GETs (dashboard S4).
+            if (method === 'GET' && url.split('?')[0] === '/compliance/posture') {
+                jsonResponse(res, 200, buildCompliancePostureSnapshot(runsDir));
+                return;
+            }
+            // GET /api-contract/posture — The Border Guard's runtime api-contract posture
+            // (api-squad findings #39/#41/#42, per-agent + severity rollup, blocking flag)
+            // derived from the latest run. Read-only + run-derived → unauth like the
+            // sibling posture/knowledge GETs (dashboard S5).
+            if (method === 'GET' && url.split('?')[0] === '/api-contract/posture') {
+                jsonResponse(res, 200, buildApiContractSnapshot(runsDir));
+                return;
+            }
+            // GET /design/posture — The Designer's design posture (a11y hard-floor gate,
+            // usability score, responsive result, per-agent rollup) derived from the
+            // latest run's design-squad findings (#8/#67/#12/#80/#29) via the ui-ux
+            // orchestrator's pure helpers. Read-only + run-derived → unauth like the
+            // sibling posture/knowledge GETs (dashboard S6).
+            if (method === 'GET' && url.split('?')[0] === '/design/posture') {
+                jsonResponse(res, 200, buildDesignPostureSnapshot(runsDir));
+                return;
+            }
+            // GET /tech-debt/posture — The Tech-Debt Tracker's posture (ROI-ranked debt
+            // inventory, per-category rollup, sequenced refactor roadmap) derived from
+            // the latest run's engine findings (#68/#69/#70/#83) via the pure
+            // runTechDebtTracker. Read-only + run-derived → unauth like the sibling
+            // posture/knowledge GETs (dashboard S7).
+            if (method === 'GET' && url.split('?')[0] === '/tech-debt/posture') {
+                jsonResponse(res, 200, buildTechDebtSnapshot(runsDir));
+                return;
+            }
+            // GET /data-integrity/posture — the Data-Integrity notary's posture
+            // (layer-computed IntegritySummary + severity-ranked engine findings from
+            // #14/#43/#44/#45 via DataIntegritySession). Read-only + run-derived →
+            // unauth like the sibling posture GETs (dashboard S8).
+            if (method === 'GET' && url.split('?')[0] === '/data-integrity/posture') {
+                jsonResponse(res, 200, buildDataIntegritySnapshot(runsDir));
+                return;
+            }
+            // GET /reliability/posture — the Conductor+DR+Tester cluster's posture
+            // (Tester honest verdict + DR resilience score, both agent-granularity
+            // from AgentResult.status; Conductor deferred). Read-only + run-derived →
+            // unauth like the sibling posture GETs (dashboard S9).
+            if (method === 'GET' && url.split('?')[0] === '/reliability/posture') {
+                jsonResponse(res, 200, buildReliabilityPostureSnapshot(runsDir));
+                return;
+            }
+            // GET /loop-engine/cockpit — the loop-engine observatory (dashboard S10).
+            // STRUCTURAL, not run-derived: per-run loop cognition is live-only and not
+            // persisted (D-UI-13), so this surfaces the engine's real structure (7
+            // loops, statuses, breaker states) from core constants + discloses the
+            // live stream. Read-only + no run input → unauth like the sibling GETs.
+            if (method === 'GET' && url.split('?')[0] === '/loop-engine/cockpit') {
+                jsonResponse(res, 200, buildLoopEngineCockpit());
+                return;
+            }
+            // GET /loop-engine/stream — LIVE loop-cognition demonstration (dashboard S11).
+            //
+            // Streams GENUINE per-cycle LoopEvents from a real kernel run on a dedicated
+            // `event: loop-event` SSE channel (decision D-UI-14). No production agent drives
+            // the kernel at runtime yet (that is Option B), so this runs the engine against a
+            // demonstration workload — the events are real kernel output, not fabricated, so
+            // the live cockpit stays honest (D-UI-12). Read-only, in-process, bounded (the demo
+            // clamps its own cycle count) and self-terminating. Unauth like the sibling GETs.
+            if (method === 'GET' && url.split('?')[0] === '/loop-engine/stream') {
+                const loopQs = url.includes('?') ? url.slice(url.indexOf('?') + 1) : '';
+                const cyclesParam = new URLSearchParams(loopQs).get('cycles');
+                const parsedCycles = cyclesParam !== null ? Number(cyclesParam) : Number.NaN;
+                const demoOpts = Number.isFinite(parsedCycles) && parsedCycles > 0 ? { cycles: parsedCycles } : {};
+                initSse(res);
+                res.writeHead(200);
+                const loopSink = new SseLoopEventSink(res);
+                try {
+                    await runLoopEngineDemo((event) => loopSink.push(event), demoOpts);
+                }
+                catch (err) {
+                    console.error('Loop-engine demo stream failed:', err);
+                }
+                // Terminal `loop-done` event — the client listens for it and closes, so the browser's
+                // EventSource does NOT auto-reconnect on stream-end and silently restart the demo. Guarded
+                // so a client that already disconnected is skipped (a dead socket must never throw).
+                if (res.writableEnded !== true && res.destroyed !== true) {
+                    res.write('event: loop-done\ndata: {}\n\n');
+                }
+                res.end();
+                return;
+            }
+            // --- Feature Canvas (Phase 1) ---
+            // GET /canvas — list persisted canvases
+            if (method === 'GET' && url.split('?')[0] === '/canvas') {
+                jsonResponse(res, 200, { canvases: await canvasStore.list() });
+                return;
+            }
+            // /canvas/:id — single-canvas load (GET) / save (POST).
+            // Note: deeper paths like /canvas/:id/nodes/... are reserved for Phase 3 (run trigger).
+            if (url.split('?')[0].startsWith('/canvas/')) {
+                const segs = url.split('?')[0].split('/').filter(Boolean); // ['canvas', id, ...]
+                let id = '';
+                try {
+                    id = segs[1] ? decodeURIComponent(segs[1]) : '';
+                }
+                catch {
+                    jsonResponse(res, 400, { error: 'Invalid canvas id encoding' });
+                    return;
+                }
+                // --- Phase 4: BDD sub-routes (/canvas/:id/bdd/*) ---
+                // These must appear BEFORE the segs.length === 2 guards because they
+                // have segs.length === 4 and would never match those guards.
+                if (segs.length >= 3 && segs[2] === 'bdd') {
+                    const subRoute = segs[3] ?? '';
+                    // (a) POST /canvas/:id/bdd/scenarios
+                    if (method === 'POST' && subRoute === 'scenarios') {
+                        if (!requireConfiguredAuth(req, res, authToken))
+                            return;
+                        let raw;
+                        try {
+                            raw = await readBody(req);
+                        }
+                        catch (err) {
+                            if (err instanceof Error && err.message === 'request body too large') {
+                                jsonResponse(res, 413, { error: err.message });
+                                return;
+                            }
+                            throw err;
+                        }
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(raw);
+                        }
+                        catch {
+                            jsonResponse(res, 400, { error: 'Invalid JSON body' });
+                            return;
+                        }
+                        if (typeof parsed !== 'object' ||
+                            parsed === null ||
+                            typeof parsed['featureKey'] !== 'string' ||
+                            typeof parsed['description'] !== 'string') {
+                            jsonResponse(res, 400, { error: 'body requires featureKey (string) and description (string)' });
+                            return;
+                        }
+                        const scenariosBody = parsed;
+                        const featureKey = scenariosBody['featureKey'];
+                        const description = scenariosBody['description'];
+                        const context = typeof scenariosBody['context'] === 'string' ? scenariosBody['context'] : undefined;
+                        let safeFeatureKey;
+                        try {
+                            safeFeatureKey = FeatureArtifactStore.safeKey(featureKey);
+                        }
+                        catch (err) {
+                            jsonResponse(res, 400, { error: err instanceof Error ? err.message : 'invalid featureKey' });
+                            return;
+                        }
+                        try {
+                            const bddSpec = await generateBdd(llmProvider, safeFeatureKey, description, { context });
+                            const now = new Date().toISOString();
+                            const provenance = {
+                                version: FEATURE_PROVENANCE_VERSION,
+                                featureKey: safeFeatureKey,
+                                bddSpec,
+                                testFiles: [],
+                                lastRunFindings: [],
+                                lastRunFailures: [],
+                                createdAt: now,
+                                updatedAt: now,
+                            };
+                            await featureStore.writeProvenance(safeFeatureKey, provenance);
+                            jsonResponse(res, 200, { featureKey: bddSpec.featureKey, scenarios: bddSpec.scenarios });
+                        }
+                        catch (err) {
+                            if (err instanceof LLMProviderError) {
+                                const status = err.kind === 'no-key' ? 503 : err.kind === 'bad-response' ? 422 : 502;
+                                // Never include err.message (may contain API key or internal details)
+                                console.error('[bridge] LLM error in POST /bdd/scenarios:', logSafe(err.message));
+                                jsonResponse(res, status, { error: 'LLM generation failed' });
+                            }
+                            else if (err instanceof FeatureBddValidationError) {
+                                console.error('[bridge] BDD validation error in POST /bdd/scenarios:', logSafe(err.message));
+                                jsonResponse(res, 422, { error: 'BDD spec validation failed' });
+                            }
+                            else if (err instanceof FeatureStorePathError || err instanceof FeatureStoreValidationError) {
+                                jsonResponse(res, 400, { error: err instanceof Error ? err.message : 'store error' });
+                            }
+                            else {
+                                console.error('[bridge] Unexpected error in POST /bdd/scenarios:', logSafe(err));
+                                jsonResponse(res, 500, { error: 'Internal server error' });
+                            }
+                        }
+                        return;
+                    }
+                    // (b) POST /canvas/:id/bdd/tests
+                    if (method === 'POST' && subRoute === 'tests') {
+                        if (!requireConfiguredAuth(req, res, authToken))
+                            return;
+                        let raw;
+                        try {
+                            raw = await readBody(req);
+                        }
+                        catch (err) {
+                            if (err instanceof Error && err.message === 'request body too large') {
+                                jsonResponse(res, 413, { error: err.message });
+                                return;
+                            }
+                            throw err;
+                        }
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(raw);
+                        }
+                        catch {
+                            jsonResponse(res, 400, { error: 'Invalid JSON body' });
+                            return;
+                        }
+                        if (typeof parsed !== 'object' ||
+                            parsed === null ||
+                            typeof parsed['featureKey'] !== 'string') {
+                            jsonResponse(res, 400, { error: 'body requires featureKey (string)' });
+                            return;
+                        }
+                        const testsBody = parsed;
+                        const featureKey = testsBody['featureKey'];
+                        const framework = typeof testsBody['framework'] === 'string' ? testsBody['framework'] : 'vitest';
+                        // Validate the client-supplied enum at the route boundary → 400
+                        // (rather than letting it surface as 422 from a deeper validator).
+                        if (!['vitest', 'jest', 'mocha'].includes(framework)) {
+                            jsonResponse(res, 400, { error: 'invalid framework; allowed: vitest, jest, mocha' });
+                            return;
+                        }
+                        let safeFeatureKey;
+                        try {
+                            safeFeatureKey = FeatureArtifactStore.safeKey(featureKey);
+                        }
+                        catch (err) {
+                            jsonResponse(res, 400, { error: err instanceof Error ? err.message : 'invalid featureKey' });
+                            return;
+                        }
+                        try {
+                            const provenance = await featureStore.readProvenance(safeFeatureKey);
+                            if (provenance === null) {
+                                jsonResponse(res, 404, { error: `no provenance for "${safeFeatureKey}"; call /bdd/scenarios first` });
+                                return;
+                            }
+                            if (!provenance.bddSpec) {
+                                jsonResponse(res, 409, { error: 'no BDD spec found; call /bdd/scenarios first' });
+                                return;
+                            }
+                            const generated = await generateTests(llmProvider, provenance.bddSpec, { framework });
+                            const writtenFiles = [];
+                            for (const f of generated.files) {
+                                await featureStore.writeTestFile(safeFeatureKey, f.filename, f.content);
+                                writtenFiles.push(f.filename);
+                            }
+                            // Update provenance with testFiles list
+                            const now = new Date().toISOString();
+                            const updatedProvenance = {
+                                ...provenance,
+                                testFiles: [
+                                    ...provenance.testFiles,
+                                    ...generated.files.map((f) => ({
+                                        filename: f.filename,
+                                        generatedAt: now,
+                                        fromLoopStage: 'generate-tests',
+                                    })),
+                                ],
+                                updatedAt: now,
+                            };
+                            await featureStore.writeProvenance(safeFeatureKey, updatedProvenance);
+                            jsonResponse(res, 200, { featureKey: safeFeatureKey, files: writtenFiles });
+                        }
+                        catch (err) {
+                            if (err instanceof LLMProviderError) {
+                                const status = err.kind === 'no-key' ? 503 : err.kind === 'bad-response' ? 422 : 502;
+                                console.error('[bridge] LLM error in POST /bdd/tests:', `kind=${err.kind}`, `status=${status}`);
+                                jsonResponse(res, status, { error: 'LLM generation failed' });
+                            }
+                            else if (err instanceof FeatureBddValidationError) {
+                                console.error('[bridge] BDD validation error in POST /bdd/tests:', logSafe(err.message));
+                                jsonResponse(res, 422, { error: 'BDD tests validation failed' });
+                            }
+                            else if (err instanceof FeatureStorePathError) {
+                                jsonResponse(res, 400, { error: err.message });
+                            }
+                            else if (err instanceof FeatureStoreValidationError) {
+                                jsonResponse(res, 422, { error: err.message });
+                            }
+                            else {
+                                console.error('[bridge] Unexpected error in POST /bdd/tests:', logSafe(err));
+                                jsonResponse(res, 500, { error: 'Internal server error' });
+                            }
+                        }
+                        return;
+                    }
+                    // (c) GET /canvas/:id/bdd/run?featureKey=...
+                    if (method === 'GET' && subRoute === 'run') {
+                        const qs = url.includes('?') ? url.slice(url.indexOf('?') + 1) : '';
+                        const rawFeatureKey = new URLSearchParams(qs).get('featureKey');
+                        if (!rawFeatureKey) {
+                            jsonResponse(res, 400, { error: 'missing required query param: featureKey' });
+                            return;
+                        }
+                        let safeFeatureKey;
+                        try {
+                            safeFeatureKey = FeatureArtifactStore.safeKey(rawFeatureKey);
+                        }
+                        catch (err) {
+                            jsonResponse(res, 400, { error: err instanceof Error ? err.message : 'invalid featureKey' });
+                            return;
+                        }
+                        // SSE setup — mirrors GET /runs/stream exactly
+                        initSse(res);
+                        res.writeHead(200);
+                        const ac = new AbortController();
+                        req.once('close', () => ac.abort());
+                        const runId = `run-${randomUUID()}`;
+                        const emitter = new RunEventEmitter(new SseRunEventSink(res));
+                        const gate = new PauseGate();
+                        gate.subscribe((q) => {
+                            emitter.questionAsked({
+                                questionId: q.id,
+                                agentId: q.agentId,
+                                title: q.title,
+                                detail: q.detail,
+                                ...(q.proposedAction !== undefined ? { proposedAction: q.proposedAction } : {}),
+                            });
+                        });
+                        ac.signal.addEventListener('abort', () => gate.cancelAll('client disconnected'));
+                        runRegistry.set(runId, { gate, emitter });
+                        emitter.runStarted({ runId, phase: 'alpha', scheduledAgentIds: [FEATURE_BDD_AGENT_ID] });
+                        try {
+                            // DoS guard (this route is unauthenticated): only spawn the vitest
+                            // child when the feature actually has generated test files. Avoids
+                            // a process-creation/glob DoS via repeated calls with random keys.
+                            const provenance = await featureStore.readProvenance(safeFeatureKey);
+                            if (!provenance || provenance.testFiles.length === 0) {
+                                res.write(`: error no test files for feature\n\n`);
+                                emitter.runFinished({ runId, passed: false });
+                                return;
+                            }
+                            const runResult = await runFeatureTests(safeFeatureKey, {
+                                executor: shellExecutor,
+                                store: featureStore,
+                                signal: ac.signal,
+                            });
+                            // Part A: persist failures into provenance BEFORE emitting run-finished
+                            // so /bdd/fix SSE can read them after this stream closes. Routed through
+                            // the store's per-key serialised recordRunFailures so concurrent runs of
+                            // the same feature can't race the read-modify-write (lost failures).
+                            try {
+                                const lastRunFailures = runResult.failures.map((f) => ({
+                                    file: f.file,
+                                    errorText: f.errorText.slice(0, 4096),
+                                    ...(f.scenarioId !== undefined ? { scenarioId: f.scenarioId } : {}),
+                                }));
+                                await featureStore.recordRunFailures(safeFeatureKey, lastRunFailures);
+                            }
+                            catch (persistErr) {
+                                // Non-fatal: log server-side + warn the client so a later /bdd/fix
+                                // reporting "no failures" isn't surprising.
+                                console.error('[bridge] BDD run: failed to persist lastRunFailures:', logErrorKind(persistErr));
+                                res.write(`: warning failed to persist failures for fix\n\n`);
+                            }
+                            emitter.runFinished({ runId, passed: runResult.passed });
+                        }
+                        catch (err) {
+                            // The SSE channel is client-visible — keep internal error strings
+                            // server-side only (mirrors the POST routes' generic-error discipline).
+                            console.error('[bridge] BDD run error:', logErrorKind(err));
+                            res.write(`: error internal\n\n`);
+                            emitter.runFinished({ runId, passed: false });
+                        }
+                        finally {
+                            runRegistry.delete(runId);
+                            res.end();
+                        }
+                        return;
+                    }
+                    // (d) GET /canvas/:id/bdd/fix?featureKey=... (SSE — mirrors /bdd/run)
+                    //
+                    // Design: unauthenticated GET SSE (mirrors /bdd/run and /runs/stream) because
+                    // the real security gate is the pause-and-ask flow that requires a human to
+                    // approve each finding via POST /runs/answer (which IS auth-gated). Untrusted
+                    // test findings always force route='pause-and-ask', so no auto-heal can fire
+                    // without explicit human approval through the authenticated answer endpoint.
+                    if (method === 'GET' && subRoute === 'fix') {
+                        const qs = url.includes('?') ? url.slice(url.indexOf('?') + 1) : '';
+                        const rawFeatureKey = new URLSearchParams(qs).get('featureKey');
+                        if (!rawFeatureKey) {
+                            jsonResponse(res, 400, { error: 'missing required query param: featureKey' });
+                            return;
+                        }
+                        let safeFeatureKey;
+                        try {
+                            safeFeatureKey = FeatureArtifactStore.safeKey(rawFeatureKey);
+                        }
+                        catch (err) {
+                            jsonResponse(res, 400, { error: err instanceof Error ? err.message : 'invalid featureKey' });
+                            return;
+                        }
+                        // SSE setup — mirrors GET /bdd/run exactly
+                        initSse(res);
+                        res.writeHead(200);
+                        const fixAc = new AbortController();
+                        req.once('close', () => fixAc.abort());
+                        const fixRunId = `run-${randomUUID()}`;
+                        const fixEmitter = new RunEventEmitter(new SseRunEventSink(res));
+                        const fixGate = new PauseGate();
+                        fixGate.subscribe((q) => {
+                            fixEmitter.questionAsked({
+                                questionId: q.id,
+                                agentId: q.agentId,
+                                title: q.title,
+                                detail: q.detail,
+                                ...(q.proposedAction !== undefined ? { proposedAction: q.proposedAction } : {}),
+                            });
+                        });
+                        fixAc.signal.addEventListener('abort', () => fixGate.cancelAll('client disconnected'));
+                        runRegistry.set(fixRunId, { gate: fixGate, emitter: fixEmitter });
+                        fixEmitter.runStarted({ runId: fixRunId, phase: 'alpha', scheduledAgentIds: [FEATURE_BDD_AGENT_ID] });
+                        try {
+                            // Read persisted failures from provenance (written by /bdd/run Part A).
+                            const fixProv = await featureStore.readProvenance(safeFeatureKey);
+                            const persistedFailures = (fixProv?.lastRunFailures ?? []).map((f) => ({
+                                file: f.file,
+                                errorText: f.errorText,
+                                ...(f.scenarioId !== undefined ? { scenarioId: f.scenarioId } : {}),
+                            }));
+                            if (persistedFailures.length === 0) {
+                                res.write(`: no failures to fix\n\n`);
+                                fixEmitter.runFinished({ runId: fixRunId, passed: true });
+                                return;
+                            }
+                            // fixFeature routes each failure through pause-and-ask (untrusted findings
+                            // always force gate.ask() — auto-heal is structurally impossible here).
+                            // Questions propagate to the client via fixGate.subscribe → fixEmitter.questionAsked.
+                            // Client answers via POST /runs/answer (auth-gated), which calls gate.answer().
+                            await fixFeature(safeFeatureKey, persistedFailures, { gate: fixGate });
+                            fixEmitter.runFinished({ runId: fixRunId, passed: true });
+                        }
+                        catch (err) {
+                            console.error('[bridge] BDD fix error:', logErrorKind(err));
+                            res.write(`: error internal\n\n`);
+                            fixEmitter.runFinished({ runId: fixRunId, passed: false });
+                        }
+                        finally {
+                            runRegistry.delete(fixRunId);
+                            res.end();
+                        }
+                        return;
+                    }
+                    // Unknown BDD sub-route
+                    jsonResponse(res, 404, { error: 'Not found' });
+                    return;
+                }
+                // GET /canvas/:id — load + validate
+                if (method === 'GET' && segs.length === 2) {
+                    try {
+                        jsonResponse(res, 200, await canvasStore.load(id));
+                    }
+                    catch (err) {
+                        if (err.code === 'ENOENT') {
+                            jsonResponse(res, 404, { error: `canvas "${id}" not found` });
+                        }
+                        else if (err instanceof CanvasPathError) {
+                            console.error('Canvas load path error:', toSafeLogMessage(err));
+                            jsonResponse(res, 400, { error: 'invalid canvas path' });
+                        }
+                        else {
+                            console.error('Canvas load failed:', toSafeLogMessage(err));
+                            jsonResponse(res, 400, { error: 'invalid canvas' });
+                        }
+                    }
+                    return;
+                }
+                // POST /canvas/:id — validate-then-save (malformed graph never reaches disk)
+                if (method === 'POST' && segs.length === 2) {
+                    if (!checkAuth(req, res, authToken))
+                        return;
+                    let raw;
+                    try {
+                        raw = await readBody(req);
+                    }
+                    catch (err) {
+                        if (err instanceof Error && err.message === 'request body too large') {
+                            jsonResponse(res, 413, { error: 'request body too large' });
+                            return;
+                        }
+                        throw err;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        jsonResponse(res, 400, { error: 'Invalid JSON body' });
+                        return;
+                    }
+                    try {
+                        jsonResponse(res, 200, await canvasStore.save(id, parsed));
+                    }
+                    catch (err) {
+                        if (err instanceof CanvasValidationError || err instanceof CanvasPathError) {
+                            console.error('Canvas save rejected:', toSafeLogMessage(err));
+                            jsonResponse(res, 400, { error: 'invalid canvas graph' });
+                        }
+                        else {
+                            console.error('Canvas save failed:', toSafeLogMessage(err));
+                            jsonResponse(res, 500, { error: 'Internal Server Error' });
+                        }
+                    }
+                    return;
+                }
+            }
+            // GET /runs/stream — live SSE event stream for a pipeline run.
+            //
+            // Design: intentionally unauthenticated GET SSE (EventSource cannot send an
+            // Authorization header). This is the read/observe surface; every MUTATING action
+            // is auth-gated — POST /execute, POST /runs/answer, POST /canvas/:id — and the
+            // pause-and-ask flow requires a human to approve each finding via the auth-gated
+            // POST /runs/answer, so no auto-heal can fire without authenticated approval.
+            // Residual (see docs/CLEANUP_PHASE.md): this GET starts a run, so when the bridge
+            // is exposed beyond localhost a query-param/cookie token for the SSE routes should
+            // gate run-triggering. Mirrors the /bdd/run and /bdd/fix SSE rationale above.
+            if (method === 'GET' && url.split('?')[0] === '/runs/stream') {
+                // 503 when no driver is configured
+                if (!runStreamDriver) {
+                    jsonResponse(res, 503, { error: 'no run driver configured' });
+                    return;
+                }
+                // Parse and validate the 'phase' query param
+                const qs = url.includes('?') ? url.slice(url.indexOf('?') + 1) : '';
+                const rawPhase = new URLSearchParams(qs).get('phase') ?? 'alpha';
+                if (!VALID_PHASES.has(rawPhase)) {
+                    jsonResponse(res, 400, {
+                        error: `invalid phase "${rawPhase}"; must be one of: alpha, beta, uat, release, exploratory`,
+                    });
+                    return;
+                }
+                const phase = rawPhase;
+                // Optional `?headed=1` requests a visible run (Phase 3.2) — browsers open headed and the
+                // driver may stream frames to the Cockpit.
+                const headedParam = new URLSearchParams(qs).get('headed');
+                const headed = headedParam === '1' || headedParam === 'true';
+                // Switch the response to SSE mode (CORS headers already set above).
+                initSse(res);
+                res.writeHead(200);
+                // Wire the AbortController to the client disconnect event.
+                const ac = new AbortController();
+                req.once('close', () => ac.abort());
+                // randomUUID (not Date.now) so two runs started in the same millisecond can't collide.
+                const runId = `run-${randomUUID()}`;
+                const emitter = new RunEventEmitter(new SseRunEventSink(res));
+                // Frames stream on the SAME response as `event: frame` SSE lines (a channel distinct from
+                // run-events). The driver pushes screencast frames into this FrameStreamer; a closed/dropped
+                // socket is skipped by the sink, so a dead screencast never breaks the run.
+                const frames = new FrameStreamer(new SseFrameSink(res));
+                // Loop cognition (Option B) streams on the SAME response as `event: loop-event` lines,
+                // tagged with the emitting agent's id + name. A dropped socket is skipped by the sink, so
+                // a dead consumer never breaks the run. Bypasses the RunEventEmitter log (D-UI-14).
+                const loopSink = new SseLoopEventSink(res);
+                // Create a PauseGate and subscribe it to forward questions onto the event stream.
+                const gate = new PauseGate();
+                gate.subscribe((q) => {
+                    emitter.questionAsked({
+                        questionId: q.id,
+                        agentId: q.agentId,
+                        title: q.title,
+                        detail: q.detail,
+                        ...(q.proposedAction !== undefined ? { proposedAction: q.proposedAction } : {}),
+                    });
+                });
+                // If the client disconnects while a question is pending, cancel it so the awaiting agent
+                // unwinds, the driver returns, and the finally block cleans up (no leaked gate/socket/agent).
+                ac.signal.addEventListener('abort', () => gate.cancelAll('client disconnected'));
+                runRegistry.set(runId, { gate, emitter });
+                // Emit run-started so the client knows the runId immediately.
+                emitter.runStarted({ runId, phase, scheduledAgentIds: [] });
+                try {
+                    await runStreamDriver({ phase, headed }, emitter, ac.signal, gate, frames, (agentId, agentName, event) => loopSink.pushForAgent(agentId, agentName, event));
+                    emitter.runFinished({ runId, passed: true });
+                }
+                catch (err) {
+                    console.error('Run stream failed:', err);
+                    // Write a terminal SSE comment so the client can detect failure (the
+                    // detailed error is logged server-side, never sent to the client).
+                    res.write(`: error\n\n`);
+                    emitter.runFinished({ runId, passed: false });
+                }
+                finally {
+                    runRegistry.delete(runId);
+                    res.end();
+                }
+                return;
+            }
+            // POST /runs/answer — deliver a human answer to a paused gate question
+            if (method === 'POST' && url === '/runs/answer') {
+                if (!checkAuth(req, res, authToken))
+                    return;
+                let raw;
+                try {
+                    raw = await readBody(req);
+                }
+                catch (err) {
+                    if (err instanceof Error && err.message === 'request body too large') {
+                        jsonResponse(res, 413, { error: err.message });
+                    }
+                    else {
+                        jsonResponse(res, 400, { error: 'failed to read request body' });
+                    }
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    jsonResponse(res, 400, { error: 'Invalid JSON body' });
+                    return;
+                }
+                if (typeof parsed !== 'object' ||
+                    parsed === null ||
+                    typeof parsed['runId'] !== 'string' ||
+                    typeof parsed['questionId'] !== 'string' ||
+                    !['approve', 'reject', 'modify'].includes(String(parsed['decision']))) {
+                    jsonResponse(res, 400, { error: 'Invalid body: requires runId (string), questionId (string), decision ("approve"|"reject"|"modify")' });
+                    return;
+                }
+                const body = parsed;
+                const runId = body['runId'];
+                const questionId = body['questionId'];
+                const decision = body['decision'];
+                const note = typeof body['note'] === 'string' ? body['note'] : undefined;
+                const entry = runRegistry.get(runId);
+                if (!entry) {
+                    jsonResponse(res, 404, { error: `unknown run: ${runId}` });
+                    return;
+                }
+                const resumed = entry.gate.answer(questionId, decision, note);
+                if (!resumed) {
+                    jsonResponse(res, 404, { error: 'unknown question' });
+                    return;
+                }
+                entry.emitter.questionAnswered({
+                    questionId,
+                    decision,
+                    ...(note !== undefined ? { note } : {}),
+                });
+                jsonResponse(res, 200, { ok: true, resumed });
+                return;
+            }
+            // GET /runs — summaries of past runs
+            if (method === 'GET' && url === '/runs') {
+                jsonResponse(res, 200, { runs: listRuns(runsDir) });
+                return;
+            }
+            // GET /runs/:id — full detail for one run
+            if (method === 'GET' && url.startsWith('/runs/')) {
+                const runId = decodeURIComponent(url.slice('/runs/'.length).split('?')[0]);
+                const detail = readRun(runsDir, runId);
+                if (!detail) {
+                    jsonResponse(res, 404, { error: `Run not found: ${runId}` });
+                    return;
+                }
+                jsonResponse(res, 200, detail);
+                return;
+            }
+            // POST /agents/:id/run — run ONE agent end-to-end via its real run()
+            // (the product's agent cognition), not the /execute executor primitive.
+            // Auth-gated like /execute; 503 when no runner is configured.
+            {
+                const runMatch = method === 'POST' ? url.split('?')[0].match(/^\/agents\/(\d+)\/run$/) : null;
+                if (runMatch) {
+                    if (!checkAuth(req, res, authToken))
+                        return;
+                    if (!agentRunner) {
+                        jsonResponse(res, 503, { error: 'no agent runner configured' });
+                        return;
+                    }
+                    const agentId = Number(runMatch[1]);
+                    try {
+                        const result = await agentRunner(agentId);
+                        jsonResponse(res, 200, result);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        if (msg.includes('not registered')) {
+                            jsonResponse(res, 404, { error: `unknown agent ${agentId}` });
+                        }
+                        else {
+                            // Log server-side; return generic (stack-trace-exposure hardening).
+                            console.error(`[bridge] agent ${agentId} run failed:`, msg);
+                            jsonResponse(res, 500, { error: 'agent run failed' });
+                        }
+                    }
+                    return;
+                }
+            }
+            // POST /execute
+            if (method === 'POST' && url === '/execute') {
+                if (!checkAuth(req, res, authToken))
+                    return;
+                let raw;
+                try {
+                    raw = await readBody(req);
+                }
+                catch (err) {
+                    if (err instanceof Error && err.message === 'request body too large') {
+                        jsonResponse(res, 413, { success: false, error: err.message, durationMs: 0 });
+                    }
+                    else {
+                        jsonResponse(res, 400, { success: false, error: 'failed to read request body', durationMs: 0 });
+                    }
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    jsonResponse(res, 400, { success: false, error: 'Invalid JSON body', durationMs: 0 });
+                    return;
+                }
+                if (!isValidBridgeTask(parsed)) {
+                    jsonResponse(res, 400, {
+                        success: false,
+                        error: 'Invalid BridgeTask: requires agentId (number), agentName (string), executorType, and config (object)',
+                        durationMs: 0,
+                    });
+                    return;
+                }
+                // Executor-specific config-shape gate: reject a structurally-wrong config
+                // (e.g. shell with no command) with a clear 400 instead of a deep 500.
+                const shapeErr = configShapeError(parsed);
+                if (shapeErr) {
+                    jsonResponse(res, 400, { success: false, error: `Invalid config: ${shapeErr}`, durationMs: 0 });
+                    return;
+                }
+                const task = parsed;
+                const result = await router.execute(task);
+                jsonResponse(res, result.success ? 200 : 500, result);
+                return;
+            }
+            // 404 for anything else
+            jsonResponse(res, 404, { error: 'Not found' });
+        }
+        catch (error) {
+            // Log the real error server-side; return a generic message so internal
+            // details / stack traces are not exposed to the client (CodeQL js/stack-trace-exposure).
+            console.error('Bridge server request failed:', toSafeLogMessage(error));
+            jsonResponse(res, 500, { success: false, error: 'Internal server error', durationMs: 0 });
+        }
+    });
+    // Periodically drop expired rate-limit entries so the keyed map can't grow
+    // unbounded under IP churn (memory-exhaustion DoS). unref() so it never keeps the
+    // process alive; cleared on server close so tests/short-lived servers don't leak timers.
+    if (limiter) {
+        const pruneTimer = setInterval(() => limiter.prune(Date.now()), 5 * 60_000);
+        pruneTimer.unref();
+        server.on('close', () => clearInterval(pruneTimer));
+    }
+    return server;
+}
+/**
+ * Start the Bridge HTTP server on the given port.
+ * Returns the server instance for graceful shutdown.
+ */
+export function startBridgeServer(port = 3310, options = {}) {
+    const server = createBridgeServer({ ...options, port });
+    server.listen(port, () => {
+        console.log(`TestTeam Bridge running on http://localhost:${port}`);
+        if (!options.runStreamDriver) {
+            // Surfacing this loudly prevents the silent-503 class: without a driver the
+            // dashboard's live-pipeline view + Screencast target a dead GET /runs/stream.
+            console.log('  ⚠ live pipeline (GET /runs/stream) disabled — no run driver configured');
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map