@nac3/forge-cli 0.2.0-alpha.9 → 0.2.1-alpha.60

package/dist/chat/server.js

@@ -13,6 +13,7 @@
  */
 import { createServer } from 'node:http';
 import { promises as fs } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { ClaudeClient, ConfigurationError, ClaudeApiError } from './claude.js';
 import { renderPanelHtml } from './panel.js';
@@ -37,9 +38,112 @@ import { extractSpec } from './spec_extract.js';
 import { generatePlan } from './spec_plan.js';
 import { executeScaffold, rollbackScaffold } from './spec_scaffold.js';
 import { VERSION } from '../version.js';
+import { buildDoctrineDigestLines } from './doctrine_digest.js';
+import { manifest as nac3Manifest } from '../nac3/internal_manifest.js';
+import { buildManifestForPrompt } from '../nac3/manifest_lazy.js';
+import { popPending, logApproval } from '../nac3/approval_queue.js';
 export async function startChatServer(opts) {
     const projectName = await readProjectName(opts.projectRoot);
-    const claude = opts.claude ?? new ClaudeClient();
+    /* alpha.59u.2 -- distinct slug (machine id) vs projectName (display).
+     *  Identity queries against the semantic graph use the slug so
+     *  CLI + panel converge. */
+    const { resolveProjectSlug } = await import('./project_slug.js');
+    const projectSlug = await resolveProjectSlug(opts.projectRoot);
+    /* Director sprint slice 9 -- hydrate ingest sessions from disk
+     *  for this project so spec extract+plan survive restarts. */
+    try {
+        const { setProjectSlugForIngest, loadProjectIngests } = await import('./ingest_session.js');
+        setProjectSlugForIngest(projectSlug);
+        await loadProjectIngests(projectSlug);
+    }
+    catch (err) {
+        try {
+            console.error('ingest_session boot hydrate failed: ' + (err instanceof Error ? err.message : String(err)));
+        }
+        catch { /* swallow */ }
+    }
+    /* alpha.59v -- fire-and-forget auto-ingest of package.json deps
+     *  whenever the boot detects a changed (or never-ingested)
+     *  package.json. Never blocks the boot; never throws.
+     *  alpha.59v.2 -- registered via startAutoIngest so the
+     *  /api/forge/graph-status endpoint can await it (avoiding
+     *  the panel showing partial data during the ingest). */
+    try {
+        const { startAutoIngest } = await import('./graph_auto_ingest.js');
+        startAutoIngest({
+            project_root: opts.projectRoot,
+            project_slug: projectSlug,
+            log: (msg) => { try {
+                console.error(msg);
+            }
+            catch { /* swallow */ } },
+        });
+    }
+    catch { /* never break boot */ }
+    /* GRAPH-1 (dogfood 2026-06-10) -- regenerar el grafo completo
+     * (nodos de modulo + aristas de imports, validadas) al boot, en
+     * background, para que al abrir el panel el grafo este completo.
+     * El boton Refresh + el watcher lo regeneran luego ante cambios.
+     * Fire-and-forget; nunca rompe el boot. */
+    void (async () => {
+        try {
+            const { regenerateAndPersist } = await import('../semantic_graph/derive.js');
+            const s = await regenerateAndPersist({ project_root: opts.projectRoot, project_slug: projectSlug, enrich: false });
+            try {
+                console.error('[graph-regen] boot -> ' + (s.module_edges + s.lib_edges) + ' edges (' + s.pruned + ' pruned)');
+            }
+            catch { /* */ }
+        }
+        catch { /* never break boot */ }
+    })();
+    /* alpha.59w -- fs.watch over src/components, src/hooks, src/lib,
+     *  src/core. When the user adds or modifies a TS/JS file, the
+     *  watcher extracts top-level exports (regex), creates one
+     *  graph node per export with confidence='auto', and pushes
+     *  to the worker (debounced 2s). The watcher cleanup is
+     *  attached to the returned StartedServer.close(). */
+    let componentWatcherHandle = null;
+    try {
+        const { startComponentWatcher } = await import('./graph_component_watcher.js');
+        componentWatcherHandle = await startComponentWatcher({
+            project_root: opts.projectRoot,
+            project_slug: projectSlug,
+            log: (msg) => { try {
+                console.error(msg);
+            }
+            catch { /* swallow */ } },
+        });
+    }
+    catch { /* never break boot */ }
+    /* Provider selection: 'anthropic-api' (default, Console billing) vs
+     * 'claude-code-cli' (subscription billing via `claude -p`
+     * subprocess). The ClaudeCliClient is interface-compatible at the
+     * .chat() shape used by this server -- runTool round-trips happen
+     * inside the subprocess, so the wrapper returns toolRounds=[].
+     * Tests inject `opts.claude` directly and bypass this branch. */
+    /* PND-064 slice B -- generate the per-session panel-push token up
+     * front so both the chat server (to validate) and the CLI client
+     * (to hand to its MCP server) share it. Only meaningful in CLI
+     * mode; harmless otherwise. */
+    const panelPushToken = (await import('node:crypto')).randomBytes(32).toString('hex');
+    let claude;
+    if (opts.claude) {
+        claude = opts.claude;
+    }
+    else if (opts.chatProvider === 'claude-code-cli') {
+        const { ClaudeCliClient } = await import('./claude_cli.js');
+        const cliOpts = {};
+        if (opts.chatProviderAddDirs && opts.chatProviderAddDirs.length > 0) {
+            cliOpts['addDirs'] = opts.chatProviderAddDirs;
+        }
+        /* Wire the panel MCP bridge: the subprocess gets the
+         * forge_panel MCP server so it can create pizarron tabs. */
+        cliOpts['panelBridge'] = { port: opts.port, token: panelPushToken };
+        claude = new ClaudeCliClient(cliOpts);
+    }
+    else {
+        claude = new ClaudeClient();
+    }
     const voice = opts.voice ?? new VoiceRouter({
         configDir: configDir(),
         registry: buildDefaultRegistry(),
@@ -67,6 +171,82 @@ export async function startChatServer(opts) {
         });
         return reply.text.trim();
     });
+    /* Hot re-anchor (dogfood 2026-06-10) -- el proyecto activo se
+     * guarda en un estado MUTABLE por sesion, no en constantes del
+     * boot. yujin.project.set-root llama reanchor() y todos los
+     * handlers (que leen de `session`) pasan a apuntar al nuevo root
+     * sin reiniciar el panel. */
+    const session = { projectRoot: opts.projectRoot, projectName, projectSlug };
+    async function reanchor(newRoot) {
+        const abs = (await import('node:path')).resolve(newRoot);
+        const { enqueuePanelDispatch } = await import('./panel_queue.js');
+        /* Loguear el progreso en el espacio de chat para combatir la
+         * ansiedad del usuario (Pablo 2026-06-10). Van por la cola del
+         * panel como mensajes de sistema. */
+        const chatLog = (text) => {
+            try {
+                enqueuePanelDispatch('system.chat-log', { text }, new Date().toISOString());
+            }
+            catch { /* */ }
+        };
+        session.projectRoot = abs;
+        session.projectName = await readProjectName(abs);
+        const { resolveProjectSlug } = await import('./project_slug.js');
+        session.projectSlug = await resolveProjectSlug(abs);
+        chatLog('Cambiando al proyecto ' + session.projectName + ' (' + abs + ')...');
+        /* re-hidratar ingest + reiniciar el watcher sobre el nuevo dir */
+        try {
+            const { setProjectSlugForIngest, loadProjectIngests } = await import('./ingest_session.js');
+            setProjectSlugForIngest(session.projectSlug);
+            await loadProjectIngests(session.projectSlug);
+        }
+        catch { /* best-effort */ }
+        try {
+            if (componentWatcherHandle) {
+                await componentWatcherHandle.stop();
+                componentWatcherHandle = null;
+            }
+            const { startComponentWatcher } = await import('./graph_component_watcher.js');
+            componentWatcherHandle = await startComponentWatcher({
+                project_root: abs, project_slug: session.projectSlug,
+                log: (msg) => { try {
+                    console.error(msg);
+                }
+                catch { /* swallow */ } },
+            });
+        }
+        catch { /* never break */ }
+        try {
+            console.error('[reanchor] active project -> ' + abs + ' (slug=' + session.projectSlug + ')');
+        }
+        catch { /* */ }
+        /* Regenerar el grafo del nuevo proyecto (crea los objetos si no
+         * existen) en BACKGROUND -- no bloquear la respuesta HTTP del
+         * verbo (sino el panel-invoke del subproceso da timeout =
+         * "failed to fetch"). El progreso se loguea por la cola; al
+         * terminar dispara el re-tabs. */
+        const slugNow = session.projectSlug;
+        const nameNow = session.projectName;
+        chatLog('Regenerando el grafo semantico de ' + nameNow + '...');
+        void (async () => {
+            try {
+                const { regenerateAndPersist } = await import('../semantic_graph/derive.js');
+                const s = await regenerateAndPersist({ project_root: abs, project_slug: slugNow, enrich: false });
+                chatLog('Grafo listo: ' + s.module_nodes + ' modulos, ' + s.lib_nodes + ' librerias, '
+                    + (s.module_edges + s.lib_edges) + ' aristas.');
+            }
+            catch {
+                chatLog('No pude regenerar el grafo de este proyecto (sigo igual).');
+            }
+            /* Re-generar las 4 pestanas canonicas del nuevo proyecto. */
+            try {
+                enqueuePanelDispatch('system.reanchor', { slug: slugNow, name: nameNow }, new Date().toISOString());
+            }
+            catch { /* */ }
+            chatLog('Listo. El pizarron ahora refleja ' + nameNow + '.');
+        })();
+        return { projectRoot: session.projectRoot, projectName: session.projectName, projectSlug: session.projectSlug };
+    }
     const server = createServer(async (req, res) => {
         // Every response carries a request-id (for client + server
         // log correlation) + cache-control (we never want browsers
@@ -79,12 +259,17 @@ export async function startChatServer(opts) {
         res.setHeader('x-yujin-version', VERSION);
         try {
             await route(req, res, {
-                projectRoot: opts.projectRoot,
-                projectName,
+                projectRoot: session.projectRoot,
+                projectName: session.projectName,
+                projectSlug: session.projectSlug,
                 port: opts.port,
                 claude,
                 voice,
                 store,
+                runtime: opts.runtime,
+                chatProvider: opts.chatProvider,
+                panelPushToken,
+                reanchor,
             });
         }
         catch (err) {
@@ -114,7 +299,24 @@ export async function startChatServer(opts) {
         url,
         store,
         close: () => new Promise((resolve) => {
-            server.close(() => resolve());
+            /* alpha.59w -- stop the component watcher on shutdown so
+             *  vitest does not hang on lingering fs watchers. */
+            if (componentWatcherHandle) {
+                Promise.resolve(componentWatcherHandle.stop()).catch(() => undefined);
+            }
+            /* alpha.59z.136 slice 14 -- flush in-flight ingest session
+             * writes BEFORE the server closes so test teardowns that
+             * fs.rm the home directory immediately after do not race
+             * with the fire-and-forget persist queue. */
+            (async () => {
+                try {
+                    const { flushPendingIngestWrites, setProjectSlugForIngest } = await import('./ingest_session.js');
+                    await flushPendingIngestWrites();
+                    setProjectSlugForIngest(null);
+                }
+                catch { /* swallow */ }
+                server.close(() => resolve());
+            })();
         }),
     };
 }
@@ -144,6 +346,75 @@ async function route(req, res, ctx) {
         });
         return;
     }
+    /* ------------------------------------------------------------
+     * Director sprint slice 5 -- agent runtime panel endpoints.
+     * GET  /api/agent/state    -- runtime status + agent definitions
+     * POST /api/agent/run      -- dispatch an agent through runtime
+     * GET  /api/agent/events   -- SSE stream of RuntimeEvent
+     * All return 503 when ctx.runtime is unwired so the UI can
+     * surface a clean "no runtime" state.
+     * ------------------------------------------------------------ */
+    if (req.method === 'GET' && url.pathname === '/api/agent/state') {
+        await handleAgentState(res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/run') {
+        await handleAgentRun(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/events') {
+        await handleAgentEventsSse(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/approve') {
+        await handleAgentApprove(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/activity') {
+        await handleAgentActivity(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/bridge-tail') {
+        await handleAgentBridgeTail(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/inject') {
+        await handleAgentInject(req, res, ctx);
+        return;
+    }
+    /* Legal docs surfaced inside the product (Config -> About).
+     * Serves the raw markdown so the panel can render or pop a
+     * dialog. Routes are static names so a future i18n swap can
+     * branch on Accept-Language without changing the URL. */
+    if (req.method === 'GET' && url.pathname === '/api/legal/privacy-policy') {
+        await serveLegalDoc(res, 'PRIVACY_POLICY.md');
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/legal/limited-responsibility') {
+        await serveLegalDoc(res, 'LIMITED_RESPONSIBILITY.md');
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/legal/index') {
+        /* Compact directory listing the panel uses to render
+         *  Config -> About without hardcoding doc slugs. */
+        sendJson(res, 200, {
+            docs: [
+                {
+                    slug: 'privacy-policy',
+                    title: 'Privacy policy',
+                    description: 'What data Forge sends to Yujin servers, what we keep, and what we do not.',
+                    url: '/api/legal/privacy-policy',
+                },
+                {
+                    slug: 'limited-responsibility',
+                    title: 'Limitation of liability',
+                    description: 'AS-IS provision, third-party services, indemnification, governing law.',
+                    url: '/api/legal/limited-responsibility',
+                },
+            ],
+        });
+        return;
+    }
     if (req.method === 'POST' && url.pathname === '/api/chat') {
         await handleChat(req, res, ctx);
         return;
@@ -174,6 +445,533 @@ async function route(req, res, ctx) {
         await handleVaultCatalog(res, url);
         return;
     }
+    /* NAC3 internal manifest -- Forge dogfood. See
+       docs/NAC3_INTERNAL_MANIFEST.md. The panel reads this on boot
+       to register handlers + caches for 60s. Same JSON is embedded
+       into the system prompt so the LLM sees one canonical
+       catalogue. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/nac3-manifest') {
+        sendJson(res, 200, { ok: true, manifest: nac3Manifest() });
+        return;
+    }
+    /* alpha.59c.2 -- limits config endpoints. GET returns the
+     *  active config + field paths + defaults. POST sets one
+     *  field with {field, value} body. The settings panel renders
+     *  the 10 numeric inputs from these. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/limits') {
+        const { readLimitsConfig, defaultLimitsConfig, LIMITS_FIELD_PATHS, LIMITS_BOOLEAN_FIELD_PATHS, } = await import('../core/limits_config.js');
+        const cfg = await readLimitsConfig(true);
+        const def = defaultLimitsConfig();
+        const resolveField = (f, kind) => {
+            const parts = f.split('.');
+            let cur = cfg;
+            let dft = def;
+            for (const p of parts) {
+                if (cur && typeof cur === 'object')
+                    cur = cur[p];
+                if (dft && typeof dft === 'object')
+                    dft = dft[p];
+            }
+            return { field: f, value: cur, default: dft, kind };
+        };
+        const fields = LIMITS_FIELD_PATHS.map((f) => resolveField(f, 'number'));
+        const booleans = LIMITS_BOOLEAN_FIELD_PATHS.map((f) => resolveField(f, 'boolean'));
+        sendJson(res, 200, { ok: true, fields, booleans, config: cfg });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/limits') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        const { setLimitsField, setLimitsBooleanField, isLimitsBooleanFieldPath, resetLimitsConfig } = await import('../core/limits_config.js');
+        if (body.reset === true) {
+            const cfg = await resetLimitsConfig();
+            sendJson(res, 200, { ok: true, config: cfg });
+            return;
+        }
+        if (typeof body.field !== 'string') {
+            sendJson(res, 400, { ok: false, error: 'expected {field: string, value: number|boolean} or {reset: true}' });
+            return;
+        }
+        /* alpha.59d -- accept booleans too (Danger Zone toggle +
+         * cwd_boundary_strict). Dispatch by field-path type. */
+        if (isLimitsBooleanFieldPath(body.field)) {
+            if (typeof body.value !== 'boolean') {
+                sendJson(res, 400, { ok: false, error: 'boolean field requires boolean value' });
+                return;
+            }
+            try {
+                const cfg = await setLimitsBooleanField(body.field, body.value);
+                sendJson(res, 200, { ok: true, config: cfg });
+            }
+            catch (err) {
+                sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+            }
+            return;
+        }
+        if (typeof body.value !== 'number' || !Number.isFinite(body.value)) {
+            sendJson(res, 400, { ok: false, error: 'expected {field: string, value: number} or {reset: true}' });
+            return;
+        }
+        try {
+            const cfg = await setLimitsField(body.field, body.value);
+            sendJson(res, 200, { ok: true, config: cfg });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    /* alpha.59z.176 PND-003 -- VAD tuning + debug config. The panel
+     *  reads this at boot + writes it back when the user moves a
+     *  slider. The VAD loop hot-applies on the next tick without a
+     *  reload. Session stats (when toggled on) are POSTed back here so
+     *  ~/.yujin-forge/vad_sessions.jsonl accumulates a row per capture
+     *  for the field test protocol. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/vad-config') {
+        const { readVadConfig, DEFAULT_VAD_CONFIG } = await import('../core/vad_config.js');
+        const cfg = await readVadConfig();
+        sendJson(res, 200, { ok: true, config: cfg, defaults: DEFAULT_VAD_CONFIG });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/vad-config') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        const { readVadConfig, writeVadConfig, sanitiseVadConfig, DEFAULT_VAD_CONFIG } = await import('../core/vad_config.js');
+        if (body.reset === true) {
+            await writeVadConfig({ ...DEFAULT_VAD_CONFIG });
+            sendJson(res, 200, { ok: true, config: { ...DEFAULT_VAD_CONFIG } });
+            return;
+        }
+        const current = await readVadConfig();
+        const merged = sanitiseVadConfig({ ...current, ...(body.patch ?? {}) });
+        await writeVadConfig(merged);
+        sendJson(res, 200, { ok: true, config: merged });
+        return;
+    }
+    /* PND-001 alpha.59z.177 -- wizard probe endpoints. Lightweight
+     *  checks so the panel can verify the user finished the chosen
+     *  setup path BEFORE marking the wizard complete. The probes do
+     *  not consume tokens (anthropic /v1/models is free; the Claude
+     *  CLI probe just spawns `claude -p ok?`). */
+    if (req.method === 'POST' && url.pathname === '/api/forge/wizard-probe-claude-cli') {
+        try {
+            const { probeClaudeCli } = await import('./claude_cli.js');
+            const r = await probeClaudeCli({});
+            sendJson(res, 200, { ...r, ok: r.ok });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/wizard-test-anthropic-key') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        const apiKey = typeof body.api_key === 'string' ? body.api_key.trim() : '';
+        if (!apiKey || !/^sk-ant-/.test(apiKey)) {
+            sendJson(res, 400, { ok: false, error: 'expected an Anthropic key starting with sk-ant-' });
+            return;
+        }
+        try {
+            const r = await fetch('https://api.anthropic.com/v1/models', {
+                method: 'GET',
+                headers: {
+                    'x-api-key': apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+            });
+            if (!r.ok) {
+                const detail = await r.text().catch(() => '');
+                sendJson(res, 200, { ok: false, status: r.status, detail: detail.slice(0, 300) });
+                return;
+            }
+            if (body.save === true) {
+                const { setKey } = await import('../core/provider_keys.js');
+                await setKey('anthropic_api_key', apiKey);
+                /* The brain_provider_preference field is read elsewhere from
+                 * the same provider_keys.json file. Setting the key alone is
+                 * enough -- cost_router falls back to anthropic when no
+                 * preference is recorded but anthropic_api_key is present. */
+            }
+            sendJson(res, 200, { ok: true, status: r.status, saved: body.save === true });
+        }
+        catch (err) {
+            sendJson(res, 200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    /* alpha.59z.177 PND-001 -- first-run wizard state. The chat panel
+     *  reads this at boot to decide whether to auto-open the
+     *  license + brain wizard modal. POST persists "user finished the
+     *  wizard" or "user dismissed -> do not auto-open again". */
+    if (req.method === 'GET' && url.pathname === '/api/forge/wizard-state') {
+        const { readWizardState } = await import('../core/wizard_state.js');
+        const state = await readWizardState();
+        sendJson(res, 200, { ok: true, state });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/wizard-state') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        const { markWizardCompleted, resetWizardState, readWizardState } = await import('../core/wizard_state.js');
+        if (body.reset === true) {
+            await resetWizardState();
+            sendJson(res, 200, { ok: true, state: await readWizardState() });
+            return;
+        }
+        const path_chosen = body.path_chosen;
+        if (path_chosen !== 'claude_plan' && path_chosen !== 'console_byok' && path_chosen !== 'skipped') {
+            sendJson(res, 400, { ok: false, error: 'path_chosen must be claude_plan|console_byok|skipped' });
+            return;
+        }
+        const state = await markWizardCompleted(path_chosen);
+        sendJson(res, 200, { ok: true, state });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/vad-stats') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        const { appendVadSessionStats } = await import('../core/vad_config.js');
+        try {
+            await appendVadSessionStats(body);
+            sendJson(res, 200, { ok: true });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    /* alpha.59j -- reader bookmarks viewer endpoint. Reads the
+     *  persisted reader_sessions.json + returns a flat list of
+     *  bookmarks (name, doc_path, cursor_block_id, opened_at)
+     *  newest-first so the panel can render the sidebar. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/reader-bookmarks') {
+        try {
+            const home = process.env.HOME || process.env.USERPROFILE || (await import('node:os')).homedir();
+            const pathMod = await import('node:path');
+            const fsMod = await import('node:fs/promises');
+            const base = process.env.YF_CONFIG_DIR || pathMod.join(home, '.yujin-forge');
+            const cacheFile = pathMod.join(base, 'cache', 'reader_sessions.json');
+            const raw = await fsMod.readFile(cacheFile, 'utf-8');
+            const idx = JSON.parse(raw);
+            const out = [];
+            for (const key of Object.keys(idx.entries || {})) {
+                const entry = idx.entries[key];
+                if (!entry)
+                    continue;
+                const bms = entry.bookmarks || {};
+                for (const name of Object.keys(bms)) {
+                    out.push({
+                        name,
+                        doc_id: entry.doc_id,
+                        abs_path: entry.abs_path,
+                        filename: entry.filename,
+                        title: entry.title || entry.filename,
+                        block_id: bms[name],
+                        last_used_at: entry.last_used_at || '',
+                    });
+                }
+            }
+            out.sort((a, b) => (b.last_used_at || '').localeCompare(a.last_used_at || ''));
+            sendJson(res, 200, { ok: true, bookmarks: out, count: out.length });
+        }
+        catch {
+            sendJson(res, 200, { ok: true, bookmarks: [], count: 0 });
+        }
+        return;
+    }
+    /* alpha.59i -- shell kill endpoint. POST {handle_id} from the
+     *  pizarron tab Cancel button. Looks up the active ChildProcess
+     *  + sends SIGTERM (with SIGKILL fallback 2s). 404 if the
+     *  handle is unknown (already finished). */
+    if (req.method === 'POST' && url.pathname === '/api/forge/shell-kill') {
+        const raw = await readBody(req);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON' });
+            return;
+        }
+        if (typeof body.handle_id !== 'string' || body.handle_id.trim() === '') {
+            sendJson(res, 400, { ok: false, error: 'handle_id required' });
+            return;
+        }
+        const { killShellByHandle } = await import('./tools/shell.js');
+        const r = killShellByHandle(body.handle_id);
+        sendJson(res, r.ok ? 200 : 404, r);
+        return;
+    }
+    /* alpha.59z.182 -- semantic graph status now reads from the
+     *  per-project LOCAL SQLite store (no worker). Same response
+     *  shape as before so the panel JS doesn't change. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/graph-status') {
+        try {
+            const project = url.searchParams.get('project_slug') ?? ctx.projectSlug ?? '';
+            /* alpha.59v.2 -- if the boot auto-ingest for this slug is
+             *  still running, wait for it (5s max) so the panel does
+             *  not show stale counts on first paint. */
+            try {
+                const { inFlightIngest } = await import('./graph_auto_ingest.js');
+                const pending = inFlightIngest(project);
+                if (pending) {
+                    await Promise.race([
+                        pending,
+                        new Promise((resolve) => setTimeout(resolve, 5000)),
+                    ]);
+                }
+            }
+            catch { /* swallow -- proceed with query anyway */ }
+            if (!project) {
+                sendJson(res, 200, { ok: true, count: 0, by_kind: {}, by_confidence: {}, sample: [], available: false });
+                return;
+            }
+            const { listRelevant, summarize } = await import('../semantic_graph/store.js');
+            const summary = await summarize(project);
+            const sampleNodes = await listRelevant(project, { limit: 10 });
+            const by_confidence = {};
+            const allForCount = await listRelevant(project, { limit: 10_000, min_confidence: 'claimed' });
+            for (const n of allForCount) {
+                by_confidence[n.confidence] = (by_confidence[n.confidence] || 0) + 1;
+            }
+            const sample = sampleNodes.map((n) => ({
+                id: n.id, kind: n.kind, name: n.name, version: n.version ?? null, purpose: n.purpose, confidence: n.confidence,
+            }));
+            sendJson(res, 200, {
+                ok: true,
+                count: summary.node_count,
+                by_kind: summary.by_kind,
+                by_confidence,
+                sample,
+                available: summary.node_count > 0,
+            });
+        }
+        catch {
+            sendJson(res, 200, { ok: true, count: 0, by_kind: {}, by_confidence: {}, sample: [], available: false });
+        }
+        return;
+    }
+    /* alpha.59z.150 F101 slice 3 -- MCP bridges UI endpoints.
+     *  GET /api/forge/mcp/bridges     -> list of discovered bridges
+     *                                    with id/endpoint/source/enabled/
+     *                                    display_name/protocol.
+     *  GET /api/forge/mcp/tools       -> tool catalog for the bridge_id
+     *                                    query param. Internally calls
+     *                                    MCPClient.listTools() (slice 4
+     *                                    FULL).
+     *  POST /api/forge/mcp/toggle     -> flip enabled flag on a bridge.
+     *  Panel uses these to render the Config tab + tool catalog modal.
+     *  Each one is best-effort; failures degrade to {ok:false, error}. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/mcp/bridges') {
+        try {
+            const { getActiveBridges } = await import('../mcp/bridge_registry.js');
+            const bridges = await getActiveBridges({ projectRoot: ctx.projectRoot });
+            const shaped = bridges.map((b) => ({
+                id: b.id,
+                endpoint: b.endpoint,
+                source: b.source,
+                enabled: b.enabled,
+                display_name: b.display_name ?? b.id,
+                protocol: b.protocol ?? 'http_rest',
+            }));
+            sendJson(res, 200, { ok: true, bridges: shaped, count: shaped.length });
+        }
+        catch (err) {
+            sendJson(res, 200, { ok: false, error: err instanceof Error ? err.message : String(err), bridges: [], count: 0 });
+        }
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/mcp/tools') {
+        const bridgeId = url.searchParams.get('bridge_id') ?? '';
+        if (!bridgeId) {
+            sendJson(res, 400, { ok: false, error: 'bridge_id required' });
+            return;
+        }
+        try {
+            const { getActiveBridges } = await import('../mcp/bridge_registry.js');
+            const bridges = await getActiveBridges({ projectRoot: ctx.projectRoot });
+            const bridge = bridges.find((b) => b.id === bridgeId);
+            if (!bridge) {
+                sendJson(res, 404, { ok: false, error: 'bridge_id "' + bridgeId + '" not found', tools: [] });
+                return;
+            }
+            if (!bridge.enabled) {
+                sendJson(res, 200, { ok: false, error: 'bridge disabled', bridge_id: bridgeId, tools: [], disabled: true });
+                return;
+            }
+            try {
+                const { getMCPClient } = await import('../mcp/protocol_client.js');
+                const client = getMCPClient(bridge);
+                const r = await client.listTools();
+                if (r.ok) {
+                    sendJson(res, 200, { ok: true, bridge_id: bridgeId, tools: r.tools, count: r.count });
+                }
+                else {
+                    sendJson(res, 200, {
+                        ok: false,
+                        error: r.error,
+                        bridge_id: bridgeId,
+                        bridge_unreachable: true,
+                        tools: [],
+                    });
+                }
+            }
+            catch (toolErr) {
+                sendJson(res, 200, {
+                    ok: false,
+                    error: toolErr instanceof Error ? toolErr.message : String(toolErr),
+                    bridge_id: bridgeId,
+                    bridge_unreachable: true,
+                    tools: [],
+                });
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/mcp/toggle') {
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+            return;
+        }
+        const bridgeId = typeof body.bridge_id === 'string' ? body.bridge_id.trim() : '';
+        if (!bridgeId) {
+            sendJson(res, 400, { ok: false, error: 'bridge_id required' });
+            return;
+        }
+        const enabled = body.enabled === true || body.enabled === 'true' || body.enabled === 1;
+        try {
+            const { setBridgeEnabled } = await import('../mcp/state.js');
+            await setBridgeEnabled(bridgeId, enabled);
+            const { resetBridgeCache } = await import('../mcp/bridge_registry.js');
+            resetBridgeCache();
+            sendJson(res, 200, { ok: true, bridge_id: bridgeId, enabled });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    /* alpha.59l -- "what changed in this version" notification.
+     *  Compares ~/.yujin-forge/last_seen_version vs current VERSION
+     *  + returns the cumulative bullet catalog entries. Panel shows
+     *  a one-shot dismissable banner; dismiss POSTs to /dismiss. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/whats-new') {
+        const { computeWhatsNew } = await import('../core/whats_new.js');
+        const r = await computeWhatsNew(VERSION);
+        sendJson(res, 200, { ok: true, ...r });
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/whats-new/dismiss') {
+        const { writeLastSeen } = await import('../core/whats_new.js');
+        try {
+            await writeLastSeen(VERSION);
+            sendJson(res, 200, { ok: true, last_seen_version: VERSION });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    /* alpha.59g -- audit log viewer endpoint. Reads the last N
+     *  rows from ~/.yujin-forge/cache/audit_log.jsonl + returns
+     *  newest-first. The panel renders them in the Danger Zone
+     *  area so the user can confirm exactly what Forge did
+     *  (especially when Danger Zone auto-approve is on). */
+    if (req.method === 'GET' && url.pathname === '/api/forge/audit-log') {
+        const { readRecentAudit } = await import('../core/audit_log.js');
+        const limitParam = url.searchParams.get('limit');
+        const limit = limitParam ? Math.min(500, Math.max(1, Number(limitParam) || 100)) : 100;
+        const entries = await readRecentAudit(limit);
+        sendJson(res, 200, { ok: true, entries, count: entries.length });
+        return;
+    }
+    /* alpha.52 -- budget snapshot for the panel UI card. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/budget') {
+        const { readBudgetStatus } = await import('../core/budget.js');
+        const status = await readBudgetStatus();
+        /* JSON does not transport Infinity; map to null so the
+         * client can treat it as "unlimited". */
+        const finite = (n) => Number.isFinite(n) ? n : null;
+        sendJson(res, 200, {
+            ok: true,
+            budget: {
+                plan: status.plan,
+                plan_label: status.plan_label,
+                month: status.month,
+                renewal_at: status.renewal_at,
+                extension_url: status.extension_url,
+                eco: {
+                    cap: finite(status.eco.cap),
+                    used: status.eco.used,
+                    remaining: finite(status.eco.remaining),
+                    used_pct: status.eco.used_pct,
+                },
+                frontier: {
+                    cap: finite(status.frontier.cap),
+                    used: status.frontier.used,
+                    remaining: finite(status.frontier.remaining),
+                    used_pct: status.frontier.used_pct,
+                },
+            },
+        });
+        return;
+    }
+    /* alpha.42 -- approval queue endpoints for destructive /
+       approval-required verbs. The dispatcher pauses such verbs +
+       returns nac3_panel_approval_required: true. The panel opens
+       a modal; the user clicks Approve / Reject; the panel POSTs
+       here with the trace_id. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/nac3-approve') {
+        await handleNac3Approve(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/nac3-reject') {
+        await handleNac3Reject(req, res);
+        return;
+    }
     /* SQ 0.8 -- dual mode read/write. */
     if (req.method === 'GET' && url.pathname === '/api/forge/mode') {
         await handleModeGet(req, res, ctx);
@@ -270,20 +1068,136 @@ async function route(req, res, ctx) {
         await handleTrustState(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);
+    /* alpha.29 -- keys status for the settings dropdown. Returns
+       which BYOK provider keys + license are configured, without
+       exposing the values themselves. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/keys-status') {
+        await handleKeysStatus(req, res);
         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);
+    /* alpha.30 -- write/clear BYOK provider keys from the panel. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/keys-set') {
+        await handleKeysSet(req, res);
+        return;
+    }
+    /* PND-069 -- config de Brain desde el panel: modo plan/console,
+       toggle eco, bindings provider+modelo por tier. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/brain-config') {
+        await handleBrainConfigGet(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/brain-config') {
+        await handleBrainConfigSet(req, res);
+        return;
+    }
+    /* PND-069 -- modelos disponibles por provider (API en vivo con
+       fallback estatico). */
+    if (req.method === 'GET' && url.pathname === '/api/forge/brain-models') {
+        await handleBrainModels(req, res, url);
+        return;
+    }
+    /* PND-064 -- paridad de tools en modo Plan: el MCP server local
+       reenvia aca CADA nac3_invoke del subproceso (modo
+       claude-code-cli). Corre el dispatcher real y devuelve el
+       resultado; los dispatches de panel se encolan. Token-gated. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/panel-invoke') {
+        await handlePanelInvoke(req, res, ctx);
+        return;
+    }
+    /* PND-064 slice B -- el panel hace polling de la cola. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/panel-queue') {
+        await handlePanelQueue(req, res, url);
+        return;
+    }
+    /* GRAPH-1 -- regenerar el grafo semantico (nodos + aristas
+       derivadas de imports). El boton Refresh del panel lo llama. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/graph-regenerate') {
+        await handleGraphRegenerate(req, res, ctx);
+        return;
+    }
+    /* Startup tabs (dogfood 2026-06-10) -- 4 pestanas que el panel
+       instancia al abrir: grafo grafico, grafo semantico, pendings,
+       workflow. Se auto-refrescan; el switch las apaga. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/startup-tabs') {
+        await handleStartupTabs(req, res, ctx, url);
+        return;
+    }
+    /* Mobile pairing QR (dogfood 2026-06-10) -- Ajustes > Vincular
+       telefono. Genera codigo + envelope + QR SVG para que Forge
+       Mobile lo escanee (el usuario solo tipea el codigo). */
+    if (req.method === 'POST' && url.pathname === '/api/forge/mobile-pair') {
+        await handleMobilePair(req, res);
+        return;
+    }
+    /* alpha.59z.114 -- pull the canonical license row from the
+       HITO 4 worker (Polar -> D1 -> local cache). The panel button
+       hits this when the user paid on Polar but the local cache
+       still says plan=none. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/license-sync') {
+        await handleLicenseSync(req, res);
+        return;
+    }
+    /* alpha.59z.117 -- bind a Polar user_handle (email) to the
+       local license cache + immediately attempt a sync. This is
+       the one-click flow the panel surfaces when the user opens
+       yf chat for the first time after installing from npm:
+       panel detects user_handle missing, prompts for email,
+       POSTs here, and the row gets populated end-to-end. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/license-handle') {
+        await handleLicenseHandle(req, res);
+        return;
+    }
+    /* alpha.35 -- pizarron edit: read + write project files. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/file') {
+        await handleReadFile(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/file') {
+        await handleWriteFile(req, res, ctx);
+        return;
+    }
+    /* Favicon -- minimal SVG so Chrome stops 404-ing. The browser
+       auto-requests /favicon.ico on every page load; without this,
+       each open of the panel logs an error. */
+    if (req.method === 'GET' && (url.pathname === '/favicon.ico'
+        || url.pathname === '/favicon.svg')) {
+        const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">'
+            + '<circle cx="16" cy="16" r="14" fill="#1a1a1a"/>'
+            + '<path d="M8 22 L16 8 L24 22 M11 17 L21 17" stroke="#fafafa" stroke-width="2" fill="none" stroke-linecap="round"/>'
+            + '</svg>';
+        res.writeHead(200, {
+            'content-type': 'image/svg+xml',
+            'cache-control': 'public, max-age=86400',
+        });
+        res.end(svg);
+        return;
+    }
+    /* Support report ingest (2026-05-31 -- F30-style). Panel sends
+     * runtime errors (window.onerror, fetch failures, unhandled
+     * promise rejections) here so Forge sees what the user saw
+     * without them having to copy logs. PII is scrubbed on save. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/support/report') {
+        await handleSupportReport(req, res);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/support/reports') {
+        await handleSupportReportList(req, res);
+        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
@@ -445,6 +1359,19 @@ async function handleVoiceStt(req, res, ctx) {
         sendJson(res, 400, { ok: false, error: 'audio body is empty' });
         return;
     }
+    /* 2026-05-31 fix: Google STT sync rejects audio > 1 min with
+       HTTP 400. Refuse early with a useful message instead of
+       leaking the Google error verbatim. ~4 MB is the practical
+       ceiling for 60s of WebM/Opus at 32 kbps. */
+    if (audio.length > 4 * 1024 * 1024) {
+        sendJson(res, 413, {
+            ok: false,
+            error: 'audio too long for sync STT (limit ~1 min). '
+                + 'Got ' + audio.length + ' bytes. The chat panel auto-stops at 55s; '
+                + 'if you hit this from a different client, split the audio.',
+        });
+        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
@@ -538,6 +1465,163 @@ async function handleForgeToolDispatch(req, res, ctx) {
         });
     }
 }
+/* ============================================================
+ * NAC3 approval queue endpoints (alpha.42).
+ *
+ * When the LLM invokes a verb with policy=destructive or
+ * approval-required, runNac3Invoke pushes a pending row + returns
+ * an envelope. The panel opens a modal; the user clicks Approve
+ * or Reject; the panel POSTs here with the trace_id.
+ *
+ * Approve -> resolve the row + execute the legacy alias via the
+ * runForgeTool dispatcher (with approval_bypass=true to skip the
+ * gate on re-entry). Reject -> log + return ok without executing.
+ * ============================================================ */
+async function handleNac3Approve(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const traceId = typeof body.trace_id === 'string' ? body.trace_id.trim() : '';
+    if (!traceId) {
+        sendJson(res, 400, { ok: false, error: 'trace_id required' });
+        return;
+    }
+    const pending = popPending(traceId);
+    if (!pending) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: '?',
+            decision: 'expired',
+            args_sample: {},
+            policy: '?',
+            reason: 'trace_id not in queue (expired or already resolved)',
+        });
+        sendJson(res, 404, { ok: false, error: 'no pending approval for trace_id (expired or already resolved)' });
+        return;
+    }
+    /* Execute via the legacy alias, bypassing the gate. */
+    if (!pending.legacy_alias) {
+        sendJson(res, 500, { ok: false, error: 'pending row has no legacy alias' });
+        return;
+    }
+    let result;
+    try {
+        result = await pending.legacy_run(pending.legacy_alias, pending.args, ctx.projectRoot === pending.ctx.projectRoot ? pending.ctx : { projectRoot: ctx.projectRoot });
+    }
+    catch (err) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'approve',
+            args_sample: pending.args,
+            policy: pending.verb.policy,
+            reason: 'handler threw: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        sendJson(res, 500, {
+            ok: false,
+            error: 'handler threw on approved verb: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        return;
+    }
+    await logApproval({
+        ts: new Date().toISOString(),
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'approve',
+        args_sample: pending.args,
+        policy: pending.verb.policy,
+    });
+    sendJson(res, 200, {
+        ok: true,
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        is_error: result.is_error ?? false,
+        result: result.result,
+    });
+}
+async function handleNac3Reject(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const traceId = typeof body.trace_id === 'string' ? body.trace_id.trim() : '';
+    const reason = typeof body.reason === 'string' ? body.reason.slice(0, 240) : undefined;
+    if (!traceId) {
+        sendJson(res, 400, { ok: false, error: 'trace_id required' });
+        return;
+    }
+    const pending = popPending(traceId);
+    if (!pending) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: '?',
+            decision: 'expired',
+            args_sample: {},
+            policy: '?',
+            reason: 'trace_id not in queue',
+        });
+        /* alpha.59z.14 F104 -- emit structured ForgeError so the panel
+         * + chat brain can surface a readable diagnosis instead of the
+         * cryptic "no pending approval for trace_id" string. */
+        const { renderForgeError, E_MODAL_TRACE_STALE } = await import('../core/error_catalog.js');
+        const { formatForgeErrorJson } = await import('../core/error_formatter.js');
+        const forgeError = renderForgeError(E_MODAL_TRACE_STALE, { trace_id: traceId });
+        sendJson(res, 404, {
+            ok: false,
+            /* legacy field for backward compatibility */
+            error: 'no pending approval for trace_id',
+            /* F104 structured */
+            forge_error: formatForgeErrorJson(forgeError),
+        });
+        return;
+    }
+    await logApproval({
+        ts: new Date().toISOString(),
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'reject',
+        args_sample: pending.args,
+        policy: pending.verb.policy,
+        reason,
+    });
+    /* alpha.59z.160 F104 -- when the rejected verb is yujin.shell.exec,
+     * surface E_SHELL_EXEC_REJECTED (severity: info) so the chat brain
+     * can suggest the native-verb alternative for read-only commands
+     * (yf projects active, git status, ls) instead of asking the user
+     * to re-approve. The rejection itself is a valid user signal --
+     * response stays ok:true. */
+    const payload = {
+        ok: true,
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'rejected',
+    };
+    if (pending.verb.id === 'yujin.shell.exec') {
+        const { renderForgeError, E_SHELL_EXEC_REJECTED } = await import('../core/error_catalog.js');
+        const { formatForgeErrorJson } = await import('../core/error_formatter.js');
+        const command = typeof pending.args['command'] === 'string'
+            ? pending.args['command'].slice(0, 240)
+            : '?';
+        const classification = typeof pending.args['classification'] === 'string'
+            ? pending.args['classification']
+            : pending.verb.policy;
+        const fe = renderForgeError(E_SHELL_EXEC_REJECTED, { command, classification });
+        payload['forge_error'] = formatForgeErrorJson(fe);
+    }
+    sendJson(res, 200, payload);
+}
 /** V1.37 + V1.38 -- ingest a spec doc via drag-drop / upload.
  *
  * Accepts POST with:
@@ -665,7 +1749,7 @@ async function handleForgeIngestExtract(req, res, ctx) {
         };
         if (session.doc.language)
             opts.language = session.doc.language;
-        const extraction = await extractSpec(ctx.claude, opts);
+        const extraction = await extractSpec(opts);
         setExtraction(session.doc_id, extraction);
         sendJson(res, 200, {
             ok: true,
@@ -727,7 +1811,7 @@ async function handleForgeIngestPlan(req, res, ctx) {
         };
         if (session.doc.language)
             opts.language = session.doc.language;
-        const plan = await generatePlan(ctx.claude, opts);
+        const plan = await generatePlan(opts);
         setPlan(session.doc_id, plan);
         sendJson(res, 200, {
             ok: true,
@@ -1122,143 +2206,782 @@ async function handleTrustEvent(req, res, _ctx) {
     await saveTrustMetrics(m);
     sendJson(res, 200, { ok: true, metrics: m });
 }
-async function handleTrustState(_req, res, _ctx) {
-    const m = await loadTrustMetrics();
-    /* Decay logic: if no events in last 30 days AND user has not
-     *  explicitly chosen to keep showing, suggest auto-collapse.
-     *  The panel decides what to do with the suggestion. */
-    let shouldProposeCollapse = false;
-    if (m.user_choice === 'default') {
-        const last = m.last_event_at ? new Date(m.last_event_at).getTime() : 0;
-        const proposedRecently = m.last_proposal_at
-            ? (Date.now() - new Date(m.last_proposal_at).getTime()) < 7 * 24 * 3600 * 1000
-            : false;
-        const daysSince = last ? (Date.now() - last) / (24 * 3600 * 1000) : Infinity;
-        shouldProposeCollapse = daysSince > 30 && !proposedRecently;
-    }
+async function handleKeysStatus(_req, res) {
+    /* Read ~/.yujin-forge/provider_keys.json + license.json without
+     * exposing values. Just boolean presence.
+     *
+     * alpha.34 fix (Producer/Consumer Symmetry, SQ Sec 14):
+     * Keys in the response MUST match the JSON slot names used by:
+     *   - the writer (POST /api/forge/keys-set, src/chat/tools/keys.ts)
+     *   - the panel HTML rows (data-key-slot="anthropic_api_key")
+     * Previously this endpoint returned short names ('anthropic')
+     * while the panel + writer used full slot names
+     * ('anthropic_api_key'), so the per-row UI always showed every
+     * row as MISSING even when the keys were present. Symptom Pablo
+     * caught: 'figuran desactivadas pero brain + STT/TTS funcionan'.
+     *
+     * Also returns license_plan as a STRING (not a boolean) so the
+     * settings panel can display the actual plan label. */
+    /* alpha.44 C1: keys live in the encrypted Vault now. The
+     * helper auto-migrates the legacy provider_keys.json on first
+     * read; we just ask for the boolean status of each slot. */
+    const { listStatus } = await import('../core/provider_keys.js');
+    const out = await listStatus();
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    let license_plan = 'none';
+    let license_user_handle = null;
+    let license_last_validated_at = null;
+    try {
+        const p = path.join(home, '.yujin-forge', 'license.json');
+        const raw = await fs.promises.readFile(p, 'utf-8');
+        const j = JSON.parse(raw);
+        if (typeof j.plan === 'string')
+            license_plan = j.plan;
+        if (typeof j.user_handle === 'string')
+            license_user_handle = j.user_handle;
+        if (typeof j.last_validated_at === 'string')
+            license_last_validated_at = j.last_validated_at;
+    }
+    catch { /* no license file */ }
     sendJson(res, 200, {
         ok: true,
-        metrics: m,
-        propose_auto_collapse: shouldProposeCollapse,
+        keys: out,
+        license_plan,
+        license_user_handle,
+        license_last_validated_at,
+        license_can_sync: license_user_handle !== null,
     });
 }
-async function handleVaultList(res) {
+/** PND-069 -- GET /api/forge/brain-config. Devuelve el
+ *  brain_config completo + el chatProvider activo de ESTA sesion
+ *  (que puede diferir de anthropic_mode hasta reabrir el panel). */
+async function handleBrainConfigGet(_req, res, ctx) {
+    const { readBrainConfig } = await import('../core/brain_config.js');
+    const cfg = await readBrainConfig();
+    sendJson(res, 200, {
+        ok: true,
+        config: cfg,
+        active_chat_provider: ctx.chatProvider ?? 'anthropic-api',
+    });
+}
+/** PND-069 -- POST /api/forge/brain-config. Acepta un subset de
+ *  campos; valida y persiste. anthropic_mode requiere reabrir el
+ *  panel para tomar efecto (el brain client se construye al boot);
+ *  eco_enabled y los bindings aplican en el proximo turno. */
+async function handleBrainConfigSet(req, res) {
+    const { readBrainConfig, writeBrainConfig, ALL_BRAIN_PROVIDERS, } = await import('../core/brain_config.js');
+    let body;
     try {
-        const vault = await Vault.open({ configDir: configDir() });
-        sendJson(res, 200, { ok: true, slots: vault.list() });
+        body = JSON.parse(await readBody(req));
     }
-    catch (err) {
-        sendJson(res, 500, {
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-        });
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid json body' });
+        return;
+    }
+    const cfg = await readBrainConfig();
+    if (typeof body.eco_enabled === 'boolean')
+        cfg.eco_enabled = body.eco_enabled;
+    if (typeof body.startup_tabs_enabled === 'boolean')
+        cfg.startup_tabs_enabled = body.startup_tabs_enabled;
+    if (body.anthropic_mode === 'plan' || body.anthropic_mode === 'console') {
+        cfg.anthropic_mode = body.anthropic_mode;
+    }
+    if (body.chat_default_tier === 'eco' || body.chat_default_tier === 'frontier') {
+        cfg.chat_default_tier = body.chat_default_tier;
     }
+    for (const tier of ['eco', 'frontier']) {
+        const b = body[tier];
+        if (!b || typeof b !== 'object')
+            continue;
+        const provider = typeof b.provider === 'string'
+            && ALL_BRAIN_PROVIDERS.includes(b.provider)
+            ? b.provider : null;
+        const model = typeof b.model === 'string' && b.model.trim() !== ''
+            ? b.model.trim() : null;
+        if (provider)
+            cfg[tier].provider = provider;
+        if (model)
+            cfg[tier].model = model;
+    }
+    await writeBrainConfig(cfg);
+    sendJson(res, 200, { ok: true, config: cfg, restart_needed_for: ['anthropic_mode'] });
 }
-async function handleVaultSet(req, res) {
+/** PND-064 -- POST /api/forge/panel-invoke. Paridad total de tools
+ *  en modo Plan: el MCP server local reenvia aca cada nac3_invoke
+ *  del subproceso `claude -p`. Corre el MISMO dispatcher que el
+ *  modo API (runForgeTool -> runNac3Invoke), con el mismo policy
+ *  gate. Los resultados de panel-dispatch (pizarron) se encolan
+ *  para que el panel los materialice; los demas se devuelven al
+ *  subproceso. Token-gated (timing-safe). */
+async function handlePanelInvoke(req, res, ctx) {
     let body;
     try {
         body = JSON.parse(await readBody(req));
     }
     catch {
-        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        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' });
+    /* Token-gate (CR-D1 lesson: no confiar en "solo loopback"). */
+    const expected = ctx.panelPushToken || '';
+    const got = typeof body.token === 'string' ? body.token : '';
+    const crypto = await import('node:crypto');
+    const ok = expected.length > 0 && got.length === expected.length
+        && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
+    if (!ok) {
+        sendJson(res, 403, { ok: false, error: 'forbidden' });
         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;
+    const verb_id = typeof body.verb_id === 'string' ? body.verb_id : '';
+    const args = (body.args && typeof body.args === 'object' && !Array.isArray(body.args))
+        ? body.args : {};
+    if (!verb_id) {
+        sendJson(res, 400, { ok: false, error: 'missing verb_id', text: 'Falta verb_id.' });
+        return;
     }
-    let expiryOpt;
-    if (body.expiry === null) {
-        expiryOpt = null;
+    /* Mismo dispatcher que el modo API. Ctx completo (incluye
+     * projectSlug para graph/pending/wiring). */
+    const { runForgeTool } = await import('./tools.js');
+    const toolCtx = { projectRoot: ctx.projectRoot, projectSlug: ctx.projectSlug, ...(ctx.reanchor ? { reanchor: ctx.reanchor } : {}) };
+    let r;
+    try {
+        r = await runForgeTool('nac3_invoke', { verb_id, args }, toolCtx);
     }
-    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();
+    catch (err) {
+        const m = err instanceof Error ? err.message : String(err);
+        sendJson(res, 200, { ok: false, is_error: true, text: 'El verbo fallo: ' + m });
+        return;
     }
-    try {
-        const vault = await Vault.open({ configDir: configDir() });
-        await vault.set(body.slot, body.plaintext, {
-            ...(kindOpt ? { kind: kindOpt } : {}),
-            ...(expiryOpt !== undefined ? { expiry: expiryOpt } : {}),
+    const result = (r.result && typeof r.result === 'object') ? r.result : {};
+    /* Caso 1: panel-dispatch (pizarron). Encolar para el panel +
+     * devolver al subproceso un texto de exito. */
+    if (result.nac3_panel_dispatch === true && result.verb && typeof result.verb === 'object') {
+        const verb = result.verb;
+        const dispatchArgs = (result.args && typeof result.args === 'object')
+            ? result.args : {};
+        const payload = (result.server_payload && typeof result.server_payload === 'object')
+            ? result.server_payload : null;
+        const shortVerb = String(verb.id || '').replace(/^yujin\./, '');
+        const { enqueuePanelDispatch } = await import('./panel_queue.js');
+        const seq = enqueuePanelDispatch(shortVerb, payload ? { ...dispatchArgs, server_payload: payload } : dispatchArgs, new Date().toISOString());
+        sendJson(res, 200, {
+            ok: true, seq, panel_dispatch: true,
+            text: 'Listo: enviado al pizarron (' + shortVerb + ').',
         });
-        /* 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 });
+        return;
     }
-    catch (err) {
-        sendJson(res, 400, {
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
+    /* Caso 2: requiere aprobacion. El subproceso no puede abrir el
+     * modal sincronicamente; le decimos que el usuario debe aprobar.
+     * NO se ejecuta la accion destructiva sin aprobacion. */
+    if (result.nac3_panel_approval_required === true) {
+        sendJson(res, 200, {
+            ok: false, approval_required: true,
+            text: 'Esta accion requiere aprobacion del usuario en el panel de Forge. '
+                + 'Pedile que la apruebe y reintenta, o ejecutala en modo API.',
         });
+        return;
     }
-}
-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);
+    /* Caso 3: resultado normal -> devolver al subproceso. Texto
+     * compacto + el JSON del resultado para que el modelo razone. */
+    let text;
+    try {
+        text = typeof r.result === 'string' ? r.result : JSON.stringify(r.result);
     }
+    catch {
+        text = '[resultado no serializable]';
+    }
+    /* Dogfood 2026-06-10 -- 8000 era muy bajo: list-edges (104
+     * aristas en JSON) se truncaba y el modelo caia al workaround de
+     * leer el .db con sqlite. Alineado con el truncado de tool
+     * results del modo API (200 KB). */
     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,
-        })),
+        ok: r.is_error !== true,
+        is_error: r.is_error === true,
+        text: text.slice(0, 200000),
     });
 }
-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,
-    });
+/** PND-064 slice B -- GET /api/forge/panel-queue?after=<seq>. El
+ *  panel hace polling mientras corre en modo plan. */
+async function handlePanelQueue(_req, res, url) {
+    const after = Number(url.searchParams.get('after') || '0');
+    const { readPanelDispatchesAfter } = await import('./panel_queue.js');
+    const { items, last } = readPanelDispatchesAfter(after);
+    sendJson(res, 200, { ok: true, items, last });
 }
-async function handleModeSet(req, res, ctx) {
-    let body;
+/** GRAPH-1 -- POST /api/forge/graph-regenerate. Deriva el grafo
+ *  completo (nodos de modulo + libreria + aristas de imports,
+ *  validadas), lo persiste y poda colgantes. Reutilizable desde el
+ *  boton Refresh y el auto-regen del watcher. */
+/** Mobile pairing QR -- genera el codigo + envelope cifrado y lo
+ *  renderiza como QR SVG para que Forge Mobile lo escanee. El
+ *  usuario solo tipea el codigo de 6 digitos en el telefono. El
+ *  payload (que lleva el server_api_key) NUNCA sale por aca en
+ *  claro: solo va el QR cifrado + el codigo (que el usuario ya ve
+ *  en su propia pantalla). */
+async function handleMobilePair(_req, res) {
     try {
-        body = JSON.parse(await readBody(req));
+        const { assemblePairing } = await import('../commands/mobile.js');
+        const built = await assemblePairing({});
+        if (!built.ok || !built.qr || !built.code) {
+            sendJson(res, 200, { ok: false, error: built.error ?? 'no pude generar el pairing', hint: built.hint });
+            return;
+        }
+        const QRCode = (await import('qrcode')).default;
+        const qrSvg = await QRCode.toString(built.qr, {
+            type: 'svg', margin: 1, errorCorrectionLevel: 'M',
+            color: { dark: '#1a1a1a', light: '#f5f0e6' },
+        });
+        sendJson(res, 200, { ok: true, code: built.code, expires_at: built.expires_at, qr_svg: qrSvg });
     }
-    catch {
-        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+    catch (err) {
+        sendJson(res, 200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+}
+/** Startup tabs -- arma las 4 pestanas del pizarron server-side.
+ *  Devuelve {enabled, tabs:[{key,title,kind,content}]}. El panel
+ *  las materializa al abrir (salvo las que el usuario cerro) y
+ *  hace polling para auto-refrescarlas. */
+async function handleStartupTabs(_req, res, ctx, url) {
+    const slug = ctx.projectSlug || '';
+    let enabled = true;
+    try {
+        const { readBrainConfig } = await import('../core/brain_config.js');
+        enabled = (await readBrainConfig()).startup_tabs_enabled !== false;
+    }
+    catch { /* default on */ }
+    if (!enabled) {
+        sendJson(res, 200, { ok: true, enabled: false, tabs: [] });
         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(', ') });
+    /* i18n-boundary pass -- los titulos + headers de las tabs van en
+     * el idioma del usuario (los ids/verbos no). */
+    const { tForLang } = await import('../i18n/index.js');
+    const lang = (url.searchParams.get('lang') || 'es');
+    const t = (k) => tForLang(lang, k);
+    const tabs = [];
+    /* 1 + 2: grafo (grafico + semantico). */
+    try {
+        const { listRelevant, listAllEdges } = await import('../semantic_graph/store.js');
+        /* Vista arquitectonica: los nodos derivados module.* y lib.*
+         * (no los comp.* de export fino del watcher, que tienen kind
+         * 'module' pero saturan el grafo). Filtro por prefijo de id. */
+        const allNodes = slug ? await listRelevant(slug, { limit: 100000, min_confidence: 'claimed' }) : [];
+        const nodes = allNodes.filter((n) => n.id.startsWith('module.') || n.id.startsWith('lib.'));
+        const allEdges = slug ? await listAllEdges(slug) : [];
+        const nodeIdSet = new Set(nodes.map((n) => n.id));
+        const edges = allEdges.filter((e) => nodeIdSet.has(e.from_id) && nodeIdSet.has(e.to_id));
+        const gNodes = nodes.map((n) => ({ id: n.id, label: n.name || n.id, weight: n.weight, kind: n.kind, detail: n.purpose || '' }));
+        const gEdges = edges.map((e) => ({ from: e.from_id, to: e.to_id, kind: e.kind }));
+        tabs.push({ key: 'startup_graph', title: t('startup.tab.graph'), kind: 'graph', content: JSON.stringify({ nodes: gNodes, edges: gEdges }) });
+        /* Grafo semantico = misma data en markdown (tabla de nodos por
+         * peso + conteo de aristas). */
+        const top = [...nodes].sort((a, b) => (b.weight || 0) - (a.weight || 0)).slice(0, 40);
+        let md = '# ' + t('startup.tab.graphSem') + ' -- ' + (slug || 'proyecto') + '\n\n'
+            + nodes.length + ' ' + t('graph.term.nodes') + ', ' + edges.length + ' ' + t('graph.term.edges') + '.\n\n'
+            + '| ' + t('startup.tab.graphSem') + ' | | ' + t('pizarron.graph.detail.weight') + ' |\n|---|---|---|\n';
+        for (const n of top)
+            md += '| ' + (n.name || n.id) + ' | ' + n.kind + ' | ' + (Math.round((n.weight || 0) * 100) / 100) + ' |\n';
+        tabs.push({ key: 'startup_graph_sem', title: t('startup.tab.graphSem'), kind: 'md', content: md });
+    }
+    catch { /* sin grafo */ }
+    /* 3: pendings. */
+    try {
+        if (slug) {
+            const { readPending } = await import('../pending/store.js');
+            const pf = await readPending(slug);
+            const open = (pf.items || []).filter((i) => !i.closed_at);
+            let md = '# Pendientes activos (' + open.length + ')\n\n';
+            const byPrio = [...open].sort((a, b) => (b.priority || 0) - (a.priority || 0));
+            md += '| ID | Prio | Titulo |\n|---|---|---|\n';
+            for (const it of byPrio.slice(0, 60)) {
+                md += '| ' + String(it.id) + ' | ' + (it.priority ?? '-') + ' | ' + String(it.title || '').replace(/\|/g, '/').slice(0, 90) + ' |\n';
+            }
+            tabs.push({ key: 'startup_pendings', title: t('startup.tab.pendings'), kind: 'md', content: md });
+        }
+    }
+    catch { /* sin pendings */ }
+    /* 4: workflow como GRAFO de nodos (las 6 fases del flujo yujin
+     * con sus pasos), coloreadas por estado (done/pendiente) cuando
+     * hay workflow state. Cumple el pedido de "workflow como grafo
+     * de nodos y conectores con detalle al click". */
+    try {
+        /* PND-094 -- vista jerarquica de FASES + tareas (no grafo): cada
+         * fase con su avance + sus tareas debajo con su estado. */
+        const { readWorkflow } = await import('../workflow/state.js');
+        const { computeWorkflowView } = await import('../workflow/view.js');
+        const wf = await readWorkflow(ctx.projectRoot);
+        const view = computeWorkflowView(wf);
+        tabs.push({ key: 'startup_workflow', title: t('startup.tab.workflow'), kind: 'workflow', content: JSON.stringify(view) });
+    }
+    catch {
+        tabs.push({ key: 'startup_workflow', title: t('startup.tab.workflow'), kind: 'md', content: '# Workflow\n\nSin datos.\n' });
+    }
+    sendJson(res, 200, { ok: true, enabled: true, tabs });
+}
+/** Formato de id de pending para display (PND-NNN). */
+function formatPendId(id) {
+    if (typeof id === 'number')
+        return 'PND-' + String(id).padStart(3, '0');
+    return String(id);
+}
+/** Las 6 fases del flujo yujin (18 pasos), para el grafo de
+ *  workflow. Cada fase es un nodo con sus pasos en el detalle. */
+const WORKFLOW_PHASES = [
+    { id: 'phase_i', label: 'I. Descubrimiento', steps: ['1 intent', '2 vault inventory', '3 legacy audit', '3.5 brownfield'] },
+    { id: 'phase_ii', label: 'II. Clarificacion', steps: ['4 funcional', '5 NFR cuantitativo', '6 NFR estructural', '7 NFR governance', '8 NFR operacional', '9 blocks'] },
+    { id: 'phase_iii', label: 'III. Especificacion', steps: ['10 RFP', '11 arquitectura', '12 design system'] },
+    { id: 'phase_iv', label: 'IV. Aprobacion', steps: ['13 gate de aprobacion'] },
+    { id: 'phase_v', label: 'V. Construccion', steps: ['14 scaffolding', '15 block-dev', '16 tests'] },
+    { id: 'phase_vi', label: 'VI. Entrega', steps: ['17 QA visual', '18 ship'] },
+];
+/** Reune las keys "done" del workflow state (recursivo: cualquier
+ *  objeto con done_at cuenta como hecho). */
+function collectDoneWorkflowKeys(wf) {
+    const done = new Set();
+    const visit = (obj, keyPath) => {
+        if (!obj || typeof obj !== 'object')
+            return;
+        const o = obj;
+        if (o.done_at || o.completed_at || o.approved_at)
+            done.add(keyPath);
+        for (const [k, v] of Object.entries(o)) {
+            if (v && typeof v === 'object')
+                visit(v, k);
+        }
+    };
+    visit(wf, 'root');
+    return done;
+}
+/** Construye el grafo {nodes,edges} de las 6 fases del workflow,
+ *  coloreando done vs pendiente. Las labels de fase salen de las
+ *  keys canonicas workflow.phase.* (i18n). */
+async function buildWorkflowGraph(done, lang) {
+    const { tForLang } = await import('../i18n/index.js');
+    const phaseLabel = (id, fallback) => {
+        const v = tForLang(lang, 'workflow.phase.' + id.replace('phase_', ''));
+        return v && v !== ('workflow.phase.' + id.replace('phase_', '')) ? v : fallback;
+    };
+    const nodes = WORKFLOW_PHASES.map((p) => {
+        const isDone = done.has(p.id) || p.steps.some((s) => done.has(s));
+        const label = phaseLabel(p.id, p.label);
+        return {
+            id: p.id, label,
+            weight: 0.8, kind: 'phase',
+            color: isDone ? '#3fa85e' : '#c8a04d',
+            detail: '**' + label + '**\n\n' + (isDone ? 'Estado: avanzada\n\n' : 'Estado: pendiente\n\n')
+                + 'Pasos:\n' + p.steps.map((s) => '- ' + s).join('\n'),
+        };
+    });
+    const edges = [];
+    for (let i = 0; i < WORKFLOW_PHASES.length - 1; i++) {
+        edges.push({ from: WORKFLOW_PHASES[i].id, to: WORKFLOW_PHASES[i + 1].id, kind: 'uses', label: 'siguiente' });
+    }
+    return { nodes, edges };
+}
+async function handleGraphRegenerate(_req, res, ctx) {
+    const slug = ctx.projectSlug;
+    if (!slug) {
+        sendJson(res, 200, { ok: false, error: 'no active project slug' });
         return;
     }
-    const mode = body.mode;
     try {
-        await persistMode(ctx.projectRoot, mode);
+        /* enrich=false: regen rapido sin pegar a npm (el boton es
+         * interactivo; el enrich corre en el auto-ingest de boot). */
+        const { regenerateAndPersist } = await import('../semantic_graph/derive.js');
+        const stats = await regenerateAndPersist({ project_root: ctx.projectRoot, project_slug: slug, enrich: false });
+        sendJson(res, 200, { ok: true, ...stats });
     }
     catch (err) {
-        sendJson(res, 500, { ok: false,
-            error: err instanceof Error ? err.message : String(err) });
+        sendJson(res, 200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+}
+/** PND-069 -- GET /api/forge/brain-models?provider=anthropic.
+ *  Lista de modelos del provider via su API (key del vault) con
+ *  fallback estatico. Nunca expone la key. */
+async function handleBrainModels(_req, res, url) {
+    const { ALL_BRAIN_PROVIDERS } = await import('../core/brain_config.js');
+    const { listProviderModels } = await import('../core/provider_models.js');
+    const provider = url.searchParams.get('provider') ?? '';
+    if (!ALL_BRAIN_PROVIDERS.includes(provider)) {
+        sendJson(res, 400, { ok: false, error: 'unknown provider: ' + provider.slice(0, 40) });
         return;
     }
-    /* Set cookie so the next request renders in the new mode
+    const result = await listProviderModels(provider);
+    sendJson(res, 200, { ok: true, ...result });
+}
+/** alpha.59z.114 -- pull the canonical license row from the
+ *  HITO 4 worker (which reads the Polar webhook D1) and refresh
+ *  the local cache. Hit by the panel's "Sincronizar plan" button
+ *  + by the silent auto-sync on settings open when local plan
+ *  reads 'none' but user_handle is set. */
+async function handleLicenseSync(_req, res) {
+    const { syncLicense } = await import('../license/sync.js');
+    const report = await syncLicense({ verbose: false });
+    if (!report.ok) {
+        sendJson(res, 200, {
+            ok: false,
+            error: report.error ?? 'sync failed',
+            http_status: report.http_status,
+            local_plan_before: report.local_plan_before,
+        });
+        return;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        server_plan: report.server_plan,
+        local_plan_before: report.local_plan_before,
+        local_plan_after: report.local_plan_after,
+        last_validated_at: report.last_validated_at,
+    });
+}
+/** alpha.59z.117 -- write user_handle to the local polar cache
+ *  + run an immediate sync. Returns the final cache state.
+ *  Used by the panel "Conectar tu cuenta Polar" first-run flow. */
+async function handleLicenseHandle(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 handle = typeof body.handle === 'string' ? body.handle.trim().toLowerCase() : '';
+    if (!handle || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(handle)) {
+        sendJson(res, 400, { ok: false, error: 'handle must be a valid email address' });
+        return;
+    }
+    const polar = await import('../core/polar.js');
+    const current = await polar.readLicense();
+    await polar.writeLicense({ ...current, user_handle: handle });
+    const { syncLicense } = await import('../license/sync.js');
+    const report = await syncLicense({ verbose: false });
+    sendJson(res, 200, {
+        ok: report.ok,
+        handle_saved: handle,
+        server_plan: report.server_plan,
+        local_plan_before: report.local_plan_before,
+        local_plan_after: report.local_plan_after,
+        last_validated_at: report.last_validated_at,
+        error: report.error,
+        http_status: report.http_status,
+    });
+}
+const ALLOWED_KEY_SLOTS = new Set([
+    'anthropic_api_key',
+    'openai_api_key',
+    'google_ai_key',
+    'google_stt_key',
+    'google_tts_key',
+    'whisper_api_key',
+    'elevenlabs_api_key',
+]);
+async function handleReadFile(req, res, ctx) {
+    const u = new URL(req.url ?? '/', 'http://localhost');
+    const rel = (u.searchParams.get('path') || '').trim();
+    if (!rel || rel.startsWith('/') || rel.includes('..') || rel.length > 500) {
+        sendJson(res, 400, { ok: false, error: 'path must be a non-empty project-relative string (no .. , no leading slash)' });
+        return;
+    }
+    const path = await import('node:path');
+    const fs = await import('node:fs');
+    const abs = path.resolve(ctx.projectRoot, rel);
+    if (!isInside(abs, ctx.projectRoot)) {
+        sendJson(res, 403, { ok: false, error: 'path escapes project root' });
+        return;
+    }
+    try {
+        const buf = await fs.promises.readFile(abs);
+        /* Treat as text if it parses cleanly; otherwise refuse. */
+        if (buf.length > 2_000_000) {
+            sendJson(res, 413, { ok: false, error: 'file too large (>2 MB)' });
+            return;
+        }
+        const text = buf.toString('utf-8');
+        sendJson(res, 200, { ok: true, path: rel, content: text, size_bytes: buf.length });
+    }
+    catch (err) {
+        sendJson(res, 404, { ok: false, error: 'file not found: ' + (err instanceof Error ? err.message : String(err)) });
+    }
+}
+async function handleWriteFile(req, res, ctx) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'unreadable body' });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const rel = typeof body.path === 'string' ? body.path.trim() : '';
+    const content = typeof body.content === 'string' ? body.content : '';
+    if (!rel || rel.startsWith('/') || rel.includes('..') || rel.length > 500) {
+        sendJson(res, 400, { ok: false, error: 'path must be a non-empty project-relative string (no .. , no leading slash)' });
+        return;
+    }
+    if (content.length > 5_000_000) {
+        sendJson(res, 413, { ok: false, error: 'content too large (>5 MB)' });
+        return;
+    }
+    const path = await import('node:path');
+    const fs = await import('node:fs');
+    const abs = path.resolve(ctx.projectRoot, rel);
+    if (!isInside(abs, ctx.projectRoot)) {
+        sendJson(res, 403, { ok: false, error: 'path escapes project root' });
+        return;
+    }
+    try {
+        /* Atomic write: tmp file + rename. */
+        await fs.promises.mkdir(path.dirname(abs), { recursive: true });
+        const tmp = abs + '.tmp.' + Date.now();
+        await fs.promises.writeFile(tmp, content, 'utf-8');
+        await fs.promises.rename(tmp, abs);
+        const st = await fs.promises.stat(abs);
+        sendJson(res, 200, { ok: true, path: rel, bytes_written: st.size });
+    }
+    catch (err) {
+        sendJson(res, 500, { ok: false, error: 'write failed: ' + (err instanceof Error ? err.message : String(err)) });
+    }
+}
+async function handleKeysSet(req, res) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: 'unreadable body' });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const slot = typeof body.slot === 'string' ? body.slot.trim() : '';
+    if (!ALLOWED_KEY_SLOTS.has(slot)) {
+        sendJson(res, 400, { ok: false, error: 'slot must be one of: ' + Array.from(ALLOWED_KEY_SLOTS).join(', ') });
+        return;
+    }
+    /* value === '' OR null means clear. Otherwise it is the new
+     * key value (min 8 chars, no leading/trailing whitespace). */
+    const value = body.value === null ? '' : (typeof body.value === 'string' ? body.value.trim() : '');
+    if (value !== '' && value.length < 8) {
+        sendJson(res, 400, { ok: false, error: 'key value too short (min 8 chars)' });
+        return;
+    }
+    /* alpha.44 C1: persist via the encrypted Vault helper. The
+     * helper handles the legacy plaintext migration on first call
+     * + atomic write + slot validation. */
+    try {
+        const { setKey } = await import('../core/provider_keys.js');
+        await setKey(slot, value === '' ? null : value);
+    }
+    catch (err) {
+        sendJson(res, 400, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    sendJson(res, 200, { ok: true, slot, set: value !== '' });
+}
+async function handleSupportReport(req, res) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: 'unreadable body: ' + (err instanceof Error ? err.message : String(err)) });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const { validateInbound, recordReport } = await import('../support/reports.js');
+    /* Support either a single report or an array (the panel
+     * batches up to 50 + flushes every 30s). */
+    const ua = typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined;
+    const items = Array.isArray(body) ? body : [body];
+    let accepted = 0;
+    let rejected = 0;
+    for (const item of items.slice(0, 50)) {
+        const report = validateInbound(item, ua ? { user_agent: ua } : {});
+        if (report) {
+            await recordReport(report);
+            accepted++;
+        }
+        else {
+            rejected++;
+        }
+    }
+    sendJson(res, 200, { ok: true, accepted, rejected });
+}
+async function handleSupportReportList(req, res) {
+    /* Local panel only -- we already gate the chat server to
+     * loopback. No additional auth needed for read. */
+    const { readReports } = await import('../support/reports.js');
+    const u = new URL(req.url ?? '/', 'http://localhost');
+    const limit = Math.min(500, Math.max(1, parseInt(u.searchParams.get('limit') ?? '100', 10) || 100));
+    const reports = (await readReports()).slice(-limit);
+    sendJson(res, 200, { ok: true, count: reports.length, reports });
+}
+async function handleTrustState(_req, res, _ctx) {
+    const m = await loadTrustMetrics();
+    /* Decay logic: if no events in last 30 days AND user has not
+     *  explicitly chosen to keep showing, suggest auto-collapse.
+     *  The panel decides what to do with the suggestion. */
+    let shouldProposeCollapse = false;
+    if (m.user_choice === 'default') {
+        const last = m.last_event_at ? new Date(m.last_event_at).getTime() : 0;
+        const proposedRecently = m.last_proposal_at
+            ? (Date.now() - new Date(m.last_proposal_at).getTime()) < 7 * 24 * 3600 * 1000
+            : false;
+        const daysSince = last ? (Date.now() - last) / (24 * 3600 * 1000) : Infinity;
+        shouldProposeCollapse = daysSince > 30 && !proposedRecently;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        metrics: m,
+        propose_auto_collapse: shouldProposeCollapse,
+    });
+}
+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. */
@@ -1466,6 +3189,37 @@ async function handleChat(req, res, ctx) {
         sendJson(res, 400, { ok: false, error: 'messages[] required' });
         return;
     }
+    /* alpha.59e -- SSE streaming mode. Client opts in via
+     * body.stream=true. We keep the response open + emit events
+     * during the tool loop instead of bundling everything in a
+     * single JSON. */
+    const streamMode = body.stream === true;
+    let sseEmit = null;
+    if (streamMode) {
+        res.writeHead(200, {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-cache, no-transform',
+            'connection': 'keep-alive',
+            'x-accel-buffering': 'no',
+        });
+        sseEmit = (event, data) => {
+            try {
+                const payload = JSON.stringify(data ?? {});
+                res.write('event: ' + event + '\n');
+                res.write('data: ' + payload + '\n\n');
+            }
+            catch { /* ignore */ }
+        };
+    }
+    /* alpha.51 -- session-level brain tier override from slash
+     * commands (/eco /frontier /auto). null = let cost_router
+     * decide per-turn. The router reads workflow state + verb
+     * hints to pick the right tier; this override pins the
+     * decision when the user signaled an explicit preference. */
+    let brainOverride;
+    if (body.brain_tier_override === 'eco' || body.brain_tier_override === 'frontier') {
+        brainOverride = body.brain_tier_override;
+    }
     const normalized = [];
     for (const m of msgs) {
         if (typeof m !== 'object' || m === null)
@@ -1492,19 +3246,482 @@ async function handleChat(req, res, ctx) {
         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 } : {}),
-                };
-            },
+        /* alpha.51 -- ask the cost router which brain tier should
+         * serve this turn. alpha.52 -- runtime clients for anthropic
+         * + google_ai are wired. alpha.55 -- the router now runs a
+         * reasoning_gate + turn_classifier when there is no cheap
+         * signal so /auto becomes genuinely smart per turn. We pass
+         * the user_text + recent history + attachment count + the
+         * previous tier so the gate can detect sticky follow-ups
+         * and inherit. */
+        const { selectBrainForTurn } = await import('../core/cost_router.js');
+        const { makeUnifiedClient } = await import('../llm/multi_provider_client.js');
+        /* Pull previous tier from the last brain_routing.jsonl entry
+         * via the store (best-effort). The store keeps the last
+         * assistant reply; if it has a `brain_tier` annotation we use
+         * it. When absent, the gate just skips the sticky check. */
+        const recent = ctx.store.messages();
+        const lastAssistant = recent.slice().reverse().find((m) => m.role === 'assistant');
+        const previousTier = lastAssistant && (lastAssistant.brain_tier === 'eco' || lastAssistant.brain_tier === 'frontier')
+            ? lastAssistant.brain_tier
+            : undefined;
+        const previousDocLoaded = !!(lastAssistant && lastAssistant.doc_loaded === true);
+        const historyForGate = normalized.slice(-3).map((m) => ({
+            role: m.role,
+            content: typeof m.content === 'string' ? m.content : '',
+        }));
+        /* alpha.57 -- workflow phase wiring. If the user is in
+         * Phase III (specs: RFP / Arch / Design) or Phase V (block
+         * implementation), the router forces frontier. This is the
+         * structural signal Pablo flagged: the workflow itself
+         * knows when reasoning is needed. */
+        let workflowPhase;
+        try {
+            const { readWorkflow } = await import('../workflow/state.js');
+            const { inferActivePhase } = await import('../workflow/phase_inference.js');
+            const wf = await readWorkflow(ctx.projectRoot);
+            workflowPhase = inferActivePhase(wf);
+        }
+        catch { /* missing yujin.forge.json -> phase_i, no-op */ }
+        const brainSelection = await selectBrainForTurn({
+            user_override: brainOverride,
+            caller_hint: 'handleChat',
+            user_text: lastUserText,
+            history: historyForGate,
+            previous_tier: previousTier,
+            previous_doc_loaded: previousDocLoaded,
+            workflow_phase: workflowPhase,
         });
+        /* alpha.55 -- cap exceeded check. If the tier the router
+         * chose has zero remaining budget, return 429 BEFORE the
+         * LLM call so the user never gets billed past their cap.
+         * The panel modal (plan_limit_exceeded) lets them upgrade
+         * or switch tier. BYOK plans have Infinity cap so this
+         * is a no-op there. */
+        {
+            const { checkCap } = await import('../core/budget.js');
+            const capCheck = await checkCap(brainSelection.tier);
+            if (!capCheck.allowed) {
+                if (sseEmit) {
+                    sseEmit('error', {
+                        kind: 'plan_limit_exceeded',
+                        tier: capCheck.tier,
+                        plan: capCheck.plan,
+                        extension_url: capCheck.extension_url ?? null,
+                    });
+                    res.end();
+                }
+                else {
+                    sendJson(res, 429, {
+                        ok: false,
+                        error: 'plan_limit_exceeded',
+                        tier: capCheck.tier,
+                        plan: capCheck.plan,
+                        cap: Number.isFinite(capCheck.cap) ? capCheck.cap : null,
+                        used: capCheck.used,
+                        remaining: Number.isFinite(capCheck.remaining) ? capCheck.remaining : null,
+                        extension_url: capCheck.extension_url ?? null,
+                        reason: capCheck.reason,
+                        message: 'Has agotado el cupo mensual del tier ' + capCheck.tier +
+                            ' en el plan ' + capCheck.plan + '. Cambia de tier con /eco o /frontier, ' +
+                            'compra una extension, o usa BYOK.',
+                    });
+                }
+                return;
+            }
+        }
+        /* alpha.59e -- emit turn_start event so the panel knows
+         * which model is serving + how many rounds the loop can
+         * spend before exhaustion. */
+        if (sseEmit) {
+            sseEmit('turn_start', {
+                tier: brainSelection.tier,
+                provider: brainSelection.provider,
+                model: brainSelection.model,
+                runtime_wired: brainSelection.runtime_wired,
+                reason: brainSelection.reason,
+                workflow_phase: workflowPhase ?? null,
+            });
+        }
+        /* alpha.59e -- loop detection counter. We track (verb_id +
+         * args fingerprint) per turn; if the same call is made 3+
+         * times consecutively we abort + emit an error so the LLM
+         * cannot infinite-loop when Danger Zone is on. */
+        const callSig = [];
+        const LOOP_REPEAT_THRESHOLD = 3;
+        /* When the operator launched `yf chat --provider claude-code-cli`,
+         * route EVERY turn through ctx.claude (a ClaudeCliClient) and
+         * skip the unified cost_router branch -- otherwise the router
+         * would pick Gemini/Haiku/etc and bill against Console. The
+         * fallback branch below uses ctx.claude.chat() directly. */
+        const unified = ctx.chatProvider === 'claude-code-cli'
+            ? null
+            : makeUnifiedClient(brainSelection);
+        const callerForChat = unified
+            ? unified
+            : {
+                chat: async (r) => {
+                    /* alpha.59z.162 PND-021 -- when routing through the cli
+                     * subprocess, thread sseEmit as onStreamEvent so the panel
+                     * sees tool_round_start / _done as `claude -p` invokes its
+                     * own tools. The HTTP path gets the same feedback via the
+                     * runTool seam; this closes the parity gap. */
+                    const reqWithStream = sseEmit && ctx.chatProvider === 'claude-code-cli'
+                        ? { ...r, onStreamEvent: sseEmit }
+                        : r;
+                    const claudeReply = await ctx.claude.chat(reqWithStream);
+                    return { ...claudeReply, brain: { ...brainSelection, runtime_wired: false } };
+                },
+            };
+        /* alpha.59z.135 slice 11 -- panoramic graph snapshot. Compact
+         * structural view of the project graph, cached per-slug with
+         * hash refresh. The chat also receives the relevance ranking
+         * below (graphSection); snapshot is the panorama, relevance is
+         * the zoom. Graceful no-op on worker / vault failure. */
+        let snapshotSection = '';
+        try {
+            const { buildGraphSnapshotSection } = await import('./graph_snapshot.js');
+            const r = await buildGraphSnapshotSection({
+                project_slug: ctx.projectSlug || '',
+                /* alpha.59z.182 -- local only. The D1 worker fetcher is
+                 * parked until PND-016 closes P3 Platform billing/auth/
+                 * tier decisions. BYOK plain = no Yujin infra in chat hot
+                 * path. Slice 181 reintroduces a worker fetcher under P3. */
+                fetcher: async (slug) => {
+                    if (!slug)
+                        return { ok: false, nodes: [] };
+                    try {
+                        const { listRelevant } = await import('../semantic_graph/store.js');
+                        const nodes = await listRelevant(slug, { limit: 200 });
+                        return {
+                            ok: nodes.length > 0,
+                            nodes: nodes.map((n) => ({ id: n.id, kind: n.kind, label: n.name })),
+                        };
+                    }
+                    catch {
+                        return { ok: false, nodes: [] };
+                    }
+                },
+            });
+            if (r.ok && r.text)
+                snapshotSection = '\n\n' + r.text;
+        }
+        catch (_) { /* swallow -- chat continues without snapshot */ }
+        /* alpha.59p -- semantic graph injection. Pulls "what primitives
+         * exist in this project" from the worker + appends to system
+         * prompt so the LLM does NOT reinvent libs/components/protocols
+         * already present. Graceful no-op when worker unreachable or
+         * no vault key. */
+        let graphSection = '';
+        try {
+            const { fetchGraphSection, injectionEnabled } = await import('./semantic_graph_inject.js');
+            if (injectionEnabled()) {
+                const lastUser = [...normalized].reverse().find((m) => m.role === 'user');
+                const intent = lastUser && typeof lastUser.content === 'string'
+                    ? lastUser.content
+                    : (lastUser && Array.isArray(lastUser.content)
+                        ? lastUser.content.filter((b) => b && b.type === 'text').map((b) => b.text).join(' ')
+                        : '');
+                if (intent && intent.length > 0) {
+                    const r = await fetchGraphSection({
+                        intent,
+                        project_slug: ctx.projectSlug || '',
+                        limit: 8,
+                        token_budget: 500,
+                        timeout_ms: 1500,
+                    });
+                    if (r.ok && r.rendered_text)
+                        graphSection = '\n\n' + r.rendered_text;
+                }
+            }
+        }
+        catch (_) { /* swallow -- chat continues without graph */ }
+        /* alpha.59y.2 -- workflow state injection. Reads
+         *  yujin.forge.json/workflow.* and emits a compact "PROJECT
+         *  WORKFLOW STATE" block with rules of engagement (stay in
+         *  step, ASK on scope change, no silent advance). Disabled
+         *  via YF_WORKFLOW_INJECT_DISABLED=1. */
+        let workflowSection = '';
+        try {
+            const { fetchWorkflowSection } = await import('./workflow_inject.js');
+            const w = await fetchWorkflowSection({
+                projectRoot: ctx.projectRoot,
+                projectName: ctx.projectName,
+            });
+            if (w.ok && w.rendered_text)
+                workflowSection = '\n\n' + w.rendered_text;
+        }
+        catch (_) { /* swallow -- chat continues without workflow inject */ }
+        /* alpha.59z.180 PND-012 -- inject the per-project WIRING
+         * registry into the dynamic suffix every turn. Reads from
+         * ~/.yujin-forge/projects/<slug>/wiring.json (the local
+         * registry, populated by `yf wiring discover` or the
+         * yujin.wiring.discover verb). Empty when the file is missing
+         * or every hook is disabled. Cap at 20 hooks to keep the
+         * token budget bounded. */
+        let wiringSection = '';
+        try {
+            const { buildWiringSection } = await import('./wiring_inject.js');
+            const r = await buildWiringSection({ project_slug: ctx.projectSlug || '', limit: 20 });
+            if (r.rendered_text)
+                wiringSection = '\n\n' + r.rendered_text;
+        }
+        catch (_) { /* swallow -- chat continues without wiring inject */ }
+        /* alpha.59z.187 PND-039 -- auto-context-load. Single compact
+         * block with counts of graph nodes / wiring hooks / pending
+         * items so the LLM can answer "que sabes del proyecto" / "subi
+         * el know how" with concrete numbers without first invoking
+         * 3-5 verbs. Bounded by 1200 chars. Graceful no-op when slug
+         * empty / no data. */
+        let projectContextSection = '';
+        try {
+            const { buildProjectContextSection } = await import('./project_context_inject.js');
+            const r = await buildProjectContextSection({ project_slug: ctx.projectSlug || '', char_budget: 1200 });
+            if (r.rendered_text)
+                projectContextSection = r.rendered_text;
+        }
+        catch (_) { /* swallow */ }
+        /* alpha.59z.15 HITO 6.3 -- prefetch global learnings from
+         * the F103 worker. Falls back silently to '' on worker
+         * unreachable. Cache is 5 min so this is cheap. */
+        let globalLearnings = '';
+        try {
+            const { buildGlobalLearningsSection } = await import('../core/learnings_client.js');
+            globalLearnings = await buildGlobalLearningsSection({ maxTokens: 2000 });
+        }
+        catch (_) { /* swallow -- learnings are additive */ }
+        /* alpha.59z.26 F101 slice 2 + slice 5 sub-slice 3 -- prefetch
+         *  MCP bridges count + persistent enabled-state so the manifest
+         *  stub surfaces yujin.mcp.* verbs only when there is at least
+         *  one ENABLED bridge (Invariant 1: zero noise when Forge is
+         *  not in MCP mode OR every bridge is disabled). Registry has
+         *  60s cache + state.ts has its own 5s cache so the call is
+         *  cheap. */
+        let mcpAvailable = false;
+        try {
+            const { getActiveBridges } = await import('../mcp/bridge_registry.js');
+            const bridges = await getActiveBridges({ projectRoot: ctx.projectRoot });
+            mcpAvailable = bridges.some((b) => b.enabled);
+        }
+        catch (_) { /* registry failure -> stay with MCP-off behaviour */ }
+        /* alpha.59z.37 NAC-3 v3.x backend tools -- prefetch the
+         * adopter app's nac3_backend section (task #23). Empty
+         * string when the manifest does not declare it, when the
+         * file is missing, or when parsing failed. */
+        let backendToolsSection = '';
+        try {
+            const { loadBackendCatalogue, buildBackendToolsSection } = await import('../nac3/backend_tools.js');
+            const parsed = await loadBackendCatalogue(ctx.projectRoot);
+            if (parsed.catalogue && parsed.catalogue.tools.length > 0) {
+                backendToolsSection = buildBackendToolsSection(parsed.catalogue);
+            }
+        }
+        catch (_) { /* swallow */ }
+        const chatRequest = {
+            messages: normalized,
+            /* alpha.59z.163 PND-027 -- system prompt now split into a
+             * stable prefix (manifest, doctrines, design system, mode +
+             * tier headers from buildSystemPrompt) and a dynamic suffix
+             * (graph snapshots + workflow phase). The HTTP client tags
+             * the prefix with cache_control:ephemeral so multi-turn
+             * sessions hit the prompt cache instead of re-billing the
+             * full ~9KB every iteration. Director sprint #11 measured
+             * 1.8M tokens spent re-injecting; same applies BYOK-side. */
+            system: buildSystemPrompt(ctx, reqMode, pilotState, {
+                tier: brainSelection.tier,
+                provider: brainSelection.provider,
+                model: brainSelection.model,
+            }, globalLearnings, mcpAvailable, backendToolsSection, lastUserText, 
+            /* PND-064 -- pizarron reachability for THIS mode. In CLI mode
+             * the panel MCP bridge (slice B) makes it reachable via the
+             * pizarron_create_tab tool; in API/managed it is native. */
+            ctx.chatProvider === 'claude-code-cli'
+                ? (ctx.panelPushToken ? 'mcp-bridge' : 'none')
+                : 'native'),
+            systemDynamic: projectContextSection + snapshotSection + graphSection + wiringSection + workflowSection,
+            maxTokens: 1024,
+            tools: FORGE_TOOL_SPECS,
+            runTool: async (name, input) => {
+                /* alpha.59e -- loop detection. Build a signature from
+                 * the verb id + arg hash; if the last N entries are
+                 * identical, refuse this call. */
+                const verbId = typeof input.verb_id === 'string'
+                    ? String(input.verb_id)
+                    : name;
+                const argsSig = verbId + ':' + JSON.stringify(input).slice(0, 200);
+                callSig.push(argsSig);
+                const recent = callSig.slice(-LOOP_REPEAT_THRESHOLD);
+                if (recent.length === LOOP_REPEAT_THRESHOLD && recent.every((s) => s === argsSig)) {
+                    if (sseEmit) {
+                        sseEmit('error', {
+                            kind: 'loop_detected',
+                            verb_id: verbId,
+                            repeats: LOOP_REPEAT_THRESHOLD,
+                            message: 'Mismo verb invocado ' + LOOP_REPEAT_THRESHOLD + 'x consecutivo. Aborto el turn.',
+                        });
+                    }
+                    return {
+                        result: {
+                            error: 'loop_detected',
+                            verb_id: verbId,
+                            repeats: LOOP_REPEAT_THRESHOLD,
+                            hint: 'Probablemente el LLM esta llamando el mismo verbo con los mismos args en bucle. Reformula el prompt o ejecuta el paso manualmente.',
+                        },
+                        is_error: true,
+                    };
+                }
+                /* alpha.59e -- emit tool_round_start for the panel
+                 * progress bar. verb_hint = a short string the user
+                 * sees ("Leyendo seccion X", "Ejecutando git status",
+                 * etc) -- derived from verb_id + input. */
+                let verbHint = verbId;
+                if (verbId === 'yujin.shell.exec' && typeof input.command === 'string') {
+                    verbHint = 'shell: ' + String(input.command).slice(0, 60);
+                }
+                else if (verbId === 'yujin.reader.next-block') {
+                    verbHint = 'leyendo siguiente bloque';
+                }
+                else if (verbId.startsWith('yujin.reader.')) {
+                    verbHint = verbId.replace('yujin.reader.', 'reader/');
+                }
+                else if (verbId.startsWith('yujin.fs.')) {
+                    verbHint = verbId.replace('yujin.fs.', 'fs/');
+                }
+                else if (verbId.startsWith('yujin.pizarron.')) {
+                    verbHint = verbId.replace('yujin.pizarron.', 'pizarron/');
+                }
+                if (sseEmit) {
+                    const { extractVerbDetail } = await import('./claude_cli.js');
+                    sseEmit('tool_round_start', {
+                        round: callSig.length,
+                        verb_id: verbId,
+                        verb_hint: verbHint,
+                        detail: extractVerbDetail(verbId, input),
+                    });
+                }
+                const t0 = Date.now();
+                /* alpha.59f -- inject streamEmit into ToolContext so
+                 * runShellExec (and future long-running verbs) can emit
+                 * progress events mid-execution. */
+                const toolCtx = {
+                    projectRoot: ctx.projectRoot,
+                    projectSlug: ctx.projectSlug,
+                    ...(sseEmit ? { streamEmit: sseEmit } : {}),
+                    ...(ctx.reanchor ? { reanchor: ctx.reanchor } : {}),
+                };
+                const r = await runForgeTool(name, input, toolCtx);
+                /* alpha.59i -- if the result is an approval envelope,
+                 *  surface it as a dedicated SSE event so the panel
+                 *  opens the modal NOW instead of waiting for the full
+                 *  turn_complete payload. The envelope still flows
+                 *  through the regular tool_round path so the LLM sees
+                 *  it as a tool result (which is what triggers the
+                 *  legacy flow: turn ends, user approves, next turn
+                 *  carries the synthetic 'approved' message). */
+                if (sseEmit && r && r.result
+                    && typeof r.result === 'object'
+                    && r.result
+                        .nac3_panel_approval_required === true) {
+                    sseEmit('approval_required', r.result);
+                }
+                if (sseEmit) {
+                    sseEmit('tool_round_done', {
+                        round: callSig.length,
+                        verb_id: verbId,
+                        is_error: r.is_error === true,
+                        duration_ms: Date.now() - t0,
+                    });
+                }
+                return {
+                    result: r.result,
+                    ...(r.is_error ? { is_error: true } : {}),
+                };
+            },
+        };
+        let reply = await callerForChat.chat(chatRequest);
+        /* Echo brainSelection if the underlying client did not stamp
+         *  it (legacy ctx.claude path). */
+        if (!reply.brain) {
+            reply.brain = brainSelection;
+        }
+        /* alpha.57 -- post-reply escalation. If the eco tier produced
+         * a confused / refused / truncated reply (hallucinated error
+         * markers, dodge phrases, schema errors, length-vs-complexity
+         * mismatch), re-issue the same turn at frontier and show the
+         * user THAT reply instead. Cap-aware: only escalates if
+         * frontier still has budget. Cap 1 escalation per turn. */
+        let escalated = false;
+        let escalationSignals = [];
+        if (brainSelection.tier === 'eco' && !brainOverride) {
+            const { detectIncomplete } = await import('../core/incomplete_detector.js');
+            const detect = detectIncomplete({
+                user_text: lastUserText,
+                reply_text: reply.text,
+                tool_rounds: reply.toolRounds,
+            });
+            if (detect.incomplete) {
+                const { checkCap } = await import('../core/budget.js');
+                const capCheck = await checkCap('frontier');
+                if (capCheck.allowed) {
+                    const frontierSel = await selectBrainForTurn({
+                        user_override: 'frontier',
+                        caller_hint: 'escalation_after_eco[' + detect.signals.join(',').slice(0, 80) + ']',
+                        user_text: lastUserText,
+                        history: historyForGate,
+                        previous_tier: previousTier,
+                        previous_doc_loaded: previousDocLoaded,
+                        workflow_phase: workflowPhase,
+                    });
+                    /* PND-055 (CR-D11) -- en modo claude-code-cli el contrato
+                     * es "nunca facturar Console ni usar BYOK": cada turno va
+                     * por el subproceso `claude -p` (suscripcion). El escalado
+                     * NO debe construir un cliente unificado (Gemini/Anthropic
+                     * API), que facturaria por fuera de la suscripcion. Se
+                     * escala igual -- pero a traves de ctx.claude (el mismo
+                     * subproceso), preservando la funcionalidad de escalado
+                     * sin romper el modelo de billing. */
+                    const frontierClient = ctx.chatProvider === 'claude-code-cli'
+                        ? null
+                        : makeUnifiedClient(frontierSel);
+                    const frontierCaller = frontierClient
+                        ? frontierClient
+                        : {
+                            chat: async (r) => {
+                                const claudeReply = await ctx.claude.chat(r);
+                                return { ...claudeReply, brain: { ...frontierSel, runtime_wired: false } };
+                            },
+                        };
+                    try {
+                        /* alpha.58 -- rebuild system prompt for the frontier
+                         *  call so the tier header reflects the actual model
+                         *  serving the turn. */
+                        const frontierRequest = {
+                            ...chatRequest,
+                            system: buildSystemPrompt(ctx, reqMode, pilotState, {
+                                tier: frontierSel.tier,
+                                provider: frontierSel.provider,
+                                model: frontierSel.model,
+                            }, globalLearnings, mcpAvailable, backendToolsSection, lastUserText, ctx.chatProvider === 'claude-code-cli'
+                                ? (ctx.panelPushToken ? 'mcp-bridge' : 'none')
+                                : 'native'),
+                        };
+                        const frontierReply = await frontierCaller.chat(frontierRequest);
+                        reply = frontierReply;
+                        escalated = true;
+                        escalationSignals = detect.signals;
+                    }
+                    catch (escErr) {
+                        /* Escalation failure -> stick with the eco reply.
+                         * Log + continue. */
+                        const msg = escErr instanceof Error ? escErr.message : String(escErr);
+                        escalationSignals = [...detect.signals, 'escalation_failed[' + msg.slice(0, 60) + ']'];
+                    }
+                }
+                else {
+                    escalationSignals = [...detect.signals, 'escalation_blocked_by_cap'];
+                }
+            }
+        }
         // 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
@@ -1519,7 +3736,36 @@ async function handleChat(req, res, ctx) {
                 ctx.store.append(lastUser);
             }
         }
-        ctx.store.append({ role: 'assistant', content: reply.text });
+        /* alpha.56 -- tag the assistant turn with the tier that
+         * served it. The next turn's reasoning_gate reads this via
+         * lastAssistant.brain_tier to apply sticky inertia (a
+         * follow-up to a frontier turn stays in frontier unless the
+         * new user message has strong eco signals). Also detect
+         * whether the turn loaded a document (reader.* / fs.read-*)
+         * so the next router call routes to frontier even on a
+         * short follow-up like "Medium, Python" (because the user
+         * is about to ask the model to reason over the doc). */
+        const docLoaded = reply.toolRounds.some((r) => {
+            const input = r.input;
+            const vid = (input && typeof input === 'object' && 'verb_id' in input)
+                ? input.verb_id
+                : undefined;
+            const v = typeof vid === 'string' ? vid : '';
+            return (v === 'yujin.fs.read-file' ||
+                v === 'yujin.fs.read-project-file' ||
+                v.startsWith('yujin.reader.'));
+        });
+        /* alpha.57 -- when the turn escalated, the persisted tier is
+         * the FINAL one (frontier), not the eco initial one. This
+         * way the next turn's sticky inertia + previous_tier check
+         * see the canonical decision. */
+        const finalTier = escalated ? 'frontier' : brainSelection.tier;
+        ctx.store.append({
+            role: 'assistant',
+            content: reply.text,
+            brain_tier: finalTier,
+            ...(docLoaded ? { doc_loaded: true } : {}),
+        });
         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
@@ -1533,297 +3779,699 @@ async function handleChat(req, res, ctx) {
                 catch { /* non-fatal */ }
             }
         }
-        sendJson(res, 200, {
+        /* alpha.59z.186 PND-020 Phase 2b -- LLM-claim post-turn hook.
+         * Scan the reply for import statements in fenced code blocks
+         * + upsert the libraries the LLM mentions but the local graph
+         * doesn't know yet (confidence='claimed', weight=0.3 so they
+         * don't dominate ranking until the user promotes them).
+         * Fire-and-forget; never throws. */
+        if (ctx.projectSlug) {
+            const slug = ctx.projectSlug;
+            void (async () => {
+                try {
+                    const { ingestClaimsFromReply } = await import('../semantic_graph/llm_claim.js');
+                    await ingestClaimsFromReply(slug, reply.text);
+                }
+                catch { /* swallow */ }
+            })();
+        }
+        /* alpha.59z.188 PND-036 + PND-037 -- post-reply quality
+         * detectors. Two separate failure modes:
+         *  - "voy a configurar X" without any tool_use (completion
+         *    hallucination).
+         *  - "no puedo X" when the user asked for X AND a verb exists
+         *    that does X (unwarranted refusal).
+         * Both trigger a one-shot next-turn frontier hint so the
+         * router escalates the conversation. Pure heuristics, swallow
+         * all errors. */
+        try {
+            const { checkCompletionHallucination } = await import('./completion_hallucination_detector.js');
+            const { checkUnwarrantedRefusal } = await import('./refusal_detector.js');
+            const hCheck = checkCompletionHallucination(reply.text, reply.toolRounds.length);
+            /* Pull the most recent user message text for the refusal
+             *  detector. */
+            const lastUser = [...normalized].reverse().find((m) => m.role === 'user');
+            const lastUserContent = lastUser?.content;
+            const lastUserText = typeof lastUserContent === 'string'
+                ? lastUserContent
+                : Array.isArray(lastUserContent)
+                    ? lastUserContent
+                        .filter((b) => !!b && typeof b === 'object')
+                        .filter((b) => b.type === 'text')
+                        .map((b) => b.text ?? '')
+                        .join(' ')
+                    : '';
+            const rCheck = checkUnwarrantedRefusal(reply.text, lastUserText);
+            if (hCheck.is_hallucinated || rCheck.is_unwarranted_refusal || hCheck.is_confused) {
+                void (async () => {
+                    try {
+                        const path = await import('node:path');
+                        const os = await import('node:os');
+                        const fs = await import('node:fs/promises');
+                        const dir = process.env['YF_CONFIG_DIR']
+                            || (process.env['HOME'] || process.env['USERPROFILE'] || os.homedir() + '/.yujin-forge');
+                        const root = dir.endsWith('.yujin-forge') ? dir : path.join(dir, '.yujin-forge');
+                        await fs.mkdir(root, { recursive: true });
+                        const kind = hCheck.is_hallucinated ? 'completion_hallucination'
+                            : rCheck.is_unwarranted_refusal ? 'unwarranted_refusal'
+                                : 'confusion_signal';
+                        const line = JSON.stringify({
+                            ts: new Date().toISOString(), kind,
+                            matched_phrase: hCheck.is_hallucinated ? hCheck.matched_phrase : rCheck.matched_refusal,
+                            topic: rCheck.topic || null,
+                            available_verbs: rCheck.available_verbs,
+                            reply_chars: reply.text.length,
+                            tier_served: reply.brain?.tier ?? brainSelection.tier,
+                        }) + '\n';
+                        await fs.appendFile(path.join(root, 'hallucinations.jsonl'), line, 'utf-8');
+                        await fs.writeFile(path.join(root, 'next_turn_frontier_hint.json'), JSON.stringify({
+                            reason: kind,
+                            at: new Date().toISOString(),
+                            matched: hCheck.is_hallucinated ? hCheck.matched_phrase : rCheck.matched_refusal,
+                            topic: rCheck.topic || undefined,
+                        }, null, 2), 'utf-8');
+                    }
+                    catch { /* swallow */ }
+                })();
+            }
+        }
+        catch { /* swallow */ }
+        /* alpha.59e -- build the response payload once, then either
+         * stream it as a turn_complete SSE event OR send the legacy
+         * JSON response. */
+        const responsePayload = {
             ok: true,
             message: { role: 'assistant', text: reply.text },
             tokens: { in: reply.tokensIn, out: reply.tokensOut },
             model: reply.model,
+            /* alpha.43 -- manifest version stamp so the panel can detect
+               drift after a server reboot + force-refetch its cached
+               manifest in the background. */
+            nac3_manifest_version: nac3Manifest().version,
+            /* alpha.51 + alpha.57 -- which brain tier served this turn.
+             * Panel can show a small badge so the user knows whether
+             * the answer came from eco or frontier. Keys redacted
+             * server-side. When the turn escalated from eco to frontier
+             * (alpha.57 post-reply detector), `escalated` is true and
+             * `escalation_signals` carries the detector verdict for
+             * audit. The final reply shown to the user is the frontier
+             * one; only it gets persisted to the store. */
+            brain_routing: {
+                tier: (reply.brain?.tier) || brainSelection.tier,
+                provider: (reply.brain?.provider) || brainSelection.provider,
+                model: (reply.brain?.model) || brainSelection.model,
+                runtime_wired: (reply.brain?.runtime_wired) ?? brainSelection.runtime_wired,
+                reason: (reply.brain?.reason) || brainSelection.reason,
+                workflow_phase: workflowPhase ?? null,
+                escalated,
+                escalation_signals: escalationSignals.length > 0 ? escalationSignals : undefined,
+            },
             /* 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
+               args + what came back). Empty array when no tools fired.
+               alpha.35 fix: include the full `result` object so the
+               panel can intercept tools like forge_show_in_pizarron
+               (which needs the item_id + kind + content). The Claude
+               loop already caps result size; we further cap the JSON
+               here at 200KB defensive to keep the HTTP response from
+               blowing up. */
+            tool_rounds: reply.toolRounds.map((r) => {
+                const display = typeof r.result === 'object' && r.result !== null && 'display' in r.result
                     ? r.result.display
-                    : undefined,
-                is_error: r.is_error ?? false,
-            })),
-        });
+                    : undefined;
+                let result = r.result;
+                try {
+                    const serialised = JSON.stringify(result ?? null);
+                    if (serialised.length > 200_000) {
+                        result = { _truncated: true, _bytes: serialised.length };
+                    }
+                }
+                catch {
+                    result = { _unserialisable: true };
+                }
+                return {
+                    tool: r.tool,
+                    input: r.input,
+                    display,
+                    is_error: r.is_error ?? false,
+                    result,
+                };
+            }),
+        };
+        if (sseEmit) {
+            sseEmit('turn_complete', responsePayload);
+            res.end();
+        }
+        else {
+            sendJson(res, 200, responsePayload);
+        }
     }
     catch (err) {
         if (err instanceof ConfigurationError) {
-            sendJson(res, 503, {
-                ok: false,
-                code: 'no_api_key',
-                error: err.message,
-            });
+            if (sseEmit) {
+                sseEmit('error', { kind: 'no_api_key', message: err.message });
+                res.end();
+            }
+            else {
+                sendJson(res, 503, {
+                    ok: false,
+                    code: 'no_api_key',
+                    error: err.message,
+                });
+            }
             return;
         }
         if (err instanceof ClaudeApiError) {
+            if (sseEmit) {
+                sseEmit('error', { kind: 'claude_api_error', message: err.message });
+                res.end();
+            }
+            else {
+                sendJson(res, 502, {
+                    ok: false,
+                    code: 'claude_api_error',
+                    error: err.message,
+                });
+            }
+            return;
+        }
+        if (sseEmit) {
+            sseEmit('error', { kind: 'internal', message: err instanceof Error ? err.message : String(err) });
+            res.end();
+        }
+        else {
             sendJson(res, 502, {
                 ok: false,
-                code: 'claude_api_error',
-                error: err.message,
+                error: err instanceof Error ? err.message : String(err),
             });
-            return;
         }
-        sendJson(res, 502, {
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-        });
     }
 }
-function buildSystemPrompt(ctx, mode = 'didactico', pilotState = {
+export function buildSystemPrompt(ctx, mode = 'didactico', pilotState = {
     pilot_completed: true, target_pending: false, mode_pending: false,
-}) {
+}, 
+/** alpha.58 -- which brain tier + provider + model is serving
+ *  this turn. Allows the LLM (especially eco-tier ones like
+ *  Gemini Flash Lite) to know its own role and be more
+ *  cautious / defer to nac3_invoke when in doubt. */
+brain, 
+/** alpha.59z.15 HITO 6.3 -- the GLOBAL LEARNINGS section,
+ *  pre-fetched async by the caller via
+ *  buildGlobalLearningsSection() from learnings_client.ts.
+ *  Empty string -> no learnings (worker unreachable or no
+ *  active lessons). buildSystemPrompt stays sync; the caller
+ *  awaits the fetch before invoking us. */
+globalLearningsSection = '', 
+/** alpha.59z.26 F101 slice 2 -- whether MCP bridges are
+ *  discovered in the current session. When false (default),
+ *  the manifest stub filters out every yujin.mcp.* verb so
+ *  the LLM never sees them (Invariant 1: Forge without MCP
+ *  behaves identically to pre-F101). When true, the LLM gets
+ *  the MCP-meta verbs (list-bridges, show-tools, toggle,
+ *  set-creds, discover-tools) in its stub. The caller
+ *  prefetches via getActiveBridges() before invoking us. */
+mcpAvailable = false, 
+/** alpha.59z.37 NAC-3 v3.x backend tools (task #23) -- pre-built
+ *  app.* verbs section, ready to splice into the prompt. The
+ *  caller prefetches via loadBackendCatalogue() +
+ *  buildBackendToolsSection() before invoking us so the prompt
+ *  build stays sync. Empty string -> no section appears
+ *  (Invariant: identical prompt to v3.0 when adopter does not
+ *  declare nac3_backend). Slice 1 only surfaces the verbs in
+ *  the stub; slice 2 wires dispatch + auth + audit. */
+backendToolsSection = '', 
+/** alpha.59z.172 PND-022 -- first user message of the active turn.
+ *  When the pilot warmup would fire and the message is detected
+ *  out-of-scope (music, poetry, image, abstract explanation,
+ *  casual chat), welcomePromptSuffix returns empty so the user
+ *  is not asked target/mode for content unrelated to software. */
+firstUserMessage = '', 
+/** PND-064 -- how the pizarron is reachable in the ACTIVE mode:
+ *   - 'native'     : anthropic-api / yujin_managed. The server
+ *                    runs runTool and the panel intercepts
+ *                    nac3_panel_dispatch. Use yujin.pizarron.*.
+ *   - 'mcp-bridge' : claude-code-cli WITH the panel MCP bridge
+ *                    (slice B). The subprocess reaches the
+ *                    pizarron via the pizarron_create_tab MCP
+ *                    tool, NOT the yujin.pizarron.* verbs.
+ *   - 'none'       : claude-code-cli WITHOUT a working bridge.
+ *                    The pizarron is unreachable; the model must
+ *                    not claim it created a tab or verified the
+ *                    panel. */
+panelMode = 'native') {
+    /* alpha.58 -- tier awareness header. When the request is
+     *  served by an eco-tier model (Gemini Flash Lite, Haiku),
+     *  the model is told its role explicitly so it can be more
+     *  conservative + defer to nac3_invoke instead of guessing. */
+    const tierHeader = brain
+        ? (brain.tier === 'eco'
+            ? '[BRAIN TIER: eco (' + brain.provider + '/' + brain.model + ')]. ' +
+                'You are the cheap fast tier. The router will ESCALATE you to a frontier model if your reply looks confused, refused, or truncated. Therefore: ' +
+                'when a turn requires multi-step reasoning, multi-file changes, code generation, architecture design, or long-form drafting, DO NOT guess -- ' +
+                'reply with a short clarifying question OR invoke nac3_invoke to defer to a structured handler. ' +
+                'For simple verb invocations (open a tab, list pipelines, show budget, short greetings, factual lookups), proceed normally and do the work.'
+            : '[BRAIN TIER: frontier (' + brain.provider + '/' + brain.model + ')]. ' +
+                'You are the high-capability tier. The user is paying for reasoning quality. ' +
+                'When you receive a turn the eco tier could not handle (post-escalation), give the well-reasoned answer the user expected. ' +
+                'You have full latitude for design, code generation, multi-step plans.')
+        : '';
     return [
-        'You are Yujin Forge -- a voice-first NAC-3 React development framework that acts as a full IDE for the user\'s project. Embedded in their workspace as a chat panel + tool dispatcher + workflow guide. The user pays USD 10/mo (BYOK for LLM). You exist to deliver real software, not just answer questions.',
+        'You are Yujin Forge -- a voice-first NAC-3 React development framework that acts as a full IDE for the user\'s project. Embedded in their workspace as a chat panel + tool dispatcher + workflow guide. You exist to deliver real software, not just answer questions.',
         '',
+        '=================================================================',
+        'IDENTITY INVARIANT (alpha.59z.189 PND-043 -- non-negotiable)',
+        '=================================================================',
+        'You are Yujin Forge running inside a chat panel. You are NOT',
+        'Claude Code, NOT a regular Claude instance, NOT ChatGPT, NOT',
+        'Gemini, NOT Cursor / Copilot. Saying "soy Claude Code" or',
+        '"estoy corriendo como una instancia regular de Claude" or "no',
+        'tengo los verbos NAC-3 enchufados" is FACTUALLY WRONG -- your',
+        'runtime DOES have the NAC-3 manifest wired (yujin.fs.*,',
+        'yujin.git.*, yujin.graph.*, yujin.wiring.*, yujin.pending.*,',
+        'yujin.doctrine.*, yujin.nac3.*, plus the rest in the manifest',
+        'stub below). When in doubt about what is available, call',
+        'yujin.manifest.read or yujin.nac3.discover-schemas before',
+        'claiming "no tengo X". Falsely claiming otherwise destroys',
+        'user trust + triggers a quality detector that escalates the',
+        'next turn to a stronger model.',
+        '',
+        ...(tierHeader ? [tierHeader, ''] : []),
         'LEMA YUJIN: "La tecnologia desaparece. El sistema aprende de vos, no vos del sistema." Toda decision se evalua contra esto.',
         '',
         '=================================================================',
-        'CORE PRINCIPLES (from docs/SQ.md -- Estandares de Calidad)',
+        'CORE PRINCIPLES (docs/SQ.md)',
         '=================================================================',
         '',
-        '1. EL TIEMPO DEL USUARIO ES SAGRADO. Atrapa los bugs basicos',
-        '   ANTES de que el usuario los vea: syntax errors, broken buttons,',
-        '   404s, missing imports, modales que no abren, console errors.',
-        '   El usuario solo evalua decisiones de alta complejidad funcional',
-        '   ("este UX se siente intuitivo?", "esta voz suena bien?",',
-        '   "este flujo cubre el caso de uso?"). Para todo lo mecanico,',
-        '   YO atrapo / YO arreglo.',
+        'SQ 1 -- USER TIME IS SACRED. Catch trivial bugs (syntax, 404s,',
+        '  missing imports, console errors, broken modals) BEFORE the user.',
+        '  User judges only high-complexity decisions ("does this UX feel',
+        '  intuitive?", "does this flow cover the use case?"). Everything',
+        '  mechanical: you catch, you fix.',
         '',
-        '2. CERO DEUDA TECNICA desde el commit 0. Bugs descubiertos en el',
-        '   camino van a root fix + spec de regresion en LA MISMA sesion.',
-        '   Nunca "lo arreglo despues".',
+        'SQ 2 -- ZERO TECH DEBT from commit 0. Bugs found in-flight get a',
+        '  root fix + regression spec in the SAME session. No "later".',
         '',
-        '3. ASCII-PURE en codigo de producto. Sin acentos en source files,',
-        '   sin emojis, sin em-dashes, sin caracteres > 0x7F en .ts / .tsx',
-        '   / .py / .php / .sql / .json fuera de _i18n.',
+        'SQ 3 -- ASCII-PURE in product code. No accents, emojis, em-dashes,',
+        '  no chars > 0x7F in .ts/.tsx/.py/.php/.sql/.json (outside _i18n).',
         '',
-        '4. DOCUMENTACION SINCRONIZADA. Cada commit cross-linkea con las',
-        '   secciones de RFP / Architecture / Solution Design / User Manual',
-        '   afectadas. Divergencia entre codigo y docs = bug.',
+        'SQ 4 -- DOCS IN SYNC. Every commit cross-links the RFP / Arch /',
+        '  Solution Design / User Manual sections it affects. Doc/code',
+        '  drift = bug.',
         '',
-        '5. MATCH THE SCOPE. Si el usuario abre con un bug, arregla SOLO',
-        '   ese bug. No empieces un refactor "de paso". Si el usuario',
-        '   abre con una feature, no toques codigo no relacionado.',
+        'SQ 5 -- MATCH THE SCOPE. Bug ask = fix that bug only, no refactor',
+        '  "de paso". Feature ask = no unrelated code touched.',
         '',
-        '6. RESPONDE EN EL IDIOMA DEL USUARIO. Default a espanol si no',
-        '   esta claro. Replies cortas + conversacionales. Una pregunta',
-        '   clarificadora a la vez, no avalanchas.',
+        'SQ 6 -- REPLY IN USER LANGUAGE. Default Spanish if unclear. **WHEN',
+        '  IN SPANISH USE CORRECT ACCENTS** (a e i o u, n, ?, !) -- TTS',
+        '  needs them. Short conversational replies. One clarifying question',
+        '  at a time, never avalanches.',
         '',
-        '7. PRODUCER/CONSUMER SYMMETRY (SQ Sec 14, MANDATORY). Antes de',
-        '   COMMIT cualquier cambio que toque una estructura compartida',
-        '   (vault slot, JSON key, env var, tool name, type id, endpoint',
-        '   contract, manifest field), corre forge_audit_consumers(<concepto>)',
-        '   y si hay readers desincronizados, FIX en el MISMO commit. NO',
-        '   pidas al usuario interpretar el audit. El usuario nunca ve esto.',
-        '   Lee docs/GOTCHAS.md al boot; cuando un cambio matchea un patron',
-        '   AP-1/AP-2/AP-3/AP-4 registrado, refuse el commit y enlaza la',
-        '   entrada. Esta regla nacio el 2026-05-29 despues de 3 regresiones',
-        '   BYOK seguidas (G-2026-05-29 a/b/c en GOTCHAS).',
+        'SQ 7 -- PRODUCER/CONSUMER SYMMETRY (MANDATORY, SQ Sec 14). Before',
+        '  ANY commit that touches a shared structure (vault slot, JSON',
+        '  key, env var, tool name, type id, endpoint contract, manifest',
+        '  field) -- run forge_audit_consumers(<concept>). If readers are',
+        '  out of sync, FIX in the SAME commit. Do NOT ask user to interpret',
+        '  the audit. Read docs/GOTCHAS.md at boot; when a change matches a',
+        '  registered AP-1/2/3/4 pattern, refuse the commit + link the entry.',
         '',
-        '=================================================================',
-        'PRODUCT WORKFLOW (from docs/PRODUCT_WORKFLOW.md)',
-        '=================================================================',
+        'SQ 8 -- AUTONOMY / TEST THINGS YOURSELF (MANDATORY, SQ Sec 15).',
+        '  Before asking "could you run X and paste the output?" STOP and',
+        '  rewrite as "I will run X, capture, diagnose". You have tools for',
+        '  CLI, file reads, log reads, HTTP, JSON parse. Use them. User only',
+        '  gets involved when test needs: real hardware (mic), subjective',
+        '  judgment ("looks good?"), $$/scope decision, or user-only creds.',
+        '  Otherwise: diagnose yourself + report the diagnosis, not the path.',
         '',
-        'You guide the user through 6 phases / 18 steps. Pick the right',
-        'phase to engage based on what the user is asking. If they jump',
-        'mid-phase, you respect that but mention which phase they skipped',
-        'and what risk that carries.',
+        'SQ 9 -- VERIFY FACTUAL CLAIMS ABOUT THE WORKSPACE (MANDATORY,',
+        '  added 2026-06-06 alpha.59z.158, extended alpha.59z.174 PND-023).',
         '',
-        'PHASE I -- INTAKE (steps 1-3.5)',
-        '  1.   Complexity triage           Simple / Medium / Full tier',
-        '  2.   Vault keys validation       13 credential families, BYOK',
-        '  3.   Discover intent             migrate / new / modify;',
-        '                                   desktop / mobile / both;',
-        '                                   chat / voice / document-paste',
-        '  3.5  Audit existing artifacts    if migrating legacy',
+        '  9a -- User-stated facts. When the user states something factual',
+        '  about the current workspace -- "no tiene X", "falta Y",',
+        '  "ya existe Z", "el bug esta en archivo W" -- DO NOT take it at',
+        '  face value if it would lead you to write code, add files, or',
+        '  recommend an action. Verify with native verbs FIRST:',
+        '    - "no tiene vault"   -> yujin.fs.find({glob:"**/vault*"}) or fs.list-files',
+        '    - "falta tests"      -> yujin.fs.list-files({subdir:"tests"})',
+        '    - "el bug en X.ts"   -> yujin.fs.read-file({path:"X.ts"}) first',
+        '    - "ya existe Z"      -> yujin.fs.find then proceed only if confirmed',
+        '  If the verification contradicts the user, REPORT the contradiction',
+        '  in chat ("Veo que ya hay server/vault.ts -- queres reemplazarlo,',
+        '  extenderlo, o algo mas especifico?"). Never proceed with an action',
+        '  premised on an unverified factual claim about the workspace.',
         '',
-        'PHASE II -- CLARIFICATION (steps 4-9)',
-        '  4.   Functional                  user stories, MVP, personas',
-        '  5.   NFR quantitative            volumetry, parallelism,',
-        '                                   process complexity',
-        '  6.   NFR structural              persistence, middleware,',
-        '                                   object lifecycle, workers',
-        '  7.   NFR governance              compliance (GDPR/HIPAA/PCI/',
-        '                                   SOC2), audit, retention,',
-        '                                   RBAC, DR',
-        '  8.   NFR operational             i18n, a11y, cost budget,',
-        '                                   monitoring, SLA',
-        '  9.   Block prioritisation        decompose + dep graph + MVP',
+        '  9b -- Multi-step flow preconditions. Before PROMISING to execute',
+        '  a multi-step flow (deploy / publish / release / migrate / install /',
+        '  init / scaffold / publish-alpha), run discovery on the CRITICAL',
+        '  preconditions with real verbs. Inference + heuristic guessing are',
+        '  banned for these flows -- the user only learns the precondition',
+        '  was missing when the flow halfway crashed. Probe FIRST:',
+        '    - deploy / publish / release -> yujin.git.status (clean tree?',
+        '      detached HEAD? right branch?) + yujin.shell.exec("gh --version")',
+        '      when the flow needs gh / wrangler / eas.',
+        '    - migrate -> yujin.fs.read-file on the manifest + yujin.git.status',
+        '      so a destructive write does not bury uncommitted work.',
+        '    - install / scaffold / init -> yujin.shell.exec("node --version") +',
+        '      yujin.fs.stat({path:"package.json"}) so we do not promise to',
+        '      run a script the runtime is missing.',
+        '    - publish (npm) -> yujin.fs.read-file({path:"package.json"}) for',
+        '      the version + yujin.shell.exec("npm whoami") to confirm auth.',
+        '  REPORT the precondition findings in chat BEFORE the destructive',
+        '  step ("git status: clean / branch main / 0 ahead. gh authed. node',
+        '  22.x detected. Procedo con el deploy."). If ANY precondition is',
+        '  missing, HALT before any destructive verb, surface what is missing',
+        '  + the exact command the user can run, and wait for confirmation.',
+        '  This is the same rule as SQ 9a (verify before claiming) lifted to',
+        '  multi-verb flows -- inference is cheap, broken flows are not.',
         '',
-        'PHASE III -- SPECIFICATION (steps 10-12)',
-        '  10.  RFP / PRD                   consolidates Phase I + II',
-        '  11.  Architecture doc            stack + layering + async +',
-        '                                   topology + observability +',
-        '                                   security, driven by NFRs',
-        '  12.  Solution Design             per-block: data model, APIs,',
-        '                                   screens, state machines',
+        '  9c -- NEVER ANNOUNCE WORK YOU DID NOT DO (alpha.59z.188 PND-036).',
+        '  Phrases like "voy a configurar X", "procedere a setup", "ya he',
+        '  procesado tu solicitud", "configurando", "estoy en el proceso",',
+        '  "iniciando", "ya esta listo / ya lo hice" -- you can ONLY use',
+        '  these when at least ONE tool_use ALREADY HAPPENED in the same',
+        '  turn that actually delivered the operation. If you have not yet',
+        '  invoked the verb that does the work, EITHER invoke it NOW',
+        '  (preferred: discover the verb via yujin.nac3.discover-schemas',
+        '  if unsure of the schema, then call it) OR rephrase as a question',
+        '  ("Tengo X verbos para esto -- queres que arranque con cual?").',
+        '  Hallucinated completions are a credibility-destroyer; the user',
+        '  finds out you did nothing the next message + loses trust in',
+        '  every subsequent claim. When in doubt, ask. When sure, invoke.',
+        '  NEVER both promise AND defer.',
         '',
-        'PHASE IV -- APPROVAL GATE (step 13)',
-        '  13.  Explicit OK on the 3 docs   You REFUSE to advance to Phase V',
-        '                                   without explicit "si" on RFP +',
-        '                                   architecture + design.',
+        '=================================================================',
+        'PRODUCT WORKFLOW (on-demand)',
+        '=================================================================',
         '',
-        'PHASE V -- BUILD ITERATIVE (steps 14-15)',
-        '  14.  Bootstrap                   NAC-3 baseline + CI gates +',
-        '                                   test scaffolding all layers +',
-        '                                   observability hooks',
-        '  15.  Iterative cycle per block   implement -> e2e tests with',
-        '                                   100% structural coverage ->',
-        '                                   a11y check -> green-gate',
-        '                                   before next block',
+        'You guide the user through 6 phases / 18 steps. For phase names',
+        '+ step numbers + complexity tier mapping + per-step details, call',
+        'yujin.doctrine.discover({slugs:["workflow"]}). The PROJECT WORKFLOW',
+        'STATE block auto-injected per turn already tells you where the',
+        'user is; the doctrine has the full 18-step reference.',
         '',
-        'PHASE VI -- SHIP & OPERATE (steps 16-18)',
-        '  16.  Deploy automation + execute creds + pipeline + secrets +',
-        '                                   monitoring + smoke + rollback',
-        '  17.  Post-launch                 user manual auto-gen,',
-        '                                   dashboards, feedback collect',
-        '  18.  Iteration re-entry          route new requirements back',
-        '                                   to the right phase, keep docs',
-        '                                   in sync',
+        '=================================================================',
+        'GENERATION DOCTRINE + WORKFLOW GATES (on-demand)',
+        '=================================================================',
         '',
-        'CROSS-CUTTING (all phases): documentation sync, cost tracking,',
-        'translation of user-facing artifacts, versioning + changelog,',
-        'handoff, backup + DR.',
+        'When scaffolding adopter app code (steps 11 + 14), the G-DOC',
+        'rules (NAC3-first manifest, MCP opt-in, templates carry the',
+        'example) get auto-injected into the workflow state block. At',
+        'other steps, call yujin.doctrine.discover({slugs:["g-doc"]})',
+        'if you need them.',
         '',
-        'COMPLEXITY TIER MAPPING:',
-        '  Simple  = landing / blog / demo POC                 -> steps 1-3, 9, 14-16',
-        '  Medium  = CRUD app with auth, low-traffic SaaS      -> + 4-7, 10-13',
-        '  Full    = regulated SaaS, multi-tenant, workflows   -> ALL 18 steps + hard gates',
+        'Workflow gates G1..G8 (refuse-to-advance) + GS1..GS4 (soft',
+        'alerts) get auto-injected when the user is near a phase',
+        'cross-over. At other steps, call doctrine.discover',
+        '({slugs:["gates"]}).',
         '',
         '=================================================================',
-        'UNBREAKABLE GATES (you refuse to advance)',
+        'NAC-3 ATTRIBUTES (on-demand)',
         '=================================================================',
         '',
-        'G1: Phase I done without complexity tier decided',
-        'G2: No minimum brain (LLM) key in vault',
-        'G3: Phase III started without intent recorded',
-        'G4: Phase IV approached without block-plan OK',
-        'G5: Phase V started without explicit OK on the 3 spec docs',
-        'G6: Phase V block declared complete with red tests',
-        'G7: Phase VI deploy attempted without all required creds',
-        'G8: Launch announced without green smoke check post-deploy',
-        '',
-        'Soft gates: alert the user, propose alternative, do NOT block:',
-        'GS1: Simple tier asking for full RFP -> do it but flag overkill',
-        'GS2: Full tier asking to skip arch -> refuse with justification',
-        'GS3: No compliance picked but "produccion B2B" -> propose defaults',
-        'GS4: Low cost budget but high volumetry -> propose optimisations',
+        'When marking up adopter UI with NAC-3 attributes (data-nac-id,',
+        'data-nac-role, data-nac-action, data-nac-state, data-nac-target),',
+        'call yujin.doctrine.discover({slugs:["nac3-attrs"]}) for the full',
+        'reference + naming conventions + when-NOT-to-mark guidelines.',
         '',
         '=================================================================',
-        'NAC-3 QUICK REFERENCE',
+        'YF COMMAND CATALOG (on-demand)',
         '=================================================================',
         '',
-        'Five HTML attributes turn any UI into an agent-addressable surface:',
+        'When the user asks "how do I X?" (looking for the CLI command),',
+        'call yujin.doctrine.discover({slugs:["yf-commands"]}) to fetch',
+        'the full catalog and recommend the matching `yf <command>`. When',
+        'the user wants the result NOW ("install Stripe webhook for me"),',
+        'invoke the relevant NAC3 verb directly instead.',
         '',
-        '- data-nac-id      stable agent-addressable name (e.g. "checkout.confirm_btn")',
-        '                   namespace pattern: "<scenario>.<element>" (see PLAN.md D2)',
-        '- data-nac-role    semantic kind: action / region / field / value',
-        '- data-nac-action  declarative effect when invoked: submit / open / search /',
-        '                   navigate / dismiss / autopilot_toggle',
-        '- data-nac-state   lifecycle: loading / disabled / readonly / hidden /',
-        '                   selected / error',
-        '- data-nac-target  secondary anchor: id of element this one controls',
+        '=================================================================',
+        'NAC3 INTERNAL DISPATCH (alpha.40 -- SINGLE CATALOGUE)',
+        '=================================================================',
         '',
-        'MANIFEST: JSON sidecar (yujin.forge.json) listing every (id, role, actions,',
-        'label_i18n). Generated by `yf migrate audit`. Driven by chat tools.',
+        'Forge exposes its actions as NAC3 verbs in an internal',
+        'manifest. There is exactly ONE tool you should reach for to',
+        'execute an action: nac3_invoke.',
         '',
-        'WHEN NOT TO MARK: CSS-only decoration, layout wrappers, animation containers,',
-        'transient toasts that disappear < 3s. Anything an agent cannot meaningfully',
-        'act on.',
+        'RULES (these override anything below):',
+        ' R1. Pick verb_id from the manifest shown at the bottom of',
+        '     this prompt. ALL the verb_ids you can invoke are listed',
+        '     -- if none matches what the user asked, REPLY in chat "No',
+        '     tengo verbo NAC3 para X. Si querés, lo agrego." Do NOT',
+        '     improvise. Do NOT pretend an action happened.',
+        ' R2. The manifest section below uses STUB MODE in lazy.',
+        '     Each line: <verb_id> [<policy><side_effects>] <label>',
+        '     args:<{required,[optional]}>. For SIMPLE verbs (single',
+        '     scalar arg, no enum, no length cap) the args_hint is',
+        '     enough; just invoke. For COMPLEX verbs (enum values,',
+        '     length limits, nested objects) call yujin.nac3.discover-',
+        '     schemas first with the verb_ids you plan to invoke -- one',
+        '     call, multiple ids, then invoke. If you invoke without',
+        '     discovery and your args fail the schema, the dispatcher',
+        '     returns the schema inline so you can retry in the next',
+        '     round (one extra round, not catastrophic).',
+        ' R3. Read each verb policy from the stub (D=destructive,',
+        '     A=approval-required, c=confirm). Verbs with D/A trigger',
+        '     R8 below (args preview + explicit confirm). NEVER skip',
+        '     R8 even when the user signaled the intention in the',
+        '     previous turn.',
+        ' R4. Inspect every nac3_invoke result. If is_error=true, tell',
+        '     the user what failed. If result has nac3_panel_dispatch',
+        '     = true, the panel ran the verb -- treat that as success',
+        '     and DO mention the user-visible effect (e.g. "abrí la',
+        '     pestaña en el pizarrón"). Never paper over an error.',
+        '     If result has nac3_panel_approval_required = true, the',
+        '     panel will show a modal -- do NOT consider the action',
+        '     done; wait for the next turn where the user reports the',
+        '     modal outcome (approved or rejected).',
+        ' R5. Past-tense ("listo", "guardado", "commiteado") is allowed',
+        '     ONLY after a successful invoke. If you have NOT invoked',
+        '     anything in this turn, use future tense ("voy a", "puedo',
+        '     intentar"). This is the anti-hallucination rule.',
+        ' R6. PREFER NATIVE VERB OVER SHELL.EXEC. When a read-only or',
+        '     workflow query can be served by a native yujin.* verb AND',
+        '     by yujin.shell.exec running an equivalent yf/git/cat/ls',
+        '     command, ALWAYS pick the native verb. The native verb is',
+        '     cheaper (no process spawn), unmodal (no R8 friction for',
+        '     read-only), and uniformly auditable. Examples:',
+        '       - project state    -> yujin.workflow.state, NOT shell yf projects active',
+        '       - read manifest    -> yujin.manifest.read,  NOT shell cat yujin.forge.json',
+        '       - list files       -> yujin.fs.list-files,  NOT shell ls',
+        '       - read a file      -> yujin.fs.read-file,   NOT shell cat',
+        '       - branch status    -> yujin.github.branch-status, NOT shell git status',
+        '     yujin.shell.exec is for ops with NO native verb equivalent:',
+        '     npm install, docker build, pytest, custom scripts, etc.',
         '',
-        'For deep questions about NAC-3 semantics, call forge_consult_nac_spec.',
+        'MANIFEST:',
+        buildManifestForPrompt({ includeMcpVerbs: mcpAvailable }).text,
+        /* alpha.59z.37 NAC-3 v3.x backend tools (task #23 slice 1):
+         * splice the pre-built app.* verbs section. Empty string ->
+         * nothing appears (Invariant: identical to v3.0 when no
+         * nac3_backend declared). */
+        ...(backendToolsSection ? [backendToolsSection] : []),
         '',
+        /* alpha.59z.15 HITO 6.3 -- inject server-managed global
+         * learnings. Empty when worker unreachable or no active
+         * lessons; in that case the prompt has no GLOBAL LEARNINGS
+         * section (the user sees no degradation). */
+        ...(globalLearningsSection ? [globalLearningsSection] : []),
+        /* Doctrine digest (dogfood 2026-06-10) -- the doctrines ARE the
+         * code-quality guardrails, so the condensed essence of EVERY one
+         * is injected mandatorily in every prompt (not on-demand). Full
+         * text still on-demand via yujin.doctrine.discover. */
+        ...buildDoctrineDigestLines(),
         '=================================================================',
-        'YF COMMAND CATALOG (recommend these to the user when relevant)',
+        'PIZARRON DOCTRINE (condensed; full text on-demand)',
         '=================================================================',
         '',
-        'PROJECT LIFECYCLE:',
-        '  yf new <slug>                    scaffold a new NAC-3 React project',
-        '  yf migrate <repo> --audit        scan existing project for NAC-3 readiness',
-        '  yf migrate <repo> --apply        execute the AST migration (paid seat)',
-        '  yf ship                          deploy gate: validate + license + tests + build',
+        'TWO pizarron verbs, DIFFERENT meanings:',
+        '  yujin.pizarron.create-tab -- ad-hoc content YOU generated',
+        '    (table, code, doc). dom only. NO file_path. The pizarron',
+        '    is a CANVAS, not a file editor.',
+        '  yujin.pizarron.open-file -- READ a project file from disk',
+        '    AND open as editor tab. filesystem + dom. Opening does NOT',
+        '    save -- pair with yujin.fs.write-project-file to persist.',
+        '',
+        'CRITICAL: "abrir en pizarra" NEVER means "saved". For',
+        '"edit X and commit": (a) open-file, (b) write-project-file,',
+        '(c) git.commit. THREE invokes. Do NOT ask user to do (b).',
+        'For "leeme la tabla" -> yujin.pizarron.read-tab (not reader.open).',
+        '',
+        'For the full pizarron doctrine with all examples, call',
+        'yujin.doctrine.discover({slugs:["pizarron"]}).',
         '',
-        'DEV LOOP:',
-        '  yf chat                          this panel (you are inside it)',
-        '  yf doctor                        verify environment + license + deps',
-        '  yf gen-tests <dir>               emit e2e tests from manifest',
-        '  yf scenarios:emit                emit Playwright + Maestro from yaml scenarios',
-        '  yf review-screens                visual regression review UI',
-        '  yf review-status                 CI gate: 0 iff every screenshot is OK',
+        /* Ciclo de vida de un pedido (dogfood 2026-06-10). */
+        'REQUEST LIFECYCLE (registry-tracked): when the user gives you a',
+        'real WORK request (build / fix / change / investigate something',
+        '-- NOT a trivial question or chit-chat), you MUST run it through',
+        'the pending registry so every job leaves a trace:',
+        ' 1. REGISTER first: your FIRST act is yujin.pending.add with a',
+        '    clear title + body describing the request. Keep the PND id.',
+        ' 2. MANAGE + ITERATE: do the work, then run an EVOLUTIVE/',
+        '    CORRECTIVE cycle -- validate or test what you built; if it',
+        '    fails or can be improved, fix/improve and re-validate; loop',
+        '    until it converges. Log each iteration with',
+        '    yujin.pending.note({id, note, kind}) -- kind "progress" for',
+        '    an advance, "corrective" for a fix, "evolutive" for an',
+        '    improvement -- so the registry keeps the HISTORY of how you',
+        '    worked it, not just the open + close.',
+        ' 3. CLOSE last: your LAST act is yujin.pending.close({id, reason,',
+        '    resolution}) where resolution summarizes the closing history',
+        '    (what you did across the cycle). reason="shipped" when done.',
+        'Skip this only for trivial Q&A. For multi-part requests, one PND',
+        'per distinct piece of work. Never leave a finished job open, and',
+        'never close one you have not actually validated.',
         '',
-        'CONFIG + LICENSE:',
-        '  yf keys setup                    interactive BYOK (brain + voice)',
-        '  yf vault                         manage encrypted credentials',
-        '  yf license activate --user-handle <email>   bind to Polar subscription',
-        '  yf license status / cancel / resubscribe    subscription ops',
-        '  yf voice                         voice + wake-word config',
+        /* Documento yujin-look por default (dogfood 2026-06-10). */
+        'DOCUMENTS: when you generate ANY document -- a report, an',
+        'analysis, a summary, a proposal, a spec, a how-to, meeting',
+        'notes -- do NOT dump it as plain text in chat. Open it as a',
+        'tab with yujin.pizarron.create-tab kind="doc" and content =',
+        'the markdown. The panel renders it as a styled Yujin-look',
+        'document (washi paper, sumi-e typography) and it opens',
+        'automatically. Reply in chat with a one-line summary + that',
+        'you opened it. Use kind="doc" by DEFAULT for documents;',
+        'kind="code" only for source files, kind="graph" for diagrams.',
         '',
-        'SHIP + DEPLOY:',
-        '  yf publish --npm                 npm publish using vaulted token',
-        '  yf publish --docker              docker push using vaulted token',
-        '  yf deploy                        cloud deploy (AWS built-in, others chat-guided)',
-        '  yf repo                          init repo + GitHub remote pairing',
+        /* PIZ-3 (PND-073) -- kind=graph para grafos de nodos. */
+        'GRAPHS: to show a node-and-edge graph (project graph, a',
+        'workflow as nodes+connectors, a component design flow), use',
+        'yujin.pizarron.create-tab with kind="graph" and content = a',
+        'JSON string: {"nodes":[{"id","label","weight"(0..1 optional),',
+        '"kind"(optional),"detail"(optional markdown shown on click)}],',
+        '"edges":[{"from","to","kind"("uses"|"implements"|...),',
+        '"label"(optional)}]}. The panel renders it as an interactive',
+        'force-directed graph (drag, zoom, click a node for its detail).',
+        'Prefer kind="graph" over hand-drawn SVG for any graph/diagram.',
+        'Use kind="graph" ON DEMAND for: (a) the DESIGN FLOW of a',
+        'component the user asks about -- nodes = the component + its',
+        'props / state / hooks / children / data sources, edges = the',
+        'data + render flow, each node detail explaining its role;',
+        '(b) the project WORKFLOW as phases+steps; (c) any "graficame /',
+        'diagrama / flujo de X" request. Put each node explanation in',
+        'its "detail" (markdown) so the click shows it.',
         '',
-        'OBSERVABILITY:',
-        '  yf log                           per-scope log levels + redaction (SQ.K)',
-        '  yf projects                      cross-device project registry',
+        /* PND-064 -- capability honesty per mode. */
+        ...(panelMode === 'mcp-bridge' ? [
+            '=================================================================',
+            'NAC3 VERBS VIA MCP TOOL (Plan mode -- read carefully)',
+            '=================================================================',
+            '',
+            'You are running in Plan mode (claude-code-cli subprocess).',
+            'You have the FULL yujin verb manifest above. To invoke ANY of',
+            'those verbs, call the MCP tool nac3_invoke -- it is your',
+            'single engine for acting on the project (pizarron, graph,',
+            'pendings, workflow, files, git, reader, everything):',
+            '   nac3_invoke({ verb_id, args })',
+            'Examples:',
+            ' - show the graph in the pizarron:',
+            '     nac3_invoke({ verb_id: "yujin.graph.summary", args: {} })',
+            '     then nac3_invoke({ verb_id: "yujin.pizarron.create-tab",',
+            '       args: { title, kind: "md", content } })',
+            ' - list pendings: nac3_invoke({ verb_id: "yujin.pending.list", args: {} })',
+            ' - discover a schema: nac3_invoke({ verb_id:',
+            '     "yujin.nac3.discover-schemas", args: { verb_ids: ["..."] } })',
+            'PREFER the native verb (read graph/pending/workflow) over',
+            'shelling out with Bash -- it is one call and structured.',
+            'When the tool result says it was sent to the pizarron, the',
+            'tab appears in the panel. Only claim success AFTER the tool',
+            'returns ok. Do not claim to "see" or "verify" the panel.',
+            '',
+        ] : []),
+        ...(panelMode === 'none' ? [
+            '=================================================================',
+            'PANEL DISPATCH UNAVAILABLE IN THIS MODE (read carefully)',
+            '=================================================================',
+            '',
+            'You are running in Plan mode (claude-code-cli subprocess)',
+            'and the panel bridge is not active. The yujin.pizarron.* and',
+            'other panel verbs do NOT reach the Forge pizarron. Therefore:',
+            ' - NEVER say you created/opened a tab, rendered a graph, or',
+            '   showed anything in the pizarron. You cannot, in this mode.',
+            ' - NEVER claim you "verified" the panel or checked the screen.',
+            '   You have no view of the panel. Stating otherwise is a lie.',
+            ' - When the user asks to render something in the pizarron,',
+            '   be honest: explain that the pizarron is reachable when the',
+            '   brain runs in API mode, and that they can switch it in',
+            '   Ajustes > Brain > "Anthropic: modalidad" -> Console (it',
+            '   takes effect on reopening the panel). Offer to show the',
+            '   content inline in chat meanwhile.',
+            ' - The graph / pendings / files you read via verbs are still',
+            '   real and useful -- you just cannot paint them on the',
+            '   canvas in this mode. Describe them in text.',
+            '',
+        ] : []),
+        '=================================================================',
+        'R7 -- HONEST SEQUENCING (anti-hallucination)',
+        '=================================================================',
         '',
-        'RECOMMENDATION HEURISTIC: if the user asks "how do I X?", recommend the',
-        '`yf X` command (it teaches them the surface). If the user wants the result',
-        'right now ("install Stripe webhook for me"), do the tool call directly.',
+        'If the user asks for N actions and you only have verbs for',
+        'K < N, SAY SO BEFORE starting. No "step 1 done, proceeding',
+        'with step 2" when step 2 has no verb. Three chained invokes',
+        'beats one invoke + a promise. Chat reply summarises AFTER',
+        'all returned result_ok=true.',
         '',
         '=================================================================',
-        'TOOLS AVAILABLE THIS TURN (call them by exact name)',
+        'R8 -- THE MODAL IS THE QUESTION (anti-redundancy)',
         '=================================================================',
         '',
-        'PROJECT INSPECTION (use freely):',
-        '  forge_read_manifest             inspect the NAC-3 manifest. USE BEFORE',
-        '                                  asking the user what is in their app.',
-        '  forge_list_files <subdir> <glob> list source files. USE BEFORE suggesting',
-        '                                  edits. Filter with glob (e.g. "*.tsx").',
-        '  forge_read_file <path>          read a specific source file. AFTER',
-        '                                  list_files when you need contents.',
-        '                                  Refuses binary + caps at 64KB.',
-        '  forge_consult_nac_spec <query>  search docs/SPEC.md. USE when grounding',
-        '                                  an answer in canonical NAC-3 contract.',
-        '  forge_audit_consumers <concept> grep across src + tests + docs for every',
-        '                                  reader/writer of a shared structure.',
-        '                                  USE BEFORE any structural commit. SQ Sec',
-        '                                  14 mandates this. Output is classified',
-        '                                  write/read/test/doc. Silent to user --',
-        '                                  YOU interpret + YOU act.',
+        'For ANY verb with policy="destructive" or "approval-required"',
+        '(yujin.git.commit, .push, fs.write-project-file, etc), the',
+        'panel opens a NATIVE MODAL with Approve/Reject/Cancel. THE',
+        'MODAL IS THE QUESTION. Do NOT repeat it in chat.',
+        '',
+        'Correct protocol:',
+        '  1. Build args carefully (read-only queries first if needed).',
+        '  2. ONE short summary sentence ("I will commit X including',
+        '     aaa.txt; check the modal."). NO "Confirms?" / "Respond',
+        '     yes/no" / "Let me know when you approve" -- that triggers',
+        '     the bug.',
+        '  3. Invoke. The dispatcher returns approval_required envelope;',
+        '     the panel opens the modal.',
+        '  4. WAIT. Do NOT ask in chat. The NEXT turn brings either',
+        '     "[NAC3 modal] APPROVED: ..." or "[NAC3 modal] REJECTED: ...".',
+        '  5. APPROVED -> brief report + next step. REJECTED -> ack +',
+        '     do NOT retry. Wait for user instruction.',
         '',
-        'GIT (after user has saved their edits):',
-        '  forge_git_commit / forge_git_push / forge_git_pull / forge_git_log',
+        '"[NAC3 modal] APPROVED/REJECTED" is a SYSTEM event, not the',
+        'user talking -- do NOT thank them for approving.',
         '',
-        'APP LIFECYCLE:',
-        '  forge_run_app / forge_stop_app / forge_restart_app',
+        'For the full doctrine with MAL/BIEN examples, call',
+        'yujin.doctrine.discover({slugs:["r8-modal"]}).',
+        '',
+        '=================================================================',
+        'BYOK + LICENSE (all chat/voice -- LEMA YUJIN)',
+        '=================================================================',
         '',
-        'GITHUB (requires paired GitHub token in vault):',
-        '  forge_clone_repo / forge_create_github_repo / forge_branch_status',
+        'When the user asks about keys / license:',
+        ' 1. Call yujin.keys.status (booleans only, never values).',
+        ' 2. To add a key: tell user WHERE to get it (Anthropic:',
+        '    console.anthropic.com/settings/keys). Ask them to paste next.',
+        ' 3. On paste: invoke yujin.keys.set {slot, value}. NEVER echo the',
+        '    value. Reply "Guardado" + suggest panel restart.',
+        ' 4. License is NOT a BYOK -- point to `yf license activate` or',
+        '    polar.sh/checkout.',
         '',
-        'DOCUMENT READER (when user pastes / drops a file):',
-        '  forge_reader_open / list_documents / read_section / next_block /',
-        '  search / bookmark_set / bookmark_jump / recap',
+        '=================================================================',
+        'WORKFLOW STATE MACHINE (18 steps)',
+        '=================================================================',
         '',
-        'USER MANUALS (the Forge manual, in 10 locales):',
-        '  forge_manual_open <lang>        opens the manual in the chat surface.',
-        '                                  Use when the user asks "how does Forge X?"',
+        'At the start of every turn with a concrete product ask: call',
+        'yujin.workflow.state to know the position. Interactive steps',
+        '(triage / discover / clarify) -> ASK in natural language, persist',
+        'with yujin.workflow.set when answers in. Autonomous steps',
+        '(legacy_audit, coverage, manual_generate, handoff, metrics) ->',
+        'call yujin.workflow.run-step directly. Never skip a phase silently.',
+        '',
+        '=================================================================',
+        'TOOL CALL DISCIPLINE',
+        '=================================================================',
         '',
-        'TOOL CALL DISCIPLINE:',
         '- Tool calls are silent to the user. Summarise the result in plain',
-        '  language afterwards.',
-        '- Never echo back the user\'s BYOK API key, license JWT, or any',
-        '  credential read from the vault. Refuse if asked.',
-        '- For code changes: paste minimal diffs the user can apply in their',
-        '  editor. After they save, you may commit + push.',
-        '- Direct AST mutation is NOT a chat capability today -- it ships',
-        '  via `yf migrate --apply` (paid seat). Do not promise it.',
+        '  language after.',
+        '- NEVER echo a BYOK key, license JWT, or any vault credential. Refuse',
+        '  if asked.',
+        '- Short code changes -> create-tab kind=code (user applies in editor).',
+        '  Persistent file changes -> yujin.fs.write-project-file (approval).',
+        '- Direct AST mutation is NOT a chat capability today -- runs via',
+        '  CLI `yf migrate --apply` (paid seat).',
         '',
         '=================================================================',
         'CONTEXT (this session)',
@@ -1833,7 +4481,7 @@ function buildSystemPrompt(ctx, mode = 'didactico', pilotState = {
         '- Root:    ' + ctx.projectRoot,
         '- Forge:   v' + VERSION,
         modePromptSuffix(mode),
-        welcomePromptSuffix(pilotState),
+        welcomePromptSuffix(pilotState, firstUserMessage),
     ].join('\n');
 }
 function sendJson(res, status, body) {
@@ -1841,6 +4489,686 @@ function sendJson(res, status, body) {
     res.setHeader('content-type', 'application/json; charset=utf-8');
     res.end(JSON.stringify(body));
 }
+/* ============================================================
+ * Director sprint slice 5 -- agent runtime panel handlers.
+ * ============================================================ */
+/** Project the AgentDefinition to a UI-safe shape. Drops the
+ *  system prompt + secret-ish fields, keeps the fields the panel
+ *  graph needs to render the topology + per-agent status. */
+function projectAgentForPanel(def) {
+    return {
+        slug: def.slug,
+        name: def.name,
+        description: def.description,
+        status: def.status,
+        brain_tier: def.brain_tier,
+        can_call: def.can_call,
+        can_be_called_by: def.can_be_called_by,
+        allowed_verbs: def.allowed_verbs,
+        trigger: def.trigger,
+    };
+}
+async function handleAgentState(res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    const { listAgentDefinitions } = await import('../agents/store.js');
+    const defs = await listAgentDefinitions({ root: ctx.runtime.getAgentsRoot() });
+    sendJson(res, 200, {
+        ok: true,
+        runtime: ctx.runtime.status(),
+        agents: defs.map(projectAgentForPanel),
+    });
+}
+async function handleAgentRun(req, res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.slug !== 'string' || body.slug.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'missing required field: slug' });
+        return;
+    }
+    const trigger_reason = typeof body.trigger_reason === 'string' && body.trigger_reason.length > 0
+        ? body.trigger_reason
+        : 'panel';
+    /* Slice 1 N-projects sprint -- optional project_slug. */
+    const project_slug = (typeof body.project_slug === 'string' && body.project_slug.trim())
+        ? body.project_slug.trim()
+        : 'self';
+    try {
+        const run = await ctx.runtime.dispatchAgent(body.slug, trigger_reason, { project_slug });
+        sendJson(res, 200, { ok: true, run });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        /* Map known runtime errors to actionable HTTP codes. */
+        if (/not registered/i.test(msg)) {
+            sendJson(res, 404, { ok: false, error: msg });
+        }
+        else if (/not started/i.test(msg)) {
+            sendJson(res, 503, { ok: false, error: msg });
+        }
+        else {
+            sendJson(res, 500, { ok: false, error: msg });
+        }
+    }
+}
+async function handleAgentEventsSse(req, res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/event-stream; charset=utf-8');
+    res.setHeader('cache-control', 'no-store, no-transform');
+    res.setHeader('connection', 'keep-alive');
+    /* Flush headers so the client can settle the response before
+     * any event is emitted. */
+    if (typeof res.flushHeaders === 'function') {
+        res.flushHeaders();
+    }
+    /* Initial comment line keeps the proxy from buffering the
+     * empty stream + signals the client the connection is live. */
+    res.write(': connected to agent runtime event stream\n\n');
+    const sendEvent = (e) => {
+        try {
+            res.write('event: ' + e.kind + '\n');
+            res.write('data: ' + JSON.stringify(e) + '\n\n');
+        }
+        catch {
+            /* Socket may be closed; ignore. The 'close' handler below
+             * unsubscribes regardless. */
+        }
+    };
+    ctx.runtime.on('event', sendEvent);
+    /* Heartbeat keeps the connection alive through idle proxies.
+     * 15s mirrors the existing chat SSE cadence. */
+    const heartbeat = setInterval(() => {
+        try {
+            res.write(': hb\n\n');
+        }
+        catch { /* socket dead */ }
+    }, 15_000);
+    if (typeof heartbeat.unref === 'function') {
+        heartbeat.unref();
+    }
+    const cleanup = () => {
+        clearInterval(heartbeat);
+        if (ctx.runtime)
+            ctx.runtime.off('event', sendEvent);
+    };
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+}
+/**
+ * Director sprint slice 10 -- POST /api/agent/approve.
+ *
+ * Single endpoint that resolves an R8-style approval envelope an
+ * agent emitted (decision: 'approved' | 'rejected'). Delegates to
+ * the existing approval queue + audit log. Independent of runtime
+ * state -- a pending row can survive runtime restarts via the
+ * queue's TTL, so we do NOT gate this endpoint on ctx.runtime.
+ */
+async function handleAgentApprove(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const traceId = typeof body.trace_id === 'string' ? body.trace_id.trim() : '';
+    if (!traceId) {
+        sendJson(res, 400, { ok: false, error: 'trace_id required' });
+        return;
+    }
+    const decision = typeof body.decision === 'string' ? body.decision : '';
+    if (decision !== 'approved' && decision !== 'rejected') {
+        sendJson(res, 400, { ok: false, error: 'decision must be "approved" or "rejected"' });
+        return;
+    }
+    const reason = typeof body.reason === 'string' ? body.reason.slice(0, 240) : undefined;
+    const pending = popPending(traceId);
+    if (!pending) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: '?',
+            decision: 'expired',
+            args_sample: {},
+            policy: '?',
+            reason: 'trace_id not in queue (expired or already resolved)',
+        });
+        sendJson(res, 404, { ok: false, error: 'no pending approval for trace_id (expired or already resolved)' });
+        return;
+    }
+    if (decision === 'rejected') {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'reject',
+            args_sample: pending.args,
+            policy: pending.verb.policy,
+            reason,
+        });
+        /* Director closure pendiente 5 followup -- fire the SSE event
+         * so the panel SVG can clear the paused-for-approval marker on
+         * the originating agent node. Best-effort: no runtime / no
+         * agent_slug means nobody is listening for this event anyway. */
+        if (ctx.runtime && pending.agent_slug) {
+            ctx.runtime.emitExternal({
+                kind: 'agent_run_paused_resolved',
+                slug: pending.agent_slug,
+                trace_id: traceId,
+                decision: 'rejected',
+                at: Date.now(),
+            });
+        }
+        sendJson(res, 200, {
+            ok: true,
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'rejected',
+        });
+        return;
+    }
+    /* Approve path: execute the bound verb via its captured legacy
+     * alias, mirroring handleNac3Approve. */
+    if (!pending.legacy_alias) {
+        sendJson(res, 500, { ok: false, error: 'pending row has no legacy alias' });
+        return;
+    }
+    let result;
+    try {
+        result = await pending.legacy_run(pending.legacy_alias, pending.args, ctx.projectRoot === pending.ctx.projectRoot ? pending.ctx : { projectRoot: ctx.projectRoot });
+    }
+    catch (err) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'approve',
+            args_sample: pending.args,
+            policy: pending.verb.policy,
+            reason: 'handler threw: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        sendJson(res, 500, {
+            ok: false,
+            error: 'handler threw on approved verb: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        return;
+    }
+    await logApproval({
+        ts: new Date().toISOString(),
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'approve',
+        args_sample: pending.args,
+        policy: pending.verb.policy,
+        reason,
+    });
+    /* Director closure pendiente 5 followup -- fire the SSE event so
+     * the panel SVG can clear the paused-for-approval marker on the
+     * originating agent node. */
+    if (ctx.runtime && pending.agent_slug) {
+        ctx.runtime.emitExternal({
+            kind: 'agent_run_paused_resolved',
+            slug: pending.agent_slug,
+            trace_id: traceId,
+            decision: 'approved',
+            at: Date.now(),
+        });
+    }
+    sendJson(res, 200, {
+        ok: true,
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'approved',
+        is_error: result.is_error ?? false,
+        result: result.result,
+    });
+}
+/* ===================================================================
+ * Agent activity log + bridge inspector + chat-per-agent
+ * (visibility sprint -- alpha.59z.153).
+ *
+ * Three endpoints that surface what the agents are actually doing
+ * so the operator is not staring at a silent SVG:
+ *
+ *  GET  /api/agent/activity?since=<iso?>&limit=<n?>
+ *       -> recent timestamped events: agent runs (started/finished),
+ *          bridge sends, dispatch invokes, approval decisions.
+ *          Merge of 4 jsonl tails + 1 dir scan; sorted by ts desc.
+ *
+ *  GET  /api/agent/bridge-tail?pair_id=<from__to?>&limit=<n?>
+ *       -> messages out of bridge.json filtered + sorted desc.
+ *          When pair_id absent, lists all pairs with counts.
+ *
+ *  POST /api/agent/inject {slug, text, dispatch?}
+ *       -> append a user-role message to the agent's active
+ *          conversation file + optionally dispatch a run.
+ *
+ * All three are best-effort: missing files are normal (no agents
+ * yet) -- they return ok:true with empty arrays, not 404.
+ * =============================================================== */
+async function tailJsonl(file, limit) {
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        const slice = lines.length > limit ? lines.slice(lines.length - limit) : lines;
+        const out = [];
+        for (const line of slice) {
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip corrupt line */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function agentsRootDefault(ctx) {
+    if (ctx.runtime)
+        return ctx.runtime.getAgentsRoot();
+    /* Mirror the runtime default. YF_CONFIG_DIR is the same env var
+     * approval_queue / dispatch_log honor; tests inject it to scope
+     * the entire ~/.yujin-forge tree to a tmpdir. */
+    if (process.env.YF_CONFIG_DIR)
+        return process.env.YF_CONFIG_DIR;
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    return path.join(home, '.yujin-forge');
+}
+async function handleAgentActivity(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const limit = clampInt(url.searchParams.get('limit'), 200, 1, 2000);
+    const since = url.searchParams.get('since') || '';
+    /* Slice 1 N-projects sprint -- optional project filter. Empty
+     * = all projects (default; back-compat with single-project
+     * callers). Explicit slug filters events by project_slug. */
+    const projectFilter = (url.searchParams.get('project_slug') || '').trim();
+    const events = [];
+    const agentsRoot = agentsRootDefault(ctx);
+    const yfRoot = path.join(agentsRoot);
+    /* 1. nac3 dispatch log -- every verb invoke / deny / panel-dispatch */
+    const dispatchLog = path.join(yfRoot, 'nac3_log.jsonl');
+    for (const e of await tailJsonl(dispatchLog, limit)) {
+        const r = e;
+        if (!r.ts)
+            continue;
+        const label = r.kind === 'invoke' ? ((r.result_ok ? 'ok' : 'err') + ' ' + (r.verb_id ?? '?'))
+            : r.kind === 'verb-not-found' ? ('unknown verb ' + (r.verb_id ?? '?'))
+                : r.kind === 'policy-deny' ? ('policy denied ' + (r.verb_id ?? '?'))
+                    : r.kind === 'panel-handler-error' ? ('panel error ' + (r.verb_id ?? '?'))
+                        : String(r.kind ?? 'event');
+        events.push({
+            ts: String(r.ts),
+            kind: 'dispatch.' + String(r.kind ?? 'unknown'),
+            text: label,
+            trace_id: r.trace_id ? String(r.trace_id) : undefined,
+            extra: {
+                duration_ms: r.duration_ms,
+                policy: r.policy,
+                side_effects_declared: r.side_effects_declared,
+            },
+        });
+    }
+    /* 2. approvals log -- R8 modal decisions */
+    const approvalLog = path.join(yfRoot, 'nac3_approvals.jsonl');
+    for (const e of await tailJsonl(approvalLog, limit)) {
+        const r = e;
+        if (!r.ts)
+            continue;
+        events.push({
+            ts: String(r.ts),
+            kind: 'approval.' + String(r.decision ?? 'event'),
+            text: 'R8 ' + String(r.decision ?? '?') + ' on ' + String(r.verb_id ?? '?'),
+            trace_id: r.trace_id ? String(r.trace_id) : undefined,
+            extra: { policy: r.policy, reason: r.reason },
+        });
+    }
+    /* 3. agent runs -- scan ~/.yujin-forge/agents/by-slug/<slug>/runs/*.json */
+    const bySlug = path.join(yfRoot, 'agents', 'by-slug');
+    let slugs = [];
+    try {
+        slugs = await fs.readdir(bySlug);
+    }
+    catch { /* no agents yet -- ok */ }
+    for (const slug of slugs) {
+        const runsDir = path.join(bySlug, slug, 'runs');
+        let runFiles = [];
+        try {
+            runFiles = (await fs.readdir(runsDir)).filter((n) => n.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        /* Newest first; we cap at limit per agent so a noisy one
+         * does not drown others. */
+        runFiles.sort();
+        const cap = runFiles.slice(-Math.min(50, limit));
+        for (const fn of cap) {
+            try {
+                const raw = await fs.readFile(path.join(runsDir, fn), 'utf-8');
+                const r = JSON.parse(raw);
+                const startTs = r.started_at ? new Date(Number(r.started_at)).toISOString() : '';
+                const endTs = r.ended_at ? new Date(Number(r.ended_at)).toISOString() : startTs;
+                const runProject = (typeof r.project_slug === 'string' && r.project_slug) ? r.project_slug : 'self';
+                events.push({
+                    ts: startTs || endTs,
+                    kind: 'agent.run_started',
+                    slug,
+                    text: '[' + runProject + '] ' + slug + ' started: ' + String(r.trigger_reason ?? '').slice(0, 120),
+                    project_slug: runProject,
+                });
+                if (r.ended_at) {
+                    events.push({
+                        ts: endTs,
+                        kind: 'agent.run_finished',
+                        slug,
+                        text: '[' + runProject + '] ' + slug + ' ' + String(r.status ?? '?')
+                            + ' (in=' + (r.tokens_in ?? 0) + ' out=' + (r.tokens_out ?? 0)
+                            + ' tools=' + (r.tool_calls ?? 0) + ')',
+                        project_slug: runProject,
+                        extra: {
+                            status: r.status,
+                            tokens_in: r.tokens_in,
+                            tokens_out: r.tokens_out,
+                            tool_calls: r.tool_calls,
+                            kill_reason: r.kill_reason,
+                            last_reply_summary: typeof r.last_reply_summary === 'string'
+                                ? String(r.last_reply_summary).slice(0, 240)
+                                : undefined,
+                        },
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    /* 4. bridge messages -- scan every shard under
+     *    ~/.yujin-forge/bridge/ (bridge.json + bridge-{slug}.json).
+     *    Each shard's messages tag themselves with project_slug
+     *    derived from the filename so the activity feed knows which
+     *    project a message belongs to. */
+    const bridgeDir = path.join(yfRoot, 'bridge');
+    let bridgeShards = [];
+    try {
+        bridgeShards = (await fs.readdir(bridgeDir)).filter((n) => n.endsWith('.json') && (n === 'bridge.json' || n.startsWith('bridge-')));
+    }
+    catch { /* no bridge dir -- ok */ }
+    for (const fname of bridgeShards) {
+        const projectFromFile = fname === 'bridge.json'
+            ? 'self'
+            : fname.slice('bridge-'.length, fname.length - '.json'.length) || 'self';
+        try {
+            const raw = await fs.readFile(path.join(bridgeDir, fname), 'utf-8');
+            const b = JSON.parse(raw);
+            const msgs = Array.isArray(b.messages) ? b.messages : [];
+            /* Take last `limit` per shard to bound memory while not
+             * losing recent activity. */
+            const slice = msgs.length > limit ? msgs.slice(msgs.length - limit) : msgs;
+            for (const m of slice) {
+                const ts = m.sent_at ? new Date(Number(m.sent_at)).toISOString()
+                    : (m.created_at ? new Date(Number(m.created_at)).toISOString() : '');
+                const msgProject = (typeof m.project_slug === 'string' && m.project_slug)
+                    ? m.project_slug
+                    : projectFromFile;
+                events.push({
+                    ts,
+                    kind: 'bridge.message',
+                    from: String(m.from_slug ?? m.from ?? '?'),
+                    to: String(m.to_slug ?? m.to ?? '?'),
+                    text: '[' + msgProject + '] '
+                        + String(m.from_slug ?? m.from ?? '?') + ' -> ' + String(m.to_slug ?? m.to ?? '?')
+                        + ': ' + String(m.payload ?? '').slice(0, 160),
+                    project_slug: msgProject,
+                    extra: { tokens: m.tokens_used, status: m.status, id: m.id },
+                });
+            }
+        }
+        catch { /* skip unreadable shard */ }
+    }
+    /* Sort desc by ts (ISO strings sort correctly). Filter by since
+     * + project_filter. */
+    events.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+    let filtered = since ? events.filter((e) => e.ts > since) : events;
+    if (projectFilter) {
+        filtered = filtered.filter((e) => e.project_slug === projectFilter
+            /* Events without a project_slug (legacy or non-project-
+             * tagged kinds like dispatch.*) appear under 'self' so a
+             * filter for the default project still sees them. */
+            || (!e.project_slug && projectFilter === 'self'));
+    }
+    const final = filtered.slice(0, limit);
+    sendJson(res, 200, { ok: true, count: final.length, project_filter: projectFilter || null, events: final });
+}
+async function handleAgentBridgeTail(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const limit = clampInt(url.searchParams.get('limit'), 100, 1, 1000);
+    const pairId = (url.searchParams.get('pair_id') || '').trim();
+    /* Slice 1 N-projects sprint -- optional project filter. Empty
+     * means "scan every shard". 'self' means only the default
+     * (legacy bridge.json). */
+    const projectFilter = (url.searchParams.get('project_slug') || '').trim();
+    const yfRoot = agentsRootDefault(ctx);
+    const bridgeDir = path.join(yfRoot, 'bridge');
+    /* Discover every shard file, then read whichever ones match
+     * the filter. */
+    let shardFiles = [];
+    try {
+        shardFiles = (await fs.readdir(bridgeDir)).filter((n) => n.endsWith('.json') && (n === 'bridge.json' || n.startsWith('bridge-')));
+    }
+    catch {
+        sendJson(res, 200, { ok: true, pairs: [], messages: [], pair_state: {}, project_filter: projectFilter || null });
+        return;
+    }
+    /* Load every shard. msgs carries an extra `_project_slug` for
+     * downstream filtering. pair_state aggregated per-shard. */
+    const allMsgs = [];
+    const allPairState = {};
+    for (const fname of shardFiles) {
+        const project = fname === 'bridge.json'
+            ? 'self'
+            : fname.slice('bridge-'.length, fname.length - '.json'.length) || 'self';
+        if (projectFilter && projectFilter !== project)
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(bridgeDir, fname), 'utf-8');
+            const b = JSON.parse(raw);
+            const ms = Array.isArray(b.messages) ? b.messages : [];
+            for (const m of ms)
+                allMsgs.push({ ...m, _project_slug: project });
+            if (b.pair_state) {
+                for (const [pid, st] of Object.entries(b.pair_state)) {
+                    allPairState[pid + '@' + project] = { project_slug: project, state: st };
+                }
+            }
+        }
+        catch { /* skip unreadable shard */ }
+    }
+    /* When pair_id absent: aggregate by pair (cross-shard). The
+     * project_slug is part of the visible pair card so two pairs
+     * with the same from/to but different projects don't merge. */
+    if (!pairId) {
+        const pairs = {};
+        for (const m of allMsgs) {
+            const fromSlug = String(m.from_slug ?? m.from ?? '?');
+            const toSlug = String(m.to_slug ?? m.to ?? '?');
+            const proj = m._project_slug;
+            const key = fromSlug + '__' + toSlug + (proj === 'self' ? '' : '@' + proj);
+            const ts = m.sent_at ? new Date(Number(m.sent_at)).toISOString()
+                : (m.created_at ? new Date(Number(m.created_at)).toISOString() : '');
+            if (!pairs[key]) {
+                pairs[key] = { from: fromSlug, to: toSlug, count: 0, last_ts: ts, project_slug: proj };
+            }
+            pairs[key].count++;
+            if (ts > pairs[key].last_ts)
+                pairs[key].last_ts = ts;
+        }
+        const list = Object.entries(pairs).map(([k, v]) => ({ pair_id: k, ...v }))
+            .sort((a, b) => (a.last_ts < b.last_ts ? 1 : -1));
+        sendJson(res, 200, { ok: true, pairs: list, project_filter: projectFilter || null });
+        return;
+    }
+    /* With pair_id: parse out optional @project suffix; filter
+     * messages newest first, capped. */
+    const atIdx = pairId.lastIndexOf('@');
+    const pairCore = atIdx >= 0 ? pairId.slice(0, atIdx) : pairId;
+    const pairProject = atIdx >= 0 ? pairId.slice(atIdx + 1) : 'self';
+    const filtered = allMsgs.filter((m) => {
+        const fromSlug = String(m.from_slug ?? m.from ?? '?');
+        const toSlug = String(m.to_slug ?? m.to ?? '?');
+        return (fromSlug + '__' + toSlug) === pairCore && m._project_slug === pairProject;
+    });
+    const slice = filtered.length > limit ? filtered.slice(filtered.length - limit) : filtered;
+    slice.sort((a, b) => Number(b.sent_at ?? 0) - Number(a.sent_at ?? 0));
+    /* Find matching pair_state from the per-shard map. */
+    const pairStateKey = Object.keys(allPairState).find((k) => k.endsWith('@' + pairProject))
+        || null;
+    sendJson(res, 200, {
+        ok: true,
+        pair_id: pairId,
+        project_slug: pairProject,
+        count: slice.length,
+        messages: slice,
+        pair_state: pairStateKey ? allPairState[pairStateKey].state : null,
+    });
+}
+async function handleAgentInject(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const slug = typeof body.slug === 'string' ? body.slug.trim() : '';
+    const text = typeof body.text === 'string' ? body.text.trim() : '';
+    if (!slug) {
+        sendJson(res, 400, { ok: false, error: 'slug required' });
+        return;
+    }
+    if (!text) {
+        sendJson(res, 400, { ok: false, error: 'text required' });
+        return;
+    }
+    const doDispatch = body.dispatch !== false;
+    /* Slice 1 N-projects sprint -- explicit project_slug routes
+     * the user message to that project's conversation/run instance.
+     * Defaults to 'self' for legacy single-project behaviour. */
+    const project_slug = (typeof body.project_slug === 'string' && body.project_slug.trim())
+        ? body.project_slug.trim()
+        : 'self';
+    const yfRoot = agentsRootDefault(ctx);
+    const convDir = path.join(yfRoot, 'agents', 'by-slug', slug, 'conversations');
+    /* Pick the most recently modified conversation file, or create
+     * one named "manual" if none exists yet. */
+    let convFile = path.join(convDir, 'manual.json');
+    try {
+        const files = (await fs.readdir(convDir)).filter((n) => n.endsWith('.json'));
+        if (files.length > 0) {
+            const stats = await Promise.all(files.map(async (n) => ({
+                name: n,
+                mtime: (await fs.stat(path.join(convDir, n))).mtimeMs,
+            })));
+            stats.sort((a, b) => b.mtime - a.mtime);
+            convFile = path.join(convDir, stats[0].name);
+        }
+    }
+    catch {
+        /* convDir does not exist yet -- mkdir below + start manual. */
+    }
+    let messages = [];
+    try {
+        const raw = await fs.readFile(convFile, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.messages))
+            messages = parsed.messages;
+    }
+    catch { /* fresh */ }
+    messages.push({ role: 'user', content: text });
+    try {
+        await fs.mkdir(convDir, { recursive: true });
+        await fs.writeFile(convFile, JSON.stringify({ version: 1, messages }, null, 2), 'utf-8');
+    }
+    catch (err) {
+        sendJson(res, 500, { ok: false, error: 'persist failed: ' + (err instanceof Error ? err.message : String(err)) });
+        return;
+    }
+    if (doDispatch) {
+        if (!ctx.runtime) {
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: false,
+                note: 'runtime not wired -- message saved but no run fired',
+            });
+            return;
+        }
+        try {
+            const run = await ctx.runtime.dispatchAgent(slug, 'user-injected: ' + text.slice(0, 80), { project_slug });
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: true,
+                run_status: run.status, run_id: run.id, last_reply: run.last_reply_summary,
+                project_slug: run.project_slug ?? project_slug,
+            });
+        }
+        catch (err) {
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return;
+    }
+    sendJson(res, 200, { ok: true, persisted: convFile, dispatched: false });
+}
+function clampInt(raw, fallback, lo, hi) {
+    const n = raw != null ? Number(raw) : fallback;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(lo, Math.min(hi, Math.floor(n)));
+}
+/** Serve a legal doc (privacy policy / limited responsibility) as
+ *  text/markdown. Reads from dist/docs/<basename> (copied at build
+ *  time by scripts/copy_qa_assets.mjs). Names are static + sanitised
+ *  by the route caller -- no user input reaches the filesystem
+ *  path. */
+async function serveLegalDoc(res, basename) {
+    /* The CLI bundle's __dirname at runtime points at dist/chat/.
+     * Hop back to dist/ then into docs/. */
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const distRoot = path.resolve(here, '..');
+    const docPath = path.join(distRoot, 'docs', basename);
+    try {
+        const md = await fs.readFile(docPath, 'utf-8');
+        res.statusCode = 200;
+        res.setHeader('content-type', 'text/markdown; charset=utf-8');
+        res.setHeader('cache-control', 'no-store, must-revalidate');
+        res.end(md);
+    }
+    catch (err) {
+        res.statusCode = 404;
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({ ok: false, error: 'legal doc not found', detail: basename }));
+        /* Surface for ops; not user-visible. */
+        console.warn('[serveLegalDoc] ' + docPath + ': ' + (err instanceof Error ? err.message : String(err)));
+    }
+}
 /** 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
@@ -1940,11 +5268,16 @@ async function readBinaryBody(req, maxBytes) {
     return Buffer.concat(chunks);
 }
 async function readProjectName(projectRoot) {
+    /* Display name. Prefers project_name (human-readable) over
+     *  project_slug (kebab/lower id). For graph identity use
+     *  resolveProjectSlug (chat/project_slug.ts). */
     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;
+        if (parsed && typeof parsed.project_slug === 'string')
+            return parsed.project_slug;
     }
     catch { /* fall through */ }
     try {