vigthoria-cli 1.10.0 → 1.10.36

package/dist/utils/api.js

@@ -9,16 +9,24 @@ import https from 'https';
 import net from 'net';
 import path from 'path';
 import WebSocket from 'ws';
+export const VIGTHORIA_HUB_CREDITS_URL = 'https://hub.vigthoria.io/credits';
+export const VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE = 'Vigthoria Server is temporarily not available. Please try again later. If the issue persists, please contact support.';
 export class CLIError extends Error {
     category;
     statusCode;
     endpoint;
+    walletUrl;
+    topupUrl;
+    balance;
     constructor(message, category, opts) {
         super(message);
         this.name = 'CLIError';
         this.category = category;
         this.statusCode = opts?.statusCode;
         this.endpoint = opts?.endpoint;
+        this.walletUrl = opts?.walletUrl;
+        this.topupUrl = opts?.topupUrl;
+        this.balance = opts?.balance;
         if (opts?.cause)
             this.cause = opts.cause;
     }
@@ -30,13 +38,25 @@ export function classifyError(error, fallbackCategory = 'network') {
     const axErr = error;
     const status = axErr?.response?.status;
     const endpoint = axErr?.config?.url || axErr?.config?.baseURL || '';
-    const message = axErr?.response?.data
-        ? typeof axErr.response.data.error === 'string'
-            ? axErr.response.data.error
-            : typeof axErr.response.data.message === 'string'
-                ? axErr.response.data.message
-                : error.message
+    const responseData = axErr?.response?.data;
+    const nestedError = responseData?.error;
+    const message = responseData
+        ? typeof nestedError === 'string'
+            ? nestedError
+            : typeof responseData.message === 'string'
+                ? responseData.message
+                : typeof nestedError === 'object' && nestedError && typeof nestedError.message === 'string'
+                    ? nestedError.message
+                    : error.message
         : error.message || String(error);
+    if (status === 402 || responseData?.errorCode === 'INSUFFICIENT_CREDITS' || responseData?.errorCode === 'WALLET_REQUIRED' || responseData?.errorCode === 'CLOUD_CREDIT_REQUIRED') {
+        const walletUrl = String(responseData?.walletUrl || responseData?.topupUrl || VIGTHORIA_HUB_CREDITS_URL);
+        const balance = typeof responseData?.balance === 'number' ? responseData.balance : undefined;
+        const creditMessage = typeof responseData?.message === 'string'
+            ? responseData.message
+            : `Your cloud credit balance is too low. Add credits: ${walletUrl}`;
+        return new CLIError(creditMessage, 'credits', { statusCode: status || 402, endpoint, walletUrl, topupUrl: walletUrl, balance });
+    }
     if (status === 401 || status === 403) {
         // Distinguish repo/community auth from model auth
         if (/community|repo/i.test(endpoint)) {
@@ -64,7 +84,7 @@ export function formatCLIError(err) {
         case 'repo_session':
             return `${tag} Repository session expired or missing${err.statusCode ? ` (${err.statusCode})` : ''}. This does not affect AI commands. Re-authenticate repo with: vigthoria repo list`;
         case 'model_backend':
-            return `${tag} Model backend error${err.statusCode ? ` (${err.statusCode})` : ''}: ${err.message}`;
+            return VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE;
         case 'bridge':
             return `${tag} Bridge connection error: ${err.message}`;
         case 'network':
@@ -75,6 +95,8 @@ export function formatCLIError(err) {
             return `${tag} Response parsing error: ${err.message}`;
         case 'tool_execution':
             return `${tag} Tool execution error: ${err.message}`;
+        case 'credits':
+            return `${tag} ${err.message}${err.walletUrl ? `\nTop up credits: ${err.walletUrl}` : ''}`;
         default:
             return `${tag} ${err.message}`;
     }
@@ -242,6 +264,21 @@ const DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS = (() => {
     const parsed = Number.parseInt(rawValue, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 90000;
 })();
+const DEFAULT_MCP_BIND_TIMEOUT_MS = (() => {
+    const rawValue = process.env.VIGTHORIA_MCP_BIND_TIMEOUT_MS || process.env.MCP_BIND_TIMEOUT_MS || '5000';
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 5000;
+})();
+const DEFAULT_WORKSPACE_SCAN_TIMEOUT_MS = (() => {
+    const rawValue = process.env.VIGTHORIA_WORKSPACE_SCAN_TIMEOUT_MS || '2500';
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 2500;
+})();
+const DEFAULT_WORKSPACE_SCAN_MAX_FILES = (() => {
+    const rawValue = process.env.VIGTHORIA_WORKSPACE_SCAN_MAX_FILES || '1800';
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 1800;
+})();
 const DEFAULT_OPERATOR_TIMEOUT_MS = (() => {
     const rawValue = process.env.VIGTHORIA_OPERATOR_TIMEOUT_MS || process.env.OPERATOR_TIMEOUT_MS;
     if (!rawValue) {
@@ -250,6 +287,16 @@ const DEFAULT_OPERATOR_TIMEOUT_MS = (() => {
     const parsed = Number.parseInt(rawValue, 10);
     return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
 })();
+const DEFAULT_CHAT_CONNECT_TIMEOUT_MS = (() => {
+    const rawValue = process.env.VIGTHORIA_CHAT_CONNECT_TIMEOUT_MS || '20000';
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 20000;
+})();
+const DEFAULT_CHAT_IDLE_TIMEOUT_MS = (() => {
+    const rawValue = process.env.VIGTHORIA_CHAT_IDLE_TIMEOUT_MS || '120000';
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 120000;
+})();
 export class APIClient {
     client;
     modelRouterClient;
@@ -291,7 +338,7 @@ export class APIClient {
                 'User-Agent': `Vigthoria-CLI/${process.env.npm_package_version || '1.6.9'}`,
             },
         });
-        // Self-hosted model router is opt-in only.
+        // Optional dedicated Vigthoria model endpoint for internal/server deployments only.
         const selfHostedModelsApiUrl = this.getSelfHostedModelsApiUrl();
         this.selfHostedModelRouterClient = selfHostedModelsApiUrl ? axios.create({
             baseURL: selfHostedModelsApiUrl,
@@ -581,16 +628,20 @@ export class APIClient {
     }
     getV3AgentBaseUrls(preferLocal = false) {
         const configuredApiUrl = String(this.config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
-        const allowLocalV3Agent = preferLocal
-            || process.env.VIGTHORIA_ALLOW_LOCAL_V3_AGENT === '1'
-            || !isServerRuntime();
-        const urls = [
+        const includeLoopbackV3Agent = process.env.VIGTHORIA_ALLOW_LOCAL_V3_AGENT === '1'
+            || (preferLocal && isServerRuntime());
+        const localCandidates = [
             process.env.VIGTHORIA_V3_AGENT_URL,
             process.env.V3_AGENT_URL,
-            ...(allowLocalV3Agent ? ['http://127.0.0.1:8030'] : []),
+            ...(includeLoopbackV3Agent ? ['http://127.0.0.1:8030'] : []),
+        ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
+        const remoteCandidates = [
             configuredApiUrl,
             'https://coder.vigthoria.io',
         ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
+        const urls = preferLocal && localCandidates.length > 0
+            ? [...localCandidates, ...remoteCandidates]
+            : [...remoteCandidates, ...localCandidates];
         return [...new Set(urls)];
     }
     getV3AgentRunUrl(baseUrl) {
@@ -1043,6 +1094,7 @@ export class APIClient {
     async getV3AgentHeaders() {
         const headers = {
             'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
         };
         const authToken = this.getAccessToken();
         if (authToken) {
@@ -1051,12 +1103,365 @@ export class APIClient {
         }
         const serviceKey = process.env.VIGTHORIA_V3_SERVICE_KEY
             || process.env.V3_SERVICE_KEY
-            || process.env.HYPERLOOP_SERVICE_KEY;
+            || process.env.HYPERLOOP_SERVICE_KEY
+            || this.config.get('v3ServiceKey');
         if (serviceKey) {
             headers['X-Service-Key'] = serviceKey;
         }
         return headers;
     }
+    /**
+     * Ensure the V3 service key is available in config.
+     * If not already set via env or stored config, fetches it from the Coder API
+     * using the current user's auth token and caches it for this session and beyond.
+     */
+    async ensureV3ServiceKey() {
+        const existing = process.env.VIGTHORIA_V3_SERVICE_KEY
+            || process.env.V3_SERVICE_KEY
+            || process.env.HYPERLOOP_SERVICE_KEY
+            || this.config.get('v3ServiceKey');
+        if (existing)
+            return;
+        try {
+            const token = this.getAccessToken();
+            if (!token)
+                return;
+            const response = await this.client.get('/api/cli/v3-service-key', {
+                headers: { Authorization: `Bearer ${token}` },
+                timeout: 6000,
+            });
+            const key = response.data?.v3ServiceKey;
+            if (key) {
+                this.config.set('v3ServiceKey', key);
+                this.logger.debug('V3 service key retrieved and cached from Coder API.');
+            }
+        }
+        catch {
+            // Non-fatal: fall through; the health check will surface the auth error.
+        }
+    }
+    /**
+     * Fast preflight for local agent loop — probes model backends in parallel
+     * so users see a clear pass/fail before "Planning..." hangs on slow routes.
+     */
+    async runChatModelPreflight(requestedModel = 'agent') {
+        const routes = [];
+        const probes = [
+            {
+                name: 'Vigthoria Coder API',
+                run: async () => {
+                    const health = await this.getCoderHealth();
+                    return { ok: health.ok, error: health.error };
+                },
+            },
+            {
+                name: 'Vigthoria Models API',
+                run: async () => {
+                    const health = await this.getModelsHealth();
+                    return { ok: health.ok, error: health.error };
+                },
+            },
+        ];
+        const selfHostedHealth = await this.getSelfHostedHealth();
+        if (selfHostedHealth) {
+            probes.unshift({
+                name: selfHostedHealth.name || 'Dedicated Models API',
+                run: async () => ({ ok: selfHostedHealth.ok, error: selfHostedHealth.error }),
+            });
+        }
+        if (this.isSelfHostedPreferredModel(this.resolveModelId(requestedModel), requestedModel)) {
+            // Agent/code models should also accept V3 health as a usable inference path.
+            probes.push({
+                name: 'V3 Agent API',
+                run: async () => {
+                    const v3 = await this.runV3HealthCheck();
+                    return { ok: v3.healthy, error: v3.error };
+                },
+            });
+        }
+        const results = await Promise.all(probes.map(async (probe) => {
+            try {
+                const result = await probe.run();
+                routes.push({ name: probe.name, ok: result.ok, error: result.error });
+                return result.ok;
+            }
+            catch (error) {
+                const message = error.message || String(error);
+                routes.push({ name: probe.name, ok: false, error: message });
+                return false;
+            }
+        }));
+        const healthy = results.some(Boolean);
+        const inferenceRoutes = routes.filter((route) => route.name !== 'V3 Agent API');
+        const firstHealthy = inferenceRoutes.find((route) => route.ok) || routes.find((route) => route.ok);
+        return {
+            healthy,
+            endpoint: firstHealthy?.name || 'api.vigthoria.io',
+            error: healthy
+                ? undefined
+                : 'No Vigthoria model backend responded during preflight. Run `vigthoria login` and check your internet connection.',
+            routes,
+        };
+    }
+    async runV3HealthCheck(options = {}) {
+        await this.ensureV3ServiceKey();
+        const endpoints = this.getV3AgentBaseUrls(false);
+        const headers = await this.getV3AgentHeaders();
+        const perEndpointTimeoutMs = 8000;
+        const probe = async (baseUrl) => {
+            const runUrl = this.getV3AgentRunUrl(baseUrl);
+            const healthUrl = /127\.0\.0\.1:8030|localhost:8030/.test(baseUrl)
+                ? `${baseUrl}/health`
+                : `${baseUrl}/api/v3-agent/health`;
+            try {
+                const response = await fetch(healthUrl, {
+                    method: 'GET',
+                    headers,
+                    signal: AbortSignal.timeout(perEndpointTimeoutMs),
+                });
+                if (response.status === 401 || response.status === 403) {
+                    return {
+                        healthy: false,
+                        endpoint: runUrl,
+                        error: 'V3 service rejected authentication. Run: vigthoria login',
+                    };
+                }
+                if (response.ok || response.status === 405) {
+                    return { healthy: true, endpoint: runUrl };
+                }
+                if (response.status === 502 || response.status === 503 || response.status === 504) {
+                    return {
+                        healthy: false,
+                        endpoint: runUrl,
+                        error: `V3 agent proxy returned ${response.status}. The V3 Code Agent service may be restarting or overloaded.`,
+                    };
+                }
+                return {
+                    healthy: false,
+                    endpoint: runUrl,
+                    error: `V3 agent health returned ${response.status}`,
+                };
+            }
+            catch (error) {
+                const reason = error?.message || String(error);
+                if (/timeout|aborted|timed out/i.test(reason)) {
+                    return {
+                        healthy: false,
+                        endpoint: runUrl,
+                        error: options.soft
+                            ? 'V3 health probe timed out; continuing with agent stream.'
+                            : 'V3 agent health check timed out. The service may be busy with another run or temporarily overloaded.',
+                    };
+                }
+                return {
+                    healthy: false,
+                    endpoint: runUrl,
+                    error: reason,
+                };
+            }
+        };
+        const results = await Promise.all(endpoints.map((baseUrl) => probe(baseUrl)));
+        const healthy = results.find((entry) => entry.healthy);
+        if (healthy) {
+            return healthy;
+        }
+        const timedOut = results.find((entry) => /timed out/i.test(entry.error || ''));
+        if (timedOut) {
+            return timedOut;
+        }
+        return results[0] || {
+            healthy: false,
+            endpoint: this.getV3AgentRunUrl(endpoints[0] || 'https://coder.vigthoria.io'),
+            error: 'V3 agent service is not responding.',
+        };
+    }
+    resolveChatConnectTimeoutMs(options = {}) {
+        if (options.connectTimeoutMs && options.connectTimeoutMs > 0) {
+            return options.connectTimeoutMs;
+        }
+        if (options.timeoutMs && options.timeoutMs > 0 && options.timeoutMs <= 60000) {
+            return options.timeoutMs;
+        }
+        return DEFAULT_CHAT_CONNECT_TIMEOUT_MS;
+    }
+    resolveChatIdleTimeoutMs(options = {}) {
+        if (options.idleTimeoutMs && options.idleTimeoutMs > 0) {
+            return options.idleTimeoutMs;
+        }
+        if (options.timeoutMs && options.timeoutMs > 60000) {
+            return options.timeoutMs;
+        }
+        return DEFAULT_CHAT_IDLE_TIMEOUT_MS;
+    }
+    mapPreflightEndpointToRoute(endpoint) {
+        const normalized = String(endpoint || '').toLowerCase();
+        if (normalized.includes('coder'))
+            return 'coder';
+        if (normalized.includes('models'))
+            return 'models';
+        if (normalized.includes('dedicated') || normalized.includes('self-hosted') || normalized.includes('selfhosted')) {
+            return 'selfhosted';
+        }
+        return null;
+    }
+    isCanonicalCoderDuplicate() {
+        const apiUrl = String(this.config.get('apiUrl') || '').replace(/\/$/, '').toLowerCase();
+        return apiUrl === 'https://coder.vigthoria.io';
+    }
+    async consumeOpenAIStreamResponse(response, idleTimeoutMs, onDelta) {
+        if (!response.body) {
+            throw new Error('Streaming response had no body');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let content = '';
+        let lastActivity = Date.now();
+        const waitForChunk = async () => {
+            const remainingIdle = idleTimeoutMs - (Date.now() - lastActivity);
+            if (idleTimeoutMs > 0 && remainingIdle <= 0) {
+                throw new Error('Model stream stalled (no output)');
+            }
+            const readPromise = reader.read();
+            if (idleTimeoutMs <= 0) {
+                return readPromise;
+            }
+            return Promise.race([
+                readPromise,
+                new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error('Model stream stalled (no output)')), Math.max(1000, remainingIdle));
+                }),
+            ]);
+        };
+        while (true) {
+            const { done, value } = await waitForChunk();
+            if (done) {
+                break;
+            }
+            lastActivity = Date.now();
+            buffer += decoder.decode(value, { stream: true });
+            const frames = buffer.split(/\r?\n\r?\n/);
+            buffer = frames.pop() || '';
+            for (const frame of frames) {
+                const dataLines = frame
+                    .split(/\r?\n/)
+                    .filter((line) => line.startsWith('data:'))
+                    .map((line) => line.slice(5).trimStart());
+                const payload = dataLines.join('\n').trim();
+                if (!payload || payload === '[DONE]') {
+                    continue;
+                }
+                try {
+                    const parsed = JSON.parse(payload);
+                    const delta = parsed?.choices?.[0]?.delta?.content
+                        || parsed?.choices?.[0]?.message?.content
+                        || parsed?.choices?.[0]?.text
+                        || '';
+                    if (typeof delta === 'string' && delta) {
+                        content += delta;
+                        onDelta?.(delta);
+                        lastActivity = Date.now();
+                    }
+                }
+                catch {
+                    // Ignore malformed stream frames.
+                }
+            }
+        }
+        return content.trim();
+    }
+    async tryStreamingModelRouterChat(baseURL, messages, resolvedModel, requestedModel, headers, options) {
+        const connectTimeoutMs = this.resolveChatConnectTimeoutMs(options);
+        const idleTimeoutMs = this.resolveChatIdleTimeoutMs(options);
+        const controller = new AbortController();
+        const connectTimer = setTimeout(() => controller.abort(), connectTimeoutMs);
+        try {
+            const response = await fetch(`${baseURL.replace(/\/$/, '')}/v1/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers,
+                },
+                body: JSON.stringify({
+                    model: resolvedModel,
+                    messages,
+                    max_tokens: this.config.get('preferences').maxTokens,
+                    temperature: 0.7,
+                    stream: true,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return null;
+            }
+            clearTimeout(connectTimer);
+            const content = await this.consumeOpenAIStreamResponse(response, idleTimeoutMs, options.onStreamDelta);
+            if (!content) {
+                return null;
+            }
+            return {
+                id: `vigthoria-stream-${Date.now()}`,
+                message: content,
+                model: resolvedModel || requestedModel,
+            };
+        }
+        catch (error) {
+            clearTimeout(connectTimer);
+            throw error;
+        }
+    }
+    async runV3AgentAuthPreflight(baseUrl, body, executionContext) {
+        const endpoint = this.getV3AgentRunUrl(baseUrl);
+        const healthEndpoint = /127\.0\.0\.1:8030|localhost:8030/.test(baseUrl)
+            ? `${baseUrl}/health`
+            : `${baseUrl}/api/v3-agent/health`;
+        const headers = await this.getV3AgentHeaders();
+        headers['X-Vigthoria-Preflight'] = '1';
+        if (executionContext.mcpContextId) {
+            headers['X-MCP-Context-Id'] = String(executionContext.mcpContextId);
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 12000);
+        try {
+            const response = await fetch(healthEndpoint, {
+                method: 'GET',
+                headers,
+                signal: controller.signal,
+            });
+            if (response.status === 401 || response.status === 403) {
+                const errorText = await response.text().catch(() => '');
+                return {
+                    ok: false,
+                    status: response.status,
+                    endpoint: healthEndpoint,
+                    reason: sanitizeUserFacingErrorText(errorText).slice(0, 200) || 'Unauthorized',
+                };
+            }
+            // Any non-auth response means token acceptance passed at the V3 service layer.
+            return { ok: true, status: response.status, endpoint: healthEndpoint };
+        }
+        catch (error) {
+            const reason = sanitizeUserFacingErrorText(error?.message || String(error)).slice(0, 200);
+            // Preflight should not block agent execution on transient timeout/abort network conditions.
+            if (/aborted|timeout|timed out|network/i.test(reason)) {
+                return {
+                    ok: true,
+                    status: 0,
+                    endpoint: healthEndpoint,
+                    reason,
+                };
+            }
+            return {
+                ok: false,
+                status: 0,
+                endpoint: healthEndpoint,
+                reason,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     async executeV3AgentRunRequest(baseUrl, body, executionContext, signal) {
         const makeRequest = async () => {
             const headers = await this.getV3AgentHeaders();
@@ -1262,7 +1667,8 @@ export class APIClient {
         const targetPath = resolvedContext.targetPath || resolvedContext.projectPath || resolvedContext.workspacePath || resolvedContext.projectRoot || process.cwd();
         const localWorkspacePath = this.resolveAgentTargetPath(resolvedContext);
         const serverWorkspacePath = this.resolveServerBindableWorkspacePath(resolvedContext);
-        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath);
+        const prompt = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || '').trim();
+        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, { prompt });
         const requestedModel = String(resolvedContext.model || resolvedContext.requestedModel || 'agent');
         const resolvedModel = this.resolvePermittedModelId(requestedModel);
         const localWorkspaceName = localWorkspacePath ? path.basename(localWorkspacePath) : null;
@@ -1314,6 +1720,46 @@ export class APIClient {
             requestStartedAt: resolvedContext.requestStartedAt,
             subscriptionPlan: this.config.getNormalizedPlan() || null,
             email: this.config.get('email') || null,
+            rawPrompt: prompt || null,
+            promptFocusTerms: prompt ? this.extractPromptFocusTerms(prompt) : [],
+            vigthoriaBrain: resolvedContext.vigthoriaBrain
+                ? this.trimVigthoriaBrainForTransport(resolvedContext.vigthoriaBrain)
+                : null,
+            clientToolExecution: resolvedContext.clientToolExecution === true
+                || (resolvedContext.localMachineCapable !== false
+                    && (resolvedContext.executionSurface === 'cli' || resolvedContext.clientSurface === 'cli')
+                    && !!localWorkspacePath
+                    && !serverWorkspacePath),
+            clientToolPathRules: (resolvedContext.clientToolExecution === true || (resolvedContext.localMachineCapable !== false
+                && (resolvedContext.executionSurface === 'cli' || resolvedContext.clientSurface === 'cli')
+                && !!localWorkspacePath
+                && !serverWorkspacePath))
+                ? [
+                    'Client-side read tools execute on the user real machine via the CLI.',
+                    'Use paths relative to the workspace root only.',
+                    'Never prefix tool paths with workspace/ or vigthoria://workspace/.',
+                    `The workspace root folder name is "${localWorkspaceName || 'project'}". Do not repeat it in paths.`,
+                    'Examples: ".", "Vigthoria-dominion/README.md", "vigthoria-dominion-win/".',
+                ].join(' ')
+                : null,
+            executionHints: {
+                ...(resolvedContext.agentTaskType === 'analysis'
+                    ? {
+                        max_iterations: Number.parseInt(process.env.VIGTHORIA_ANALYSIS_MAX_ITERATIONS || '15', 10) || 15,
+                        analysis_guidance: this.buildAnalysisGuidance(Array.isArray(localWorkspaceSummary?.promptFocusDirectories)
+                            ? localWorkspaceSummary.promptFocusDirectories
+                            : [], Array.isArray(localWorkspaceSummary?.mandatoryReadPaths)
+                            ? localWorkspaceSummary.mandatoryReadPaths
+                            : []),
+                    }
+                    : {}),
+                ...(['implementation', 'game-build', 'web-build', 'build', 'fix'].includes(String(resolvedContext.agentTaskType || '').toLowerCase())
+                    ? {
+                        requires_file_changes: true,
+                        task_kind: String(resolvedContext.agentTaskType || 'implementation').toLowerCase(),
+                    }
+                    : {}),
+            },
         };
         return this.compactV3Context(payload);
     }
@@ -1341,9 +1787,15 @@ export class APIClient {
             const overhead = json.length - JSON.stringify(summary.workspaceFiles).length;
             const budget = LIMIT - overhead - 512; // reserve a little headroom
             if (budget > 0) {
+                const focusTerms = Array.isArray(payload.promptFocusTerms) ? payload.promptFocusTerms : [];
+                const focusDirectories = Array.isArray(payload.localWorkspaceSummary?.promptFocusDirectories)
+                    ? payload.localWorkspaceSummary.promptFocusDirectories
+                    : [];
+                const sortedEntries = [...fileEntries].sort((a, b) => this.scoreWorkspacePathForHydration(b[0], focusTerms, focusDirectories)
+                    - this.scoreWorkspacePathForHydration(a[0], focusTerms, focusDirectories));
                 const trimmed = {};
                 let used = 2; // {}
-                for (const [k, v] of fileEntries) {
+                for (const [k, v] of sortedEntries) {
                     const entryLen = JSON.stringify(k).length + 1 + JSON.stringify(v).length + 1;
                     if (used + entryLen > budget)
                         break;
@@ -1909,7 +2361,8 @@ menu {
         const headers = await this.getMcpHeaders();
         const localWorkspacePath = this.resolveAgentTargetPath(executionContext);
         const workspacePath = this.resolveServerBindableWorkspacePath(executionContext);
-        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath);
+        const prompt = String(executionContext.rawPrompt || executionContext.contextualPrompt || '').trim();
+        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, { prompt });
         const metadata = {
             source: 'vigthoria-cli',
             sharedContextId: executionContext.contextId,
@@ -1945,6 +2398,7 @@ menu {
                 method: 'PUT',
                 headers,
                 body: JSON.stringify({ data }),
+                signal: AbortSignal.timeout(DEFAULT_MCP_BIND_TIMEOUT_MS),
             });
             if (!response.ok) {
                 const errorText = await response.text().catch(() => '');
@@ -1976,6 +2430,7 @@ menu {
                         userId: this.config.get('userId') || this.config.get('email') || 'vigthoria-cli',
                         metadata,
                     }),
+                    signal: AbortSignal.timeout(DEFAULT_MCP_BIND_TIMEOUT_MS),
                 });
                 if (!createResponse.ok) {
                     const errorText = await createResponse.text().catch(() => '');
@@ -2050,6 +2505,7 @@ menu {
         }
         const localName = paths.localWorkspacePath ? path.basename(paths.localWorkspacePath) : null;
         const serverBindableWorkspace = !!paths.serverWorkspacePath || runtime.serverBindableWorkspace === true;
+        const isLocalMachine = !serverBindableWorkspace;
         return {
             osPlatform: runtime.osPlatform || null,
             platform: runtime.platform || null,
@@ -2060,17 +2516,273 @@ menu {
             workspaceName: localName,
             workspacePath: serverBindableWorkspace ? paths.serverWorkspacePath || null : (localName ? `vigthoria://local-workspace/${localName}` : null),
             cwd: serverBindableWorkspace ? paths.serverWorkspacePath || null : (localName ? `vigthoria://local-workspace/${localName}` : null),
+            localExecutionRequired: isLocalMachine,
+            toolExecutionSurface: isLocalMachine ? 'cli-local' : 'server-workspace',
+            executionGuidance: isLocalMachine
+                ? 'The user runs Vigthoria CLI on their local machine. Real files and folders live on the client filesystem. Server workspace tools only see a partial hydrated copy — read `.vigthoria-workspace-index.md` and `promptFocusDirectories` before guessing root-level README.md. Prefer localWorkspaceSummary for structure and tell the user when live local tool execution is required.'
+                : null,
+        };
+    }
+    extractPromptFocusTerms(prompt) {
+        const terms = new Set();
+        const normalized = String(prompt || '').trim();
+        if (!normalized) {
+            return [];
+        }
+        for (const match of normalized.matchAll(/["'`]([^"'`]{2,120})["'`]/g)) {
+            terms.add(match[1].trim());
+        }
+        for (const match of normalized.matchAll(/(?:project|game|folder|directory|path|repo(?:sitory)?)\s+([A-Za-z0-9][\w ._-]{2,80})/gi)) {
+            terms.add(match[1].trim());
+        }
+        for (const match of normalized.matchAll(/(?:investigate|find|explore|look at|check|inspect|analyse|analyze)\s+(?:the\s+)?([A-Za-z0-9][\w ._-]{2,80}?)(?:\s+(?:folder|directory|foulder|dir|project|game))?\b/gi)) {
+            terms.add(match[1].trim());
+        }
+        for (const match of normalized.matchAll(/\b([A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+)+)\b/g)) {
+            const phrase = match[1].trim();
+            if (phrase.length <= 48) {
+                terms.add(phrase);
+            }
+        }
+        for (const match of normalized.matchAll(/\/([\w .-]{2,80})/g)) {
+            const segment = match[1].trim();
+            if (!/^(users|home|desktop|documents|var|www|c)$/i.test(segment)) {
+                terms.add(segment);
+            }
+        }
+        return [...terms].filter((term) => term.length >= 3 && term.length <= 48).slice(0, 8);
+    }
+    buildTopLevelWorkspaceLayout(rootPath) {
+        const skipDirs = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '.cache', '__pycache__', '.venv', 'venv']);
+        const layout = { directories: [], files: [] };
+        try {
+            for (const entry of fs.readdirSync(rootPath, { withFileTypes: true })) {
+                if (entry.name.startsWith('.')) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    if (!skipDirs.has(entry.name)) {
+                        layout.directories.push(entry.name);
+                    }
+                }
+                else if (entry.isFile()) {
+                    layout.files.push(entry.name);
+                }
+            }
+        }
+        catch {
+            return layout;
+        }
+        layout.directories.sort((a, b) => a.localeCompare(b));
+        layout.files.sort((a, b) => a.localeCompare(b));
+        return layout;
+    }
+    normalizeFocusPathKey(value) {
+        return String(value || '').toLowerCase().replace(/[\s_./\\-]+/g, '');
+    }
+    resolvePromptFocusDirectories(rootPath, focusTerms) {
+        const layout = this.buildTopLevelWorkspaceLayout(rootPath);
+        const matches = new Set();
+        const normalizedTerms = focusTerms.map((term) => term.toLowerCase());
+        const normalizedTermKeys = focusTerms.map((term) => this.normalizeFocusPathKey(term));
+        for (const dir of layout.directories) {
+            const dirLower = dir.toLowerCase();
+            const dirKey = this.normalizeFocusPathKey(dir);
+            for (let index = 0; index < normalizedTerms.length; index += 1) {
+                const term = normalizedTerms[index];
+                const termKey = normalizedTermKeys[index];
+                if (dirLower === term
+                    || dirLower.includes(term)
+                    || term.includes(dirLower)
+                    || (termKey && (dirKey === termKey || dirKey.includes(termKey) || termKey.includes(dirKey)))) {
+                    matches.add(`${dir.replace(/\\/g, '/')}/`);
+                }
+            }
+        }
+        for (const term of focusTerms) {
+            const candidate = path.join(rootPath, term);
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+                matches.add(`${term.replace(/\\/g, '/')}/`);
+            }
+        }
+        return [...matches];
+    }
+    buildMandatoryFocusReadPaths(rootPath, focusDirectories) {
+        const candidates = [];
+        const pushIfExists = (relativePath) => {
+            const normalized = relativePath.replace(/\\/g, '/');
+            const absolutePath = path.join(rootPath, normalized);
+            if (fs.existsSync(absolutePath)) {
+                candidates.push(normalized);
+            }
         };
+        for (const focusDir of focusDirectories) {
+            const base = focusDir.replace(/\\/g, '/').replace(/\/$/, '');
+            pushIfExists(`${base}/package.json`);
+            pushIfExists(`${base}/game.js`);
+            pushIfExists(`${base}/src/Game.js`);
+            pushIfExists(`${base}/src/factions/FactionModels.js`);
+            pushIfExists(`${base}/GAME_DESIGN_DOCUMENT.md`);
+        }
+        const layout = this.buildTopLevelWorkspaceLayout(rootPath);
+        for (const dir of layout.directories) {
+            if (/dominion/i.test(dir) && /-win|desktop|electron/i.test(dir)) {
+                pushIfExists(`${dir.replace(/\\/g, '/')}/`);
+            }
+        }
+        return [...new Set(candidates)];
+    }
+    buildAnalysisGuidance(focusDirectories, mandatoryReadPaths) {
+        const focusLabel = focusDirectories.length > 0
+            ? focusDirectories.map((entry) => entry.replace(/\/$/, '')).join(', ')
+            : 'the requested project folder';
+        const reads = mandatoryReadPaths.length > 0
+            ? mandatoryReadPaths.slice(0, 12).map((entry) => `- \`${entry}\``).join('\n')
+            : '- package.json\n- game.js\n- src/Game.js\n- src/factions/\n- GAME_DESIGN_DOCUMENT.md';
+        return [
+            `The user asked for a grounded overview of ${focusLabel}.`,
+            'Do NOT summarize from root README.md, PRODUCTION_ROADMAP.md, or PROJECT_STATUS_REPORT.md alone — they may be stale or AI-generated.',
+            'Read these code-first paths before writing your final answer:',
+            reads,
+            'MANDATORY: Compare README claims against package.json, game.js, and src/. If they disagree, your final answer MUST:',
+            '1) State what the game actually is based on code,',
+            '2) Quote what README incorrectly claims,',
+            '3) Explicitly say "README is inconsistent with the codebase" and recommend fixing it.',
+            'List `vigthoria-dominion-win/` (or similar) if present to confirm desktop/Electron distribution.',
+        ].join('\n');
+    }
+    collectFocusDirectoryFilePaths(rootPath, focusDirRelative, maxFiles = 250) {
+        const focusRoot = path.join(rootPath, focusDirRelative);
+        if (!fs.existsSync(focusRoot)) {
+            return [];
+        }
+        const skipDirs = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '.cache', '__pycache__', '.venv', 'venv']);
+        const results = [];
+        const stack = [{ abs: focusRoot, rel: focusDirRelative.replace(/\\/g, '/') }];
+        while (stack.length > 0 && results.length < maxFiles) {
+            const current = stack.pop();
+            if (!current) {
+                continue;
+            }
+            let entries;
+            try {
+                entries = fs.readdirSync(current.abs, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (results.length >= maxFiles) {
+                    break;
+                }
+                const rel = `${current.rel}${current.rel.endsWith('/') ? '' : '/'}${entry.name}`.replace(/\\/g, '/');
+                const abs = path.join(current.abs, entry.name);
+                if (entry.isDirectory()) {
+                    if (!skipDirs.has(entry.name) && !entry.name.startsWith('.')) {
+                        stack.push({ abs, rel: `${rel}/` });
+                    }
+                }
+                else if (entry.isFile()) {
+                    results.push(rel);
+                }
+            }
+        }
+        return results;
+    }
+    mergeWorkspacePathCandidates(primary, extras) {
+        const seen = new Set();
+        const merged = [];
+        for (const candidate of [...extras, ...primary]) {
+            const normalized = candidate.replace(/\\/g, '/');
+            if (!normalized || seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            merged.push(normalized);
+        }
+        return merged;
+    }
+    scoreWorkspacePathForHydration(filePath, focusTerms, focusDirectories = []) {
+        const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+        let score = 0;
+        if (normalized === '.vigthoria-workspace-index.md') {
+            score += 1000;
+        }
+        if (normalized.endsWith('package.json')) {
+            score += 360;
+        }
+        if (/(^|\/)game\.js$/i.test(normalized) || /\/src\/game\.js$/i.test(normalized)) {
+            score += 350;
+        }
+        if (/\/src\/factions\//i.test(normalized) || /factionmodels\.js/i.test(normalized)) {
+            score += 340;
+        }
+        if (/game_design_document\.md/i.test(normalized)) {
+            score += 320;
+        }
+        if (normalized.endsWith('readme.md')) {
+            score += focusDirectories.some((dir) => normalized.startsWith(dir.toLowerCase())) ? 120 : 40;
+        }
+        if (/production_roadmap|project_status_report|status_report|roadmap\.md/i.test(normalized)) {
+            score += 20;
+        }
+        if (/\.(js|ts|tsx|jsx|mjs|cjs)$/i.test(normalized)) {
+            score += 100;
+        }
+        if (/\.(md|txt|json|yaml|yml|toml)$/i.test(normalized)) {
+            score += 40;
+        }
+        for (const dir of focusDirectories.map((entry) => entry.toLowerCase())) {
+            if (normalized.startsWith(dir)) {
+                score += 250;
+            }
+        }
+        for (const term of focusTerms) {
+            const termLower = term.toLowerCase();
+            const termKey = this.normalizeFocusPathKey(term);
+            if (normalized.includes(termLower) || (termKey && normalized.replace(/[\s_./\\-]+/g, '').includes(termKey))) {
+                score += 80;
+            }
+        }
+        return score;
+    }
+    sortWorkspacePathsForHydration(filePaths, focusTerms, focusDirectories) {
+        return [...filePaths].sort((a, b) => this.scoreWorkspacePathForHydration(b, focusTerms, focusDirectories)
+            - this.scoreWorkspacePathForHydration(a, focusTerms, focusDirectories));
+    }
+    trimVigthoriaBrainForTransport(brain, maxChars = 12000) {
+        try {
+            const serialized = typeof brain === 'string' ? brain : JSON.stringify(brain);
+            if (serialized.length <= maxChars) {
+                return typeof brain === 'string' ? brain : JSON.parse(serialized);
+            }
+            return {
+                truncated: true,
+                excerpt: serialized.slice(0, maxChars),
+            };
+        }
+        catch {
+            return null;
+        }
     }
-    buildLocalWorkspaceSummary(rootPath) {
+    buildLocalWorkspaceSummary(rootPath, options = {}) {
         if (!rootPath || !fs.existsSync(rootPath)) {
             return null;
         }
         try {
+            const prompt = String(options.prompt || '').trim();
+            const focusTerms = prompt ? this.extractPromptFocusTerms(prompt) : [];
+            const topLevelLayout = this.buildTopLevelWorkspaceLayout(rootPath);
+            const focusDirectories = this.resolvePromptFocusDirectories(rootPath, focusTerms);
+            const mandatoryReadPaths = this.buildMandatoryFocusReadPaths(rootPath, focusDirectories);
             const summary = {
                 path: 'vigthoria://workspace/',
                 name: path.basename(rootPath),
                 files: [],
+                topLevelLayout,
+                promptFocusTerms: focusTerms,
+                promptFocusDirectories: focusDirectories,
+                mandatoryReadPaths,
             };
             const snapshot = this.getAgentWorkspaceSnapshot(rootPath);
             summary.fileCount = snapshot.fileCount;
@@ -2087,12 +2799,34 @@ menu {
                 };
             }
             const readmePath = path.join(rootPath, 'README.md');
-            if (fs.existsSync(readmePath)) {
+            if (focusDirectories.length === 0 && fs.existsSync(readmePath)) {
                 summary.readmeExcerpt = fs.readFileSync(readmePath, 'utf8').slice(0, 2500);
             }
+            else if (focusDirectories.length > 0) {
+                summary.readmeWarning = 'Root README and planning docs are often stale or agent-generated. Prefer package.json, game.js, src/, and GAME_DESIGN_DOCUMENT.md inside the focus folder.';
+            }
+            for (const focusDir of focusDirectories) {
+                const focusReadme = path.join(rootPath, focusDir, 'README.md');
+                if (fs.existsSync(focusReadme)) {
+                    summary.focusReadmeWarning = summary.focusReadmeWarning || {};
+                    summary.focusReadmeWarning[`${focusDir}README.md`.replace(/\\/g, '/')] =
+                        'Subfolder README may be stale or wrong. Prefer package.json, game.js, src/, and GAME_DESIGN_DOCUMENT.md.';
+                }
+            }
+            const focusPaths = [
+                ...mandatoryReadPaths,
+                ...focusDirectories.flatMap((focusDir) => this.collectFocusDirectoryFilePaths(rootPath, focusDir)),
+            ];
+            const hydrationPaths = this.sortWorkspacePathsForHydration(this.mergeWorkspacePathCandidates(snapshot.paths, focusPaths), focusTerms, focusDirectories);
             // Hydrate workspace: include actual file contents so the V3 server
             // can populate the remote workspace before the agent starts.
-            summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, snapshot.paths);
+            summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, hydrationPaths);
+            summary.workspaceFiles['.vigthoria-workspace-index.md'] = this.buildWorkspaceIndexFile(rootPath, snapshot, {
+                focusTerms,
+                focusDirectories,
+                topLevelLayout,
+                mandatoryReadPaths,
+            });
             return summary;
         }
         catch (error) {
@@ -2100,6 +2834,61 @@ menu {
             return null;
         }
     }
+    buildWorkspaceIndexFile(rootPath, snapshot, options = {}) {
+        const workspaceName = path.basename(rootPath);
+        const listedPaths = snapshot.paths.slice(0, 1800);
+        const focusTerms = options.focusTerms || [];
+        const focusDirectories = options.focusDirectories || [];
+        const mandatoryReadPaths = options.mandatoryReadPaths || [];
+        const topLevelLayout = options.topLevelLayout || this.buildTopLevelWorkspaceLayout(rootPath);
+        const lines = [
+            '# Vigthoria Local Workspace Index',
+            '',
+            'This file is generated by the Vigthoria CLI so the remote V3 agent can search and understand the local workspace layout without seeing private machine paths.',
+            'Read this file before guessing paths like README.md at the workspace root.',
+            'README.md, PRODUCTION_ROADMAP.md, and PROJECT_STATUS_REPORT.md may be stale or AI-generated. Trust package.json, game.js, src/, and GAME_DESIGN_DOCUMENT.md instead.',
+            '',
+            '## Path rules for client-side tools',
+            '- The workspace root is already bound to the user folder below.',
+            '- Use relative paths from that root: `.`, `Vigthoria-dominion/`, `README.md`.',
+            '- NEVER prefix paths with `workspace/` — that alias does not exist on the user machine.',
+            '- Do NOT repeat the workspace folder name in paths.',
+            '',
+            `Workspace name: ${workspaceName}`,
+            `Indexed files: ${snapshot.fileCount}`,
+            '',
+            '## Top-level layout',
+            ...(topLevelLayout.directories.length > 0
+                ? topLevelLayout.directories.map((dir) => `- ${dir}/`)
+                : ['- (no subdirectories listed)']),
+            ...(topLevelLayout.files.length > 0
+                ? ['', '## Top-level files', ...topLevelLayout.files.map((file) => `- ${file}`)]
+                : []),
+        ];
+        if (focusTerms.length > 0 || focusDirectories.length > 0) {
+            lines.push('', '## Prompt focus');
+            if (focusTerms.length > 0) {
+                lines.push(`User focus terms: ${focusTerms.join(', ')}`);
+            }
+            if (focusDirectories.length > 0) {
+                lines.push('Likely project folders:');
+                for (const focusDir of focusDirectories) {
+                    lines.push(`- ${focusDir}`);
+                }
+            }
+            if (mandatoryReadPaths.length > 0) {
+                lines.push('', '## Mandatory code-first reads (before summarizing)');
+                for (const readPath of mandatoryReadPaths.slice(0, 12)) {
+                    lines.push(`- ${readPath}`);
+                }
+            }
+        }
+        lines.push('', '## Files', ...listedPaths.map((filePath) => `- ${filePath.replace(/\\/g, '/')}`));
+        if (snapshot.fileCount > listedPaths.length) {
+            lines.push('', `Index truncated: ${snapshot.fileCount - listedPaths.length} additional files were not listed.`);
+        }
+        return `${lines.join('\n')}\n`;
+    }
     /**
      * Collect text file contents from the workspace for V3 agent hydration.
      * Budget: up to ~2 MB total, per-file cap 200 KB, skip binary extensions.
@@ -2152,14 +2941,24 @@ menu {
             if (!root || !fs.existsSync(root)) {
                 return false;
             }
+            const skipDirs = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '.cache', '__pycache__', '.venv', 'venv']);
+            const startedAt = Date.now();
             const stack = [root];
+            let scannedDirs = 0;
             while (stack.length > 0) {
+                if (Date.now() - startedAt > DEFAULT_WORKSPACE_SCAN_TIMEOUT_MS) {
+                    return false;
+                }
                 const current = stack.pop();
                 if (!current)
                     continue;
+                scannedDirs += 1;
+                if (scannedDirs > DEFAULT_WORKSPACE_SCAN_MAX_FILES) {
+                    return false;
+                }
                 const entries = fs.readdirSync(current, { withFileTypes: true });
                 for (const entry of entries) {
-                    if (entry.name === '.git' || entry.name === 'node_modules') {
+                    if (skipDirs.has(entry.name)) {
                         continue;
                     }
                     const fullPath = path.join(current, entry.name);
@@ -2178,16 +2977,24 @@ menu {
         return false;
     }
     getAgentWorkspaceSnapshot(rootPath) {
+        const skipDirs = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '.cache', '__pycache__', '.venv', 'venv']);
         const stack = [rootPath];
+        const startedAt = Date.now();
         let fileCount = 0;
         const entries = [];
         while (stack.length > 0) {
+            if (Date.now() - startedAt > DEFAULT_WORKSPACE_SCAN_TIMEOUT_MS) {
+                break;
+            }
+            if (entries.length >= DEFAULT_WORKSPACE_SCAN_MAX_FILES) {
+                break;
+            }
             const current = stack.pop();
             if (!current) {
                 continue;
             }
             for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-                if (entry.name === '.git' || entry.name === 'node_modules') {
+                if (skipDirs.has(entry.name)) {
                     continue;
                 }
                 const fullPath = path.join(current, entry.name);
@@ -2201,6 +3008,9 @@ menu {
                 fileCount += 1;
                 const stat = fs.statSync(fullPath);
                 entries.push(`${path.relative(rootPath, fullPath)}:${stat.size}:${stat.mtimeMs}`);
+                if (entries.length >= DEFAULT_WORKSPACE_SCAN_MAX_FILES) {
+                    break;
+                }
             }
         }
         entries.sort();
@@ -2843,14 +3653,14 @@ document.addEventListener('DOMContentLoaded', () => {
         if (typeof result === 'string') {
             return sanitizeUserFacingPathText(result);
         }
-        if (typeof result?.summary === 'string' && result.summary.trim()) {
+        if (typeof result?.summary === 'string' && result.summary.trim() && !this.isGenericV3AgentSummary(result.summary)) {
             return sanitizeUserFacingPathText(result.summary);
         }
-        if (typeof result?.message === 'string' && result.message.trim()) {
+        if (typeof result?.message === 'string' && result.message.trim() && !this.isGenericV3AgentSummary(result.message)) {
             return sanitizeUserFacingPathText(result.message);
         }
         if (Array.isArray(data?.events)) {
-            const completionEvent = [...data.events].reverse().find((event) => event && event.type === 'complete' && typeof event.summary === 'string' && event.summary.trim());
+            const completionEvent = [...data.events].reverse().find((event) => event && event.type === 'complete' && typeof event.summary === 'string' && event.summary.trim() && !this.isGenericV3AgentSummary(event.summary));
             if (completionEvent) {
                 return sanitizeUserFacingPathText(completionEvent.summary);
             }
@@ -2860,77 +3670,463 @@ document.addEventListener('DOMContentLoaded', () => {
             }
             // Synthesize a grounded answer from the tool-call evidence the
             // agent produced, rather than dumping the raw event trace.
-            const answer = this.synthesizeAnswerFromV3Events(data.events);
+            const answer = this.synthesizeAnswerFromV3Events(data.events, data.liveToolEvidence);
             if (answer) {
                 return answer;
             }
         }
-        // Last resort: if data has files written, report them.
-        if (data?.files && typeof data.files === 'object' && Object.keys(data.files).length > 0) {
+        if (Array.isArray(data?.liveToolEvidence) && data.liveToolEvidence.length > 0) {
+            const answer = this.synthesizeAnswerFromV3Events([], data.liveToolEvidence);
+            if (answer) {
+                return answer;
+            }
+        }
+        // Last resort: if data has files written, report them.
+        if (data?.files && typeof data.files === 'object' && Object.keys(data.files).length > 0) {
             const fileList = Object.keys(data.files).join(', ');
             return `Agent wrote workspace files: ${sanitizeUserFacingPathText(fileList)}`;
         }
         const text = sanitizeUserFacingPathText(JSON.stringify(data, null, 2));
         return text.length > 12000 ? `${text.slice(0, 12000)}\n\n[V3 agent output truncated]` : text;
     }
+    isGenericV3AgentSummary(value) {
+        const text = String(value || '').trim();
+        if (!text)
+            return true;
+        return /^(task completed|v3 agent workflow completed\.?|agent run finished|workflow completed\.?|max iterations \(\d+\) reached after\b)/i.test(text);
+    }
+    isV3StreamStatusMessage(value) {
+        const text = String(value || '').trim();
+        if (!text)
+            return true;
+        return /^(the agent produced an in-progress note|continuing to finish cleanly|a previous tool call failed|max iterations \(\d+\) reached)/i.test(text)
+            || /pending blocker|not been resolved|instead of a final report/i.test(text);
+    }
+    scoreEvidenceFilePath(filePath) {
+        const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+        let score = 0;
+        if (normalized.endsWith('package.json'))
+            score += 100;
+        if (/(^|\/)game\.js$/i.test(normalized) || /\/src\/game\.js$/i.test(normalized))
+            score += 95;
+        if (/\/src\/factions\//i.test(normalized) || /factionmodels\.js/i.test(normalized))
+            score += 90;
+        if (/game_design_document\.md/i.test(normalized))
+            score += 85;
+        if (/\.(js|ts|tsx|jsx|mjs|cjs)$/i.test(normalized))
+            score += 70;
+        if (normalized.endsWith('index.html'))
+            score += 50;
+        if (/production_roadmap|project_status_report|status_report/i.test(normalized))
+            score += 5;
+        if (normalized.endsWith('readme.md'))
+            score += normalized.includes('vigthoria-dominion') ? 25 : 10;
+        return score;
+    }
+    isLowTrustDocPath(filePath) {
+        const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+        return normalized.endsWith('readme.md')
+            || /production_roadmap|project_status_report|status_report|roadmap\.md/i.test(normalized);
+    }
+    extractCodeSignalsFromEvidence(filesRead, liveToolEvidence = []) {
+        const signals = new Set();
+        const ingest = (filePath, excerpt) => {
+            const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+            const text = String(excerpt || '');
+            const lower = text.toLowerCase();
+            if (normalized.endsWith('package.json')) {
+                const match = text.match(/"description"\s*:\s*"([^"]+)"/i);
+                if (match?.[1])
+                    signals.add(`package.json: ${match[1]}`);
+                if (/rts|real-time strategy|command & conquer/i.test(text)) {
+                    signals.add('package.json identifies a real-time strategy game project.');
+                }
+            }
+            if (/(^|\/)game\.js$/i.test(normalized) || /\/src\/game\.js$/i.test(normalized)) {
+                if (/rts|real-time strategy|command & conquer|dune 2000|3d rts/i.test(lower)) {
+                    signals.add('game.js entry identifies a 3D RTS engine (Command & Conquer / Dune 2000 style).');
+                }
+            }
+            if (/\/src\/factions\//i.test(normalized) || /factionmodels\.js/i.test(normalized)) {
+                const factions = ['Iron Dominion', 'Nova Collective', 'Aqua Tide', 'Swarm Hive']
+                    .filter((name) => lower.includes(name.toLowerCase()));
+                if (factions.length >= 2) {
+                    signals.add(`Faction code references: ${factions.join(', ')} (4-faction RTS).`);
+                }
+            }
+            if (/vigthoria-dominion-win/i.test(normalized) || /dist-desktop|electron/i.test(lower)) {
+                signals.add('Desktop/Electron build artifacts are present (full desktop RTS distribution).');
+            }
+        };
+        for (const entry of filesRead)
+            ingest(entry.path, entry.excerpt);
+        for (const entry of liveToolEvidence) {
+            if (entry?.success === false)
+                continue;
+            ingest(String(entry.target || entry.arguments?.path || ''), String(entry.output || ''));
+        }
+        return [...signals];
+    }
+    classifyGameGenreFromText(text) {
+        const lower = String(text || '').toLowerCase();
+        if (/card game|deck-building|dominion is a deck|treasure cards?|victory points?|buy phase|action phase/i.test(lower)) {
+            return 'card/deck-building game';
+        }
+        if (/rts|real-time strategy|command & conquer|dune 2000|3d rts|build bases|gather resources|train units/i.test(lower)) {
+            return '3D real-time strategy (RTS) game';
+        }
+        if (/turn-based strategy|4x strategy/i.test(lower)) {
+            return 'turn-based strategy game';
+        }
+        if (/platformer|roguelike|puzzle game/i.test(lower)) {
+            const match = lower.match(/(platformer|roguelike|puzzle game)/i);
+            return match?.[1] || null;
+        }
+        return null;
+    }
+    extractReadmeGenreClaims(filesRead, liveToolEvidence = []) {
+        const claims = [];
+        const ingest = (filePath, excerpt) => {
+            const normalized = String(filePath || '').replace(/\\/g, '/');
+            if (!/readme\.md$/i.test(normalized))
+                return;
+            const genre = this.classifyGameGenreFromText(excerpt);
+            if (!genre)
+                return;
+            const lines = String(excerpt || '').split('\n').map((line) => line.trim()).filter(Boolean);
+            const quoteLine = lines.find((line) => /card game|deck|rts|real-time strategy|strategy game|browser game|3d/i.test(line))
+                || lines.slice(0, 6).join(' ');
+            claims.push({
+                path: normalized,
+                genre,
+                quote: quoteLine.slice(0, 220),
+            });
+        };
+        for (const entry of filesRead)
+            ingest(entry.path, entry.excerpt);
+        for (const entry of liveToolEvidence) {
+            if (entry?.success === false)
+                continue;
+            ingest(String(entry.target || entry.arguments?.path || ''), String(entry.output || ''));
+        }
+        return claims;
+    }
+    extractCodeGenreClaims(filesRead, liveToolEvidence = []) {
+        const sources = [];
+        const factions = new Set();
+        let genre = null;
+        const ingest = (filePath, excerpt) => {
+            const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+            const text = String(excerpt || '');
+            const detected = this.classifyGameGenreFromText(text);
+            const isCodeFile = normalized.endsWith('package.json')
+                || /(^|\/)game\.js$/i.test(normalized)
+                || /\/src\//i.test(normalized);
+            if (detected && isCodeFile) {
+                genre = genre || detected;
+                sources.push(normalized);
+            }
+            if (/\/src\/factions\//i.test(normalized) || /factionmodels\.js/i.test(normalized)) {
+                for (const name of ['Iron Dominion', 'Nova Collective', 'Aqua Tide', 'Swarm Hive']) {
+                    if (text.toLowerCase().includes(name.toLowerCase()))
+                        factions.add(name);
+                }
+            }
+        };
+        for (const entry of filesRead)
+            ingest(entry.path, entry.excerpt);
+        for (const entry of liveToolEvidence) {
+            if (entry?.success === false)
+                continue;
+            ingest(String(entry.target || entry.arguments?.path || ''), String(entry.output || ''));
+        }
+        return { genre, sources: [...new Set(sources)], factions: [...factions] };
+    }
+    buildReadmeCodeConsistencySection(filesRead, liveToolEvidence = []) {
+        const readmeClaims = this.extractReadmeGenreClaims(filesRead, liveToolEvidence);
+        const codeClaims = this.extractCodeGenreClaims(filesRead, liveToolEvidence);
+        if (readmeClaims.length === 0 && !codeClaims.genre) {
+            return null;
+        }
+        const lines = ['## README vs code — consistency check'];
+        if (codeClaims.genre) {
+            lines.push('', '**What the game actually is (from code):**');
+            lines.push(`- Genre: **${codeClaims.genre}**`);
+            if (codeClaims.factions.length >= 2) {
+                lines.push(`- Factions in source: ${codeClaims.factions.join(', ')}`);
+            }
+            if (codeClaims.sources.length > 0) {
+                lines.push(`- Evidence: ${codeClaims.sources.slice(0, 4).map((entry) => `\`${entry}\``).join(', ')}`);
+            }
+        }
+        else {
+            lines.push('', '**What the game actually is (from code):** _Not determined — core code files were not read yet._');
+        }
+        if (readmeClaims.length > 0) {
+            lines.push('', '**What README says:**');
+            for (const claim of readmeClaims.slice(0, 4)) {
+                lines.push(`- \`${claim.path}\` → **${claim.genre}**`);
+                if (claim.quote)
+                    lines.push(`  > "${claim.quote}"`);
+            }
+        }
+        const readmeGenres = new Set(readmeClaims.map((entry) => entry.genre));
+        const hasConflict = codeClaims.genre
+            && readmeClaims.some((entry) => entry.genre !== codeClaims.genre);
+        if (hasConflict && codeClaims.genre) {
+            lines.push('', '**Status: INCONSISTENT** — README documentation contradicts the codebase.', '', `The project code identifies this as a **${codeClaims.genre}**, but README describes it differently (${[...readmeGenres].join('; ')}).`, 'When reporting to the user, state the **code truth first**, then explicitly call out that README is wrong or stale and should be corrected.');
+        }
+        else if (codeClaims.genre && readmeClaims.length > 0) {
+            lines.push('', '**Status: CONSISTENT** — README and code agree on the project type.');
+        }
+        else if (readmeClaims.length > 0 && !codeClaims.genre) {
+            lines.push('', '**Status: UNVERIFIED** — README was read but core code was not inspected.', 'Do not present README claims as fact until package.json, game.js, and src/ are read.');
+        }
+        return lines.join('\n');
+    }
+    detectDocReliabilityWarnings(filesRead, liveToolEvidence = []) {
+        const warnings = [];
+        let subfolderCardGameReadme = false;
+        let codeSaysRts = false;
+        let readRootPlanningDocs = false;
+        let readCoreCode = false;
+        const inspect = (filePath, excerpt) => {
+            const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+            const lower = String(excerpt || '').toLowerCase();
+            if (/production_roadmap|project_status_report|status_report/i.test(normalized)) {
+                readRootPlanningDocs = true;
+            }
+            if (/vigthoria-dominion\/readme\.md$/i.test(normalized) && /card game|deck-building|dominion is a deck/i.test(lower)) {
+                subfolderCardGameReadme = true;
+            }
+            if (/readme\.md$/i.test(normalized) && /card game|deck-building|dominion is a deck/i.test(lower)) {
+                subfolderCardGameReadme = true;
+            }
+            if (/(^|\/)game\.js$/i.test(normalized) || /\/src\/game\.js$/i.test(normalized) || normalized.endsWith('package.json')) {
+                if (/rts|real-time strategy|command & conquer|3d rts/i.test(lower)) {
+                    codeSaysRts = true;
+                    readCoreCode = true;
+                }
+            }
+            if (/\/src\//i.test(normalized) && /\.(js|ts)$/i.test(normalized)) {
+                readCoreCode = true;
+            }
+        };
+        for (const entry of filesRead)
+            inspect(entry.path, entry.excerpt);
+        for (const entry of liveToolEvidence) {
+            if (entry?.success === false)
+                continue;
+            inspect(String(entry.target || entry.arguments?.path || ''), String(entry.output || ''));
+        }
+        if (subfolderCardGameReadme && codeSaysRts) {
+            warnings.push('README describes a card/deck-building game, but code (`game.js` / `package.json`) describes a 3D RTS. Report the RTS truth first, then tell the user README is inconsistent and should be fixed.');
+        }
+        if (readRootPlanningDocs && !readCoreCode) {
+            warnings.push('The agent read planning/status markdown at the workspace root but did not read core game code under `Vigthoria-dominion/src/` or `package.json`. Any genre/feature summary from those docs may be wrong.');
+        }
+        if (!readCoreCode) {
+            warnings.push('Core source files (`package.json`, entry `game.js`, and key files under `src/`) were not read. The overview may be incomplete until those files are inspected.');
+        }
+        return warnings;
+    }
     /**
      * Build a human-readable answer from the tool results in a V3 event
      * stream when the server didn't emit a proper complete/message event.
      */
-    synthesizeAnswerFromV3Events(events) {
+    synthesizeAnswerFromV3Events(events, liveToolEvidence = []) {
         const toolResults = [];
+        const failedPaths = [];
         const filesRead = [];
         const filesWritten = [];
+        const directoriesListed = [];
+        const searches = [];
         const assistantFragments = [];
+        const pendingToolCalls = [];
+        const ingestToolEvidence = (name, args, output, success) => {
+            const target = String(args.path || args.file_path || args.file || args.target || '').trim();
+            const cleanOutput = sanitizeUserFacingPathText(String(output || '').trim());
+            if (!success || !cleanOutput) {
+                if (!success && cleanOutput) {
+                    const failPath = target || name;
+                    failedPaths.push({
+                        path: sanitizeUserFacingPathText(failPath),
+                        detail: cleanOutput.split('\n').find(Boolean)?.slice(0, 160) || cleanOutput.slice(0, 160),
+                    });
+                    toolResults.push(`[${name}] ${cleanOutput.slice(0, 400)}`);
+                }
+                return;
+            }
+            if (name === 'read_file') {
+                const filePath = target || 'unknown file';
+                const excerpt = cleanOutput.length > 4000 ? `${cleanOutput.slice(0, 4000)}\n\n[...truncated...]` : cleanOutput;
+                filesRead.push({ path: sanitizeUserFacingPathText(filePath), excerpt });
+                return;
+            }
+            if (name === 'list_directory') {
+                const excerpt = cleanOutput.length > 1200 ? `${cleanOutput.slice(0, 1200)}\n[...truncated...]` : cleanOutput;
+                directoriesListed.push({ path: sanitizeUserFacingPathText(target || '.'), excerpt });
+                return;
+            }
+            if (name === 'search_files') {
+                const pattern = String(args.pattern || args.query || '').trim();
+                const searchPath = String(args.path || '.').trim();
+                searches.push(`${pattern || 'search'} in ${sanitizeUserFacingPathText(searchPath)}`);
+                if (cleanOutput.length > 0) {
+                    toolResults.push(`[search_files] ${cleanOutput.slice(0, 600)}`);
+                }
+                return;
+            }
+            if (name === 'write_file' || name === 'create_file' || name === 'edit_file') {
+                if (target)
+                    filesWritten.push(sanitizeUserFacingPathText(target));
+                return;
+            }
+            toolResults.push(`[${name}] ${cleanOutput.slice(0, 600)}`);
+        };
         for (const event of events) {
             if (!event)
                 continue;
-            if (event.type === 'tool_result' && event.success && typeof event.output === 'string') {
-                const name = event.name || 'unknown_tool';
-                if (name === 'read_file' && typeof event.target === 'string') {
-                    filesRead.push(sanitizeUserFacingPathText(event.target));
-                }
-                else if ((name === 'write_file' || name === 'create_file') && typeof event.target === 'string') {
-                    filesWritten.push(sanitizeUserFacingPathText(event.target));
-                }
-                else {
-                    // Keep last ~300 chars of output for context
-                    const excerpt = event.output.length > 300 ? event.output.slice(-300) : event.output;
-                    toolResults.push(`[${name}] ${sanitizeUserFacingPathText(excerpt)}`);
-                }
+            if (event.type === 'tool_call') {
+                pendingToolCalls.push({
+                    name: String(event.name || event.tool || 'unknown_tool'),
+                    args: event.arguments && typeof event.arguments === 'object' ? event.arguments : {},
+                });
+                continue;
+            }
+            if (event.type === 'tool_result') {
+                const success = event.success !== false;
+                const output = typeof event.output === 'string'
+                    ? event.output
+                    : typeof event.result === 'string'
+                        ? event.result
+                        : '';
+                const name = String(event.name || event.tool || 'unknown_tool');
+                const callIndex = pendingToolCalls.findIndex((call) => call.name === name);
+                const call = callIndex >= 0 ? pendingToolCalls.splice(callIndex, 1)[0] : pendingToolCalls.shift();
+                ingestToolEvidence(name, call?.args || {}, output, success);
             }
             if (event.type === 'assistant' && typeof event.content === 'string' && event.content.trim()) {
-                assistantFragments.push(sanitizeUserFacingPathText(event.content.trim()));
+                const fragment = sanitizeUserFacingPathText(event.content.trim());
+                if (!this.isV3StreamStatusMessage(fragment)) {
+                    assistantFragments.push(fragment);
+                }
             }
             // Some servers emit 'text' events for incremental assistant text
             if (event.type === 'text' && typeof event.content === 'string' && event.content.trim()) {
-                assistantFragments.push(sanitizeUserFacingPathText(event.content.trim()));
+                const fragment = sanitizeUserFacingPathText(event.content.trim());
+                if (!this.isV3StreamStatusMessage(fragment)) {
+                    assistantFragments.push(fragment);
+                }
+            }
+            if (event.type === 'message' && typeof event.content === 'string' && event.content.trim()) {
+                const fragment = sanitizeUserFacingPathText(event.content.trim());
+                if (!this.isV3StreamStatusMessage(fragment)) {
+                    assistantFragments.push(fragment);
+                }
             }
             // Some servers emit content_block_delta for streamed text
             if (event.type === 'content_block_delta' && typeof event.delta?.text === 'string' && event.delta.text.trim()) {
                 assistantFragments.push(sanitizeUserFacingPathText(event.delta.text.trim()));
             }
         }
-        // Concatenate ALL assistant text fragments in order — keeps full
-        // multi-turn reasoning instead of only the last fragment.
+        for (const entry of liveToolEvidence) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            ingestToolEvidence(String(entry.name || entry.tool || 'unknown_tool'), entry.arguments && typeof entry.arguments === 'object' ? entry.arguments : { path: entry.target || entry.path || '' }, String(entry.output || ''), entry.success !== false);
+        }
+        // Prefer grounded tool evidence over streamed status chatter.
+        const hasEvidence = directoriesListed.length > 0
+            || filesRead.length > 0
+            || searches.length > 0
+            || filesWritten.length > 0
+            || toolResults.length > 0
+            || failedPaths.length > 0;
+        if (hasEvidence) {
+            const sections = [];
+            sections.push('## Workspace analysis (from local file inspection)');
+            sections.push('This report is rebuilt from files the agent actually read. **Code and package manifests outrank README/planning docs**, which may be stale or AI-generated.');
+            const codeSignals = this.extractCodeSignalsFromEvidence(filesRead, liveToolEvidence);
+            const consistencySection = this.buildReadmeCodeConsistencySection(filesRead, liveToolEvidence);
+            if (consistencySection) {
+                sections.unshift(consistencySection);
+            }
+            if (codeSignals.length > 0) {
+                sections.push(['## What the code says (trusted)', ...codeSignals.map((line) => `- ${line}`)].join('\n'));
+                if (!consistencySection && codeSignals.some((line) => /rts|real-time strategy|3d rts|4-faction|desktop\/electron/i.test(line))) {
+                    sections.unshift([
+                        '## Executive summary',
+                        'Vigthoria Dominion is a **3D real-time strategy game** (Command & Conquer / Dune 2000 style) with **four factions**, based on code evidence from your local workspace — not from README/planning docs, which may be wrong.',
+                        'The project includes browser/Three.js source (`Vigthoria-dominion/`) and may include a desktop Electron build (`vigthoria-dominion-win/`).',
+                    ].join('\n'));
+                }
+            }
+            else if (consistencySection && /INCONSISTENT/i.test(consistencySection)) {
+                sections.unshift([
+                    '## Executive summary',
+                    'The agent found that **README documentation does not match the codebase**. See the consistency check below — the code defines what this game actually is.',
+                ].join('\n'));
+            }
+            const docWarnings = this.detectDocReliabilityWarnings(filesRead, liveToolEvidence);
+            if (docWarnings.length > 0) {
+                sections.push(['## Documentation reliability warnings', ...docWarnings.map((line) => `- ${line}`)].join('\n'));
+            }
+            if (directoriesListed.length > 0) {
+                const uniqueDirs = new Map();
+                for (const entry of directoriesListed) {
+                    if (!uniqueDirs.has(entry.path))
+                        uniqueDirs.set(entry.path, entry.excerpt);
+                }
+                const dirLines = [...uniqueDirs.entries()].slice(0, 8).map(([dirPath, excerpt]) => {
+                    const preview = excerpt.split('\n').filter(Boolean).slice(0, 12).join('\n');
+                    return `### ${dirPath}\n${preview}`;
+                });
+                sections.push(['## Directories inspected', ...dirLines].join('\n\n'));
+            }
+            if (filesRead.length > 0) {
+                const uniqueFiles = new Map();
+                for (const entry of filesRead) {
+                    if (!uniqueFiles.has(entry.path))
+                        uniqueFiles.set(entry.path, entry.excerpt);
+                }
+                const sortedFiles = [...uniqueFiles.entries()].sort((a, b) => this.scoreEvidenceFilePath(b[0]) - this.scoreEvidenceFilePath(a[0]));
+                const fileLines = sortedFiles.slice(0, 8).map(([filePath, excerpt]) => {
+                    const tag = this.isLowTrustDocPath(filePath) ? ' _(low-trust doc)_' : '';
+                    return `### ${filePath}${tag}\n${excerpt}`;
+                });
+                sections.push(['## Files read (code-first order)', ...fileLines].join('\n\n'));
+            }
+            if (searches.length > 0) {
+                sections.push(`## Searches run\n${Array.from(new Set(searches)).slice(0, 8).map((entry) => `- ${entry}`).join('\n')}`);
+            }
+            if (filesWritten.length > 0) {
+                sections.push(`## Files written\n${Array.from(new Set(filesWritten)).slice(0, 12).map((entry) => `- ${entry}`).join('\n')}`);
+            }
+            if (failedPaths.length > 0) {
+                const uniqueFails = new Map();
+                for (const entry of failedPaths) {
+                    if (!uniqueFails.has(entry.path))
+                        uniqueFails.set(entry.path, entry.detail);
+                }
+                const failLines = [...uniqueFails.entries()].slice(0, 12).map(([failPath, detail]) => `- \`${failPath}\`${detail ? ` — ${detail}` : ''}`);
+                sections.push([
+                    '## Paths not found (exploration misses)',
+                    ...failLines,
+                    '',
+                    '_These paths were guessed by the agent and do not exist at that location. Check the directories inspected above for the correct layout (often under `src/`)._',
+                ].join('\n'));
+            }
+            if (toolResults.length > 0) {
+                sections.push(`## Additional tool evidence\n${toolResults.slice(-5).join('\n\n')}`);
+            }
+            return sections.join('\n\n');
+        }
+        // Concatenate substantive assistant text fragments in order.
         const fullAssistantText = assistantFragments.join('\n\n').trim();
-        if (fullAssistantText.length > 20) {
+        if (fullAssistantText.length > 80 && !this.isGenericV3AgentSummary(fullAssistantText)) {
             return fullAssistantText;
         }
-        // Otherwise build a summary from tool evidence
-        const sections = [];
-        if (filesRead.length > 0) {
-            sections.push(`Files inspected: ${filesRead.join(', ')}`);
-        }
-        if (filesWritten.length > 0) {
-            sections.push(`Files written: ${filesWritten.join(', ')}`);
-        }
-        if (toolResults.length > 0) {
-            sections.push(toolResults.slice(-5).join('\n'));
-        }
-        return sections.length > 0
-            ? sections.join('\n\n')
-            : '';
+        return '';
     }
     sanitizeV3AgentEventForUser(event) {
         const sanitizeValue = (value) => {
@@ -3013,17 +4209,42 @@ document.addEventListener('DOMContentLoaded', () => {
                 break;
             }
             buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split('\n');
-            buffer = lines.pop() || '';
-            for (const line of lines) {
-                if (!line.startsWith('data: ')) {
-                    continue;
+            const frames = buffer.split(/\r?\n\r?\n/);
+            buffer = frames.pop() || '';
+            for (const frame of frames) {
+                const lines = frame.split(/\r?\n/);
+                const dataLines = [];
+                let explicitEventType = null;
+                for (const rawLine of lines) {
+                    const line = rawLine.trimEnd();
+                    if (!line || line.startsWith(':')) {
+                        continue;
+                    }
+                    if (line.startsWith('event:')) {
+                        explicitEventType = line.slice(6).trim() || null;
+                        continue;
+                    }
+                    if (line.startsWith('data:')) {
+                        dataLines.push(line.slice(5).trimStart());
+                    }
                 }
-                const payload = line.slice(6).trim();
+                const payload = dataLines.join('\n').trim();
                 if (!payload || payload === '[DONE]') {
                     continue;
                 }
-                const event = JSON.parse(payload);
+                let event;
+                try {
+                    event = JSON.parse(payload);
+                }
+                catch {
+                    event = {
+                        type: explicitEventType || 'message',
+                        content: payload,
+                    };
+                }
+                if (explicitEventType && (!event.type || event.type === 'message')) {
+                    event.type = explicitEventType;
+                }
                 const userEvent = this.sanitizeV3AgentEventForUser(event);
                 events.push(userEvent);
                 if (!contextId && typeof event.context_id === 'string' && event.context_id.trim()) {
@@ -3034,10 +4255,9 @@ document.addEventListener('DOMContentLoaded', () => {
                 }
                 this.captureV3AgentStreamMutation(event, streamedFiles, serverWorkspaceRoot);
                 this.applyV3AgentStreamEventToWorkspace(event, context, serverWorkspaceRoot);
-                // Empty workspace guard: if the remote agent lists its root
-                // and finds nothing while our local workspace has files, the
-                // workspace was not hydrated. Abort early with a clear error
-                // instead of letting the agent spin on an empty directory.
+                // Empty workspace soft guard: the first list_directory result can be
+                // transiently empty before remote workspace hydration catches up.
+                // Avoid hard-failing here; let the stream continue.
                 if (event.type === 'tool_result'
                     && event.name === 'list_directory'
                     && event.success === true
@@ -3052,9 +4272,7 @@ document.addEventListener('DOMContentLoaded', () => {
                         const localPath = this.resolveAgentTargetPath(context);
                         const localHasFiles = localPath && fs.existsSync(localPath) && this.hasAgentWorkspaceOutput({ ...context, projectPath: localPath, targetPath: localPath });
                         if (localHasFiles) {
-                            throw new Error('Remote workspace is empty — the V3 server did not receive your project files. '
-                                + 'Your local workspace has files but the remote agent sees an empty directory. '
-                                + 'This is a workspace sync failure. Falling back to local agent loop.');
+                            this.logger?.debug?.('V3 remote workspace initially empty; waiting for hydration instead of aborting.');
                         }
                     }
                 }
@@ -3066,6 +4284,43 @@ document.addEventListener('DOMContentLoaded', () => {
                         // Ignore UI callback failures; never break the agent stream for them.
                     }
                 }
+                if (event.type === 'client_tool_request') {
+                    const activeContextId = String(event.context_id || contextId || context.contextId || '').trim();
+                    const callId = String(event.call_id || '').trim();
+                    const handler = context.onClientToolExecute;
+                    let toolResult = {
+                        success: false,
+                        output: '',
+                        error: 'No local tool handler configured',
+                    };
+                    if (typeof handler === 'function' && activeContextId && callId) {
+                        try {
+                            toolResult = await handler(event);
+                        }
+                        catch (error) {
+                            toolResult = {
+                                success: false,
+                                output: '',
+                                error: sanitizeUserFacingErrorText(error?.message || 'Local tool execution failed'),
+                            };
+                        }
+                    }
+                    if (activeContextId && callId) {
+                        await this.submitClientToolResult(activeContextId, callId, toolResult, context.v3BackendUrl);
+                    }
+                    continue;
+                }
+                if (event.type === 'context' && typeof context.onWorkspaceContext === 'function') {
+                    try {
+                        await context.onWorkspaceContext({
+                            contextId: String(event.context_id || contextId || '').trim(),
+                            serverWorkspaceRoot: String(event.workspace_root || serverWorkspaceRoot || '').trim(),
+                        });
+                    }
+                    catch {
+                        // Ignore workspace bind callback failures.
+                    }
+                }
                 if (event.type === 'error') {
                     if (event.checkpointed && event.task_id) {
                         // Agent checkpointed — return data so caller can auto-continue
@@ -3095,6 +4350,19 @@ document.addEventListener('DOMContentLoaded', () => {
                 if (event.type === 'complete' || event.type === 'message') {
                     final = event;
                 }
+                // Exit stream early on complete — agent is done; server-side teardown
+                // can hold the connection open for many seconds otherwise.
+                if (event.type === 'complete') {
+                    reader.cancel().catch(() => { });
+                    return {
+                        task_id: events.find((entry) => entry && entry.task_id)?.task_id || null,
+                        context_id: contextId,
+                        result: final,
+                        events,
+                        files: streamedFiles,
+                        serverWorkspaceRoot: serverWorkspaceRoot || null,
+                    };
+                }
             }
         }
         return {
@@ -3106,6 +4374,36 @@ document.addEventListener('DOMContentLoaded', () => {
             serverWorkspaceRoot: serverWorkspaceRoot || null,
         };
     }
+    async submitClientToolResult(contextId, callId, result, backendUrl) {
+        const trimmedContextId = String(contextId || '').trim();
+        const trimmedCallId = String(callId || '').trim();
+        if (!trimmedContextId || !trimmedCallId) {
+            return;
+        }
+        const baseUrl = String(backendUrl || this.getV3AgentBaseUrls()[0] || '').replace(/\/$/, '');
+        if (!baseUrl) {
+            return;
+        }
+        const headers = await this.getV3AgentHeaders();
+        const endpoint = /127\.0\.0\.1:8030|localhost:8030/.test(baseUrl)
+            ? `${baseUrl}/api/agent/client-tool-result`
+            : `${baseUrl}/api/v3-agent/client-tool-result`;
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                context_id: trimmedContextId,
+                call_id: trimmedCallId,
+                success: result.success === true,
+                output: String(result.output || ''),
+                error: String(result.error || ''),
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => '');
+            throw new Error(`Client tool result rejected (${response.status}): ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
+        }
+    }
     async runV3AgentWorkflow(message, context = {}) {
         const executionContext = await this.bindExecutionContext(context);
         const requestedTimeoutMs = Number(executionContext.agentTimeoutMs ?? DEFAULT_V3_AGENT_TIMEOUT_MS);
@@ -3135,7 +4433,7 @@ document.addEventListener('DOMContentLoaded', () => {
                     legacyFallbackAllowed: true,
                 })
                 : executionContext;
-            const requestBody = {
+            const buildRequestBody = (contextIdOverride) => ({
                 request: message,
                 model: resolvedModel,
                 preferred_model: resolvedModel,
@@ -3145,119 +4443,154 @@ document.addEventListener('DOMContentLoaded', () => {
                 context: useRelaxedAttempt
                     ? this.buildMinimalV3AgentContext(requestExecutionContext)
                     : this.buildV3AgentContext(requestExecutionContext),
-                context_id: requestExecutionContext.contextId,
+                context_id: contextIdOverride ?? requestExecutionContext.contextId,
                 mcp_context_id: useRelaxedAttempt ? null : requestExecutionContext.mcpContextId || null,
                 stream: true,
-            };
+            });
             for (const baseUrl of this.getV3AgentBaseUrls(preferLocalV3)) {
-                const controller = new AbortController();
-                const timeoutId = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
-                try {
-                    const response = await this.executeV3AgentRunRequest(baseUrl, requestBody, requestExecutionContext, controller.signal);
-                    if (!response.ok) {
-                        const errorText = await response.text().catch(() => '');
-                        throw new Error(`V3 agent ${response.status}: ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
-                    }
-                    const data = await this.collectV3AgentStream(response, requestExecutionContext);
-                    // Auto-continuation: if the agent checkpointed (budget exceeded), continue automatically
-                    if (data.checkpointed && data.checkpointed_task_id) {
-                        const maxContinuations = 10;
-                        let continuationData = data;
-                        let continuations = 0;
-                        while (continuationData.checkpointed && continuationData.checkpointed_task_id && continuations < maxContinuations) {
-                            continuations++;
-                            if (typeof requestExecutionContext.onStreamEvent === 'function') {
+                let contextIdOverride;
+                const authPreflight = await this.runV3AgentAuthPreflight(baseUrl, buildRequestBody(), requestExecutionContext);
+                if (!authPreflight.ok) {
+                    errors.push(`V3 auth preflight ${authPreflight.status} [${authPreflight.endpoint}]: ${authPreflight.reason || 'Unauthorized'}`);
+                    continue;
+                }
+                for (let contextRetry = 0; contextRetry < 2; contextRetry += 1) {
+                    const requestBody = buildRequestBody(contextIdOverride);
+                    const controller = new AbortController();
+                    const timeoutId = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
+                    try {
+                        const response = await this.executeV3AgentRunRequest(baseUrl, requestBody, requestExecutionContext, controller.signal);
+                        if (!response.ok) {
+                            const errorText = await response.text().catch(() => '');
+                            const sanitized = sanitizeUserFacingErrorText(errorText).slice(0, 200);
+                            const isContextCollision = response.status === 409 && /already in progress/i.test(errorText);
+                            const isTransientWorkspaceHydration = /remote workspace is empty|workspace sync failure/i.test(errorText);
+                            if ((isContextCollision || isTransientWorkspaceHydration) && contextRetry === 0) {
+                                contextIdOverride = `${requestExecutionContext.contextId || 'vig'}-retry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                                this.logger?.debug?.(`V3 transient agent error on ${baseUrl}; retrying with fresh context id.`);
+                                continue;
+                            }
+                            throw new Error(`V3 agent ${response.status}: ${sanitized}`);
+                        }
+                        const data = await this.collectV3AgentStream(response, {
+                            ...requestExecutionContext,
+                            v3BackendUrl: baseUrl,
+                        });
+                        // Auto-continuation: if the agent checkpointed (budget exceeded), continue automatically
+                        if (data.checkpointed && data.checkpointed_task_id) {
+                            const maxContinuations = 10;
+                            let continuationData = data;
+                            let continuations = 0;
+                            while (continuationData.checkpointed && continuationData.checkpointed_task_id && continuations < maxContinuations) {
+                                continuations++;
+                                if (typeof requestExecutionContext.onStreamEvent === 'function') {
+                                    try {
+                                        requestExecutionContext.onStreamEvent({
+                                            type: 'message',
+                                            content: `Auto-continuing task (phase ${continuations + 1})...`,
+                                        });
+                                    }
+                                    catch { /* ignore */ }
+                                }
+                                const continueBody = {
+                                    task_id: continuationData.checkpointed_task_id,
+                                    context: requestBody.context,
+                                    context_id: requestBody.context_id,
+                                    mcp_context_id: requestBody.mcp_context_id,
+                                    stream: true,
+                                };
+                                const continueController = new AbortController();
+                                const continueTimeoutId = timeoutMs > 0 ? setTimeout(() => continueController.abort(), timeoutMs) : null;
                                 try {
-                                    requestExecutionContext.onStreamEvent({
-                                        type: 'message',
-                                        content: `Auto-continuing task (phase ${continuations + 1})...`,
+                                    const continueHeaders = await this.getV3AgentHeaders();
+                                    const continueResponse = await fetch(this.getV3AgentContinueUrl(baseUrl), {
+                                        method: 'POST',
+                                        headers: { ...continueHeaders, 'Content-Type': 'application/json' },
+                                        body: JSON.stringify(continueBody),
+                                        signal: continueController.signal,
+                                    });
+                                    if (!continueResponse.ok) {
+                                        break; // Fall through to normal completion with partial data
+                                    }
+                                    continuationData = await this.collectV3AgentStream(continueResponse, {
+                                        ...requestExecutionContext,
+                                        v3BackendUrl: baseUrl,
                                     });
                                 }
-                                catch { /* ignore */ }
-                            }
-                            const continueBody = {
-                                task_id: continuationData.checkpointed_task_id,
-                                context: requestBody.context,
-                                context_id: requestBody.context_id,
-                                mcp_context_id: requestBody.mcp_context_id,
-                                stream: true,
-                            };
-                            const continueController = new AbortController();
-                            const continueTimeoutId = timeoutMs > 0 ? setTimeout(() => continueController.abort(), timeoutMs) : null;
-                            try {
-                                const continueHeaders = await this.getV3AgentHeaders();
-                                const continueResponse = await fetch(this.getV3AgentContinueUrl(baseUrl), {
-                                    method: 'POST',
-                                    headers: { ...continueHeaders, 'Content-Type': 'application/json' },
-                                    body: JSON.stringify(continueBody),
-                                    signal: continueController.signal,
-                                });
-                                if (!continueResponse.ok) {
+                                catch {
                                     break; // Fall through to normal completion with partial data
                                 }
-                                continuationData = await this.collectV3AgentStream(continueResponse, requestExecutionContext);
-                            }
-                            catch {
-                                break; // Fall through to normal completion with partial data
-                            }
-                            finally {
-                                if (continueTimeoutId)
-                                    clearTimeout(continueTimeoutId);
+                                finally {
+                                    if (continueTimeoutId)
+                                        clearTimeout(continueTimeoutId);
+                                }
                             }
+                            // Use the final continuation data for workspace recovery
+                            this.recoverAgentWorkspaceFiles(executionContext, continuationData.files || {}, expectedFiles);
+                            await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
+                            await this.ensureAgentFrontendPolish(message, executionContext);
+                            const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                            const finalContextId = continuationData.context_id || data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
+                            return {
+                                content: this.formatV3AgentResponse({
+                                    ...continuationData,
+                                    liveToolEvidence: requestExecutionContext.liveToolEvidence,
+                                }) || this.formatV3AgentResponse({
+                                    ...data,
+                                    liveToolEvidence: requestExecutionContext.liveToolEvidence,
+                                }),
+                                taskId: continuationData.task_id || data.task_id || null,
+                                contextId: finalContextId,
+                                backendUrl: baseUrl,
+                                partial: continuationData.checkpointed === true,
+                                metadata: { source: 'v3-agent', mode: 'agent', contextId: finalContextId, continuations, previewGate },
+                            };
                         }
-                        // Use the final continuation data for workspace recovery
-                        this.recoverAgentWorkspaceFiles(executionContext, continuationData.files || {}, expectedFiles);
+                        const contextId = data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
+                        const mcpContextId = response.headers.get('x-mcp-context-id') || requestExecutionContext.mcpContextId || null;
+                        this.recoverAgentWorkspaceFiles(executionContext, data.files || {}, expectedFiles);
                         await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
                         await this.ensureAgentFrontendPolish(message, executionContext);
                         const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
-                        const finalContextId = continuationData.context_id || data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
+                        if (previewGate.required && previewGate.passed !== true && !this.hasAgentWorkspaceOutput(executionContext)) {
+                            errors.push(`${baseUrl}: workflow rejected the result - ${previewGate.error || 'Workspace changes were not fully validated.'}`);
+                            continue;
+                        }
                         return {
-                            content: this.formatV3AgentResponse(continuationData) || this.formatV3AgentResponse(data),
-                            taskId: continuationData.task_id || data.task_id || null,
-                            contextId: finalContextId,
+                            content: this.formatV3AgentResponse({
+                                ...data,
+                                liveToolEvidence: requestExecutionContext.liveToolEvidence,
+                            }),
+                            taskId: data.task_id || null,
+                            contextId,
                             backendUrl: baseUrl,
-                            partial: continuationData.checkpointed === true,
-                            metadata: { source: 'v3-agent', mode: 'agent', contextId: finalContextId, continuations, previewGate },
+                            metadata: { source: 'v3-agent', mode: 'agent', contextId, mcpContextId, previewGate },
                         };
                     }
-                    const contextId = data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
-                    const mcpContextId = response.headers.get('x-mcp-context-id') || requestExecutionContext.mcpContextId || null;
-                    this.recoverAgentWorkspaceFiles(executionContext, data.files || {}, expectedFiles);
-                    await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
-                    await this.ensureAgentFrontendPolish(message, executionContext);
-                    const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
-                    if (previewGate.required && previewGate.passed !== true && !this.hasAgentWorkspaceOutput(executionContext)) {
-                        errors.push(`${baseUrl}: workflow rejected the result - ${previewGate.error || 'Workspace changes were not fully validated.'}`);
-                        continue;
+                    catch (error) {
+                        if (error && error.name === 'AbortError' && error.partialData && this.hasAgentWorkspaceOutput(executionContext)) {
+                            this.recoverAgentWorkspaceFiles(executionContext, error.partialData.files || {}, expectedFiles);
+                            await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
+                            await this.ensureAgentFrontendPolish(message, executionContext);
+                            const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                            return {
+                                content: this.formatV3AgentResponse({
+                                    ...error.partialData,
+                                    liveToolEvidence: requestExecutionContext.liveToolEvidence,
+                                }) || 'V3 agent wrote workspace files before the request timed out waiting for a final summary.',
+                                taskId: error.partialData.task_id || null,
+                                contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null,
+                                backendUrl: baseUrl,
+                                partial: true,
+                                metadata: { source: 'v3-agent', mode: 'agent', partial: true, contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null, mcpContextId: requestExecutionContext.mcpContextId || executionContext.mcpContextId || null, previewGate },
+                            };
+                        }
+                        errors.push(`${baseUrl}: ${error?.message || String(error)}`);
                     }
-                    return {
-                        content: this.formatV3AgentResponse(data),
-                        taskId: data.task_id || null,
-                        contextId,
-                        backendUrl: baseUrl,
-                        metadata: { source: 'v3-agent', mode: 'agent', contextId, mcpContextId, previewGate },
-                    };
-                }
-                catch (error) {
-                    if (error && error.name === 'AbortError' && error.partialData && this.hasAgentWorkspaceOutput(executionContext)) {
-                        this.recoverAgentWorkspaceFiles(executionContext, error.partialData.files || {}, expectedFiles);
-                        await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
-                        await this.ensureAgentFrontendPolish(message, executionContext);
-                        const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
-                        return {
-                            content: this.formatV3AgentResponse(error.partialData) || 'V3 agent wrote workspace files before the request timed out waiting for a final summary.',
-                            taskId: error.partialData.task_id || null,
-                            contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null,
-                            backendUrl: baseUrl,
-                            partial: true,
-                            metadata: { source: 'v3-agent', mode: 'agent', partial: true, contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null, mcpContextId: requestExecutionContext.mcpContextId || executionContext.mcpContextId || null, previewGate },
-                        };
+                    finally {
+                        if (timeoutId)
+                            clearTimeout(timeoutId);
                     }
-                    errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-                }
-                finally {
-                    if (timeoutId)
-                        clearTimeout(timeoutId);
                 }
             }
             lastErrors = errors;
@@ -3271,7 +4604,7 @@ document.addEventListener('DOMContentLoaded', () => {
             await new Promise((resolve) => setTimeout(resolve, 1500));
         }
         const errors = lastErrors;
-        const onlyUnauthorizedErrors = errors.length > 0 && errors.every((entry) => /V3 agent 401:/i.test(entry));
+        const onlyUnauthorizedErrors = errors.length > 0 && errors.every((entry) => /V3 agent 401:|V3 agent 401 \[|V3 auth preflight 401|V3 auth preflight 403/i.test(entry));
         const usingStoredConfigToken = !process.env.VIGTHORIA_TOKEN
             && !process.env.VIGTHORIA_AUTH_TOKEN
             && Boolean(this.config.get('authToken'));
@@ -3281,7 +4614,16 @@ document.addEventListener('DOMContentLoaded', () => {
                 this.config.clearAuth();
                 throw new Error('V3 agent authentication failed. The stored CLI login token is invalid or expired. Run vigthoria login again.');
             }
-            throw new Error('V3 agent authentication failed at the V3 service layer while your gateway login token is still valid. Please retry shortly.');
+            const rejectedEndpoints = Array.from(new Set(errors
+                .map((entry) => {
+                const match = entry.match(/\[(https?:\/\/[^\]]+)\]/i);
+                return match ? match[1] : null;
+            })
+                .filter((entry) => Boolean(entry))));
+            const endpointSummary = rejectedEndpoints.length > 0
+                ? ` Rejected V3 endpoints: ${rejectedEndpoints.join(', ')}.`
+                : '';
+            throw new Error(`V3 agent authentication failed at the V3 service layer while your gateway login token is still valid.${endpointSummary} Please retry shortly.`);
         }
         if (preferLocalV3
             && !this.hasAgentWorkspaceOutput(executionContext)
@@ -3506,7 +4848,7 @@ document.addEventListener('DOMContentLoaded', () => {
      *
      * NO localhost fallbacks - CLI is for external users, not server-side!
      */
-    async chat(messages, model, useLocal = false) {
+    async chat(messages, model, useLocal = false, options = {}) {
         this.lastChatTransportErrors = [];
         const resolvedModel = this.resolveModelId(model);
         const candidateModels = this.isCloudModelId(resolvedModel) && !this.canUseCloudModel()
@@ -3517,7 +4859,7 @@ document.addEventListener('DOMContentLoaded', () => {
             candidateModels.push(fallbackModel);
         }
         for (const candidateModel of candidateModels) {
-            const response = await this.tryChatWithModel(messages, candidateModel, model);
+            const response = await this.tryChatWithModel(messages, candidateModel, model, options);
             if (response) {
                 if (candidateModel !== resolvedModel) {
                     this.logger.debug(`Recovered chat request using fallback model: ${candidateModel}`);
@@ -3525,79 +4867,100 @@ document.addEventListener('DOMContentLoaded', () => {
                 return response;
             }
         }
-        // No more localhost fallbacks - CLI is for external users!
-        const detail = this.lastChatTransportErrors.length > 0
-            ? ` Tried routes: ${this.lastChatTransportErrors.slice(0, 4).join(' | ')}`
-            : '';
-        throw new CLIError(`AI service unavailable. Please check your internet connection or try again later.${detail}`, 'model_backend');
+        // Keep route diagnostics internal. Users only need to know the Vigthoria service is temporarily unavailable.
+        if (this.lastChatTransportErrors.length > 0) {
+            this.logger.debug(`Chat transport failures: ${this.lastChatTransportErrors.slice(0, 4).join(' | ')}`);
+        }
+        throw new CLIError(VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE, 'model_backend');
+    }
+    getLastChatTransportErrors() {
+        return [...this.lastChatTransportErrors];
     }
     shouldSkipCloudRoutes(resolvedModel) {
         return this.shouldSimulateCloudFailure() && this.isCloudModelId(resolvedModel);
     }
-    async tryChatWithModel(messages, resolvedModel, requestedModel) {
+    async tryChatWithModel(messages, resolvedModel, requestedModel, options = {}) {
         const routeFailures = [];
-        const preferSelfHostedFirst = this.isSelfHostedPreferredModel(resolvedModel, requestedModel);
-        if (preferSelfHostedFirst) {
-            const selfHostedResponse = await this.trySelfHostedChatWithModel(messages, resolvedModel, requestedModel);
-            if (selfHostedResponse) {
-                return selfHostedResponse;
+        const connectTimeoutMs = this.resolveChatConnectTimeoutMs(options);
+        const idleTimeoutMs = this.resolveChatIdleTimeoutMs(options);
+        const useStream = options.stream === true;
+        const notifyRoute = (label) => {
+            try {
+                options.onRouteAttempt?.(label);
+            }
+            catch {
+                // Spinner callbacks must not break chat routing.
+            }
+        };
+        const tryModelsRoute = async () => {
+            if (this.shouldSkipCloudRoutes(resolvedModel) || this.isCloudModelId(resolvedModel)) {
+                return null;
+            }
+            const token = this.getAccessToken();
+            const authHeaders = token ? { Authorization: `Bearer ${token}` } : {};
+            if (useStream) {
+                try {
+                    notifyRoute('Streaming from Vigthoria Models API...');
+                    return await this.tryStreamingModelRouterChat(this.modelRouterClient.defaults.baseURL || 'https://api.vigthoria.io', messages, resolvedModel, requestedModel, authHeaders, options);
+                }
+                catch (error) {
+                    const errMsg = error?.message || 'Unknown error';
+                    routeFailures.push(`models-stream:${String(errMsg).slice(0, 120)}`);
+                }
             }
-        }
-        // STRATEGY 1: Direct Vigthoria Models API (api.vigthoria.io)
-        if (!this.shouldSkipCloudRoutes(resolvedModel)) {
             try {
-                this.logger.debug(`Direct Vigthoria Models API: ${resolvedModel}`);
-                const token = this.getAccessToken();
+                notifyRoute('Connecting to Vigthoria Models API...');
                 const response = await this.modelRouterClient.post('/v1/chat/completions', {
                     model: resolvedModel,
                     messages,
                     max_tokens: this.config.get('preferences').maxTokens,
                     temperature: 0.7,
                     stream: false,
+                    cloudAccessApproved: this.isCloudModelId(resolvedModel),
+                    routeClass: 'direct-chat',
                 }, {
-                    headers: token ? { Authorization: `Bearer ${token}` } : {},
+                    timeout: connectTimeoutMs,
+                    headers: {
+                        ...authHeaders,
+                        ...this.buildDirectChatHeaders(this.isCloudModelId(resolvedModel)),
+                    },
                 });
-                if (response.data.choices && response.data.choices.length > 0) {
-                    const content = response.data.choices[0].message?.content || response.data.choices[0].text;
-                    if (typeof content !== 'string' || !content.trim()) {
-                        this.logger.debug(`Direct API returned empty message content for ${resolvedModel}`);
-                    }
-                    else {
-                        return {
-                            id: response.data.id || `vigthoria-${Date.now()}`,
-                            message: content,
-                            model: response.data.model || resolvedModel || requestedModel,
-                            usage: response.data.usage,
-                        };
-                    }
+                const content = response.data.choices?.[0]?.message?.content || response.data.choices?.[0]?.text;
+                if (typeof content === 'string' && content.trim()) {
+                    return {
+                        id: response.data.id || `vigthoria-${Date.now()}`,
+                        message: content,
+                        model: response.data.model || resolvedModel || requestedModel,
+                        usage: response.data.usage,
+                    };
                 }
-                this.logger.debug(`Direct API returned no choices for ${resolvedModel}`);
             }
             catch (error) {
                 const errMsg = error.response?.data?.error || error.message || 'Unknown error';
-                this.logger.debug(`Direct Vigthoria Models API failed for ${resolvedModel}: ${errMsg}`);
                 routeFailures.push(`models:${String(errMsg).slice(0, 120)}`);
             }
-        }
-        else {
-            this.logger.debug(`Simulating cloud failure for ${resolvedModel}; skipping cloud-backed public API route.`);
-        }
-        // STRATEGY 2: Vigthoria Cloud API via Coder (authenticated users only)
-        if (this.config.isAuthenticated() && !this.shouldSkipCloudRoutes(resolvedModel)) {
+            return null;
+        };
+        const tryCoderRoute = async () => {
+            if (!this.config.isAuthenticated() || this.shouldSkipCloudRoutes(resolvedModel)) {
+                return null;
+            }
             try {
-                this.logger.debug(`Vigthoria Cloud API fallback: ${resolvedModel}`);
+                notifyRoute('Connecting to Vigthoria Coder API...');
                 const response = await this.client.post('/api/ai/chat', {
                     messages,
                     model: resolvedModel,
                     maxTokens: this.config.get('preferences').maxTokens,
                     temperature: 0.7,
+                    routeClass: 'direct-chat',
+                    cloudAccessApproved: this.isCloudModelId(resolvedModel),
+                }, {
+                    timeout: idleTimeoutMs,
+                    headers: this.buildDirectChatHeaders(this.isCloudModelId(resolvedModel)),
                 });
                 if (response.data.success !== false) {
                     const content = response.data.response || response.data.message || response.data.content;
-                    if (typeof content !== 'string' || !content.trim()) {
-                        this.logger.debug(`Cloud API returned empty message content for ${resolvedModel}`);
-                    }
-                    else {
+                    if (typeof content === 'string' && content.trim()) {
                         return {
                             id: response.data.id || `vigthoria-coder-${Date.now()}`,
                             message: content,
@@ -3606,48 +4969,81 @@ document.addEventListener('DOMContentLoaded', () => {
                         };
                     }
                 }
-                this.logger.debug(`Cloud API returned success=false for ${resolvedModel}`);
             }
             catch (error) {
                 const errMsg = error.response?.data?.error || error.message || 'Unknown error';
-                this.logger.debug(`Vigthoria Cloud API failed for ${resolvedModel}: ${errMsg}`);
                 routeFailures.push(`coder:${String(errMsg).slice(0, 120)}`);
             }
+            return null;
+        };
+        const tryCanonicalRoute = async () => {
+            if (options.fastFail || this.isCanonicalCoderDuplicate() || !this.config.isAuthenticated()) {
+                return null;
+            }
             try {
-                this.logger.debug(`Canonical Vigthoria Cloud fallback: ${resolvedModel}`);
+                notifyRoute('Connecting to Vigthoria Coder (canonical)...');
                 const token = this.getAccessToken();
                 const response = await axios.post('https://coder.vigthoria.io/api/ai/chat', {
                     messages,
                     model: resolvedModel,
                     maxTokens: this.config.get('preferences').maxTokens,
                     temperature: 0.7,
+                    routeClass: 'direct-chat',
+                    cloudAccessApproved: this.isCloudModelId(resolvedModel),
                 }, {
-                    timeout: 180000,
+                    timeout: idleTimeoutMs,
                     httpsAgent: this._httpsAgent ?? undefined,
-                    headers: token ? { Authorization: `Bearer ${token}`, Cookie: `vigthoria-auth-token=${token}` } : {},
+                    headers: {
+                        ...(token ? { Authorization: `Bearer ${token}`, Cookie: `vigthoria-auth-token=${token}` } : {}),
+                        ...this.buildDirectChatHeaders(this.isCloudModelId(resolvedModel)),
+                    },
                 });
-                if (response.data?.success !== false) {
-                    const content = response.data.response || response.data.message || response.data.content;
-                    if (typeof content === 'string' && content.trim()) {
-                        return {
-                            id: response.data.id || `vigthoria-coder-canonical-${Date.now()}`,
-                            message: content,
-                            model: response.data.model || resolvedModel || requestedModel,
-                            usage: response.data.usage,
-                        };
-                    }
+                const content = response.data?.response || response.data?.message || response.data?.content;
+                if (response.data?.success !== false && typeof content === 'string' && content.trim()) {
+                    return {
+                        id: response.data.id || `vigthoria-coder-canonical-${Date.now()}`,
+                        message: content,
+                        model: response.data.model || resolvedModel || requestedModel,
+                        usage: response.data.usage,
+                    };
                 }
             }
             catch (error) {
                 const errMsg = error.response?.data?.error || error.message || 'Unknown error';
-                this.logger.debug(`Canonical Vigthoria Cloud fallback failed for ${resolvedModel}: ${errMsg}`);
                 routeFailures.push(`coder-canonical:${String(errMsg).slice(0, 120)}`);
             }
-        }
-        if (!preferSelfHostedFirst) {
-            const selfHostedResponse = await this.trySelfHostedChatWithModel(messages, resolvedModel, requestedModel);
-            if (selfHostedResponse) {
-                return selfHostedResponse;
+            return null;
+        };
+        const trySelfHostedRoute = async () => {
+            notifyRoute('Connecting to dedicated model endpoint...');
+            return this.trySelfHostedChatWithModel(messages, resolvedModel, requestedModel, idleTimeoutMs, options);
+        };
+        const preferred = options.preferredRoute
+            || (this.config.isAuthenticated() ? 'coder' : 'models');
+        const singleRouteMode = options.fastFail === true && (options.singleRoute === true || !!options.preferredRoute);
+        const routeOrder = singleRouteMode && options.preferredRoute
+            ? [options.preferredRoute]
+            : preferred === 'coder'
+                ? ['coder', 'models', 'selfhosted']
+                : preferred === 'selfhosted'
+                    ? ['selfhosted', 'coder', 'models']
+                    : ['models', 'coder', 'selfhosted'];
+        for (const route of routeOrder) {
+            let result = null;
+            if (route === 'coder') {
+                result = await tryCoderRoute();
+                if (!result) {
+                    result = await tryCanonicalRoute();
+                }
+            }
+            else if (route === 'models') {
+                result = await tryModelsRoute();
+            }
+            else {
+                result = await trySelfHostedRoute();
+            }
+            if (result) {
+                return result;
             }
         }
         if (routeFailures.length > 0) {
@@ -3655,13 +5051,13 @@ document.addEventListener('DOMContentLoaded', () => {
         }
         return null;
     }
-    async trySelfHostedChatWithModel(messages, resolvedModel, requestedModel) {
+    async trySelfHostedChatWithModel(messages, resolvedModel, requestedModel, requestTimeoutMs, options = {}) {
         if (!this.selfHostedModelRouterClient || !this.shouldTrySelfHostedFallback(resolvedModel, requestedModel)) {
             return null;
         }
         const selfHostedModel = this.getSelfHostedFallbackModelId(resolvedModel, requestedModel);
         try {
-            this.logger.debug(`Self-hosted Vigthoria GPU fallback: ${selfHostedModel}`);
+            this.logger.debug(`Dedicated Vigthoria model endpoint fallback: ${selfHostedModel}`);
             const response = await this.selfHostedModelRouterClient.post('/v1/chat/completions', {
                 model: selfHostedModel,
                 messages,
@@ -3669,6 +5065,7 @@ document.addEventListener('DOMContentLoaded', () => {
                 temperature: 0.7,
                 stream: false,
             }, {
+                timeout: requestTimeoutMs,
                 headers: {
                     'x-agent-mode': 'true',
                 },
@@ -3676,21 +5073,21 @@ document.addEventListener('DOMContentLoaded', () => {
             if (response.data.choices && response.data.choices.length > 0) {
                 const content = response.data.choices[0].message?.content || response.data.choices[0].text;
                 if (typeof content !== 'string' || !content.trim()) {
-                    this.logger.debug(`Self-hosted route returned empty message content for ${selfHostedModel}`);
+                    this.logger.debug(`Dedicated Vigthoria model endpoint returned empty message content for ${selfHostedModel}`);
                     return null;
                 }
                 return {
-                    id: response.data.id || `vigthoria-self-hosted-${Date.now()}`,
+                    id: response.data.id || `vigthoria-dedicated-${Date.now()}`,
                     message: content,
                     model: response.data.model || selfHostedModel,
                     usage: response.data.usage,
                 };
             }
-            this.logger.debug(`Self-hosted route returned no choices for ${selfHostedModel}`);
+            this.logger.debug(`Dedicated Vigthoria model endpoint returned no choices for ${selfHostedModel}`);
         }
         catch (error) {
             const errMsg = error.response?.data?.error || error.message || 'Unknown error';
-            this.logger.debug(`Self-hosted Vigthoria GPU fallback failed for ${selfHostedModel}: ${errMsg}`);
+            this.logger.debug(`Dedicated Vigthoria model endpoint fallback failed for ${selfHostedModel}: ${errMsg}`);
         }
         return null;
     }
@@ -3708,11 +5105,37 @@ document.addEventListener('DOMContentLoaded', () => {
         return null;
     }
     isCloudModelId(resolvedModel) {
-        return resolvedModel === 'deepseek-v3.1:671b-cloud'
-            || resolvedModel === 'moonshotai/kimi-k2.5'
-            || resolvedModel === 'vigthoria-cloud-pro'
-            || resolvedModel === 'vigthoria-cloud-k2'
-            || resolvedModel === 'vigthoria-cloud-ultra';
+        const normalized = String(resolvedModel || '').trim().toLowerCase();
+        const cloudIds = new Set([
+            'deepseek-v3.1:671b-cloud',
+            'moonshotai/kimi-k2.5',
+            'vigthoria-cloud-pro',
+            'vigthoria-cloud-k2',
+            'vigthoria-cloud-ultra',
+            'vigthoria-cloud-fast',
+            'vigthoria-cloud-balanced',
+            'vigthoria-cloud-code',
+            'vigthoria-cloud-power',
+            'vigthoria-cloud-maximum',
+            'cloud-fast',
+            'cloud-balanced',
+            'cloud-code',
+            'cloud-power',
+            'cloud-maximum',
+            'cloud',
+            'cloud-reason',
+            'ultra',
+        ]);
+        return cloudIds.has(normalized) || normalized.includes('vigthoria-cloud-');
+    }
+    buildDirectChatHeaders(isCloud) {
+        const headers = {
+            'x-vigthoria-route-class': 'direct-chat',
+        };
+        if (isCloud) {
+            headers['x-vigthoria-cloud-approved'] = 'true';
+        }
+        return headers;
     }
     canUseCloudModel() {
         return this.config.hasCloudAccess();
@@ -4701,7 +6124,7 @@ document.addEventListener('DOMContentLoaded', () => {
     resolveModelId(shortName) {
         const modelMap = {
             // ═══════════════════════════════════════════════════════════════
-            // VIGTHORIA LOCAL - Self-hosted models
+            // Vigthoria server infrastructure models
             // ═══════════════════════════════════════════════════════════════
             'fast': 'vigthoria-v3-balanced-4b',
             'mini': 'vigthoria-mini-0.6b',
@@ -4709,7 +6132,7 @@ document.addEventListener('DOMContentLoaded', () => {
             'balanced-4b': 'vigthoria-v3-balanced-4b',
             'creative': 'vigthoria-creative-9b-v4',
             // Code Models - 35B is the default powerhouse
-            'code': 'vigthoria-v3-code-35b', // Internal: self-hosted 35B on Blackwell
+            'code': 'vigthoria-v3-code-35b', // Vigthoria server infrastructure 35B model
             'code-30b': 'vigthoria-v3-code-35b',
             'code-35b': 'vigthoria-v3-code-35b',
             'code-8b': 'vigthoria-v3-code-9b',
@@ -4754,24 +6177,59 @@ document.addEventListener('DOMContentLoaded', () => {
             };
         }
     }
+    isHealthyServicePayload(payload) {
+        const status = String(payload?.status || '').toLowerCase();
+        return payload?.healthy === true
+            || status === 'healthy'
+            || status === 'ok'
+            || status === 'ready'
+            || status === 'degraded';
+    }
+    extractModelCount(payload) {
+        if (Array.isArray(payload?.data))
+            return payload.data.length;
+        if (Array.isArray(payload?.models))
+            return payload.models.length;
+        if (Array.isArray(payload?.model_list))
+            return payload.model_list.length;
+        if (typeof payload?.total === 'number')
+            return payload.total;
+        return 0;
+    }
+    async probeModelList(client) {
+        const candidates = ['/v1/models', '/models', '/api/models', '/api/tags'];
+        for (const endpoint of candidates) {
+            try {
+                const response = await client.get(endpoint, { timeout: 5000 });
+                const modelCount = this.extractModelCount(response.data);
+                if (modelCount > 0) {
+                    return { modelCount, endpoint };
+                }
+            }
+            catch {
+                // try next endpoint
+            }
+        }
+        return { modelCount: 0, endpoint: candidates[0] };
+    }
     async getModelsHealth() {
         const modelsApiUrl = this.config.get('modelsApiUrl');
         try {
-            const [healthResponse, modelsResponse] = await Promise.all([
+            const [healthResponse, modelProbe] = await Promise.all([
                 this.modelRouterClient.get('/health', { timeout: 5000 }),
-                this.modelRouterClient.get('/v1/models', { timeout: 5000 }),
+                this.probeModelList(this.modelRouterClient),
             ]);
-            const healthOk = healthResponse.data?.status === 'healthy'
-                || healthResponse.data?.status === 'ok'
-                || healthResponse.data?.healthy === true;
-            const modelCount = Array.isArray(modelsResponse.data?.data) ? modelsResponse.data.data.length : 0;
+            const healthOk = this.isHealthyServicePayload(healthResponse.data);
+            const modelCount = modelProbe.modelCount;
+            const ok = healthOk || modelCount > 0;
             return {
                 name: 'Models API',
                 endpoint: `${modelsApiUrl}/health`,
-                ok: healthOk && modelCount > 0,
+                ok,
                 details: {
                     health: healthResponse.data,
                     modelCount,
+                    modelsEndpoint: modelProbe.endpoint,
                 },
             };
         }
@@ -4790,20 +6248,26 @@ document.addEventListener('DOMContentLoaded', () => {
             return null;
         }
         try {
-            const response = await this.selfHostedModelRouterClient.get('/health', { timeout: 5000 });
-            const ok = response.data?.status === 'healthy'
-                || response.data?.status === 'ok'
-                || response.data?.healthy === true;
+            const [healthResponse, modelProbe] = await Promise.all([
+                this.selfHostedModelRouterClient.get('/health', { timeout: 5000 }),
+                this.probeModelList(this.selfHostedModelRouterClient),
+            ]);
+            const healthOk = this.isHealthyServicePayload(healthResponse.data);
+            const ok = healthOk || modelProbe.modelCount > 0;
             return {
-                name: 'Self-hosted Models API',
+                name: 'Vigthoria Models API',
                 endpoint: `${selfHostedModelsApiUrl}/health`,
                 ok,
-                details: { health: response.data },
+                details: {
+                    health: healthResponse.data,
+                    modelCount: modelProbe.modelCount,
+                    modelsEndpoint: modelProbe.endpoint,
+                },
             };
         }
         catch (error) {
             return {
-                name: 'Self-hosted Models API',
+                name: 'Vigthoria Models API',
                 endpoint: `${selfHostedModelsApiUrl}/health`,
                 ok: false,
                 error: error.message,
@@ -5056,7 +6520,7 @@ document.addEventListener('DOMContentLoaded', () => {
             withTimeout(this.getDevtoolsBridgeStatus(), 'DevTools Bridge'),
         ]);
         return {
-            overallOk: v3Agent.ok && hyperLoop.ok && repoMemory.ok,
+            overallOk: v3Agent.ok && (hyperLoop.ok || repoMemory.ok),
             v3Agent,
             hyperLoop,
             repoMemory,