@ranger-testing/ranger-cli 1.1.7 → 2.0.1

package/build/commands/verifyFeature.js

@@ -1,4 +1,5 @@
 import { query, } from '@anthropic-ai/claude-agent-sdk';
+import { createTelemetryCollector, } from './utils/telemetry.js';
 import { join, dirname } from 'path';
 import { readFile, readdir, appendFile, mkdir, rm, stat } from 'fs/promises';
 import { existsSync } from 'fs';
@@ -6,11 +7,16 @@ import { execSync } from 'child_process';
 import { tmpdir } from 'os';
 import inquirer from 'inquirer';
 import { loadSettings, resolveEnvVars, buildPlaywrightConfig, cleanupTempFiles, getEnvDir, } from './utils/settings.js';
-import { createBrowserSession, updateBrowserSession, getUploadUrls, uploadTrace, uploadConversation, uploadScreenshot, uploadVideo, buildTraceViewerUrl, getAnthropicApiKey, createVerificationStep, createStepAsset, } from './utils/browserSessionsApi.js';
+import { createBrowserSession, updateBrowserSession, getUploadUrls, uploadTrace, uploadConversation, uploadScreenshot, uploadVideo, buildTraceViewerUrl, getProxySessionToken, createVerificationStep, createStepAsset, } from './utils/browserSessionsApi.js';
+import { getAiProxyUrl } from './utils/environment.js';
 import { getToken } from './utils/keychain.js';
 import { getActiveFeatureId } from './feature.js';
-import { getFeature, updateFeature, updateChecklistItem, startSession, getActionItems, getItemFeedback, } from './utils/featureApi.js';
+import { readActiveProfileName } from './utils/activeProfile.js';
+import { getEnvNames } from './env.js';
+import { formatProfileRequiredMessage } from './utils/profileMessages.js';
+import { getFeature, updateFeature, updateChecklistItem, startSession, getActionItems, getItemFeedback, markCommentsAddressed, } from './utils/featureApi.js';
 import { getRangerDir } from './utils/rangerRoot.js';
+const bold = (text) => `\x1b[1m${text}\x1b[0m`;
 /**
  * Get the current git branch
  */
@@ -73,7 +79,7 @@ function getMockEvaluation(outcome) {
             success: true,
             summary: '[DEBUG] Mock verification completed successfully.',
             evaluation: 'verified',
-            evaluationReason: 'All checklist requirements were met.',
+            evaluationReason: 'All scenario requirements were met.',
         },
         partial: {
             success: false,
@@ -91,7 +97,7 @@ function getMockEvaluation(outcome) {
         incomplete: {
             success: false,
             summary: '[DEBUG] Mock incomplete verification.',
-            evaluation: 'partial',
+            evaluation: 'incomplete',
             evaluationReason: 'Implementation is incomplete and needs additional work.',
             issues: [
                 {
@@ -157,42 +163,52 @@ function getDebugPrompt() {
 Return your findings in the structured output format.`;
 }
 /**
- * Prompt user to select a checklist item
+ * Prompt user to select a scenario
  */
 async function selectChecklistItem(items) {
     if (items.length === 0) {
         return null;
     }
-    const choices = items.map((item, i) => {
-        const emoji = item.status === 'verified'
+    const choices = items.map((item) => {
+        const emoji = item.status === 'closed' && item.terminalReason === 'approved'
             ? '\u2705'
-            : item.status === 'incomplete'
-                ? '\ud83d\udfe0' // orange circle
-                : item.status === 'blocked'
-                    ? '\ud83d\uded1'
-                    : item.status === 'closed'
-                        ? '\u26d4'
-                        : '\u2b1c';
+            : item.status === 'verified'
+                ? '\ud83d\udfe2' // green circle
+                : item.status === 'incomplete'
+                    ? '\ud83d\udfe0' // orange circle
+                    : item.status === 'blocked'
+                        ? '\ud83d\uded1'
+                        : item.status === 'closed'
+                            ? '\u26d4'
+                            : item.status === 'verification_in_progress'
+                                ? '\u23f3'
+                                : '\u2b1c';
         const commentBadge = item.unaddressedCommentCount > 0
             ? ` [${item.unaddressedCommentCount} comments]`
             : '';
+        const disabledReason = item.actionable
+            ? false
+            : item.status === 'closed' && item.terminalReason
+                ? item.terminalReason
+                : 'not actionable';
         return {
-            name: `${i + 1}. ${emoji} ${item.description}${commentBadge}`,
+            name: `${item.displayIndex + 1}. ${emoji} ${item.description}${commentBadge}`,
             value: item.id,
+            disabled: disabledReason,
         };
     });
     const { selected } = await inquirer.prompt([
         {
             type: 'list',
             name: 'selected',
-            message: 'Which checklist item does this verify?',
+            message: 'Which scenario does this verify?',
             choices,
         },
     ]);
     return items.find((i) => i.id === selected) || null;
 }
 /**
- * Handle incomplete verification - check if all other items are terminal and prompt user
+ * Handle incomplete verification - check if all other scenarios are terminal and prompt user
  */
 async function handleIncompleteItem(featureId, incompleteItem, result) {
     // Get action items to check if there are other items to work on
@@ -217,46 +233,98 @@ async function handleIncompleteItem(featureId, incompleteItem, result) {
     }
     console.log(`\nNext steps:`);
     console.log(`  1. Fix the issues above in your code`);
-    console.log(`  2. Run 'ranger verify-feature' again to re-verify`);
+    console.log(`  2. Run 'ranger go' again to re-verify`);
     if (allOthersTerminal && otherItems.length > 0) {
-        console.log(`\nAll other checklist items are complete.`);
-        console.log(`If you're done for now, run 'ranger feature conclude-session' to end this session.`);
+        console.log(`\nAll other scenarios are complete.`);
+        console.log(`If you're done for now, you can stop and resume later with 'ranger resume'.`);
     }
     console.log(`${'='.repeat(60)}\n`);
 }
 /**
- * PostToolUse hook that logs browser tool calls to stdout.
+ * Create a PostToolUse hook that logs browser tool calls to stdout and tracks
+ * all tool calls via telemetry with per-call timing.
+ */
+function createToolCallTrackingHook(telemetry) {
+    const toolCallCounts = new Map();
+    const hook = async (input) => {
+        if (input.hook_event_name !== 'PostToolUse')
+            return {};
+        const postInput = input;
+        const toolInput = postInput.tool_input;
+        const shortName = postInput.tool_name.replace('mcp__ranger-browser__', '');
+        // Track count
+        toolCallCounts.set(shortName, (toolCallCounts.get(shortName) || 0) + 1);
+        // Log tool call as telemetry event
+        telemetry.trackPhaseStart('tool_call', { toolName: shortName });
+        telemetry.trackPhaseEnd('tool_call', {
+            toolName: shortName,
+            toolInput: summarizeToolInput(shortName, toolInput),
+        });
+        // Console log
+        switch (postInput.tool_name) {
+            case 'mcp__ranger-browser__browser_navigate':
+                console.log(`[browser] Navigate → ${toolInput.url}`);
+                break;
+            case 'mcp__ranger-browser__browser_click':
+                console.log(`[browser] Click → "${toolInput.element}"`);
+                break;
+            case 'mcp__ranger-browser__browser_type':
+                console.log(`[browser] Type → "${toolInput.text}" into "${toolInput.element}"`);
+                break;
+            case 'mcp__ranger-browser__browser_press_key':
+                console.log(`[browser] Press key → ${toolInput.key}`);
+                break;
+            case 'mcp__ranger-browser__browser_wait_for':
+                console.log(`[browser] Wait → ${toolInput.time ? `${toolInput.time}ms` : toolInput.text || 'condition'}`);
+                break;
+        }
+        return {};
+    };
+    return { hook, toolCallCounts };
+}
+/**
+ * Create a PostToolUseFailure hook that tracks tool failures via telemetry.
  */
-const browserToolLogHook = async (input) => {
-    if (input.hook_event_name !== 'PostToolUse')
+function createToolFailureHook(telemetry) {
+    return async (input) => {
+        if (input.hook_event_name !== 'PostToolUseFailure')
+            return {};
+        const failInput = input;
+        const shortName = failInput.tool_name.replace('mcp__ranger-browser__', '');
+        await telemetry.trackPhaseError('tool_failure', failInput.error, {
+            toolName: shortName,
+            isInterrupt: failInput.is_interrupt,
+        });
         return {};
-    const postInput = input;
-    const toolInput = postInput.tool_input;
-    switch (postInput.tool_name) {
-        case 'mcp__ranger-browser__browser_navigate':
-            console.log(`[browser] Navigate → ${toolInput.url}`);
-            break;
-        case 'mcp__ranger-browser__browser_click':
-            console.log(`[browser] Click → "${toolInput.element}"`);
-            break;
-        case 'mcp__ranger-browser__browser_type':
-            console.log(`[browser] Type → "${toolInput.text}" into "${toolInput.element}"`);
-            break;
-        case 'mcp__ranger-browser__browser_press_key':
-            console.log(`[browser] Press key → ${toolInput.key}`);
-            break;
-        case 'mcp__ranger-browser__browser_wait_for':
-            console.log(`[browser] Wait → ${toolInput.time ? `${toolInput.time}ms` : toolInput.text || 'condition'}`);
-            break;
+    };
+}
+/**
+ * Summarize tool input for telemetry (avoid logging sensitive/large data).
+ */
+function summarizeToolInput(toolName, input) {
+    switch (toolName) {
+        case 'browser_navigate':
+            return { url: input.url };
+        case 'browser_click':
+            return { element: input.element };
+        case 'browser_type':
+            return { element: input.element };
+        case 'browser_take_screenshot':
+            return { filename: input.filename };
+        case 'browser_press_key':
+            return { key: input.key };
+        case 'browser_wait_for':
+            return { time: input.time, text: input.text };
+        default:
+            return {};
     }
-    return {};
-};
+}
 /**
  * Create a PostToolUse hook that uploads screenshots immediately after they're taken.
  * Returns the hook callback and a set of filenames that were successfully uploaded,
  * so the post-hoc fallback can skip them.
  */
-function createScreenshotUploadHook(sessionId, checklistItemId, traceDir) {
+function createScreenshotUploadHook(sessionId, checklistItemId, traceDir, telemetry) {
     const uploadedFiles = new Set();
     let position = 1;
     const hook = async (input) => {
@@ -271,11 +339,15 @@ function createScreenshotUploadHook(sessionId, checklistItemId, traceDir) {
         const filename = toolInput?.filename;
         if (!filename)
             return {};
+        const isKeyFrame = filename.toLowerCase().startsWith('key_');
+        telemetry.trackPhaseStart('hook_screenshot_upload', {
+            filename,
+            isKeyFrame,
+        });
         try {
             const pngPath = join(traceDir, filename);
             const pngBuffer = await readFile(pngPath);
             const pngStat = await stat(pngPath);
-            const isKeyFrame = filename.toLowerCase().startsWith('key_');
             const displayName = filename
                 .replace(/\.png$/i, '')
                 .replace(/^key_/i, '')
@@ -315,96 +387,142 @@ function createScreenshotUploadHook(sessionId, checklistItemId, traceDir) {
             await uploadScreenshot(assetResponse.uploadUrl, pngBuffer);
             // Track as uploaded
             uploadedFiles.add(filename);
+            telemetry.trackPhaseEnd('hook_screenshot_upload', {
+                filename,
+                bytes: pngBuffer.length,
+            });
         }
         catch (err) {
-            // swallow error for now
-            // TODO: should log / report these
+            await telemetry.trackPhaseError('hook_screenshot_upload', err, {
+                filename,
+            });
         }
         return {};
     };
     return { hook, uploadedFiles };
 }
 /**
- * Verify a checklist item in the browser
+ * Phase 1: Setup through agent completion.
+ * Returns context for processVerificationResult.
  */
-export async function verifyFeature(options) {
+async function runVerification(options, telemetry) {
     const isDebugMode = !!options.debugOutcome;
     if (isDebugMode) {
         console.log(`\n[DEBUG MODE] Running minimal browser test with outcome: ${options.debugOutcome}`);
     }
-    // 1. Check for active feature
+    // --- Phase: feature_load ---
+    telemetry.trackPhaseStart('feature_load');
     const featureId = await getActiveFeatureId();
     if (!featureId) {
-        throw new Error('No active feature. Run: ranger feature resume <id> or ranger feature create');
+        throw new Error('No active feature review. Run: ranger resume <id> or ranger create');
     }
-    // Load feature details
     const feature = await getFeature(featureId);
-    // Update the feature's gitBranch to the current branch
+    telemetry.setContext({ featureId });
     const currentBranch = getGitBranch();
     if (currentBranch && currentBranch !== feature.gitBranch) {
         await updateFeature(featureId, { gitBranch: currentBranch });
         console.log(`   Updated branch to: ${currentBranch}`);
     }
-    console.log(`\nActive feature: ${feature.name} (${featureId})`);
-    // Get action items - leaf items that can be verified (non-closed with no non-closed children)
+    console.log(`\nActive feature review: ${feature.name} (${featureId})`);
     const { items: actionItems } = await getActionItems(featureId);
-    // 2. Determine which checklist item we're verifying
+    const actionItemsById = new Map(actionItems.map((item) => [item.id, item]));
+    const displayItems = feature.checklistItems.map((item, index) => {
+        const actionItem = actionItemsById.get(item.id);
+        return {
+            ...item,
+            unaddressedCommentCount: actionItem?.unaddressedCommentCount ?? 0,
+            displayIndex: index,
+            actionable: !!actionItem && item.status !== 'closed',
+        };
+    });
+    telemetry.trackPhaseEnd('feature_load', {
+        itemCount: actionItems.length,
+    });
+    // --- Phase: scenario_select ---
+    telemetry.trackPhaseStart('scenario_select');
     let checklistItem = null;
-    let taskDescription = options.task;
-    if (options.item !== undefined) {
+    let taskDescription = options.notes;
+    if (options.scenario !== undefined) {
         // Use specified item index (1-based)
-        const itemIndex = options.item - 1; // 1-based to 0-based
-        if (itemIndex < 0 || itemIndex >= actionItems.length) {
-            throw new Error(`Invalid item index: ${options.item}. Feature has ${actionItems.length} actionable items.`);
+        const itemIndex = options.scenario - 1; // 1-based to 0-based
+        if (itemIndex < 0 || itemIndex >= displayItems.length) {
+            throw new Error(`Invalid scenario index: ${options.scenario}. Feature review has ${displayItems.length} scenarios.`);
         }
-        checklistItem = actionItems[itemIndex];
+        const displayItem = displayItems[itemIndex];
+        if (!displayItem.actionable) {
+            const reason = displayItem.status === 'closed' && displayItem.terminalReason
+                ? displayItem.terminalReason
+                : 'not actionable';
+            throw new Error(`Scenario ${options.scenario} is ${reason} and cannot be verified. Choose a different scenario.`);
+        }
+        const actionItem = actionItemsById.get(displayItem.id);
+        if (!actionItem) {
+            throw new Error(`Scenario ${options.scenario} is not currently actionable. Try another scenario.`);
+        }
+        checklistItem = actionItem;
         if (!taskDescription) {
             taskDescription = checklistItem.description;
         }
     }
     else {
-        // Check if running in non-TTY environment (CI, scripts, Claude Code, etc.)
         const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
         if (!isInteractive) {
-            // Non-TTY mode: require --item flag, show available items
-            console.log('\nNon-interactive mode detected. The --item flag is required.');
-            console.log('\nAvailable checklist items to verify:');
-            actionItems.forEach((item, i) => {
-                const emoji = item.status === 'verified'
+            // Non-TTY mode: require --scenario flag, show available scenarios
+            console.log('\nNon-interactive mode detected. The --scenario flag is required.');
+            console.log('\nAvailable scenarios to verify:');
+            displayItems.forEach((item) => {
+                const emoji = item.status === 'closed' &&
+                    item.terminalReason === 'approved'
                     ? '\u2705'
-                    : item.status === 'incomplete'
-                        ? '\ud83d\udfe0' // orange circle
-                        : item.status === 'blocked'
-                            ? '\ud83d\uded1'
-                            : item.status === 'closed'
-                                ? '\u26d4'
-                                : '\u2b1c';
+                    : item.status === 'verified'
+                        ? '\ud83d\udfe2'
+                        : item.status === 'incomplete'
+                            ? '\ud83d\udfe0'
+                            : item.status === 'blocked'
+                                ? '\ud83d\uded1'
+                                : item.status === 'closed'
+                                    ? '\u26d4'
+                                    : item.status === 'verification_in_progress'
+                                        ? '\u23f3'
+                                        : '\u2b1c';
                 const commentBadge = item.unaddressedCommentCount > 0
                     ? ` [${item.unaddressedCommentCount} comments]`
                     : '';
-                console.log(`  ${i + 1}. ${emoji} ${item.description}${commentBadge}`);
+                const actionHint = item.actionable ? '' : ' [not actionable]';
+                console.log(`  ${item.displayIndex + 1}. ${emoji} ${item.description}${commentBadge}${actionHint}`);
             });
-            console.log('\nUsage: ranger verify-feature --item <number>');
-            console.log('Example: ranger verify-feature --item 1');
-            throw new Error('The --item flag is required in non-interactive mode. See available items above.');
+            console.log('\nUsage: ranger go --scenario <number>');
+            console.log('Example: ranger go --scenario 1');
+            throw new Error('The --scenario flag is required in non-interactive mode. See available scenarios above.');
         }
-        // Interactive selection
-        checklistItem = await selectChecklistItem(actionItems);
-        if (!taskDescription && checklistItem) {
-            taskDescription = checklistItem.description;
+        const selectedItem = await selectChecklistItem(displayItems);
+        if (selectedItem) {
+            const actionItem = actionItemsById.get(selectedItem.id);
+            if (!actionItem) {
+                throw new Error('Selected scenario is not currently actionable. Choose another scenario.');
+            }
+            checklistItem = actionItem;
+            if (!taskDescription) {
+                taskDescription = checklistItem.description;
+            }
         }
     }
     if (!checklistItem) {
-        throw new Error('No checklist item selected. Create items when creating the feature with -c flag.');
+        throw new Error('No scenario selected. Create scenarios when creating the feature review with -c or --scenario flags.');
     }
     if (checklistItem.status === 'closed') {
-        throw new Error(`Cannot verify item "${checklistItem.description}" — it is concluded (${checklistItem.terminalReason || 'unknown reason'}).`);
+        throw new Error(`Cannot verify scenario "${checklistItem.description}" — it is concluded (${checklistItem.terminalReason || 'unknown reason'}).`);
     }
     if (!taskDescription) {
-        throw new Error('No task description provided');
+        throw new Error('No notes provided');
     }
-    console.log(`\nVerifying: ${checklistItem.description}`);
-    console.log(`Task: ${taskDescription}`);
+    telemetry.setContext({ checklistItemId: checklistItem.id });
+    telemetry.trackPhaseEnd('scenario_select', {
+        selectionMethod: options.scenario !== undefined ? 'flag' : 'interactive',
+        itemStatus: checklistItem.status,
+    });
+    console.log(`\nVerifying scenario: ${checklistItem.description}`);
+    console.log(`Notes: ${taskDescription}`);
     // Fetch reviewer feedback if item has parent or unaddressed comments
     let itemFeedback = null;
     if (checklistItem.parentItemId ||
@@ -415,8 +533,9 @@ export async function verifyFeature(options) {
                 console.log(`Reviewer feedback: ${itemFeedback.unaddressedComments.length} comment(s) to verify`);
             }
         }
-        catch {
-            // Non-fatal - continue without feedback
+        catch (err) {
+            // Non-fatal - continue without feedback, but log it
+            await telemetry.trackPhaseError('feedback_fetch', err);
         }
     }
     // Start the session if it's in ready status
@@ -427,41 +546,38 @@ export async function verifyFeature(options) {
             await startSession(featureId, feature.currentSessionId);
         }
         catch (error) {
-            // Ignore if session is already started (race condition)
             const message = error instanceof Error ? error.message : String(error);
             if (!message.includes('already')) {
                 throw error;
             }
         }
     }
-    // Update checklist item status to verification_in_progress
+    // Update scenario status to verification_in_progress
     await updateChecklistItem(featureId, checklistItem.id, {
         status: 'verification_in_progress',
     });
-    // 3. Determine which environment to use (same pattern as verifyInBrowser)
-    let activeEnv;
-    if (options.env) {
-        activeEnv = options.env;
+    // --- Phase: profile_resolution ---
+    telemetry.trackPhaseStart('profile_resolution');
+    let activeProfile = null;
+    if (options.profile) {
+        activeProfile = options.profile;
     }
     else {
-        const activeEnvPath = join(getRangerDir(), 'active-env.txt');
-        if (!existsSync(activeEnvPath)) {
-            throw new Error('No active environment. Run: ranger use <env-name>');
-        }
-        activeEnv = await readFile(activeEnvPath, 'utf-8').then((s) => s.trim());
+        activeProfile = await readActiveProfileName();
+    }
+    if (!activeProfile) {
+        throw new Error('No active profile. Run: ranger profile use <profile-name>');
     }
-    const envDir = getEnvDir(activeEnv);
+    const envDir = getEnvDir(activeProfile);
     if (!existsSync(envDir)) {
-        throw new Error(`Environment "${activeEnv}" not found. Run: ranger add env ${activeEnv}`);
+        throw new Error(`Profile "${activeProfile}" not found. Run: ranger profile add ${activeProfile}`);
     }
-    const settings = await loadSettings(activeEnv);
+    const settings = await loadSettings(activeProfile);
     const resolvedSettings = resolveEnvVars(settings);
-    // Get base URL from settings
     let url = resolvedSettings.baseUrl;
     if (!url) {
-        throw new Error(`No baseUrl configured for environment "${activeEnv}". Run: ranger config set ${activeEnv} baseUrl <url>`);
+        throw new Error(`No baseUrl configured for profile "${activeProfile}". Run: ranger profile config set ${activeProfile} baseUrl <url>`);
     }
-    // Append startPath if provided
     if (options.startPath) {
         const base = url.endsWith('/') ? url.slice(0, -1) : url;
         const path = options.startPath.startsWith('/')
@@ -469,13 +585,17 @@ export async function verifyFeature(options) {
             : '/' + options.startPath;
         url = base + path;
     }
-    // 4. Create browser session
+    telemetry.trackPhaseEnd('profile_resolution', {
+        profileName: activeProfile,
+    });
+    // --- Phase: browser_session_create ---
+    telemetry.trackPhaseStart('browser_session_create');
     const token = await getToken();
     if (!token) {
-        throw new Error('No API token configured. Run: ranger start <token>');
+        throw new Error('No API token configured. Run: ranger setup [token]');
     }
     const browserSession = await createBrowserSession({
-        environmentName: activeEnv,
+        environmentName: activeProfile,
         settings: resolvedSettings,
         task: taskDescription,
         url,
@@ -483,116 +603,90 @@ export async function verifyFeature(options) {
         checklistItemId: checklistItem.id,
     });
     console.log(`Browser session created: ${browserSession.id}`);
-    // Link the browser session to the checklist item immediately so steps
+    telemetry.setContext({ browserSessionId: browserSession.id });
+    // Link the browser session to the scenario immediately so steps
     // are visible in the dashboard while verification is in progress
     await updateChecklistItem(featureId, checklistItem.id, {
         browserSessionId: browserSession.id,
     });
+    telemetry.trackPhaseEnd('browser_session_create');
+    // --- Phase: playwright_config ---
+    telemetry.trackPhaseStart('playwright_config');
     let configResult;
-    const startTime = Date.now();
-    // Handle process interruption (Ctrl+C or coding agent killing the process)
-    let interrupted = false;
-    const handleInterrupt = async () => {
-        if (interrupted)
-            return;
-        interrupted = true;
-        console.log('\nVerification interrupted. Cleaning up...');
+    let sessionToken;
+    try {
+        sessionToken = await getProxySessionToken();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const errorMsg = `Failed to fetch proxy session token: ${message}`;
         try {
             await updateBrowserSession(browserSession.id, {
-                status: 'interrupted',
-                durationMs: Date.now() - startTime,
-            });
-        }
-        catch {
-            // Best effort
-        }
-        try {
-            await updateChecklistItem(featureId, checklistItem.id, {
-                status: 'pending',
+                status: 'failed',
+                durationMs: 0,
+                errorMessage: errorMsg,
             });
         }
-        catch {
-            // Best effort
+        catch (updateErr) {
+            await telemetry.trackPhaseError('session_error_update', updateErr);
         }
-        if (configResult) {
-            try {
-                await cleanupTempFiles(configResult);
-            }
-            catch {
-                // Best effort
-            }
-        }
-        console.log('Checklist item reset to pending. Partial steps are preserved.');
-        process.exit(0);
+        throw new Error(errorMsg);
+    }
+    configResult = await buildPlaywrightConfig(resolvedSettings, activeProfile, browserSession?.id);
+    telemetry.trackPhaseEnd('playwright_config');
+    const startTime = Date.now();
+    const rangerBrowserMcp = {
+        command: 'npx',
+        args: [
+            '@ranger-testing/playwright',
+            'run-mcp-server',
+            '--config',
+            configResult.configPath,
+        ],
     };
-    process.on('SIGINT', handleInterrupt);
-    process.on('SIGTERM', handleInterrupt);
-    let anthropicApiKey;
-    let conversationDir;
+    // Build verifier prompt
     let verifierPrompt;
-    let checklistItemResolved = false;
-    try {
-        // Fetch Anthropic API key
-        try {
-            anthropicApiKey = await getAnthropicApiKey();
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const errorMsg = `Failed to fetch Anthropic API key: ${message}`;
-            try {
-                await updateBrowserSession(browserSession.id, {
-                    status: 'failed',
-                    durationMs: Date.now() - startTime,
-                    errorMessage: errorMsg,
-                });
-            }
-            catch {
-                // Ignore
-            }
-            throw new Error(errorMsg);
-        }
-        configResult = await buildPlaywrightConfig(resolvedSettings, activeEnv, browserSession?.id);
-        const rangerBrowserMcp = {
-            command: 'npx',
-            args: [
-                '@ranger-testing/playwright',
-                'run-mcp-server',
-                '--config',
-                configResult.configPath,
-            ],
-        };
-        // 5. UI Verifier + Evaluation Agent prompt
-        if (isDebugMode) {
-            verifierPrompt = getDebugPrompt();
+    if (isDebugMode) {
+        let debugFeedbackSection = '';
+        if (itemFeedback && itemFeedback.unaddressedComments.length > 0) {
+            const commentLines = itemFeedback.unaddressedComments
+                .map((c) => `- [${c.id}] "${c.content}"`)
+                .join('\n');
+            const instruction = options.debugAddressComments
+                ? 'For debug purposes, mark ALL of the following comments as addressed by including every ID in addressedCommentIds.'
+                : 'For debug purposes, do NOT mark any comments as addressed. Return an empty addressedCommentIds array.';
+            debugFeedbackSection = `\n\n## Debug: Reviewer Comments\n${instruction}\n\n${commentLines}`;
         }
-        else {
-            const notesSection = checklistItem.notes
-                ? `\n\n## Additional Notes\n${checklistItem.notes}`
-                : '';
-            // Build reviewer feedback section if available
-            let feedbackSection = '';
-            if (itemFeedback && itemFeedback.unaddressedComments.length > 0) {
-                const commentLines = itemFeedback.unaddressedComments
-                    .map((c) => {
-                    const date = new Date(c.createdAt).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
-                    const author = c.authorName || c.authorEmail || 'Reviewer';
-                    return `- **${author}** (${date}): "${c.content}"`;
-                })
-                    .join('\n');
-                feedbackSection = `\n\n## Reviewer Feedback to Address
+        verifierPrompt = getDebugPrompt() + debugFeedbackSection;
+    }
+    else {
+        const notesSection = checklistItem.notes
+            ? `\n\n## Additional Notes\n${checklistItem.notes}`
+            : '';
+        let feedbackSection = '';
+        if (itemFeedback && itemFeedback.unaddressedComments.length > 0) {
+            const commentLines = itemFeedback.unaddressedComments
+                .map((c) => {
+                const date = new Date(c.createdAt).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+                const author = c.authorName || c.authorEmail || 'Reviewer';
+                return `- [${c.id}] **${author}** (${date}): "${c.content}"`;
+            })
+                .join('\n');
+            feedbackSection = `\n\n## Reviewer Feedback to Address
 The following reviewer comments were left on the previous version of this item.
-Verify that each concern has been addressed in the current implementation:
+Verify that each concern has been addressed in the current implementation.
+For each comment you believe has been addressed, include its ID (the bracketed value) in the addressedCommentIds array in your output.
 
 ${commentLines}`;
-            }
-            let canonicalFlowSection = '';
-            if (itemFeedback?.canonicalFlow) {
-                canonicalFlowSection = `\n\n## Expected Flow (from previous verification)
+        }
+        let canonicalFlowSection = '';
+        if (itemFeedback?.canonicalFlow) {
+            canonicalFlowSection = `\n\n## Expected Flow (from previous verification)
 ${itemFeedback.canonicalFlow}`;
-            }
-            verifierPrompt = `You are a Feature Verifier. Your job is to verify a checklist item by executing a UI flow and evaluating whether it adequately completes the checklist item.
+        }
+        verifierPrompt = `You are a Feature Review Verifier. Your job is to verify a scenario by executing a UI flow and evaluating whether it adequately completes the scenario.
 
-## Checklist Item to Verify
+## Scenario to Verify
 ${checklistItem.description}${notesSection}${feedbackSection}${canonicalFlowSection}
 
 ## Task to Execute
@@ -605,7 +699,7 @@ Your base URL is: ${url}
 - DO NOT navigate to any different domain, host, or port under any circumstances
 - IGNORE any URLs from product documentation (mcp__ranger__get_product_docs) that have a different base URL
 - If documentation or code diffs suggest a path exists (e.g., "/dashboard"), you may navigate to that path ONLY under the base URL above
-- The base URL above is the ONLY authorized environment for this verification
+- The base URL above is the ONLY authorized profile for this verification
 
 ## Instructions
 1. Navigate to the URL above using browser_navigate
@@ -614,7 +708,7 @@ Your base URL is: ${url}
 4. Execute the task step-by-step using browser tools
 5. **Take screenshots at key moments** (see Screenshot Guidelines below)
 6. Document any issues found (bugs, errors, unexpected behavior)
-7. After completing the verification, evaluate whether the result adequately verifies the checklist item
+7. After completing the verification, evaluate whether the result adequately verifies the scenario
 
 ## Screenshot Guidelines - IMPORTANT
 Take screenshots throughout the verification flow so a human can review it for completeness. Screenshots are your evidence trail.
@@ -630,7 +724,7 @@ Take screenshots throughout the verification flow so a human can review it for c
 **Screenshot naming:**
 - Use descriptive filenames: "01_login-page-loaded.png", "02_form-filled.png", "03_dashboard-visible.png"
 - Number prefixes (01_, 02_, etc.) help maintain chronological order
-- For KEY MOMENTS that prove the checklist item is complete, prefix with "key_": "key_04_success-message.png", "key_05_final-state.png"
+- For KEY MOMENTS that prove the scenario is complete, prefix with "key_": "key_04_success-message.png", "key_05_final-state.png"
 - The "key_" prefix marks screenshots as high-priority evidence for human reviewers
 
 **Aim for 3-6 screenshots per verification** to document the complete flow. Mark 1-2 of the most important ones with the "key_" prefix.
@@ -657,266 +751,340 @@ After step 2 (taking initial snapshot), IMMEDIATELY check for blocking HTTP erro
 This early exit prevents wasting time on tasks that cannot succeed due to fundamental errors.
 
 ## Evaluation Criteria
-- VERIFIED: The task completed successfully and the checklist item requirements are fully met
-- PARTIAL: The task partially completed but some aspects of the checklist item are not verified
+- VERIFIED: The task completed successfully and the scenario requirements are fully met
+- PARTIAL: The task partially completed but some aspects of the scenario are not verified
 - BLOCKED: A blocking issue (bug, error, missing feature) prevents completion
 - FAILED: The task could not be completed due to errors
 
 Return your findings in the structured output format with your evaluation.`;
-        }
-        const outputSchema = {
-            type: 'object',
-            properties: {
-                success: { type: 'boolean' },
-                summary: { type: 'string' },
-                evaluation: {
-                    type: 'string',
-                    enum: ['verified', 'partial', 'blocked', 'failed'],
-                },
-                evaluationReason: { type: 'string' },
-                issues: {
-                    type: 'array',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            severity: {
-                                type: 'string',
-                                enum: ['BLOCKER', 'MAJOR', 'MINOR'],
-                            },
-                            type: {
-                                type: 'string',
-                                enum: [
-                                    'HTTP_404',
-                                    'HTTP_500',
-                                    'HTTP_400',
-                                    'NAVIGATION_ERROR',
-                                    'OTHER',
-                                ],
-                            },
-                            description: { type: 'string' },
-                            screenshot: { type: 'string' },
+    }
+    const outputSchema = {
+        type: 'object',
+        properties: {
+            success: { type: 'boolean' },
+            summary: { type: 'string' },
+            evaluation: {
+                type: 'string',
+                enum: ['verified', 'partial', 'blocked', 'failed'],
+            },
+            evaluationReason: { type: 'string' },
+            issues: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        severity: {
+                            type: 'string',
+                            enum: ['BLOCKER', 'MAJOR', 'MINOR'],
                         },
-                        required: ['severity', 'description'],
+                        type: {
+                            type: 'string',
+                            enum: [
+                                'HTTP_404',
+                                'HTTP_500',
+                                'HTTP_400',
+                                'NAVIGATION_ERROR',
+                                'OTHER',
+                            ],
+                        },
+                        description: { type: 'string' },
+                        screenshot: { type: 'string' },
                     },
+                    required: ['severity', 'description'],
                 },
             },
-            required: ['success', 'summary', 'evaluation', 'evaluationReason'],
-        };
-        // 6. Execute agent
-        const traceDir = getTraceDirectory(browserSession.id);
-        const screenshotHook = createScreenshotUploadHook(browserSession.id, checklistItem.id, traceDir);
-        const result = query({
-            prompt: verifierPrompt,
-            options: {
-                cwd: process.cwd(),
-                model: 'claude-opus-4-6',
-                mcpServers: {
-                    'ranger-browser': rangerBrowserMcp,
-                },
-                tools: ['mcp__ranger-browser__*'],
-                permissionMode: 'acceptEdits',
-                allowedTools: [
-                    'mcp__ranger-browser__*',
-                    'Read',
-                    'Glob',
-                    'Grep',
+            addressedCommentIds: {
+                type: 'array',
+                description: 'IDs of reviewer comments that have been addressed in the current implementation',
+                items: { type: 'string' },
+            },
+        },
+        required: ['success', 'summary', 'evaluation', 'evaluationReason'],
+    };
+    // --- Phase: agent_execution ---
+    telemetry.trackPhaseStart('agent_execution');
+    const traceDir = getTraceDirectory(browserSession.id);
+    const screenshotHook = createScreenshotUploadHook(browserSession.id, checklistItem.id, traceDir, telemetry);
+    const toolCallHook = createToolCallTrackingHook(telemetry);
+    const toolFailureHook = createToolFailureHook(telemetry);
+    const result = query({
+        prompt: verifierPrompt,
+        options: {
+            cwd: process.cwd(),
+            model: 'claude-opus-4-6',
+            mcpServers: {
+                'ranger-browser': rangerBrowserMcp,
+            },
+            tools: ['mcp__ranger-browser__*'],
+            permissionMode: 'acceptEdits',
+            allowedTools: ['mcp__ranger-browser__*', 'Read', 'Glob', 'Grep'],
+            outputFormat: {
+                type: 'json_schema',
+                schema: outputSchema,
+            },
+            hooks: {
+                PostToolUse: [
+                    {
+                        hooks: [toolCallHook.hook, screenshotHook.hook],
+                    },
+                ],
+                PostToolUseFailure: [
+                    {
+                        hooks: [toolFailureHook],
+                    },
                 ],
-                outputFormat: {
-                    type: 'json_schema',
-                    schema: outputSchema,
-                },
-                hooks: {
-                    PostToolUse: [
-                        {
-                            hooks: [browserToolLogHook, screenshotHook.hook],
-                        },
-                    ],
-                },
-                env: {
-                    ...process.env,
-                    ANTHROPIC_API_KEY: anthropicApiKey,
-                },
-                persistSession: false,
             },
-        });
-        // 7. Collect messages
-        let finalResult = null;
-        let agentError = null;
-        // Fallback: capture StructuredOutput tool call input in case SDK fails to populate structured_output
-        let lastStructuredOutputInput = null;
-        const conversationFilePath = getConversationFilePath(browserSession.id);
-        conversationDir = dirname(conversationFilePath);
-        await mkdir(conversationDir, { recursive: true });
-        const TIMEOUT_MS = 59 * 60 * 1000;
-        const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new Error('Agent execution timed out after 59 minutes'));
-            }, TIMEOUT_MS);
-        });
-        try {
-            await Promise.race([
-                (async () => {
-                    for await (const message of result) {
-                        try {
-                            const jsonLine = JSON.stringify(message) + '\n';
-                            await appendFile(conversationFilePath, jsonLine, 'utf-8');
-                        }
-                        catch {
-                            // Ignore
-                        }
-                        const msg = message;
-                        // Capture StructuredOutput tool call input as fallback
-                        // This handles SDK bug where structured_output is not populated in result
-                        if (msg.type === 'assistant' && msg.message?.content) {
-                            for (const block of msg.message.content) {
-                                if (block.type === 'tool_use' &&
-                                    block.name === 'StructuredOutput' &&
-                                    block.input) {
-                                    lastStructuredOutputInput =
-                                        block.input;
-                                }
+            env: {
+                ...process.env,
+                ANTHROPIC_API_KEY: sessionToken,
+                ANTHROPIC_BASE_URL: getAiProxyUrl(),
+            },
+            persistSession: false,
+        },
+    });
+    // Collect messages
+    let finalResult = null;
+    let agentError = null;
+    let lastStructuredOutputInput = null;
+    let resultMeta = {};
+    const conversationFilePath = getConversationFilePath(browserSession.id);
+    const conversationDir = dirname(conversationFilePath);
+    await mkdir(conversationDir, { recursive: true });
+    const TIMEOUT_MS = 59 * 60 * 1000;
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error('Agent execution timed out after 59 minutes'));
+        }, TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([
+            (async () => {
+                for await (const message of result) {
+                    try {
+                        const jsonLine = JSON.stringify(message) + '\n';
+                        await appendFile(conversationFilePath, jsonLine, 'utf-8');
+                    }
+                    catch {
+                        // Ignore
+                    }
+                    const msg = message;
+                    // Capture StructuredOutput tool call input as fallback
+                    if (msg.type === 'assistant' && msg.message?.content) {
+                        for (const block of msg.message.content) {
+                            if (block.type === 'tool_use' &&
+                                block.name === 'StructuredOutput' &&
+                                block.input) {
+                                lastStructuredOutputInput =
+                                    block.input;
                             }
                         }
-                        if (msg.error) {
-                            let errorText = msg.error;
-                            if (msg.message?.content &&
-                                Array.isArray(msg.message.content)) {
-                                const texts = msg.message.content
-                                    .filter((c) => c.type === 'text')
-                                    .map((c) => c.text || '')
-                                    .filter(Boolean);
-                                if (texts.length > 0) {
-                                    errorText = texts.join(' ');
-                                }
+                    }
+                    if (msg.error) {
+                        let errorText = msg.error;
+                        if (msg.message?.content &&
+                            Array.isArray(msg.message.content)) {
+                            const texts = msg.message.content
+                                .filter((c) => c.type === 'text')
+                                .map((c) => c.text || '')
+                                .filter(Boolean);
+                            if (texts.length > 0) {
+                                errorText = texts.join(' ');
                             }
-                            agentError = errorText;
                         }
-                        if (message.type === 'result') {
-                            if (message.subtype === 'success' &&
-                                message.structured_output) {
-                                finalResult =
-                                    message.structured_output;
+                        agentError = errorText;
+                    }
+                    if (msg.type === 'result') {
+                        // Capture SDK result metadata
+                        resultMeta = {
+                            numTurns: msg.num_turns,
+                            totalCostUsd: msg.total_cost_usd,
+                            durationApiMs: msg.duration_api_ms,
+                            sdkDurationMs: msg.duration_ms,
+                            inputTokens: msg.usage?.input_tokens,
+                            outputTokens: msg.usage?.output_tokens,
+                            cacheReadTokens: msg.usage?.cache_read_input_tokens,
+                            cacheCreationTokens: msg.usage?.cache_creation_input_tokens,
+                        };
+                        if (msg.subtype === 'success' &&
+                            message.structured_output) {
+                            finalResult = message.structured_output;
+                        }
+                        else if (msg.subtype !== 'success') {
+                            if (lastStructuredOutputInput &&
+                                msg.errors?.length === 0) {
+                                finalResult = lastStructuredOutputInput;
+                                agentError = null;
                             }
-                            else if (message.subtype !== 'success') {
-                                // SDK bug workaround: If we got error_during_execution but have
-                                // a StructuredOutput tool call, use that instead
-                                if (lastStructuredOutputInput &&
-                                    message.errors?.length === 0) {
-                                    finalResult = lastStructuredOutputInput;
-                                    // Clear the error since we actually succeeded
-                                    agentError = null;
-                                }
-                                else if (!agentError) {
-                                    agentError =
-                                        message.errors?.join(', ') ||
-                                            'Unknown error';
-                                }
+                            else if (!agentError) {
+                                agentError =
+                                    msg.errors?.join(', ') || 'Unknown error';
                             }
                         }
                     }
-                })(),
-                timeoutPromise,
-            ]);
-        }
-        catch (error) {
-            agentError = error instanceof Error ? error.message : String(error);
-        }
-        const durationMs = Date.now() - startTime;
-        // 8. Upload trace, videos, screenshots with metadata, and update session
-        let traceDownloadUrl;
-        try {
-            const traceDir = getTraceDirectory(browserSession.id);
-            if (existsSync(traceDir)) {
-                const files = await readdir(traceDir);
-                if (files.length > 0) {
-                    // Upload trace zip
+                }
+            })(),
+            timeoutPromise,
+        ]);
+    }
+    catch (error) {
+        agentError = error instanceof Error ? error.message : String(error);
+    }
+    const durationMs = Date.now() - startTime;
+    telemetry.trackPhaseEnd('agent_execution', {
+        ...resultMeta,
+        toolCallCounts: Object.fromEntries(toolCallHook.toolCallCounts),
+        hasResult: !!finalResult,
+        hasError: !!agentError,
+    });
+    return {
+        featureId,
+        checklistItem,
+        browserSession,
+        finalResult,
+        agentError,
+        lastStructuredOutputInput,
+        screenshotHook,
+        toolCallCounts: toolCallHook.toolCallCounts,
+        configResult,
+        startTime,
+        durationMs,
+        conversationFilePath,
+        conversationDir,
+        isDebugMode,
+        debugOutcome: options.debugOutcome,
+        debugAddressComments: options.debugAddressComments,
+        resultMeta,
+        telemetry,
+        feedbackCommentIds: itemFeedback
+            ? itemFeedback.unaddressedComments.map((c) => c.id)
+            : [],
+    };
+}
+/**
+ * Phase 2: Upload artifacts, evaluate result, update scenario.
+ */
+async function processVerificationResult(ctx) {
+    const { featureId, checklistItem, browserSession, screenshotHook, durationMs, conversationFilePath, isDebugMode, debugOutcome, debugAddressComments, telemetry, feedbackCommentIds, } = ctx;
+    const { finalResult, agentError } = ctx;
+    let traceDownloadUrl;
+    // --- Upload trace ---
+    try {
+        const traceDir = getTraceDirectory(browserSession.id);
+        if (existsSync(traceDir)) {
+            const files = await readdir(traceDir);
+            if (files.length > 0) {
+                telemetry.trackPhaseStart('upload_trace');
+                try {
                     const traceUrls = await getUploadUrls(browserSession.id, 'trace.zip', 'zip');
                     const traceBuffer = await zipDirectory(traceDir);
                     await uploadTrace(traceUrls.uploadUrl, traceBuffer);
                     traceDownloadUrl = traceUrls.downloadUrl;
-                    // Upload videos from videos/ subdirectory
-                    const videos = await loadSessionVideos(traceDir);
-                    for (const video of videos) {
-                        try {
-                            const videoBuffer = await readFile(video.path);
-                            const videoUrls = await getUploadUrls(browserSession.id, video.filename, 'webm');
-                            await uploadVideo(videoUrls.uploadUrl, videoBuffer);
-                        }
-                        catch {
-                            // Ignore individual video upload errors
-                        }
+                    telemetry.trackPhaseEnd('upload_trace', {
+                        bytes: traceBuffer.length,
+                    });
+                }
+                catch (err) {
+                    await telemetry.trackPhaseError('upload_trace', err);
+                }
+                // --- Upload videos ---
+                const videos = await loadSessionVideos(traceDir);
+                for (const video of videos) {
+                    telemetry.trackPhaseStart('upload_video', {
+                        filename: video.filename,
+                    });
+                    try {
+                        const videoBuffer = await readFile(video.path);
+                        const videoUrls = await getUploadUrls(browserSession.id, video.filename, 'webm');
+                        await uploadVideo(videoUrls.uploadUrl, videoBuffer);
+                        telemetry.trackPhaseEnd('upload_video', {
+                            filename: video.filename,
+                            bytes: videoBuffer.length,
+                        });
                     }
-                    // Create verification steps and upload screenshots as step assets
-                    // Filter out screenshots already uploaded by the PostToolUse hook
-                    const pngFiles = files
-                        .filter((f) => f.toLowerCase().endsWith('.png'))
-                        .filter((f) => !screenshotHook.uploadedFiles.has(f))
-                        .sort(); // Sort to maintain order by filename (01_, 02_, etc.)
-                    // Start position after any screenshots already uploaded by the hook
-                    const positionOffset = screenshotHook.uploadedFiles.size + 1;
-                    for (let i = 0; i < pngFiles.length; i++) {
-                        const pngFile = pngFiles[i];
-                        try {
-                            const pngPath = join(traceDir, pngFile);
-                            const pngBuffer = await readFile(pngPath);
-                            const pngStat = await stat(pngPath);
-                            // Detect "key_" prefix for high-priority screenshots
-                            const isKeyFrame = pngFile
-                                .toLowerCase()
-                                .startsWith('key_');
-                            const displayName = pngFile
-                                .replace(/\.png$/i, '')
-                                .replace(/^key_/i, '')
-                                .replace(/^\d+_/, '')
-                                .replace(/-/g, ' ');
-                            // Create a verification step for this screenshot
-                            const { step } = await createVerificationStep(browserSession.id, {
-                                checklistItemId: checklistItem.id,
-                                position: positionOffset + i,
-                                stepType: 'screenshot',
-                                stepName: displayName,
-                                description: isKeyFrame
-                                    ? 'Key moment captured during verification'
-                                    : 'Screenshot captured during verification',
-                                isKeyStep: isKeyFrame,
-                                status: 'success',
-                                metadata: {
-                                    filename: pngFile,
-                                    timestamp: pngStat.mtime.toISOString(),
-                                },
-                            });
-                            // Create step asset with upload URL
-                            const assetResponse = await createStepAsset(browserSession.id, step.id, {
+                    catch (err) {
+                        await telemetry.trackPhaseError('upload_video', err, {
+                            filename: video.filename,
+                        });
+                    }
+                }
+                // --- Upload remaining screenshots ---
+                const pngFiles = files
+                    .filter((f) => f.toLowerCase().endsWith('.png'))
+                    .filter((f) => !screenshotHook.uploadedFiles.has(f))
+                    .sort();
+                const positionOffset = screenshotHook.uploadedFiles.size + 1;
+                for (let i = 0; i < pngFiles.length; i++) {
+                    const pngFile = pngFiles[i];
+                    const isKeyFrame = pngFile.toLowerCase().startsWith('key_');
+                    telemetry.trackPhaseStart('upload_screenshot', {
+                        filename: pngFile,
+                        isKeyFrame,
+                    });
+                    try {
+                        const pngPath = join(traceDir, pngFile);
+                        const pngBuffer = await readFile(pngPath);
+                        const pngStat = await stat(pngPath);
+                        const displayName = pngFile
+                            .replace(/\.png$/i, '')
+                            .replace(/^key_/i, '')
+                            .replace(/^\d+_/, '')
+                            .replace(/-/g, ' ');
+                        const { step } = await createVerificationStep(browserSession.id, {
+                            checklistItemId: checklistItem.id,
+                            position: positionOffset + i,
+                            stepType: 'screenshot',
+                            stepName: displayName,
+                            description: isKeyFrame
+                                ? 'Key moment captured during verification'
+                                : 'Screenshot captured during verification',
+                            isKeyStep: isKeyFrame,
+                            status: 'success',
+                            metadata: {
                                 filename: pngFile,
-                                assetType: 'screenshot',
-                                timing: 'after',
-                                position: 0,
-                                capturedAt: pngStat.mtime.toISOString(),
-                                metadata: {
-                                    name: displayName,
-                                    highPriority: isKeyFrame,
-                                },
-                            });
-                            // Upload the screenshot to the signed URL
-                            await uploadScreenshot(assetResponse.uploadUrl, pngBuffer);
-                        }
-                        catch {
-                            // Ignore individual screenshot upload errors
-                        }
+                                timestamp: pngStat.mtime.toISOString(),
+                            },
+                        });
+                        const assetResponse = await createStepAsset(browserSession.id, step.id, {
+                            filename: pngFile,
+                            assetType: 'screenshot',
+                            timing: 'after',
+                            position: 0,
+                            capturedAt: pngStat.mtime.toISOString(),
+                            metadata: {
+                                name: displayName,
+                                highPriority: isKeyFrame,
+                            },
+                        });
+                        await uploadScreenshot(assetResponse.uploadUrl, pngBuffer);
+                        telemetry.trackPhaseEnd('upload_screenshot', {
+                            filename: pngFile,
+                            bytes: pngBuffer.length,
+                        });
+                    }
+                    catch (err) {
+                        await telemetry.trackPhaseError('upload_screenshot', err, { filename: pngFile });
                     }
                 }
             }
-            if (existsSync(conversationFilePath)) {
-                try {
-                    const conversationUrls = await getUploadUrls(browserSession.id, 'conversation.jsonl', 'jsonl');
-                    const conversationBuffer = await readFile(conversationFilePath);
-                    await uploadConversation(conversationUrls.uploadUrl, conversationBuffer);
-                }
-                catch {
-                    // Ignore
-                }
+        }
+        // --- Upload conversation ---
+        if (existsSync(conversationFilePath)) {
+            telemetry.trackPhaseStart('upload_conversation');
+            try {
+                const conversationUrls = await getUploadUrls(browserSession.id, 'conversation.jsonl', 'jsonl');
+                const conversationBuffer = await readFile(conversationFilePath);
+                await uploadConversation(conversationUrls.uploadUrl, conversationBuffer);
+                telemetry.trackPhaseEnd('upload_conversation', {
+                    bytes: conversationBuffer.length,
+                });
             }
-            // Cast to help TypeScript understand the type after complex control flow
+            catch (err) {
+                await telemetry.trackPhaseError('upload_conversation', err);
+            }
+        }
+        // --- Update browser session ---
+        telemetry.trackPhaseStart('update_session');
+        try {
             const typedResult = finalResult;
             const updateData = {
                 status: (agentError ? 'failed' : 'completed'),
@@ -933,121 +1101,243 @@ Return your findings in the structured output format with your evaluation.`;
                 typedResult.durationMs = durationMs;
                 typedResult.checklistItemId = checklistItem.id;
             }
+            telemetry.trackPhaseEnd('update_session');
         }
-        catch {
-            // Ignore upload errors
+        catch (err) {
+            await telemetry.trackPhaseError('update_session', err);
         }
-        // 9. Determine the result to use for evaluation
-        // In debug mode, use mock evaluation; otherwise use agent result
-        let resultForEval;
-        if (isDebugMode && options.debugOutcome) {
-            const mockEval = getMockEvaluation(options.debugOutcome);
-            resultForEval = {
-                ...mockEval,
-                sessionId: browserSession.id,
-                sessionDir: getTraceDirectory(browserSession.id),
-                durationMs,
-                traceViewerUrl: traceDownloadUrl
-                    ? buildTraceViewerUrl(traceDownloadUrl)
-                    : undefined,
-                checklistItemId: checklistItem.id,
-            };
-            console.log(`\n[DEBUG MODE] Using mock evaluation: ${options.debugOutcome}`);
+    }
+    catch {
+        // Ignore upload errors
+    }
+    // --- Phase: evaluation ---
+    telemetry.trackPhaseStart('evaluation');
+    let resultForEval;
+    if (isDebugMode && debugOutcome) {
+        const mockEval = getMockEvaluation(debugOutcome);
+        const typedResult = finalResult;
+        resultForEval = {
+            ...mockEval,
+            sessionId: browserSession.id,
+            sessionDir: getTraceDirectory(browserSession.id),
+            durationMs,
+            traceViewerUrl: traceDownloadUrl
+                ? buildTraceViewerUrl(traceDownloadUrl)
+                : undefined,
+            checklistItemId: checklistItem.id,
+            addressedCommentIds: typedResult?.addressedCommentIds ?? [],
+        };
+        console.log(`\n[DEBUG MODE] Using mock evaluation: ${debugOutcome}`);
+    }
+    else {
+        const typedResult = finalResult;
+        if (agentError && !typedResult) {
+            throw new Error(`Verification failed: ${agentError}`);
         }
-        else {
-            const typedResult = finalResult;
-            if (agentError && !typedResult) {
-                throw new Error(`Verification failed: ${agentError}`);
-            }
-            if (!typedResult) {
-                throw new Error('No result received from agent');
+        if (!typedResult) {
+            throw new Error('No result received from agent');
+        }
+        resultForEval = typedResult;
+    }
+    telemetry.trackPhaseEnd('evaluation', {
+        evaluation: resultForEval.evaluation,
+        issueCount: resultForEval.issues?.length ?? 0,
+    });
+    // --- Phase: scenario_update ---
+    telemetry.trackPhaseStart('scenario_update');
+    const evaluation = resultForEval.evaluation;
+    if (evaluation === 'verified') {
+        await updateChecklistItem(featureId, checklistItem.id, {
+            status: 'verified',
+            browserSessionId: browserSession.id,
+        });
+        console.log(`\n\u2705 Scenario verified!`);
+    }
+    else if (evaluation === 'blocked') {
+        await updateChecklistItem(featureId, checklistItem.id, {
+            status: 'blocked',
+            browserSessionId: browserSession.id,
+            blockedReason: resultForEval.evaluationReason,
+        });
+        // Enhanced output for Claude Code
+        console.log(`\n${'='.repeat(60)}`);
+        console.log(`BLOCKING ISSUE DETECTED - Debug Required`);
+        console.log(`${'='.repeat(60)}`);
+        console.log(`\nIssue: ${resultForEval.evaluationReason}`);
+        if (resultForEval.issues?.length) {
+            console.log(`\nDetails:`);
+            for (const issue of resultForEval.issues) {
+                const typeStr = issue.type ? ` (${issue.type})` : '';
+                console.log(`  - [${issue.severity}]${typeStr} ${issue.description}`);
             }
-            resultForEval = typedResult;
         }
-        // 10. Update checklist item based on evaluation
-        const evaluation = resultForEval.evaluation;
-        if (evaluation === 'verified') {
-            await updateChecklistItem(featureId, checklistItem.id, {
-                status: 'verified',
-                browserSessionId: browserSession.id,
-            });
-            console.log(`\n\u2705 Checklist item verified!`);
+        if (resultForEval.traceViewerUrl) {
+            console.log(`\nTrace: ${resultForEval.traceViewerUrl}`);
         }
-        else if (evaluation === 'blocked') {
-            await updateChecklistItem(featureId, checklistItem.id, {
-                status: 'blocked',
-                browserSessionId: browserSession.id,
-                blockedReason: resultForEval.evaluationReason,
+        console.log(`\nSuggested action: Debug this issue in your code, then run go again.`);
+        console.log(`${'='.repeat(60)}\n`);
+    }
+    else if (evaluation === 'partial' ||
+        evaluation === 'failed' ||
+        evaluation === 'incomplete') {
+        // Mark as incomplete - verification happened but requirements not fully met
+        await updateChecklistItem(featureId, checklistItem.id, {
+            status: 'incomplete',
+            browserSessionId: browserSession.id,
+            incompleteReason: resultForEval.evaluationReason,
+        });
+        // Check if other items are terminal and prompt user
+        await handleIncompleteItem(featureId, checklistItem, resultForEval);
+    }
+    telemetry.trackPhaseEnd('scenario_update', { newStatus: evaluation });
+    // --- Phase: comment_addressing ---
+    telemetry.trackPhaseStart('comment_addressing', {
+        totalFeedbackComments: feedbackCommentIds.length,
+        agentAddressedCount: resultForEval.addressedCommentIds?.length ?? 0,
+    });
+    const addressedIds = resultForEval.addressedCommentIds?.filter((id) => feedbackCommentIds.includes(id));
+    if (addressedIds && addressedIds.length > 0) {
+        try {
+            await markCommentsAddressed(featureId, checklistItem.id, addressedIds);
+            console.log(`Marked ${addressedIds.length} comment(s) as addressed`);
+            telemetry.trackPhaseEnd('comment_addressing', {
+                addressedCount: addressedIds.length,
             });
-            // Enhanced output for Claude Code
-            console.log(`\n${'='.repeat(60)}`);
-            console.log(`BLOCKING ISSUE DETECTED - Debug Required`);
-            console.log(`${'='.repeat(60)}`);
-            console.log(`\nIssue: ${resultForEval.evaluationReason}`);
-            if (resultForEval.issues?.length) {
-                console.log(`\nDetails:`);
-                for (const issue of resultForEval.issues) {
-                    const typeStr = issue.type ? ` (${issue.type})` : '';
-                    console.log(`  - [${issue.severity}]${typeStr} ${issue.description}`);
-                }
+        }
+        catch (err) {
+            await telemetry.trackPhaseError('comment_addressing', err);
+        }
+    }
+    else {
+        telemetry.trackPhaseEnd('comment_addressing', {
+            addressedCount: 0,
+        });
+    }
+    return resultForEval;
+}
+/**
+ * Verify a scenario in the browser.
+ * Orchestrates runVerification -> processVerificationResult with telemetry.
+ */
+export async function verifyFeature(options) {
+    const telemetry = createTelemetryCollector('go');
+    await telemetry.trackCommandStart({
+        hasProfile: !!options.profile,
+        hasScenario: options.scenario !== undefined,
+        hasNotes: !!options.notes,
+        isDebugMode: !!options.debugOutcome,
+    });
+    const { envNames } = await getEnvNames();
+    if (envNames.length === 0) {
+        throw new Error(formatProfileRequiredMessage((text) => bold(text)));
+    }
+    let ctx;
+    let interrupted = false;
+    let checklistItemResolved = false;
+    const handleInterrupt = async () => {
+        if (interrupted)
+            return;
+        interrupted = true;
+        console.log('\nVerification interrupted. Cleaning up...');
+        await telemetry.trackCommandEnd('interrupted', {
+            durationMs: ctx ? Date.now() - ctx.startTime : 0,
+        });
+        if (ctx) {
+            try {
+                await updateBrowserSession(ctx.browserSession.id, {
+                    status: 'interrupted',
+                    durationMs: Date.now() - ctx.startTime,
+                });
             }
-            if (resultForEval.traceViewerUrl) {
-                console.log(`\nTrace: ${resultForEval.traceViewerUrl}`);
+            catch {
+                // Best effort
+            }
+            try {
+                await updateChecklistItem(ctx.featureId, ctx.checklistItem.id, {
+                    status: 'pending',
+                });
+            }
+            catch {
+                // Best effort
+            }
+            if (ctx.configResult) {
+                try {
+                    await cleanupTempFiles(ctx.configResult);
+                }
+                catch {
+                    // Best effort
+                }
             }
-            console.log(`\nSuggested action: Debug this issue in your code, then run verify-feature again.`);
-            console.log(`${'='.repeat(60)}\n`);
-        }
-        else if (evaluation === 'partial' || evaluation === 'failed') {
-            // Mark as incomplete - verification happened but requirements not fully met
-            await updateChecklistItem(featureId, checklistItem.id, {
-                status: 'incomplete',
-                browserSessionId: browserSession.id,
-                incompleteReason: resultForEval.evaluationReason,
-            });
-            // Check if other items are terminal and prompt user
-            await handleIncompleteItem(featureId, checklistItem, resultForEval);
         }
+        console.log('Scenario reset to pending. Partial steps are preserved.');
+        process.exit(0);
+    };
+    process.on('SIGINT', handleInterrupt);
+    process.on('SIGTERM', handleInterrupt);
+    try {
+        // Phase 1: Setup + agent execution
+        ctx = await runVerification(options, telemetry);
+        // Boundary flush — all agent execution telemetry is now safe
+        await telemetry.flush();
+        // Phase 2: Uploads + evaluation + status update
+        const resultForEval = await processVerificationResult(ctx);
         checklistItemResolved = true;
+        await telemetry.trackCommandEnd('success', {
+            evaluation: resultForEval.evaluation,
+            durationMs: ctx.durationMs,
+            ...ctx.resultMeta,
+        });
         return resultForEval;
     }
+    catch (error) {
+        await telemetry.trackCommandError(error);
+        throw error;
+    }
     finally {
-        // Remove interrupt handlers to avoid double-firing after normal completion
         process.removeListener('SIGINT', handleInterrupt);
         process.removeListener('SIGTERM', handleInterrupt);
-        // If the checklist item was never resolved (agent error, throw, etc.),
+        // If the scenario was never resolved (agent error, throw, etc.),
         // reset it to pending so it doesn't stay stuck in verification_in_progress.
-        if (!interrupted && !checklistItemResolved) {
+        if (ctx && !interrupted && !checklistItemResolved) {
             try {
-                await updateChecklistItem(featureId, checklistItem.id, {
+                await updateChecklistItem(ctx.featureId, ctx.checklistItem.id, {
                     status: 'pending',
                 });
-                console.log('Checklist item reset to pending after unexpected error.');
+                console.log('Scenario reset to pending after unexpected error.');
             }
-            catch {
-                // Best effort
+            catch (resetErr) {
+                await telemetry.trackPhaseError('scenario_reset', resetErr);
             }
         }
-        // Cleanup
-        if (configResult) {
-            await cleanupTempFiles(configResult);
-        }
-        try {
-            const traceDir = getTraceDirectory(browserSession.id);
-            if (existsSync(traceDir)) {
-                await rm(traceDir, { recursive: true, force: true });
+        // --- Phase: cleanup ---
+        if (ctx) {
+            telemetry.trackPhaseStart('cleanup');
+            if (ctx.configResult) {
+                await cleanupTempFiles(ctx.configResult);
             }
-        }
-        catch {
-            // Ignore
-        }
-        try {
-            if (conversationDir && existsSync(conversationDir)) {
-                await rm(conversationDir, { recursive: true, force: true });
+            try {
+                const traceDir = getTraceDirectory(ctx.browserSession.id);
+                if (existsSync(traceDir)) {
+                    await rm(traceDir, { recursive: true, force: true });
+                }
             }
+            catch {
+                // Ignore
+            }
+            try {
+                if (ctx.conversationDir && existsSync(ctx.conversationDir)) {
+                    await rm(ctx.conversationDir, {
+                        recursive: true,
+                        force: true,
+                    });
+                }
+            }
+            catch {
+                // Ignore
+            }
+            telemetry.trackPhaseEnd('cleanup');
         }
-        catch {
-            // Ignore
-        }
+        await telemetry.flush();
     }
 }
 //# sourceMappingURL=verifyFeature.js.map