vigthoria-cli 1.13.18 → 1.13.22

package/dist/utils/api.js

@@ -3,23 +3,38 @@
  * Connects to coder.vigthoria.io API endpoints
  */
 import axios from 'axios';
-import { execFile } from 'child_process';
 import { randomUUID } from 'crypto';
 import fs from 'fs';
 import https from 'https';
 import net from 'net';
 import path from 'path';
-import WebSocket from 'ws';
 import { globSync } from 'glob';
+import { AuthSessionService, subscribeAuthInvalidation } from './auth-session.js';
+import { appendContextLayer } from './context-state.js';
 import { buildSemanticContext } from './context-ranker.js';
 import { getChangedFiles } from './workspace-cache.js';
 import { isSubstantiveAgentAnswer, isToolEvidenceStubAnswer } from './agentRunOutcome.js';
-import { isV3WorkspaceRootAliasPath, joinV3WorkspacePath, normalizeV3WorkspaceRelativePath } from './v3-workspace-path.js';
 import { buildExecutionHints, isPlannerBuildTask, resolvePlannerAgentTimeoutMs } from './requestIntent.js';
 import { isV3StreamKeepaliveEvent } from './v3-stream-events.js';
 import { resolveV3ContextCharLimit, WORKSPACE_FILE_CHAR_CAP, } from './contextBudget.js';
 import { isLocalTestfarmMode, fetchWithServiceTimeout } from './localTestMode.js';
 import { buildClientManifest } from './clientManifest.js';
+import { assertTrustedEndpoint, installAxiosNetworkPolicy, installGlobalFetchPolicy } from './network-policy.js';
+import { assertSafeRelativePath, resolveWorkspacePath } from './workspace-boundary.js';
+import { parseSupportedProcess } from './process-policy.js';
+import { OptionalPuppeteerScreenshotAdapter } from './preview-screenshot-adapter.js';
+import { ModelGovernance } from './model-governance.js';
+import { OperatorClient, OperatorClientError } from './operator-client.js';
+import { CodeOperationsService } from './code-operations-service.js';
+import { McpContextClient } from './mcp-context-client.js';
+import { FrontendPreviewService } from './frontend-preview-service.js';
+import { V3AgentClient } from './v3-agent-client.js';
+import { V3WorkspaceService } from './v3-workspace-service.js';
+import { CapabilityHealthService, } from './capability-health-service.js';
+import { ModelTransportService } from './model-transport-service.js';
+import { VigFlowClient, } from './vigflow-client.js';
+import { MutationJournal, finalizeMutationTransaction, } from './mutation-journal.js';
+import { isSensitivePath, redactSensitiveText, safeChildProcessEnv, scanOutboundContext, } from './secret-policy.js';
 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 {
@@ -183,28 +198,13 @@ export function sanitizeUserFacingErrorText(input) {
         return '';
     }
     const withoutTags = raw.replace(/<[^>]+>/g, ' ');
-    return sanitizeUserFacingPathText(withoutTags)
+    return redactSensitiveText(sanitizeUserFacingPathText(withoutTags))
         .replace(/\\[nr]/g, ' ')
         .replace(/https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?(?:\/[^\s'")\]]*)?/gi, 'internal AI service')
         .replace(/\b(?:deepseek|openrouter)\/[A-Za-z0-9._/-]+\b/gi, 'cloud model')
         .replace(/\s+/g, ' ')
         .trim();
 }
-const TRUSTED_TOKEN_HOST_PATTERN = /(^|\.)vigthoria\.io$/i;
-function isLoopbackHost(hostname) {
-    const host = String(hostname || '').toLowerCase();
-    return host === 'localhost' || host === '127.0.0.1';
-}
-function isTrustedTokenDestination(rawUrl) {
-    try {
-        const parsed = new URL(rawUrl);
-        const host = parsed.hostname.toLowerCase();
-        return TRUSTED_TOKEN_HOST_PATTERN.test(host) || isLoopbackHost(host);
-    }
-    catch {
-        return false;
-    }
-}
 function resolveAxiosRequestUrl(req) {
     const direct = String(req?.url || '').trim();
     const base = String(req?.baseURL || '').trim();
@@ -222,14 +222,6 @@ function resolveAxiosRequestUrl(req) {
     }
     return direct;
 }
-export function isServerRuntime() {
-    if (process.env.VIGTHORIA_ALLOW_LOCAL_SERVICES === '1') {
-        return true;
-    }
-    const host = String(process.env.HOSTNAME || '').toLowerCase();
-    const cwd = String(process.cwd() || '').toLowerCase();
-    return host.includes('ubuntu') || cwd.startsWith('/var/www');
-}
 export function describeUpstreamStatus(status) {
     if (status >= 500)
         return 'upstream internal error';
@@ -307,19 +299,141 @@ export class APIClient {
     modelRouterClient;
     selfHostedModelRouterClient;
     config;
+    authSession;
+    unsubscribeAuthInvalidation = null;
     logger;
-    ws = null;
-    vigFlowTokens = new Map();
+    modelGovernance;
+    codeOperations;
+    mcpContextClient;
+    v3AgentClient;
+    v3WorkspaceService;
+    capabilityHealthService;
+    modelTransportService;
+    operatorClient;
+    vigFlowClient;
     _httpsAgent = null;
     lastChatTransportErrors = [];
     clientToolErrors = [];
     pendingV3ClientToolTasks = new Set();
     /** Tracks files mutated via client_tool_request during an active V3 SSE stream. */
     activeV3StreamedFiles = null;
-    activeV3StreamContext = null;
-    constructor(config, logger) {
+    lifecycleAbortController = new AbortController();
+    frontendPreviewService;
+    withLifecycleSignal(signal) {
+        return signal
+            ? AbortSignal.any([signal, this.lifecycleAbortController.signal])
+            : this.lifecycleAbortController.signal;
+    }
+    fetch(input, init = {}) {
+        return fetch(input, { ...init, signal: this.withLifecycleSignal(init.signal) });
+    }
+    constructor(config, logger, dependencies = {}) {
         this.config = config;
         this.logger = logger;
+        this.authSession = new AuthSessionService(config);
+        this.modelGovernance = new ModelGovernance({
+            hasCloudAccess: () => this.config.hasCloudAccess(),
+            hasSelfHostedEndpoint: () => Boolean(this.selfHostedModelRouterClient),
+            simulateCloudFailure: () => process.env.VIGTHORIA_SIMULATE_CLOUD_FAILURE === '1',
+            debug: (message) => this.logger.debug(message),
+        });
+        this.codeOperations = new CodeOperationsService((systemPrompt, userPrompt, model, maxTokens) => this.chatComplete(systemPrompt, userPrompt, model, maxTokens));
+        this.mcpContextClient = new McpContextClient({
+            getBaseUrls: () => this.getMcpBaseUrls(),
+            getAccessToken: () => this.getAccessToken(),
+            fetch: (input, init) => this.fetch(input, init),
+            sanitizeError: sanitizeUserFacingErrorText,
+            debug: (message, detail) => this.logger.debug(message, detail),
+        });
+        this.v3AgentClient = new V3AgentClient({
+            getConfiguredApiUrl: () => String(this.config.get('apiUrl') || 'https://coder.vigthoria.io'),
+            getAccessToken: () => this.getAccessToken(),
+            getServiceKey: () => this.config.get('v3ServiceKey'),
+            setServiceKey: (key) => this.config.set('v3ServiceKey', key),
+            fetchServiceKey: async (token) => {
+                const response = await this.client.get('/api/cli/v3-service-key', {
+                    headers: { Authorization: `Bearer ${token}` }, timeout: 6000,
+                });
+                return response.data?.v3ServiceKey || null;
+            },
+            refreshToken: () => this.refreshToken(),
+            fetch: (input, init) => this.fetch(input, init),
+            sanitizeError: sanitizeUserFacingErrorText,
+            debug: (message) => this.logger.debug(message),
+        });
+        this.v3WorkspaceService = new V3WorkspaceService({
+            resolveTargetPath: (context) => this.resolveAgentTargetPath(context),
+            warn: (message) => this.logger.warn(message),
+        });
+        this.capabilityHealthService = new CapabilityHealthService({
+            getCoderHealth: () => this.getCoderHealth(),
+            getModelsHealth: () => this.getModelsHealth(),
+            getSelfHostedHealth: () => this.getSelfHostedHealth(),
+            getV3Health: () => this.getV3AgentHealth(),
+            getHyperLoopHealth: () => this.getHyperLoopHealth(),
+            getRepoMemoryHealth: (context) => this.getRepoMemoryHealth(context),
+            getDevtoolsBridgeHealth: () => this.probeDevtoolsBridgeStatus(),
+            modelUsesV3: (requestedModel) => this.modelGovernance.isSelfHostedPreferredModel(this.resolveModelId(requestedModel), requestedModel),
+        });
+        this.modelTransportService = new ModelTransportService({
+            resolveModelId: (model) => this.modelGovernance.resolveModelId(model),
+            resolvePermittedModelId: (model) => this.modelGovernance.resolvePermittedModelId(model),
+            hasCloudAccess: () => this.config.hasCloudAccess(),
+            isAuthenticated: () => this.config.isAuthenticated(),
+            isCloudModelId: (model) => this.modelGovernance.isCloudModelId(model),
+            shouldSkipCloudRoutes: (model) => this.modelGovernance.shouldSkipCloudRoutes(model),
+            isSelfHostedPreferred: (model, requested) => this.modelGovernance.isSelfHostedPreferredModel(model, requested),
+            shouldTrySelfHosted: (model, requested) => this.modelGovernance.shouldTrySelfHostedFallback(model, requested),
+            getSelfHostedFallback: (model, requested) => this.modelGovernance.getSelfHostedFallbackModelId(model, requested),
+            getFallbackModel: (model) => this.modelGovernance.getFallbackModelId(model),
+            getMaxTokens: () => this.config.get('preferences').maxTokens,
+            hasSelfHostedTransport: () => Boolean(this.selfHostedModelRouterClient),
+            postModels: async (body) => (await this.modelRouterClient.post('/v1/chat/completions', body)).data,
+            postCoder: async (body) => (await this.client.post('/api/ai/chat', body)).data,
+            postCanonicalCoder: async (body) => {
+                const endpoint = 'https://coder.vigthoria.io/api/ai/chat';
+                const token = this.getAccessToken();
+                assertTrustedEndpoint(endpoint, { audience: 'coder', credentialBearing: Boolean(token) });
+                return (await axios.post(endpoint, body, {
+                    timeout: 180000,
+                    httpsAgent: this._httpsAgent ?? undefined,
+                    headers: token ? { Authorization: `Bearer ${token}`, Cookie: `vigthoria-auth-token=${token}` } : {},
+                    signal: this.withLifecycleSignal(),
+                    maxRedirects: 0,
+                })).data;
+            },
+            postSelfHosted: async (body) => {
+                if (!this.selfHostedModelRouterClient)
+                    throw new Error('Dedicated model transport is unavailable.');
+                return (await this.selfHostedModelRouterClient.post('/v1/chat/completions', body, { headers: { 'x-agent-mode': 'true' } })).data;
+            },
+            debug: (message) => this.logger.debug(message),
+        });
+        this.operatorClient = new OperatorClient({
+            getBaseUrls: () => this.getOperatorBaseUrls(),
+            getAuthToken: () => this.config.get('authToken'),
+            fetch: (input, init) => this.fetch(input, init),
+            sanitizeError: sanitizeUserFacingErrorText,
+        });
+        this.frontendPreviewService = new FrontendPreviewService({
+            getBaseUrls: () => this.getTemplateServiceBaseUrls(),
+            getAccessToken: () => this.getAccessToken(),
+            fetch: (input, init) => this.fetch(input, init),
+            resolveTargetPath: (context) => this.resolveAgentTargetPath(context),
+            extractExpectedFiles: (message, context) => this.extractExpectedWorkspaceFiles(message, context),
+            isAnalysisOnlyTask: (message, context) => this.isAnalysisOnlyTask(message, context),
+            sanitizeError: sanitizeUserFacingErrorText,
+            screenshotAdapter: dependencies.screenshotAdapter || new OptionalPuppeteerScreenshotAdapter(),
+        });
+        this.vigFlowClient = new VigFlowClient({
+            getBaseUrls: () => this.getVigFlowBaseUrls(),
+            getAccessToken: () => this.getAccessToken(),
+            debug: (message, detail) => this.logger.debug(message, detail),
+        });
+        this.unsubscribeAuthInvalidation = subscribeAuthInvalidation(() => {
+            this.vigFlowClient.clearCredentials();
+        });
+        installGlobalFetchPolicy();
         // Create HTTPS agent with proper settings for cross-platform compatibility
         const httpsAgent = new https.Agent({
             rejectUnauthorized: true, // Enforce SSL verification
@@ -358,11 +472,22 @@ export class APIClient {
                 'User-Agent': `Vigthoria-CLI/${process.env.npm_package_version || '1.6.9'}`,
             },
         }) : null;
+        installAxiosNetworkPolicy(this.client, 'coder');
+        installAxiosNetworkPolicy(this.modelRouterClient, 'models');
+        if (this.selfHostedModelRouterClient)
+            installAxiosNetworkPolicy(this.selfHostedModelRouterClient, 'models');
+        for (const client of [this.client, this.modelRouterClient, this.selfHostedModelRouterClient].filter(Boolean)) {
+            client.interceptors.request.use((request) => {
+                request.signal = this.withLifecycleSignal(request.signal);
+                return request;
+            });
+        }
         // Add auth interceptor
         this.client.interceptors.request.use((req) => {
             const token = this.getAccessToken();
             const destination = resolveAxiosRequestUrl(req);
-            if (token && isTrustedTokenDestination(destination)) {
+            if (token) {
+                assertTrustedEndpoint(destination, { audience: 'coder', credentialBearing: true });
                 req.headers.Authorization = `Bearer ${token}`;
                 req.headers.Cookie = `vigthoria-auth-token=${token}`;
             }
@@ -371,7 +496,8 @@ export class APIClient {
         this.modelRouterClient.interceptors.request.use((req) => {
             const token = this.getAccessToken();
             const destination = resolveAxiosRequestUrl(req);
-            if (token && isTrustedTokenDestination(destination)) {
+            if (token) {
+                assertTrustedEndpoint(destination, { audience: 'models', credentialBearing: true });
                 req.headers.Authorization = `Bearer ${token}`;
                 req.headers.Cookie = `vigthoria-auth-token=${token}`;
             }
@@ -380,7 +506,8 @@ export class APIClient {
         this.selfHostedModelRouterClient?.interceptors.request.use((req) => {
             const token = this.getAccessToken();
             const destination = resolveAxiosRequestUrl(req);
-            if (token && isTrustedTokenDestination(destination)) {
+            if (token) {
+                assertTrustedEndpoint(destination, { audience: 'models', credentialBearing: true });
                 req.headers.Authorization = `Bearer ${token}`;
             }
             return req;
@@ -411,17 +538,13 @@ export class APIClient {
      * on Windows / Node 25+.
      */
     destroy() {
+        this.lifecycleAbortController.abort();
+        this.unsubscribeAuthInvalidation?.();
+        this.unsubscribeAuthInvalidation = null;
         if (this._httpsAgent) {
             this._httpsAgent.destroy();
             this._httpsAgent = null;
         }
-        if (this.ws) {
-            try {
-                this.ws.close();
-            }
-            catch { /* ok */ }
-            this.ws = null;
-        }
     }
     /** Exposed for Balanced 4B agent routing (local inference :8016). */
     getSelfHostedModelsApiUrl() {
@@ -441,10 +564,8 @@ export class APIClient {
                 throw new Error(response.data.error || 'Login failed');
             }
             const { token, user } = response.data;
-            this.config.setAuth({
-                token,
-                userId: user.id,
-                email: user.email,
+            await this.authSession.validateAndPersistToken(token, {
+                identity: { userId: user.id, email: user.email },
             });
             // Set subscription from user data
             this.config.setSubscription({
@@ -463,92 +584,16 @@ export class APIClient {
     }
     async loginWithToken(token) {
         try {
-            // Validate token by making a request to user info endpoint
-            this.config.set('authToken', token);
-            const headers = {
-                Authorization: `Bearer ${token}`,
-                Cookie: `vigthoria-auth-token=${token}`,
-            };
-            const candidateEndpoints = [
-                '/api/user/profile',
-                '/api/user/info',
-                '/api/auth/me',
-            ];
-            for (const endpoint of candidateEndpoints) {
-                try {
-                    const response = await this.client.get(endpoint, { headers });
-                    const profile = this.extractUserProfile(response.data);
-                    if (!profile) {
-                        continue;
-                    }
-                    this.config.setAuth({
-                        token,
-                        userId: profile.id,
-                        email: profile.email,
-                    });
-                    this.config.setSubscription({
-                        plan: profile.plan,
-                        status: 'active',
-                        expiresAt: undefined,
-                    });
-                    return true;
-                }
-                catch (error) {
-                    const axiosError = error;
-                    if (axiosError.response?.status && axiosError.response.status !== 404) {
-                        throw error;
-                    }
-                }
-            }
-            this.config.clearAuth();
-            return false;
+            await this.authSession.validateAndPersistToken(token);
+            return true;
         }
         catch (error) {
-            this.config.clearAuth();
             this.logger.error('Token validation failed:', error.message);
             return false;
         }
     }
-    extractUserProfile(data) {
-        if (!data) {
-            return null;
-        }
-        const rawUser = data.user || data;
-        const userId = rawUser.id;
-        const email = rawUser.email;
-        if (!userId || !email) {
-            return null;
-        }
-        const plan = data.subscription?.plan
-            || rawUser.subscription?.plan
-            || rawUser.subscription_plan
-            || data.subscription_plan
-            || 'community';
-        return {
-            id: userId,
-            email,
-            plan,
-        };
-    }
     async refreshToken() {
-        const refreshToken = this.config.get('refreshToken');
-        if (!refreshToken)
-            return false;
-        try {
-            const response = await this.client.post('/api/token/refresh', {
-                refresh_token: refreshToken
-            });
-            const { token, access_token, refresh_token } = response.data;
-            this.config.set('authToken', token || access_token);
-            if (refresh_token) {
-                this.config.set('refreshToken', refresh_token);
-            }
-            return true;
-        }
-        catch {
-            this.config.clearAuth();
-            return false;
-        }
+        return this.authSession.refresh();
     }
     async getSubscriptionStatus() {
         try {
@@ -565,10 +610,7 @@ export class APIClient {
         }
     }
     getAccessToken() {
-        return process.env.VIGTHORIA_TOKEN
-            || process.env.VIGTHORIA_AUTH_TOKEN
-            || this.config.get('authToken')
-            || null;
+        return this.authSession.getAccessToken();
     }
     /**
      * Validate the current auth token against the Coder API.
@@ -648,63 +690,22 @@ export class APIClient {
         return { valid: true };
     }
     isDirectV3AgentBaseUrl(baseUrl) {
-        try {
-            const parsed = new URL(String(baseUrl));
-            return parsed.port === '8030' || parsed.port.endsWith('8030');
-        }
-        catch {
-            return /(?:127\.0\.0\.1|localhost|172\.19\.0\.1|host\.lan):(?:\d*8030|8030)/.test(String(baseUrl));
-        }
+        return this.v3AgentClient.isDirectBaseUrl(baseUrl);
     }
     getV3AgentBaseUrls(preferLocal = false) {
-        const configuredApiUrl = String(this.config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
-        const localTestMode = isLocalTestfarmMode();
-        const explicitV3EndpointConfigured = Boolean(process.env.VIGTHORIA_V3_AGENT_URL || process.env.V3_AGENT_URL);
-        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,
-            ...(includeLoopbackV3Agent ? ['http://127.0.0.1:8030'] : []),
-        ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
-        const remoteCandidates = localTestMode
-            ? [configuredApiUrl]
-            : [configuredApiUrl, 'https://coder.vigthoria.io'];
-        const normalizedRemote = remoteCandidates
-            .filter(Boolean)
-            .map((url) => String(url).replace(/\/$/, ''));
-        // An explicit V3 endpoint is an operator routing decision, not a fallback.
-        // Keep it ahead of the public Coder relay so stale remote user credentials
-        // cannot abort a healthy service-key-authenticated internal CLI run.
-        const urls = (preferLocal || localTestMode || explicitV3EndpointConfigured) && localCandidates.length > 0
-            ? [...localCandidates, ...normalizedRemote]
-            : [...normalizedRemote, ...localCandidates];
-        return [...new Set(urls)];
+        return this.v3AgentClient.getBaseUrls(preferLocal);
     }
     getV3AgentRunUrl(baseUrl) {
-        if (this.isDirectV3AgentBaseUrl(baseUrl)) {
-            return `${baseUrl}/api/agent/run`;
-        }
-        return `${baseUrl}/api/v3-agent/run`;
+        return this.v3AgentClient.runUrl(baseUrl);
     }
     getV3AgentContinueUrl(baseUrl) {
-        if (this.isDirectV3AgentBaseUrl(baseUrl)) {
-            return `${baseUrl}/api/agent/continue`;
-        }
-        return `${baseUrl}/api/v3-agent/continue`;
+        return this.v3AgentClient.continueUrl(baseUrl);
     }
     getV3AgentBackgroundUrl(baseUrl, suffix = '') {
-        const cleanSuffix = suffix ? `/${suffix.replace(/^\/+/, '')}` : '';
-        if (this.isDirectV3AgentBaseUrl(baseUrl)) {
-            return `${baseUrl}/api/agent/background${cleanSuffix}`;
-        }
-        return `${baseUrl}/api/v3-agent/background${cleanSuffix}`;
+        return this.v3AgentClient.backgroundUrl(baseUrl, suffix);
     }
     getV3AgentApprovalUrl(baseUrl) {
-        if (this.isDirectV3AgentBaseUrl(baseUrl)) {
-            return `${baseUrl}/api/agent/approval`;
-        }
-        return `${baseUrl}/api/v3-agent/approval`;
+        return this.v3AgentClient.approvalUrl(baseUrl);
     }
     getOperatorBaseUrls() {
         const configuredModelsApiUrl = String(this.config.get('modelsApiUrl') || 'https://api.vigthoria.io').replace(/\/$/, '');
@@ -717,9 +718,6 @@ export class APIClient {
         ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
         return [...new Set(urls)];
     }
-    getOperatorStreamUrl(baseUrl) {
-        return `${baseUrl}/api/operator/stream`;
-    }
     getMcpBaseUrls() {
         const configuredApiUrl = String(this.config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
         const localTestMode = isLocalTestfarmMode();
@@ -765,22 +763,6 @@ export class APIClient {
         ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
         return [...new Set(urls)];
     }
-    isFrontendTask(message = '', context = {}) {
-        // Never treat analysis-only tasks as frontend tasks — preview gate
-        // should not fire for read-only inspection prompts.
-        if (this.isAnalysisOnlyTask(message, context)) {
-            return false;
-        }
-        const prompt = String(message || '');
-        const expectedFiles = this.extractExpectedWorkspaceFiles(message, context);
-        const hasHtmlEntry = expectedFiles.some((filePath) => /\.html?$/i.test(filePath));
-        return /(premium|polished|landing|site|page|dashboard|saas|frontend|ui|pricing|showcase|hero|responsive)/i.test(prompt)
-            || hasHtmlEntry;
-    }
-    /**
-     * Returns true when the prompt describes a read-only / analysis task.
-     * Used to suppress preview gate and other write-oriented side effects.
-     */
     isAnalysisOnlyTask(message = '', context = {}) {
         const prompt = String(message || '').toLowerCase();
         const taskType = String(context.agentTaskType || '').toLowerCase();
@@ -790,801 +772,51 @@ export class APIClient {
             return true;
         return /^(what|which|how many|list|show|check|inspect|analyze|analyse|audit|explain|describe|summarize|summarise|review|overview|find|count|read|look at|tell me|diagnos)/i.test(prompt.trim());
     }
+    runTemplateServicePreviewGate(message = '', context = {}) {
+        return this.frontendPreviewService.runTemplateServicePreviewGate(message, context);
+    }
     normalizeWorkspaceRelativePath(filePath) {
-        return String(filePath || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+        return this.frontendPreviewService.normalizeWorkspaceRelativePath(filePath);
     }
     collectAgentStateSyncPaths(rootPath) {
-        const paths = [];
-        const progressPath = path.join(rootPath, '.vigthoria', 'agent-state', 'progress.json');
-        if (!fs.existsSync(progressPath)) {
-            return paths;
-        }
-        paths.push('.vigthoria/agent-state/progress.json');
-        const tasksDir = path.join(rootPath, '.vigthoria', 'agent-state', 'tasks');
-        if (!fs.existsSync(tasksDir)) {
-            return paths;
-        }
-        try {
-            for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
-                if (!entry.isFile() || !entry.name.endsWith('.json')) {
-                    continue;
-                }
-                paths.push(`.vigthoria/agent-state/tasks/${entry.name}`);
-            }
-        }
-        catch {
-            // Ignore unreadable task snapshots.
-        }
-        return paths;
-    }
-    listFrontendWorkspaceFiles(rootPath) {
-        const results = [];
-        const stack = [rootPath];
-        while (stack.length > 0) {
-            const current = stack.pop();
-            if (!current) {
-                continue;
-            }
-            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-                if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.vigthoria') {
-                    continue;
-                }
-                const fullPath = path.join(current, entry.name);
-                if (entry.isDirectory()) {
-                    stack.push(fullPath);
-                    continue;
-                }
-                if (!entry.isFile()) {
-                    continue;
-                }
-                const relativePath = this.normalizeWorkspaceRelativePath(path.relative(rootPath, fullPath));
-                if (relativePath) {
-                    results.push(relativePath);
-                }
-            }
-        }
-        results.sort((left, right) => left.localeCompare(right));
-        return results;
-    }
-    chooseFrontendPreviewEntry(rootPath, htmlPaths, expectedFiles = []) {
-        const normalizedExpected = expectedFiles
-            .map((filePath) => this.normalizeWorkspaceRelativePath(filePath))
-            .filter((filePath) => /\.html?$/i.test(filePath));
-        for (const expectedPath of normalizedExpected) {
-            if (htmlPaths.includes(expectedPath)) {
-                return expectedPath;
-            }
-        }
-        const scored = htmlPaths.map((relativePath) => {
-            const baseName = path.posix.basename(relativePath).toLowerCase();
-            const depth = relativePath.split('/').length - 1;
-            let score = 0;
-            const normalizedPath = relativePath.toLowerCase();
-            const topLevelDir = normalizedPath.split('/')[0];
-            if (['dist', 'build', 'out'].includes(topLevelDir)) {
-                score += 320;
-            }
-            else if (topLevelDir === 'public') {
-                score += 180;
-            }
-            if (normalizedPath === 'index.html') {
-                score += 200;
-            }
-            if (baseName === 'index.html') {
-                score += 120;
-            }
-            if (/(landing|home|main|dashboard|app)/i.test(baseName)) {
-                score += 60;
-            }
-            if (depth === 0) {
-                score += 40;
-            }
-            return { relativePath, score, depth };
-        }).sort((left, right) => right.score - left.score || left.depth - right.depth || left.relativePath.localeCompare(right.relativePath));
-        return scored[0]?.relativePath || null;
+        return this.frontendPreviewService.collectAgentStateSyncPaths(rootPath);
     }
     extractLinkedFrontendAssets(html, entryPath) {
-        const css = new Set();
-        const js = new Set();
-        const assets = new Set();
-        const entryDir = path.posix.dirname(this.normalizeWorkspaceRelativePath(entryPath) || '.');
-        const normalizeAsset = (assetPath) => {
-            const clean = String(assetPath || '').trim();
-            if (!clean || clean.startsWith('http://') || clean.startsWith('https://') || clean.startsWith('//') || clean.startsWith('data:') || clean.startsWith('#')) {
-                return null;
-            }
-            const withoutQuery = clean.split('?')[0].split('#')[0];
-            if (!withoutQuery) {
-                return null;
-            }
-            if (withoutQuery.startsWith('/')) {
-                // Preview/runtime serve a nested HTML entry from its containing
-                // directory, so `/styles.css` beside `showcase/index.html` resolves to
-                // `showcase/styles.css` in the hydrated workspace.
-                return this.normalizeWorkspaceRelativePath(path.posix.normalize(path.posix.join(entryDir, withoutQuery.slice(1))));
-            }
-            return this.normalizeWorkspaceRelativePath(path.posix.normalize(path.posix.join(entryDir, withoutQuery)));
-        };
-        const cssPattern = /<link[^>]+href=["']([^"']+\.css(?:[?#][^"']*)?)["'][^>]*>/gi;
-        const jsPattern = /<script[^>]+src=["']([^"']+\.(?:js|mjs|cjs)(?:[?#][^"']*)?)["'][^>]*>/gi;
-        let match;
-        while ((match = cssPattern.exec(String(html || ''))) !== null) {
-            const resolved = normalizeAsset(match[1]);
-            if (resolved) {
-                css.add(resolved);
-            }
-        }
-        while ((match = jsPattern.exec(String(html || ''))) !== null) {
-            const resolved = normalizeAsset(match[1]);
-            if (resolved) {
-                js.add(resolved);
-            }
-        }
-        const assetPattern = /<(?:link|img|source|video|audio)\b[^>]+(?:href|src)=["']([^"']+)["'][^>]*>/gi;
-        while ((match = assetPattern.exec(String(html || ''))) !== null) {
-            const resolved = normalizeAsset(match[1]);
-            if (resolved) {
-                assets.add(resolved);
-            }
-        }
-        return {
-            css: Array.from(css),
-            js: Array.from(js),
-            assets: Array.from(assets),
-        };
-    }
-    async buildFrontendForPreview(rootPath) {
-        const packagePath = path.join(rootPath, 'package.json');
-        if (!fs.existsSync(packagePath)) {
-            return { attempted: false, succeeded: false };
-        }
-        try {
-            const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-            if (!packageJson.scripts?.build) {
-                return { attempted: false, succeeded: false };
-            }
-        }
-        catch (error) {
-            return { attempted: false, succeeded: false, error: `Invalid package.json: ${error?.message || String(error)}` };
-        }
-        const npmCommand = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'npm';
-        const npmArgs = process.platform === 'win32'
-            ? ['/d', '/s', '/c', 'npm run build']
-            : ['run', 'build'];
-        return await new Promise((resolve) => {
-            execFile(npmCommand, npmArgs, { cwd: rootPath, timeout: 150_000, windowsHide: true, maxBuffer: 2 * 1024 * 1024 }, (error) => {
-                if (error) {
-                    resolve({ attempted: true, succeeded: false, error: sanitizeUserFacingErrorText(error.message).slice(0, 300) });
-                    return;
-                }
-                resolve({ attempted: true, succeeded: true });
-            });
-        });
-    }
-    gatherFrontendPreviewArtifacts(message = '', context = {}) {
-        const rootPath = this.resolveAgentTargetPath(context);
-        if (!rootPath || !fs.existsSync(rootPath)) {
-            return { error: 'Frontend preview gate requires a readable project workspace.' };
-        }
-        const workspaceFiles = this.listFrontendWorkspaceFiles(rootPath);
-        const expectedFiles = this.extractExpectedWorkspaceFiles(message, context);
-        const htmlPaths = workspaceFiles.filter((filePath) => /\.html?$/i.test(filePath));
-        if (htmlPaths.length === 0) {
-            return { error: 'Frontend preview gate requires at least one HTML entry file in the workspace.' };
-        }
-        const htmlPath = this.chooseFrontendPreviewEntry(rootPath, htmlPaths, expectedFiles);
-        if (!htmlPath) {
-            return { error: 'Frontend preview gate could not determine a primary HTML entry file.' };
-        }
-        const html = fs.readFileSync(path.join(rootPath, htmlPath), 'utf8');
-        const linkedAssets = this.extractLinkedFrontendAssets(html, htmlPath);
-        const cssFiles = workspaceFiles.filter((filePath) => /\.css$/i.test(filePath));
-        const jsFiles = workspaceFiles.filter((filePath) => /\.(?:js|mjs|cjs)$/i.test(filePath));
-        const expectedCss = expectedFiles
-            .map((filePath) => this.normalizeWorkspaceRelativePath(filePath))
-            .filter((filePath) => /\.css$/i.test(filePath));
-        const expectedJs = expectedFiles
-            .map((filePath) => this.normalizeWorkspaceRelativePath(filePath))
-            .filter((filePath) => /\.(?:js|mjs|cjs)$/i.test(filePath));
-        const chooseExisting = (candidates, fallback) => {
-            const selected = new Set();
-            for (const candidate of [...candidates, ...fallback]) {
-                const normalized = this.normalizeWorkspaceRelativePath(candidate);
-                if (!normalized || selected.has(normalized)) {
-                    continue;
-                }
-                if (!fs.existsSync(path.join(rootPath, normalized))) {
-                    continue;
-                }
-                selected.add(normalized);
-            }
-            return Array.from(selected);
-        };
-        const selectedCssFiles = chooseExisting(linkedAssets.css, [...expectedCss, ...cssFiles]).slice(0, 12);
-        const selectedJsFiles = chooseExisting(linkedAssets.js, [...expectedJs, ...jsFiles]).slice(0, 12);
-        const css = selectedCssFiles.map((filePath) => fs.readFileSync(path.join(rootPath, filePath), 'utf8')).join('\n\n');
-        const js = selectedJsFiles.map((filePath) => fs.readFileSync(path.join(rootPath, filePath), 'utf8')).join('\n\n');
-        return { htmlPath, html, css, js, cssPaths: selectedCssFiles, jsPaths: selectedJsFiles };
-    }
-    async captureFrontendPreviewScreenshot(entryAbsolutePath, screenshotPath) {
-        try {
-            const puppeteerModule = await import('puppeteer').catch(() => null);
-            const puppeteer = puppeteerModule?.default || puppeteerModule;
-            if (!puppeteer || typeof puppeteer.launch !== 'function') {
-                return { captured: false, error: 'puppeteer-unavailable' };
-            }
-            const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox', '--disable-setuid-sandbox'] });
-            try {
-                const page = await browser.newPage();
-                await page.setViewport({ width: 1440, height: 960, deviceScaleFactor: 1 });
-                await page.goto(`file://${entryAbsolutePath}`, { waitUntil: 'networkidle0', timeout: 20000 });
-                await page.screenshot({ path: screenshotPath, fullPage: true });
-            }
-            finally {
-                await browser.close();
-            }
-            return { captured: true };
-        }
-        catch (error) {
-            return { captured: false, error: error?.message || String(error) };
-        }
+        return this.frontendPreviewService.extractLinkedFrontendAssets(html, entryPath);
     }
-    evaluateFrontendVisualProof(summary = {}, artifacts = {}) {
-        const reasons = [];
-        const cssPaths = Array.isArray(artifacts.cssPaths) ? artifacts.cssPaths : [];
-        const html = String(artifacts.html || '');
-        const css = String(artifacts.css || '');
-        const js = String(artifacts.js || '');
-        if (!summary.hasViewportMeta) {
-            reasons.push('missing viewport metadata');
-        }
-        const hasStyleEvidence = cssPaths.length > 0 || /<style[\s>]/i.test(html) || css.trim().length > 0;
-        if (!hasStyleEvidence) {
-            reasons.push('missing stylesheet or inline style evidence');
-        }
-        const hasInteractionOrResponsiveEvidence = Boolean(summary.hasResponsiveSignals) || Boolean(summary.hasInteractiveSignals) || /<script[\s>]/i.test(html) || js.trim().length > 0;
-        if (!hasInteractionOrResponsiveEvidence) {
-            reasons.push('missing responsive or interactive evidence');
-        }
-        return {
-            ok: reasons.length === 0,
-            reasons,
-        };
+    listVigFlowTemplates(options = {}) {
+        return this.vigFlowClient.listTemplates(options);
     }
-    async persistFrontendPreviewArtifacts(previewGate, rootPath, context = {}) {
-        if (!previewGate.required || !previewGate.entryPath) {
-            return previewGate;
-        }
-        try {
-            const artifactsDir = path.join(rootPath, '.vigthoria', 'proof', 'preview');
-            fs.mkdirSync(artifactsDir, { recursive: true });
-            const contextId = String(context.contextId || 'preview').trim() || 'preview';
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-            const baseName = `${timestamp}-${contextId}`;
-            const manifestPath = path.join(artifactsDir, `${baseName}.json`);
-            const screenshotPath = path.join(artifactsDir, `${baseName}.png`);
-            const entryAbsolutePath = path.join(rootPath, previewGate.entryPath);
-            const previewFileUrl = `file://${entryAbsolutePath}`;
-            const screenshot = await this.captureFrontendPreviewScreenshot(entryAbsolutePath, screenshotPath);
-            const manifest = {
-                schemaVersion: 1,
-                createdAt: new Date().toISOString(),
-                contextId: context.contextId || null,
-                workspaceRoot: rootPath,
-                entryPath: previewGate.entryPath,
-                previewFileUrl,
-                previewCommand: `vigthoria preview -p ${rootPath}`,
-                previewGate,
-                validationArtifacts: {
-                    summary: previewGate.summary || {},
-                    modes: previewGate.modes || {},
-                    backendUrl: previewGate.backendUrl || null,
-                    processingTimeMs: previewGate.processingTimeMs || null,
-                    assetPaths: previewGate.assetPaths || { css: [], js: [] },
-                },
-                screenshot: {
-                    path: screenshot.captured ? screenshotPath : null,
-                    captured: screenshot.captured,
-                    error: screenshot.error || null,
-                },
-            };
-            fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-            return {
-                ...previewGate,
-                artifacts: {
-                    manifestPath,
-                    screenshotPath: screenshot.captured ? screenshotPath : undefined,
-                    previewFileUrl,
-                    screenshotCaptured: screenshot.captured,
-                    screenshotError: screenshot.error,
-                },
-            };
-        }
-        catch (error) {
-            return {
-                ...previewGate,
-                artifacts: {
-                    ...(previewGate.artifacts || {}),
-                    screenshotCaptured: false,
-                    screenshotError: error?.message || String(error),
-                },
-            };
-        }
+    listVigFlowWorkflows() {
+        return this.vigFlowClient.listWorkflows();
     }
-    async runTemplateServicePreviewGate(message = '', context = {}) {
-        if (!this.isFrontendTask(message, context)) {
-            return { required: false, passed: true };
-        }
-        const rootPath = this.resolveAgentTargetPath(context);
-        let artifacts = this.gatherFrontendPreviewArtifacts(message, context);
-        let buildResult = null;
-        if (rootPath && artifacts.error?.includes('at least one HTML entry file')) {
-            buildResult = await this.buildFrontendForPreview(rootPath);
-            if (buildResult.attempted) {
-                artifacts = this.gatherFrontendPreviewArtifacts(message, context);
-            }
-        }
-        if (artifacts.error || !artifacts.htmlPath || typeof artifacts.html !== 'string') {
-            const buildDetail = buildResult?.attempted
-                ? ` Build retry ${buildResult.succeeded ? 'completed but produced no HTML entry' : `failed: ${buildResult.error || 'unknown build error'}`}.`
-                : '';
-            return {
-                required: true,
-                passed: false,
-                error: `${artifacts.error || 'Frontend preview gate could not collect frontend artifacts.'}${buildDetail}`,
-            };
-        }
-        // Cap artifact sizes to prevent 413 Payload Too Large
-        const PREVIEW_MAX_ARTIFACT_BYTES = 250 * 1024;
-        const html = artifacts.html.slice(0, PREVIEW_MAX_ARTIFACT_BYTES);
-        const css = (artifacts.css || '').slice(0, PREVIEW_MAX_ARTIFACT_BYTES);
-        const js = (artifacts.js || '').slice(0, PREVIEW_MAX_ARTIFACT_BYTES);
-        const errors = [];
-        for (const baseUrl of this.getTemplateServiceBaseUrls()) {
-            try {
-                const proofPayload = JSON.stringify({
-                    vision: String(context.rawPrompt || message || '').slice(0, 2000),
-                    html,
-                    css,
-                    js,
-                    entryPath: artifacts.htmlPath,
-                    workspaceName: path.basename(rootPath),
-                });
-                // Skip preview proof if payload is still too large (> 4 MB)
-                if (Buffer.byteLength(proofPayload, 'utf8') > 4 * 1024 * 1024) {
-                    return {
-                        required: true,
-                        passed: true,
-                        error: 'Preview proof skipped: payload exceeds size limit.',
-                    };
-                }
-                const internalServiceKey = process.env.VIGTHORIA_TEMPLATE_SERVICE_KEY
-                    || process.env.V3_SERVICE_KEY;
-                const authToken = this.getAccessToken();
-                const response = await fetch(`${baseUrl}/preview-proof`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Accept: 'application/json',
-                        ...(authToken ? {
-                            Authorization: `Bearer ${authToken}`,
-                            Cookie: `vigthoria-auth-token=${authToken}`,
-                        } : {}),
-                        ...(internalServiceKey ? { 'x-vigthoria-service-key': internalServiceKey } : {}),
-                    },
-                    body: proofPayload,
-                });
-                if (!response.ok) {
-                    const errorText = await response.text().catch(() => '');
-                    throw new Error(`Template preview proof ${response.status}: ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
-                }
-                const payload = await response.json();
-                const modes = payload?.modes || {};
-                const summary = payload?.summary || {};
-                const visualProof = this.evaluateFrontendVisualProof(summary, artifacts);
-                const passed = payload?.success === true
-                    && modes?.design?.ready === true
-                    && modes?.live?.ready === true
-                    && modes?.production?.ready === true
-                    && visualProof.ok;
-                const previewGate = {
-                    required: true,
-                    passed,
-                    backendUrl: baseUrl,
-                    entryPath: artifacts.htmlPath,
-                    assetPaths: {
-                        css: artifacts.cssPaths || [],
-                        js: artifacts.jsPaths || [],
-                    },
-                    modes,
-                    summary,
-                    processingTimeMs: Number(payload?.processing_time || 0) || undefined,
-                    error: passed ? undefined : (visualProof.ok ? 'Template Service preview modes did not all report ready.' : `Frontend preview proof is missing required visual evidence: ${visualProof.reasons.join(', ')}.`),
-                };
-                return await this.persistFrontendPreviewArtifacts(previewGate, rootPath, context);
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        return await this.persistFrontendPreviewArtifacts({
-            required: true,
-            passed: false,
-            entryPath: artifacts.htmlPath,
-            assetPaths: {
-                css: artifacts.cssPaths || [],
-                js: artifacts.jsPaths || [],
-            },
-            error: errors.join(' | ') || 'No Template Service preview endpoint was reachable.',
-        }, rootPath, context);
+    resolveVigFlowWorkflow(selector) {
+        return this.vigFlowClient.resolveWorkflow(selector);
     }
-    getMcpContextCreateUrl(baseUrl) {
-        return `${baseUrl}/mcp/context/create`;
+    useVigFlowTemplate(templateId, options = {}) {
+        return this.vigFlowClient.useTemplate(templateId, options);
     }
-    getMcpContextUrl(baseUrl, contextId) {
-        return `${baseUrl}/mcp/context/${encodeURIComponent(contextId)}`;
+    runVigFlowWorkflow(workflowId, options = {}) {
+        return this.vigFlowClient.runWorkflow(workflowId, options);
     }
-    async getMcpHeaders() {
-        const headers = {
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-        };
-        const authToken = this.getAccessToken();
-        if (authToken) {
-            headers.Authorization = `Bearer ${authToken}`;
-            headers.Cookie = `vigthoria-auth-token=${authToken}`;
-            headers['X-Vigthoria-Token'] = authToken;
-            headers['X-Auth-Token'] = authToken;
-        }
-        return headers;
+    getVigFlowExecutionStatus(executionId) {
+        return this.vigFlowClient.executionStatus(executionId);
     }
     async getV3AgentHeaders() {
-        const headers = {
-            'Content-Type': 'application/json',
-            Accept: 'text/event-stream',
-        };
-        const authToken = this.getAccessToken();
-        if (authToken) {
-            headers.Authorization = `Bearer ${authToken}`;
-            headers.Cookie = `vigthoria-auth-token=${authToken}`;
-        }
-        const serviceKey = process.env.VIGTHORIA_V3_SERVICE_KEY
-            || process.env.V3_SERVICE_KEY
-            || process.env.HYPERLOOP_SERVICE_KEY
-            || this.config.get('v3ServiceKey');
-        if (serviceKey) {
-            headers['X-Service-Key'] = serviceKey;
-        }
-        return headers;
+        return this.v3AgentClient.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.
-        }
+        return this.v3AgentClient.ensureServiceKey();
     }
     async runV3HealthCheck() {
-        const endpoints = this.getV3AgentBaseUrls(false);
-        const headers = await this.getV3AgentHeaders();
-        const failures = [];
-        for (const baseUrl of endpoints) {
-            const runUrl = this.getV3AgentRunUrl(baseUrl);
-            // Use the lightweight GET /health endpoint — no LLM invocation, responds instantly.
-            // For local 8030 the path is /health directly; for remote it's /api/v3-agent/health via proxy.
-            const healthUrl = this.isDirectV3AgentBaseUrl(baseUrl)
-                ? `${baseUrl}/health`
-                : `${baseUrl}/api/v3-agent/health`;
-            for (let attempt = 1; attempt <= 3; attempt += 1) {
-                try {
-                    const response = await fetch(healthUrl, {
-                        method: 'GET',
-                        headers,
-                        signal: AbortSignal.timeout(8000),
-                    });
-                    if (response.status === 401 || response.status === 403) {
-                        return {
-                            healthy: false,
-                            endpoint: runUrl,
-                            error: 'V3 service rejected authentication. Please re-login to refresh your token.',
-                        };
-                    }
-                    // 200 OK or 405 Method Not Allowed both mean V3 is reachable.
-                    if (response.ok || response.status === 405) {
-                        return { healthy: true, endpoint: runUrl };
-                    }
-                    failures.push(`${healthUrl} attempt ${attempt}: HTTP ${response.status}`);
-                }
-                catch (error) {
-                    const reason = sanitizeUserFacingErrorText(error?.message || String(error)).slice(0, 160);
-                    failures.push(`${healthUrl} attempt ${attempt}: ${reason || 'network error'}`);
-                }
-                if (attempt < 3) {
-                    await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
-                }
-            }
-        }
-        return {
-            healthy: false,
-            endpoint: endpoints[0] ? this.getV3AgentRunUrl(endpoints[0]) : 'unknown',
-            error: `V3 service is not reachable during startup preflight. Checked ${endpoints.length} endpoint(s). ${failures.slice(-3).join(' | ')}`,
-        };
+        return this.v3AgentClient.health();
     }
-    async runV3AgentAuthPreflight(baseUrl, body, executionContext) {
-        const endpoint = this.getV3AgentRunUrl(baseUrl);
-        const healthEndpoint = this.isDirectV3AgentBaseUrl(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);
-        }
+    runV3AgentAuthPreflight(baseUrl, executionContext) {
+        return this.v3AgentClient.preflight(baseUrl, executionContext);
     }
-    async executeV3AgentRunRequest(baseUrl, body, executionContext, signal) {
-        const makeRequest = async () => {
-            const headers = await this.getV3AgentHeaders();
-            if (executionContext.mcpContextId) {
-                headers['X-MCP-Context-Id'] = String(executionContext.mcpContextId);
-            }
-            return fetch(this.getV3AgentRunUrl(baseUrl), {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(body),
-                signal,
-            });
-        };
-        let response = await makeRequest();
-        if (response.status !== 401) {
-            return response;
-        }
-        const refreshed = await this.refreshToken();
-        if (!refreshed) {
-            return response;
-        }
-        response = await makeRequest();
-        return response;
+    executeV3AgentRunRequest(baseUrl, body, executionContext, signal) {
+        return this.v3AgentClient.run(baseUrl, body, executionContext, signal);
     }
-    async getVigFlowAccessToken(baseUrl) {
-        const cachedToken = this.vigFlowTokens.get(baseUrl);
-        if (cachedToken) {
-            return cachedToken;
-        }
-        const authToken = this.getAccessToken();
-        if (!authToken) {
-            throw new Error('Not authenticated. Run vigthoria login first.');
-        }
-        const response = await axios.post(`${baseUrl}/api/auth/sso`, { token: authToken }, {
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            timeout: 30000,
-        });
-        const payload = response.data;
-        const vigFlowToken = String(payload.token || '').trim();
-        if (!vigFlowToken) {
-            throw new Error('VigFlow SSO response did not include a token.');
-        }
-        this.vigFlowTokens.set(baseUrl, vigFlowToken);
-        return vigFlowToken;
-    }
-    async getVigFlowHeaders(baseUrl) {
-        const token = await this.getVigFlowAccessToken(baseUrl);
-        return {
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-            Authorization: `Bearer ${token}`,
-        };
-    }
-    async withVigFlow(operation, action) {
-        let lastError = null;
-        for (const baseUrl of this.getVigFlowBaseUrls()) {
-            try {
-                const headers = await this.getVigFlowHeaders(baseUrl);
-                return await action(baseUrl, headers);
-            }
-            catch (error) {
-                lastError = error;
-                this.logger.debug(`VigFlow ${operation} via ${baseUrl} failed:`, lastError.message);
-            }
-        }
-        // Throw a clean message instead of the raw ECONNREFUSED from the last URL tried
-        throw new Error(`No VigFlow backend available for ${operation}. The workflow service is not deployed or not reachable.`);
-    }
-    /**
-     * Build the correct sub-path for VigFlow endpoints.
-     * Local servers (e.g. localhost:5060) need `/api/…` prefix.
-     * The remote gateway URL already ends with `/api/vigflow`, so appending
-     * another `/api/…` would double the prefix and cause 404s.
-     */
-    vigFlowEndpoint(baseUrl, subPath) {
-        if (/\/api\/vigflow\/?$/i.test(baseUrl)) {
-            // Remote gateway – subPath like '/templates' is enough
-            return `${baseUrl.replace(/\/$/, '')}${subPath}`;
-        }
-        return `${baseUrl}/api${subPath}`;
-    }
-    async listVigFlowTemplates(options = {}) {
-        return this.withVigFlow('list templates', async (baseUrl, headers) => {
-            const query = new URLSearchParams();
-            if (options.category) {
-                query.set('category', options.category);
-            }
-            if (options.search) {
-                query.set('search', options.search);
-            }
-            const url = `${this.vigFlowEndpoint(baseUrl, '/templates')}${query.size > 0 ? `?${query.toString()}` : ''}`;
-            const response = await axios.get(url, {
-                headers,
-                timeout: 30000,
-            });
-            const payload = response.data;
-            return Array.isArray(payload.templates) ? payload.templates : [];
-        });
-    }
-    async listVigFlowWorkflows() {
-        return this.withVigFlow('list workflows', async (baseUrl, headers) => {
-            const response = await axios.get(this.vigFlowEndpoint(baseUrl, '/workflows'), {
-                headers,
-                timeout: 30000,
-            });
-            const payload = response.data;
-            return Array.isArray(payload.workflows) ? payload.workflows : [];
-        });
-    }
-    async resolveVigFlowWorkflow(selector) {
-        const normalizedSelector = String(selector || '').trim();
-        if (!normalizedSelector) {
-            throw new Error('Workflow selector is required. Provide a workflow id or name.');
-        }
-        const workflows = await this.listVigFlowWorkflows();
-        const byId = workflows.find((workflow) => workflow.id === normalizedSelector);
-        if (byId) {
-            return {
-                id: byId.id,
-                name: byId.name,
-                selector: normalizedSelector,
-                matchedBy: 'id',
-            };
-        }
-        const loweredSelector = normalizedSelector.toLowerCase();
-        const exactNameMatches = workflows.filter((workflow) => String(workflow.name || '').trim().toLowerCase() === loweredSelector);
-        if (exactNameMatches.length === 1) {
-            return {
-                id: exactNameMatches[0].id,
-                name: exactNameMatches[0].name,
-                selector: normalizedSelector,
-                matchedBy: 'name',
-            };
-        }
-        if (exactNameMatches.length > 1) {
-            throw new Error(`Multiple workflows matched the name "${normalizedSelector}". Use the workflow id instead.`);
-        }
-        const searchMatches = workflows.filter((workflow) => String(workflow.name || '').toLowerCase().includes(loweredSelector));
-        if (searchMatches.length === 1) {
-            return {
-                id: searchMatches[0].id,
-                name: searchMatches[0].name,
-                selector: normalizedSelector,
-                matchedBy: 'search',
-            };
-        }
-        if (searchMatches.length > 1) {
-            throw new Error(`Multiple workflows partially matched "${normalizedSelector}". Use a full workflow name or id.`);
-        }
-        throw new Error(`No VigFlow workflow matched "${normalizedSelector}".`);
-    }
-    async useVigFlowTemplate(templateId, options = {}) {
-        return this.withVigFlow('use template', async (baseUrl, headers) => {
-            const response = await axios.post(`${this.vigFlowEndpoint(baseUrl, `/templates/${encodeURIComponent(templateId)}/use`)}`, {
-                name: options.name,
-                variables: options.variables || {},
-            }, {
-                headers,
-                timeout: 30000,
-            });
-            const payload = response.data;
-            if (!payload.workflow?.id) {
-                throw new Error('VigFlow use-template response did not include a workflow id.');
-            }
-            return payload.workflow;
-        });
-    }
-    async runVigFlowWorkflow(workflowId, options = {}) {
-        return this.withVigFlow('run workflow', async (baseUrl, headers) => {
-            const response = await axios.post(`${this.vigFlowEndpoint(baseUrl, `/executions/run/${encodeURIComponent(workflowId)}`)}`, {
-                data: options.data || {},
-                options: options.executionOptions || {},
-            }, {
-                headers,
-                timeout: 60000,
-            });
-            const payload = response.data;
-            if (!payload.executionId) {
-                throw new Error('VigFlow run response did not include an execution id.');
-            }
-            return payload;
-        });
-    }
-    async getVigFlowExecutionStatus(executionId) {
-        return this.withVigFlow('execution status', async (baseUrl, headers) => {
-            const response = await axios.get(`${this.vigFlowEndpoint(baseUrl, `/executions/${encodeURIComponent(executionId)}`)}`, {
-                headers,
-                timeout: 30000,
-            });
-            const payload = response.data;
-            if (!payload.execution?.id) {
-                throw new Error('VigFlow execution response did not include execution details.');
-            }
-            return payload.execution;
-        });
-    }
-    /** Legacy cap — prefer resolveV3ContextCharLimit() for token-aligned budgets. */
-    static V3_CONTEXT_CHAR_LIMIT = 100_000;
     static HYDRATION_PRIORITY_BASENAMES = new Set([
         'package.json', 'index.html', 'game.js', 'main.js', 'app.js', 'script.js',
         'styles.css', 'style.css', 'README.md', 'manifest.json',
@@ -1618,18 +850,10 @@ export class APIClient {
             if (used + entryLen > budgetChars) {
                 const normalizedPath = this.normalizeWorkspaceRelativePath(filePath);
                 if (mandatory.has(normalizedPath)) {
-                    // Explicit prompt targets are hydration requirements, not ranking
-                    // hints.  Skipping an HTML entry merely because a larger targeted
-                    // stylesheet consumed the provisional budget creates false preview
-                    // failures in the remote V3 workspace.  Keep the complete explicit
-                    // file and let later context-compaction phases shed history/metadata.
                     trimmed[filePath] = clipped;
                     used += entryLen;
                 }
                 else if (explicitPriority.has(normalizedPath)) {
-                    // Linked preview assets are important enough to hydrate, but unlike
-                    // edit targets they may be compacted. Keep a bounded prefix so the
-                    // remote static server resolves the asset instead of returning 404.
                     const envelope = JSON.stringify(filePath).length + 128;
                     const available = Math.max(256, budgetChars - used - envelope);
                     const dependencyClip = content.length > available
@@ -1647,7 +871,6 @@ export class APIClient {
     }
     buildV3AgentContext(context = {}) {
         const resolvedContext = this.ensureExecutionContext(context);
-        const targetPath = resolvedContext.targetPath || resolvedContext.projectPath || resolvedContext.workspacePath || resolvedContext.projectRoot || process.cwd();
         const localWorkspacePath = this.resolveAgentTargetPath(resolvedContext);
         const serverWorkspacePath = this.resolveServerBindableWorkspacePath(resolvedContext);
         const promptFocus = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || resolvedContext.prompt || '');
@@ -1666,10 +889,6 @@ export class APIClient {
         const localWorkspaceRef = localWorkspaceName ? `vigthoria://local-workspace/${localWorkspaceName}` : null;
         const executionSurface = String(resolvedContext.executionSurface || resolvedContext.clientSurface || 'cli');
         const localMachineCapable = resolvedContext.localMachineCapable !== false;
-        // A workspace under a configured server root is already available to the
-        // V3 service. Keep tool execution on the server in that case; delegating
-        // tools back to the CLI can turn server paths into invalid client paths.
-        // An explicit caller override remains authoritative for specialist flows.
         const clientToolExecution = resolvedContext.clientToolExecution === false
             ? false
             : (resolvedContext.clientToolExecution === true
@@ -1704,6 +923,11 @@ export class APIClient {
                 executionHints.requires_file_changes = false;
             }
         }
+        const contextState = resolvedContext.mcpContextId
+            ? appendContextLayer(resolvedContext.contextState, 'mcp-context', {
+                metadata: { contextId: resolvedContext.mcpContextId, semanticAuthority: 'tool-evidence-only' },
+            })
+            : resolvedContext.contextState || null;
         const payload = {
             workspace: this.buildPublicWorkspaceDescriptor(resolvedContext.workspace, {
                 localWorkspacePath,
@@ -1755,11 +979,13 @@ export class APIClient {
             codebaseContext: resolvedContext.codebaseContext || '',
             accountBrainContext: resolvedContext.accountBrainContext || '',
             projectMemory: resolvedContext.projectMemory || '',
+            contextState,
+            contextCompatibilityAdapters: contextState?.compatibilityAdapters || null,
             clientManifest: buildClientManifest(resolvedContext.clientManifest && typeof resolvedContext.clientManifest === 'object'
                 ? resolvedContext.clientManifest
                 : {}),
         };
-        return this.compactV3Context(payload);
+        return this.compactV3Context(scanOutboundContext(payload).value);
     }
     /**
      * Compact a V3 context payload so the serialized JSON stays under
@@ -1892,34 +1118,35 @@ export class APIClient {
         }
         return finish();
     }
-    /** Normalize common Unix-only commands before Windows cmd/powershell execution. */
-    normalizeWindowsRunCommand(command, serverRoot = '') {
-        let cmd = String(command || '').trim();
+    /** Remove server-side workspace aliases before delegated local execution. */
+    normalizePortableRunCommand(command, serverRoot = '') {
+        const cmd = String(command || '').trim();
         if (!cmd)
             return cmd;
-        if (serverRoot) {
-            const escapedRoot = serverRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            cmd = cmd.replace(new RegExp(`^\\s*cd\\s+(?:[\"']?${escapedRoot}[\"']?)\\s*(?:&&|;)\\s*`, 'i'), '');
-        }
-        if (/^\/[^\s/]/.test(cmd) && !/^\/[a-z]:/i.test(cmd)) {
-            throw new Error('Command starts with "/" which Windows interprets as an invalid switch. Use workspace-relative paths without a leading slash.');
-        }
-        const replacements = [
-            [/^ls(\s|$)/i, 'dir$1'],
-            [/^cat\s+/i, 'type '],
-            [/^pwd\s*$/i, 'cd'],
-            [/^rm\s+-rf?\s+/i, 'rmdir /s /q '],
-            [/^rm\s+/i, 'del '],
-            [/^cp\s+/i, 'copy '],
-            [/^mv\s+/i, 'move '],
-        ];
-        for (const [pattern, replacement] of replacements) {
-            cmd = cmd.replace(pattern, replacement);
-        }
-        return cmd;
+        const match = cmd.match(/^\s*cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&]+))\s*(?:&&|;)\s*([\s\S]+)$/i);
+        if (!match)
+            return cmd;
+        const requestedCwd = String(match[1] || match[2] || match[3] || '').trim().replace(/\\/g, '/').replace(/\/$/, '');
+        const normalizedServerRoot = String(serverRoot || '').trim().replace(/\\/g, '/').replace(/\/$/, '');
+        const workspaceAliases = new Set([
+            '.',
+            'vigthoria://workspace',
+            'vigthoria://server-internal',
+            '/vigthoria/workspace',
+            '/workspace',
+            '[internal]',
+            normalizedServerRoot,
+        ].filter(Boolean).map((value) => value.toLowerCase()));
+        // The delegated client already executes with a validated workspace cwd.
+        // Strip only exact root aliases; preserve real relative subdirectory cd
+        // commands so project-specific workflows keep their intended scope.
+        return workspaceAliases.has(requestedCwd.toLowerCase()) ? String(match[4] || '').trim() : cmd;
     }
     resolveRunCommandCwd(rootPath, args, serverRoot) {
-        const cwdRaw = args.cwd ?? args.path ?? '.';
+        // run_command owns a cwd field. A model-supplied source `path` belongs to
+        // file tools and must not silently move command execution into that file's
+        // parent directory (which breaks root-level validation scripts).
+        const cwdRaw = args.cwd ?? args.directory ?? '.';
         let target = this.resolveV3ClientToolPath(rootPath, cwdRaw, serverRoot ? [serverRoot] : []);
         if (!target) {
             target = this.resolveV3ClientToolPath(rootPath, '.', serverRoot ? [serverRoot] : []);
@@ -2044,6 +1271,7 @@ export class APIClient {
             requestStartedAt: resolvedContext.requestStartedAt,
             vigthoriaBrain: dedupedBrain,
             vigthoria_brain: dedupedBrain,
+            contextState: resolvedContext.contextState || null,
         });
     }
     extractEmergencyAppName(message = '', fallback = 'Signal Desk') {
@@ -2514,18 +1742,18 @@ menu {
     }
     async bindExecutionContext(context = {}) {
         const executionContext = this.ensureExecutionContext(context);
-        const headers = await this.getMcpHeaders();
         const localWorkspacePath = this.resolveAgentTargetPath(executionContext);
         const workspacePath = this.resolveServerBindableWorkspacePath(executionContext);
         const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, String(executionContext.rawPrompt || executionContext.contextualPrompt || executionContext.prompt || ''));
+        const workspaceAlias = `vigthoria://workspace/${encodeURIComponent(path.basename(localWorkspacePath || workspacePath || 'workspace'))}`;
         const metadata = {
             source: 'vigthoria-cli',
             sharedContextId: executionContext.contextId,
             traceId: executionContext.traceId,
             executionSurface: executionContext.executionSurface || 'cli',
             clientSurface: executionContext.clientSurface || 'cli',
-            workspacePath: workspacePath || null,
-            localWorkspacePath: localWorkspacePath || null,
+            workspacePath: workspaceAlias,
+            localWorkspacePath: workspaceAlias,
             localWorkspaceSummary,
             runtimeEnvironment: executionContext.agentRuntime || null,
             requestStartedAt: executionContext.requestStartedAt,
@@ -2536,10 +1764,10 @@ menu {
             sharedContextId: executionContext.contextId,
             traceId: executionContext.traceId,
             requestStartedAt: executionContext.requestStartedAt,
-            workspacePath: workspacePath || null,
-            projectPath: workspacePath || null,
-            targetPath: workspacePath || null,
-            localWorkspacePath: localWorkspacePath || null,
+            workspacePath: workspaceAlias,
+            projectPath: workspaceAlias,
+            targetPath: workspaceAlias,
+            localWorkspacePath: workspaceAlias,
             localWorkspaceSummary,
             runtimeEnvironment: executionContext.agentRuntime || null,
             activeFile: executionContext.activeFile || null,
@@ -2548,68 +1776,22 @@ menu {
             userId: this.config.get('userId') || null,
             email: this.config.get('email') || null,
         };
-        const updateExisting = async (binding) => {
-            const response = await fetch(this.getMcpContextUrl(binding.backendUrl, binding.mcpContextId), {
-                method: 'PUT',
-                headers,
-                body: JSON.stringify({ data }),
-            });
-            if (!response.ok) {
-                const errorText = await response.text().catch(() => '');
-                throw new Error(`MCP context update ${response.status}: ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
-            }
-            return {
-                ...executionContext,
-                localWorkspacePath: localWorkspacePath || executionContext.localWorkspacePath || null,
-                targetPath: localWorkspacePath || executionContext.targetPath || executionContext.projectPath || executionContext.workspacePath || null,
-                projectPath: localWorkspacePath || executionContext.projectPath || executionContext.targetPath || executionContext.workspacePath || null,
-                workspacePath: localWorkspacePath || executionContext.workspacePath || executionContext.projectPath || executionContext.targetPath || null,
-                mcpContextId: binding.mcpContextId,
-                mcpContextBackendUrl: binding.backendUrl,
-            };
-        };
-        if (executionContext.mcpContextId && executionContext.mcpContextBackendUrl) {
-            try {
-                return await updateExisting({
-                    mcpContextId: String(executionContext.mcpContextId),
-                    backendUrl: String(executionContext.mcpContextBackendUrl),
-                });
-            }
-            catch (error) {
-                this.logger.debug('Failed to refresh existing MCP context binding:', error.message);
-            }
-        }
-        for (const baseUrl of this.getMcpBaseUrls()) {
-            try {
-                const createResponse = await fetch(this.getMcpContextCreateUrl(baseUrl), {
-                    method: 'POST',
-                    headers,
-                    body: JSON.stringify({
-                        userId: this.config.get('userId') || this.config.get('email') || 'vigthoria-cli',
-                        metadata,
-                    }),
-                });
-                if (!createResponse.ok) {
-                    const errorText = await createResponse.text().catch(() => '');
-                    throw new Error(`MCP context create ${createResponse.status}: ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
-                }
-                const payload = await createResponse.json();
-                const mcpContextId = String(payload.contextId || '').trim();
-                if (!mcpContextId) {
-                    throw new Error('MCP context create response did not include a contextId');
-                }
-                return await updateExisting({ mcpContextId, backendUrl: baseUrl });
-            }
-            catch (error) {
-                this.logger.debug(`Failed to bind MCP context via ${baseUrl}:`, error.message);
-            }
-        }
+        const binding = await this.mcpContextClient.bind({
+            existing: executionContext.mcpContextId && executionContext.mcpContextBackendUrl ? {
+                mcpContextId: String(executionContext.mcpContextId),
+                backendUrl: String(executionContext.mcpContextBackendUrl),
+            } : null,
+            userId: this.config.get('userId') || this.config.get('email') || 'vigthoria-cli',
+            metadata,
+            data,
+        });
         return {
             ...executionContext,
             localWorkspacePath: localWorkspacePath || executionContext.localWorkspacePath || null,
             targetPath: localWorkspacePath || executionContext.targetPath || executionContext.projectPath || executionContext.workspacePath || null,
             projectPath: localWorkspacePath || executionContext.projectPath || executionContext.targetPath || executionContext.workspacePath || null,
             workspacePath: localWorkspacePath || executionContext.workspacePath || executionContext.projectPath || executionContext.targetPath || null,
+            ...(binding ? { mcpContextId: binding.mcpContextId, mcpContextBackendUrl: binding.backendUrl } : {}),
         };
     }
     isServerManagedTempWorkspacePath(pathValue) {
@@ -2721,7 +1903,7 @@ menu {
                 files: [],
             };
             const snapshot = this.getAgentWorkspaceSnapshot(rootPath);
-            const candidatePaths = snapshot.paths.filter((entry) => !/(^|[\/\\])\.vigthoria([\/\\]|$)/.test(entry));
+            const candidatePaths = snapshot.paths.filter((entry) => !isSensitivePath(entry));
             const focusFiles = this.extractExpectedWorkspaceFiles(requestFocus)
                 .map((entry) => this.normalizeWorkspaceRelativePath(entry))
                 .filter((entry) => candidatePaths.includes(entry));
@@ -2739,12 +1921,13 @@ menu {
                     }
                 }
                 catch {
-                    // Missing/unreadable focused HTML remains visible to the server via
-                    // the original focus list; dependency expansion is best effort.
+                    // Best effort: the explicit target remains in focusFiles.
                 }
             }
             const hydrationFocusFiles = [...focusFiles, ...linkedFocusAssets];
-            const agentStatePaths = this.collectAgentStateSyncPaths(rootPath);
+            // Runtime state remains local. Resume/auth/session material under
+            // .vigthoria is never hydrated into a remote agent workspace.
+            const agentStatePaths = this.collectAgentStateSyncPaths(rootPath).filter((entry) => !isSensitivePath(entry));
             let orderedPaths = [...agentStatePaths, ...hydrationFocusFiles, ...candidatePaths];
             try {
                 const ranked = buildSemanticContext(rootPath, requestFocus, 60).topFiles.map((file) => file.path);
@@ -2807,8 +1990,7 @@ menu {
     }
     /**
      * Build complete workspace hydration separately from model context.
-     * Remote audits must inspect the same byte-complete assets the user has
-     * locally; context compaction must never become filesystem compaction.
+     * Context compaction must not become filesystem compaction.
      */
     buildOutOfBandWorkspaceFiles(context) {
         const resolvedContext = this.ensureExecutionContext(context);
@@ -2826,271 +2008,28 @@ menu {
      * Budget: up to ~2 MB total, per-file cap 200 KB, skip binary extensions.
      */
     collectWorkspaceFileContents(rootPath, filePaths) {
-        const MAX_TOTAL_BYTES = 2 * 1024 * 1024;
-        const MAX_FILE_BYTES = 200 * 1024;
-        const BINARY_EXTENSIONS = new Set([
-            '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.avif',
-            '.mp3', '.mp4', '.wav', '.ogg', '.webm', '.flac', '.aac',
-            '.zip', '.gz', '.tar', '.rar', '.7z', '.bz2',
-            '.exe', '.dll', '.so', '.dylib', '.bin', '.dat',
-            '.woff', '.woff2', '.ttf', '.eot', '.otf',
-            '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
-            '.db', '.sqlite', '.sqlite3',
-            '.pyc', '.pyo', '.class', '.o', '.obj',
-            '.DS_Store', '.lock',
-        ]);
-        const result = {};
-        let totalBytes = 0;
-        for (const relativePath of filePaths) {
-            if (totalBytes >= MAX_TOTAL_BYTES)
-                break;
-            const ext = path.extname(relativePath).toLowerCase();
-            if (BINARY_EXTENSIONS.has(ext))
-                continue;
-            if (/(^|[\/\\])\.(git|hg)([\/\\]|$)/.test(relativePath))
-                continue;
-            const normalizedPath = relativePath.replace(/\\/g, '/');
-            const isAgentStateSync = /^\.vigthoria\/agent-state\//i.test(normalizedPath);
-            if (!isAgentStateSync && /(^|[\/\\])\.vigthoria([\/\\]|$)/.test(relativePath))
-                continue;
-            const absolutePath = path.join(rootPath, relativePath);
-            try {
-                const stat = fs.statSync(absolutePath);
-                if (!stat.isFile() || stat.size > MAX_FILE_BYTES || stat.size === 0)
-                    continue;
-                const content = fs.readFileSync(absolutePath, 'utf8');
-                // Skip likely binary content (high ratio of non-printable chars)
-                if (/[\x00-\x08\x0e-\x1f]/.test(content.slice(0, 512)))
-                    continue;
-                result[relativePath] = content;
-                totalBytes += Buffer.byteLength(content, 'utf8');
-            }
-            catch {
-                // Skip unreadable files
-            }
-        }
-        return result;
+        return this.v3WorkspaceService.collectFileContents(rootPath, filePaths);
     }
     hasAgentWorkspaceOutput(context = {}) {
-        try {
-            const root = this.resolveAgentTargetPath(context);
-            if (!root || !fs.existsSync(root)) {
-                return false;
-            }
-            const stack = [root];
-            while (stack.length > 0) {
-                const current = stack.pop();
-                if (!current)
-                    continue;
-                const entries = fs.readdirSync(current, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.name === '.git' || entry.name === 'node_modules') {
-                        continue;
-                    }
-                    const fullPath = path.join(current, entry.name);
-                    if (entry.isFile()) {
-                        return true;
-                    }
-                    if (entry.isDirectory()) {
-                        stack.push(fullPath);
-                    }
-                }
-            }
-        }
-        catch {
-            return false;
-        }
-        return false;
+        return this.v3WorkspaceService.hasOutput(context);
     }
     getAgentWorkspaceSnapshot(rootPath) {
-        const stack = [rootPath];
-        let fileCount = 0;
-        const entries = [];
-        while (stack.length > 0) {
-            const current = stack.pop();
-            if (!current) {
-                continue;
-            }
-            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-                if (entry.name === '.git' || entry.name === 'node_modules') {
-                    continue;
-                }
-                const fullPath = path.join(current, entry.name);
-                if (entry.isDirectory()) {
-                    stack.push(fullPath);
-                    continue;
-                }
-                if (!entry.isFile()) {
-                    continue;
-                }
-                fileCount += 1;
-                const stat = fs.statSync(fullPath);
-                entries.push(`${path.relative(rootPath, fullPath)}:${stat.size}:${stat.mtimeMs}`);
-            }
-        }
-        entries.sort();
-        return {
-            fileCount,
-            paths: entries.map((entry) => entry.split(':', 1)[0]),
-            signature: entries.join('|'),
-        };
+        return this.v3WorkspaceService.snapshot(rootPath);
     }
     async waitForAgentWorkspaceSettle(context = {}, options = {}) {
-        const rootPath = this.resolveAgentTargetPath(context);
-        if (!rootPath || !fs.existsSync(rootPath)) {
-            return;
-        }
-        const timeoutMs = options.timeoutMs || 15000;
-        const pollMs = options.pollMs || 300;
-        const stableMs = options.stableMs || 1200;
-        const expectedFiles = Array.isArray(options.expectedFiles)
-            ? options.expectedFiles.map((entry) => String(entry || '').trim()).filter(Boolean)
-            : [];
-        const start = Date.now();
-        let stableSince = 0;
-        let lastSignature = '';
-        while (Date.now() - start < timeoutMs) {
-            const snapshot = this.getAgentWorkspaceSnapshot(rootPath);
-            if (snapshot.fileCount === 0) {
-                stableSince = 0;
-                lastSignature = '';
-                await new Promise((resolve) => setTimeout(resolve, pollMs));
-                continue;
-            }
-            if (expectedFiles.length > 0 && !expectedFiles.every((filePath) => snapshot.paths.includes(filePath))) {
-                stableSince = 0;
-                lastSignature = snapshot.signature;
-                await new Promise((resolve) => setTimeout(resolve, pollMs));
-                continue;
-            }
-            if (snapshot.signature === lastSignature) {
-                if (!stableSince) {
-                    stableSince = Date.now();
-                }
-                if (Date.now() - stableSince >= stableMs) {
-                    return;
-                }
-            }
-            else {
-                lastSignature = snapshot.signature;
-                stableSince = Date.now();
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollMs));
-        }
+        return this.v3WorkspaceService.waitForSettle(context, options);
     }
     extractExpectedWorkspaceFiles(message = '', context = {}) {
-        const candidates = new Set();
-        const addMatches = (value) => {
-            const text = String(value || '');
-            const patterns = [
-                /`([^`]+\.(?:html|css|js|jsx|ts|tsx|json|md|py|sh))`/gi,
-                /\b([A-Za-z0-9_./-]+\.(?:html|css|js|jsx|ts|tsx|json|md|py|sh))\b/g,
-            ];
-            for (const pattern of patterns) {
-                let match;
-                while ((match = pattern.exec(text)) !== null) {
-                    const filePath = match[1].trim().replace(/^\.\//, '');
-                    if (filePath && !filePath.startsWith('http://') && !filePath.startsWith('https://')) {
-                        candidates.add(filePath);
-                    }
-                }
-            }
-        };
-        addMatches(message);
-        addMatches(context.rawMessage);
-        addMatches(context.agentPrompt);
-        return Array.from(candidates);
+        return this.v3WorkspaceService.extractExpectedFiles(message, context);
     }
     captureV3AgentStreamMutation(event, streamedFiles, serverRoot) {
-        if (!event || !streamedFiles) {
-            return;
-        }
-        if (event.type === 'file_mutation' && typeof event.path === 'string') {
-            const filePath = this.normalizeAgentWorkspaceRelativePath(event.path, serverRoot || undefined);
-            if (!filePath) {
-                return;
-            }
-            if (event.action === 'delete') {
-                delete streamedFiles[filePath];
-                return;
-            }
-            if (typeof event.content === 'string') {
-                streamedFiles[filePath] = event.content;
-            }
-            return;
-        }
-        // workspace_snapshot is handled by applyV3AgentStreamEventToWorkspace only —
-        // never count hydrated baselines as "files changed".
-        // Only count confirmed mutations — not workspace snapshots (hydrated baseline)
-        // or tool_call previews that may still fail client-side / read-only guards.
-        if (event.type === 'tool_result' && event.success) {
-            const name = String(event.name || event.tool || '').trim();
-            const args = event.arguments || {};
-            const targetPath = typeof event.target === 'string'
-                ? event.target
-                : (typeof args.path === 'string' ? args.path : '');
-            if ((name === 'write_file' || name === 'edit_file') && targetPath) {
-                const filePath = this.normalizeAgentWorkspaceRelativePath(targetPath, serverRoot || undefined);
-                if (filePath && typeof args.content === 'string') {
-                    streamedFiles[filePath] = args.content;
-                }
-            }
-        }
+        this.v3WorkspaceService.captureMutation(event, streamedFiles, serverRoot);
     }
     applyV3AgentStreamEventToWorkspace(event, context = {}, serverRoot) {
-        if (!event || !['file_mutation', 'workspace_snapshot'].includes(String(event.type || ''))) {
-            return false;
-        }
-        const rootPath = this.resolveAgentTargetPath(context);
-        if (!rootPath) {
-            return false;
-        }
-        if (event.type === 'workspace_snapshot' && event.files && typeof event.files === 'object') {
-            let applied = false;
-            for (const [rawPath, content] of Object.entries(event.files)) {
-                if (typeof content !== 'string') {
-                    continue;
-                }
-                applied = this.writeV3AgentWorkspaceFile(rootPath, rawPath, content, serverRoot || undefined) || applied;
-            }
-            return applied;
-        }
-        if (event.type === 'file_mutation' && typeof event.path === 'string') {
-            const relativePath = this.normalizeAgentWorkspaceRelativePath(event.path, serverRoot || undefined);
-            if (!relativePath) {
-                return false;
-            }
-            if (event.action === 'delete') {
-                return this.deleteV3AgentWorkspaceFile(rootPath, relativePath);
-            }
-            if (typeof event.content === 'string') {
-                return this.writeV3AgentWorkspaceFile(rootPath, relativePath, event.content, rootPath);
-            }
-        }
-        return false;
+        return this.v3WorkspaceService.applyStreamEvent(event, context, serverRoot);
     }
     resolveV3ClientToolPath(rootPath, rawPath, sourceRoots = []) {
-        const raw = String(rawPath || '.').trim();
-        const roots = [rootPath, ...sourceRoots.filter(Boolean)];
-        let relativePath = '';
-        for (const sourceRoot of roots) {
-            relativePath = this.normalizeAgentWorkspaceRelativePath(raw, sourceRoot);
-            if (relativePath || raw === '.' || raw === '') {
-                break;
-            }
-        }
-        if (!relativePath && raw !== '.' && raw !== '') {
-            const treatAsWorkspaceRoot = roots.some((sourceRoot) => isV3WorkspaceRootAliasPath(raw, sourceRoot));
-            if (!treatAsWorkspaceRoot) {
-                return null;
-            }
-        }
-        const absolutePath = relativePath ? joinV3WorkspacePath(rootPath, relativePath) : path.resolve(rootPath);
-        const resolvedRoot = path.resolve(rootPath);
-        if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
-            return null;
-        }
-        return { relativePath: relativePath || '.', absolutePath };
+        return this.v3WorkspaceService.resolveClientToolPath(rootPath, rawPath, sourceRoots);
     }
     recordV3ClientToolMutation(event, context, result) {
         if (!result.success) {
@@ -3136,7 +2075,7 @@ menu {
         const serverRoot = String(context.__v3ServerWorkspaceRoot || '').trim();
         const isRunCommand = name === 'run_command';
         const pathArg = isRunCommand
-            ? (args.cwd ?? args.path ?? args.directory ?? '.')
+            ? (args.cwd ?? args.directory ?? '.')
             : (args.path || args.directory || args.cwd || '.');
         let target = this.resolveV3ClientToolPath(rootPath, pathArg, serverRoot ? [serverRoot] : []);
         if (!target && isRunCommand) {
@@ -3170,7 +2109,26 @@ menu {
                 return result;
             }
             if (name === 'read_file') {
-                return { success: true, output: fs.readFileSync(target.absolutePath, 'utf8') };
+                const content = fs.readFileSync(target.absolutePath, 'utf8');
+                const lines = content.split('\n');
+                const startValue = args.start_line ?? args.startLine ?? args.fromLine ?? args.lineStart;
+                const endValue = args.end_line ?? args.endLine ?? args.toLine ?? args.lineEnd;
+                let startLine = Number.parseInt(String(startValue ?? '1'), 10);
+                let endLine = Number.parseInt(String(endValue ?? '0'), 10);
+                if (!Number.isFinite(startLine) || startLine < 1)
+                    startLine = 1;
+                if (startLine > lines.length)
+                    startLine = lines.length;
+                if (!Number.isFinite(endLine) || endLine === 0)
+                    endLine = lines.length;
+                if (endLine < startLine)
+                    endLine = startLine;
+                if (endLine > lines.length)
+                    endLine = lines.length;
+                return {
+                    success: true,
+                    output: lines.slice(startLine - 1, endLine).join('\n'),
+                };
             }
             if (name === 'list_directory') {
                 const entries = fs.readdirSync(target.absolutePath, { withFileTypes: true })
@@ -3181,6 +2139,15 @@ menu {
             if (name === 'glob' || name === 'search_files' || name === 'grep') {
                 const rawPattern = String(args.pattern || args.query || '').trim();
                 const pattern = rawPattern.toLowerCase();
+                let contentPattern = null;
+                if (rawPattern) {
+                    try {
+                        contentPattern = new RegExp(rawPattern, 'i');
+                    }
+                    catch {
+                        contentPattern = null;
+                    }
+                }
                 const matches = [];
                 const walk = (dir) => {
                     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -3195,8 +2162,11 @@ menu {
                         if (name !== 'glob' && pattern) {
                             try {
                                 const content = fs.readFileSync(absolute, 'utf8');
-                                if (relative.toLowerCase().includes(pattern.replace(/\*/g, '')) || content.toLowerCase().includes(pattern)) {
-                                    matches.push(`${relative}: ${content.split('\n').find((line) => line.toLowerCase().includes(pattern))?.trim() || '(match)'}`);
+                                const lines = content.split('\n');
+                                const lineIndex = lines.findIndex((line) => (contentPattern ? contentPattern.test(line) : line.toLowerCase().includes(pattern)));
+                                if (relative.toLowerCase().includes(pattern.replace(/\*/g, '')) || lineIndex >= 0) {
+                                    const displayLine = lineIndex >= 0 ? lineIndex + 1 : 1;
+                                    matches.push(`${relative}:${displayLine}: ${lineIndex >= 0 ? lines[lineIndex].trim() : '(path match)'}`);
                                 }
                             }
                             catch {
@@ -3212,9 +2182,19 @@ menu {
                         cwd: searchRoot,
                         nodir: true,
                         dot: false,
+                        follow: false,
                         ignore: ['**/node_modules/**', '**/.git/**'],
                     })
                         .map((entry) => String(entry).replace(/\\/g, '/'))
+                        .filter((entry) => {
+                        try {
+                            resolveWorkspacePath(searchRoot, entry);
+                            return true;
+                        }
+                        catch {
+                            return false;
+                        }
+                    })
                         .sort((left, right) => left.localeCompare(right));
                     return { success: true, output: globbed.slice(0, 200).join('\n') || '(no matches)' };
                 }
@@ -3243,9 +2223,9 @@ menu {
                     return { success: true, output: `Syntax check passed: ${target.relativePath}` };
                 }
                 if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
-                    const { execSync } = await import('child_process');
+                    const { execFileSync } = await import('child_process');
                     try {
-                        execSync(`node --check "${target.absolutePath}"`, { stdio: 'pipe' });
+                        execFileSync(process.execPath, ['--check', target.absolutePath], { stdio: 'pipe', timeout: 10_000, windowsHide: true, env: safeChildProcessEnv() });
                         return { success: true, output: `Syntax check passed: ${target.relativePath}` };
                     }
                     catch (error) {
@@ -3261,36 +2241,73 @@ menu {
                 if (!command)
                     return { success: false, output: '', error: 'run_command requires command.' };
                 try {
-                    if (process.platform === 'win32') {
-                        command = this.normalizeWindowsRunCommand(command, serverRoot);
-                    }
+                    command = this.normalizePortableRunCommand(command, serverRoot);
+                }
+                catch (error) {
+                    return { success: false, output: '', error: error.message };
+                }
+                let processRequest;
+                try {
+                    processRequest = parseSupportedProcess(command);
                 }
                 catch (error) {
                     return { success: false, output: '', error: error.message };
                 }
-                const cwd = this.resolveRunCommandCwd(rootPath, args, serverRoot);
-                const { exec, execFile } = await import('child_process');
+                let cwd = this.resolveRunCommandCwd(rootPath, args, serverRoot);
+                // V3 models sometimes attach a virtual cwd such as /workspace even
+                // when the named validation script is visibly rooted in the bound
+                // client project. Prefer the real project root for an existing,
+                // workspace-relative Node/Python entrypoint so external clients never
+                // depend on a server-only filesystem alias.
+                const processName = path.basename(processRequest.executable).toLowerCase();
+                const rootScript = String(/^(?:node|python|python3)(?:\.exe)?$/.test(processName)
+                    ? processRequest.args.find((arg) => !arg.startsWith('-')) || ''
+                    : '').replace(/\\/g, '/');
+                if (rootScript && !path.isAbsolute(rootScript) && !rootScript.startsWith('../')) {
+                    const rootCandidate = path.resolve(rootPath, rootScript);
+                    const normalizedRoot = path.resolve(rootPath);
+                    if ((rootCandidate === normalizedRoot || rootCandidate.startsWith(`${normalizedRoot}${path.sep}`))
+                        && fs.existsSync(rootCandidate)
+                        && fs.statSync(rootCandidate).isFile()) {
+                        cwd = normalizedRoot;
+                    }
+                }
+                const { execFile } = await import('child_process');
+                // The V3 run_command contract expresses timeout in seconds (default
+                // 30, maximum 300). child_process expects milliseconds. Passing the
+                // model value through unchanged turned a normal timeout=30 request
+                // into 30ms, which reliably killed real validators while tiny unit
+                // commands appeared healthy.
+                const requestedTimeoutSeconds = Number(args.timeout ?? 30);
+                const timeoutSeconds = Number.isFinite(requestedTimeoutSeconds)
+                    ? Math.min(300, Math.max(1, requestedTimeoutSeconds))
+                    : 30;
+                const timeoutMs = timeoutSeconds * 1000;
                 return await new Promise((resolve) => {
-                    const timeout = Number(args.timeout || 30000);
                     const finish = (error, stdout, stderr) => {
                         const stdoutText = String(stdout || '');
                         const stderrText = String(stderr || '');
                         const combined = [stdoutText, stderrText].filter(Boolean).join('\n').slice(0, 12000);
+                        const failureDetail = error
+                            ? [
+                                error.killed ? `Command timed out after ${timeoutSeconds}s` : String(error.message || error),
+                                combined,
+                            ].filter(Boolean).join('\n').slice(0, 12000)
+                            : '';
                         resolve({
                             success: !error,
                             output: combined,
-                            error: error ? String(error.message || error) : '',
+                            error: failureDetail,
                         });
                     };
-                    if (process.platform === 'win32') {
-                        const commandProcessor = process.env.ComSpec
-                            || path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
-                        execFile(commandProcessor, ['/d', '/s', '/c', command], {
-                            cwd, timeout, maxBuffer: 1024 * 1024, env: process.env, windowsHide: true,
-                        }, finish);
-                        return;
-                    }
-                    exec(command, { cwd, timeout, maxBuffer: 1024 * 1024, env: process.env }, finish);
+                    execFile(processRequest.executable, processRequest.args, {
+                        cwd,
+                        timeout: timeoutMs,
+                        maxBuffer: 1024 * 1024,
+                        env: safeChildProcessEnv(),
+                        windowsHide: true,
+                        encoding: 'utf8',
+                    }, finish);
                 });
             }
             return { success: false, output: '', error: `Unsupported client tool: ${name}` };
@@ -3329,84 +2346,13 @@ menu {
         }
     }
     writeV3AgentWorkspaceFile(rootPath, rawPath, content, sourceRoot) {
-        const relativePath = this.normalizeAgentWorkspaceRelativePath(rawPath, sourceRoot || rootPath);
-        if (!relativePath) {
-            return false;
-        }
-        const absolutePath = joinV3WorkspacePath(rootPath, relativePath);
-        const resolvedRoot = path.resolve(rootPath);
-        if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
-            this.logger.warn(`Refusing to write V3 file outside workspace: ${rawPath}`);
-            return false;
-        }
-        try {
-            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-            if (fs.existsSync(absolutePath)) {
-                const existing = fs.readFileSync(absolutePath, 'utf8');
-                if (existing === content) {
-                    return false;
-                }
-            }
-            fs.writeFileSync(absolutePath, content, 'utf8');
-            return true;
-        }
-        catch (error) {
-            this.logger.warn(`Failed to write V3 file ${relativePath}: ${error.message}`);
-            return false;
-        }
-    }
-    deleteV3AgentWorkspaceFile(rootPath, rawPath) {
-        const relativePath = this.normalizeAgentWorkspaceRelativePath(rawPath, rootPath);
-        if (!relativePath) {
-            return false;
-        }
-        const absolutePath = joinV3WorkspacePath(rootPath, relativePath);
-        const resolvedRoot = path.resolve(rootPath);
-        if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
-            this.logger.warn(`Refusing to delete V3 file outside workspace: ${rawPath}`);
-            return false;
-        }
-        try {
-            if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isFile()) {
-                fs.unlinkSync(absolutePath);
-                return true;
-            }
-        }
-        catch (error) {
-            this.logger.warn(`Failed to delete V3 file ${relativePath}: ${error.message}`);
-        }
-        return false;
+        return this.v3WorkspaceService.writeFile(rootPath, rawPath, content, sourceRoot);
     }
     recoverAgentWorkspaceFiles(context = {}, streamedFiles = {}, expectedFiles = []) {
-        const rootPath = this.resolveAgentTargetPath(context);
-        if (!rootPath || Object.keys(streamedFiles).length === 0) {
-            return;
-        }
-        if (!fs.existsSync(rootPath)) {
-            try {
-                fs.mkdirSync(rootPath, { recursive: true });
-            }
-            catch {
-                return;
-            }
-        }
-        const targets = expectedFiles.length > 0
-            ? Array.from(new Set([...expectedFiles, ...Object.keys(streamedFiles)]))
-            : Object.keys(streamedFiles);
-        for (const targetPath of targets) {
-            const relativePath = this.normalizeAgentWorkspaceRelativePath(targetPath, rootPath);
-            if (!relativePath) {
-                continue;
-            }
-            const content = streamedFiles[relativePath];
-            if (typeof content !== 'string') {
-                continue;
-            }
-            this.writeV3AgentWorkspaceFile(rootPath, relativePath, content, rootPath);
-        }
+        this.v3WorkspaceService.recover(context, streamedFiles, expectedFiles);
     }
     normalizeAgentWorkspaceRelativePath(rawPath, rootPath) {
-        return normalizeV3WorkspaceRelativePath(rawPath, rootPath);
+        return this.v3WorkspaceService.normalizeRelativePath(rawPath, rootPath);
     }
     async ensureAgentFrontendPolish(message = '', context = {}) {
         const rootPath = this.resolveAgentTargetPath(context);
@@ -3541,14 +2487,23 @@ menu {
             if (!candidate || /^https?:\/\//i.test(candidate) || /^data:/i.test(candidate) || candidate.startsWith('#')) {
                 return '';
             }
-            return candidate.split('?')[0].split('#')[0].replace(/^\//, '');
+            const assetReference = candidate.split('?')[0].split('#')[0];
+            if (/^\/{2,}/.test(assetReference))
+                return '';
+            const relative = assetReference.replace(/^\//, '');
+            try {
+                return assertSafeRelativePath(relative);
+            }
+            catch {
+                return '';
+            }
         };
         const ensureTextAsset = (relativePath, content) => {
             const normalized = localAssetPath(relativePath);
             if (!normalized) {
                 return '';
             }
-            const absolutePath = path.join(rootPath, normalized);
+            const absolutePath = resolveWorkspacePath(rootPath, normalized, { allowMissing: true });
             if (!fs.existsSync(absolutePath)) {
                 fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
                 fs.writeFileSync(absolutePath, content, 'utf8');
@@ -3561,8 +2516,8 @@ menu {
         const jsRefs = Array.from(html.matchAll(/<script[^>]+src=["']([^"']+\.(?:js|mjs)(?:\?[^"']*)?)["']/gi))
             .map((match) => localAssetPath(match[1]))
             .filter(Boolean);
-        let cssPath = cssRefs.map((ref) => path.join(rootPath, ref)).find((candidate) => fs.existsSync(candidate)) || '';
-        let jsPath = jsRefs.map((ref) => path.join(rootPath, ref)).find((candidate) => fs.existsSync(candidate)) || '';
+        let cssPath = cssRefs.map((ref) => resolveWorkspacePath(rootPath, ref, { allowMissing: true })).find((candidate) => fs.existsSync(candidate)) || '';
+        let jsPath = jsRefs.map((ref) => resolveWorkspacePath(rootPath, ref, { allowMissing: true })).find((candidate) => fs.existsSync(candidate)) || '';
         const cssTemplate = this.buildFallbackFrontendCss(surfaceLabel);
         const jsTemplate = this.buildFallbackFrontendJs(surfaceLabel);
         if (!cssPath && cssRefs.length > 0) {
@@ -3740,8 +2695,18 @@ document.addEventListener('DOMContentLoaded', () => {
             if (!candidate || /^https?:\/\//i.test(candidate) || /^data:/i.test(candidate) || candidate.startsWith('#')) {
                 return true;
             }
-            const sanitized = candidate.split('?')[0].split('#')[0].replace(/^\//, '');
-            return !sanitized || fs.existsSync(path.join(rootPath, sanitized));
+            const assetReference = candidate.split('?')[0].split('#')[0];
+            if (/^\/{2,}/.test(assetReference))
+                return false;
+            const sanitized = assetReference.replace(/^\//, '');
+            if (!sanitized)
+                return true;
+            try {
+                return fs.existsSync(resolveWorkspacePath(rootPath, sanitized, { allowMissing: true }));
+            }
+            catch {
+                return false;
+            }
         };
         const repairedHtml = html.replace(/(<img\b[^>]*\ssrc=["'])([^"']+)(["'][^>]*>)/gi, (match, prefix, assetPath, suffix) => {
             if (hasLocalAsset(assetPath)) {
@@ -3752,7 +2717,7 @@ document.addEventListener('DOMContentLoaded', () => {
             const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 800"><defs><linearGradient id="heroGradient" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0f172a"/><stop offset="1" stop-color="#2563eb"/></linearGradient></defs><rect width="1200" height="800" rx="40" ry="40" fill="url(#heroGradient)"/><circle cx="220" cy="210" r="130" fill="rgba(255,255,255,0.08)"/><circle cx="980" cy="600" r="170" fill="rgba(255,255,255,0.12)"/><text x="84" y="700" fill="#ffffff" font-family="Arial, sans-serif" font-size="64" font-weight="700">${safeLabel}</text></svg>`;
             return `${prefix}data:image/svg+xml;utf8,${encodeURIComponent(svg)}${suffix}`;
         });
-        const repairedCss = css.replace(/url\((["']?)([^)"']+)\1\)/gi, (match, quote, assetPath) => {
+        const repairedCss = css.replace(/url\((["']?)([^)"']+)\1\)/gi, (match, _quote, assetPath) => {
             if (hasLocalAsset(assetPath)) {
                 return match;
             }
@@ -3939,12 +2904,34 @@ document.addEventListener('DOMContentLoaded', () => {
             : {};
         return { ...streamed, ...clientMutations };
     }
-    finalizeV3AgentWorkflowResponse(data, response) {
-        const changedFiles = this.resolveAgentChangedFiles(data);
+    finalizeV3AgentWorkflowResponse(data, response, journal = null) {
+        let changedFiles = this.resolveAgentChangedFiles(data);
+        const previewGate = response.metadata?.previewGate;
+        let mutation;
+        if (journal) {
+            const proofSucceeded = previewGate?.required === true
+                ? previewGate.passed === true && previewGate.skipped !== true
+                : true;
+            mutation = finalizeMutationTransaction(journal, proofSucceeded);
+            if (!proofSucceeded)
+                changedFiles = {};
+        }
         this.activeV3StreamedFiles = null;
-        this.activeV3StreamContext = null;
         return {
             ...response,
+            metadata: {
+                ...(response.metadata || {}),
+                ...(journal ? { operationId: journal.operationId } : {}),
+                ...(mutation ? { mutation, partialMutation: mutation.partialMutation } : {}),
+                ...(previewGate && mutation ? {
+                    previewGate: {
+                        ...previewGate,
+                        operationId: journal?.operationId,
+                        mutation,
+                        partialMutation: mutation.partialMutation,
+                    },
+                } : {}),
+            },
             changedFiles,
         };
     }
@@ -3963,7 +2950,6 @@ document.addEventListener('DOMContentLoaded', () => {
         let serverWorkspaceRoot = null;
         const streamedFiles = {};
         this.activeV3StreamedFiles = streamedFiles;
-        this.activeV3StreamContext = context;
         context.__v3StreamedFiles = streamedFiles;
         const idleTimeoutMs = (() => {
             const base = context.agentIdleTimeoutMs ?? DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS;
@@ -4224,6 +3210,13 @@ document.addEventListener('DOMContentLoaded', () => {
     }
     async runV3AgentWorkflow(message, context = {}) {
         const executionContext = await this.bindExecutionContext(context);
+        const mutationRoot = this.resolveAgentTargetPath(executionContext);
+        let mutationJournal = null;
+        if (mutationRoot && fs.existsSync(mutationRoot) && fs.statSync(mutationRoot).isDirectory()) {
+            mutationJournal = new MutationJournal(mutationRoot, executionContext.operationId);
+            executionContext.operationId = mutationJournal.operationId;
+            executionContext.__mutationJournal = mutationJournal;
+        }
         const requestedTimeoutMs = Number(executionContext.agentTimeoutMs ?? DEFAULT_V3_AGENT_TIMEOUT_MS);
         const baseTimeoutMs = Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0 ? requestedTimeoutMs : 0;
         const expectedFiles = this.extractExpectedWorkspaceFiles(message, executionContext);
@@ -4263,11 +3256,12 @@ document.addEventListener('DOMContentLoaded', () => {
                 workspace_files: useRelaxedAttempt ? undefined : workspaceFiles,
                 context_id: contextIdOverride ?? requestExecutionContext.contextId,
                 mcp_context_id: useRelaxedAttempt ? null : requestExecutionContext.mcpContextId || null,
+                operation_id: executionContext.operationId || undefined,
                 stream: true,
             });
             for (const baseUrl of this.getV3AgentBaseUrls(preferLocalV3)) {
                 let contextIdOverride;
-                const authPreflight = await this.runV3AgentAuthPreflight(baseUrl, buildRequestBody(), requestExecutionContext);
+                const authPreflight = await this.runV3AgentAuthPreflight(baseUrl, requestExecutionContext);
                 if (!authPreflight.ok) {
                     errors.push(`V3 auth preflight ${authPreflight.status} [${authPreflight.endpoint}]: ${authPreflight.reason || 'Unauthorized'}`);
                     continue;
@@ -4318,10 +3312,14 @@ document.addEventListener('DOMContentLoaded', () => {
                                 const continueTimeoutId = timeoutMs > 0 ? setTimeout(() => continueController.abort(), timeoutMs) : null;
                                 try {
                                     const continueHeaders = await this.getV3AgentHeaders();
-                                    const continueResponse = await fetch(this.getV3AgentContinueUrl(baseUrl), {
+                                    if (executionContext.operationId) {
+                                        continueHeaders['Idempotency-Key'] = String(executionContext.operationId);
+                                        continueHeaders['X-Vigthoria-Operation-Id'] = String(executionContext.operationId);
+                                    }
+                                    const continueResponse = await this.fetch(this.getV3AgentContinueUrl(baseUrl), {
                                         method: 'POST',
                                         headers: { ...continueHeaders, 'Content-Type': 'application/json' },
-                                        body: JSON.stringify(continueBody),
+                                        body: JSON.stringify(scanOutboundContext(continueBody).value),
                                         signal: continueController.signal,
                                     });
                                     if (!continueResponse.ok) {
@@ -4350,17 +3348,17 @@ document.addEventListener('DOMContentLoaded', () => {
                                 backendUrl: baseUrl,
                                 partial: continuationData.checkpointed === true,
                                 metadata: { source: 'v3-agent', mode: 'agent', contextId: finalContextId, continuations, previewGate },
-                            });
+                            }, mutationJournal);
                         }
                         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);
                         if (data.terminal_error) {
                             // A pre-existing local project is not proof that this run produced
-                            // valid output. Preserve real streamed mutations, but never run or
-                            // report a preview gate after a terminal planner/executor error.
+                            // valid output. A terminal planner/executor error fails proof and
+                            // causes the operation journal to roll back streamed mutations.
                             const failedPreviewGate = {
-                                required: false,
+                                required: true,
                                 passed: false,
                                 skipped: true,
                                 error: 'Agent execution failed before preview validation.',
@@ -4379,22 +3377,18 @@ document.addEventListener('DOMContentLoaded', () => {
                                     previewGate: failedPreviewGate,
                                     workflowError: data.terminal_error,
                                 },
-                            });
+                            }, mutationJournal);
                         }
                         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;
-                        }
                         return this.finalizeV3AgentWorkflowResponse(data, {
                             content: this.formatV3AgentResponse(data),
                             taskId: data.task_id || null,
                             contextId,
                             backendUrl: baseUrl,
                             metadata: { source: 'v3-agent', mode: 'agent', contextId, mcpContextId, previewGate },
-                        });
+                        }, mutationJournal);
                     }
                     catch (error) {
                         if (error && error.name === 'AbortError' && error.partialData && this.hasAgentWorkspaceOutput(executionContext)) {
@@ -4409,7 +3403,17 @@ document.addEventListener('DOMContentLoaded', () => {
                                 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 },
-                            });
+                            }, mutationJournal);
+                        }
+                        if (mutationJournal?.hasMutations()) {
+                            const mutation = mutationJournal.rollback();
+                            mutationJournal = null;
+                            this.activeV3StreamedFiles = null;
+                            const ambiguousError = new Error(`V3 mutation outcome is ambiguous for operation ${mutation.operationId}; workspace rollback was attempted and no alternate backend retry was allowed.`);
+                            ambiguousError.operationId = mutation.operationId;
+                            ambiguousError.mutation = mutation;
+                            ambiguousError.partialMutation = mutation.partialMutation;
+                            throw ambiguousError;
                         }
                         errors.push(`${baseUrl}: ${error?.message || String(error)}`);
                     }
@@ -4437,7 +3441,7 @@ document.addEventListener('DOMContentLoaded', () => {
         if (onlyUnauthorizedErrors && usingStoredConfigToken) {
             const gatewayTokenCheck = await this.validateToken({ allowNetworkFailOpen: true, enforceTokenShape: true });
             if (!gatewayTokenCheck.valid) {
-                this.config.clearAuth();
+                this.authSession.clearLocalCredentials();
                 throw new Error('V3 agent authentication failed. The stored CLI login token is invalid or expired. Run vigthoria login again.');
             }
             const rejectedEndpoints = Array.from(new Set(errors
@@ -4459,28 +3463,30 @@ document.addEventListener('DOMContentLoaded', () => {
                 await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles: ['index.html', 'styles.css', 'scripts.js'] });
                 await this.ensureAgentFrontendPolish(message, executionContext);
                 const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
-                return {
+                return this.finalizeV3AgentWorkflowResponse({}, {
                     content: `Recovered a local SaaS workspace scaffold for ${appName} after repeated V3 materialization failures.`,
                     taskId: null,
                     contextId: executionContext.contextId || null,
                     backendUrl: 'local-emergency-scaffold',
                     partial: true,
                     metadata: { source: 'v3-agent-emergency-scaffold', mode: 'agent', previewGate, emergencyScaffold: true },
-                };
+                }, mutationJournal);
             }
         }
-        throw new Error(errors.join(' | '));
+        const finalError = new Error(errors.join(' | '));
+        if (mutationJournal) {
+            const mutation = mutationJournal.rollback();
+            mutationJournal = null;
+            finalError.operationId = mutation.operationId;
+            finalError.mutation = mutation;
+            finalError.partialMutation = mutation.partialMutation;
+        }
+        throw finalError;
     }
     async startV3BackgroundJob(message, context = {}) {
         await this.ensureV3ServiceKey();
         const executionContext = await this.bindExecutionContext({
             ...context,
-            // Background callers historically supplied only workspace metadata.
-            // Without the request in the execution context, buildV3AgentContext()
-            // classified every detached job from an empty prompt and emitted an
-            // `analysis_only` workflow.  V3 would then inspect the workspace but was
-            // correctly forbidden from writing.  Preserve an explicit caller value,
-            // otherwise make the submitted job request authoritative for routing.
             rawPrompt: context.rawPrompt || context.prompt || message,
             prompt: context.prompt || context.rawPrompt || message,
             backgroundJob: true,
@@ -4500,1667 +3506,180 @@ document.addEventListener('DOMContentLoaded', () => {
             workspace_files: workspaceFiles,
             stream: false,
             model: resolvedModel,
-            mcp_context_id: executionContext.mcpContextId || undefined,
-        };
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl), {
-                    method: 'POST',
-                    headers: await this.getV3AgentHeaders(),
-                    body: JSON.stringify(body),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status} ${await response.text().catch(() => '')}`);
-                    continue;
-                }
-                return await response.json();
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to start background job: ${errors.join('; ')}`);
-    }
-    async listV3BackgroundJobs(limit = 20) {
-        await this.ensureV3ServiceKey();
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(`${this.getV3AgentBackgroundUrl(baseUrl)}?limit=${encodeURIComponent(String(limit))}`, {
-                    method: 'GET',
-                    headers: await this.getV3AgentHeaders(),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status}`);
-                    continue;
-                }
-                const data = await response.json();
-                return Array.isArray(data.jobs) ? data.jobs : [];
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to list background jobs: ${errors.join('; ')}`);
-    }
-    async getV3BackgroundJob(jobId) {
-        await this.ensureV3ServiceKey();
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, encodeURIComponent(jobId)), {
-                    method: 'GET',
-                    headers: await this.getV3AgentHeaders(),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status}`);
-                    continue;
-                }
-                return await response.json();
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to get background job: ${errors.join('; ')}`);
-    }
-    async cancelV3BackgroundJob(jobId) {
-        await this.ensureV3ServiceKey();
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, `${encodeURIComponent(jobId)}/cancel`), {
-                    method: 'POST',
-                    headers: await this.getV3AgentHeaders(),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status}`);
-                    continue;
-                }
-                return await response.json();
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to cancel background job: ${errors.join('; ')}`);
-    }
-    async resolveV3BackgroundApproval(jobId, approvalId, approved, allowMode = 'once') {
-        await this.ensureV3ServiceKey();
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(this.getV3AgentApprovalUrl(baseUrl), {
-                    method: 'POST',
-                    headers: await this.getV3AgentHeaders(),
-                    body: JSON.stringify({
-                        context_id: jobId,
-                        approval_id: approvalId,
-                        approved,
-                        allow_mode: allowMode,
-                    }),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status}`);
-                    continue;
-                }
-                return await response.json();
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to resolve background approval: ${errors.join('; ')}`);
-    }
-    async getV3BackgroundJobFiles(jobId) {
-        await this.ensureV3ServiceKey();
-        const errors = [];
-        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
-            try {
-                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, `${encodeURIComponent(jobId)}/files`), {
-                    method: 'GET',
-                    headers: await this.getV3AgentHeaders(),
-                });
-                if (!response.ok) {
-                    errors.push(`${baseUrl}: ${response.status}`);
-                    continue;
-                }
-                return await response.json();
-            }
-            catch (error) {
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-        }
-        throw new Error(`Unable to fetch background job files: ${errors.join('; ')}`);
-    }
-    async applyV3BackgroundJobFiles(jobId, context = {}) {
-        const [data, job] = await Promise.all([
-            this.getV3BackgroundJobFiles(jobId),
-            this.getV3BackgroundJob(jobId),
-        ]);
-        if (job?.status !== 'completed' || job?.result?.success === false || job?.result?.type === 'error') {
-            throw new Error(`Background job ${jobId} is not a successful completed job and cannot be applied.`);
-        }
-        const mutatedPaths = new Set();
-        const addMutatedPath = (value) => {
-            const normalized = this.normalizeWorkspaceRelativePath(String(value || ''));
-            if (!normalized || path.isAbsolute(normalized) || normalized.split('/').includes('..'))
-                return;
-            mutatedPaths.add(normalized);
-        };
-        for (const filePath of data.confirmed_mutations || []) {
-            addMutatedPath(filePath);
-        }
-        for (const event of Array.isArray(job?.events) ? job.events : []) {
-            if (event?.type === 'file_mutation' && event?.action !== 'delete') {
-                addMutatedPath(event.path);
-            }
-            if (event?.type === 'executor_complete') {
-                let summary = event.summary;
-                if (typeof summary === 'string') {
-                    try {
-                        summary = JSON.parse(summary);
-                    }
-                    catch {
-                        summary = null;
-                    }
-                }
-                if (summary?.status === 'completed') {
-                    for (const filePath of [...(summary.changed_files || []), ...(summary.created_files || [])]) {
-                        addMutatedPath(filePath);
-                    }
-                }
-            }
-        }
-        if (mutatedPaths.size === 0) {
-            throw new Error(`Background job ${jobId} has no confirmed successful file mutations to apply.`);
-        }
-        const rootPath = this.resolveAgentTargetPath({
-            ...context,
-            workspacePath: context.workspacePath || data.local_workspace_path,
-            projectPath: context.projectPath || data.local_workspace_path,
-            targetPath: context.targetPath || data.local_workspace_path,
-        });
-        if (!rootPath) {
-            throw new Error('No local workspace path available for applying background job files.');
-        }
-        const applied = [];
-        const skipped = [];
-        for (const [relativePath, content] of Object.entries(data.files || {})) {
-            const normalizedRelativePath = this.normalizeWorkspaceRelativePath(relativePath);
-            if (!mutatedPaths.has(normalizedRelativePath)) {
-                skipped.push(relativePath);
-                continue;
-            }
-            if (typeof content !== 'string') {
-                skipped.push(relativePath);
-                continue;
-            }
-            if (this.writeV3AgentWorkspaceFile(rootPath, relativePath, content, rootPath)) {
-                applied.push(relativePath);
-            }
-            else {
-                skipped.push(relativePath);
-            }
-        }
-        return { applied, skipped, status: data.status };
-    }
-    formatOperatorResponse(data = {}) {
-        // If the server returned a direct answer field, prefer it (for lookup tasks)
-        if (typeof data.answer === 'string' && data.answer.trim()) {
-            return data.answer.trim();
-        }
-        if (typeof data.result === 'string' && data.result.trim()) {
-            return data.result.trim();
-        }
-        const lines = [];
-        if (data.summary) {
-            lines.push(String(data.summary).trim());
-        }
-        if (Array.isArray(data.completed_agents) && data.completed_agents.length > 0) {
-            lines.push(`Completed agents: ${data.completed_agents.join(', ')}`);
-        }
-        if (data.details) {
-            const detailText = JSON.stringify(data.details, null, 2);
-            if (detailText && detailText !== '{}') {
-                lines.push(detailText.length > 12000 ? `${detailText.slice(0, 12000)}\n\n[Operator output truncated]` : detailText);
-            }
-        }
-        return lines.filter(Boolean).join('\n\n').trim() || 'Operator workflow completed.';
-    }
-    async runOperatorWorkflow(message, context = {}) {
-        const executionContext = await this.bindExecutionContext(context);
-        const requestedOperatorTimeoutMs = Number(context.operatorTimeoutMs ?? DEFAULT_OPERATOR_TIMEOUT_MS);
-        const timeoutMs = Number.isFinite(requestedOperatorTimeoutMs) && requestedOperatorTimeoutMs > 0
-            ? requestedOperatorTimeoutMs
-            : 0;
-        const errors = [];
-        const authToken = this.config.get('authToken');
-        // Collect a lightweight workspace file listing so the operator can
-        // ground its analysis in real files rather than returning files_analyzed: 0.
-        const workspacePath = executionContext.workspacePath || executionContext.projectPath || executionContext.targetPath || process.cwd();
-        const workspaceSummary = this.buildLocalWorkspaceSummary(workspacePath);
-        const requestedModel = String(executionContext.model || 'code');
-        const resolvedModel = this.resolveModelId(requestedModel);
-        for (const baseUrl of this.getOperatorBaseUrls()) {
-            const controller = new AbortController();
-            const timeoutId = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
-            try {
-                const response = await fetch(this.getOperatorStreamUrl(baseUrl), {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Accept: 'text/event-stream',
-                        ...(executionContext.mcpContextId ? { 'X-MCP-Context-Id': String(executionContext.mcpContextId) } : {}),
-                        ...(authToken ? {
-                            Authorization: `Bearer ${authToken}`,
-                            Cookie: `vigthoria-auth-token=${authToken}`,
-                        } : {}),
-                    },
-                    body: JSON.stringify({
-                        prompt: message,
-                        task: message,
-                        raw_prompt: executionContext.rawPrompt || null,
-                        model: requestedModel,
-                        preferred_model: resolvedModel,
-                        context_id: executionContext.contextId,
-                        trace_id: executionContext.traceId,
-                        mcp_context_id: executionContext.mcpContextId || null,
-                        context: {
-                            workspace: { path: workspacePath },
-                            workspace_path: workspacePath,
-                            workspace_summary: workspaceSummary,
-                            model: resolvedModel,
-                            history: executionContext.history || [],
-                            executionSurface: executionContext.executionSurface || 'cli',
-                            clientSurface: executionContext.clientSurface || 'cli',
-                            contextId: executionContext.contextId,
-                            traceId: executionContext.traceId,
-                            mcpContextId: executionContext.mcpContextId || null,
-                            mcp_context_id: executionContext.mcpContextId || null,
-                            rawPrompt: executionContext.rawPrompt || null,
-                            requestStartedAt: executionContext.requestStartedAt,
-                            vigthoriaBrain: executionContext.vigthoriaBrain || null,
-                            vigthoria_brain: executionContext.vigthoriaBrain || null,
-                        },
-                        workflow_type: executionContext.workflowType || 'full',
-                        options: {
-                            stream: true,
-                            save_to_vigflow: executionContext.savePlanToVigFlow === true,
-                        },
-                    }),
-                    signal: controller.signal,
-                });
-                if (!response.ok) {
-                    const errorText = await response.text().catch(() => '');
-                    throw new Error(`Operator stream ${response.status}: ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
-                }
-                if (!response.body || typeof response.body.getReader !== 'function') {
-                    const fallbackData = await response.json();
-                    return {
-                        content: this.formatOperatorResponse(fallbackData),
-                        workflowId: fallbackData.workflow_id || null,
-                        contextId: fallbackData.context_id || response.headers.get('x-context-id') || executionContext.contextId || null,
-                        backendUrl: baseUrl,
-                        savedWorkflow: fallbackData.saved_workflow || null,
-                        metadata: {
-                            source: 'operator',
-                            mode: 'operator',
-                            contextId: fallbackData.context_id || response.headers.get('x-context-id') || executionContext.contextId || null,
-                            mcpContextId: fallbackData.mcp_context_id || response.headers.get('x-mcp-context-id') || executionContext.mcpContextId || null,
-                        },
-                    };
-                }
-                const reader = response.body.getReader();
-                const decoder = new TextDecoder();
-                let buffer = '';
-                let workflowId = null;
-                let contextId = response.headers.get('x-context-id') || executionContext.contextId || null;
-                let mcpContextId = response.headers.get('x-mcp-context-id') || executionContext.mcpContextId || null;
-                let resultPayload = null;
-                let savedWorkflow = null;
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done) {
-                        break;
-                    }
-                    buffer += decoder.decode(value, { stream: true });
-                    const chunks = buffer.split('\n\n');
-                    buffer = chunks.pop() || '';
-                    for (const chunk of chunks) {
-                        const lines = chunk.split('\n');
-                        let eventName = 'message';
-                        const dataLines = [];
-                        for (const line of lines) {
-                            if (line.startsWith('event:')) {
-                                eventName = line.slice(6).trim();
-                            }
-                            else if (line.startsWith('data:')) {
-                                dataLines.push(line.slice(5).trim());
-                            }
-                        }
-                        if (dataLines.length === 0) {
-                            continue;
-                        }
-                        let payload = null;
-                        try {
-                            payload = JSON.parse(dataLines.join('\n'));
-                        }
-                        catch {
-                            payload = { raw: dataLines.join('\n') };
-                        }
-                        if (payload.workflow_id && !workflowId) {
-                            workflowId = payload.workflow_id;
-                        }
-                        if (!contextId && typeof payload.context_id === 'string' && payload.context_id.trim()) {
-                            contextId = payload.context_id.trim();
-                        }
-                        if (!mcpContextId && typeof payload.mcp_context_id === 'string' && payload.mcp_context_id.trim()) {
-                            mcpContextId = payload.mcp_context_id.trim();
-                        }
-                        if (!savedWorkflow && payload.saved_workflow && typeof payload.saved_workflow === 'object') {
-                            savedWorkflow = payload.saved_workflow;
-                        }
-                        if (typeof context.onStreamEvent === 'function') {
-                            try {
-                                context.onStreamEvent({ type: eventName, ...payload, context_id: payload.context_id || contextId, mcp_context_id: payload.mcp_context_id || mcpContextId });
-                            }
-                            catch {
-                                // UI callback failures must not break operator execution.
-                            }
-                        }
-                        if (eventName === 'result') {
-                            resultPayload = payload;
-                        }
-                        if (eventName === 'error') {
-                            throw new Error(payload.error || payload.message || 'Operator workflow failed');
-                        }
-                    }
-                }
-                return {
-                    content: this.formatOperatorResponse(resultPayload || {}),
-                    workflowId,
-                    contextId,
-                    backendUrl: baseUrl,
-                    savedWorkflow,
-                    metadata: { source: 'operator', mode: 'operator', contextId, mcpContextId, savedWorkflowId: savedWorkflow?.id || null },
-                };
-            }
-            catch (error) {
-                const isAbort = error?.name === 'AbortError' || error?.code === 'ABORT_ERR';
-                if (isAbort) {
-                    const mins = Math.round(timeoutMs / 60000);
-                    throw new CLIError(`Operator workflow timed out after ${mins} minute(s). You can increase the timeout with VIGTHORIA_OPERATOR_TIMEOUT_MS.`, 'timeout', error);
-                }
-                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
-            }
-            finally {
-                if (timeoutId)
-                    clearTimeout(timeoutId);
-            }
-        }
-        throw new CLIError(`Operator workflow failed on all endpoints: ${errors.join(' | ')}`, 'model_backend');
-    }
-    /**
-     * Chat API - Direct Vigthoria Models API Architecture
-     *
-     * PRIMARY: api.vigthoria.io - Direct access to Vigthoria Model Router
-     *          This is the centralized public API for all AI operations.
-     *          Works for both authenticated and unauthenticated users.
-     *
-     * FALLBACK: Coder Cloud API - For authenticated users only
-     *
-     * NO localhost fallbacks - CLI is for external users, not server-side!
-     */
-    async chat(messages, model, useLocal = false) {
-        this.lastChatTransportErrors = [];
-        const resolvedModel = this.resolveModelId(model);
-        const candidateModels = this.isCloudModelId(resolvedModel) && !this.canUseCloudModel()
-            ? [this.getSelfHostedFallbackModelId(resolvedModel, model)]
-            : [resolvedModel];
-        const fallbackModel = this.getFallbackModelId(resolvedModel);
-        if (fallbackModel && fallbackModel !== resolvedModel) {
-            candidateModels.push(fallbackModel);
-        }
-        for (const candidateModel of candidateModels) {
-            const response = await this.tryChatWithModel(messages, candidateModel, model);
-            if (response) {
-                if (candidateModel !== resolvedModel) {
-                    this.logger.debug(`Recovered chat request using fallback model: ${candidateModel}`);
-                }
-                return response;
-            }
-        }
-        // 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');
-    }
-    shouldSkipCloudRoutes(resolvedModel) {
-        return this.shouldSimulateCloudFailure() && this.isCloudModelId(resolvedModel);
-    }
-    async tryChatWithModel(messages, resolvedModel, requestedModel) {
-        const routeFailures = [];
-        const preferSelfHostedFirst = this.isSelfHostedPreferredModel(resolvedModel, requestedModel);
-        if (preferSelfHostedFirst) {
-            const selfHostedResponse = await this.trySelfHostedChatWithModel(messages, resolvedModel, requestedModel);
-            if (selfHostedResponse) {
-                return selfHostedResponse;
-            }
-        }
-        // STRATEGY 1: Direct Vigthoria Models API (api.vigthoria.io)
-        // Cloud aliases must be charged through Coder wallet gates first.
-        if (!this.shouldSkipCloudRoutes(resolvedModel) && !this.isCloudModelId(resolvedModel)) {
-            try {
-                this.logger.debug(`Direct Vigthoria Models API: ${resolvedModel}`);
-                const token = this.getAccessToken();
-                const response = await this.modelRouterClient.post('/v1/chat/completions', {
-                    model: resolvedModel,
-                    messages,
-                    max_tokens: this.config.get('preferences').maxTokens,
-                    temperature: 0.7,
-                    stream: false,
-                }, {
-                    headers: token ? { Authorization: `Bearer ${token}` } : {},
-                });
-                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,
-                        };
-                    }
-                }
-                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 {
-            if (this.isCloudModelId(resolvedModel)) {
-                this.logger.debug(`Cloud model ${resolvedModel} routed through Coder wallet gate first; skipping direct models API route.`);
-            }
-            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)) {
-            try {
-                this.logger.debug(`Vigthoria Cloud API fallback: ${resolvedModel}`);
-                const response = await this.client.post('/api/ai/chat', {
-                    messages,
-                    model: resolvedModel,
-                    maxTokens: this.config.get('preferences').maxTokens,
-                    temperature: 0.7,
-                    cloudConsent: 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 {
-                        return {
-                            id: response.data.id || `vigthoria-coder-${Date.now()}`,
-                            message: content,
-                            model: response.data.model || resolvedModel || requestedModel,
-                            usage: response.data.usage,
-                        };
-                    }
-                }
-                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)}`);
-            }
-            try {
-                this.logger.debug(`Canonical Vigthoria Cloud fallback: ${resolvedModel}`);
-                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,
-                    cloudConsent: this.isCloudModelId(resolvedModel),
-                }, {
-                    timeout: 180000,
-                    httpsAgent: this._httpsAgent ?? undefined,
-                    headers: token ? { Authorization: `Bearer ${token}`, Cookie: `vigthoria-auth-token=${token}` } : {},
-                });
-                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,
-                        };
-                    }
-                }
-            }
-            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;
-            }
-        }
-        if (routeFailures.length > 0) {
-            this.lastChatTransportErrors = routeFailures;
-        }
-        return null;
-    }
-    async trySelfHostedChatWithModel(messages, resolvedModel, requestedModel) {
-        if (!this.selfHostedModelRouterClient || !this.shouldTrySelfHostedFallback(resolvedModel, requestedModel)) {
-            return null;
-        }
-        const selfHostedModel = this.getSelfHostedFallbackModelId(resolvedModel, requestedModel);
-        try {
-            this.logger.debug(`Dedicated Vigthoria model endpoint fallback: ${selfHostedModel}`);
-            const response = await this.selfHostedModelRouterClient.post('/v1/chat/completions', {
-                model: selfHostedModel,
-                messages,
-                max_tokens: this.config.get('preferences').maxTokens,
-                temperature: 0.7,
-                stream: false,
-            }, {
-                headers: {
-                    'x-agent-mode': 'true',
-                },
-            });
-            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(`Dedicated Vigthoria model endpoint returned empty message content for ${selfHostedModel}`);
-                    return null;
-                }
-                return {
-                    id: response.data.id || `vigthoria-dedicated-${Date.now()}`,
-                    message: content,
-                    model: response.data.model || selfHostedModel,
-                    usage: response.data.usage,
-                };
-            }
-            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(`Dedicated Vigthoria model endpoint fallback failed for ${selfHostedModel}: ${errMsg}`);
-        }
-        return null;
-    }
-    getFallbackModelId(resolvedModel) {
-        const cloudModels = new Set([
-            'deepseek-v3.1:671b-cloud',
-            'moonshotai/kimi-k2.5',
-            'vigthoria-cloud-pro',
-            'vigthoria-cloud-k2',
-            'vigthoria-cloud-ultra',
-        ]);
-        if (cloudModels.has(resolvedModel)) {
-            return 'vigthoria-v3-code-35b';
-        }
-        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';
-    }
-    canUseCloudModel() {
-        return this.config.hasCloudAccess();
-    }
-    resolvePermittedModelId(shortName) {
-        const normalizedRequested = String(shortName || '').trim().toLowerCase();
-        const blockedModels = new Set(['fast', 'mini', 'creative', 'creative-v3', 'creative-v4']);
-        if (blockedModels.has(normalizedRequested)) {
-            this.logger.debug(`Blocked governed model ${shortName}; using fallback vigthoria-v3-code-35b`);
-            return 'vigthoria-v3-code-35b';
-        }
-        const resolvedModel = this.resolveModelId(shortName);
-        if (this.isCloudModelId(resolvedModel) && !this.canUseCloudModel()) {
-            const fallbackModel = this.getSelfHostedFallbackModelId(resolvedModel, shortName);
-            this.logger.debug(`Blocked unauthorized cloud model ${shortName}; using fallback ${fallbackModel}`);
-            return fallbackModel;
-        }
-        return resolvedModel;
-    }
-    shouldSimulateCloudFailure() {
-        return process.env.VIGTHORIA_SIMULATE_CLOUD_FAILURE === '1';
-    }
-    shouldTrySelfHostedFallback(resolvedModel, requestedModel) {
-        if (!this.selfHostedModelRouterClient) {
-            return false;
-        }
-        const normalizedRequested = String(requestedModel || '').toLowerCase();
-        return this.isSelfHostedPreferredModel(resolvedModel, requestedModel)
-            || normalizedRequested === 'cloud'
-            || normalizedRequested === 'cloud-reason'
-            || normalizedRequested === 'ultra';
-    }
-    isSelfHostedPreferredModel(resolvedModel, requestedModel) {
-        const normalizedRequested = String(requestedModel || '').toLowerCase();
-        const selfHostedModels = new Set([
-            'vigthoria-v3-code-35b',
-            'vigthoria-v3-code-35b:latest',
-            'vigthoria-v3-code-9b',
-            'vigthoria-v3-code-9b:latest',
-            'vigthoria-v3-balanced-4b',
-            'vigthoria-v3-balanced-4b:latest',
-            'qwen3-coder:latest',
-        ]);
-        return selfHostedModels.has(resolvedModel)
-            || normalizedRequested === 'agent'
-            || normalizedRequested === 'code'
-            || normalizedRequested === 'code-30b'
-            || normalizedRequested === 'code-35b'
-            || normalizedRequested === 'code-9b'
-            || normalizedRequested === 'balanced'
-            || normalizedRequested === 'balanced-4b'
-            || normalizedRequested === 'pro';
-    }
-    getSelfHostedFallbackModelId(resolvedModel, requestedModel) {
-        if (this.isSelfHostedPreferredModel(resolvedModel, requestedModel)) {
-            return resolvedModel === 'qwen3-coder:latest' ? 'vigthoria-v3-code-35b' : resolvedModel;
-        }
-        return 'vigthoria-v3-code-35b';
-    }
-    // Streaming chat
-    async *chatStream(messages, model) {
-        const wsUrl = this.config.get('wsUrl');
-        const token = this.config.get('authToken');
-        return new Promise((resolve, reject) => {
-            const ws = new WebSocket(`${wsUrl}/chat`, {
-                headers: { Authorization: `Bearer ${token}` },
-            });
-            ws.on('open', () => {
-                ws.send(JSON.stringify({
-                    type: 'chat',
-                    messages,
-                    model: this.resolvePermittedModelId(model),
-                    stream: true,
-                }));
-            });
-            ws.on('message', (data) => {
-                const chunk = JSON.parse(data.toString());
-                // Yield chunk - but this pattern won't work directly
-                // Need to use event emitter pattern instead
-            });
-            ws.on('error', (error) => {
-                reject(error);
-            });
-            ws.on('close', () => {
-                resolve(undefined);
-            });
-        });
-    }
-    // Non-streaming alternative with callback
-    async chatWithCallback(messages, model, onChunk, onDone, onError) {
-        const wsUrl = this.config.get('wsUrl');
-        const token = this.config.get('authToken');
-        return new Promise((resolve, reject) => {
-            const ws = new WebSocket(`${wsUrl}/chat`, {
-                headers: { Authorization: `Bearer ${token}` },
-            });
-            ws.on('open', () => {
-                ws.send(JSON.stringify({
-                    type: 'chat',
-                    messages,
-                    model: this.resolvePermittedModelId(model),
-                    stream: true,
-                }));
-            });
-            ws.on('message', (data) => {
-                try {
-                    const chunk = JSON.parse(data.toString());
-                    if (chunk.type === 'content') {
-                        onChunk(chunk.content);
-                    }
-                    else if (chunk.type === 'done') {
-                        onDone();
-                        ws.close();
-                        resolve();
-                    }
-                    else if (chunk.type === 'error') {
-                        onError(new Error(chunk.error));
-                        ws.close();
-                        reject(new Error(chunk.error));
-                    }
-                }
-                catch (e) {
-                    // Raw text chunk
-                    onChunk(data.toString());
-                }
-            });
-            ws.on('error', (error) => {
-                onError(error);
-                reject(error);
-            });
-            ws.on('close', () => {
-                resolve();
-            });
-        });
-    }
-    // ─── Chat completion helper ────────────────────────────────────────
-    // Routes all AI file commands through the Model Router
-    // (/v1/chat/completions on api.vigthoria.io) which is the only
-    // backend that reliably accepts our auth token.
-    async chatComplete(systemPrompt, userPrompt, model, maxTokens) {
-        const resolvedModel = model ? this.resolvePermittedModelId(model) : 'vigthoria-v3-code-35b';
-        const response = await this.modelRouterClient.post('/v1/chat/completions', {
-            model: resolvedModel,
-            messages: [
-                { role: 'system', content: systemPrompt },
-                { role: 'user', content: userPrompt },
-            ],
-            max_tokens: maxTokens || this.config.get('preferences').maxTokens || 4096,
-            temperature: 0.3,
-            stream: false,
-        });
-        const content = response.data.choices?.[0]?.message?.content || response.data.choices?.[0]?.text || '';
-        return typeof content === 'string' ? content : '';
-    }
-    // Code operations - Using Vigthoria Centralized API (via Model Router)
-    async generateCode(prompt, language, model) {
-        const isNonHtmlLang = !['html', 'css'].includes(language.toLowerCase());
-        const wordCount = prompt.trim().split(/\s+/).length;
-        // Prepend a forceful scope-enforcement instruction so the model
-        // doesn't expand a small task into an oversized glossy page.
-        const buildScopedPrompt = (retry) => {
-            if (retry && isNonHtmlLang) {
-                // Ultra-minimal retry prompt — no long instruction block
-                return `OUTPUT ONLY RAW ${language.toUpperCase()} CODE. MAXIMUM 10 LINES. NO DOM. NO HTML. NO CSS. NO ANIMATION. NO VALIDATION. NO COMMENTS.\n\n${prompt}`;
-            }
-            const lines = [
-                'IMPORTANT — MANDATORY SCOPE CONSTRAINTS (violation = failure):',
-                `1. You MUST output ONLY ${language.toUpperCase()} code. Do NOT output HTML, CSS, or DOM manipulation unless the language is html/css.`,
-                `2. The target language is: ${language}. Do not switch to a different language.`,
-                '3. Output ONLY what the user explicitly asked for. Nothing more.',
-                '4. If the prompt is ≤ 15 words, produce ≤ 80 lines of code maximum.',
-                '5. If the user says "tiny", "small", "simple", "minimal", or "basic", produce ≤ 50 lines.',
-                '6. NEVER add any of these unless the user EXPLICITLY requests them:',
-                '   - Hero sections, CTAs, testimonials, pricing tables, footers, navbars',
-                '   - CSS animations, gradients, neon effects, glass-morphism, particles',
-                '   - Google Fonts, Font Awesome, external CDN links, icon libraries',
-                '   - DOM manipulation, document.createElement, innerHTML',
-                '   - Responsive breakpoints, media queries (unless asked)',
-                '   - Multiple pages or components when one was requested',
-                '   - Input validation, error handling beyond what was requested',
-                '7. Prefer inline styles or a small <style> block ONLY if the language is html. No CSS frameworks.',
-                '8. Return raw code only — no markdown fences, no explanations, no comments about what could be added.',
-                '9. Match the complexity of the request: a "hello world" is 1-5 lines, a "multiply function" is 3-5 lines, a "button" is 5-15 lines.',
-            ];
-            if (isNonHtmlLang) {
-                lines.push(`10. This is a PURE ${language.toUpperCase()} task. ABSOLUTELY NO document.*, window.*, DOM, createElement, innerHTML, querySelector, addEventListener. Output a plain ${language} function/module ONLY.`);
-            }
-            lines.push('', prompt);
-            return lines.join('\n');
-        };
-        // First attempt — route through Model Router chat completions
-        const systemPrompt = `You are a code generator. Output ONLY raw ${language} code. No markdown fences, no explanations, no commentary. Just the code.`;
-        let code = await this.chatComplete(systemPrompt, buildScopedPrompt(false), model);
-        // Strip markdown fences if model included them
-        code = code.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim();
-        // Client-side validation: reject DOM-polluted or over-engineered responses for non-HTML languages
-        const needsRetry = isNonHtmlLang && (this.codeContainsDomPollution(code) ||
-            this.codeIsOverEngineered(code, prompt));
-        if (needsRetry) {
-            // Retry once with stronger constraint — via Model Router
-            code = await this.chatComplete(systemPrompt, buildScopedPrompt(true), model);
-            code = code.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim();
-            // If still polluted, strip DOM code client-side
-            if (this.codeContainsDomPollution(code)) {
-                code = this.stripDomPollution(code, language);
-            }
-        }
-        // Final cleanup: for non-HTML, if still over-engineered after retry,
-        // extract only the first complete function/class definition.
-        if (isNonHtmlLang && this.codeIsOverEngineered(code, prompt)) {
-            code = this.extractFirstFunction(code);
-        }
-        // Ensure balanced braces — model sometimes truncates closing braces
-        code = this.ensureBalancedBraces(code);
-        return code;
-    }
-    /**
-     * Ensure code has balanced curly braces by appending missing closing braces.
-     */
-    ensureBalancedBraces(code) {
-        // Count braces/parens/brackets outside strings and comments
-        let braces = 0, parens = 0, brackets = 0;
-        let inStr = null;
-        let inLine = false, inBlock = false;
-        for (let i = 0; i < code.length; i++) {
-            const ch = code[i], nx = code[i + 1] || '';
-            if (inLine) {
-                if (ch === '\n')
-                    inLine = false;
-                continue;
-            }
-            if (inBlock) {
-                if (ch === '*' && nx === '/') {
-                    inBlock = false;
-                    i++;
-                }
-                continue;
-            }
-            if (inStr) {
-                if (ch === inStr && code[i - 1] !== '\\')
-                    inStr = null;
-                continue;
-            }
-            if (ch === '/' && nx === '/') {
-                inLine = true;
-                continue;
-            }
-            if (ch === '/' && nx === '*') {
-                inBlock = true;
-                continue;
-            }
-            if (ch === '"' || ch === "'" || ch === '`') {
-                inStr = ch;
-                continue;
-            }
-            if (ch === '{')
-                braces++;
-            else if (ch === '}')
-                braces--;
-            else if (ch === '(')
-                parens++;
-            else if (ch === ')')
-                parens--;
-            else if (ch === '[')
-                brackets++;
-            else if (ch === ']')
-                brackets--;
-        }
-        let result = code.trimEnd();
-        for (let i = 0; i < braces; i++)
-            result += '\n}';
-        for (let i = 0; i < parens; i++)
-            result += ')';
-        for (let i = 0; i < brackets; i++)
-            result += ']';
-        return braces > 0 || parens > 0 || brackets > 0 ? result : code;
-    }
-    /**
-     * Quick JS/TS syntax validation using Node's built-in parser.
-     * Returns true if the code parses without errors.
-     */
-    validateJsSyntax(code) {
-        try {
-            // Use Function constructor to check syntax without executing
-            new Function(code);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Extract the first complete function/class from code.
-     * Used as last-resort when the model keeps over-producing.
-     */
-    extractFirstFunction(code) {
-        const lines = code.split('\n');
-        const funcStart = lines.findIndex(l => /^(export\s+)?(const\s+\w+\s*=\s*(\(|function)|function\s+\w+|class\s+\w+|def\s+\w+|fn\s+\w+|func\s+\w+)/.test(l.trim()));
-        if (funcStart === -1)
-            return code;
-        let braceDepth = 0;
-        let foundOpen = false;
-        const result = [];
-        for (let i = funcStart; i < lines.length; i++) {
-            const line = lines[i];
-            result.push(line);
-            braceDepth += (line.match(/{/g) || []).length;
-            braceDepth -= (line.match(/}/g) || []).length;
-            if (braceDepth > 0)
-                foundOpen = true;
-            if (foundOpen && braceDepth <= 0) {
-                break;
-            }
-        }
-        // If we reached the end without balancing braces, add closing
-        if (braceDepth > 0) {
-            result.push('};');
-        }
-        return result.join('\n');
-    }
-    /**
-     * Detect if code is excessively over-engineered for a short prompt.
-     * E.g. a "multiply function" request producing 20+ lines.
-     */
-    codeIsOverEngineered(code, prompt) {
-        const wordCount = prompt.trim().split(/\s+/).length;
-        const lineCount = code.trim().split('\n').length;
-        // Short prompt (≤15 words) should not produce more than 15 lines
-        if (wordCount <= 15 && lineCount > 15)
-            return true;
-        return false;
-    }
-    /**
-     * Detect if generated code contains DOM/HTML pollution inappropriate
-     * for a pure programming language like JavaScript, Python, etc.
-     */
-    codeContainsDomPollution(code) {
-        const domPatterns = /document\.(createElement|querySelector|getElementById|getElementsBy|body|head|addEventListener)|innerHTML|\.style\.(cssText|position|transform|animation)|@keyframes|\.appendChild|\.removeChild|window\.(onload|addEventListener)|CSSAnimation|new\s+Animation\b|\.getAnimations\s*\(|\.animate\s*\(/;
-        return domPatterns.test(code);
-    }
-    /**
-     * Strip DOM pollution from generated code, keeping only the pure logic.
-     * Used as last-resort fallback when the model repeatedly ignores constraints.
-     */
-    stripDomPollution(code, language) {
-        const lines = code.split('\n');
-        const cleanLines = [];
-        let insideDomBlock = false;
-        let braceDepth = 0;
-        for (const line of lines) {
-            // Detect start of DOM blocks
-            if (/document\.|\.style\.|\.appendChild|\.removeChild|\.textContent\s*=|@keyframes|addEventListener|CSSAnimation|\.getAnimations|\.animate\s*\(/.test(line) && !insideDomBlock) {
-                insideDomBlock = true;
-                braceDepth = 0;
-            }
-            if (insideDomBlock) {
-                braceDepth += (line.match(/{/g) || []).length;
-                braceDepth -= (line.match(/}/g) || []).length;
-                if (braceDepth <= 0) {
-                    insideDomBlock = false;
-                }
-                continue; // Skip DOM lines
-            }
-            cleanLines.push(line);
-        }
-        const cleaned = cleanLines.join('\n').trim();
-        // If we stripped too aggressively (less than 2 lines left), return a minimal stub
-        if (cleaned.split('\n').length < 2) {
-            return `// Auto-generated: model returned DOM code for a ${language} task.\n// Please regenerate or provide more specific instructions.`;
-        }
-        return cleaned;
-    }
-    // Senior Developer Mode - Planning + Generation + Quality Check
-    async generateProject(prompt, projectType, model) {
-        const sysPrompt = [
-            `You are a senior developer. Generate a complete ${projectType} project.`,
-            'Return a JSON object with these fields:',
-            '  "code": the full source code as a string,',
-            '  "plan": an object describing the architecture,',
-            '  "quality": { "lineCount": number, "score": number (0-100) }',
-            'Return ONLY the JSON object, no markdown fences.',
-        ].join('\n');
-        const raw = await this.chatComplete(sysPrompt, prompt, model, 8192);
-        try {
-            const cleaned = raw.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim();
-            const parsed = JSON.parse(cleaned);
-            return {
-                code: parsed.code || raw,
-                plan: parsed.plan,
-                quality: parsed.quality,
-            };
-        }
-        catch {
-            return { code: raw.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim() };
-        }
-    }
-    async explainCode(code, language) {
-        const sysPrompt = [
-            `You are a code explainer. Explain the following ${language} code clearly and concisely.`,
-            'Focus on what it does, how it works, and any notable patterns or potential issues.',
-            'Format your response as clean Markdown:',
-            '- Use ## headers for major sections (e.g. ## Overview, ## How It Works, ## Key Details).',
-            '- Use bullet points (- or *) for all lists. Do NOT use numbered lists.',
-            '- Wrap code references in backticks.',
-            '- Keep paragraphs short (2-3 sentences max).',
-            '- Do NOT use raw HTML or excessive blank lines.',
-            '- Do NOT nest numbered lists inside sections.',
-        ].join('\n');
-        return this.chatComplete(sysPrompt, code);
-    }
-    async reviewCode(code, language) {
-        const sysPrompt = [
-            `You are a senior code reviewer for ${language}. Analyze the code and return a JSON object with:`,
-            '  "score": number 0-100,',
-            '  "issues": [{ "type": string, "line": number, "message": string, "severity": "error"|"warning"|"info" }],',
-            '  "suggestions": [string]',
-            'Rules:',
-            '- Return concrete, line-specific issues with severity.',
-            '- Every issue MUST reference a line number.',
-            '- Report each distinct bug ONCE. Do NOT report the same bug multiple times with different wording.',
-            '- For trivial/short code (< 10 lines), report ONLY actual bugs. Do NOT pad with style, robustness, or best-practice suggestions.',
-            '- If you find a real bug (wrong operator, logic error, type mismatch), report ONLY that bug. Do NOT also suggest input validation, type checking, or error handling unless those are ACTUAL bugs.',
-            '- Prioritize REAL BUGS: wrong operators, logic errors, off-by-one, type mismatches.',
-            '- Do NOT suggest adding error handling, input validation, or documentation as issues unless the user explicitly asked for a style review.',
-            '- Return ONLY the JSON object, no markdown fences or extra text.',
-        ].join('\n');
-        let raw = {};
-        try {
-            const result = await this.chatComplete(sysPrompt, code);
-            const cleaned = result.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim();
-            raw = JSON.parse(cleaned);
-        }
-        catch {
-            // If parsing fails, return minimal review
-        }
-        const score = typeof raw.score === 'number' ? raw.score : 0;
-        const issues = Array.isArray(raw.issues) ? raw.issues : [];
-        const suggestions = Array.isArray(raw.suggestions) ? raw.suggestions : [];
-        // Merge client-side heuristics, but with tight dedup to avoid
-        // redundant over-reporting when the model already found the bug.
-        const modelFoundError = issues.some(i => i.severity === 'error');
-        const heuristic = this.heuristicCodeIssues(code, language);
-        for (const h of heuristic) {
-            // If the model already found a real error, skip non-error heuristics
-            // entirely — they're just padding (style, robustness, etc.)
-            if (modelFoundError && h.severity !== 'error')
-                continue;
-            // Semantic duplicate check: same line + (similar type OR overlapping
-            // keywords in the message).  This catches cases where the model
-            // and heuristic describe the same bug with different wording.
-            const hWords = new Set(h.message.toLowerCase().split(/\W+/).filter(w => w.length > 3));
-            const hTypeNorm = h.type.toLowerCase().replace(/[^a-z]/g, '');
-            const isSemanticallyDuplicate = issues.some((existing) => {
-                if (existing.line !== h.line)
-                    return false;
-                // Normalize types: "logic-error", "logic_error", "logic" all match
-                const eTypeNorm = existing.type.toLowerCase().replace(/[^a-z]/g, '');
-                if (eTypeNorm === hTypeNorm || eTypeNorm.startsWith(hTypeNorm) || hTypeNorm.startsWith(eTypeNorm))
-                    return true;
-                // Both errors on same line about the same category of problem
-                if (existing.severity === 'error' && h.severity === 'error')
-                    return true;
-                // Check keyword overlap — if ≥2 significant words match, it's the same finding
-                const eWords = existing.message.toLowerCase().split(/\W+/).filter(w => w.length > 3);
-                let overlap = 0;
-                for (const w of eWords) {
-                    if (hWords.has(w))
-                        overlap++;
-                }
-                return overlap >= 2;
-            });
-            if (!isSemanticallyDuplicate) {
-                issues.push(h);
-            }
-        }
-        // Sort: errors first, then warnings, then info
-        const severityOrder = { error: 0, warning: 1, info: 2 };
-        issues.sort((a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3));
-        // Prevent contradictory output: low score but zero issues.
-        if (score < 50 && issues.length === 0) {
-            issues.push({
-                type: 'quality',
-                line: 1,
-                message: `The analysis returned a low quality score (${score}/100) but did not enumerate specific issues. Re-run the review or inspect the file manually.`,
-                severity: 'warning',
-            });
-        }
-        return { score, issues, suggestions };
+            mcp_context_id: executionContext.mcpContextId || undefined,
+        };
+        return this.v3AgentClient.requestBackground('POST', '', body);
     }
-    /**
-     * Lightweight client-side heuristic scan: catches common code smells
-     * AND logic/arithmetic bugs so review never returns "score 30, no issues".
-     */
-    heuristicCodeIssues(code, language) {
-        const issues = [];
-        const lines = code.split('\n');
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            const lineNum = i + 1;
-            // console.log left in production code
-            if (/\bconsole\.(log|debug|info)\b/.test(line) && !/\/\//.test(line.slice(0, line.indexOf('console')))) {
-                issues.push({ type: 'quality', line: lineNum, message: 'console.log/debug statement — remove or replace with proper logging.', severity: 'warning' });
-            }
-            // TODO/FIXME/HACK comments
-            if (/\b(TODO|FIXME|HACK|XXX)\b/.test(line)) {
-                issues.push({ type: 'maintainability', line: lineNum, message: `Unresolved ${line.match(/\b(TODO|FIXME|HACK|XXX)\b/)?.[0]} comment.`, severity: 'info' });
-            }
-            // Empty catch blocks
-            if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(line)) {
-                issues.push({ type: 'error-handling', line: lineNum, message: 'Empty catch block — errors are silently swallowed.', severity: 'warning' });
-            }
-            // Very long lines (> 200 chars)
-            if (line.length > 200) {
-                issues.push({ type: 'style', line: lineNum, message: `Line exceeds 200 characters (${line.length}).`, severity: 'info' });
-            }
-            // Arithmetic / logic bugs: function named 'add' but using subtraction
-            if (/\breturn\s+\w+\s*-\s*\w+/.test(line)) {
-                // Check if the enclosing function name implies addition
-                for (let j = i; j >= Math.max(0, i - 5); j--) {
-                    if (/function\s+add\b/i.test(lines[j]) || /\badd\s*[=(]/.test(lines[j])) {
-                        issues.push({ type: 'logic', line: lineNum, message: 'Subtraction operator in a function named "add" — likely should be addition (+).', severity: 'error' });
-                        break;
-                    }
-                }
-            }
-            // Multiplication where addition is expected
-            if (/\breturn\s+\w+\s*\*\s*\w+/.test(line)) {
-                for (let j = i; j >= Math.max(0, i - 5); j--) {
-                    if (/function\s+add\b/i.test(lines[j]) || /\badd\s*[=(]/.test(lines[j])) {
-                        issues.push({ type: 'logic', line: lineNum, message: 'Multiplication operator in a function named "add" — likely should be addition (+).', severity: 'error' });
-                        break;
-                    }
-                }
-            }
-            // Division where subtraction/addition is expected in subtract
-            if (/\breturn\s+\w+\s*\+\s*\w+/.test(line)) {
-                for (let j = i; j >= Math.max(0, i - 5); j--) {
-                    if (/function\s+subtract\b/i.test(lines[j]) || /\bsubtract\s*[=(]/.test(lines[j])) {
-                        issues.push({ type: 'logic', line: lineNum, message: 'Addition operator in a function named "subtract" — likely should be subtraction (-).', severity: 'error' });
-                        break;
+    async listV3BackgroundJobs(limit = 20) {
+        const data = await this.v3AgentClient.requestBackground('GET', '', undefined, `?limit=${encodeURIComponent(String(limit))}`);
+        return Array.isArray(data.jobs) ? data.jobs : [];
+    }
+    async getV3BackgroundJob(jobId) {
+        return this.v3AgentClient.requestBackground('GET', encodeURIComponent(jobId));
+    }
+    async cancelV3BackgroundJob(jobId) {
+        return this.v3AgentClient.requestBackground('POST', `${encodeURIComponent(jobId)}/cancel`);
+    }
+    async resolveV3BackgroundApproval(jobId, approvalId, approved, allowMode = 'once') {
+        return this.v3AgentClient.resolveApproval({ context_id: jobId, approval_id: approvalId, approved, allow_mode: allowMode });
+    }
+    async getV3BackgroundJobFiles(jobId) {
+        return this.v3AgentClient.requestBackground('GET', `${encodeURIComponent(jobId)}/files`);
+    }
+    async applyV3BackgroundJobFiles(jobId, context = {}) {
+        const [data, job] = await Promise.all([
+            this.getV3BackgroundJobFiles(jobId),
+            this.getV3BackgroundJob(jobId),
+        ]);
+        if (job?.status !== 'completed' || job?.result?.success === false || job?.result?.type === 'error') {
+            throw new Error(`Background job ${jobId} is not a successful completed job and cannot be applied.`);
+        }
+        const mutatedPaths = new Set();
+        const addMutatedPath = (value) => {
+            const normalized = this.normalizeWorkspaceRelativePath(String(value || ''));
+            if (!normalized || path.isAbsolute(normalized) || normalized.split('/').includes('..'))
+                return;
+            mutatedPaths.add(normalized);
+        };
+        for (const filePath of (data.confirmed_mutations || []))
+            addMutatedPath(filePath);
+        for (const event of (Array.isArray(job?.events) ? job.events : [])) {
+            if (event?.type === 'file_mutation' && event?.action !== 'delete')
+                addMutatedPath(event.path);
+            if (event?.type === 'executor_complete') {
+                let summary = event.summary;
+                if (typeof summary === 'string') {
+                    try {
+                        summary = JSON.parse(summary);
                     }
-                }
-            }
-            // Accumulator/reducer bug: subtraction used in a reduce/total/sum context
-            // e.g. "sum - item.price" in a function named calculateTotal, getTotal, etc.
-            if (/\w+\s*-\s*\w+\.\s*(price|cost|amount|value|total|quantity|count)\b/.test(line) || /\w+\.\s*(price|cost|amount|value|total)\s*-\s*/.test(line)) {
-                // Check enclosing function/method name for total/sum/aggregate semantics
-                for (let j = i; j >= Math.max(0, i - 10); j--) {
-                    if (/(function\s+)?(calculate|calc|get|compute|sum|total|aggregate|accumulate)\s*(Total|Sum|Cost|Price|Amount|All)?\s*[=(]/i.test(lines[j]) || /\.(reduce|forEach|map)\s*\(/.test(lines[j])) {
-                        // Also check if this looks like an accumulator pattern (sum - something instead of sum + something)
-                        if (/\w+\s*-\s*\w+\.\s*(price|cost|amount|value|total|quantity)\b/.test(line)) {
-                            issues.push({ type: 'logic', line: lineNum, message: 'Subtraction used in an accumulation context (total/sum/reduce) — likely should be addition (+).', severity: 'error' });
-                        }
-                        break;
+                    catch {
+                        summary = null;
                     }
                 }
-            }
-            // Mismatched function name vs operator: sum/total function using wrong operator
-            if (/\breturn\b/.test(line)) {
-                for (let j = i; j >= Math.max(0, i - 8); j--) {
-                    const funcMatch = lines[j].match(/function\s+(\w+)/i) || lines[j].match(/(?:const|let|var)\s+(\w+)\s*=/i);
-                    if (funcMatch) {
-                        const funcName = funcMatch[1].toLowerCase();
-                        if ((funcName.includes('total') || funcName.includes('sum') || funcName.includes('add')) && /\s-\s/.test(line) && !/\s\+\s/.test(line)) {
-                            const alreadyReported = issues.some(iss => iss.line === lineNum && iss.type === 'logic');
-                            if (!alreadyReported) {
-                                issues.push({ type: 'logic', line: lineNum, message: `Subtraction operator in "${funcMatch[1]}" — function name implies addition. Likely should use + instead of -.`, severity: 'error' });
-                            }
-                        }
-                        break;
+                if (summary?.status === 'completed') {
+                    for (const filePath of [...(summary.changed_files || []), ...(summary.created_files || [])]) {
+                        addMutatedPath(filePath);
                     }
                 }
             }
-            // Off-by-one: comparing with === where <= or >= may be needed
-            // (not implemented yet — would require more complex AST analysis)
-            // Limit to 15 heuristic issues
-            if (issues.length >= 15)
-                break;
-        }
-        return issues;
-    }
-    async fixCode(code, language, fixType) {
-        // Client-side syntax pre-check: detect obvious errors and include
-        // them in the request so the model has concrete signals.
-        const syntaxHints = fixType === 'bugs' || fixType === 'syntax' ? this.detectSyntaxErrors(code, language) : '';
-        // Run heuristic logic analysis, but ONLY pass hints relevant to the fixType
-        const heuristicIssues = this.heuristicCodeIssues(code, language);
-        const relevantIssues = heuristicIssues.filter(issue => {
-            if (fixType === 'bugs' || fixType === 'logic')
-                return issue.type === 'logic' || issue.severity === 'error';
-            if (fixType === 'syntax')
-                return issue.type !== 'logic' && issue.severity === 'error';
-            if (fixType === 'style')
-                return issue.type === 'style' || issue.type === 'quality';
-            if (fixType === 'security')
-                return issue.type === 'security';
-            if (fixType === 'performance')
-                return issue.type === 'performance';
-            return true; // 'all' or unknown fixType: include everything
-        });
-        const logicHints = relevantIssues
-            .map(i => `Line ${i.line}: [${i.type}] ${i.message}`)
-            .join('\n// ');
-        const allHints = [syntaxHints, logicHints].filter(Boolean).join('\n// ');
-        // Build a constraint preamble that's stricter for syntax-only mode.
-        let preamble;
-        if (fixType === 'syntax') {
-            preamble = allHints
-                ? `// SYNTAX ERRORS DETECTED BY CLIENT:\n// ${allHints}\n// RULES: Fix ONLY bracket/parenthesis/brace mismatches and keyword typos. Do NOT rename functions, do NOT add comments, do NOT restructure or reformat. Output the corrected code ONLY.\n\n`
-                : '';
-        }
-        else {
-            preamble = allHints
-                ? `// BUGS DETECTED BY STATIC ANALYSIS — YOU MUST FIX THESE:\n// ${allHints}\n// IMPORTANT: Fix ONLY these specific bugs. Do not add comments, do not restructure the code, do not add or remove lines beyond the minimal fix.\n\n`
-                : '';
-        }
-        const augmentedCode = preamble ? `${preamble}${code}` : code;
-        const sysPrompt = [
-            `You are a ${language} code fixer. Fix the code for: ${fixType}.`,
-            'Return a JSON object with:',
-            '  "fixed": the COMPLETE corrected source code as a string (not a snippet — the full file),',
-            '  "changes": [{ "line": number, "before": string, "after": string, "reason": string }]',
-            'Rules:',
-            '- The "fixed" field MUST contain the entire corrected source code with ALL lines, including unchanged lines.',
-            '- The "fixed" code MUST have balanced braces, parentheses, and brackets.',
-            '- Fix ONLY the issues related to the fix type.',
-            '- Do not add comments, do not restructure beyond the minimal fix.',
-            '- Return ONLY the JSON object, no markdown fences.',
-        ].join('\n');
-        let raw = {};
-        try {
-            const result = await this.chatComplete(sysPrompt, augmentedCode);
-            const cleaned = result.replace(/^```[\w]*\n?/gm, '').replace(/\n?```$/gm, '').trim();
-            raw = JSON.parse(cleaned);
-        }
-        catch {
-            // If parsing fails, fall through to client-side handling
-        }
-        let fixed = typeof raw.fixed === 'string' ? raw.fixed : (typeof raw.code === 'string' ? raw.code : code);
-        let changes = Array.isArray(raw.changes) ? raw.changes : [];
-        // If server returned no changes but we found issues, strip
-        // our injected comment prefix from the returned code and attempt
-        // a basic client-side repair.
-        if (changes.length === 0 && preamble && fixed === augmentedCode) {
-            fixed = code; // restore original
-        }
-        // Strip the injected comment block if it leaked into the output
-        if (fixed.startsWith('// BUGS DETECTED BY STATIC ANALYSIS') || fixed.startsWith('// SYNTAX ERRORS DETECTED BY CLIENT')) {
-            const idx = fixed.indexOf('\n\n');
-            if (idx !== -1) {
-                fixed = fixed.slice(idx + 2);
-            }
         }
-        // For syntax-only fixes, strip any comments the model added that
-        // weren't in the original code (e.g. "// Fixed mismatched parentheses").
-        if (fixType === 'syntax' && fixed !== code) {
-            fixed = this.stripInjectedComments(code, fixed, language);
-        }
-        // Safety net: for syntax fixes, ensure the fix didn't make bracket
-        // balance worse.  If the original had more closing delimiters than
-        // the fix, append the missing ones.
-        if (fixType === 'syntax' && fixed !== code) {
-            fixed = this.repairBracketBalance(code, fixed);
-        }
-        // Final bracket-balance guarantee — ensure the emitted code has
-        // balanced braces/parens/brackets regardless of what the model returned.
-        fixed = this.ensureBalancedBraces(fixed);
-        // For JS/TS syntax fixes, validate the output actually parses.
-        // If it doesn't, attempt a more aggressive bracket repair.
-        if ((fixType === 'syntax' || fixType === 'bugs') && fixed !== code) {
-            const lang = language.toLowerCase();
-            if (['javascript', 'js', 'typescript', 'ts'].includes(lang)) {
-                if (!this.validateJsSyntax(fixed)) {
-                    // Try once more: strip any remaining injected comments and re-balance
-                    let repaired = this.stripInjectedComments(code, fixed, language);
-                    repaired = this.ensureBalancedBraces(repaired);
-                    if (this.validateJsSyntax(repaired)) {
-                        fixed = repaired;
-                    }
-                    // If still invalid, return the best-effort fix — better than
-                    // silently reverting to the original broken code.
-                }
-            }
+        if (mutatedPaths.size === 0) {
+            throw new Error(`Background job ${jobId} has no confirmed successful file mutations to apply.`);
         }
-        // If there are still no changes but the fixed code differs, compute
-        // a semantic diff using LCS so inserted/removed lines don't cause
-        // every subsequent line to appear as changed.
-        if (changes.length === 0 && fixed !== code) {
-            // Use a clean reason string — strip verbose static-analysis hints
-            const cleanReason = relevantIssues.length > 0
-                ? relevantIssues.map(i => i.message).join('; ')
-                : 'AI-suggested fix';
-            changes = this.computeSemanticDiff(code, fixed, cleanReason);
+        const rootPath = this.resolveAgentTargetPath({
+            ...context,
+            workspacePath: context.workspacePath || data.local_workspace_path,
+            projectPath: context.projectPath || data.local_workspace_path,
+            targetPath: context.targetPath || data.local_workspace_path,
+        });
+        if (!rootPath) {
+            throw new Error('No local workspace path available for applying background job files.');
         }
-        return { fixed, changes };
-    }
-    /**
-     * Compute a semantic diff between original and fixed code using
-     * Longest Common Subsequence (LCS) to avoid the line-shift inflation
-     * bug where inserting one line flags all subsequent lines as changed.
-     */
-    computeSemanticDiff(original, fixed, reason) {
-        const origLines = original.split('\n');
-        const fixedLines = fixed.split('\n');
-        const changes = [];
-        // Build LCS table
-        const m = origLines.length;
-        const n = fixedLines.length;
-        const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
-        for (let i = 1; i <= m; i++) {
-            for (let j = 1; j <= n; j++) {
-                if (origLines[i - 1] === fixedLines[j - 1]) {
-                    dp[i][j] = dp[i - 1][j - 1] + 1;
-                }
-                else {
-                    dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
-                }
+        const applied = [];
+        const skipped = [];
+        for (const [relativePath, content] of Object.entries(data.files || {})) {
+            const normalizedRelativePath = this.normalizeWorkspaceRelativePath(relativePath);
+            if (!mutatedPaths.has(normalizedRelativePath)) {
+                skipped.push(relativePath);
+                continue;
             }
-        }
-        // Backtrack to find the diff
-        let i = m, j = n;
-        const ops = [];
-        while (i > 0 || j > 0) {
-            if (i > 0 && j > 0 && origLines[i - 1] === fixedLines[j - 1]) {
-                ops.push({ type: 'keep', origLine: i, fixedLine: j, text: origLines[i - 1] });
-                i--;
-                j--;
+            if (typeof content !== 'string') {
+                skipped.push(relativePath);
+                continue;
             }
-            else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
-                ops.push({ type: 'add', fixedLine: j, text: fixedLines[j - 1] });
-                j--;
+            if (this.writeV3AgentWorkspaceFile(rootPath, relativePath, content, rootPath)) {
+                applied.push(relativePath);
             }
             else {
-                ops.push({ type: 'remove', origLine: i, text: origLines[i - 1] });
-                i--;
-            }
-        }
-        ops.reverse();
-        // Merge adjacent remove+add pairs into single change entries
-        let idx = 0;
-        while (idx < ops.length) {
-            const op = ops[idx];
-            if (op.type === 'remove') {
-                // Look ahead for a matching 'add' immediately after
-                if (idx + 1 < ops.length && ops[idx + 1].type === 'add') {
-                    changes.push({
-                        line: op.origLine,
-                        before: op.text,
-                        after: ops[idx + 1].text,
-                        reason: reason || 'AI-suggested fix',
-                    });
-                    idx += 2;
-                    continue;
-                }
-                changes.push({
-                    line: op.origLine,
-                    before: op.text,
-                    after: '(line removed)',
-                    reason: reason || 'AI-suggested fix',
-                });
-            }
-            else if (op.type === 'add') {
-                changes.push({
-                    line: op.fixedLine,
-                    before: '(new line)',
-                    after: op.text,
-                    reason: reason || 'AI-suggested fix',
-                });
+                skipped.push(relativePath);
             }
-            idx++;
-        }
-        if (changes.length === 0) {
-            changes.push({ line: 1, before: '(whitespace changes)', after: '(see fixed file)', reason: reason || 'AI-suggested fix' });
         }
-        return changes;
+        return { applied, skipped, status: data.status };
     }
-    /**
-     * Lightweight client-side syntax error detection.
-     * Returns a human-readable description of obvious errors, or empty string.
-     */
-    detectSyntaxErrors(code, language) {
-        const lang = language.toLowerCase();
-        const errors = [];
-        if (lang === 'javascript' || lang === 'typescript' || lang === 'js' || lang === 'ts') {
-            // Bracket matching
-            let braces = 0, brackets = 0, parens = 0;
-            // Track string context (simple heuristic — not a full parser)
-            let inString = null;
-            let inLineComment = false;
-            let inBlockComment = false;
-            for (let i = 0; i < code.length; i++) {
-                const ch = code[i];
-                const next = code[i + 1] || '';
-                if (inLineComment) {
-                    if (ch === '\n')
-                        inLineComment = false;
-                    continue;
-                }
-                if (inBlockComment) {
-                    if (ch === '*' && next === '/') {
-                        inBlockComment = false;
-                        i++;
-                    }
-                    continue;
-                }
-                if (inString) {
-                    if (ch === inString && code[i - 1] !== '\\')
-                        inString = null;
-                    continue;
-                }
-                if (ch === '/' && next === '/') {
-                    inLineComment = true;
-                    continue;
-                }
-                if (ch === '/' && next === '*') {
-                    inBlockComment = true;
-                    continue;
-                }
-                if (ch === '"' || ch === "'" || ch === '`') {
-                    inString = ch;
-                    continue;
-                }
-                if (ch === '{')
-                    braces++;
-                else if (ch === '}')
-                    braces--;
-                else if (ch === '[')
-                    brackets++;
-                else if (ch === ']')
-                    brackets--;
-                else if (ch === '(')
-                    parens++;
-                else if (ch === ')')
-                    parens--;
-            }
-            if (braces !== 0)
-                errors.push(`Mismatched braces (balance: ${braces > 0 ? '+' : ''}${braces})`);
-            if (brackets !== 0)
-                errors.push(`Mismatched brackets (balance: ${brackets > 0 ? '+' : ''}${brackets})`);
-            if (parens !== 0)
-                errors.push(`Mismatched parentheses (balance: ${parens > 0 ? '+' : ''}${parens})`);
-            // Detect obvious keyword typos
-            const lines = code.split('\n');
-            for (let li = 0; li < lines.length; li++) {
-                const line = lines[li];
-                if (/\bfuncion\b|\bfuction\b|\bfuntion\b/i.test(line))
-                    errors.push(`Line ${li + 1}: Misspelled 'function'`);
-                if (/\bretrun\b/i.test(line))
-                    errors.push(`Line ${li + 1}: Misspelled 'return'`);
-                if (/\bconts\b|\bcosnt\b/i.test(line))
-                    errors.push(`Line ${li + 1}: Misspelled 'const'`);
-            }
+    async runOperatorWorkflow(message, context = {}) {
+        const executionContext = await this.bindExecutionContext(context);
+        const requestedOperatorTimeoutMs = Number(context.operatorTimeoutMs ?? DEFAULT_OPERATOR_TIMEOUT_MS);
+        const timeoutMs = Number.isFinite(requestedOperatorTimeoutMs) && requestedOperatorTimeoutMs > 0
+            ? requestedOperatorTimeoutMs
+            : 0;
+        const workspacePath = executionContext.workspacePath || executionContext.projectPath || executionContext.targetPath || process.cwd();
+        const workspaceSummary = this.buildLocalWorkspaceSummary(workspacePath);
+        const operatorWorkspaceAlias = `vigthoria://workspace/${encodeURIComponent(path.basename(workspacePath))}`;
+        const requestedModel = String(executionContext.model || 'code');
+        const resolvedModel = this.resolveModelId(requestedModel);
+        try {
+            return await this.operatorClient.run({
+                message,
+                executionContext,
+                workspaceAlias: operatorWorkspaceAlias,
+                workspaceSummary,
+                requestedModel,
+                resolvedModel,
+                timeoutMs,
+                onStreamEvent: typeof context.onStreamEvent === 'function' ? context.onStreamEvent : undefined,
+            });
         }
-        if (lang === 'python' || lang === 'py') {
-            const lines = code.split('\n');
-            for (let li = 0; li < lines.length; li++) {
-                const line = lines[li];
-                if (/^\s*(def|class|if|elif|else|for|while|try|except|with)\b/.test(line) && !line.trimEnd().endsWith(':') && !line.trimEnd().endsWith('\\')) {
-                    errors.push(`Line ${li + 1}: Missing colon after '${line.trim().split(/\s/)[0]}'`);
-                }
+        catch (error) {
+            if (error instanceof OperatorClientError) {
+                throw new CLIError(error.message, error.category, { cause: error });
             }
+            throw error;
         }
-        return errors.join('; ');
     }
     /**
-     * Strip comment lines that the model added during a fix but were not
-     * present in the original code.  Used for syntax-only fixes where the
-     * model tends to annotate its changes with "// Fixed ..." comments.
+     * Chat API - Direct Vigthoria Models API Architecture
+     *
+     * PRIMARY: api.vigthoria.io - Direct access to Vigthoria Model Router
+     *          This is the centralized public API for all AI operations.
+     *          Works for both authenticated and unauthenticated users.
+     *
+     * FALLBACK: Coder Cloud API - For authenticated users only
+     *
+     * NO localhost fallbacks - CLI is for external users, not server-side!
      */
-    stripInjectedComments(original, fixed, language) {
-        const lang = language.toLowerCase();
-        // Only handle JS/TS/Python single-line comment patterns for now
-        let wholeLineRe;
-        let inlineRe;
-        if (lang === 'python' || lang === 'py') {
-            wholeLineRe = /^\s*#\s/;
-            inlineRe = /\s+#\s.*$/;
-        }
-        else {
-            wholeLineRe = /^\s*\/\/\s/;
-            inlineRe = /\s+\/\/\s.*$/;
-        }
-        const origLines = original.split('\n');
-        const origSet = new Set(origLines.map(l => l.trim()));
-        const fixedLines = fixed.split('\n');
-        const result = [];
-        for (let idx = 0; idx < fixedLines.length; idx++) {
-            let line = fixedLines[idx];
-            // Remove whole-line comments not in original
-            if (wholeLineRe.test(line) && !origSet.has(line.trim())) {
-                continue;
-            }
-            // Strip inline trailing comments the model added.
-            // Only strip if the corresponding original line at the same position
-            // didn't have an inline comment at all.
-            if (inlineRe.test(line)) {
-                const origLine = idx < origLines.length ? origLines[idx] : '';
-                if (!inlineRe.test(origLine)) {
-                    line = line.replace(inlineRe, '');
-                }
-            }
-            result.push(line);
-        }
-        return result.join('\n');
+    async chat(messages, model, _useLocal = false) {
+        const response = await this.modelTransportService.chat(messages, model);
+        this.lastChatTransportErrors = this.modelTransportService.getLastErrors();
+        if (response)
+            return response;
+        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');
     }
-    /**
-     * Ensure the fixed code hasn't lost closing delimiters relative to the
-     * original.  Counts {, }, (, ), [, ] outside strings/comments and if
-     * the fix has fewer closers than the original, appends the missing ones.
-     */
-    repairBracketBalance(original, fixed) {
-        const count = (src) => {
-            let braces = 0, parens = 0, brackets = 0;
-            let inStr = null;
-            let inLine = false, inBlock = false;
-            for (let i = 0; i < src.length; i++) {
-                const ch = src[i], nx = src[i + 1] || '';
-                if (inLine) {
-                    if (ch === '\n')
-                        inLine = false;
-                    continue;
-                }
-                if (inBlock) {
-                    if (ch === '*' && nx === '/') {
-                        inBlock = false;
-                        i++;
-                    }
-                    continue;
-                }
-                if (inStr) {
-                    if (ch === inStr && src[i - 1] !== '\\')
-                        inStr = null;
-                    continue;
-                }
-                if (ch === '/' && nx === '/') {
-                    inLine = true;
-                    continue;
-                }
-                if (ch === '/' && nx === '*') {
-                    inBlock = true;
-                    continue;
-                }
-                if (ch === '"' || ch === "'" || ch === '`') {
-                    inStr = ch;
-                    continue;
-                }
-                if (ch === '{')
-                    braces++;
-                else if (ch === '}')
-                    braces--;
-                else if (ch === '(')
-                    parens++;
-                else if (ch === ')')
-                    parens--;
-                else if (ch === '[')
-                    brackets++;
-                else if (ch === ']')
-                    brackets--;
-            }
-            return { braces, parens, brackets };
-        };
-        const orig = count(original);
-        const fix = count(fixed);
-        const append = [];
-        // If original was balanced (or close) but fix is missing closers,
-        // append them.  Only act when the fix is *more unbalanced* than original.
-        if (fix.braces > orig.braces) {
-            for (let i = 0; i < fix.braces - orig.braces; i++)
-                append.push('}');
-        }
-        if (fix.parens > orig.parens) {
-            for (let i = 0; i < fix.parens - orig.parens; i++)
-                append.push(')');
-        }
-        if (fix.brackets > orig.brackets) {
-            for (let i = 0; i < fix.brackets - orig.brackets; i++)
-                append.push(']');
-        }
-        if (append.length > 0) {
-            return fixed.trimEnd() + '\n' + append.join('\n');
-        }
-        return fixed;
+    resolvePermittedModelId(shortName) {
+        return this.modelGovernance.resolvePermittedModelId(shortName);
+    }
+    // ─── Chat completion helper ────────────────────────────────────────
+    // Routes all AI file commands through the Model Router
+    // (/v1/chat/completions on api.vigthoria.io) which is the only
+    // backend that reliably accepts our auth token.
+    async chatComplete(systemPrompt, userPrompt, model, maxTokens) {
+        return this.modelTransportService.complete(systemPrompt, userPrompt, model, maxTokens);
+    }
+    // Compatibility facade for code generation/review commands.
+    generateCode(prompt, language, model) {
+        return this.codeOperations.generateCode(prompt, language, model);
+    }
+    generateProject(prompt, projectType, model) {
+        return this.codeOperations.generateProject(prompt, projectType, model);
+    }
+    explainCode(code, language) {
+        return this.codeOperations.explainCode(code, language);
+    }
+    reviewCode(code, language) {
+        return this.codeOperations.reviewCode(code, language);
+    }
+    fixCode(code, language, fixType) {
+        return this.codeOperations.fixCode(code, language, fixType);
     }
     // Model resolution - maps Vigthoria model names to internal IDs
     // INTERNAL USE ONLY - users see only Vigthoria branding
     resolveModelId(shortName) {
-        const modelMap = {
-            // ═══════════════════════════════════════════════════════════════
-            // Vigthoria server infrastructure models
-            // ═══════════════════════════════════════════════════════════════
-            'fast': 'vigthoria-v3-balanced-4b',
-            'mini': 'vigthoria-mini-0.6b',
-            'balanced': 'vigthoria-v3-balanced-4b',
-            'balanced-4b': 'vigthoria-v3-balanced-4b',
-            'creative': 'vigthoria-creative-9b-v4',
-            // Code Models - 35B is the default powerhouse
-            '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',
-            'code-9b': 'vigthoria-v3-code-9b',
-            'pro': 'vigthoria-v3-code-35b',
-            'agent': 'vigthoria-v3-code-35b',
-            'vigthoria-code': 'vigthoria-v3-code-35b',
-            'vigthoria-agent': 'vigthoria-v3-code-35b',
-            // ═══════════════════════════════════════════════════════════════
-            // VIGTHORIA CLOUD - current billing catalog aliases
-            // ═══════════════════════════════════════════════════════════════
-            'cloud': 'vigthoria-cloud-balanced',
-            'cloud-code': 'vigthoria-cloud-code',
-            'cloud-balanced': 'vigthoria-cloud-balanced',
-            'cloud-fast': 'vigthoria-cloud-fast',
-            'cloud-power': 'vigthoria-cloud-power',
-            'cloud-maximum': 'vigthoria-cloud-maximum',
-            'cloud-reason': 'vigthoria-cloud-power',
-            'ultra': 'vigthoria-cloud-maximum',
-            // Legacy aliases kept for backward compatibility
-            'cloud-pro': 'vigthoria-cloud-power',
-            'cloud-k2': 'vigthoria-cloud-power',
-            'cloud-ultra': 'vigthoria-cloud-maximum',
-        };
-        // If already a full model ID, return as-is
-        if (shortName.includes('vigthoria') || shortName.includes('/') || shortName.includes(':')) {
-            if (modelMap[shortName]) {
-                return modelMap[shortName];
-            }
-            return shortName;
-        }
-        return modelMap[shortName] || 'vigthoria-v3-code-35b';
+        return this.modelGovernance.resolveModelId(shortName);
     }
     async getCoderHealth() {
         try {
-            const response = await this.client.get('/api/health', { timeout: 5000 });
+            const response = await this.client.get('/api/health', { timeout: 12000 });
             const ok = response.data?.status === 'ok' || response.data?.healthy === true;
             return {
                 name: 'Coder API',
@@ -6183,75 +3702,10 @@ document.addEventListener('DOMContentLoaded', () => {
      * 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) {
-            const sh = selfHostedHealth;
-            probes.unshift({
-                name: sh.name || 'Dedicated Models API',
-                run: async () => ({ ok: sh.ok, error: sh.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,
-        };
+        return this.capabilityHealthService.runModelPreflight(requestedModel);
     }
     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;
+        return this.capabilityHealthService.mapPreflightEndpoint(endpoint);
     }
     getLastChatTransportErrors() {
         return this.lastChatTransportErrors;
@@ -6291,7 +3745,7 @@ document.addEventListener('DOMContentLoaded', () => {
             error: String(result.error || ''),
         });
         for (let attempt = 0; attempt < 3; attempt += 1) {
-            const response = await fetch(endpoint, {
+            const response = await this.fetch(endpoint, {
                 method: 'POST',
                 headers: { ...headers, 'Content-Type': 'application/json' },
                 body,
@@ -6335,7 +3789,7 @@ document.addEventListener('DOMContentLoaded', () => {
         const candidates = ['/v1/models', '/models', '/api/models', '/api/tags'];
         for (const endpoint of candidates) {
             try {
-                const response = await client.get(endpoint, { timeout: 5000 });
+                const response = await client.get(endpoint, { timeout: 12000 });
                 const modelCount = this.extractModelCount(response.data);
                 if (modelCount > 0) {
                     return { modelCount, endpoint };
@@ -6351,7 +3805,7 @@ document.addEventListener('DOMContentLoaded', () => {
         const modelsApiUrl = this.config.get('modelsApiUrl');
         try {
             const [healthResponse, modelProbe] = await Promise.all([
-                this.modelRouterClient.get('/health', { timeout: 5000 }),
+                this.modelRouterClient.get('/health', { timeout: 12000 }),
                 this.probeModelList(this.modelRouterClient),
             ]);
             const healthOk = this.isHealthyServicePayload(healthResponse.data);
@@ -6384,7 +3838,7 @@ document.addEventListener('DOMContentLoaded', () => {
         }
         try {
             const [healthResponse, modelProbe] = await Promise.all([
-                this.selfHostedModelRouterClient.get('/health', { timeout: 5000 }),
+                this.selfHostedModelRouterClient.get('/health', { timeout: 12000 }),
                 this.probeModelList(this.selfHostedModelRouterClient),
             ]);
             const healthOk = this.isHealthyServicePayload(healthResponse.data);
@@ -6422,8 +3876,8 @@ document.addEventListener('DOMContentLoaded', () => {
         for (const endpoint of candidates) {
             try {
                 const controller = new AbortController();
-                const timer = setTimeout(() => controller.abort(), 3000);
-                const response = await fetch(endpoint, {
+                const timer = setTimeout(() => controller.abort(), 12000);
+                const response = await this.fetch(endpoint, {
                     method: 'GET',
                     headers,
                     signal: controller.signal,
@@ -6471,7 +3925,7 @@ document.addEventListener('DOMContentLoaded', () => {
         try {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), 2000);
-            const probe = await fetch(runUrl, { method: 'OPTIONS', headers, signal: controller.signal });
+            const probe = await this.fetch(runUrl, { method: 'OPTIONS', headers, signal: controller.signal });
             clearTimeout(timer);
             if (probe.ok || probe.status === 204 || probe.status === 405) {
                 return {
@@ -6497,9 +3951,13 @@ document.addEventListener('DOMContentLoaded', () => {
         const endpoint = process.env.VIGTHORIA_HYPERLOOP_URL || `${configuredApiUrl}/api/hyperloop/health`;
         try {
             const token = this.getAccessToken();
+            const hyperLoopServiceKey = process.env.VIGTHORIA_HYPERLOOP_SERVICE_KEY || process.env.HYPERLOOP_SERVICE_KEY || '';
             const response = await fetchWithServiceTimeout(endpoint, {
                 method: 'GET',
-                headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+                headers: {
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                    ...(hyperLoopServiceKey ? { 'X-Service-Key': hyperLoopServiceKey } : {}),
+                },
             });
             if (!response.ok) {
                 throw new Error(`Hyper Loop health ${response.status}`);
@@ -6527,13 +3985,17 @@ document.addEventListener('DOMContentLoaded', () => {
         const endpoint = process.env.VIGTHORIA_HYPERLOOP_EXECUTE_URL || `${configuredApiUrl}/api/hyperloop/execute`;
         const modulesEndpoint = process.env.VIGTHORIA_HYPERLOOP_MODULES_URL || `${configuredApiUrl}/api/hyperloop/modules`;
         const token = this.getAccessToken();
+        const hyperLoopServiceKey = process.env.VIGTHORIA_HYPERLOOP_SERVICE_KEY || process.env.HYPERLOOP_SERVICE_KEY || '';
+        const hyperLoopHeaders = {
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...(hyperLoopServiceKey ? { 'X-Service-Key': hyperLoopServiceKey } : {}),
+        };
         const projectPath = this.resolveAgentTargetPath(context);
+        const projectAlias = `vigthoria://workspace/${encodeURIComponent(path.basename(projectPath || 'workspace'))}`;
         try {
             const modulesResponse = await fetchWithServiceTimeout(modulesEndpoint, {
                 method: 'GET',
-                headers: {
-                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                },
+                headers: hyperLoopHeaders,
             });
             if (!modulesResponse.ok) {
                 throw new Error(`Repo memory modules ${modulesResponse.status}`);
@@ -6545,27 +4007,26 @@ document.addEventListener('DOMContentLoaded', () => {
             try {
                 const probeResponse = await fetchWithServiceTimeout(endpoint, {
                     method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                    },
+                    headers: { 'Content-Type': 'application/json', ...hyperLoopHeaders },
                     body: JSON.stringify({
                         module: 'repo_context_compactor',
                         payload: {
-                            path: projectPath,
+                            path: projectAlias,
                             request_focus: 'Capability truth status probe',
                             max_files: 20,
                             max_chars: 800,
                         },
                         context: {
-                            project_path: projectPath,
+                            project_path: projectAlias,
                             source: 'vigthoria-cli-capability-truth',
                         },
                     }),
                 });
                 if (probeResponse.ok) {
                     const probeData = await probeResponse.json();
-                    compactContextLength = String(probeData?.result?.compact_context || '').length;
+                    compactContextLength = String(probeData?.result?.compact_context
+                        || probeData?.result?.result?.compact_context
+                        || '').length;
                 }
             }
             catch {
@@ -6621,19 +4082,38 @@ document.addEventListener('DOMContentLoaded', () => {
             message: 'V3 service is reachable again — retrying the workflow once.',
         };
     }
-    async getDevtoolsBridgeStatus() {
+    async probeDevtoolsBridgeStatus() {
         const host = process.env.VIGTHORIA_DEVTOOLS_BRIDGE_HOST || '127.0.0.1';
         const port = Number.parseInt(process.env.VIGTHORIA_DEVTOOLS_BRIDGE_PORT || '4016', 10);
         const endpoint = `ws://${host}:${port}/ws`;
         const healthEndpoint = `http://${host}:${port}/health`;
+        // The HTTP policy protects fetch, but the legacy compatibility probe below
+        // opens a raw TCP socket. Validate once before either transport so offline
+        // mode and explicit-loopback consent cannot be bypassed by the fallback.
+        try {
+            assertTrustedEndpoint(healthEndpoint, { audience: 'bridge' });
+        }
+        catch (error) {
+            return {
+                name: 'DevTools Bridge',
+                endpoint,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
         try {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), 1500);
-            const response = await fetch(healthEndpoint, {
-                signal: controller.signal,
-                headers: { Accept: 'application/json' },
-            });
-            clearTimeout(timer);
+            let response;
+            try {
+                response = await this.fetch(healthEndpoint, {
+                    signal: controller.signal,
+                    headers: { Accept: 'application/json' },
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
             if (response.ok) {
                 return {
                     name: 'DevTools Bridge',
@@ -6681,40 +4161,14 @@ document.addEventListener('DOMContentLoaded', () => {
             });
         });
     }
+    async getDevtoolsBridgeStatus() {
+        return this.probeDevtoolsBridgeStatus();
+    }
     async getCapabilityTruthStatus(context = {}) {
-        // Wrap each probe with its own 6 s timeout so they always resolve
-        // before the outer 8 s race in auth.ts, producing real error messages
-        // (ECONNREFUSED, 404, etc.) instead of the generic "Timed out (8s)".
-        const withTimeout = (p, name) => Promise.race([
-            p,
-            new Promise(resolve => setTimeout(() => resolve({ name, endpoint: '', ok: false, error: 'Service not reachable (6 s timeout)' }), 6000)),
-        ]);
-        const [v3Agent, hyperLoop, repoMemory, devtoolsBridge] = await Promise.all([
-            withTimeout(this.getV3AgentHealth(), 'V3 Agent'),
-            withTimeout(this.getHyperLoopHealth(), 'Hyper Loop'),
-            withTimeout(this.getRepoMemoryHealth(context), 'Repo Memory'),
-            withTimeout(this.getDevtoolsBridgeStatus(), 'DevTools Bridge'),
-        ]);
-        return {
-            overallOk: v3Agent.ok && (hyperLoop.ok || repoMemory.ok),
-            v3Agent,
-            hyperLoop,
-            repoMemory,
-            devtoolsBridge,
-        };
+        return this.capabilityHealthService.getCapabilityTruth(context);
     }
     async getHealthStatus() {
-        const [coder, models, selfHosted] = await Promise.all([
-            this.getCoderHealth(),
-            this.getModelsHealth(),
-            this.getSelfHostedHealth(),
-        ]);
-        return {
-            overallOk: coder.ok && models.ok,
-            coder,
-            models,
-            selfHosted,
-        };
+        return this.capabilityHealthService.getHealth();
     }
     // Health check
     async healthCheck() {