vigthoria-cli 1.13.25 → 1.13.29

package/dist/utils/api.js

@@ -3,7 +3,7 @@
  * Connects to coder.vigthoria.io API endpoints
  */
 import axios from 'axios';
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import fs from 'fs';
 import https from 'https';
 import net from 'net';
@@ -15,29 +15,31 @@ import { buildSemanticContext } from './context-ranker.js';
 import { getChangedFiles } from './workspace-cache.js';
 import { isSubstantiveAgentAnswer, isToolEvidenceStubAnswer } from './agentRunOutcome.js';
 import { buildExecutionHints, isPlannerBuildTask, resolvePlannerAgentTimeoutMs } from './requestIntent.js';
-import { isV3StreamKeepaliveEvent } from './v3-stream-events.js';
+import { assertValidAgentPlanEvent, 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, guardedFetch, 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 { SystemBrowserScreenshotAdapter } from './preview-screenshot-adapter.js';
 import { normalizeSubscriptionResponse } from './subscription-policy.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 { FrontendPreviewService, isConstrainedStaticFrontendRequest, } 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';
+import { containsHighConfidenceSecret, isSensitivePath, redactSensitiveText, safeChildProcessEnv, scanOutboundContext, } from './secret-policy.js';
+import { buildLocalWorkspaceReference } from './workspace-reference.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.';
+const MAX_V3_CLIENT_MUTATION_BYTES = 512 * 1024;
 export class CLIError extends Error {
     category;
     statusCode;
@@ -424,7 +426,7 @@ export class APIClient {
             extractExpectedFiles: (message, context) => this.extractExpectedWorkspaceFiles(message, context),
             isAnalysisOnlyTask: (message, context) => this.isAnalysisOnlyTask(message, context),
             sanitizeError: sanitizeUserFacingErrorText,
-            screenshotAdapter: dependencies.screenshotAdapter || new OptionalPuppeteerScreenshotAdapter(),
+            screenshotAdapter: dependencies.screenshotAdapter || new SystemBrowserScreenshotAdapter(),
         });
         const vigFlowTransport = axios.create({ timeout: 30_000 });
         installAxiosNetworkPolicy(vigFlowTransport, 'vigflow');
@@ -710,13 +712,10 @@ export class APIClient {
         return this.v3AgentClient.approvalUrl(baseUrl);
     }
     getOperatorBaseUrls() {
-        const configuredModelsApiUrl = String(this.config.get('modelsApiUrl') || 'https://api.vigthoria.io').replace(/\/$/, '');
         const urls = [
             process.env.VIGTHORIA_OPERATOR_URL,
             process.env.OPERATOR_URL,
-            'http://127.0.0.1:4009',
-            configuredModelsApiUrl,
-            'https://api.vigthoria.io',
+            'https://agent.vigthoria.io',
         ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
         return [...new Set(urls)];
     }
@@ -805,6 +804,9 @@ export class APIClient {
     getVigFlowExecutionStatus(executionId) {
         return this.vigFlowClient.executionStatus(executionId);
     }
+    deleteVigFlowWorkflow(selector) {
+        return this.vigFlowClient.deleteWorkflow(selector);
+    }
     async getV3AgentHeaders() {
         return this.v3AgentClient.headers();
     }
@@ -876,20 +878,12 @@ export class APIClient {
         const resolvedContext = this.ensureExecutionContext(context);
         const localWorkspacePath = this.resolveAgentTargetPath(resolvedContext);
         const serverWorkspacePath = this.resolveServerBindableWorkspacePath(resolvedContext);
-        const promptFocus = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || resolvedContext.prompt || '');
-        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, promptFocus);
-        if (resolvedContext.workspaceFilesOutOfBand === true && localWorkspaceSummary?.workspaceFiles) {
-            localWorkspaceSummary.workspaceHydration = {
-                delivery: 'out-of-band',
-                fileCount: Object.keys(localWorkspaceSummary.workspaceFiles).length,
-                complete: true,
-            };
-            delete localWorkspaceSummary.workspaceFiles;
-        }
         const requestedModel = String(resolvedContext.model || resolvedContext.requestedModel || 'agent');
         const resolvedModel = this.resolvePermittedModelId(requestedModel);
         const localWorkspaceName = this.getDisplayWorkspaceName(localWorkspacePath);
-        const localWorkspaceRef = localWorkspaceName ? `vigthoria://local-workspace/${localWorkspaceName}` : null;
+        const localWorkspaceRef = localWorkspacePath
+            ? buildLocalWorkspaceReference(localWorkspacePath, String(this.config.get('userId') || this.config.get('email') || ''))
+            : null;
         const executionSurface = String(resolvedContext.executionSurface || resolvedContext.clientSurface || 'cli');
         const localMachineCapable = resolvedContext.localMachineCapable !== false;
         const clientToolExecution = resolvedContext.clientToolExecution === false
@@ -898,15 +892,34 @@ export class APIClient {
                 || (!serverWorkspacePath
                     && localMachineCapable
                     && ['cli', 'fork', 'local-ide', 'desktop', 'local'].includes(executionSurface)));
+        const promptFocus = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || resolvedContext.prompt || '');
+        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, promptFocus, !clientToolExecution);
+        if (clientToolExecution && localWorkspaceSummary) {
+            localWorkspaceSummary.workspaceHydration = {
+                delivery: 'client-tool-bridge',
+                fileCount: Number(localWorkspaceSummary.fileCount || 0),
+                complete: false,
+                authoritativeLocation: 'client',
+            };
+            delete localWorkspaceSummary.workspaceFiles;
+        }
+        else if (resolvedContext.workspaceFilesOutOfBand === true && localWorkspaceSummary?.workspaceFiles) {
+            localWorkspaceSummary.workspaceHydration = {
+                delivery: 'out-of-band',
+                fileCount: Object.keys(localWorkspaceSummary.workspaceFiles).length,
+                complete: true,
+                authoritativeLocation: 'server',
+            };
+            delete localWorkspaceSummary.workspaceFiles;
+        }
         const publicRuntimeEnvironment = this.buildPublicRuntimeEnvironment(resolvedContext.agentRuntime, {
             localWorkspacePath,
             serverWorkspacePath,
         });
-        // When the server cannot directly access the workspace (e.g. Windows
-        // client), use the local path as a hint and flag that the workspace
-        // files are provided inline in localWorkspaceSummary.workspaceFiles.
+        // A local CLI/Workbench workspace remains authoritative on that machine.
+        // Only server-owned/background runs may hydrate a bounded server copy.
         const effectiveWorkspacePath = serverWorkspacePath || null;
-        const needsHydration = !serverWorkspacePath && !!localWorkspacePath;
+        const needsHydration = !clientToolExecution && !serverWorkspacePath && !!localWorkspacePath;
         const agentTaskType = resolvedContext.agentTaskType || 'general';
         const rawPrompt = resolvedContext.rawPrompt || resolvedContext.prompt || '';
         const executionHints = (resolvedContext.executionHints && typeof resolvedContext.executionHints === 'object')
@@ -960,15 +973,13 @@ export class APIClient {
             projectPath: effectiveWorkspacePath,
             targetPath: effectiveWorkspacePath,
             // Never send a client-local absolute path to the V3 model boundary.
-            // The server only needs a stable label; file contents are carried by
-            // localWorkspaceSummary.workspaceFiles and hydrated into a temp workspace.
+            // The server only receives a stable label. Local bridge runs retrieve
+            // file contents on demand through authenticated client tool requests.
             localWorkspacePath: serverWorkspacePath ? serverWorkspacePath : localWorkspaceRef,
             localWorkspaceRef,
             localWorkspaceName,
             localWorkspaceSummary,
-            // Signal to the server that the workspace filesystem is not locally
-            // accessible — it must hydrate a temp directory from the provided
-            // workspaceFiles before the agent starts using tools.
+            // This is true only for explicit server-owned/background execution.
             workspaceHydrationRequired: needsHydration,
             contextId: resolvedContext.contextId,
             traceId: resolvedContext.traceId,
@@ -1895,7 +1906,7 @@ menu {
             cwd: serverBindableWorkspace ? paths.serverWorkspacePath || null : (localName ? `vigthoria://local-workspace/${localName}` : null),
         };
     }
-    buildLocalWorkspaceSummary(rootPath, requestFocus = '') {
+    buildLocalWorkspaceSummary(rootPath, requestFocus = '', includeWorkspaceFiles = true) {
         if (!rootPath || !fs.existsSync(rootPath)) {
             return null;
         }
@@ -1981,9 +1992,12 @@ menu {
             if (fs.existsSync(readmePath)) {
                 summary.readmeExcerpt = fs.readFileSync(readmePath, 'utf8').slice(0, 2500);
             }
-            // Hydrate workspace: include actual file contents so the V3 server
-            // can populate the remote workspace before the agent starts.
-            summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, orderedPaths);
+            if (includeWorkspaceFiles) {
+                // Explicit server-owned/background execution may hydrate a bounded
+                // copy. Interactive CLI/Workbench runs retrieve files on demand via
+                // the local tool bridge and never upload a workspace mirror.
+                summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, orderedPaths);
+            }
             return summary;
         }
         catch (error) {
@@ -1999,7 +2013,15 @@ menu {
         const resolvedContext = this.ensureExecutionContext(context);
         const localWorkspacePath = this.resolveAgentTargetPath(resolvedContext);
         const serverWorkspacePath = this.resolveServerBindableWorkspacePath(resolvedContext);
-        if (serverWorkspacePath || !localWorkspacePath)
+        const executionSurface = String(resolvedContext.executionSurface || resolvedContext.clientSurface || 'cli');
+        const localMachineCapable = resolvedContext.localMachineCapable !== false;
+        const clientToolExecution = resolvedContext.clientToolExecution === false
+            ? false
+            : (resolvedContext.clientToolExecution === true
+                || (!serverWorkspacePath
+                    && localMachineCapable
+                    && ['cli', 'fork', 'local-ide', 'desktop', 'local'].includes(executionSurface)));
+        if (clientToolExecution || serverWorkspacePath || !localWorkspacePath)
             return undefined;
         const promptFocus = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || resolvedContext.prompt || '');
         const summary = this.buildLocalWorkspaceSummary(localWorkspacePath, promptFocus);
@@ -2034,6 +2056,29 @@ menu {
     resolveV3ClientToolPath(rootPath, rawPath, sourceRoots = []) {
         return this.v3WorkspaceService.resolveClientToolPath(rootPath, rawPath, sourceRoots);
     }
+    describeMissingV3ClientToolPath(rootPath, relativePath) {
+        const normalized = String(relativePath || '').replace(/\\/g, '/');
+        const requestedDirectory = path.posix.dirname(normalized);
+        const requestedExtension = path.posix.extname(normalized).toLowerCase();
+        let candidates = [];
+        try {
+            const paths = this.getAgentWorkspaceSnapshot(rootPath).paths;
+            const sameDirectory = paths.filter((entry) => path.posix.dirname(entry) === requestedDirectory);
+            const sameExtension = paths.filter((entry) => (requestedExtension && path.posix.extname(entry).toLowerCase() === requestedExtension));
+            candidates = Array.from(new Set([
+                ...sameDirectory,
+                ...sameExtension,
+                ...paths,
+            ])).slice(0, 16);
+        }
+        catch {
+            // The primary not-found error remains actionable even if inventory fails.
+        }
+        const inventory = candidates.length > 0
+            ? ` Existing workspace files include: ${candidates.join(', ')}.`
+            : '';
+        return `File not found in the local workspace: ${normalized}.${inventory} Use list_directory or glob and retry with an existing workspace-relative path.`;
+    }
     recordV3ClientToolMutation(event, context, result) {
         if (!result.success) {
             return;
@@ -2068,6 +2113,23 @@ menu {
             }
         }
     }
+    buildV3ClientToolMutation(relativePath, content) {
+        if (isSensitivePath(relativePath)) {
+            return { error: 'Sensitive paths cannot be synchronized to the Agent service.' };
+        }
+        const byteLength = Buffer.byteLength(content, 'utf8');
+        if (byteLength > MAX_V3_CLIENT_MUTATION_BYTES) {
+            return { error: `Client mutation exceeds the ${MAX_V3_CLIENT_MUTATION_BYTES}-byte synchronization limit.` };
+        }
+        if (containsHighConfidenceSecret(content)) {
+            return { error: 'Client mutation contains credential-like material and was not synchronized.' };
+        }
+        return {
+            path: relativePath,
+            content,
+            sha256: createHash('sha256').update(content, 'utf8').digest('hex'),
+        };
+    }
     async executeV3ClientToolRequest(event, context = {}) {
         const rootPath = this.resolveAgentTargetPath(context);
         if (!rootPath) {
@@ -2087,13 +2149,121 @@ menu {
         if (!target) {
             return { success: false, output: '', error: 'Tool path is outside the workspace.' };
         }
+        const existingPathTools = new Set([
+            'read_file', 'edit_file', 'list_directory', 'glob', 'search_files', 'grep',
+            'syntax_check', 'preview_check', 'runtime_check',
+        ]);
+        if (existingPathTools.has(name) && !fs.existsSync(target.absolutePath)) {
+            return {
+                success: false,
+                output: '',
+                error: this.describeMissingV3ClientToolPath(rootPath, target.relativePath),
+            };
+        }
         try {
+            if (name === 'preview_check') {
+                const entryPath = fs.statSync(target.absolutePath).isDirectory()
+                    ? path.join(target.absolutePath, 'index.html')
+                    : target.absolutePath;
+                if (!fs.existsSync(entryPath) || !fs.statSync(entryPath).isFile()) {
+                    return { success: false, output: '', error: 'Preview entry file not found.' };
+                }
+                const htmlBytes = fs.statSync(entryPath).size;
+                if (htmlBytes > 2 * 1024 * 1024) {
+                    return { success: false, output: '', error: 'Preview entry exceeds the 2 MiB local validation limit.' };
+                }
+                const html = fs.readFileSync(entryPath, 'utf8');
+                const expectedText = String(args.expect_text || '').trim();
+                if (expectedText && !html.includes(expectedText)) {
+                    return { success: false, output: '', error: `Expected text was not found in ${path.basename(entryPath)}.` };
+                }
+                const missingAssets = [];
+                const checkedAssets = [];
+                const assetPattern = /<(?:script|link|img|source|video|audio)\b[^>]+(?:src|href)=["']([^"']+)["']/gi;
+                let match;
+                while ((match = assetPattern.exec(html)) !== null && checkedAssets.length < 200) {
+                    const rawAsset = String(match[1] || '').trim();
+                    if (!rawAsset || /^(?:https?:|data:|blob:|mailto:|tel:|javascript:|#)/i.test(rawAsset))
+                        continue;
+                    let decoded;
+                    try {
+                        decoded = decodeURIComponent(rawAsset.split(/[?#]/, 1)[0]);
+                    }
+                    catch {
+                        return { success: false, output: '', error: 'Preview contains a malformed local asset URL.' };
+                    }
+                    const entryRelative = path.relative(rootPath, entryPath).replace(/\\/g, '/');
+                    const entryDirectory = path.posix.dirname(entryRelative);
+                    const assetRelative = decoded.startsWith('/')
+                        ? decoded.replace(/^\/+/, '')
+                        : path.posix.normalize(path.posix.join(entryDirectory, decoded));
+                    let assetAbsolute;
+                    try {
+                        assetAbsolute = resolveWorkspacePath(rootPath, assetRelative);
+                    }
+                    catch {
+                        return { success: false, output: '', error: 'Preview asset path escapes the local workspace.' };
+                    }
+                    checkedAssets.push(assetRelative);
+                    if (!fs.existsSync(assetAbsolute) || !fs.statSync(assetAbsolute).isFile())
+                        missingAssets.push(assetRelative);
+                }
+                if (missingAssets.length > 0) {
+                    return {
+                        success: false,
+                        output: '',
+                        error: `Missing local preview assets: ${missingAssets.slice(0, 12).join(', ')}`,
+                    };
+                }
+                return {
+                    success: true,
+                    output: JSON.stringify({
+                        entry: path.relative(rootPath, entryPath).replace(/\\/g, '/'),
+                        checkedAssets: checkedAssets.length,
+                        expectedTextMatched: Boolean(expectedText),
+                    }),
+                };
+            }
+            if (name === 'runtime_check') {
+                const previewResult = await this.executeV3ClientToolRequest({ ...event, name: 'preview_check', arguments: args }, context);
+                if (!previewResult.success)
+                    return previewResult;
+                const relativeTarget = target.relativePath && target.relativePath !== '.' ? target.relativePath : 'index.html';
+                const gate = await this.frontendPreviewService.runTemplateServicePreviewGate(`Verify the interactive frontend runtime at ${relativeTarget}.`, {
+                    ...context,
+                    targetPath: rootPath,
+                    workspacePath: rootPath,
+                    projectPath: rootPath,
+                    rawPrompt: `Verify the interactive frontend runtime at ${relativeTarget}.`,
+                    forceFrontendPreview: true,
+                    localScreenshotProof: true,
+                    requireScreenshot: true,
+                });
+                if (!gate.passed || gate.artifacts?.screenshotCaptured !== true) {
+                    return {
+                        success: false,
+                        output: '',
+                        error: gate.error || gate.artifacts?.screenshotError || 'Local browser runtime proof failed closed.',
+                    };
+                }
+                return {
+                    success: true,
+                    output: JSON.stringify({
+                        entry: gate.entryPath || relativeTarget,
+                        screenshotCaptured: true,
+                        proof: 'local-system-browser',
+                    }),
+                };
+            }
             if (name === 'write_file') {
                 if (typeof args.content !== 'string')
                     return { success: false, output: '', error: 'write_file requires string content.' };
+                const mutation = this.buildV3ClientToolMutation(target.relativePath, args.content);
+                if ('error' in mutation)
+                    return { success: false, output: '', error: mutation.error };
                 fs.mkdirSync(path.dirname(target.absolutePath), { recursive: true });
                 fs.writeFileSync(target.absolutePath, args.content, 'utf8');
-                const result = { success: true, output: `Updated ${target.relativePath}` };
+                const result = { success: true, output: `Updated ${target.relativePath}`, mutation };
                 this.recordV3ClientToolMutation(event, context, result);
                 return result;
             }
@@ -2104,10 +2274,31 @@ menu {
                     return { success: false, output: '', error: 'edit_file requires old_string.' };
                 const existing = fs.readFileSync(target.absolutePath, 'utf8');
                 const count = existing.split(oldString).length - 1;
-                if (count !== 1)
-                    return { success: false, output: '', error: `old_string found ${count} times; expected exactly once.` };
-                fs.writeFileSync(target.absolutePath, existing.replace(oldString, newString), 'utf8');
-                const result = { success: true, output: `Edited ${target.relativePath}` };
+                const replaceAll = args.replace_all === true;
+                if ((!replaceAll && count !== 1) || (replaceAll && count < 1)) {
+                    return {
+                        success: false,
+                        output: '',
+                        error: replaceAll
+                            ? `old_string found ${count} times; expected at least once.`
+                            : `old_string found ${count} times; expected exactly once.`,
+                    };
+                }
+                if (replaceAll && (oldString.includes('\n') || newString.includes('\n') || oldString.length > 120 || count > 1000)) {
+                    return {
+                        success: false,
+                        output: '',
+                        error: 'replace_all is restricted to short, single-line token migrations with at most 1000 matches.',
+                    };
+                }
+                const nextContent = replaceAll
+                    ? existing.split(oldString).join(newString)
+                    : existing.replace(oldString, newString);
+                const mutation = this.buildV3ClientToolMutation(target.relativePath, nextContent);
+                if ('error' in mutation)
+                    return { success: false, output: '', error: mutation.error };
+                fs.writeFileSync(target.absolutePath, nextContent, 'utf8');
+                const result = { success: true, output: `Edited ${target.relativePath}`, mutation };
                 this.recordV3ClientToolMutation(event, context, result);
                 return result;
             }
@@ -2357,6 +2548,19 @@ menu {
     normalizeAgentWorkspaceRelativePath(rawPath, rootPath) {
         return this.v3WorkspaceService.normalizeRelativePath(rawPath, rootPath);
     }
+    isExplicitSingleFileFrontendRequest(prompt, expectedFiles, rootPath) {
+        const normalizedFiles = Array.from(new Set(expectedFiles
+            .map((filePath) => this.normalizeAgentWorkspaceRelativePath(filePath, rootPath))
+            .filter((filePath) => /\.html?$/i.test(filePath))));
+        if (normalizedFiles.length !== 1) {
+            return false;
+        }
+        const request = String(prompt || '').toLowerCase();
+        const explicitOneFileLanguage = /\b(?:single|one)[ -]?file\b/i.test(request)
+            || /\b(?:in\s+)?(?:exactly|only)\s+[`'\"]?[a-z0-9_./-]+\.html?\b/i.test(request)
+            || /\b[a-z0-9_./-]+\.html?\b[^.\n]{0,100}\b(?:only|alone)\b/i.test(request);
+        return explicitOneFileLanguage;
+    }
     async ensureAgentFrontendPolish(message = '', context = {}) {
         const rootPath = this.resolveAgentTargetPath(context);
         if (!rootPath || !fs.existsSync(rootPath)) {
@@ -2364,16 +2568,66 @@ menu {
         }
         const prompt = String(message || '');
         const expectedFiles = this.extractExpectedWorkspaceFiles(message, context);
-        const looksLikeFrontendTask = /(premium|polished|landing|site|page|dashboard|saas|frontend|ui|pricing|showcase)/i.test(prompt)
+        const looksLikeFrontendTask = /(premium|polished|landing|site|page|dashboard|saas|frontend|ui|pricing|showcase|responsive|interactive|game|canvas)/i.test(prompt)
             || expectedFiles.some((filePath) => /\.(html|css|js)$/i.test(filePath));
         if (!looksLikeFrontendTask) {
             return;
         }
-        const htmlPath = path.join(rootPath, 'index.html');
-        if (!fs.existsSync(htmlPath)) {
+        const expectedHtmlPaths = expectedFiles
+            .map((filePath) => this.normalizeAgentWorkspaceRelativePath(filePath, rootPath))
+            .filter((filePath) => /\.html?$/i.test(filePath));
+        const selectedHtmlRelativePath = [
+            ...expectedHtmlPaths,
+            'index.html',
+        ].find((filePath) => {
+            try {
+                return Boolean(filePath) && fs.existsSync(resolveWorkspacePath(rootPath, filePath));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!selectedHtmlRelativePath) {
+            return;
+        }
+        const htmlPath = resolveWorkspacePath(rootPath, selectedHtmlRelativePath);
+        let html = fs.readFileSync(htmlPath, 'utf8');
+        // The Template Service correctly fails motion-bearing frontend artifacts
+        // without a reduced-motion path.  V3 may produce a valid single-file app
+        // whose only motion is inline CSS, so enforce this small accessibility
+        // contract on the actual requested HTML entry before preview validation.
+        // This remains inside the surrounding mutation journal and is rolled back
+        // with every other client-side mutation when preview later fails.
+        const usesMotion = /@keyframes|\banimation(?:-name)?\s*:|\btransition(?:-property)?\s*:/i.test(html);
+        if (usesMotion && !/prefers-reduced-motion/i.test(html)) {
+            const reducedMotionCss = `
+
+@media (prefers-reduced-motion: reduce) {
+    html { scroll-behavior: auto !important; }
+    *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+    }
+}`;
+            if (/<\/style>/i.test(html)) {
+                html = html.replace(/<\/style>/i, `${reducedMotionCss}\n</style>`);
+            }
+            else if (/<\/head>/i.test(html)) {
+                html = html.replace(/<\/head>/i, `<style>${reducedMotionCss}\n</style>\n</head>`);
+            }
+            fs.writeFileSync(htmlPath, html, 'utf8');
+        }
+        if (isConstrainedStaticFrontendRequest(prompt)
+            || this.isExplicitSingleFileFrontendRequest(prompt, expectedFiles, rootPath)) {
+            return;
+        }
+        // The broader legacy polish recovery owns only the conventional root
+        // index entry.  Arbitrary explicitly named applications retain their
+        // architecture; only the accessibility contract above is normalized.
+        if (selectedHtmlRelativePath !== 'index.html') {
             return;
         }
-        const html = fs.readFileSync(htmlPath, 'utf8');
         const ensuredAssets = this.ensureReferencedFrontendAssets(rootPath, html, prompt, 'Vigthoria CLI');
         const cssPath = ensuredAssets.cssPath;
         const jsPath = ensuredAssets.jsPath;
@@ -2383,6 +2637,24 @@ menu {
         }
         let css = fs.readFileSync(cssPath, 'utf8');
         let js = fs.existsSync(jsPath) ? fs.readFileSync(jsPath, 'utf8') : '';
+        // Production preview evaluates the linked stylesheet as part of the final
+        // artifact.  The earlier inline-only guard cannot see animation and
+        // transition rules that live in that stylesheet, which allowed the Agent's
+        // client-side runtime check to pass and the final Template Service gate to
+        // reject the same workspace.  Normalize the two deterministic production
+        // contracts before any of the legacy early-return paths below.
+        const linkedFrontend = `${html}\n${css}`;
+        if (!/\*\s*,\s*\*::before\s*,\s*\*::after\s*\{[^}]*box-sizing\s*:\s*border-box/i.test(linkedFrontend)) {
+            css = `*, *::before, *::after {\n    box-sizing: border-box;\n}\n\n${css}`;
+        }
+        const linkedFrontendWithReset = `${html}\n${css}`;
+        const linkedStylesUseMotion = /@keyframes|\banimation(?:-name)?\s*:|\btransition(?:-property)?\s*:/i.test(linkedFrontendWithReset);
+        if (linkedStylesUseMotion && !/prefers-reduced-motion/i.test(linkedFrontendWithReset)) {
+            css = `${css.trimEnd()}\n\n/* Vigthoria CLI Reduced Motion Baseline */\n@media (prefers-reduced-motion: reduce) {\n    html { scroll-behavior: auto !important; }\n    *, *::before, *::after {\n        animation-duration: 0.01ms !important;\n        animation-iteration-count: 1 !important;\n        transition-duration: 0.01ms !important;\n    }\n}\n`;
+        }
+        if (css !== fs.readFileSync(cssPath, 'utf8')) {
+            fs.writeFileSync(cssPath, `${css.trimEnd()}\n`, 'utf8');
+        }
         const keyframesBlocks = Array.from(js.matchAll(/@keyframes[\s\S]*?\n\}/g)).map((match) => match[0]);
         if (keyframesBlocks.length > 0) {
             const migrated = keyframesBlocks.filter((block) => !css.includes(block));
@@ -2460,7 +2732,15 @@ menu {
         const cssMarker = '/* Vigthoria CLI Motion Enhancement */';
         const jsMarker = '/* Vigthoria CLI Motion Enhancement */';
         if (!css.includes(cssMarker)) {
-            fs.appendFileSync(cssPath, `\n\n${cssMarker}\n.hero, section {\n    opacity: 0;\n    transform: translateY(24px);\n    animation: vigCliFadeIn 0.8s ease forwards;\n}\n\nsection {\n    animation-delay: 0.12s;\n}\n\nbutton, .cta, a {\n    transition: transform 0.25s ease, opacity 0.25s ease;\n}\n\nbutton:hover, .cta:hover, a:hover {\n    transform: translateY(-2px);\n}\n\n.motion-reveal {\n    opacity: 0;\n    transform: translateY(24px);\n    transition: opacity 0.7s ease, transform 0.7s ease;\n}\n\n.motion-reveal.is-visible {\n    opacity: 1;\n    transform: translateY(0);\n}\n\n@keyframes vigCliFadeIn {\n    from {\n        opacity: 0;\n        transform: translateY(24px);\n    }\n    to {\n        opacity: 1;\n        transform: translateY(0);\n    }\n}\n`, 'utf8');
+            // This enhancement introduces motion after the earlier linked-asset
+            // normalization pass.  Add the accessibility counterpart in the same
+            // atomic append so the final Template Service gate never observes
+            // CLI-created animation without a reduced-motion contract.
+            const currentCss = fs.readFileSync(cssPath, 'utf8');
+            const reducedMotionBaseline = /prefers-reduced-motion/i.test(currentCss)
+                ? ''
+                : `\n\n/* Vigthoria CLI Reduced Motion Baseline */\n@media (prefers-reduced-motion: reduce) {\n    html { scroll-behavior: auto !important; }\n    *, *::before, *::after {\n        animation-duration: 0.01ms !important;\n        animation-iteration-count: 1 !important;\n        transition-duration: 0.01ms !important;\n    }\n}`;
+            fs.appendFileSync(cssPath, `\n\n${cssMarker}\n.hero, section {\n    opacity: 0;\n    transform: translateY(24px);\n    animation: vigCliFadeIn 0.8s ease forwards;\n}\n\nsection {\n    animation-delay: 0.12s;\n}\n\nbutton, .cta, a {\n    transition: transform 0.25s ease, opacity 0.25s ease;\n}\n\nbutton:hover, .cta:hover, a:hover {\n    transform: translateY(-2px);\n}\n\n.motion-reveal {\n    opacity: 0;\n    transform: translateY(24px);\n    transition: opacity 0.7s ease, transform 0.7s ease;\n}\n\n.motion-reveal.is-visible {\n    opacity: 1;\n    transform: translateY(0);\n}\n\n@keyframes vigCliFadeIn {\n    from {\n        opacity: 0;\n        transform: translateY(24px);\n    }\n    to {\n        opacity: 1;\n        transform: translateY(0);\n    }\n}${reducedMotionBaseline}\n`, 'utf8');
         }
         if (!js.includes(jsMarker)) {
             fs.appendFileSync(jsPath, `\n\n${jsMarker}\ndocument.addEventListener('DOMContentLoaded', () => {\n    const revealTargets = document.querySelectorAll('section, .hero, .project-grid > *, .journal-preview > *');\n    if (typeof IntersectionObserver !== 'function') {\n        revealTargets.forEach((element) => element.classList.add('is-visible'));\n        return;\n    }\n\n    const observer = new IntersectionObserver((entries) => {\n        entries.forEach((entry) => {\n            if (entry.isIntersecting) {\n                entry.target.classList.add('is-visible');\n                observer.unobserve(entry.target);\n            }\n        });\n    }, { threshold: 0.16 });\n\n    revealTargets.forEach((element, index) => {\n        element.classList.add('motion-reveal');\n        element.style.transitionDelay = String(Math.min(index * 60, 320)) + 'ms';\n        observer.observe(element);\n    });\n});\n`, 'utf8');
@@ -3109,6 +3389,7 @@ document.addEventListener('DOMContentLoaded', () => {
                     if (explicitEventType && (!event.type || event.type === 'message')) {
                         event.type = explicitEventType;
                     }
+                    assertValidAgentPlanEvent(event);
                     const userEvent = this.sanitizeV3AgentEventForUser(event);
                     events.push(userEvent);
                     if (!contextId && typeof event.context_id === 'string' && event.context_id.trim()) {
@@ -3360,12 +3641,15 @@ document.addEventListener('DOMContentLoaded', () => {
                             // A pre-existing local project is not proof that this run produced
                             // valid output. A terminal planner/executor error fails proof and
                             // causes the operation journal to roll back streamed mutations.
-                            const failedPreviewGate = {
-                                required: true,
-                                passed: false,
-                                skipped: true,
-                                error: 'Agent execution failed before preview validation.',
-                            };
+                            const analysisOnly = this.isAnalysisOnlyTask(message, executionContext);
+                            const failedPreviewGate = analysisOnly
+                                ? { required: false, passed: true, skipped: false }
+                                : {
+                                    required: true,
+                                    passed: false,
+                                    skipped: true,
+                                    error: 'Agent execution failed before preview validation.',
+                                };
                             return this.finalizeV3AgentWorkflowResponse(data, {
                                 content: '',
                                 taskId: data.task_id || null,
@@ -3394,6 +3678,23 @@ document.addEventListener('DOMContentLoaded', () => {
                         }, mutationJournal);
                     }
                     catch (error) {
+                        if (error?.code === 'AGENT_PLAN_INVALID') {
+                            if (mutationJournal?.hasMutations()) {
+                                const mutation = mutationJournal.rollback();
+                                mutationJournal = null;
+                                error.operationId = mutation.operationId;
+                                error.mutation = mutation;
+                                error.partialMutation = mutation.partialMutation;
+                            }
+                            else {
+                                error.partialMutation = false;
+                            }
+                            this.activeV3StreamedFiles = null;
+                            // A malformed graph is deterministic and backend-independent.
+                            // Never retry it against another service or erase its typed code
+                            // while folding endpoint diagnostics into a string.
+                            throw error;
+                        }
                         if (error && error.name === 'AbortError' && error.partialData && this.hasAgentWorkspaceOutput(executionContext)) {
                             this.recoverAgentWorkspaceFiles(executionContext, error.partialData.files || {}, expectedFiles);
                             await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
@@ -3606,14 +3907,50 @@ document.addEventListener('DOMContentLoaded', () => {
             ? requestedOperatorTimeoutMs
             : 0;
         const workspacePath = executionContext.workspacePath || executionContext.projectPath || executionContext.targetPath || process.cwd();
-        const workspaceSummary = this.buildLocalWorkspaceSummary(workspacePath);
+        const serverWorkspacePath = this.resolveServerBindableWorkspacePath(executionContext);
+        const clientWorkspaceAuthoritative = Boolean(workspacePath
+            && !serverWorkspacePath
+            && executionContext.localMachineCapable !== false);
+        let workspaceSummary = this.buildLocalWorkspaceSummary(workspacePath, message, !clientWorkspaceAuthoritative);
         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({
+            let groundedAnalysis = null;
+            let operatorExecutionContext = executionContext;
+            if (clientWorkspaceAuthoritative) {
+                groundedAnalysis = await this.runV3AgentWorkflow([
+                    'Inspect the client workspace through the authenticated local tool bridge.',
+                    'Produce a grounded, read-only technical report for the BMAD Operator.',
+                    'Do not modify files. Identify relevant files, constraints, risks, and exact evidence for this request:',
+                    message,
+                ].join('\n'), {
+                    ...executionContext,
+                    rawPrompt: message,
+                    contextualPrompt: message,
+                    agentTaskType: 'analysis',
+                    workflowType: 'analysis_only',
+                    clientToolExecution: true,
+                    localMachineCapable: true,
+                });
+                const groundingReport = String(groundedAnalysis.content || '').trim();
+                if (!groundingReport || groundedAnalysis.partial === true) {
+                    throw new CLIError('Operator could not obtain a complete grounded report from the client workspace bridge.', 'model_backend');
+                }
+                workspaceSummary = workspaceSummary || { name: path.basename(workspacePath), files: [] };
+                workspaceSummary.workspaceAuthority = 'client-tool-bridge';
+                workspaceSummary.groundedBy = 'v3-client-tools';
+                delete workspaceSummary.workspaceFiles;
+                operatorExecutionContext = {
+                    ...executionContext,
+                    workspaceAuthority: 'client-tool-bridge',
+                    clientGroundingReport: groundingReport.slice(0, 64 * 1024),
+                    workflowType: executionContext.workflowType === 'full' ? 'planning_only' : executionContext.workflowType,
+                };
+            }
+            const operatorResult = await this.operatorClient.run({
                 message,
-                executionContext,
+                executionContext: operatorExecutionContext,
                 workspaceAlias: operatorWorkspaceAlias,
                 workspaceSummary,
                 requestedModel,
@@ -3621,6 +3958,54 @@ document.addEventListener('DOMContentLoaded', () => {
                 timeoutMs,
                 onStreamEvent: typeof context.onStreamEvent === 'function' ? context.onStreamEvent : undefined,
             });
+            if (!clientWorkspaceAuthoritative || executionContext.workflowType !== 'full') {
+                return {
+                    ...operatorResult,
+                    metadata: {
+                        ...(operatorResult.metadata || {}),
+                        ...(clientWorkspaceAuthoritative ? {
+                            workspaceAuthority: 'client-tool-bridge',
+                            groundingTaskId: groundedAnalysis?.taskId || null,
+                        } : {}),
+                    },
+                };
+            }
+            const plan = String(operatorResult.content || '').trim();
+            if (!plan) {
+                throw new CLIError('BMAD Operator returned no governed implementation plan.', 'model_backend');
+            }
+            const implementation = await this.runV3AgentWorkflow([
+                message,
+                '',
+                'Execute this governed BMAD plan against the authoritative client workspace using client tools:',
+                plan.slice(0, 64 * 1024),
+            ].join('\n'), {
+                ...executionContext,
+                rawPrompt: message,
+                contextualPrompt: message,
+                workflowType: 'full',
+                clientToolExecution: true,
+                localMachineCapable: true,
+            });
+            if (implementation.partial === true) {
+                throw new CLIError('Local implementation ended partially and was not reported as Operator success.', 'model_backend');
+            }
+            return {
+                content: implementation.content,
+                workflowId: operatorResult.workflowId,
+                contextId: implementation.contextId || operatorResult.contextId,
+                backendUrl: operatorResult.backendUrl,
+                savedWorkflow: operatorResult.savedWorkflow,
+                changedFiles: implementation.changedFiles,
+                metadata: {
+                    ...(operatorResult.metadata || {}),
+                    workspaceAuthority: 'client-tool-bridge',
+                    groundingTaskId: groundedAnalysis?.taskId || null,
+                    implementationTaskId: implementation.taskId,
+                    implementationBackendUrl: implementation.backendUrl,
+                    bmadPlan: true,
+                },
+            };
         }
         catch (error) {
             if (error instanceof OperatorClientError) {
@@ -3746,6 +4131,7 @@ document.addEventListener('DOMContentLoaded', () => {
             success: result.success === true,
             output: String(result.output || ''),
             error: String(result.error || ''),
+            mutation: result.mutation || null,
         });
         for (let attempt = 0; attempt < 3; attempt += 1) {
             const response = await this.fetch(endpoint, {