@nac3/forge-cli 0.2.0-alpha.1

package/dist/chat/server.js

@@ -0,0 +1,1540 @@
+/**
+ * Yujin Forge -- chat panel HTTP server.
+ *
+ * Routes (all on the local loopback port; CORS not needed):
+ *
+ *   GET  /                serves the panel HTML
+ *   GET  /api/health      { ok: true, version, project }
+ *   POST /api/chat        { messages } -> { ok, message }
+ *
+ * The server binds to 127.0.0.1 only -- never 0.0.0.0. Forge
+ * chat is a local-developer tool; exposing it on the LAN would
+ * leak the API key + the project source-aware system prompt.
+ */
+import { createServer } from 'node:http';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ClaudeClient, ConfigurationError, ClaudeApiError } from './claude.js';
+import { renderPanelHtml } from './panel.js';
+import { TranscriptStore } from './persistence.js';
+import { FORGE_TOOL_SPECS, runForgeTool } from './tools.js';
+import { Vault } from '../vault/store.js';
+import { SLOT_CATALOG, SLOT_KINDS } from '../vault/catalog.js';
+import { resolveMode, persistMode, modePromptSuffix, FORGE_MODES, } from '../core/mode.js';
+import { resolveTarget, persistTarget, normaliseTarget, FORGE_TARGETS, } from '../core/target.js';
+import { readPilotState, completePilotSetup, welcomePromptSuffix, shouldAutoComplete, } from '../core/pilot_setup.js';
+import { readRegistry, upsertProject, setActive, activeSlug, deriveSlugFromPath, scanForProjects, } from '../core/projects.js';
+import { configDir } from '../license/index.js';
+import { VoiceRouter } from '../voice/router.js';
+import { buildDefaultRegistry } from '../voice/registry.js';
+import { matchReaderIntent } from '../voice/intents.js';
+import { setRecapSummarizer } from './tools/reader.js';
+import { parseDocument } from '../reader/registry.js';
+import { SUPPORTED_LANGUAGES, LANGUAGE_DISPLAY_NAMES, BCP47, getCatalog, setLanguage, currentLanguage, normaliseLanguageTag, } from '../i18n/index.js';
+import { listAvailableManuals } from './tools/manual.js';
+import { recordIngest, getIngest, setExtraction, setPlan, setScaffold, clearScaffold, listIngest } from './ingest_session.js';
+import { extractSpec } from './spec_extract.js';
+import { generatePlan } from './spec_plan.js';
+import { executeScaffold, rollbackScaffold } from './spec_scaffold.js';
+import { VERSION } from '../version.js';
+export async function startChatServer(opts) {
+    const projectName = await readProjectName(opts.projectRoot);
+    const claude = opts.claude ?? new ClaudeClient();
+    const voice = opts.voice ?? new VoiceRouter({
+        configDir: configDir(),
+        registry: buildDefaultRegistry(),
+    });
+    const store = new TranscriptStore(opts.projectRoot, VERSION);
+    /* V1.26b -- install the Claude-backed recap summariser so
+       forge.reader.recap({mode:'summary'}) can call it. The
+       reader still gates via env var YF_ENABLE_CLAUDE_RECAP=1
+       before actually invoking; this just makes the function
+       available. */
+    setRecapSummarizer(async (blocks, options) => {
+        const lang = options.language || 'es';
+        /* i18n-exempt: developer-facing system prompt that
+           instructs Claude in Spanish; Claude understands it and
+           is asked to respond in `lang`. Not surfaced to the user. */
+        const sys = 'Sos un resumidor breve. Te paso una lista de bloques de texto que el usuario acaba de escuchar via reader. '
+            + 'Devolves un resumen de 1 a 2 oraciones en idioma ' + lang + ', sin agregar informacion que no este en los bloques. '
+            + 'Sin vinetas. Solo prosa breve y clara.';
+        const reply = await claude.chat({
+            messages: [
+                { role: 'user', content: 'Resumi estos bloques:\n\n' + blocks.map((b, i) => '[' + (i + 1) + '] ' + b).join('\n') },
+            ],
+            system: sys,
+            maxTokens: 200,
+        });
+        return reply.text.trim();
+    });
+    const server = createServer(async (req, res) => {
+        // Every response carries a request-id (for client + server
+        // log correlation) + cache-control (we never want browsers
+        // to cache panel HTML / API responses since the panel is
+        // dynamic). Anti-debt headers requested in the 600-suite
+        // followup list -- see docs/CROSS_BROWSER_REPORT_600.md.
+        const requestId = generateRequestId();
+        res.setHeader('x-request-id', requestId);
+        res.setHeader('cache-control', 'no-store, must-revalidate');
+        res.setHeader('x-yujin-version', VERSION);
+        try {
+            await route(req, res, {
+                projectRoot: opts.projectRoot,
+                projectName,
+                port: opts.port,
+                claude,
+                voice,
+                store,
+            });
+        }
+        catch (err) {
+            sendJson(res, 500, {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                request_id: requestId,
+            });
+        }
+    });
+    // Aggressive socket cleanup. Default keepAliveTimeout (5s)
+    // can keep sockets pending when the panel is in a test or
+    // headless context that does not close them gracefully. The
+    // 600-suite followup observed force-killed webkit workers
+    // when the suite ended -- shorter timeouts let Node drop the
+    // sockets cleanly so Playwright cleanup is immediate.
+    server.keepAliveTimeout = 1000;
+    server.headersTimeout = 5000;
+    server.requestTimeout = 30000;
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port, '127.0.0.1', () => resolve());
+    });
+    const url = 'http://127.0.0.1:' + opts.port + '/';
+    return {
+        server,
+        url,
+        store,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+        }),
+    };
+}
+async function route(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    if (req.method === 'GET' && url.pathname === '/') {
+        // Stateless lang resolution: query string > cookie >
+        // server-wide setLanguage. This isolates per-request
+        // rendering so concurrent clients with different langs
+        // do not race on the shared current_language state.
+        const reqLang = resolveRequestLang(req, url);
+        res.statusCode = 200;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.end(renderPanelHtml({
+            projectRoot: ctx.projectRoot,
+            projectName: ctx.projectName,
+            port: ctx.port,
+            lang: reqLang,
+        }));
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/health') {
+        sendJson(res, 200, {
+            ok: true,
+            version: VERSION,
+            project: { name: ctx.projectName, root: ctx.projectRoot },
+        });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/chat') {
+        await handleChat(req, res, ctx);
+        return;
+    }
+    /* Vault surface (V0.4 of HITO 0). Same-origin: the server only
+       listens on 127.0.0.1 and the browser blocks cross-origin
+       fetches from other sites by default (no CORS headers set).
+       Plaintext NEVER returns through any of these endpoints --
+       only set accepts it, and only list/has/info return metadata. */
+    if (req.method === 'GET' && url.pathname === '/api/vault/list') {
+        await handleVaultList(res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/vault/set') {
+        await handleVaultSet(req, res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/vault/remove') {
+        await handleVaultRemove(req, res);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname.startsWith('/api/vault/has/')) {
+        const slot = url.pathname.slice('/api/vault/has/'.length);
+        await handleVaultHas(res, slot);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/vault/catalog') {
+        await handleVaultCatalog(res, url);
+        return;
+    }
+    /* SQ 0.8 -- dual mode read/write. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/mode') {
+        await handleModeGet(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/mode') {
+        await handleModeSet(req, res, ctx);
+        return;
+    }
+    /* SQ 0.10 -- pre-dev target query + persistence. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/target') {
+        await handleTargetGet(res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/target') {
+        await handleTargetSet(req, res, ctx);
+        return;
+    }
+    /* PLAN #10 -- project registry endpoints. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/projects') {
+        await handleProjectsList(res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/projects/active') {
+        await handleProjectsSwitch(req, res);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/projects/active') {
+        await handleProjectsActive(res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/projects/scan') {
+        await handleProjectsScan(req, res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/projects/add') {
+        await handleProjectsAdd(req, res);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname.startsWith('/api/vault/test/')) {
+        const slot = url.pathname.slice('/api/vault/test/'.length);
+        await handleVaultTest(req, res, slot);
+        return;
+    }
+    /* Voice surface (V1.5 of HITO 1). Same-origin only (loopback +
+       no CORS). Audio bytes flow on /stt; JSON on /tts; the response
+       is binary audio. */
+    if (req.method === 'GET' && url.pathname === '/api/voice/config') {
+        await handleVoiceConfigGet(res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/voice/config') {
+        await handleVoiceConfigSet(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/voice/stt') {
+        await handleVoiceStt(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/voice/tts') {
+        await handleVoiceTts(req, res, ctx);
+        return;
+    }
+    /* Direct reader-tool dispatch (V1.32). The voice intent matcher
+       surfaces a tool + args on the STT response; this endpoint
+       lets the client execute it without a Claude round-trip.
+       Whitelisted to forge.reader.* only -- write-class tools
+       (git_commit, git_push, run_app, create_github_repo, ...)
+       are NOT reachable here, they keep their approval flow
+       through /api/chat. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/tool') {
+        await handleForgeToolDispatch(req, res, ctx);
+        return;
+    }
+    /* Spec doc ingest (V1.37 + V1.38 -- bloque 4.5 scaffolding).
+       Client uploads a spec file (PDF / DOCX / HTML / md / ...)
+       and the server parses it via the existing reader pipeline,
+       returning the NormalisedDocument shape. Real plan-building
+       + file scaffolding lands in V1.41..V1.46. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest') {
+        await handleForgeIngest(req, res, ctx);
+        return;
+    }
+    /* Spec extraction via Claude (V1.40). After an ingest, the
+       panel calls this to ask Claude for structured
+       requirements/entities/endpoints/components. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest/extract') {
+        await handleForgeIngestExtract(req, res, ctx);
+        return;
+    }
+    /* List active ingest sessions (V1.40 -- for debugging + the
+       panel's "previously ingested" picker, future slice). */
+    if (req.method === 'GET' && url.pathname === '/api/forge/ingest') {
+        sendJson(res, 200, { ok: true, sessions: listIngest() });
+        return;
+    }
+    /* Plan generation (V1.41). Asks Claude to convert the V1.40
+       extraction into a concrete file scaffold plan. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest/plan') {
+        await handleForgeIngestPlan(req, res, ctx);
+        return;
+    }
+    /* Scaffold approval + execution (V1.42 + V1.43). The body
+       must include {doc_id, approve:true}; only then does the
+       scaffolder touch the filesystem. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest/scaffold') {
+        await handleForgeIngestScaffold(req, res, ctx);
+        return;
+    }
+    /* Progress stream (V1.44). Server-sent events fire as the
+       scaffolder writes each file. The handler does the same
+       work as /scaffold but emits incremental updates. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest/scaffold/stream') {
+        await handleForgeIngestScaffoldStream(req, res, ctx);
+        return;
+    }
+    /* Rollback (V1.45). Undoes a scaffold via its recorded
+       rollback log. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/ingest/rollback') {
+        await handleForgeIngestRollback(req, res, ctx);
+        return;
+    }
+    /* i18n surface (Fase F.3). The panel uses these to populate
+       the language selector + drive the current panel language. */
+    if (req.method === 'GET' && url.pathname === '/api/i18n/languages') {
+        const available = await listAvailableManuals();
+        sendJson(res, 200, {
+            ok: true,
+            current: currentLanguage(),
+            languages: SUPPORTED_LANGUAGES.map((l) => ({
+                code: l,
+                display: LANGUAGE_DISPLAY_NAMES[l],
+                bcp47: BCP47[l],
+                manual_available: available.includes(l),
+            })),
+        });
+        return;
+    }
+    if (req.method === 'GET' && url.pathname.startsWith('/api/i18n/catalog/')) {
+        const langRaw = url.pathname.slice('/api/i18n/catalog/'.length);
+        const lang = normaliseLanguageTag(langRaw);
+        sendJson(res, 200, {
+            ok: true,
+            lang,
+            catalog: getCatalog(lang),
+        });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/i18n/language') {
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+            return;
+        }
+        if (!body || typeof body.lang !== 'string') {
+            sendJson(res, 400, { ok: false, error: 'lang (string) required' });
+            return;
+        }
+        const resolved = setLanguage(body.lang);
+        sendJson(res, 200, { ok: true, current: resolved });
+        return;
+    }
+    sendJson(res, 404, { ok: false, error: 'not found' });
+}
+const SUPPORTED_STT_FORMATS = new Set(['webm', 'ogg', 'wav', 'mp3', 'flac', 'mp4']);
+const SUPPORTED_TTS_FORMATS = new Set(['mp3', 'wav', 'ogg', 'opus']);
+/** Cap audio uploads at 25 MB. Larger payloads usually mean a
+ *  recording loop got stuck; refuse loudly so the panel surfaces
+ *  the problem instead of OOMing the server. */
+const STT_MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+const TTS_AUDIO_MIME = {
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    opus: 'audio/ogg',
+};
+async function handleVoiceConfigGet(res, ctx) {
+    try {
+        const cfg = await ctx.voice.loadConfig();
+        const providers = ctx.voice.registeredProviders();
+        sendJson(res, 200, { ok: true, config: cfg, providers });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVoiceConfigSet(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body !== 'object') {
+        sendJson(res, 400, { ok: false, error: 'body must be a VoiceConfig object' });
+        return;
+    }
+    const cfg = body;
+    if (!cfg.stt || !cfg.tts) {
+        sendJson(res, 400, { ok: false, error: 'config must include stt + tts blocks' });
+        return;
+    }
+    try {
+        await ctx.voice.saveConfig(cfg);
+        sendJson(res, 200, { ok: true, config: cfg });
+    }
+    catch (err) {
+        sendJson(res, 400, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVoiceStt(req, res, ctx) {
+    const format = String(req.headers['x-audio-format'] ?? '').toLowerCase();
+    if (!SUPPORTED_STT_FORMATS.has(format)) {
+        sendJson(res, 400, {
+            ok: false,
+            error: 'X-Audio-Format header missing or unsupported. Supported: '
+                + Array.from(SUPPORTED_STT_FORMATS).join(', '),
+        });
+        return;
+    }
+    const languageHint = typeof req.headers['x-audio-language'] === 'string'
+        ? String(req.headers['x-audio-language'])
+        : undefined;
+    let audio;
+    try {
+        audio = await readBinaryBody(req, STT_MAX_AUDIO_BYTES);
+    }
+    catch (err) {
+        sendJson(res, 413, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    if (audio.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'audio body is empty' });
+        return;
+    }
+    /* Optional active document hint (V1.31). Lets the voice intent
+       matcher resolve commands like "siguiente" or "buscar X" against
+       the currently-open reader session. Client sets this header to
+       the doc_id returned by the last forge.reader.open call. */
+    const activeDocId = typeof req.headers['x-active-doc-id'] === 'string'
+        ? String(req.headers['x-active-doc-id']).trim()
+        : '';
+    try {
+        const result = await ctx.voice.transcribe({
+            audio,
+            format: format,
+            ...(languageHint ? { languageHint } : {}),
+        });
+        /* Reader intent shortcut (V1.31). After successful STT, try
+           to match the transcript against the reader-intent
+           catalogue. On a hit, surface the proposed tool + args so
+           the client can dispatch directly without a Claude
+           round-trip. On a miss, matched_intent is null and the
+           client passes the transcript to Claude as before. */
+        const matched = matchReaderIntent(result.text, {
+            ...(activeDocId ? { active_doc_id: activeDocId } : {}),
+        });
+        sendJson(res, 200, {
+            ok: true,
+            transcript: result,
+            matched_intent: matched,
+        });
+    }
+    catch (err) {
+        sendJson(res, 502, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Allow-list for the V1.32 direct-dispatch endpoint. Only
+ * read-only reader tools are exposed here. Any write-class
+ * tool (commit / push / run / repo create / branch switch /
+ * file write) MUST go through /api/chat so the approval flow
+ * runs.
+ */
+const FORGE_TOOL_DIRECT_ALLOWLIST = new Set([
+    'forge.reader.open',
+    'forge.reader.list_documents',
+    'forge.reader.read_section',
+    'forge.reader.next_block',
+    'forge.reader.search',
+    'forge.reader.bookmark_set',
+    'forge.reader.bookmark_jump',
+    'forge.reader.recap',
+    /* Fase F.8 -- HTML user manuals in 10 languages. Read-only,
+       same safety profile as the reader tools. */
+    'forge.manual.open',
+]);
+async function handleForgeToolDispatch(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.tool !== 'string' || typeof body.args !== 'object' || body.args === null) {
+        sendJson(res, 400, { ok: false, error: 'tool (string) + args (object) required' });
+        return;
+    }
+    if (!FORGE_TOOL_DIRECT_ALLOWLIST.has(body.tool)) {
+        /* Loud refusal. The caller picked a tool that requires
+           approval flow; route them to /api/chat instead. */
+        sendJson(res, 403, {
+            ok: false,
+            error: 'tool not allowed via direct dispatch (use /api/chat for approval-gated tools): ' + body.tool,
+        });
+        return;
+    }
+    try {
+        const r = await runForgeTool(body.tool, body.args, { projectRoot: ctx.projectRoot });
+        sendJson(res, 200, {
+            ok: true,
+            tool: body.tool,
+            result: r.result,
+            is_error: r.is_error ?? false,
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/** V1.37 + V1.38 -- ingest a spec doc via drag-drop / upload.
+ *
+ * Accepts POST with:
+ *   - Header X-Filename: the original filename (used for
+ *     extension-based format detection + slug).
+ *   - Body: raw binary file contents (up to INGEST_MAX_BYTES).
+ *
+ * Pipeline:
+ *   1. Read the binary body.
+ *   2. detectFormat(filename, buffer) -> auto-detects format.
+ *   3. parseDocument({...}) -> NormalisedDocument.
+ *   4. Return summary: title, format, sections count, byte
+ *      count, language, first 3 paragraph excerpts.
+ *
+ * Does NOT persist the file or open a reader session yet --
+ * that's V1.39+ (plan building + scaffold). For V1.37/V1.38
+ * the endpoint is a single-shot parse so the panel can confirm
+ * "yes, Forge can read this spec" before the user commits to
+ * the full ingest flow.
+ */
+const INGEST_MAX_BYTES = 32 * 1024 * 1024;
+async function handleForgeIngest(req, res, ctx) {
+    const filenameHdr = req.headers['x-filename'];
+    const filename = typeof filenameHdr === 'string' && filenameHdr.trim() !== ''
+        ? filenameHdr.trim()
+        : 'spec.bin';
+    /* Basic filename sanitisation: forbid path separators so an
+       attacker cannot use this endpoint to scribble outside any
+       directory we might later derive from the name. */
+    if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+        sendJson(res, 400, {
+            ok: false,
+            error: 'X-Filename must not contain path separators or "..".',
+        });
+        return;
+    }
+    let buffer;
+    try {
+        buffer = await readBinaryBody(req, INGEST_MAX_BYTES);
+    }
+    catch (err) {
+        sendJson(res, 413, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    if (buffer.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'body is empty' });
+        return;
+    }
+    try {
+        const doc = await parseDocument({ filename, buffer });
+        /* V1.40 -- record the session so /extract + /plan +
+           /scaffold can read it later. */
+        recordIngest(doc);
+        /* Compose a compact summary the panel can render. */
+        const firstParas = [];
+        for (const s of doc.sections) {
+            for (const b of s.blocks) {
+                if (b.kind === 'paragraph') {
+                    firstParas.push(b.text);
+                    if (firstParas.length >= 3)
+                        break;
+                }
+            }
+            if (firstParas.length >= 3)
+                break;
+        }
+        sendJson(res, 200, {
+            ok: true,
+            ingested: {
+                doc_id: doc.id,
+                filename: doc.filename,
+                format: doc.format,
+                bytes: doc.bytes,
+                title: doc.title,
+                language: doc.language ?? null,
+                sections: doc.sections.length,
+                first_paragraphs: firstParas,
+            },
+        });
+    }
+    catch (err) {
+        sendJson(res, 422, {
+            ok: false,
+            error: 'parse failed: ' + (err instanceof Error ? err.message : String(err)),
+        });
+    }
+}
+/** V1.40 -- run Claude extraction on a previously ingested spec. */
+async function handleForgeIngestExtract(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.doc_id !== 'string' || body.doc_id.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'doc_id (non-empty string) required' });
+        return;
+    }
+    const session = getIngest(body.doc_id);
+    if (!session) {
+        sendJson(res, 404, { ok: false, error: 'no ingest session for doc_id ' + body.doc_id });
+        return;
+    }
+    /* If the extraction was already computed and the caller did
+       not pass force=true, return the cached value. */
+    if (session.extraction && body.force !== true) {
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            extraction: session.extraction,
+            cached: true,
+        });
+        return;
+    }
+    try {
+        const opts = {
+            title: session.doc.title,
+            text: session.flat_text,
+        };
+        if (session.doc.language)
+            opts.language = session.doc.language;
+        const extraction = await extractSpec(ctx.claude, opts);
+        setExtraction(session.doc_id, extraction);
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            extraction,
+            cached: false,
+        });
+    }
+    catch (err) {
+        sendJson(res, 502, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/** V1.41 -- generate a file scaffold plan from a previously
+ *  extracted spec. Requires the extraction (V1.40) to exist;
+ *  if not, returns a clear 409 telling the caller to run
+ *  extract first. */
+async function handleForgeIngestPlan(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.doc_id !== 'string' || body.doc_id.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'doc_id (non-empty string) required' });
+        return;
+    }
+    const session = getIngest(body.doc_id);
+    if (!session) {
+        sendJson(res, 404, { ok: false, error: 'no ingest session for doc_id ' + body.doc_id });
+        return;
+    }
+    if (!session.extraction) {
+        sendJson(res, 409, {
+            ok: false,
+            error: 'no extraction yet for doc_id ' + body.doc_id
+                + ' -- call POST /api/forge/ingest/extract first',
+        });
+        return;
+    }
+    if (session.plan && body.force !== true) {
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            plan: session.plan,
+            cached: true,
+        });
+        return;
+    }
+    try {
+        const opts = {
+            extraction: session.extraction,
+            title: session.doc.title,
+        };
+        if (session.doc.language)
+            opts.language = session.doc.language;
+        const plan = await generatePlan(ctx.claude, opts);
+        setPlan(session.doc_id, plan);
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            plan,
+            cached: false,
+        });
+    }
+    catch (err) {
+        sendJson(res, 502, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/** V1.42 + V1.43 -- approve + execute the scaffold plan.
+ *  The approve flag is required + must be true. */
+async function handleForgeIngestScaffold(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.doc_id !== 'string' || body.doc_id.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'doc_id (non-empty string) required' });
+        return;
+    }
+    if (body.approve !== true) {
+        sendJson(res, 403, {
+            ok: false,
+            error: 'scaffold requires explicit {approve: true} in the body. This step writes files to disk; deliberate gating prevents accidental scaffolds.',
+        });
+        return;
+    }
+    const session = getIngest(body.doc_id);
+    if (!session) {
+        sendJson(res, 404, { ok: false, error: 'no ingest session for doc_id ' + body.doc_id });
+        return;
+    }
+    if (!session.plan) {
+        sendJson(res, 409, {
+            ok: false,
+            error: 'no plan yet for doc_id ' + body.doc_id
+                + ' -- call POST /api/forge/ingest/plan first',
+        });
+        return;
+    }
+    try {
+        const force = body.force === true;
+        const report = await executeScaffold({
+            plan: session.plan,
+            projectRoot: ctx.projectRoot,
+            force,
+        });
+        setScaffold(session.doc_id, report);
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            created: report.created,
+            overwritten: report.overwritten,
+            skipped: report.skipped,
+            errors: report.errors,
+            total_writes: report.rollback_log.length,
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/** V1.44 -- stream scaffold progress as Server-Sent Events.
+ *  Same approval gate as /scaffold; each ProgressEvent fires
+ *  as a separate SSE message so the panel can update a live
+ *  progress bar. */
+async function handleForgeIngestScaffoldStream(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.doc_id !== 'string' || body.doc_id.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'doc_id (non-empty string) required' });
+        return;
+    }
+    if (body.approve !== true) {
+        sendJson(res, 403, {
+            ok: false,
+            error: 'scaffold/stream requires explicit {approve: true} in the body.',
+        });
+        return;
+    }
+    const session = getIngest(body.doc_id);
+    if (!session) {
+        sendJson(res, 404, { ok: false, error: 'no ingest session for doc_id ' + body.doc_id });
+        return;
+    }
+    if (!session.plan) {
+        sendJson(res, 409, {
+            ok: false,
+            error: 'no plan yet for doc_id ' + body.doc_id,
+        });
+        return;
+    }
+    /* Switch to SSE response. */
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/event-stream; charset=utf-8');
+    res.setHeader('cache-control', 'no-cache');
+    res.setHeader('connection', 'keep-alive');
+    const force = body.force === true;
+    try {
+        const report = await executeScaffold({
+            plan: session.plan,
+            projectRoot: ctx.projectRoot,
+            force,
+            onProgress: (ev) => {
+                try {
+                    res.write('event: progress\ndata: ' + JSON.stringify(ev) + '\n\n');
+                }
+                catch {
+                    /* connection closed mid-stream -- the scaffolder
+                       keeps writing, we just stop emitting. */
+                }
+            },
+        });
+        setScaffold(session.doc_id, report);
+        res.write('event: complete\ndata: ' + JSON.stringify({
+            doc_id: session.doc_id,
+            created: report.created,
+            overwritten: report.overwritten,
+            skipped: report.skipped,
+            errors: report.errors,
+            total_writes: report.rollback_log.length,
+        }) + '\n\n');
+        res.end();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        try {
+            res.write('event: error\ndata: ' + JSON.stringify({ error: msg }) + '\n\n');
+        }
+        catch { /* connection already closed */ }
+        res.end();
+    }
+}
+/** V1.45 -- rollback a scaffold. */
+async function handleForgeIngestRollback(req, res, ctx) {
+    /* ctx is needed for projectRoot validation in the future; */
+    /* unused for now keeps the signature parallel to siblings. */
+    void ctx;
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.doc_id !== 'string' || body.doc_id.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'doc_id (non-empty string) required' });
+        return;
+    }
+    const session = getIngest(body.doc_id);
+    if (!session) {
+        sendJson(res, 404, { ok: false, error: 'no ingest session for doc_id ' + body.doc_id });
+        return;
+    }
+    if (!session.scaffold) {
+        sendJson(res, 409, {
+            ok: false,
+            error: 'no scaffold to rollback for doc_id ' + body.doc_id,
+        });
+        return;
+    }
+    try {
+        const result = await rollbackScaffold(session.scaffold.rollback_log);
+        clearScaffold(session.doc_id);
+        sendJson(res, 200, {
+            ok: true,
+            doc_id: session.doc_id,
+            undone: result.undone,
+            errors: result.errors,
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVoiceTts(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (!body || typeof body.text !== 'string' || body.text.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'text (non-empty string) required' });
+        return;
+    }
+    if (body.format !== undefined && !SUPPORTED_TTS_FORMATS.has(body.format)) {
+        sendJson(res, 400, {
+            ok: false,
+            error: 'format unsupported. Supported: ' + Array.from(SUPPORTED_TTS_FORMATS).join(', '),
+        });
+        return;
+    }
+    try {
+        const result = await ctx.voice.synthesize({
+            text: body.text,
+            ...(body.voice ? { voice: String(body.voice) } : {}),
+            ...(typeof body.speed === 'number' ? { speed: body.speed } : {}),
+            ...(body.language ? { language: String(body.language) } : {}),
+            ...(body.format ? { format: body.format } : {}),
+            ...(body.ssml === true ? { ssml: true } : {}),
+        });
+        res.statusCode = 200;
+        res.setHeader('content-type', TTS_AUDIO_MIME[result.format]);
+        res.setHeader('content-length', String(result.audio.length));
+        res.setHeader('x-voice-provider', result.provider);
+        res.setHeader('x-voice-voice', result.voice);
+        res.setHeader('x-voice-latency-ms', String(result.latency_ms));
+        res.end(result.audio);
+    }
+    catch (err) {
+        sendJson(res, 502, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVaultList(res) {
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        sendJson(res, 200, { ok: true, slots: vault.list() });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVaultSet(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.slot !== 'string' || typeof body.plaintext !== 'string') {
+        sendJson(res, 400, { ok: false, error: 'slot + plaintext (both strings) required' });
+        return;
+    }
+    /* Optional kind / expiry validation. */
+    let kindOpt;
+    if (body.kind !== undefined) {
+        if (typeof body.kind !== 'string' || !SLOT_KINDS.includes(body.kind)) {
+            sendJson(res, 400, { ok: false, error: 'invalid kind. Allowed: ' + SLOT_KINDS.join(', ') });
+            return;
+        }
+        kindOpt = body.kind;
+    }
+    let expiryOpt;
+    if (body.expiry === null) {
+        expiryOpt = null;
+    }
+    else if (body.expiry !== undefined) {
+        if (typeof body.expiry !== 'string') {
+            sendJson(res, 400, { ok: false, error: 'expiry must be a string ISO 8601 or null' });
+            return;
+        }
+        const d = new Date(body.expiry);
+        if (isNaN(d.getTime())) {
+            sendJson(res, 400, { ok: false, error: 'expiry is not a valid ISO 8601 timestamp' });
+            return;
+        }
+        expiryOpt = d.toISOString();
+    }
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        await vault.set(body.slot, body.plaintext, {
+            ...(kindOpt ? { kind: kindOpt } : {}),
+            ...(expiryOpt !== undefined ? { expiry: expiryOpt } : {}),
+        });
+        /* Echo metadata only -- never the plaintext, never the
+           ciphertext. The 4-char prefix on list() is the only
+           visible confirmation. */
+        const meta = vault.list().find((s) => s.name === body.slot);
+        sendJson(res, 200, { ok: true, slot: meta });
+    }
+    catch (err) {
+        sendJson(res, 400, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVaultCatalog(res, url) {
+    const kindFilter = url.searchParams.get('kind');
+    let entries = SLOT_CATALOG;
+    if (kindFilter && SLOT_KINDS.includes(kindFilter)) {
+        entries = entries.filter((e) => e.kind === kindFilter);
+    }
+    sendJson(res, 200, {
+        ok: true,
+        slots: entries.map((e) => ({
+            name: e.name, kind: e.kind, description: e.description,
+            ...(e.obtainUrl ? { obtain_url: e.obtainUrl } : {}),
+            has_probe: !!e.test,
+        })),
+    });
+}
+async function handleModeGet(req, res, ctx) {
+    const mode = await resolveModeForRequest(req, ctx.projectRoot);
+    const projectResolved = await resolveMode({ projectRoot: ctx.projectRoot });
+    sendJson(res, 200, {
+        ok: true,
+        mode,
+        source: projectResolved.source,
+        available: FORGE_MODES,
+    });
+}
+async function handleModeSet(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.mode !== 'string' || !FORGE_MODES.includes(body.mode)) {
+        sendJson(res, 400, { ok: false, error: 'mode must be one of: ' + FORGE_MODES.join(', ') });
+        return;
+    }
+    const mode = body.mode;
+    try {
+        await persistMode(ctx.projectRoot, mode);
+    }
+    catch (err) {
+        sendJson(res, 500, { ok: false,
+            error: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    /* Set cookie so the next request renders in the new mode
+       even before the user reloads. The cookie is the source of
+       truth for the running browser; the persisted file is the
+       source of truth for the NEXT session. */
+    res.setHeader('set-cookie', 'yf-mode=' + mode + '; Path=/; Max-Age=' + (60 * 60 * 24 * 365) + '; SameSite=Lax');
+    sendJson(res, 200, { ok: true, mode });
+}
+async function handleProjectsList(res) {
+    const reg = await readRegistry();
+    sendJson(res, 200, { ok: true, registry: reg });
+}
+async function handleProjectsActive(res) {
+    const slug = await activeSlug();
+    const reg = await readRegistry();
+    const entry = slug ? reg.projects.find((p) => p.slug === slug) : null;
+    sendJson(res, 200, { ok: true, active: slug, project: entry ?? null });
+}
+async function handleProjectsSwitch(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+        return;
+    }
+    if (typeof body.slug !== 'string') {
+        sendJson(res, 400, { ok: false, error: 'slug (string) required' });
+        return;
+    }
+    try {
+        const reg = await setActive(body.slug);
+        sendJson(res, 200, { ok: true, active: reg.active_slug, registry: reg });
+    }
+    catch (err) {
+        sendJson(res, 404, { ok: false,
+            error: err instanceof Error ? err.message : String(err) });
+    }
+}
+async function handleProjectsScan(req, res) {
+    let body;
+    try {
+        const raw = await readBody(req);
+        body = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+        return;
+    }
+    const candidates = typeof body.root === 'string'
+        ? [body.root]
+        : [process.env.HOME ?? '', '/tmp'].filter((s) => s.length > 0);
+    let found = 0;
+    for (const root of candidates) {
+        const matches = await scanForProjects(root, 4);
+        for (const projPath of matches) {
+            const slug = await deriveSlugFromPath(projPath);
+            await upsertProject({ slug, path: projPath });
+            found += 1;
+        }
+    }
+    const reg = await readRegistry();
+    sendJson(res, 200, { ok: true, found, registry: reg });
+}
+async function handleProjectsAdd(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+        return;
+    }
+    if (typeof body.path !== 'string') {
+        sendJson(res, 400, { ok: false, error: 'path (string) required' });
+        return;
+    }
+    const slug = await deriveSlugFromPath(body.path);
+    await upsertProject({ slug, path: body.path });
+    const reg = await readRegistry();
+    sendJson(res, 200, { ok: true, slug, registry: reg });
+}
+async function handleTargetGet(res, ctx) {
+    const r = await resolveTarget(ctx.projectRoot);
+    sendJson(res, 200, {
+        ok: true,
+        target: r.target,
+        feature_split: r.feature_split,
+        available: FORGE_TARGETS,
+        pending_question: r.target === null, /* Pilot uses this to know whether to prompt */
+    });
+}
+async function handleTargetSet(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const target = normaliseTarget(body.target);
+    if (!target) {
+        sendJson(res, 400, {
+            ok: false, error: 'target must be one of: ' + FORGE_TARGETS.join(', '),
+        });
+        return;
+    }
+    let featureSplitArg;
+    if (body.feature_split !== undefined && body.feature_split !== null) {
+        if (typeof body.feature_split !== 'object') {
+            sendJson(res, 400, { ok: false, error: 'feature_split must be an object' });
+            return;
+        }
+        featureSplitArg = body.feature_split;
+    }
+    try {
+        await persistTarget(ctx.projectRoot, target, featureSplitArg);
+    }
+    catch (err) {
+        sendJson(res, 500, { ok: false,
+            error: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    const r = await resolveTarget(ctx.projectRoot);
+    sendJson(res, 200, { ok: true, target: r.target, feature_split: r.feature_split });
+}
+async function handleVaultTest(req, res, slot) {
+    let timeoutMs = 5000;
+    /* Optional body for { timeout_ms }. */
+    try {
+        const raw = await readBody(req);
+        if (raw && raw.length > 0) {
+            const body = JSON.parse(raw);
+            if (typeof body.timeout_ms === 'number' && body.timeout_ms > 0 && body.timeout_ms <= 30000) {
+                timeoutMs = body.timeout_ms;
+            }
+        }
+    }
+    catch { /* ignore -- use default */ }
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        if (!vault.has(slot)) {
+            sendJson(res, 404, { ok: false, error: 'slot not found: ' + slot });
+            return;
+        }
+        const result = await vault.test(slot, { timeoutMs });
+        sendJson(res, 200, { ok: true, slot, result });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVaultRemove(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.slot !== 'string') {
+        sendJson(res, 400, { ok: false, error: 'slot (string) required' });
+        return;
+    }
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        const removed = await vault.remove(body.slot);
+        sendJson(res, 200, { ok: true, removed });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleVaultHas(res, slot) {
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        sendJson(res, 200, { ok: true, slot, present: vault.has(slot) });
+    }
+    catch (err) {
+        sendJson(res, 500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function handleChat(req, res, ctx) {
+    const raw = await readBody(req);
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const msgs = body.messages;
+    if (!Array.isArray(msgs) || msgs.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'messages[] required' });
+        return;
+    }
+    const normalized = [];
+    for (const m of msgs) {
+        if (typeof m !== 'object' || m === null)
+            continue;
+        const r = m['role'];
+        const c = m['content'];
+        if ((r === 'user' || r === 'assistant') && typeof c === 'string') {
+            normalized.push({ role: r, content: c });
+        }
+    }
+    if (normalized.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'no valid user/assistant messages' });
+        return;
+    }
+    try {
+        /* Resolve mode (didactico vs tecnico) per-request -- read
+           from the cookie if set, else from yujin.forge.json,
+           else default. */
+        const reqMode = await resolveModeForRequest(req, ctx.projectRoot);
+        /* Pilot first-run setup (SQ 0.7 + 0.10). If pilot has not
+           run yet, inject a welcome suffix that asks the user
+           target + mode in plain prose. Also schedule auto-complete
+           after the reply. */
+        const pilotState = await readPilotState(ctx.projectRoot);
+        const lastUserMsg = normalized.filter((m) => m.role === 'user').slice(-1)[0];
+        const lastUserText = typeof lastUserMsg?.content === 'string' ? lastUserMsg.content : '';
+        const reply = await ctx.claude.chat({
+            messages: normalized,
+            system: buildSystemPrompt(ctx, reqMode, pilotState),
+            maxTokens: 1024,
+            tools: FORGE_TOOL_SPECS,
+            runTool: async (name, input) => {
+                const r = await runForgeTool(name, input, { projectRoot: ctx.projectRoot });
+                return {
+                    result: r.result,
+                    ...(r.is_error ? { is_error: true } : {}),
+                };
+            },
+        });
+        // Append the latest user message + the assistant's reply to
+        // the persistent transcript. Older messages may already be
+        // present from previous turns; we only need to capture the
+        // *new* turn so the on-disk file matches conversation order.
+        const lastUser = normalized[normalized.length - 1];
+        if (lastUser && lastUser.role === 'user') {
+            // Only append if this user message isn't already the last
+            // recorded one (prevents dup on retry).
+            const recent = ctx.store.messages();
+            const tail = recent[recent.length - 1];
+            if (!tail || tail.role !== 'user' || tail.content !== lastUser.content) {
+                ctx.store.append(lastUser);
+            }
+        }
+        ctx.store.append({ role: 'assistant', content: reply.text });
+        void ctx.store.flush();
+        /* Pilot first-run auto-complete (SQ 0.10). If Pilot is
+           not yet completed, decide based on the user's first
+           message whether to mark setup done with defaults. */
+        if (!pilotState.pilot_completed) {
+            const decision = shouldAutoComplete(pilotState, lastUserText);
+            if (decision.complete) {
+                try {
+                    await completePilotSetup(ctx.projectRoot);
+                }
+                catch { /* non-fatal */ }
+            }
+        }
+        sendJson(res, 200, {
+            ok: true,
+            message: { role: 'assistant', text: reply.text },
+            tokens: { in: reply.tokensIn, out: reply.tokensOut },
+            model: reply.model,
+            /* Slice 4: surface the audit trail so the panel can render
+               the action trace (which tools Claude called + with what
+               args + what came back). Empty array when no tools fired. */
+            tool_rounds: reply.toolRounds.map((r) => ({
+                tool: r.tool,
+                input: r.input,
+                display: typeof r.result === 'object' && r.result !== null && 'display' in r.result
+                    ? r.result.display
+                    : undefined,
+                is_error: r.is_error ?? false,
+            })),
+        });
+    }
+    catch (err) {
+        if (err instanceof ConfigurationError) {
+            sendJson(res, 503, {
+                ok: false,
+                code: 'no_api_key',
+                error: err.message,
+            });
+            return;
+        }
+        if (err instanceof ClaudeApiError) {
+            sendJson(res, 502, {
+                ok: false,
+                code: 'claude_api_error',
+                error: err.message,
+            });
+            return;
+        }
+        sendJson(res, 502, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function buildSystemPrompt(ctx, mode = 'didactico', pilotState = {
+    pilot_completed: true, target_pending: false, mode_pending: false,
+}) {
+    return [
+        'You are Yujin Forge -- a friendly assistant embedded in a developer\'s React project.',
+        '',
+        'PRINCIPLES:',
+        '- Reply in the user\'s language. Default to Spanish if unclear.',
+        '- Keep replies short + conversational.',
+        '- Ask one clarifying question at a time.',
+        '- When proposing code changes, paste minimal diffs the user can apply manually.',
+        '  Direct AST mutation lands when the write-class tools ship.',
+        '',
+        'TOOLS:',
+        '- forge.read_manifest: inspect the NAC-3 manifest in the project.',
+        '  Use it BEFORE asking the user what is in their app.',
+        '- forge.consult_nac_spec: search docs/SPEC.md for canonical',
+        '  answers about NAC-3. Use it when the user asks "what does',
+        '  NAC say about X" or you need to ground an answer in the spec.',
+        '- forge.list_files: list source files under a subdir of the',
+        '  project (default src/). Use it when you need to know what',
+        '  files exist before suggesting where to edit. Filter with',
+        '  the glob arg (e.g. "*.tsx") to narrow the result.',
+        '- forge.read_file: read a specific source file by relative',
+        '  path. Use AFTER forge.list_files when you need the actual',
+        '  contents. Refuses binary files + caps at 64KB by default.',
+        '- Tool calls are silent to the user. Summarise what you found',
+        '  in plain language afterwards.',
+        '',
+        'CONTEXT:',
+        '- Project: ' + ctx.projectName,
+        '- Root:    ' + ctx.projectRoot,
+        '- Forge:   v' + VERSION,
+        modePromptSuffix(mode),
+        welcomePromptSuffix(pilotState),
+    ].join('\n');
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.end(JSON.stringify(body));
+}
+/** Resolve the active Forge mode for a single request.
+ *  Layer order: yf-mode cookie -> yujin.forge.json -> default.
+ *  Stays out of server-wide state for race-safe concurrent
+ *  rendering, mirroring the i18n stateless pattern. */
+async function resolveModeForRequest(req, projectRoot) {
+    /* 1. Cookie. */
+    const cookie = req.headers.cookie ?? '';
+    for (const part of cookie.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        if (k !== 'yf-mode')
+            continue;
+        const v = part.slice(eq + 1).trim();
+        if (FORGE_MODES.includes(v)) {
+            return v;
+        }
+    }
+    /* 2. Project config + default (handled by resolveMode). */
+    const r = await resolveMode({ projectRoot });
+    return r.mode;
+}
+/** Resolve the language for the current request without
+ *  mutating server-wide state. Priority chain:
+ *    1. ?lang=xx query string
+ *    2. yf-lang cookie
+ *    3. server-wide setLanguage (legacy default)
+ *  Unknown / unsupported codes fall back to the server-wide
+ *  current_language. This keeps the lang switching UX working
+ *  for clients without cookie support while making concurrent
+ *  renders race-safe. */
+function resolveRequestLang(req, url) {
+    const qp = url.searchParams.get('lang');
+    if (qp && SUPPORTED_LANGUAGES.includes(qp)) {
+        return qp;
+    }
+    const cookie = req.headers.cookie ?? '';
+    for (const part of cookie.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        if (k !== 'yf-lang')
+            continue;
+        const v = part.slice(eq + 1).trim();
+        if (SUPPORTED_LANGUAGES.includes(v)) {
+            return v;
+        }
+    }
+    return undefined; /* defer to server-wide current_language */
+}
+/** Short hex request id -- not a UUID, no dependency. Used in
+ *  the x-request-id response header so client and server logs
+ *  can be correlated. 16 hex chars give ~64 bits of entropy --
+ *  way more than enough for a local dev server. */
+function generateRequestId() {
+    const bytes = new Uint8Array(8);
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+        globalThis.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) {
+        s += bytes[i].toString(16).padStart(2, '0');
+    }
+    return s;
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+        if (chunks.reduce((s, c) => s + c.length, 0) > 1_000_000) {
+            throw new Error('request body too large (>1MB)');
+        }
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/** Read a raw binary body up to maxBytes. Used by /api/voice/stt
+ *  where the body is the audio recording (typically a few MB).
+ *  Throws loudly when the cap is exceeded so the panel surfaces
+ *  the size issue. */
+async function readBinaryBody(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > maxBytes) {
+            throw new Error('request body too large (>' + maxBytes + ' bytes)');
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+async function readProjectName(projectRoot) {
+    try {
+        const raw = await fs.readFile(path.join(projectRoot, 'yujin.forge.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.project_name === 'string')
+            return parsed.project_name;
+    }
+    catch { /* fall through */ }
+    try {
+        const raw = await fs.readFile(path.join(projectRoot, 'package.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.name === 'string')
+            return parsed.name;
+    }
+    catch { /* fall through */ }
+    return path.basename(projectRoot);
+}
+//# sourceMappingURL=server.js.map