vigthoria-cli 1.10.0 → 1.10.36

package/dist/commands/chat.js

@@ -4,13 +4,14 @@ import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError, sanitizeUserFacingErrorText, sanitizeUserFacingPathText, propagateError } from '../utils/api.js';
+import { APIClient, CLIError, classifyError, formatCLIError, sanitizeUserFacingErrorText, sanitizeUserFacingPathText, propagateError, VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE } from '../utils/api.js';
 import { AgenticTools, robustifyStreamResponse } from '../utils/tools.js';
 import { SessionManager } from '../utils/session.js';
 import { BridgeClient, getBridgeClient } from '../utils/bridge-client.js';
-import { WorkspaceWatcher } from '../utils/workspace-stream.js';
+import { WorkspaceWatcher, WorkspaceWSClient } from '../utils/workspace-stream.js';
 import { TaskDisplay } from '../utils/task-display.js';
 import { ProjectMemoryService } from '../utils/project-memory.js';
+import { buildPersonaOverlay, normalizePersonaMode } from '../utils/persona.js';
 const DEFAULT_V3_AGENT_TIMEOUT_MS = (() => {
     const rawValue = process.env.VIGTHORIA_AGENT_TIMEOUT_MS || process.env.V3_AGENT_TIMEOUT_MS;
     if (!rawValue) {
@@ -22,18 +23,18 @@ const DEFAULT_V3_AGENT_TIMEOUT_MS = (() => {
 const DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS = (() => {
     const rawValue = process.env.VIGTHORIA_AGENT_IDLE_TIMEOUT_MS || process.env.V3_AGENT_IDLE_TIMEOUT_MS;
     if (!rawValue) {
-        return 0;
+        return 90000;
     }
     const parsed = Number.parseInt(rawValue, 10);
-    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 90000;
 })();
 const DEFAULT_V3_AGENT_SOFT_TIMEOUT_MS = (() => {
     const rawValue = process.env.VIGTHORIA_AGENT_SOFT_TIMEOUT_MS || process.env.V3_AGENT_SOFT_TIMEOUT_MS;
     if (!rawValue) {
-        return 0;
+        return 180000;
     }
     const parsed = Number.parseInt(rawValue, 10);
-    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 180000;
 })();
 export class ChatCommand {
     config;
@@ -52,6 +53,7 @@ export class ChatCommand {
     currentModel = 'code';
     modelExplicitlySelected = false;
     autoApprove = false;
+    personaOverride = null;
     // Phase 5: Agent quality gate — track tool usage for evidence thresholds
     agentToolEvidence = { discovery: 0, mutation: 0, searchFailed: 0 };
     operatorMode = false;
@@ -112,17 +114,22 @@ export class ChatCommand {
     toUserFacingApiError(error, context) {
         const classified = classifyError(error);
         const status = classified.statusCode || (this.isJwtExpirationError(error) ? 401 : 500);
-        if (this.isJwtExpirationError(error)) {
+        if (this.isJwtExpirationError(error) || classified.category === 'auth') {
             return new CLIError('Your Vigthoria session has expired. Run `vigthoria login` to authenticate again.', 'auth', { statusCode: 401 });
         }
-        if (this.isTimeoutError(error)) {
+        // Preserve structured API classification first (auth/model/network/etc.)
+        // so upstream responses are not relabeled by message heuristics.
+        if (classified.category === 'timeout') {
             return new CLIError(`${context} timed out. Check your connection and try again.`, 'timeout', { statusCode: status });
         }
-        if (this.isNetworkError(error)) {
+        if (classified.category === 'network') {
             return new CLIError(`${context} could not reach the Vigthoria API. Check your network connection and try again.`, 'network', { statusCode: status });
         }
+        if (classified.category === 'model_backend') {
+            return new CLIError(VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE, 'model_backend', { statusCode: status, endpoint: classified.endpoint });
+        }
         const message = sanitizeUserFacingErrorText(classified.message || `${context} failed`);
-        return new CLIError(message, status === 401 ? 'auth' : 'model_backend', { statusCode: status });
+        return new CLIError(message, 'model_backend', { statusCode: status, endpoint: classified.endpoint });
     }
     handleApiError(error, context) {
         const userFacingError = this.toUserFacingApiError(error, context);
@@ -151,10 +158,6 @@ export class ChatCommand {
                 return await operation();
             }
             catch (error) {
-                if (!this.jsonOutput) {
-                    const transient = this.isTimeoutError(error) ? 'timeout' : this.isNetworkError(error) ? 'network error' : 'API error';
-                    console.error(chalk.red(`${context} failed with ${transient}: ${this.toUserFacingApiError(error, context).message}`));
-                }
                 lastError = error;
                 if (this.isJwtExpirationError(error)) {
                     this.handleApiError(error, context);
@@ -163,7 +166,8 @@ export class ChatCommand {
                     this.handleApiError(error, context);
                 }
                 if (!this.jsonOutput) {
-                    this.logger.warn(`${context} failed due to ${this.isTimeoutError(error) ? 'timeout' : 'network error'}; retrying (${attempt + 1}/${retries})...`);
+                    const transient = this.isTimeoutError(error) ? 'timeout' : this.isNetworkError(error) ? 'network error' : 'temporary service issue';
+                    this.logger.warn(`${context} failed due to ${transient}; retrying (${attempt + 1}/${retries})...`);
                 }
                 await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
             }
@@ -262,7 +266,7 @@ export class ChatCommand {
                 explicitModel: true,
                 heavyTask,
                 cloudEligible,
-                cloudSelected: this.currentModel === 'cloud' || this.currentModel === 'cloud-reason' || this.currentModel === 'ultra',
+                cloudSelected: ['cloud', 'cloud-reason', 'ultra', 'cloud-fast', 'cloud-balanced', 'cloud-code', 'cloud-power', 'cloud-maximum'].includes(this.currentModel),
                 routeReason: 'explicit-model-selection',
             };
         }
@@ -295,8 +299,19 @@ export class ChatCommand {
             routeReason: 'default-v3-agent',
         };
     }
-    getMessagesForModel() {
+    getMessagesForModel(options) {
         const messages = [...this.messages];
+        const personaOverlay = this.buildActivePersonaOverlay();
+        if (personaOverlay && !messages.some((message) => message.role === 'system' && message.content.includes('Optional persona overlay: Wiener Grantler mode.'))) {
+            const insertionIndex = messages.findIndex((message) => message.role !== 'system');
+            const personaMessage = { role: 'system', content: personaOverlay };
+            if (insertionIndex === -1) {
+                messages.push(personaMessage);
+            }
+            else {
+                messages.splice(insertionIndex, 0, personaMessage);
+            }
+        }
         const memoryContexts = [
             this.sessionManager.buildMemoryContext(this.currentSession),
             this.projectMemory?.buildContextForPrompt(this.getLastUserPrompt()) || '',
@@ -318,8 +333,137 @@ export class ChatCommand {
                 messages.splice(insertionIndex, 0, memoryMessage);
             }
         }
+        if (options?.compact) {
+            const compactLimit = 6000;
+            const systemMessages = messages.filter((message) => message.role === 'system').map((message) => ({
+                ...message,
+                content: message.content.length > compactLimit
+                    ? `${message.content.slice(0, compactLimit)}\n...[trimmed for first local agent turn]`
+                    : message.content,
+            }));
+            const lastUser = [...messages].reverse().find((message) => message.role === 'user');
+            return lastUser ? [...systemMessages.slice(0, 2), lastUser] : systemMessages.slice(0, 2);
+        }
         return messages;
     }
+    normalizeClientV3ToolPath(rawPath) {
+        let normalized = String(rawPath || '.').trim().replace(/\\/g, '/');
+        if (!normalized || normalized === '/') {
+            return '.';
+        }
+        normalized = normalized.replace(/^vigthoria:\/\/workspace\/?/i, '');
+        normalized = normalized.replace(/^\.\/+/, '');
+        normalized = normalized.replace(/^workspace\/?/i, '');
+        const workspaceRoot = this.currentProjectPath || process.cwd();
+        const workspaceName = path.basename(workspaceRoot);
+        if (workspaceName) {
+            const workspaceKey = workspaceName.toLowerCase().replace(/[\s_./\\-]+/g, '');
+            const parts = normalized.split('/').filter(Boolean);
+            if (parts.length > 0) {
+                const firstKey = parts[0].toLowerCase().replace(/[\s_./\\-]+/g, '');
+                if (firstKey === workspaceKey) {
+                    normalized = parts.slice(1).join('/') || '.';
+                }
+            }
+        }
+        normalized = normalized.replace(/^\/+/, '').replace(/\/+$/, '');
+        return normalized || '.';
+    }
+    resolveClientV3ToolPath(rawPath) {
+        const root = this.currentProjectPath || process.cwd();
+        const normalized = this.normalizeClientV3ToolPath(rawPath);
+        const absoluteTarget = path.resolve(root, normalized === '.' ? '' : normalized);
+        if (fs.existsSync(absoluteTarget)) {
+            return normalized;
+        }
+        const parts = normalized.split('/').filter(Boolean);
+        if (parts.length === 0) {
+            return '.';
+        }
+        try {
+            const entries = fs.readdirSync(root, { withFileTypes: true });
+            const firstKey = parts[0].toLowerCase().replace(/[\s_./\\-]+/g, '');
+            for (const entry of entries) {
+                const entryKey = entry.name.toLowerCase().replace(/[\s_./\\-]+/g, '');
+                if (entryKey === firstKey || entryKey.includes(firstKey) || firstKey.includes(entryKey)) {
+                    const rest = parts.slice(1).join('/');
+                    const candidate = rest ? `${entry.name}/${rest}` : entry.name;
+                    if (fs.existsSync(path.resolve(root, candidate))) {
+                        return candidate.replace(/\\/g, '/');
+                    }
+                    if (!rest) {
+                        return entry.name.replace(/\\/g, '/');
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore unreadable workspace roots during path repair.
+        }
+        return normalized;
+    }
+    normalizeClientV3ToolArgs(args) {
+        const normalizedArgs = { ...args };
+        for (const key of ['path', 'file_path', 'file', 'target']) {
+            if (typeof normalizedArgs[key] === 'string' && normalizedArgs[key].trim()) {
+                normalizedArgs[key] = this.resolveClientV3ToolPath(normalizedArgs[key]);
+            }
+        }
+        return normalizedArgs;
+    }
+    async executeClientV3Tool(event) {
+        if (!this.tools) {
+            return { success: false, output: '', error: 'Local agent tools are not initialized.' };
+        }
+        const name = String(event.name || '').trim();
+        const args = (event.arguments && typeof event.arguments === 'object')
+            ? event.arguments
+            : {};
+        let toolName = name;
+        let toolArgs = {};
+        for (const [key, value] of Object.entries(args)) {
+            toolArgs[key] = value == null ? '' : String(value);
+        }
+        toolArgs = this.normalizeClientV3ToolArgs(toolArgs);
+        if (name === 'list_directory') {
+            toolName = 'list_dir';
+            toolArgs = {
+                path: toolArgs.path || '.',
+                ...(toolArgs.recursive === 'true' || toolArgs.recursive === '1' ? { recursive: 'true' } : {}),
+            };
+        }
+        else if (name === 'search_files') {
+            toolName = 'grep';
+            toolArgs = {
+                path: toolArgs.path || '.',
+                pattern: toolArgs.pattern || toolArgs.query || '',
+                ...(toolArgs.file_pattern ? { includePattern: toolArgs.file_pattern } : {}),
+            };
+        }
+        else if (name === 'read_file') {
+            toolName = 'read_file';
+        }
+        else if (name === 'write_file' || name === 'edit_file') {
+            toolName = name;
+        }
+        if (!toolName) {
+            return { success: false, output: '', error: 'Missing V3 client tool name.' };
+        }
+        const result = await this.tools.execute({ tool: toolName, args: toolArgs });
+        return {
+            success: result.success === true,
+            output: String(result.output || result.message || ''),
+            error: result.error ? String(result.error) : '',
+        };
+    }
+    getActivePersonaMode() {
+        if (this.personaOverride)
+            return this.personaOverride;
+        return normalizePersonaMode(this.config.get('persona')) || 'default';
+    }
+    buildActivePersonaOverlay() {
+        return buildPersonaOverlay(this.getActivePersonaMode(), this.getLastUserPrompt());
+    }
     isDiagnosticPrompt(prompt) {
         return /(startup|start up|won'?t start|doesn'?t start|crash|crashes|error|errors|failing|fails|issue|issues|bug|bugs|diagnos|debug|runtime|log|logs|exception|traceback|stack trace|yaml|blocking|blocker)/i.test(prompt);
     }
@@ -328,10 +472,270 @@ export class ChatCommand {
      * question — these should use analysis_only workflow, not full_autonomy.
      */
     isAnalysisLookupPrompt(prompt) {
+        if (this.isImplementationPrompt(prompt)) {
+            return false;
+        }
         return /^(what|which|where|how many|who|find|list|show|check|inspect|analyze|analyse|audit|explain|describe|summarize|summarise|review|overview|count|read|look at|tell me|locate|search for|does .* exist)/i.test(prompt.trim());
     }
+    isImplementationPrompt(prompt) {
+        const trimmed = String(prompt || '').trim();
+        if (!trimmed)
+            return false;
+        if (/\b(implement|add|fix|repair|complete|finish|build|create|write|patch|update|modify|edit|make\s+(?:it\s+)?work(?:ing)?|get\s+(?:a\s+)?working)\b/i.test(trimmed)) {
+            return true;
+        }
+        if (/\bwhat(?:'s|\s+is|\s+are)\s+missing\b/i.test(trimmed)) {
+            return true;
+        }
+        if (/\b(game|html5|pacman|rogue|app|site)\b/i.test(trimmed) && /\b(missing|broken|fix|implement|working|playable)\b/i.test(trimmed)) {
+            return true;
+        }
+        if (/continue the previous agent run/i.test(trimmed) && /\b(implement|fix|missing|blocker|remaining)\b/i.test(trimmed)) {
+            return true;
+        }
+        return false;
+    }
+    getWindowsPromptPathRoots() {
+        const roots = new Set();
+        const add = (value) => {
+            const raw = String(value || '').trim();
+            if (!raw)
+                return;
+            try {
+                const resolved = path.resolve(raw);
+                if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+                    roots.add(resolved);
+                }
+            }
+            catch {
+                // Ignore unreadable discovery roots.
+            }
+        };
+        const home = os.homedir();
+        const cwdRoot = path.parse(process.cwd()).root || path.parse(home).root || '';
+        add(process.cwd());
+        add(home);
+        add(path.join(home, 'Desktop'));
+        add(path.join(home, 'Documents'));
+        add(process.env.USERPROFILE);
+        add(process.env.OneDrive);
+        add(process.env.OneDriveCommercial);
+        add(process.env.OneDriveConsumer);
+        if (process.env.OneDrive) {
+            add(path.join(process.env.OneDrive, 'Desktop'));
+            add(path.join(process.env.OneDrive, 'Documents'));
+        }
+        if (cwdRoot) {
+            add(cwdRoot);
+            add(path.join(cwdRoot, 'vigthoria'));
+            add(path.join(cwdRoot, 'Vigthoria'));
+        }
+        return Array.from(roots);
+    }
+    findPromptDirectoryByName(rawPath) {
+        if (os.platform() !== 'win32')
+            return null;
+        const normalized = String(rawPath || '').trim().replace(/^\/+/, '').replace(/[\\/]+/g, path.sep);
+        if (!normalized)
+            return null;
+        const wantedParts = normalized.split(/[\\/]+/).filter(Boolean);
+        const wantedName = wantedParts[wantedParts.length - 1];
+        if (!wantedName)
+            return null;
+        const maxDepth = 3;
+        const maxEntries = 2500;
+        const roots = this.getWindowsPromptPathRoots();
+        for (const root of roots) {
+            let visited = 0;
+            const direct = path.join(root, normalized);
+            try {
+                if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+                    return direct;
+                }
+            }
+            catch {
+                // Continue with bounded search.
+            }
+            const stack = [{ dir: root, depth: 0 }];
+            while (stack.length > 0 && visited < maxEntries) {
+                const current = stack.pop();
+                if (!current || current.depth > maxDepth)
+                    continue;
+                let entries;
+                try {
+                    entries = fs.readdirSync(current.dir, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                visited += entries.length;
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    if (entry.name === 'node_modules' || entry.name === '.git' || entry.name.startsWith('$'))
+                        continue;
+                    const fullPath = path.join(current.dir, entry.name);
+                    if (entry.name.toLowerCase() === wantedName.toLowerCase()) {
+                        if (wantedParts.length === 1 || fullPath.toLowerCase().endsWith(normalized.toLowerCase())) {
+                            return fullPath;
+                        }
+                    }
+                    if (current.depth < maxDepth) {
+                        stack.push({ dir: fullPath, depth: current.depth + 1 });
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    extractExplicitLocalPath(prompt) {
+        const resolveExistingPath = (rawPath) => {
+            const trimmed = String(rawPath || '').trim().replace(/^['"]|['"]$/g, '');
+            if (!trimmed)
+                return null;
+            const candidates = [];
+            candidates.push(path.resolve(trimmed));
+            if (os.platform() === 'win32' && /^\/[A-Za-z0-9._ -]/.test(trimmed)) {
+                const withoutLeadingSlash = trimmed.replace(/^\/+/, '');
+                const cwdRoot = path.parse(process.cwd()).root || '';
+                // Allow prompts like "/Vigthoria Games" to resolve as "C:/Vigthoria/Games".
+                const asSegments = withoutLeadingSlash.replace(/\s+/g, path.sep);
+                for (const root of this.getWindowsPromptPathRoots()) {
+                    candidates.push(path.resolve(root, withoutLeadingSlash));
+                    candidates.push(path.resolve(root, asSegments));
+                    const segmentParts = asSegments.split(/[\\/]+/).filter(Boolean);
+                    if (segmentParts.length > 1 && path.basename(root).toLowerCase() === segmentParts[0].toLowerCase()) {
+                        candidates.push(path.resolve(root, ...segmentParts.slice(1)));
+                    }
+                }
+                if (cwdRoot && !candidates.includes(path.resolve(cwdRoot, withoutLeadingSlash))) {
+                    candidates.push(path.resolve(cwdRoot, withoutLeadingSlash));
+                    candidates.push(path.resolve(cwdRoot, asSegments));
+                }
+            }
+            for (const candidate of candidates) {
+                try {
+                    if (fs.existsSync(candidate)) {
+                        return candidate;
+                    }
+                }
+                catch {
+                    // Continue trying other normalized candidates.
+                }
+            }
+            const discovered = this.findPromptDirectoryByName(trimmed);
+            if (discovered)
+                return discovered;
+            return null;
+        };
+        // Quoted paths first (supports spaces safely).
+        const quotedPatterns = [
+            /"([A-Za-z]:[\\/][^"\r\n]+)"/,
+            /'([A-Za-z]:[\\/][^'\r\n]+)'/,
+            /"(\/[^"]+)"/,
+            /'(\/[^']+)'/,
+        ];
+        for (const pattern of quotedPatterns) {
+            const match = prompt.match(pattern);
+            if (match?.[1]) {
+                const resolved = resolveExistingPath(match[1]);
+                if (resolved)
+                    return resolved;
+            }
+        }
+        // Unquoted Windows path with optional spaces, stopping before instruction connectors.
+        const windowsMatch = prompt.match(/(?:^|\s)([A-Za-z]:[\\/][^<>"|?*\r\n]+?)(?=(?:\s+(?:and|then|to|for|with|where|that|which|who|make|create|build|analyse|analyze)\b|\s{2,}|[.,;!?)]|$))/i);
+        if (windowsMatch?.[1]) {
+            const resolved = resolveExistingPath(windowsMatch[1]);
+            if (resolved)
+                return resolved;
+        }
+        // Unix-style absolute path with optional spaces (but not URLs).
+        if (!/(https?|ftp):\/\//i.test(prompt)) {
+            const unixMatch = prompt.match(/(?:^|\s)(\/[a-zA-Z0-9._\-/ ]+?)(?=(?:\s+(?:and|then|to|for|with|where|that|which|who|make|create|build|analyse|analyze)\b|\s{2,}|[.,;!?)]|$))/i);
+            if (unixMatch?.[1]) {
+                const candidatePath = unixMatch[1]
+                    .replace(/\s+(and|or|at|in|the|to|for|with|from|by|on)$/i, '')
+                    .replace(/[.,;!?:)\]]*$/, '')
+                    .trim();
+                if (candidatePath.length > 1) {
+                    const resolved = resolveExistingPath(candidatePath);
+                    if (resolved)
+                        return resolved;
+                }
+            }
+        }
+        return null;
+    }
+    isUnscopedPromptPathOverrideAllowed() {
+        return /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_ALLOW_UNSCOPED_PROMPT_PATHS || ''));
+    }
+    isPathWithinRoot(candidatePath, rootPath) {
+        const candidate = path.resolve(candidatePath);
+        const root = path.resolve(rootPath);
+        const rel = path.relative(root, candidate);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    }
+    getPromptPathAllowedRoots(baseWorkspace) {
+        const roots = new Set();
+        const addRoot = (rawValue) => {
+            const value = String(rawValue || '').trim();
+            if (!value)
+                return;
+            const resolved = path.resolve(value);
+            try {
+                if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+                    roots.add(resolved);
+                }
+            }
+            catch {
+                // ignore invalid or unreadable roots
+            }
+        };
+        addRoot(baseWorkspace);
+        addRoot(this.currentProjectPath);
+        addRoot(process.cwd());
+        addRoot(this.config.get('project')?.rootPath || null);
+        const envRootsRaw = String(process.env.VIGTHORIA_ALLOWED_WORKSPACE_ROOTS || '').trim();
+        if (envRootsRaw) {
+            for (const entry of envRootsRaw.split(path.delimiter)) {
+                addRoot(entry);
+            }
+        }
+        return Array.from(roots);
+    }
+    resolvePromptWorkspacePath(prompt, baseWorkspace) {
+        const explicitPath = this.extractExplicitLocalPath(prompt);
+        if (!explicitPath) {
+            return null;
+        }
+        const candidate = path.resolve(explicitPath);
+        if (this.isUnscopedPromptPathOverrideAllowed()) {
+            return candidate;
+        }
+        const runtime = this.getRuntimeEnvironmentContext();
+        // On local-machine CLI sessions, allow explicit absolute paths from user prompts.
+        // The path still must exist on disk (validated by extractExplicitLocalPath).
+        if (runtime.machineScope === 'local-machine') {
+            return candidate;
+        }
+        const allowedRoots = this.getPromptPathAllowedRoots(baseWorkspace);
+        const isAllowed = allowedRoots.some((root) => this.isPathWithinRoot(candidate, root));
+        if (isAllowed) {
+            return candidate;
+        }
+        if (!this.jsonOutput) {
+            console.log(chalk.yellow(`Ignoring path outside allowed workspace roots: ${candidate}`));
+            if (allowedRoots.length > 0) {
+                const displayRoots = allowedRoots.map((root) => root.replace(/\\/g, '/')).join(', ');
+                console.log(chalk.gray(`Allowed roots: ${displayRoots}`));
+            }
+            console.log(chalk.gray('To allow unrestricted prompt path overrides, set VIGTHORIA_ALLOW_UNSCOPED_PROMPT_PATHS=1.'));
+        }
+        return null;
+    }
     isBrowserTaskPrompt(prompt) {
-        return /(browser|chrome|devtools|console|dom|network tab|network request|frontend runtime|client-side|client side|rendering|page load|websocket|ui bug|inspect element)/i.test(prompt);
+        return /(\bbrowser\b|\bchrome\b|\bdevtools\b|\bconsole\b|\bdom\b|network tab|network request|frontend runtime|client-side|client side|rendering|page load|\bwebsocket\b|ui bug|inspect element)/i.test(prompt);
     }
     /**
      * Returns true when a prompt can be answered directly without the full
@@ -377,13 +781,36 @@ export class ChatCommand {
     inferAgentTaskType(prompt) {
         if (this.isDiagnosticPrompt(prompt))
             return 'debugging';
+        if (this.isImplementationPrompt(prompt)) {
+            return /\b(game|html5|pacman|rogue|playable)\b/i.test(prompt) ? 'game-build' : 'implementation';
+        }
         if (/^(what|which|how many|list|show|check|inspect|analyze|analyse|audit|explain|describe|summarize|summarise|review|overview|find|count|read|look at|tell me)/i.test(prompt.trim()))
             return 'analysis';
         return 'implementation';
     }
+    bindPromptWorkspace(prompt) {
+        const resolved = this.resolvePromptWorkspacePath(prompt, this.currentProjectPath);
+        if (!resolved) {
+            return;
+        }
+        const normalizedResolved = path.resolve(resolved);
+        const normalizedCurrent = path.resolve(this.currentProjectPath);
+        if (normalizedResolved === normalizedCurrent) {
+            return;
+        }
+        if (!this.jsonOutput) {
+            console.log(chalk.cyan(`📁 Workspace from prompt: ${normalizedResolved}`));
+        }
+        this.currentProjectPath = normalizedResolved;
+        this.tools?.setWorkspaceRoot(normalizedResolved);
+        this.projectMemory = new ProjectMemoryService(normalizedResolved);
+    }
     buildTaskShapingInstructions(prompt) {
         const instructions = [];
         const runtime = this.getRuntimeEnvironmentContext();
+        if (runtime.machineScope === 'local-machine') {
+            instructions.push(`Execution environment: local user machine (${runtime.platform}).`, `Project workspace root on this machine: ${runtime.workspacePath}.`, 'All list_dir, read_file, grep, glob, and bash tools operate on this local filesystem — not a remote server copy.', 'Use paths relative to that root only. Never prefix paths with workspace/ or repeat the workspace folder name.', 'Start with list_dir on "." to discover the real folder structure before reading files.', 'If read_file fails, use list_dir or glob to locate the correct relative path, then retry read_file.');
+        }
         // Platform-aware routing hints
         if (runtime.platform === 'windows') {
             instructions.push('Platform: Windows. Use list_dir, glob, read_file, and the grep tool for searching.', 'The grep tool handles Windows automatically — do not use bash to call grep, findstr, or Select-String manually.', 'Do not use bash for Unix commands (cat, head, tail, awk, sed, wc).', 'Use read_file to inspect file contents instead of shell commands.', 'All file paths use forward slashes internally.');
@@ -495,6 +922,9 @@ export class ChatCommand {
     v3ToolCallCount = 0;
     v3LastActivity = Date.now();
     v3StreamingStarted = false;
+    v3StreamedTextBuffer = '';
+    v3LiveToolEvidence = [];
+    v3PendingToolCalls = [];
     /**
      * Strip server-internal path prefixes from tool output strings.
      * Prevents exposing paths like /var/www/V3-Code-Agent/... to end users.
@@ -502,7 +932,16 @@ export class ChatCommand {
     sanitizeServerPath(text) {
         if (!text)
             return text;
-        return sanitizeUserFacingPathText(text);
+        return sanitizeUserFacingPathText(this.stripHiddenThoughtBlocks(text));
+    }
+    stripHiddenThoughtBlocks(text) {
+        if (!text)
+            return text;
+        return text
+            .replace(/<\|mask_start\|>[\s\S]*?<\|mask_end\|>/g, '')
+            .replace(/<think>[\s\S]*?<\/think>/gi, '')
+            .replace(/<\|(?:mask_start|mask_end)\|>/g, '')
+            .trim();
     }
     describeV3AgentTool(toolName) {
         const normalized = String(toolName || '').toLowerCase();
@@ -560,6 +999,7 @@ export class ChatCommand {
         if (!safeText) {
             return;
         }
+        this.v3StreamedTextBuffer += safeText;
         if (!this.v3StreamingStarted) {
             this.v3StreamingStarted = true;
             spinner.stop();
@@ -572,6 +1012,117 @@ export class ChatCommand {
         }
         process.stdout.write(safeText);
     }
+    isGenericV3AgentContent(text) {
+        const value = String(text || '').trim();
+        return !value || /^(v3 agent workflow completed\.?|task completed|agent run finished|workflow completed\.?)$/i.test(value);
+    }
+    hasAlreadyStreamedV3Content(text) {
+        const value = String(text || '').trim();
+        if (!value)
+            return true;
+        return this.v3StreamedTextBuffer.includes(value) || value.includes(this.v3StreamedTextBuffer.trim());
+    }
+    isThinV3Summary(text) {
+        const value = String(text || '').trim();
+        if (!value)
+            return true;
+        if (/^#\s*Workspace overview/m.test(value) || /^## Workspace analysis \(from local file inspection\)/m.test(value)) {
+            return false;
+        }
+        if (this.isGenericV3AgentContent(value))
+            return true;
+        if (/^The V3 agent finished without emitting a dedicated final answer/i.test(value)) {
+            return !/(## Files read|## Directories inspected|### )/i.test(value);
+        }
+        return value.length < 120;
+    }
+    shouldPrintV3FinalContent(text) {
+        if (!text || this.isGenericV3AgentContent(text)) {
+            return false;
+        }
+        const value = text.trim();
+        if (/^## Workspace analysis \(from local file inspection\)/m.test(value)) {
+            return true;
+        }
+        if (/Reconstructed task summary|Workspace analysis \(from local file inspection\)/i.test(value)) {
+            return true;
+        }
+        if (!this.v3StreamingStarted) {
+            return true;
+        }
+        return !this.hasAlreadyStreamedV3Content(value);
+    }
+    rememberV3ToolEvidence(event, args = {}) {
+        const output = typeof event?.output === 'string' ? event.output.trim() : '';
+        const errorText = typeof event?.error === 'string' ? event.error.trim() : '';
+        const combined = output || errorText;
+        if (!combined) {
+            return;
+        }
+        const target = String(args.path || args.file_path || args.file || args.target || event?.target || '').trim();
+        this.v3LiveToolEvidence.push({
+            name: String(event?.name || event?.tool || 'unknown_tool'),
+            target: target || undefined,
+            arguments: args,
+            output: combined,
+            success: event?.success !== false,
+        });
+    }
+    buildUserFacingV3RunReport(prompt, workspacePath, options = {}) {
+        const evidenceBody = this.api.formatV3AgentResponse({
+            events: [],
+            liveToolEvidence: this.v3LiveToolEvidence,
+        });
+        const successes = this.v3LiveToolEvidence.filter((entry) => entry.success !== false);
+        const failures = this.v3LiveToolEvidence.filter((entry) => entry.success === false);
+        if (!evidenceBody && successes.length === 0 && failures.length === 0) {
+            return [
+                '# Agent run summary',
+                '',
+                `**Workspace:** ${workspacePath}`,
+                `**Your request:** ${prompt.trim()}`,
+                '',
+                'The agent finished without successfully reading local files, so no grounded overview could be built.',
+                options.serverNote ? `\n**Server note:** ${options.serverNote}` : '',
+                '',
+                'Try `/continue` with: "Read Vigthoria-dominion/package.json, game.js, src/Game.js, and src/factions/, then write a full overview."',
+            ].filter(Boolean).join('\n');
+        }
+        const lines = [
+            '# Workspace overview',
+            '',
+            `**Workspace:** ${workspacePath}`,
+            `**Your request:** ${prompt.trim()}`,
+            options.partial
+                ? '**Status:** Partial — the agent used its iteration budget before writing a final narrative. The report below is rebuilt from files it actually read on your machine.'
+                : '**Status:** Complete — summary rebuilt from local file inspection.',
+            '',
+            evidenceBody || '_No readable file excerpts were captured._',
+        ];
+        if (failures.length > 0) {
+            const uniqueFails = new Map();
+            for (const entry of failures) {
+                const failPath = entry.target || entry.arguments?.path || entry.name;
+                if (!uniqueFails.has(failPath)) {
+                    uniqueFails.set(failPath, entry.output.split('\n').find(Boolean)?.slice(0, 140) || entry.output.slice(0, 140));
+                }
+            }
+            if (uniqueFails.size > 0 && !/## Paths not found/i.test(evidenceBody || '')) {
+                lines.push('', '## Paths not found (exploration misses)', ...[...uniqueFails.entries()].slice(0, 12).map(([failPath, detail]) => `- \`${failPath}\`${detail ? ` — ${detail}` : ''}`), '', '_These are usually incorrect guesses (for example `Vigthoria-dominion/entities` instead of `Vigthoria-dominion/src/entities`). They do not mean your project is broken._');
+            }
+        }
+        lines.push('', '---', 'Use `/continue` if you want a longer narrative summary or a deep dive into a specific subfolder.');
+        return lines.join('\n');
+    }
+    printV3UserReport(report) {
+        const value = String(report || '').trim();
+        if (!value || this.isGenericV3AgentContent(value)) {
+            return;
+        }
+        console.log();
+        console.log(value);
+        console.log();
+    }
     updateV3AgentSpinner(spinner, event) {
         if (this.isRawV3StreamPayload(event)) {
             this.consumeV3StreamPayload(spinner, event).catch((error) => {
@@ -589,7 +1140,7 @@ export class ChatCommand {
         if (event.type === 'tool_call') {
             this.v3ToolCallCount += 1;
             const toolDesc = this.describeV3AgentTool(event.tool || event.name || event.tool_name);
-            const toolTarget = event.arguments?.path || event.arguments?.file_path || event.arguments?.pattern || '';
+            const toolTarget = event.arguments?.path || event.arguments?.file_path || event.arguments?.pattern || event.arguments?.query || '';
             const sanitizedTarget = this.sanitizeServerPath(String(toolTarget));
             const shortTarget = sanitizedTarget ? ` → ${sanitizedTarget.replace(/\\/g, '/').split('/').slice(-2).join('/')}` : '';
             const stepLabel = chalk.cyan(`  [${this.v3IterationCount}/${this.v3ToolCallCount}]`) + ` ${toolDesc}${shortTarget}`;
@@ -599,6 +1150,21 @@ export class ChatCommand {
             // Show extra detail for key tools
             const args = event.arguments || {};
             const toolName = event.name || event.tool || '';
+            this.v3PendingToolCalls.push({
+                name: String(toolName || 'unknown_tool'),
+                args: args && typeof args === 'object' ? args : {},
+            });
+            if (toolName === 'search_files') {
+                const pattern = String(args.pattern || args.query || '').trim();
+                const searchPath = String(args.path || '.').trim();
+                process.stderr.write(chalk.gray(`      search: ${pattern || '(empty)'} in ${this.sanitizeServerPath(searchPath)}\n`));
+            }
+            else if (toolName === 'list_directory') {
+                process.stderr.write(chalk.gray(`      list: ${this.sanitizeServerPath(String(args.path || '.'))}${args.recursive ? ' (recursive)' : ''}\n`));
+            }
+            else if (toolName === 'read_file') {
+                process.stderr.write(chalk.gray(`      read: ${this.sanitizeServerPath(String(args.path || args.file_path || ''))}\n`));
+            }
             if ((toolName === 'write_file' || toolName === 'edit_file') && typeof args.content === 'string') {
                 const len = args.content.length;
                 process.stderr.write(chalk.gray(`      ${len > 1000 ? Math.round(len / 1024) + ' KB' : len + ' bytes'} content\n`));
@@ -621,25 +1187,51 @@ export class ChatCommand {
             // Show output for failures, or brief summary for successes — sanitize server paths
             const rawOutput = typeof event.output === 'string' ? event.output.trim() : '';
             const output = this.sanitizeServerPath(rawOutput);
+            const pendingIndex = this.v3PendingToolCalls.findIndex((call) => call.name === toolName);
+            const pendingCall = pendingIndex >= 0
+                ? this.v3PendingToolCalls.splice(pendingIndex, 1)[0]
+                : this.v3PendingToolCalls.shift();
+            this.rememberV3ToolEvidence(event, pendingCall?.args || {});
             if (!success && output) {
                 const sanitizedError = this.sanitizeServerPath(typeof event.error === 'string' ? event.error : output);
                 const lines = sanitizedError.split('\n').slice(0, 4);
                 process.stderr.write(chalk.red(`      ${lines.join('\n      ')}\n`));
             }
             else if (success && output && output.length > 0) {
-                const brief = output.split('\n')[0].slice(0, 120);
+                const outputLines = output.split('\n').map((line) => line.trimEnd()).filter(Boolean);
+                const firstMeaningfulLine = outputLines.find((line) => !/^## Untrusted workspace data boundary/i.test(line)) || outputLines[0] || '';
+                const brief = firstMeaningfulLine.slice(0, 160);
                 process.stderr.write(chalk.gray(`      ${brief}${output.length > 120 ? '…' : ''}\n`));
             }
             spinner.start();
             spinner.text = 'Next step...';
             return;
         }
+        if (event.type === 'v3_status') {
+            spinner.text = this.sanitizeServerPath(String(event.content || 'Routing to V3 Agent...'));
+            return;
+        }
+        if (event.type === 'queued') {
+            if (spinner.isSpinning)
+                spinner.stop();
+            process.stderr.write(chalk.yellow('  [Queue] ') + this.sanitizeServerPath(String(event.message || 'Waiting for V3 capacity...')) + '\n');
+            spinner.start();
+            spinner.text = 'Waiting for V3...';
+            return;
+        }
+        if (event.type === 'heartbeat') {
+            spinner.text = 'V3 Agent is still thinking...';
+            return;
+        }
         if (event.type === 'thinking') {
             this.v3IterationCount += 1;
             const iterText = this.sanitizeServerPath(event.content || '');
             if (spinner.isSpinning)
                 spinner.stop();
-            process.stderr.write(chalk.cyan(`\n── ${iterText || `Iteration ${this.v3IterationCount}`} ──\n`));
+            process.stderr.write(chalk.cyan(`\n── Iteration ${this.v3IterationCount}${iterText ? '' : '...'} ──\n`));
+            if (iterText) {
+                process.stderr.write(chalk.gray(`${iterText}\n`));
+            }
             spinner.start();
             spinner.text = 'Analyzing...';
             return;
@@ -813,6 +1405,22 @@ export class ChatCommand {
             process.stderr.write(chalk.cyan('  [Start] ') + 'Agent initialized\n');
             spinner.start();
             spinner.text = 'Working...';
+            return;
+        }
+        const fallbackStatus = typeof event.status === 'string' ? this.sanitizeServerPath(event.status) : '';
+        const fallbackStage = typeof event.stage === 'string' ? this.sanitizeServerPath(event.stage) : '';
+        const fallbackMessage = typeof event.message === 'string'
+            ? this.sanitizeServerPath(event.message)
+            : (typeof event.content === 'string' ? this.sanitizeServerPath(event.content) : '');
+        if (event.type === 'status' || event.type === 'progress' || fallbackStatus || fallbackStage) {
+            if (spinner.isSpinning)
+                spinner.stop();
+            if (fallbackMessage) {
+                process.stderr.write(chalk.cyan('  [V3] ') + `${fallbackMessage}\n`);
+            }
+            spinner.start();
+            spinner.text = fallbackStatus || fallbackStage || 'Working...';
+            return;
         }
     }
     updateOperatorSpinner(spinner, event) {
@@ -878,6 +1486,7 @@ export class ChatCommand {
             }
             return;
         }
+        await this.config.refreshHubModelPreferences().catch(() => null);
         this.agentMode = options.agent === true;
         this.operatorMode = options.operator === true;
         this.workflowTarget = typeof options.workflow === 'string' && options.workflow.trim()
@@ -886,6 +1495,7 @@ export class ChatCommand {
         this.savePlanToVigFlow = options.savePlan === true;
         this.jsonOutput = options.json === true;
         this.autoApprove = options.autoApprove === true || this.jsonOutput;
+        this.personaOverride = options.grant === true ? 'wiener_grant' : null;
         this.modelExplicitlySelected = Boolean(String(options.model || '').trim());
         this.currentModel = this.resolveInitialModel(options);
         this.applyNoAgentGovernance(String(options.model || this.currentModel || ''));
@@ -956,7 +1566,10 @@ export class ChatCommand {
                     bridge.destroy();
                 }
             }
-            return;
+            // Force-exit: undici + chokidar + HTTPS pool keep the Node.js event
+            // loop alive indefinitely in direct prompt mode; a clean exit is safe here.
+            this.api.destroy();
+            process.exit(process.exitCode ?? 0);
         }
         await this.startInteractiveChat();
         const bridge = getBridgeClient();
@@ -998,11 +1611,57 @@ export class ChatCommand {
         }
         fs.mkdirSync(this.currentProjectPath, { recursive: true });
     }
+    shouldStartWorkspaceWatcher(workspaceRoot) {
+        if (!workspaceRoot) {
+            return false;
+        }
+        const resolved = path.resolve(workspaceRoot);
+        if (!fs.existsSync(resolved)) {
+            return false;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(resolved);
+        }
+        catch {
+            return false;
+        }
+        if (!stat.isDirectory()) {
+            return false;
+        }
+        const homeDir = path.resolve(os.homedir());
+        const normalized = resolved.replace(/\\/g, '/');
+        const normalizedHome = homeDir.replace(/\\/g, '/');
+        // Guardrail: do not watch broad home/root scopes on interactive shells.
+        if (normalized.toLowerCase() === normalizedHome.toLowerCase()) {
+            if (!this.jsonOutput) {
+                console.log(chalk.gray('Info: workspace watcher disabled for home directory scope.'));
+            }
+            return false;
+        }
+        if (/^[a-zA-Z]:\/$/.test(normalized) || normalized === '/') {
+            if (!this.jsonOutput) {
+                console.log(chalk.gray('Info: workspace watcher disabled for filesystem root scope.'));
+            }
+            return false;
+        }
+        return true;
+    }
     resolveProjectPath(options) {
         const requestedProject = String(options.project || '').trim();
         if (requestedProject) {
             return path.resolve(requestedProject);
         }
+        // Check if prompt contains an explicit local path provided by the user
+        if (options.prompt) {
+            const explicitPath = this.resolvePromptWorkspacePath(options.prompt, process.cwd());
+            if (explicitPath) {
+                if (!this.jsonOutput) {
+                    console.log(chalk.gray(`📁 Using project path from prompt: ${explicitPath}`));
+                }
+                return explicitPath;
+            }
+        }
         if (this.shouldUseManagedWorkspace(options)) {
             const rootPath = this.getManagedWorkspaceRoot();
             fs.mkdirSync(rootPath, { recursive: true });
@@ -1465,6 +2124,26 @@ export class ChatCommand {
         }
     }
     async runSimplePrompt(prompt) {
+        if (!this.directPromptMode && !this.operatorMode) {
+            const promptToRun = this.isConfirmationFollowUp(prompt) && this.lastActionableUserInput && this.isRepoGroundedPrompt(this.lastActionableUserInput)
+                ? this.lastActionableUserInput
+                : prompt;
+            if (this.isRepoGroundedPrompt(promptToRun) || /\b(build|implement|complete|fix|create|make|edit|write|change|finish)\b/i.test(promptToRun)) {
+                if (!this.tools) {
+                    throw new Error('Agent tools are not initialized.');
+                }
+                this.agentMode = true;
+                this.syncInteractiveModeModel('agent');
+                if (this.currentSession) {
+                    this.currentSession.agentMode = true;
+                    this.currentSession.model = this.currentModel;
+                }
+                console.log(chalk.yellow('This request needs file access, so I am switching to Agent mode and working in this workspace now.'));
+                console.log(chalk.gray('You do not need to confirm with "yes"; I will continue until the agent run finishes or reports a blocker.'));
+                await this.runAgentTurn(promptToRun);
+                return;
+            }
+        }
         this.lastActionableUserInput = prompt;
         // For direct --prompt mode with simple prompts, use a minimal system
         // message to avoid polluting the response with tool/platform context.
@@ -1525,7 +2204,7 @@ export class ChatCommand {
             const response = await this.callApi('Send chat message', () => this.api.chat(this.getMessagesForModel(), this.currentModel));
             if (spinner)
                 spinner.stop();
-            const finalText = (response.message || '').trim();
+            const finalText = this.sanitizeDirectModeOutput(this.stripHiddenThoughtBlocks(response.message || '')).trim();
             const effectiveModel = String(response.model || this.currentModel);
             const metadata = this.modelGovernanceFallback
                 ? { modelFallback: this.modelGovernanceFallback }
@@ -1570,21 +2249,32 @@ export class ChatCommand {
             }
         }
     }
-    async runAgentTurn(prompt) {
+    async runAgentTurn(prompt, options = {}) {
         if (!this.tools) {
             throw new Error('Agent tools are not initialized.');
         }
+        this.bindPromptWorkspace(prompt);
         const requiresV3Workflow = this.shouldRequireV3AgentWorkflow(prompt);
         const handledByDirectFileFlow = await this.tryDirectSingleFileFlow(prompt);
         if (handledByDirectFileFlow) {
             this.saveSession();
             return;
         }
-        if (this.shouldPreferLocalAgentLoop(prompt)) {
-            await this.runLocalAgentLoop(prompt);
-            return;
+        // Prime the message context with the target file when the direct-file flow was
+        // bypassed (e.g. HTML files routed to V3) so the local agent loop has file
+        // awareness and the ⚙ Executing: read_file banner is always emitted.
+        await this.primeBypassedTargetFileContext(prompt);
+        if (!options.skipLocalLoop && !options.forceV3 && this.shouldPreferLocalAgentLoop(prompt)) {
+            const completed = await this.runLocalAgentLoop(prompt);
+            if (completed) {
+                this.saveSession();
+                return;
+            }
+            if (!this.jsonOutput) {
+                console.log(chalk.yellow('Local chat backend unavailable (self-hosted inference may be offline). Trying V3 agent workflow...'));
+            }
         }
-        const handledByV3Workflow = await this.tryV3AgentWorkflow(prompt);
+        const handledByV3Workflow = await this.tryV3AgentWorkflow(prompt, options);
         if (handledByV3Workflow) {
             this.saveSession();
             return;
@@ -1598,10 +2288,56 @@ export class ChatCommand {
         }
         await this.runLocalAgentLoop(prompt);
     }
+    localAgentIterationCount = 0;
+    buildLocalAgentChatOptions(preflight, onRouteAttempt) {
+        const preferredRoute = preflight?.endpoint
+            ? this.api.mapPreflightEndpointToRoute(preflight.endpoint)
+            : undefined;
+        return {
+            fastFail: true,
+            singleRoute: true,
+            stream: true,
+            connectTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_CONNECT_TIMEOUT_MS || '20000', 10),
+            idleTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_IDLE_TIMEOUT_MS || '120000', 10),
+            preferredRoute: preferredRoute || 'coder',
+            onRouteAttempt,
+        };
+    }
+    printChatModelPreflight(preflight) {
+        if (this.jsonOutput) {
+            return;
+        }
+        console.log(chalk.gray('Model backend preflight:'));
+        for (const route of preflight.routes) {
+            const marker = route.ok ? chalk.green('  ✓') : chalk.red('  ✗');
+            const detail = route.error ? chalk.gray(` — ${route.error}`) : '';
+            console.log(`${marker} ${route.name}${detail}`);
+        }
+        if (preflight.healthy) {
+            console.log(chalk.gray(`Using: ${preflight.endpoint}`));
+        }
+        else if (preflight.error) {
+            console.log(chalk.yellow(preflight.error));
+        }
+        console.log();
+    }
     async runLocalAgentLoop(prompt) {
         if (!this.tools) {
             throw new Error('Agent tools are not initialized.');
         }
+        this.localAgentIterationCount = 0;
+        const runtime = this.getRuntimeEnvironmentContext();
+        if (!this.jsonOutput) {
+            console.log();
+            console.log(chalk.gray('━━━ ROUTING DECISION ━━━'));
+            console.log(chalk.gray('Reason: local-machine-agent-loop'));
+            console.log(chalk.gray(`Platform: ${runtime.platform}`));
+            console.log(chalk.gray(`Machine scope: ${runtime.machineScope}`));
+            console.log(chalk.gray(`Workspace: ${runtime.workspacePath}`));
+            console.log(chalk.gray('Tools execute on your local filesystem.'));
+            console.log(chalk.gray('━'.repeat(30)));
+            console.log();
+        }
         this.lastActionableUserInput = prompt;
         this.directToolContinuationCount = 0;
         this.agentToolEvidence = { discovery: 0, mutation: 0, searchFailed: 0 };
@@ -1610,12 +2346,50 @@ export class ChatCommand {
         this.ensureAgentSystemPrompt();
         this.messages.push({ role: 'user', content: this.buildScopedUserPrompt(prompt) });
         this.saveSession();
+        const preflightSpinner = this.jsonOutput
+            ? null
+            : createSpinner({ text: 'Checking model connection (preflight)...', spinner: 'clock' }).start();
+        let preflight;
+        try {
+            preflight = await this.api.runChatModelPreflight(this.currentModel);
+        }
+        finally {
+            if (preflightSpinner) {
+                preflightSpinner.stop();
+            }
+        }
+        this.printChatModelPreflight(preflight);
+        if (!preflight.healthy) {
+            return false;
+        }
         const maxTurns = 10;
+        const preferredRoute = preflight?.endpoint
+            ? (this.api.mapPreflightEndpointToRoute(preflight.endpoint) || 'coder')
+            : 'coder';
         for (let turn = 0; turn < maxTurns; turn += 1) {
-            const spinner = this.jsonOutput ? null : createSpinner({ text: turn === 0 ? 'Planning...' : 'Continuing...', spinner: 'clock' }).start();
+            const spinner = this.jsonOutput ? null : createSpinner({ text: turn === 0 ? 'Planning first tool step...' : 'Continuing...', spinner: 'clock' }).start();
+            let streamedVisible = '';
             let response;
             try {
-                response = await this.callApi('Send agent chat message', () => this.api.chat(this.getMessagesForModel(), this.currentModel), 0);
+                response = await this.callApi('Send agent chat message', () => this.api.chat(this.getMessagesForModel({ compact: turn === 0 }), this.currentModel, false, {
+                    fastFail: true,
+                    singleRoute: true,
+                    stream: true,
+                    connectTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_CONNECT_TIMEOUT_MS || '20000', 10),
+                    idleTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_IDLE_TIMEOUT_MS || '120000', 10),
+                    preferredRoute,
+                    onRouteAttempt: (routeLabel) => {
+                        if (spinner) {
+                            spinner.text = routeLabel;
+                        }
+                    },
+                    onStreamDelta: (chunk) => {
+                        streamedVisible += chunk;
+                        if (spinner) {
+                            spinner.text = streamedVisible.trim().slice(-72) || 'Streaming model output...';
+                        }
+                    },
+                }), 0);
             }
             catch (firstErr) {
                 // If we already gathered evidence and the model API fails on a
@@ -1624,7 +2398,14 @@ export class ChatCommand {
                     this.logger.debug('Agent continuation API call failed, retrying once...');
                     try {
                         await new Promise(r => setTimeout(r, 2000));
-                        response = await this.callApi('Retry agent chat message', () => this.api.chat(this.getMessagesForModel(), this.currentModel), 0);
+                        response = await this.callApi('Retry agent chat message', () => this.api.chat(this.getMessagesForModel(), this.currentModel, false, {
+                            fastFail: true,
+                            singleRoute: true,
+                            stream: true,
+                            connectTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_CONNECT_TIMEOUT_MS || '20000', 10),
+                            idleTimeoutMs: Number.parseInt(process.env.VIGTHORIA_CHAT_IDLE_TIMEOUT_MS || '120000', 10),
+                            preferredRoute,
+                        }), 0);
                     }
                     catch (retryErr) {
                         // Retry also failed — synthesize an answer from evidence
@@ -1647,13 +2428,57 @@ export class ChatCommand {
                                 console.log(fallbackContent);
                             }
                             this.saveSession();
-                            return;
+                            return true;
                         }
                         throw retryErr;
                     }
                 }
                 else {
-                    throw firstErr;
+                    const cliErr = firstErr instanceof CLIError ? firstErr : classifyError(firstErr);
+                    const formatted = formatCLIError(cliErr);
+                    if (spinner)
+                        spinner.stop();
+                    this.rememberBrainEvent('issue', 'Agent model request failed: ' + formatted, 'agent');
+                    if (turn === 0 && (cliErr.category === 'model_backend' || cliErr.category === 'network' || cliErr.category === 'timeout')) {
+                        if (!this.jsonOutput) {
+                            this.logger.error(formatted);
+                            const transport = this.api.getLastChatTransportErrors();
+                            if (transport.length > 0) {
+                                console.log(chalk.gray(`Routes tried: ${transport.slice(0, 3).join(' | ')}`));
+                            }
+                        }
+                        else {
+                            process.exitCode = 1;
+                            console.log(JSON.stringify({
+                                success: false,
+                                mode: 'agent',
+                                model: this.currentModel,
+                                partial: false,
+                                content: '',
+                                error: formatted,
+                                errorCategory: cliErr.category,
+                                metadata: { executionPath: 'local-agent-loop' },
+                            }, null, 2));
+                        }
+                        return false;
+                    }
+                    if (this.jsonOutput) {
+                        process.exitCode = 1;
+                        console.log(JSON.stringify({
+                            success: false,
+                            mode: 'agent',
+                            model: this.currentModel,
+                            partial: false,
+                            content: '',
+                            error: formatted,
+                            errorCategory: cliErr.category,
+                            metadata: { executionPath: 'local-agent-loop' },
+                        }, null, 2));
+                    }
+                    else {
+                        this.logger.error(formatted);
+                    }
+                    return true;
                 }
             }
             if (spinner)
@@ -1663,6 +2488,11 @@ export class ChatCommand {
                 this.messages.push({ role: 'assistant', content: assistantMessage });
                 const toolCalls = this.extractToolCalls(assistantMessage);
                 const visibleText = this.stripToolPayloads(assistantMessage).trim();
+                if (visibleText && !this.jsonOutput) {
+                    this.localAgentIterationCount += 1;
+                    console.log(chalk.cyan(`\n── Iteration ${this.localAgentIterationCount} ──`));
+                    console.log(chalk.gray(visibleText));
+                }
                 getBridgeClient()?.emitModelResponse({
                     model: this.currentModel,
                     chars: assistantMessage.length,
@@ -1731,7 +2561,7 @@ export class ChatCommand {
                         console.log(finalContent);
                     }
                     this.saveSession();
-                    return;
+                    return true;
                 }
                 await this.executeToolCalls(toolCalls);
                 this.directToolContinuationCount += 1;
@@ -1765,7 +2595,7 @@ export class ChatCommand {
                 else {
                     this.logger.error(errorMsg);
                 }
-                return;
+                return true;
             }
         }
         if (this.jsonOutput) {
@@ -1786,6 +2616,36 @@ export class ChatCommand {
             console.log('Task complete.');
         }
         this.saveSession();
+        return true;
+    }
+    async primeBypassedTargetFileContext(prompt) {
+        if (!this.directPromptMode || !this.tools) {
+            return;
+        }
+        const targetFile = this.inferTargetFileFromPrompt(prompt);
+        if (!targetFile) {
+            return;
+        }
+        // Only prime if the direct-file flow was bypassed for this file (e.g. HTML routed to V3).
+        // This ensures the local agent loop always has full file awareness before planning.
+        if (!this.shouldBypassDirectSingleFileFlow(targetFile, prompt)) {
+            return;
+        }
+        const readCall = {
+            tool: 'read_file',
+            args: { path: targetFile },
+        };
+        if (!this.jsonOutput) {
+            console.log(chalk.cyan(`⚙ Executing: ${readCall.tool}`));
+        }
+        const readResult = await this.tools.execute(readCall);
+        const readSummary = this.formatToolResult(readCall, readResult);
+        if (!this.jsonOutput) {
+            console.log(readResult.success ? chalk.gray(readSummary) : chalk.red(readSummary));
+        }
+        if (readResult.success && readResult.output) {
+            this.messages.push({ role: 'system', content: readSummary });
+        }
     }
     async tryDirectSingleFileFlow(prompt) {
         if (!this.directPromptMode || !this.tools) {
@@ -1942,7 +2802,16 @@ export class ChatCommand {
             'Do not reinterpret this confirmation as a new website, landing page, template, or index.html task.',
         ].join('\n');
     }
-    async tryV3AgentWorkflow(prompt) {
+    async tryV3AgentWorkflow(prompt, options = {}) {
+        // Extract explicit workspace path from prompt (if provided by user)
+        let promptWorkspacePath = null;
+        try {
+            promptWorkspacePath = this.resolvePromptWorkspacePath(prompt, this.currentProjectPath);
+        }
+        catch {
+            // Path extraction failed, use default workspace
+        }
+        const workspacePath = promptWorkspacePath || this.currentProjectPath;
         const contextualPrompt = this.buildContextualAgentPrompt(prompt);
         if (contextualPrompt === prompt && !this.isConfirmationFollowUp(prompt)) {
             this.lastActionableUserInput = prompt;
@@ -1950,11 +2819,28 @@ export class ChatCommand {
         this.messages.push({ role: 'user', content: contextualPrompt });
         const runtimeContext = await this.getPromptRuntimeContext(contextualPrompt);
         const routingPolicy = this.resolveAgentExecutionPolicy(contextualPrompt);
+        // STREAMING: Log routing decision transparently to user
+        if (!this.jsonOutput) {
+            console.log();
+            console.log(chalk.gray('━━━ ROUTING DECISION ━━━'));
+            console.log(chalk.gray(`Reason: ${routingPolicy.routeReason}`));
+            console.log(chalk.gray(`Model: ${routingPolicy.selectedModel}`));
+            console.log(chalk.gray(`Cloud Eligible: ${routingPolicy.cloudEligible}`));
+            console.log(chalk.gray(`Cloud Selected: ${routingPolicy.cloudSelected}`));
+            if (routingPolicy.heavyTask) {
+                console.log(chalk.gray(`Task Complexity: HEAVY`));
+            }
+            console.log(chalk.gray('━'.repeat(30)));
+            console.log();
+        }
         // Reset streaming counters for new workflow
         this.v3IterationCount = 0;
         this.v3ToolCallCount = 0;
         this.v3LastActivity = Date.now();
         this.v3StreamingStarted = false;
+        this.v3StreamedTextBuffer = '';
+        this.v3LiveToolEvidence = [];
+        this.v3PendingToolCalls = [];
         const taskDisplay = new TaskDisplay(['Analyse workspace', 'Execute tasks', 'Validate output', 'Self-heal'], !this.jsonOutput);
         taskDisplay.start(0);
         const spinner = this.jsonOutput ? null : createSpinner({
@@ -2018,25 +2904,59 @@ export class ChatCommand {
         const executionPrompt = this.buildExecutionPrompt(contextualPrompt);
         const agentTaskType = this.inferAgentTaskType(contextualPrompt);
         const workspaceContext = {
-            workspacePath: this.currentProjectPath,
-            projectPath: this.currentProjectPath,
-            targetPath: this.currentProjectPath,
+            workspacePath: workspacePath,
+            projectPath: workspacePath,
+            targetPath: workspacePath,
             ...runtimeContext,
         };
+        if (!this.jsonOutput && !this.directPromptMode) {
+            try {
+                const snapshot = this.api.getAgentWorkspaceSnapshot(workspacePath);
+                console.log(chalk.gray(`Workspace sync: ${snapshot.fileCount} files indexed from ${workspacePath}`));
+                if (snapshot.paths.length > 0) {
+                    console.log(chalk.gray(`Workspace index: ${snapshot.paths.slice(0, 5).map((filePath) => filePath.replace(/\\/g, '/')).join(', ')}${snapshot.paths.length > 5 ? ', ...' : ''}`));
+                }
+            }
+            catch {
+                console.log(chalk.gray(`Workspace sync: preparing ${workspacePath}`));
+            }
+        }
         // Start workspace watcher for bidirectional real-time sync
         let watcher = null;
-        if (this.currentProjectPath && fs.existsSync(this.currentProjectPath)) {
+        let workspaceWs = null;
+        const stopWorkspaceSync = () => {
+            watcher?.stop();
+            if (workspaceWs) {
+                workspaceWs.disconnect();
+                workspaceWs = null;
+            }
+        };
+        if (this.shouldStartWorkspaceWatcher(workspacePath)) {
             watcher = new WorkspaceWatcher({
-                workspaceRoot: this.currentProjectPath,
+                workspaceRoot: workspacePath,
                 onFileChange: (relativePath, content, action) => {
                     this.logger.debug(`Local change detected: ${action} ${relativePath}`);
+                    workspaceWs?.syncFile(relativePath, content, action);
                 },
             });
             watcher.start();
         }
         try {
+            // Ensure the V3 service key is available before health check
+            await this.api.ensureV3ServiceKey();
+            if (spinner)
+                this.updateV3AgentSpinner(spinner, { type: 'v3_status', content: 'Checking V3 connection (preflight)...' });
+            const healthCheck = await this.api.runV3HealthCheck({ soft: true });
+            if (!healthCheck.healthy) {
+                this.logger.warn('V3 health probe did not confirm readiness; starting SSE agent stream anyway.');
+                if (spinner)
+                    this.updateV3AgentSpinner(spinner, { type: 'v3_status', content: 'Starting V3 agent stream...' });
+            }
+            else if (spinner) {
+                this.updateV3AgentSpinner(spinner, { type: 'v3_status', content: 'Connected to V3. Starting agent execution...' });
+            }
             const workflowPromise = this.api.runV3AgentWorkflow(executionPrompt, {
-                workspace: { path: this.currentProjectPath },
+                workspace: { path: workspacePath },
                 ...workspaceContext,
                 agentTaskType,
                 executionSurface: 'cli',
@@ -2052,6 +2972,32 @@ export class ChatCommand {
                 rawPrompt: prompt,
                 contextualPrompt,
                 history: this.getMessagesForModel(),
+                clientToolExecution: true,
+                liveToolEvidence: this.v3LiveToolEvidence,
+                onClientToolExecute: (event) => this.executeClientV3Tool(event),
+                onWorkspaceContext: async ({ contextId, serverWorkspaceRoot }) => {
+                    if (workspaceWs || !contextId || !serverWorkspaceRoot || !this.shouldStartWorkspaceWatcher(workspacePath)) {
+                        return;
+                    }
+                    const headers = await this.api.getV3AgentHeaders();
+                    const token = String(headers.Authorization?.replace(/^Bearer\s+/i, '')
+                        || headers['X-V3-Service-Key']
+                        || headers['x-v3-service-key']
+                        || '').trim();
+                    if (!token) {
+                        return;
+                    }
+                    const baseUrl = this.api.getV3AgentBaseUrls(false)[0] || 'https://coder.vigthoria.io';
+                    const serverUrl = baseUrl.replace(/^http/i, 'ws');
+                    workspaceWs = new WorkspaceWSClient({
+                        serverUrl,
+                        token,
+                        contextId,
+                        workspaceRoot: serverWorkspaceRoot,
+                    });
+                    workspaceWs.connect();
+                    this.logger.debug(`Workspace WS sync bound to context ${contextId}`);
+                },
                 ...runtimeContext,
                 onStreamEvent: (event) => {
                     if (event.type === 'plan') {
@@ -2111,6 +3057,34 @@ export class ChatCommand {
             if (this.v3StreamingStarted) {
                 process.stdout.write('\n');
             }
+            let finalContent = String(response.content || '').trim();
+            const needsUserReport = this.inferAgentTaskType(prompt) === 'analysis'
+                || this.isThinV3Summary(finalContent)
+                || this.v3LiveToolEvidence.length > 0;
+            if (needsUserReport) {
+                const userReport = this.buildUserFacingV3RunReport(prompt, workspacePath, {
+                    partial: response.partial === true || this.isThinV3Summary(finalContent),
+                    serverNote: finalContent && !this.isThinV3Summary(finalContent) ? finalContent : undefined,
+                });
+                if (userReport && !this.isThinV3Summary(userReport)) {
+                    finalContent = userReport;
+                }
+            }
+            else if (this.isThinV3Summary(finalContent) && this.v3LiveToolEvidence.length > 0) {
+                const evidenceSummary = this.api.formatV3AgentResponse({
+                    events: [],
+                    liveToolEvidence: this.v3LiveToolEvidence,
+                });
+                if (evidenceSummary && !this.isThinV3Summary(evidenceSummary)) {
+                    finalContent = evidenceSummary;
+                }
+            }
+            response.content = finalContent || response.content;
+            let v3UserReportPrinted = false;
+            if (!this.jsonOutput && finalContent && needsUserReport) {
+                this.printV3UserReport(finalContent);
+                v3UserReportPrinted = true;
+            }
             const previewGate = (response.metadata?.previewGate || null);
             const workspaceHasOutput = this.api.hasAgentWorkspaceOutput(workspaceContext);
             const success = previewGate?.required === true
@@ -2123,7 +3097,7 @@ export class ChatCommand {
                     }
                     this.logger.warn('Falling back to legacy CLI agent loop');
                     this.logger.debug(`V3 agent workflow returned an incomplete result: ${previewGate?.error || 'workspace changes were not fully validated'}`);
-                    watcher?.stop();
+                    stopWorkspaceSync();
                     return false;
                 }
                 const errorMessage = `V3 agent workflow returned an incomplete result and legacy fallback is disabled. ${previewGate?.error || 'Workspace changes were not fully validated.'}`;
@@ -2144,7 +3118,7 @@ export class ChatCommand {
                         metadata: { executionPath: 'v3-agent', previewGate },
                     }, null, 2));
                 }
-                watcher?.stop();
+                stopWorkspaceSync();
                 return true;
             }
             if (!this.jsonOutput && previewGate?.required && previewGate?.passed !== true && workspaceHasOutput) {
@@ -2164,16 +3138,32 @@ export class ChatCommand {
                 }, null, 2));
             }
             else if (this.v3StreamingStarted) {
-                // Content was already streamed to stdout in real-time; skip duplicate print.
-                if (!this.jsonOutput) {
+                // Content may have been streamed already, but some V3 runs only stream
+                // status/tool messages and keep the useful final report in response.content.
+                if (!v3UserReportPrinted && !this.jsonOutput) {
                     console.log(chalk.gray(`Agent routing: ${routingPolicy.cloudSelected ? 'Vigthoria Cloud' : 'V3 Agent'}`));
                 }
+                if (!v3UserReportPrinted && response.content && this.shouldPrintV3FinalContent(response.content)) {
+                    console.log(response.content);
+                }
+                else if (!v3UserReportPrinted && response.content && this.isThinV3Summary(response.content)) {
+                    console.log(chalk.yellow('V3 agent finished after reading local files, but no final narrative summary was emitted.'));
+                    console.log(chalk.gray('Use /continue and ask for a written overview.'));
+                }
             }
             else if (response.content) {
-                if (!this.directPromptMode) {
+                if (!v3UserReportPrinted && !this.directPromptMode) {
                     console.log(chalk.gray(`Agent routing: ${routingPolicy.cloudSelected ? 'Vigthoria Cloud' : 'V3 Agent'}`));
                 }
-                console.log(response.content);
+                if (!v3UserReportPrinted && this.shouldPrintV3FinalContent(response.content)) {
+                    console.log(response.content);
+                }
+                else if (!v3UserReportPrinted && this.isThinV3Summary(response.content)) {
+                    console.log('V3 agent workflow completed, but no final task summary was emitted.');
+                }
+                else if (!v3UserReportPrinted) {
+                    console.log(response.content);
+                }
             }
             else {
                 if (!this.directPromptMode) {
@@ -2285,11 +3275,11 @@ export class ChatCommand {
                 this.printAgentRunSummary(this.lastAgentRunOutcome, executorSucceeded, changedFileCount);
             }
             this.messages.push({ role: 'assistant', content: response.content || 'V3 agent workflow completed.' });
-            watcher?.stop();
+            stopWorkspaceSync();
             return true;
         }
         catch (error) {
-            watcher?.stop();
+            stopWorkspaceSync();
             if (!this.api.hasAgentWorkspaceOutput(workspaceContext)) {
                 const recovered = await this.tryRecoverV3ServiceAndRetry(executionPrompt, prompt, workspaceContext, routingPolicy, spinner, error);
                 if (recovered) {
@@ -2592,9 +3582,15 @@ export class ChatCommand {
                     this.syncInteractiveModeModel('agent');
                     console.log(chalk.gray('Agent mode re-enabled for continuation.'));
                 }
-                await this.runAgentTurn(followUp);
+                await this.runAgentTurn(followUp, { skipLocalLoop: true, forceV3: true });
                 continue;
             }
+            if (/^(?:\/logout|logout)$/i.test(trimmed)) {
+                const { logout } = await import('./auth.js');
+                await logout();
+                console.log(chalk.gray('Session ended.'));
+                break;
+            }
             if (trimmed === '/save') {
                 this.saveSession();
                 console.log(chalk.green('Session saved.'));
@@ -2681,6 +3677,9 @@ export class ChatCommand {
                 console.log(chalk.gray('  Pending:  ') + chalk.yellow(unfinishedList.join(', ')) + more);
             }
         }
+        else if (!executorSucceeded) {
+            console.log(chalk.gray('  The detailed overview is printed above when available.'));
+        }
         if (typeof outcome.qualityScore === 'number') {
             const score = outcome.qualityScore.toFixed(1);
             const colour = outcome.qualityScore >= 70 ? chalk.green : outcome.qualityScore >= 30 ? chalk.yellow : chalk.red;
@@ -2769,7 +3768,10 @@ export class ChatCommand {
         const missingLine = o.qualityMissing.length > 0
             ? `\nMissing pieces: ${o.qualityMissing.slice(0, 6).join(', ')}.`
             : '';
-        return `Continue the previous agent run from the current workspace state without re-doing already-completed work.${taskList}${blockerLine}${missingLine}\nOriginal request was: ${o.prompt}`;
+        return `Continue the previous agent run from the current workspace state without re-doing already-completed work.${taskList}${blockerLine}${missingLine}
+Original request was: ${o.prompt}
+
+Now implement the missing fixes by editing the local workspace files. Use write/edit tools to apply the required code and HTML changes so the project runs.`;
     }
     /**
      * Re-print the last agent run summary, or guide the user when there isn't one.
@@ -2857,6 +3859,7 @@ export class ChatCommand {
         });
     }
     buildAgentSystemPrompt() {
+        const runtime = this.getRuntimeEnvironmentContext();
         const toolCatalog = AgenticTools.getToolDefinitions()
             .map((tool) => {
             const params = tool.parameters
@@ -2868,6 +3871,7 @@ export class ChatCommand {
         return [
             'Vigthoria CLI agent operating contract.',
             `You are operating inside the project root: ${this.currentProjectPath}`,
+            `Execution platform: ${runtime.platform} (${runtime.osPlatform}). Machine scope: ${runtime.machineScope}.`,
             `You are operating on the user's LOCAL machine. This CLI is not a server-only runtime.`,
             `All file reads/writes and command execution must target the local project/workspace path unless the user explicitly requests remote/server execution.`,
             'For command execution: ask for confirmation before risky commands; never redirect normal local work to server paths.',
@@ -2900,10 +3904,12 @@ export class ChatCommand {
         ].join('\n');
     }
     buildScopedUserPrompt(prompt) {
+        const runtime = this.getRuntimeEnvironmentContext();
         return [
             this.buildExecutionPrompt(prompt),
             '',
             `Project root: ${this.currentProjectPath}`,
+            `Execution platform: ${runtime.platform}. Machine scope: ${runtime.machineScope}.`,
             'Stay within this project root unless the user explicitly expands scope.',
             'Finish the request and stop once it is complete.',
         ].join('\n');
@@ -2965,7 +3971,14 @@ export class ChatCommand {
             return true;
         }
         const extension = path.extname(targetFile).toLowerCase();
-        return extension === '';
+        if (extension === '')
+            return true;
+        // HTML/HTM files need V3 agent with the 35B model for quality rewrites (canvas,
+        // styling, interactivity). Route them to tryV3AgentWorkflow instead of the
+        // lightweight cloud-chat direct-file path.
+        if (extension === '.html' || extension === '.htm')
+            return true;
+        return false;
     }
     shouldPreferLocalAgentLoop(prompt) {
         if (this.shouldRequireV3AgentWorkflow(prompt)) {
@@ -2975,16 +3988,44 @@ export class ChatCommand {
         if (forceV3) {
             return false;
         }
+        if (this.isBrowserTaskPrompt(prompt)) {
+            return false;
+        }
         const runtime = this.getRuntimeEnvironmentContext();
-        // Local machines and non-server-bindable workspaces should run locally first.
+        const forceRemoteAgent = /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_PREFER_V3_AGENT_LOOP
+            || process.env.VIGTHORIA_FORCE_REMOTE_AGENT
+            || ''));
+        // CLI sessions on a user's local machine must execute tools locally.
+        // Remote V3 only sees a partial hydrated copy and cannot reach real paths.
+        if (runtime.machineScope === 'local-machine') {
+            if (forceRemoteAgent) {
+                return false;
+            }
+            if (this.isImplementationPrompt(prompt)) {
+                return true;
+            }
+            const preferLocalOptIn = /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_PREFER_LOCAL_AGENT_LOOP || ''));
+            // Read-only analysis on a Windows/macOS/Linux desktop is faster and more
+            // reliable through V3 + client-side read tools than a blocking chat route.
+            if (this.isAnalysisLookupPrompt(prompt) && !preferLocalOptIn) {
+                return false;
+            }
+            return true;
+        }
+        // Server-bindable workspaces keep V3 as the default execution path.
+        const preferLocalOptIn = /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_PREFER_LOCAL_AGENT_LOOP || ''));
+        if (!preferLocalOptIn) {
+            return false;
+        }
+        if (this.directPromptMode && this.isRepoGroundedPrompt(prompt)) {
+            return false;
+        }
         if (!runtime.serverBindableWorkspace) {
             return true;
         }
-        // Interactive sessions should prioritize local edits unless V3 is explicitly forced.
         if (!this.directPromptMode) {
             return true;
         }
-        // For direct prompts on server-bindable Linux roots, keep V3-first behavior.
         return runtime.platform !== 'linux';
     }
     getRuntimeEnvironmentContext() {
@@ -3026,7 +4067,7 @@ export class ChatCommand {
         if (!projectPath || !path.isAbsolute(projectPath) || !fs.existsSync(projectPath)) {
             return false;
         }
-        const configuredRoots = (process.env.VIGTHORIA_SERVER_WORKSPACE_ROOTS || '/var/www/vigthoria-user-workspaces,/var/lib/vigthoria-workspaces')
+        const configuredRoots = (process.env.VIGTHORIA_SERVER_WORKSPACE_ROOTS || '/var/www,/var/www/vigthoria-user-workspaces,/var/lib/vigthoria-workspaces')
             .split(',')
             .map((entry) => entry.trim())
             .filter(Boolean);
@@ -3325,7 +4366,11 @@ export class ChatCommand {
      * substantive answer.
      */
     sanitizeDirectModeOutput(text) {
-        let cleaned = text;
+        let cleaned = this.stripHiddenThoughtBlocks(text);
+        cleaned = cleaned
+            .replace(/<\|mask_start\|>[\s\S]*?<\|mask_end\|>/g, '')
+            .replace(/<think>[\s\S]*?<\/think>/gi, '')
+            .replace(/<\|(?:mask_start|mask_end)\|>/g, '');
         // ── Phase 1: Strip entire tool-output blocks ──
         // Matches "Tool <name> succeeded/FAILED." through the next blank line,
         // next tool header, or end-of-string.  The DOTALL-like [\s\S]*? is
@@ -3398,7 +4443,7 @@ export class ChatCommand {
         cleaned = kept.join('\n\n');
         // Collapse multiple blank lines
         cleaned = cleaned.replace(/\n{3,}/g, '\n\n').trim();
-        return cleaned || text;
+        return cleaned || this.stripHiddenThoughtBlocks(text);
     }
     isDirectModeFollowUpQuestion(text) {
         return /^(would you like me|do you want me|which aspect|what aspect|can you clarify|could you clarify|should i focus on|i will follow|i understand|i('ll| will) adhere|provide your|waiting for)/i.test(text.trim());
@@ -3480,6 +4525,57 @@ export class ChatCommand {
             .trim();
         return normalized || null;
     }
+    async tryLocalToolFallback(call, result) {
+        if (result.success || !this.tools) {
+            return result;
+        }
+        const runtime = this.getRuntimeEnvironmentContext();
+        if (runtime.machineScope !== 'local-machine') {
+            return result;
+        }
+        if (call.tool === 'read_file' && call.args.path) {
+            const parent = path.dirname(call.args.path);
+            const listPath = parent === '.' || parent === '' ? '.' : parent;
+            const listResult = await this.tools.execute({
+                tool: 'list_dir',
+                args: { path: listPath },
+            });
+            if (listResult.success && listResult.output) {
+                return {
+                    ...result,
+                    suggestion: `File not found at "${call.args.path}". Parent directory "${listPath}" contains:\n${listResult.output}`,
+                };
+            }
+            const baseName = path.basename(call.args.path);
+            const globResult = await this.tools.execute({
+                tool: 'glob',
+                args: { pattern: `**/${baseName}` },
+            });
+            if (globResult.success && globResult.output?.trim()) {
+                return {
+                    ...result,
+                    suggestion: `File not found at "${call.args.path}". Matching paths:\n${globResult.output}`,
+                };
+            }
+        }
+        if (call.tool === 'list_dir') {
+            const listPath = call.args.path || '.';
+            const command = runtime.platform === 'windows'
+                ? `dir /b "${path.join(this.currentProjectPath, listPath)}"`
+                : `ls -la "${path.join(this.currentProjectPath, listPath)}"`;
+            const shellResult = await this.tools.execute({
+                tool: 'bash',
+                args: { command, cwd: this.currentProjectPath },
+            });
+            if (shellResult.success && shellResult.output) {
+                return {
+                    ...result,
+                    suggestion: `list_dir failed for "${listPath}". Terminal listing:\n${shellResult.output}`,
+                };
+            }
+        }
+        return result;
+    }
     async executeToolCalls(toolCalls) {
         if (!this.tools) {
             throw new Error('Agent tools are not initialized.');
@@ -3489,10 +4585,15 @@ export class ChatCommand {
         const verbose = !this.jsonOutput;
         for (const call of toolCalls) {
             if (verbose) {
-                console.log(chalk.cyan(`⚙ Executing: ${call.tool}`));
+                const target = call.args.path || call.args.pattern || call.args.command || '';
+                const detail = target ? chalk.gray(` → ${String(target).replace(/\\/g, '/')}`) : '';
+                console.log(chalk.cyan(`⚙ Executing: ${call.tool}`) + detail);
             }
             getBridgeClient()?.emitToolCall({ tool: call.tool, args: call.args });
             let result = await this.tools.execute(call);
+            if (!result.success) {
+                result = await this.tryLocalToolFallback(call, result);
+            }
             // Phase 2: If a search tool failed (search_failed), retry with alternate approach
             const searchStatus = result.metadata?.searchStatus;
             if (call.tool === 'grep' && searchStatus === 'search_failed') {