@nexus-ai-nexoralabs/cli 0.1.3 → 0.1.4

package/dist/preview/previewService.d.ts

@@ -6,27 +6,56 @@
  * safe browser launching.
  */
 import type { AgentTaskRepository } from '../storage/repositories/agentTaskRepository.js';
+import type { TaskArtifactRepository } from '../storage/repositories/taskArtifactRepository.js';
 import type { AgentTask } from '../storage/repositories/types.js';
 import type { PreviewResult, PreviewStatus, DiscoveredArtifacts } from './previewTypes.js';
 export declare class PreviewService {
     private taskRepo;
     private workspaceRoot;
+    private artifactRepo?;
     private server;
     private logger;
     private activeTask;
-    constructor(taskRepo: AgentTaskRepository, workspaceRoot: string, logLevel?: import('../common/logger.js').LogLevel);
+    constructor(taskRepo: AgentTaskRepository, workspaceRoot: string, logLevel?: import('../common/logger.js').LogLevel, artifactRepo?: TaskArtifactRepository | undefined);
+    setArtifactRepository(artifactRepo: TaskArtifactRepository): void;
+    /**
+     * Resolve target task based on explicit index (number), task ID (string), or latest task (undefined).
+     *
+     * 1. No argument: targets the latest task across ALL states in the task repository.
+     * 2. Number / Numeric string (e.g. 2, "2", "#2"): targets the N-th task (1-indexed) from deterministic task history.
+     * 3. Task ID string: targets the specific task by its unique ID.
+     */
+    resolveTargetTask(target?: string | number): {
+        task: AgentTask | null;
+        targetType: 'latest' | 'index' | 'id';
+        targetIndex?: number;
+        error?: string;
+    };
     /**
      * Resolve latest completed task or specific task by ID.
+     * Maintained for backwards compatibility.
      */
     resolveCompletedTask(taskId?: string): AgentTask | null;
     /**
      * Discover files and project entry point created by a completed task.
+     *
+     * PRIORITY 1: Task's persisted artifact record in SQLite (TaskArtifactRepository).
+     * PRIORITY 2: Task-scoped plan steps (legacy tasks only).
+     * PRIORITY 3: FAIL SAFELY. Never fall back to arbitrary workspace scanning, mtime, or other tasks.
      */
     discoverArtifacts(task: AgentTask): DiscoveredArtifacts;
     /**
-     * Launch preview for latest completed task or specified task ID.
+     * Launch preview for latest task, specific task number (#N), or specified task ID.
+     *
+     * STRICT SEMANTICS:
+     * 1. If no target is given, resolves the user's latest task.
+     * 2. If target is numeric (e.g. 2, "2", "#2"), resolves task #N from /tasks list.
+     * 3. If target is string, resolves task by ID.
+     * 4. If target task is FAILED -> returns status TASK_FAILED with reason, blocks preview, NO FALLBACK.
+     * 5. If target task is INCOMPLETE -> returns status TASK_INCOMPLETE, blocks preview, NO FALLBACK.
+     * 6. If target task is COMPLETED -> verifies artifact for THAT task, then launches preview.
      */
-    preview(taskId?: string): Promise<PreviewResult>;
+    preview(target?: string | number): Promise<PreviewResult>;
     /**
      * Stop active preview server.
      */

package/dist/preview/previewService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"previewService.d.ts","sourceRoot":"","sources":["../../src/preview/previewService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAC1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAGlE,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAG3B,qBAAa,cAAc;IAMvB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;IANvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAA0B;gBAGlC,QAAQ,EAAE,mBAAmB,EAC7B,aAAa,EAAE,MAAM,EAC7B,QAAQ,GAAE,OAAO,qBAAqB,EAAE,QAAiB;IAM3D;;OAEG;IACH,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAyBvD;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB;IA6JvD;;OAEG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAgFtD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IAoBpC;;OAEG;IACH,SAAS,IAAI,aAAa;IAc1B;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAiCjD"}
+{"version":3,"file":"previewService.d.ts","sourceRoot":"","sources":["../../src/preview/previewService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAC1F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mDAAmD,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAElE,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAW3B,qBAAa,cAAc;IAMvB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;IAErB,OAAO,CAAC,YAAY,CAAC;IARvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAA0B;gBAGlC,QAAQ,EAAE,mBAAmB,EAC7B,aAAa,EAAE,MAAM,EAC7B,QAAQ,GAAE,OAAO,qBAAqB,EAAE,QAAiB,EACjD,YAAY,CAAC,EAAE,sBAAsB,YAAA;IAM/C,qBAAqB,CAAC,YAAY,EAAE,sBAAsB,GAAG,IAAI;IAIjE;;;;;;OAMG;IACH,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG;QAC3C,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;QACvB,UAAU,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;QACtC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAwDD;;;OAGG;IACH,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAQvD;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB;IAmTvD;;;;;;;;;;OAUG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAoI/D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IAoBpC;;OAEG;IACH,SAAS,IAAI,aAAa;IAc1B;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAqCjD"}

package/dist/preview/previewService.js

@@ -9,139 +9,344 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execFile } from 'child_process';
 import { PreviewServer } from './previewServer.js';
+import { verifyHtmlContentSubstance } from '../orchestration/placeholderDetector.js';
 import { Logger } from '../common/logger.js';
+function isSubpathOrEqual(parentDir, childPath) {
+    const isWin = process.platform === 'win32';
+    const p = isWin ? parentDir.toLowerCase() : parentDir;
+    const c = isWin ? childPath.toLowerCase() : childPath;
+    return c === p || c.startsWith(p + (isWin ? '\\' : '/')) || c.startsWith(p + path.sep);
+}
 export class PreviewService {
     taskRepo;
     workspaceRoot;
+    artifactRepo;
     server;
     logger;
     activeTask = null;
-    constructor(taskRepo, workspaceRoot, logLevel = 'info') {
+    constructor(taskRepo, workspaceRoot, logLevel = 'info', artifactRepo) {
         this.taskRepo = taskRepo;
         this.workspaceRoot = workspaceRoot;
+        this.artifactRepo = artifactRepo;
         this.logger = new Logger('PreviewService', logLevel);
         this.server = new PreviewServer(logLevel);
     }
+    setArtifactRepository(artifactRepo) {
+        this.artifactRepo = artifactRepo;
+    }
     /**
-     * Resolve latest completed task or specific task by ID.
+     * Resolve target task based on explicit index (number), task ID (string), or latest task (undefined).
+     *
+     * 1. No argument: targets the latest task across ALL states in the task repository.
+     * 2. Number / Numeric string (e.g. 2, "2", "#2"): targets the N-th task (1-indexed) from deterministic task history.
+     * 3. Task ID string: targets the specific task by its unique ID.
      */
-    resolveCompletedTask(taskId) {
-        if (taskId && taskId.trim()) {
-            const cleanId = taskId.trim();
-            const task = this.taskRepo.findById(cleanId);
-            if (task && task.state === 'completed') {
-                return task;
+    resolveTargetTask(target) {
+        const allTasks = this.taskRepo.listAll();
+        if (allTasks.length === 0) {
+            return {
+                task: null,
+                targetType: 'latest',
+                error: 'No tasks recorded yet.',
+            };
+        }
+        if (target === undefined || target === null || (typeof target === 'string' && target.trim() === '')) {
+            return {
+                task: allTasks[0],
+                targetType: 'latest',
+                targetIndex: 1,
+            };
+        }
+        const str = String(target).trim();
+        // Check if target is a numeric index (e.g. 1, 2, "1", "2", "#1", "#2")
+        if (/^#?\d+$/.test(str)) {
+            const idx = parseInt(str.replace(/^#/, ''), 10);
+            if (idx >= 1) {
+                if (idx > allTasks.length) {
+                    return {
+                        task: null,
+                        targetType: 'index',
+                        targetIndex: idx,
+                        error: `Task #${idx} does not exist. Available tasks: 1 to ${allTasks.length}. Run /tasks to view all tasks.`,
+                    };
+                }
+                return {
+                    task: allTasks[idx - 1],
+                    targetType: 'index',
+                    targetIndex: idx,
+                };
             }
-            return null;
         }
-        const completed = this.taskRepo.findByState('completed');
-        if (completed.length === 0) {
-            return null;
+        // Otherwise, treat as explicit taskId
+        const task = this.taskRepo.findById(str);
+        if (!task) {
+            return {
+                task: null,
+                targetType: 'id',
+                error: `Task with ID '${str}' not found.`,
+            };
         }
-        // Sort descending by completedAt or updatedAt or createdAt
-        completed.sort((a, b) => {
-            const tA = new Date(a.completedAt || a.updatedAt || a.createdAt).getTime();
-            const tB = new Date(b.completedAt || b.updatedAt || b.createdAt).getTime();
-            return tB - tA;
-        });
-        return completed[0];
+        return {
+            task,
+            targetType: 'id',
+        };
+    }
+    /**
+     * Resolve latest completed task or specific task by ID.
+     * Maintained for backwards compatibility.
+     */
+    resolveCompletedTask(taskId) {
+        const resolved = this.resolveTargetTask(taskId);
+        if (resolved.task && resolved.task.state === 'completed') {
+            return resolved.task;
+        }
+        return null;
     }
     /**
      * Discover files and project entry point created by a completed task.
+     *
+     * PRIORITY 1: Task's persisted artifact record in SQLite (TaskArtifactRepository).
+     * PRIORITY 2: Task-scoped plan steps (legacy tasks only).
+     * PRIORITY 3: FAIL SAFELY. Never fall back to arbitrary workspace scanning, mtime, or other tasks.
      */
     discoverArtifacts(task) {
         const canonicalWorkspace = fs.realpathSync(path.resolve(this.workspaceRoot));
-        const createdFiles = [];
-        // 1. Inspect task plan steps if present
-        if (task.plan) {
-            try {
-                const planObj = typeof task.plan === 'string' ? JSON.parse(task.plan) : task.plan;
-                if (Array.isArray(planObj.steps)) {
-                    for (const step of planObj.steps) {
-                        if ((step.toolId === 'filesystem_write' || step.toolId === 'filesystem_edit') &&
-                            step.params) {
-                            const rel = step.params.relativePath || step.params.path;
-                            if (rel && typeof rel === 'string') {
-                                createdFiles.push(rel);
+        // ── PRIORITY 1: Persisted Artifact Metadata from SQLite ────────────────────
+        if (this.artifactRepo) {
+            let persistedArtifact = this.artifactRepo.findByTaskId(task.id);
+            // If this is a parent task, check artifacts owned by its child tasks
+            if (!persistedArtifact) {
+                const childTasks = this.taskRepo.findByParentTaskId(task.id);
+                if (childTasks.length > 0) {
+                    const childArtifacts = childTasks
+                        .map((c) => this.artifactRepo.findByTaskId(c.id))
+                        .filter((a) => !!a);
+                    if (childArtifacts.length > 0) {
+                        const mergedFiles = Array.from(new Set(childArtifacts.flatMap((a) => a.files)));
+                        const primary = childArtifacts[childArtifacts.length - 1];
+                        persistedArtifact = {
+                            ...primary,
+                            id: `art-${task.id}`,
+                            taskId: task.id,
+                            files: mergedFiles,
+                        };
+                    }
+                }
+            }
+            // If this is a child task, check parent artifact
+            if (!persistedArtifact && task.parentTaskId) {
+                persistedArtifact = this.artifactRepo.findByTaskId(task.parentTaskId);
+            }
+            if (persistedArtifact) {
+                let canonicalProjectDir = persistedArtifact.projectRoot;
+                try {
+                    if (fs.existsSync(canonicalProjectDir)) {
+                        canonicalProjectDir = fs.realpathSync(canonicalProjectDir);
+                    }
+                }
+                catch {
+                    // keep path
+                }
+                const entryPath = path.join(canonicalProjectDir, persistedArtifact.entryPoint || 'index.html');
+                const entryExists = fs.existsSync(entryPath) && fs.statSync(entryPath).isFile();
+                if (entryExists) {
+                    // Scan project directory for associated web files
+                    const allProjectFiles = [];
+                    const scanDir = (currentDir, relPrefix) => {
+                        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+                        for (const entry of entries) {
+                            if (['node_modules', '.git', 'dist', 'build', '.nexus'].includes(entry.name))
+                                continue;
+                            const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+                            if (entry.isDirectory()) {
+                                scanDir(path.join(currentDir, entry.name), relPath);
+                            }
+                            else if (entry.isFile()) {
+                                allProjectFiles.push(relPath.replace(/\\/g, '/'));
                             }
                         }
+                    };
+                    try {
+                        scanDir(canonicalProjectDir, '');
+                    }
+                    catch {
+                        // ignore scan failure
                     }
+                    const uniqueFiles = Array.from(new Set([...persistedArtifact.files, ...allProjectFiles]));
+                    this.logger.info(`Resolved preview artifact from SQLite metadata for task '${task.id}'`, {
+                        projectDir: canonicalProjectDir,
+                        entryFile: persistedArtifact.entryPoint,
+                        fileCount: uniqueFiles.length,
+                    });
+                    return {
+                        projectDir: canonicalProjectDir,
+                        entryFile: persistedArtifact.entryPoint || 'index.html',
+                        files: uniqueFiles,
+                        hasIndexHtml: true,
+                        isWebProject: true,
+                    };
+                }
+                else {
+                    this.logger.warn(`Persisted artifact entry point missing on disk for task '${task.id}'`, { entryPath });
+                    return {
+                        projectDir: canonicalProjectDir,
+                        entryFile: persistedArtifact.entryPoint || 'index.html',
+                        files: [],
+                        hasIndexHtml: false,
+                        isWebProject: false,
+                    };
                 }
             }
+        }
+        // ── PRIORITY 2: Task-Scoped Plan Steps (Legacy Plan Fallback) ──────────────
+        const createdFiles = [];
+        const createdDirs = [];
+        const extractFromObj = (obj) => {
+            if (!obj || typeof obj !== 'object')
+                return;
+            for (const [key, value] of Object.entries(obj)) {
+                if (typeof value === 'string' && value.trim()) {
+                    const val = value.trim();
+                    const lowerKey = key.toLowerCase();
+                    if (lowerKey.includes('path') ||
+                        lowerKey.includes('file') ||
+                        lowerKey.includes('dir') ||
+                        lowerKey.includes('dest') ||
+                        lowerKey === 'target' ||
+                        val.endsWith('.html') ||
+                        val.endsWith('.css') ||
+                        val.endsWith('.js')) {
+                        if (val.endsWith('.html') || val.endsWith('.css') || val.endsWith('.js') || val.includes('/') || val.includes('\\')) {
+                            createdFiles.push(val);
+                        }
+                        else {
+                            createdDirs.push(val);
+                        }
+                    }
+                }
+                else if (typeof value === 'object' && value !== null) {
+                    extractFromObj(value);
+                }
+            }
+        };
+        if (task.plan) {
+            try {
+                const planObj = typeof task.plan === 'string' ? JSON.parse(task.plan) : task.plan;
+                extractFromObj(planObj);
+            }
             catch (err) {
                 this.logger.warn(`Failed to parse plan JSON for task '${task.id}'`, { error: String(err) });
             }
         }
-        // 2. Determine base directory candidate from created files
-        let projectDir = canonicalWorkspace;
-        let entryFile = 'index.html';
-        // Look for index.html among step file targets
-        const indexRel = createdFiles.find((f) => path.basename(f).toLowerCase() === 'index.html');
-        if (indexRel) {
-            const absIndex = path.resolve(canonicalWorkspace, indexRel);
-            projectDir = path.dirname(absIndex);
-            entryFile = path.basename(absIndex);
+        // Extract folder name from task title if explicit or matches existing subdirectories
+        try {
+            const wsEntries = fs.readdirSync(canonicalWorkspace, { withFileTypes: true });
+            const dirNames = wsEntries
+                .filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules')
+                .map((d) => d.name);
+            const folderMatch = task.title.match(/(?:folder|directory|project|called|named|create)\s+[`"']?([a-zA-Z0-9_\-]+)[`"']?/i);
+            if (folderMatch && folderMatch[1]) {
+                const candidate = folderMatch[1].trim();
+                if (dirNames.some((d) => d.toLowerCase() === candidate.toLowerCase())) {
+                    createdDirs.push(candidate);
+                }
+            }
+            const titleWords = task.title.toLowerCase().replace(/[^a-z0-9_\-\s]/g, ' ').split(/\s+/).filter((w) => w.length > 2 && w !== 'task' && w !== 'the');
+            for (const d of dirNames) {
+                const lowerName = d.toLowerCase();
+                if (titleWords.some((w) => lowerName.includes(w) || (w.length > 3 && w.includes(lowerName)))) {
+                    createdDirs.push(d);
+                }
+            }
+            // If task title mentions subdirectory/folder/app and exactly one subdirectory with index.html exists
+            if (createdDirs.length === 0 && /(?:subdirectory|folder|project|app|site|web)/i.test(task.title)) {
+                const subdirsWithIndex = dirNames.filter((d) => fs.existsSync(path.join(canonicalWorkspace, d, 'index.html')));
+                if (subdirsWithIndex.length === 1) {
+                    createdDirs.push(subdirsWithIndex[0]);
+                }
+            }
         }
-        else if (createdFiles.length > 0) {
-            const firstAbs = path.resolve(canonicalWorkspace, createdFiles[0]);
-            const dirCandidate = path.dirname(firstAbs);
-            if (fs.existsSync(dirCandidate) && fs.statSync(dirCandidate).isDirectory()) {
-                projectDir = dirCandidate;
+        catch {
+            /* ignore */
+        }
+        const validAbsFiles = [];
+        for (const f of createdFiles) {
+            const abs = path.resolve(canonicalWorkspace, f);
+            if (isSubpathOrEqual(canonicalWorkspace, abs) && fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+                validAbsFiles.push(fs.realpathSync(abs));
             }
         }
-        // Canonicalize projectDir
-        let canonicalProjectDir = fs.existsSync(projectDir)
-            ? fs.realpathSync(projectDir)
-            : canonicalWorkspace;
-        // Security check: projectDir must be inside canonicalWorkspace
-        if (!canonicalProjectDir.startsWith(canonicalWorkspace)) {
-            canonicalProjectDir = canonicalWorkspace;
+        const validAbsDirs = [];
+        for (const d of createdDirs) {
+            const abs = path.resolve(canonicalWorkspace, d);
+            if (isSubpathOrEqual(canonicalWorkspace, abs) && fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+                validAbsDirs.push(fs.realpathSync(abs));
+            }
         }
-        // Check if canonicalWorkspace root itself directly contains index.html and get mtime
-        const rootIndexPath = path.join(canonicalWorkspace, 'index.html');
-        const rootHasIndex = fs.existsSync(rootIndexPath) && fs.statSync(rootIndexPath).isFile();
-        const rootIndexMtime = rootHasIndex ? fs.statSync(rootIndexPath).mtimeMs : 0;
-        // If canonicalProjectDir is still canonicalWorkspace, check subdirectories for candidate web projects
-        if (canonicalProjectDir === canonicalWorkspace) {
-            const subdirsWithIndex = [];
-            try {
-                const entries = fs.readdirSync(canonicalWorkspace, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory() &&
-                        !entry.name.startsWith('.') &&
-                        !['node_modules', 'dist', 'build', 'coverage', 'src', 'data', 'bin', 'docs'].includes(entry.name)) {
-                        const subDir = path.join(canonicalWorkspace, entry.name);
-                        const indexPath = path.join(subDir, 'index.html');
-                        if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
-                            const stat = fs.statSync(indexPath);
-                            subdirsWithIndex.push({
-                                dir: subDir,
-                                mtime: stat.mtimeMs,
-                            });
-                        }
-                    }
+        // Root workspace fallback ONLY when task is a web task and no specific subdirectory was claimed and root index.html exists
+        if (validAbsFiles.length === 0 && validAbsDirs.length === 0) {
+            if (!/(?:python|data|analysis|backend|fibonacci|non-web)/i.test(task.title)) {
+                const rootIndex = path.join(canonicalWorkspace, 'index.html');
+                if (fs.existsSync(rootIndex) && fs.statSync(rootIndex).isFile()) {
+                    validAbsFiles.push(fs.realpathSync(rootIndex));
                 }
             }
-            catch (err) {
-                this.logger.warn('Failed to scan workspace subdirectories for web projects', { error: String(err) });
-            }
-            if (subdirsWithIndex.length > 0) {
-                // If createdFiles point to a subdirectory, prefer that directory
-                const resolvedCreated = createdFiles.map((f) => path.resolve(canonicalWorkspace, f));
-                const matchedDir = subdirsWithIndex.find((s) => resolvedCreated.some((c) => c.startsWith(s.dir)));
-                if (matchedDir) {
-                    canonicalProjectDir = fs.realpathSync(matchedDir.dir);
+        }
+        let targetProjectDir = null;
+        let entryFile = 'index.html';
+        const indexAbs = validAbsFiles.find((f) => path.basename(f).toLowerCase() === 'index.html');
+        if (indexAbs) {
+            targetProjectDir = path.dirname(indexAbs);
+            entryFile = path.basename(indexAbs);
+        }
+        if (!targetProjectDir && validAbsFiles.length > 0) {
+            const fileDirs = validAbsFiles.map((f) => path.dirname(f));
+            const candidateDirs = Array.from(new Set([...fileDirs, ...validAbsDirs]));
+            for (const dir of candidateDirs) {
+                const indexPath = path.join(dir, 'index.html');
+                if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+                    targetProjectDir = dir;
+                    entryFile = 'index.html';
+                    break;
                 }
-                else {
-                    // Sort by mtime descending (most recently modified project first)
-                    subdirsWithIndex.sort((a, b) => b.mtime - a.mtime);
-                    if (!rootHasIndex || subdirsWithIndex[0].mtime > rootIndexMtime) {
-                        canonicalProjectDir = fs.realpathSync(subdirsWithIndex[0].dir);
-                    }
+            }
+            if (!targetProjectDir) {
+                targetProjectDir = fileDirs[0];
+            }
+        }
+        if (!targetProjectDir && validAbsDirs.length > 0) {
+            for (const dir of validAbsDirs) {
+                const indexPath = path.join(dir, 'index.html');
+                if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+                    targetProjectDir = dir;
+                    entryFile = 'index.html';
+                    break;
                 }
             }
+            if (!targetProjectDir) {
+                targetProjectDir = validAbsDirs[0];
+            }
+        }
+        // If NO task-specific artifact could be identified for THIS task, FAIL SAFELY.
+        // NEVER fall back to global workspace, root index.html, or arbitrary mtime directories.
+        if (!targetProjectDir) {
+            this.logger.info(`No task-specific previewable artifact found for task '${task.id}'`);
+            return {
+                projectDir: canonicalWorkspace,
+                entryFile: 'index.html',
+                files: [],
+                hasIndexHtml: false,
+                isWebProject: false,
+            };
+        }
+        // Canonicalize target project directory
+        let canonicalProjectDir = fs.existsSync(targetProjectDir)
+            ? fs.realpathSync(targetProjectDir)
+            : canonicalWorkspace;
+        if (!isSubpathOrEqual(canonicalWorkspace, canonicalProjectDir)) {
+            canonicalProjectDir = canonicalWorkspace;
         }
-        // Scan selected projectDir for existing files
+        // Scan selected projectDir for files
         const allProjectFiles = [];
         let hasIndexHtml = false;
         let hasWebFiles = false;
@@ -175,8 +380,8 @@ export class PreviewService {
                 this.logger.warn(`Error scanning directory '${canonicalProjectDir}'`, { error: String(err) });
             }
         }
-        // Combine step created files and scanned files
-        const uniqueFiles = Array.from(new Set([...createdFiles, ...allProjectFiles]));
+        const relativeCreatedFiles = validAbsFiles.map((abs) => path.relative(canonicalProjectDir, abs));
+        const uniqueFiles = Array.from(new Set([...relativeCreatedFiles, ...allProjectFiles]));
         return {
             projectDir: canonicalProjectDir,
             entryFile,
@@ -186,24 +391,59 @@ export class PreviewService {
         };
     }
     /**
-     * Launch preview for latest completed task or specified task ID.
+     * Launch preview for latest task, specific task number (#N), or specified task ID.
+     *
+     * STRICT SEMANTICS:
+     * 1. If no target is given, resolves the user's latest task.
+     * 2. If target is numeric (e.g. 2, "2", "#2"), resolves task #N from /tasks list.
+     * 3. If target is string, resolves task by ID.
+     * 4. If target task is FAILED -> returns status TASK_FAILED with reason, blocks preview, NO FALLBACK.
+     * 5. If target task is INCOMPLETE -> returns status TASK_INCOMPLETE, blocks preview, NO FALLBACK.
+     * 6. If target task is COMPLETED -> verifies artifact for THAT task, then launches preview.
      */
-    async preview(taskId) {
-        const task = this.resolveCompletedTask(taskId);
-        if (!task) {
-            if (taskId) {
-                return {
-                    success: false,
-                    status: 'NO_COMPLETED_TASK',
-                    message: `Task '${taskId}' is not a completed task or does not exist.`,
-                };
-            }
+    async preview(target) {
+        const resolved = this.resolveTargetTask(target);
+        if (!resolved.task) {
             return {
                 success: false,
                 status: 'NO_COMPLETED_TASK',
-                message: 'No completed task is available to preview.',
+                message: resolved.error || 'No task is available to preview.',
             };
         }
+        const task = resolved.task;
+        const targetLabel = resolved.targetType === 'latest'
+            ? 'Latest task'
+            : resolved.targetType === 'index'
+                ? `Task #${resolved.targetIndex}`
+                : `Task '${task.id}'`;
+        // 1. Check if task failed -> NEVER FALL BACK TO AN OLDER TASK
+        if (task.state === 'failed') {
+            this.logger.warn(`Preview blocked: ${targetLabel} is in FAILED state`, {
+                taskId: task.id,
+                errorCategory: task.errorCategory,
+            });
+            return {
+                success: false,
+                status: 'TASK_FAILED',
+                task,
+                error: task.errorCategory || 'Execution Failed',
+                message: `Preview unavailable: ${targetLabel} '${task.title}' failed (${task.errorCategory || 'Execution Failed'}).`,
+            };
+        }
+        // 2. Check if task is incomplete -> NEVER FALL BACK
+        if (task.state !== 'completed') {
+            this.logger.warn(`Preview blocked: ${targetLabel} is not completed (state: ${task.state})`, {
+                taskId: task.id,
+                state: task.state,
+            });
+            return {
+                success: false,
+                status: 'TASK_INCOMPLETE',
+                task,
+                message: `Preview unavailable: ${targetLabel} '${task.title}' is currently ${task.state.toUpperCase()}. Only completed tasks can be previewed.`,
+            };
+        }
+        // 3. Task is COMPLETED: Discover artifacts for THIS task only
         const artifacts = this.discoverArtifacts(task);
         if (!artifacts.isWebProject) {
             return {
@@ -211,7 +451,7 @@ export class PreviewService {
                 status: 'NOT_WEB_PROJECT',
                 task,
                 artifactsSummary: artifacts.files,
-                message: `Latest task '${task.title}' does not contain a previewable web project.`,
+                message: `${targetLabel} '${task.title}' does not contain a previewable web project.`,
             };
         }
         if (!artifacts.hasIndexHtml) {
@@ -220,12 +460,12 @@ export class PreviewService {
                 status: 'MISSING_INDEX',
                 task,
                 detectedFiles: artifacts.files,
-                message: 'No index.html entry point was found.',
+                message: `No index.html entry point was found for task '${task.title}'.`,
             };
         }
         // Ensure projectDir is inside workspace
         const canonicalWorkspace = fs.realpathSync(path.resolve(this.workspaceRoot));
-        if (!artifacts.projectDir.startsWith(canonicalWorkspace)) {
+        if (!isSubpathOrEqual(canonicalWorkspace, artifacts.projectDir)) {
             return {
                 success: false,
                 status: 'ERROR',
@@ -233,6 +473,25 @@ export class PreviewService {
                 error: 'Security Error: Preview directory is outside workspace boundaries.',
             };
         }
+        // Verify artifact is a real implementation and passes content integrity checks
+        const entryFullPath = path.join(artifacts.projectDir, artifacts.entryFile || 'index.html');
+        if (fs.existsSync(entryFullPath)) {
+            const content = fs.readFileSync(entryFullPath, 'utf8');
+            const contentVerif = verifyHtmlContentSubstance(content, task.title);
+            if (!contentVerif.valid) {
+                this.logger.warn(`Preview blocked: artifact failed content verification for task '${task.id}'`, {
+                    category: contentVerif.errorCategory,
+                    reason: contentVerif.reason,
+                });
+                return {
+                    success: false,
+                    status: 'PLACEHOLDER_ARTIFACT_BLOCKED',
+                    task,
+                    detectedFiles: artifacts.files,
+                    message: `Preview blocked: generated artifact failed integrity/content verification. ${contentVerif.reason || ''}`.trim(),
+                };
+            }
+        }
         try {
             const serverInfo = await this.server.start(artifacts.projectDir, artifacts.entryFile || 'index.html');
             this.activeTask = task;
@@ -296,6 +555,9 @@ export class PreviewService {
      * Open local preview URL safely in default browser without shell injection risk.
      */
     async openBrowser(url) {
+        if (process.env.NODE_ENV === 'test' || process.env.VITEST) {
+            return true;
+        }
         if (!url.startsWith('http://127.0.0.1:')) {
             this.logger.warn(`Refusing to open non-loopback URL: '${url}'`);
             return false;