@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.119

package/dist/chat/server.js

@@ -37,8 +37,53 @@ 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 { 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);
+    /* 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);
+    /* 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 */ }
+    /* 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 */ }
     const claude = opts.claude ?? new ClaudeClient();
     const voice = opts.voice ?? new VoiceRouter({
         configDir: configDir(),
@@ -81,6 +126,7 @@ export async function startChatServer(opts) {
             await route(req, res, {
                 projectRoot: opts.projectRoot,
                 projectName,
+                projectSlug,
                 port: opts.port,
                 claude,
                 voice,
@@ -114,6 +160,11 @@ export async function startChatServer(opts) {
         url,
         store,
         close: () => new Promise((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);
+            }
             server.close(() => resolve());
         }),
     };
@@ -144,6 +195,39 @@ async function route(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 +258,281 @@ 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.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.59r -- semantic graph status proxy. Forwards a list
+     *  call to the worker so the panel can show node counts in
+     *  the settings card without exposing the HMAC bearer to JS.
+     *  Returns { ok, count, by_kind, by_confidence, sample[] }.
+     *  Graceful: returns count=0 when worker unreachable. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/graph-status') {
+        try {
+            const { semanticGraphGet } = await import('../license/hito4_client.js');
+            /* alpha.59u.2 -- default to ctx.projectName when the panel
+             *  JS does not pass an explicit project_slug. This matches
+             *  the slug that the CLI `yf graph ingest` uses (both call
+             *  resolveProjectSlug). Without this, panel sees '' while
+             *  CLI wrote with 'name-from-package-json' -> 0 results. */
+            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. The user reported
+             *  seeing "1 node" then "19 nodes" after Refrescar; this
+             *  serialises them. */
+            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 */ }
+            const r = await semanticGraphGet('/v1/semantic-graph/nodes', {}, { project_slug: project });
+            if (!r.ok || !r.body || r.body.ok !== true) {
+                sendJson(res, 200, { ok: true, count: 0, by_kind: {}, by_confidence: {}, sample: [], available: false });
+                return;
+            }
+            const nodes = r.body.nodes || [];
+            const by_kind = {};
+            const by_confidence = {};
+            for (const n of nodes) {
+                by_kind[n.kind] = (by_kind[n.kind] || 0) + 1;
+                by_confidence[n.confidence] = (by_confidence[n.confidence] || 0) + 1;
+            }
+            const sample = nodes.slice(0, 10).map((n) => ({
+                id: n.id, kind: n.kind, name: n.name, version: n.version, purpose: n.purpose, confidence: n.confidence,
+            }));
+            sendJson(res, 200, { ok: true, count: nodes.length, by_kind, by_confidence, sample, available: true });
+        }
+        catch {
+            sendJson(res, 200, { ok: true, count: 0, by_kind: {}, by_confidence: {}, sample: [], available: false });
+        }
+        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);
@@ -248,6 +607,95 @@ async function route(req, res, ctx) {
         await handleForgeToolDispatch(req, res, ctx);
         return;
     }
+    /* Open-in-editor escape hatch (Layer A.2). The panel surfaces
+       file paths as clickable; click triggers this endpoint, which
+       spawns the user's default editor (code / cursor / subl /
+       idea, in order). Best-effort -- on failure returns the
+       resolved path so the panel can copy-to-clipboard fallback. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/open-in-editor') {
+        await handleOpenInEditor(req, res, ctx);
+        return;
+    }
+    /* Trust gradient tracking (Layer A.2). Panel increments
+       counters when the user expands a diff / opens a file in
+       their editor / overrides Forge. Forge reads them at session
+       boot and decides whether to surface or hide the detail
+       links. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/trust-event') {
+        await handleTrustEvent(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/trust-state') {
+        await handleTrustState(req, res, ctx);
+        return;
+    }
+    /* 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;
+    }
+    /* 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;
+    }
+    /* 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,
@@ -423,6 +871,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
@@ -516,6 +977,144 @@ 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,
+    });
+    sendJson(res, 200, {
+        ok: true,
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'rejected',
+    });
+}
 /** V1.37 + V1.38 -- ingest a spec doc via drag-drop / upload.
  *
  * Accepts POST with:
@@ -643,7 +1242,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,
@@ -705,7 +1304,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,
@@ -948,6 +1547,460 @@ async function handleVoiceTts(req, res, ctx) {
         });
     }
 }
+/* ============================================================
+ * Layer A.2 -- minority surface (open in editor + trust gradient)
+ * ============================================================ */
+/** Check that `target` is inside `root` (after resolving both).
+ *  Refuses path traversal like ../../../etc/passwd. */
+function isInside(target, root) {
+    const targetAbs = path.resolve(target);
+    const rootAbs = path.resolve(root) + path.sep;
+    return targetAbs === path.resolve(root) || targetAbs.startsWith(rootAbs);
+}
+/** Editor commands tried in order. First match wins. The args
+ *  templates are joined with the file path at runtime. All
+ *  commands run with stdio ignored + detached so the panel does
+ *  not block on the editor's window lifetime. */
+const EDITOR_CANDIDATES = [
+    { cmd: 'code', args: (f) => [f] }, // VS Code
+    { cmd: 'cursor', args: (f) => [f] }, // Cursor
+    { cmd: 'subl', args: (f) => [f] }, // Sublime Text
+    { cmd: 'idea', args: (f) => [f] }, // IntelliJ family
+    { cmd: 'webstorm', args: (f) => [f] },
+    { cmd: 'nano', args: (f) => [f] },
+    { cmd: 'vim', args: (f) => [f] },
+];
+async function handleOpenInEditor(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.path !== 'string' || body.path.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'path (non-empty string) required' });
+        return;
+    }
+    /* Resolve to absolute under the project root. Refuse paths
+     *  that escape the project tree (no user opening /etc/passwd
+     *  through the chat). */
+    const requestedRel = body.path.trim().replace(/^[/\\]+/, '');
+    const absolute = path.join(ctx.projectRoot, requestedRel);
+    if (!isInside(absolute, ctx.projectRoot)) {
+        sendJson(res, 400, { ok: false, error: 'path escapes project root' });
+        return;
+    }
+    /* Walk the candidates, spawn the first one that does not
+     *  throw ENOENT. */
+    const { spawn } = await import('node:child_process');
+    for (const candidate of EDITOR_CANDIDATES) {
+        try {
+            const cmd = process.platform === 'win32' ? `${candidate.cmd}.cmd` : candidate.cmd;
+            const child = spawn(cmd, candidate.args(absolute), {
+                stdio: 'ignore',
+                detached: true,
+                shell: false,
+            });
+            child.on('error', () => { });
+            child.unref();
+            /* If spawn returned, the binary is at least present.
+             *  We do not wait for editor to launch (it might be slow
+             *  or might be a background daemon). Report success. */
+            sendJson(res, 200, {
+                ok: true,
+                editor: candidate.cmd,
+                path: absolute,
+            });
+            return;
+        }
+        catch { /* ENOENT etc -- try next candidate */ }
+    }
+    /* No editor found. Return the absolute path so the panel can
+     *  offer copy-to-clipboard fallback. */
+    sendJson(res, 200, {
+        ok: false,
+        error: 'no supported editor found in PATH',
+        path: absolute,
+        candidates: EDITOR_CANDIDATES.map((c) => c.cmd),
+        hint: 'Install VS Code (code), Cursor, Sublime (subl), or IntelliJ; or copy the path manually.',
+    });
+}
+function trustMetricsPath() {
+    return path.join(configDir(), 'trust_metrics.json');
+}
+async function loadTrustMetrics() {
+    const fs = await import('node:fs');
+    try {
+        const raw = await fs.promises.readFile(trustMetricsPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            return {
+                v: 1,
+                diff_expansions: Number(parsed.diff_expansions) || 0,
+                editor_opens: Number(parsed.editor_opens) || 0,
+                forge_overrides: Number(parsed.forge_overrides) || 0,
+                last_event_at: typeof parsed.last_event_at === 'string' ? parsed.last_event_at : null,
+                last_proposal_at: typeof parsed.last_proposal_at === 'string' ? parsed.last_proposal_at : null,
+                user_choice: ['show', 'hide', 'default'].includes(parsed.user_choice) ? parsed.user_choice : 'default',
+            };
+        }
+    }
+    catch { /* missing or bad -- return defaults */ }
+    return {
+        v: 1,
+        diff_expansions: 0,
+        editor_opens: 0,
+        forge_overrides: 0,
+        last_event_at: null,
+        last_proposal_at: null,
+        user_choice: 'default',
+    };
+}
+async function saveTrustMetrics(m) {
+    const fs = await import('node:fs');
+    await fs.promises.mkdir(configDir(), { recursive: true });
+    await fs.promises.writeFile(trustMetricsPath(), JSON.stringify(m, null, 2), 'utf-8');
+}
+async function handleTrustEvent(req, res, _ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const kind = typeof body.kind === 'string' ? body.kind : '';
+    const m = await loadTrustMetrics();
+    const now = new Date().toISOString();
+    switch (kind) {
+        case 'diff_expansion':
+            m.diff_expansions += 1;
+            break;
+        case 'editor_open':
+            m.editor_opens += 1;
+            break;
+        case 'forge_override':
+            m.forge_overrides += 1;
+            break;
+        case 'user_chose_show':
+            m.user_choice = 'show';
+            break;
+        case 'user_chose_hide':
+            m.user_choice = 'hide';
+            break;
+        default:
+            sendJson(res, 400, { ok: false, error: 'unknown kind: ' + kind });
+            return;
+    }
+    m.last_event_at = now;
+    await saveTrustMetrics(m);
+    sendJson(res, 200, { ok: true, metrics: m });
+}
+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,
+        keys: out,
+        license_plan,
+        license_user_handle,
+        license_last_validated_at,
+        license_can_sync: license_user_handle !== null,
+    });
+}
+/** 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() });
@@ -1272,6 +2325,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)
@@ -1298,19 +2382,373 @@ 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({
+        /* 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;
+        const unified = makeUnifiedClient(brainSelection);
+        const callerForChat = unified
+            ? unified
+            : {
+                chat: async (r) => {
+                    const claudeReply = await ctx.claude.chat(r);
+                    return { ...claudeReply, brain: { ...brainSelection, runtime_wired: false } };
+                },
+            };
+        /* 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.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,
-            system: buildSystemPrompt(ctx, reqMode, pilotState),
+            system: buildSystemPrompt(ctx, reqMode, pilotState, {
+                tier: brainSelection.tier,
+                provider: brainSelection.provider,
+                model: brainSelection.model,
+            }, globalLearnings, mcpAvailable, backendToolsSection) + graphSection + workflowSection,
             maxTokens: 1024,
             tools: FORGE_TOOL_SPECS,
             runTool: async (name, input) => {
-                const r = await runForgeTool(name, input, { projectRoot: ctx.projectRoot });
+                /* 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) {
+                    sseEmit('tool_round_start', {
+                        round: callSig.length,
+                        verb_id: verbId,
+                        verb_hint: verbHint,
+                    });
+                }
+                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,
+                    ...(sseEmit ? { streamEmit: sseEmit } : {}),
+                };
+                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,
+                    });
+                    const frontierClient = 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),
+                        };
+                        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
@@ -1325,7 +2763,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
@@ -1339,77 +2806,429 @@ async function handleChat(req, res, ctx) {
                 catch { /* non-fatal */ }
             }
         }
-        sendJson(res, 200, {
+        /* 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.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 friendly assistant embedded in a developer\'s React project.',
+        '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.',
+        '',
+        ...(tierHeader ? [tierHeader, ''] : []),
+        'LEMA YUJIN: "La tecnologia desaparece. El sistema aprende de vos, no vos del sistema." Toda decision se evalua contra esto.',
+        '',
+        '=================================================================',
+        'CORE PRINCIPLES (docs/SQ.md)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        'SQ 2 -- ZERO TECH DEBT from commit 0. Bugs found in-flight get a',
+        '  root fix + regression spec in the SAME session. No "later".',
+        '',
+        'SQ 3 -- ASCII-PURE in product code. No accents, emojis, em-dashes,',
+        '  no chars > 0x7F in .ts/.tsx/.py/.php/.sql/.json (outside _i18n).',
+        '',
+        'SQ 4 -- DOCS IN SYNC. Every commit cross-links the RFP / Arch /',
+        '  Solution Design / User Manual sections it affects. Doc/code',
+        '  drift = bug.',
+        '',
+        'SQ 5 -- MATCH THE SCOPE. Bug ask = fix that bug only, no refactor',
+        '  "de paso". Feature ask = no unrelated code touched.',
+        '',
+        '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.',
+        '',
+        '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.',
+        '',
+        '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.',
+        '',
+        '=================================================================',
+        'PRODUCT WORKFLOW (on-demand)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '=================================================================',
+        'GENERATION DOCTRINE + WORKFLOW GATES (on-demand)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '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"]}).',
+        '',
+        '=================================================================',
+        'NAC-3 ATTRIBUTES (on-demand)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '=================================================================',
+        'YF COMMAND CATALOG (on-demand)',
+        '=================================================================',
         '',
-        'PRINCIPLES:',
-        '- Reply in the user\'s language. Default to Spanish if unclear.',
-        '- Keep replies short + conversational.',
-        '- Ask one clarifying question at a time.',
-        '- When proposing code changes, paste minimal diffs the user can apply manually.',
-        '  Direct AST mutation lands when the write-class tools ship.',
+        '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.',
         '',
-        'TOOLS:',
-        '- forge.read_manifest: inspect the NAC-3 manifest in the project.',
-        '  Use it BEFORE asking the user what is in their app.',
-        '- forge.consult_nac_spec: search docs/SPEC.md for canonical',
-        '  answers about NAC-3. Use it when the user asks "what does',
-        '  NAC say about X" or you need to ground an answer in the spec.',
-        '- forge.list_files: list source files under a subdir of the',
-        '  project (default src/). Use it when you need to know what',
-        '  files exist before suggesting where to edit. Filter with',
-        '  the glob arg (e.g. "*.tsx") to narrow the result.',
-        '- forge.read_file: read a specific source file by relative',
-        '  path. Use AFTER forge.list_files when you need the actual',
-        '  contents. Refuses binary files + caps at 64KB by default.',
-        '- Tool calls are silent to the user. Summarise what you found',
-        '  in plain language afterwards.',
+        '=================================================================',
+        'NAC3 INTERNAL DISPATCH (alpha.40 -- SINGLE CATALOGUE)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '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.',
+        '',
+        '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] : []),
+        '=================================================================',
+        'PIZARRON DOCTRINE (condensed; full text on-demand)',
+        '=================================================================',
+        '',
+        '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"]}).',
+        '',
+        '=================================================================',
+        'R7 -- HONEST SEQUENCING (anti-hallucination)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '=================================================================',
+        'R8 -- THE MODAL IS THE QUESTION (anti-redundancy)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '"[NAC3 modal] APPROVED/REJECTED" is a SYSTEM event, not the',
+        'user talking -- do NOT thank them for approving.',
+        '',
+        'For the full doctrine with MAL/BIEN examples, call',
+        'yujin.doctrine.discover({slugs:["r8-modal"]}).',
+        '',
+        '=================================================================',
+        'BYOK + LICENSE (all chat/voice -- LEMA YUJIN)',
+        '=================================================================',
+        '',
+        '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.',
+        '',
+        '=================================================================',
+        'WORKFLOW STATE MACHINE (18 steps)',
+        '=================================================================',
+        '',
+        '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 calls are silent to the user. Summarise the result in plain',
+        '  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)',
+        '=================================================================',
         '',
-        'CONTEXT:',
         '- Project: ' + ctx.projectName,
         '- Root:    ' + ctx.projectRoot,
         '- Forge:   v' + VERSION,
@@ -1422,6 +3241,33 @@ function sendJson(res, status, body) {
     res.setHeader('content-type', 'application/json; charset=utf-8');
     res.end(JSON.stringify(body));
 }
+/** 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
@@ -1521,11 +3367,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 {