browser-debug-mcp-bridge 1.9.0 → 1.11.0

package/apps/mcp-server/dist/mcp/server.js

@@ -1,9 +1,20 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { existsSync, readFileSync } from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { dirname, resolve } from 'path';
+import { z } from 'zod';
 import { getConnection } from '../db/connection.js';
+import { diagnoseOverridePoc, insertOverridePlanAudit, listOverridePlanAudits, listOverridePocRequests, listOverridePocRuns, } from '../override-audit.js';
+import { createOverrideProfileConfig, OVERRIDE_PROFILE_ADAPTERS, } from '../override-profile-generator.js';
+import { assertOverrideResponseRequestCaptureSafe, classifyOverrideResponseRequestCapability, } from '../override-capabilities.js';
+import { getOverridePocConfigSummary } from '../override-poc.js';
+import { normalizeOverrideRequestMethod } from '../override-rule-types.js';
+import { mapNextOverrideAssetsWithDrift } from '../next-asset-mapper.js';
+import { planNextSourceOverride } from '../next-source-override-planner.js';
+import { listObservedOverrideAssets, persistObservedOverrideAssets } from '../override-observed-assets.js';
+import { planOverrideResponsePatch } from '../override-response-planner.js';
 function createDefaultMcpLogger() {
     const write = (level, message, payload) => {
         process.stderr.write(`${message} ${JSON.stringify({ level, ...payload })}\n`);
@@ -20,6 +31,238 @@ function createDefaultMcpLogger() {
         },
     };
 }
+const LiveUIActionTargetSchema = z.object({
+    selector: z.string().min(1).optional(),
+    elementRef: z.string().min(1).optional(),
+    tabId: z.number().int().min(0).optional(),
+    frameId: z.number().int().min(0).optional(),
+    url: z.string().url().optional(),
+});
+const LiveUIActionBaseSchema = z.object({
+    traceId: z.string().min(1).optional(),
+    target: LiveUIActionTargetSchema.optional(),
+});
+const LiveUIActionRequestSchema = z.discriminatedUnion('action', [
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('click'),
+        input: z.object({
+            button: z.enum(['left', 'middle', 'right']).optional(),
+            clickCount: z.number().int().min(1).max(3).optional(),
+        }).optional(),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('input'),
+        input: z.object({
+            value: z.string(),
+        }),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('focus'),
+        input: z.object({}).optional(),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('blur'),
+        input: z.object({}).optional(),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('scroll'),
+        input: z.object({
+            x: z.number().optional(),
+            y: z.number().optional(),
+            behavior: z.enum(['auto', 'smooth']).optional(),
+        }).optional(),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('press_key'),
+        input: z.object({
+            key: z.string().min(1),
+            altKey: z.boolean().optional(),
+            ctrlKey: z.boolean().optional(),
+            metaKey: z.boolean().optional(),
+            shiftKey: z.boolean().optional(),
+        }),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('submit'),
+        input: z.object({}).optional(),
+    }),
+    LiveUIActionBaseSchema.extend({
+        action: z.literal('reload'),
+        input: z.object({
+            ignoreCache: z.boolean().optional(),
+        }).optional(),
+    }),
+]);
+const UIWorkflowModeSchema = z.enum(['safe', 'fast']);
+const UIWorkflowFailureStrategySchema = z.enum(['stop', 'continue', 'retry_once']);
+const UIWorkflowActionTargetScopeSchema = z.enum(['buttons', 'inputs', 'modals', 'focused']);
+const UIWorkflowActionTargetSchema = z.object({
+    selector: z.string().min(1).optional(),
+    elementRef: z.string().min(1).optional(),
+    tabId: z.number().int().min(0).optional(),
+    frameId: z.number().int().min(0).optional(),
+    url: z.string().url().optional(),
+    testId: z.string().min(1).optional(),
+    scope: UIWorkflowActionTargetScopeSchema.optional(),
+    textContains: z.string().min(1).optional(),
+    labelContains: z.string().min(1).optional(),
+    titleContains: z.string().min(1).optional(),
+    tagName: z.string().min(1).optional(),
+    type: z.string().min(1).optional(),
+    disabled: z.boolean().optional(),
+    selected: z.boolean().optional(),
+    pressed: z.boolean().optional(),
+    expanded: z.boolean().optional(),
+    readOnly: z.boolean().optional(),
+    requiredField: z.boolean().optional(),
+}).superRefine((value, ctx) => {
+    if (!value.selector
+        && !value.elementRef
+        && !value.testId
+        && !value.textContains
+        && !value.labelContains
+        && !value.titleContains) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'target requires selector, elementRef, testId, textContains, labelContains, or titleContains',
+            path: ['target'],
+        });
+    }
+});
+const UIWorkflowFailureCaptureSchema = z.object({
+    enabled: z.boolean().optional(),
+    selector: z.string().min(1).optional(),
+    mode: z.enum(['dom', 'png', 'both']).optional(),
+    styleMode: z.enum(['computed-lite', 'computed-full']).optional(),
+    maxDepth: z.number().int().min(1).max(10).optional(),
+    maxBytes: z.number().int().min(1_000).max(200_000).optional(),
+    maxAncestors: z.number().int().min(0).max(10).optional(),
+    includeDom: z.boolean().optional(),
+    includeStyles: z.boolean().optional(),
+    includePngDataUrl: z.boolean().optional(),
+});
+const UIWorkflowFailurePolicySchema = z.object({
+    strategy: UIWorkflowFailureStrategySchema.optional(),
+    capture: UIWorkflowFailureCaptureSchema.optional(),
+});
+const UIWorkflowStepBaseSchema = z.object({
+    id: z.string().min(1).optional(),
+    note: z.string().min(1).optional(),
+    onFailure: UIWorkflowFailurePolicySchema.optional(),
+});
+const UIWorkflowActionBaseSchema = UIWorkflowStepBaseSchema.extend({
+    kind: z.literal('action'),
+    traceId: z.string().min(1).optional(),
+    target: UIWorkflowActionTargetSchema.optional(),
+});
+const UIWorkflowActionStepSchema = z.discriminatedUnion('action', [
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('click'),
+        input: z.object({
+            button: z.enum(['left', 'middle', 'right']).optional(),
+            clickCount: z.number().int().min(1).max(3).optional(),
+        }).optional(),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('input'),
+        input: z.object({
+            value: z.string(),
+        }),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('focus'),
+        input: z.object({}).optional(),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('blur'),
+        input: z.object({}).optional(),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('scroll'),
+        input: z.object({
+            x: z.number().optional(),
+            y: z.number().optional(),
+            behavior: z.enum(['auto', 'smooth']).optional(),
+        }).optional(),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('press_key'),
+        input: z.object({
+            key: z.string().min(1),
+            altKey: z.boolean().optional(),
+            ctrlKey: z.boolean().optional(),
+            metaKey: z.boolean().optional(),
+            shiftKey: z.boolean().optional(),
+        }),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('submit'),
+        input: z.object({}).optional(),
+    }),
+    UIWorkflowActionBaseSchema.extend({
+        action: z.literal('reload'),
+        input: z.object({
+            ignoreCache: z.boolean().optional(),
+        }).optional(),
+    }),
+]);
+const UIWorkflowPageStateMatcherSchema = z.object({
+    scope: z.enum(['buttons', 'inputs', 'modals', 'focused', 'page']),
+    selector: z.string().optional(),
+    testId: z.string().optional(),
+    textContains: z.string().optional(),
+    labelContains: z.string().optional(),
+    titleContains: z.string().optional(),
+    urlContains: z.string().optional(),
+    language: z.string().optional(),
+    disabled: z.boolean().optional(),
+    selected: z.boolean().optional(),
+    pressed: z.boolean().optional(),
+    expanded: z.boolean().optional(),
+    readOnly: z.boolean().optional(),
+    requiredField: z.boolean().optional(),
+    tagName: z.string().optional(),
+    type: z.string().optional(),
+    countExactly: z.number().int().min(0).optional(),
+    countAtLeast: z.number().int().min(0).optional(),
+    maxItems: z.number().int().min(1).max(100).optional(),
+    maxTextLength: z.number().int().min(8).max(200).optional(),
+}).superRefine((value, ctx) => {
+    if (value.countExactly !== undefined && value.countAtLeast !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'countExactly and countAtLeast cannot both be set',
+            path: ['countExactly'],
+        });
+    }
+});
+const UIWorkflowWaitForStepSchema = UIWorkflowStepBaseSchema.extend({
+    kind: z.literal('waitFor'),
+    matcher: UIWorkflowPageStateMatcherSchema.extend({
+        timeoutMs: z.number().int().min(100).max(30000).optional(),
+        pollIntervalMs: z.number().int().min(50).max(2000).optional(),
+    }),
+});
+const UIWorkflowAssertStepSchema = UIWorkflowStepBaseSchema.extend({
+    kind: z.literal('assert'),
+    matcher: UIWorkflowPageStateMatcherSchema,
+});
+const UIWorkflowStepSchema = z.discriminatedUnion('kind', [
+    UIWorkflowActionStepSchema,
+    UIWorkflowWaitForStepSchema,
+    UIWorkflowAssertStepSchema,
+]);
+const RunUIStepsSchema = z.object({
+    sessionId: z.string().min(1),
+    mode: UIWorkflowModeSchema.default('safe'),
+    stopOnFailure: z.boolean().default(true),
+    defaultTimeoutMs: z.number().int().min(100).max(30000).optional(),
+    defaultPollIntervalMs: z.number().int().min(50).max(2000).optional(),
+    steps: z.array(UIWorkflowStepSchema).min(1).max(50),
+});
+function createUIWorkflowTraceId() {
+    return `uiworkflow-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
 const TOOL_SCHEMAS = {
     list_sessions: {
         type: 'object',
@@ -37,6 +280,13 @@ const TOOL_SCHEMAS = {
             sessionId: { type: 'string' },
         },
     },
+    get_live_session_health: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+        },
+    },
     get_recent_events: {
         type: 'object',
         properties: {
@@ -212,6 +462,96 @@ const TOOL_SCHEMAS = {
             selector: { type: 'string' },
         },
     },
+    get_page_state: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            maxItems: { type: 'number' },
+            maxTextLength: { type: 'number' },
+            includeButtons: { type: 'boolean' },
+            includeInputs: { type: 'boolean' },
+            includeModals: { type: 'boolean' },
+        },
+    },
+    get_interactive_elements: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            kinds: {
+                type: 'array',
+                items: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused'] },
+            },
+            maxItems: { type: 'number' },
+            maxTextLength: { type: 'number' },
+        },
+    },
+    set_viewport: {
+        type: 'object',
+        required: ['sessionId', 'width', 'height'],
+        properties: {
+            sessionId: { type: 'string' },
+            width: { type: 'number' },
+            height: { type: 'number' },
+        },
+    },
+    assert_page_state: {
+        type: 'object',
+        required: ['sessionId', 'scope'],
+        properties: {
+            sessionId: { type: 'string' },
+            scope: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused', 'page'] },
+            selector: { type: 'string' },
+            testId: { type: 'string' },
+            textContains: { type: 'string' },
+            labelContains: { type: 'string' },
+            titleContains: { type: 'string' },
+            urlContains: { type: 'string' },
+            language: { type: 'string' },
+            disabled: { type: 'boolean' },
+            selected: { type: 'boolean' },
+            pressed: { type: 'boolean' },
+            expanded: { type: 'boolean' },
+            readOnly: { type: 'boolean' },
+            requiredField: { type: 'boolean' },
+            tagName: { type: 'string' },
+            type: { type: 'string' },
+            countExactly: { type: 'number' },
+            countAtLeast: { type: 'number' },
+            maxItems: { type: 'number' },
+            maxTextLength: { type: 'number' },
+        },
+    },
+    wait_for_page_state: {
+        type: 'object',
+        required: ['sessionId', 'scope'],
+        properties: {
+            sessionId: { type: 'string' },
+            scope: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused', 'page'] },
+            selector: { type: 'string' },
+            testId: { type: 'string' },
+            textContains: { type: 'string' },
+            labelContains: { type: 'string' },
+            titleContains: { type: 'string' },
+            urlContains: { type: 'string' },
+            language: { type: 'string' },
+            disabled: { type: 'boolean' },
+            selected: { type: 'boolean' },
+            pressed: { type: 'boolean' },
+            expanded: { type: 'boolean' },
+            readOnly: { type: 'boolean' },
+            requiredField: { type: 'boolean' },
+            tagName: { type: 'string' },
+            type: { type: 'string' },
+            countExactly: { type: 'number' },
+            countAtLeast: { type: 'number' },
+            maxItems: { type: 'number' },
+            maxTextLength: { type: 'number' },
+            timeoutMs: { type: 'number' },
+            pollIntervalMs: { type: 'number' },
+        },
+    },
     capture_ui_snapshot: {
         type: 'object',
         required: ['sessionId'],
@@ -247,6 +587,223 @@ const TOOL_SCHEMAS = {
             maxResponseBytes: { type: 'number' },
         },
     },
+    list_override_profiles: {
+        type: 'object',
+        properties: {},
+    },
+    create_override_profile: {
+        type: 'object',
+        required: ['targetBaseUrl'],
+        properties: {
+            adapter: { type: 'string' },
+            mode: { type: 'string' },
+            targetBaseUrl: { type: 'string' },
+            projectRoot: { type: 'string' },
+            assetRoot: { type: 'string' },
+            nextDir: { type: 'string' },
+            configPath: { type: 'string' },
+            profileId: { type: 'string' },
+            profileName: { type: 'string' },
+            enabled: { type: 'boolean' },
+            profileEnabled: { type: 'boolean' },
+            autoReload: { type: 'boolean' },
+            includeManifestFiles: { type: 'boolean' },
+            includeStaticFiles: { type: 'boolean' },
+            extensions: { type: 'array', items: { type: 'string' } },
+            maxRules: { type: 'number' },
+            writeConfig: { type: 'boolean' },
+            overwrite: { type: 'boolean' },
+        },
+    },
+    validate_override_profile: {
+        type: 'object',
+        properties: {
+            profileId: { type: 'string' },
+        },
+    },
+    preflight_overrides: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            profileId: { type: 'string' },
+        },
+    },
+    observe_override_assets: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            includePerformance: { type: 'boolean' },
+        },
+    },
+    capture_override_response_body: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            targetUrl: { type: 'string' },
+            targetAssetUrl: { type: 'string' },
+            captureMode: { type: 'string', enum: ['extension-fetch', 'cdp-response'] },
+            triggerReload: { type: 'boolean' },
+            matchMode: { type: 'string', enum: ['exact', 'prefix'] },
+            requestMethod: { type: 'string' },
+            requestHeaders: { type: 'object' },
+            timeoutMs: { type: 'number' },
+            maxBodyBytes: { type: 'number' },
+            includeBody: { type: 'boolean' },
+        },
+    },
+    list_observed_override_assets: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            limit: { type: 'number' },
+            sinceTimestamp: { type: 'number' },
+        },
+    },
+    map_next_override_assets: {
+        type: 'object',
+        required: ['projectRoot'],
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            projectRoot: { type: 'string' },
+            nextDir: { type: 'string' },
+            route: { type: 'string' },
+            sourcePaths: { type: 'array', items: { type: 'string' } },
+            observedAssets: { type: 'array', items: { type: 'object' } },
+            maxResults: { type: 'number' },
+            fetchProductionAssets: { type: 'boolean' },
+            productionFetchTimeoutMs: { type: 'number' },
+            maxProductionAssetBytes: { type: 'number' },
+            maxDriftCandidates: { type: 'number' },
+            productionFetchConcurrency: { type: 'number' },
+        },
+    },
+    plan_override_response_patch: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            targetUrl: { type: 'string' },
+            targetAssetUrl: { type: 'string' },
+            captureMode: { type: 'string', enum: ['extension-fetch', 'cdp-response'] },
+            triggerReload: { type: 'boolean' },
+            ruleType: { type: 'string' },
+            requestMethod: { type: 'string' },
+            matchMode: { type: 'string', enum: ['exact', 'prefix'] },
+            requestHeaders: { type: 'object' },
+            timeoutMs: { type: 'number' },
+            contentType: { type: 'string' },
+            responseBodyText: { type: 'string' },
+            bodyText: { type: 'string' },
+            responseBodyBase64: { type: 'string' },
+            bodyBase64: { type: 'string' },
+            textPatches: { type: 'array', items: { type: 'object' } },
+            jsonPatches: { type: 'array', items: { type: 'object' } },
+            documentPatches: { type: 'array', items: { type: 'object' } },
+            maxBodyBytes: { type: 'number' },
+            outputRoot: { type: 'string' },
+            configPath: { type: 'string' },
+            writeBody: { type: 'boolean' },
+            writeConfig: { type: 'boolean' },
+            overwrite: { type: 'boolean' },
+            enabled: { type: 'boolean' },
+            profileEnabled: { type: 'boolean' },
+            autoReload: { type: 'boolean' },
+            profileId: { type: 'string' },
+            profileName: { type: 'string' },
+            ruleId: { type: 'string' },
+            includePreview: { type: 'boolean' },
+        },
+    },
+    plan_next_source_override: {
+        type: 'object',
+        required: ['projectRoot', 'sourceEdits'],
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            projectRoot: { type: 'string' },
+            nextDir: { type: 'string' },
+            route: { type: 'string' },
+            sourcePaths: { type: 'array', items: { type: 'string' } },
+            sourceEdits: { type: 'array', items: { type: 'object' } },
+            observedAssets: { type: 'array', items: { type: 'object' } },
+            configPath: { type: 'string' },
+            writeConfig: { type: 'boolean' },
+            overwrite: { type: 'boolean' },
+            enabled: { type: 'boolean' },
+            profileEnabled: { type: 'boolean' },
+            autoReload: { type: 'boolean' },
+            profileId: { type: 'string' },
+            profileName: { type: 'string' },
+            buildTimeoutMs: { type: 'number' },
+            maxRules: { type: 'number' },
+            fetchProductionAssets: { type: 'boolean' },
+            productionFetchTimeoutMs: { type: 'number' },
+            maxProductionAssetBytes: { type: 'number' },
+            maxDriftCandidates: { type: 'number' },
+            productionFetchConcurrency: { type: 'number' },
+            overlayTtlMs: { type: 'number' },
+        },
+    },
+    enable_overrides: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            tabId: { type: 'number' },
+            profileId: { type: 'string' },
+        },
+    },
+    disable_overrides: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+        },
+    },
+    get_override_status: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string' },
+            profileId: { type: 'string' },
+        },
+    },
+    get_override_request_log: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            runId: { type: 'string' },
+            limit: { type: 'number' },
+            offset: { type: 'number' },
+            maxResponseBytes: { type: 'number' },
+        },
+    },
+    get_override_plan_log: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            planId: { type: 'string' },
+            limit: { type: 'number' },
+            offset: { type: 'number' },
+            maxResponseBytes: { type: 'number' },
+        },
+    },
+    diagnose_overrides: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            runId: { type: 'string' },
+        },
+    },
     explain_last_failure: {
         type: 'object',
         required: ['sessionId'],
@@ -298,6 +855,191 @@ const TOOL_SCHEMAS = {
             encoding: { type: 'string' },
         },
     },
+    list_automation_runs: {
+        type: 'object',
+        required: ['sessionId'],
+        properties: {
+            sessionId: { type: 'string' },
+            status: { type: 'string', enum: ['requested', 'started', 'succeeded', 'failed', 'rejected', 'stopped'] },
+            action: { type: 'string', enum: ['click', 'input', 'focus', 'blur', 'scroll', 'press_key', 'submit', 'reload'] },
+            traceId: { type: 'string' },
+            limit: { type: 'number' },
+            offset: { type: 'number' },
+            maxResponseBytes: { type: 'number' },
+        },
+    },
+    get_automation_run: {
+        type: 'object',
+        required: ['sessionId', 'runId'],
+        properties: {
+            sessionId: { type: 'string' },
+            runId: { type: 'string' },
+            stepLimit: { type: 'number' },
+            stepOffset: { type: 'number' },
+            maxResponseBytes: { type: 'number' },
+        },
+    },
+    execute_ui_action: {
+        type: 'object',
+        required: ['sessionId', 'action'],
+        properties: {
+            sessionId: { type: 'string' },
+            action: { type: 'string', enum: ['click', 'input', 'focus', 'blur', 'scroll', 'press_key', 'submit', 'reload'] },
+            traceId: { type: 'string' },
+            target: {
+                type: 'object',
+                properties: {
+                    selector: { type: 'string' },
+                    elementRef: { type: 'string' },
+                    tabId: { type: 'number' },
+                    frameId: { type: 'number' },
+                    url: { type: 'string' },
+                },
+            },
+            input: { type: 'object' },
+            captureOnFailure: {
+                type: 'object',
+                properties: {
+                    enabled: { type: 'boolean' },
+                    selector: { type: 'string' },
+                    mode: { type: 'string', enum: ['dom', 'png', 'both'] },
+                    styleMode: { type: 'string', enum: ['computed-lite', 'computed-full'] },
+                    maxDepth: { type: 'number' },
+                    maxBytes: { type: 'number' },
+                    maxAncestors: { type: 'number' },
+                    includeDom: { type: 'boolean' },
+                    includeStyles: { type: 'boolean' },
+                    includePngDataUrl: { type: 'boolean' },
+                },
+            },
+            waitForPageState: {
+                type: 'object',
+                required: ['scope'],
+                properties: {
+                    scope: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused', 'page'] },
+                    selector: { type: 'string' },
+                    testId: { type: 'string' },
+                    textContains: { type: 'string' },
+                    labelContains: { type: 'string' },
+                    titleContains: { type: 'string' },
+                    urlContains: { type: 'string' },
+                    language: { type: 'string' },
+                    disabled: { type: 'boolean' },
+                    selected: { type: 'boolean' },
+                    pressed: { type: 'boolean' },
+                    expanded: { type: 'boolean' },
+                    readOnly: { type: 'boolean' },
+                    requiredField: { type: 'boolean' },
+                    tagName: { type: 'string' },
+                    type: { type: 'string' },
+                    countExactly: { type: 'number' },
+                    countAtLeast: { type: 'number' },
+                    maxItems: { type: 'number' },
+                    maxTextLength: { type: 'number' },
+                    timeoutMs: { type: 'number' },
+                    pollIntervalMs: { type: 'number' },
+                },
+            },
+        },
+    },
+    run_ui_steps: {
+        type: 'object',
+        required: ['sessionId', 'steps'],
+        properties: {
+            sessionId: { type: 'string' },
+            mode: { type: 'string', enum: ['safe', 'fast'] },
+            stopOnFailure: { type: 'boolean' },
+            defaultTimeoutMs: { type: 'number' },
+            defaultPollIntervalMs: { type: 'number' },
+            steps: {
+                type: 'array',
+                minItems: 1,
+                items: {
+                    type: 'object',
+                    required: ['kind'],
+                    properties: {
+                        id: { type: 'string' },
+                        note: { type: 'string' },
+                        kind: { type: 'string', enum: ['action', 'waitFor', 'assert'] },
+                        action: { type: 'string' },
+                        traceId: { type: 'string' },
+                        target: {
+                            type: 'object',
+                            properties: {
+                                selector: { type: 'string' },
+                                elementRef: { type: 'string' },
+                                tabId: { type: 'number' },
+                                frameId: { type: 'number' },
+                                url: { type: 'string' },
+                                testId: { type: 'string' },
+                                scope: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused'] },
+                                textContains: { type: 'string' },
+                                labelContains: { type: 'string' },
+                                titleContains: { type: 'string' },
+                                tagName: { type: 'string' },
+                                type: { type: 'string' },
+                                disabled: { type: 'boolean' },
+                                selected: { type: 'boolean' },
+                                pressed: { type: 'boolean' },
+                                expanded: { type: 'boolean' },
+                                readOnly: { type: 'boolean' },
+                                requiredField: { type: 'boolean' },
+                            },
+                        },
+                        input: { type: 'object' },
+                        onFailure: {
+                            type: 'object',
+                            properties: {
+                                strategy: { type: 'string', enum: ['stop', 'continue', 'retry_once'] },
+                                capture: {
+                                    type: 'object',
+                                    properties: {
+                                        enabled: { type: 'boolean' },
+                                        selector: { type: 'string' },
+                                        mode: { type: 'string', enum: ['dom', 'png', 'both'] },
+                                        styleMode: { type: 'string', enum: ['computed-lite', 'computed-full'] },
+                                        maxDepth: { type: 'number' },
+                                        maxBytes: { type: 'number' },
+                                        maxAncestors: { type: 'number' },
+                                        includeDom: { type: 'boolean' },
+                                        includeStyles: { type: 'boolean' },
+                                        includePngDataUrl: { type: 'boolean' },
+                                    },
+                                },
+                            },
+                        },
+                        matcher: {
+                            type: 'object',
+                            properties: {
+                                scope: { type: 'string', enum: ['buttons', 'inputs', 'modals', 'focused', 'page'] },
+                                selector: { type: 'string' },
+                                testId: { type: 'string' },
+                                textContains: { type: 'string' },
+                                labelContains: { type: 'string' },
+                                titleContains: { type: 'string' },
+                                urlContains: { type: 'string' },
+                                language: { type: 'string' },
+                                disabled: { type: 'boolean' },
+                                selected: { type: 'boolean' },
+                                pressed: { type: 'boolean' },
+                                expanded: { type: 'boolean' },
+                                readOnly: { type: 'boolean' },
+                                requiredField: { type: 'boolean' },
+                                tagName: { type: 'string' },
+                                type: { type: 'string' },
+                                countExactly: { type: 'number' },
+                                countAtLeast: { type: 'number' },
+                                maxItems: { type: 'number' },
+                                maxTextLength: { type: 'number' },
+                                timeoutMs: { type: 'number' },
+                                pollIntervalMs: { type: 'number' },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
 };
 const TOOL_DESCRIPTIONS = {
     list_sessions: 'List captured debugging sessions',
@@ -318,13 +1060,39 @@ const TOOL_DESCRIPTIONS = {
     get_dom_document: 'Capture full document as outline or html',
     get_computed_styles: 'Read computed CSS styles for an element',
     get_layout_metrics: 'Read viewport and element layout metrics',
+    get_page_state: 'Read a compact structured page model for forms, buttons, modals, and viewport state',
+    get_interactive_elements: 'Read compact live element references for buttons, inputs, modals, and focused elements',
+    get_live_session_health: 'Read live transport health and session binding details for one session',
+    set_viewport: 'Resize the live browser window for a session and return the resulting viewport metrics',
+    assert_page_state: 'Assert compact page-state conditions without pulling raw DOM payloads',
+    wait_for_page_state: 'Poll compact page state until a structured assertion becomes true',
     capture_ui_snapshot: 'Capture redacted UI snapshot (DOM/styles/optional PNG) and persist it',
     get_live_console_logs: 'Read in-memory live console logs for a connected session',
+    list_override_profiles: 'List configured browser override profiles',
+    create_override_profile: 'Generate a candidate browser override profile from local build assets',
+    validate_override_profile: 'Validate the current browser override profile and local asset readiness',
+    preflight_overrides: 'Run production-safety checks before enabling browser overrides for a live session',
+    observe_override_assets: 'Observe production render artifacts from a live extension tab',
+    capture_override_response_body: 'Capture a bounded text response body from a live extension session for override planning, using extension fetch or explicit CDP response-stage capture',
+    list_observed_override_assets: 'List persisted production render artifacts observed for a session',
+    map_next_override_assets: 'Map observed production Next.js assets to local build chunks and source paths',
+    plan_override_response_patch: 'Patch a supplied or live-captured text response body with literal textPatches or JSON Pointer jsonPatches and write an exact or prefix override rule for supported response types',
+    plan_next_source_override: 'Apply source edits in a temp Next.js overlay build and plan exact browser override rules',
+    enable_overrides: 'Enable browser overrides for a live extension session',
+    disable_overrides: 'Disable browser overrides for a live extension session',
+    get_override_status: 'Read live or persisted browser override status for a session',
+    get_override_request_log: 'Read persisted browser override request audit rows',
+    get_override_plan_log: 'Read persisted generated override plan audit rows with previews, hashes, and rollback metadata',
+    diagnose_overrides: 'Diagnose persisted browser override runs and failure indicators',
     explain_last_failure: 'Explain the latest failure timeline',
     get_event_correlation: 'Correlate related events by window',
     list_snapshots: 'List snapshot metadata by session/time/trigger',
     get_snapshot_for_event: 'Find snapshot most related to an event',
     get_snapshot_asset: 'Read bounded binary chunks for snapshot assets',
+    list_automation_runs: 'List first-class automation runs from dedicated automation tables',
+    get_automation_run: 'Inspect one automation run with bounded step details',
+    execute_ui_action: 'Execute one live UI action in the current bound extension session',
+    run_ui_steps: 'Run a small generic UI workflow locally in the bridge using actions, waits, and assertions',
 };
 const ALL_TOOLS = Object.keys(TOOL_SCHEMAS);
 const DEFAULT_REDACTION_SUMMARY = {
@@ -345,6 +1113,16 @@ const DEFAULT_NETWORK_POLL_TIMEOUT_MS = 15_000;
 const MAX_NETWORK_POLL_TIMEOUT_MS = 120_000;
 const DEFAULT_NETWORK_POLL_INTERVAL_MS = 250;
 const LIVE_SESSION_DISCONNECTED_CODE = 'LIVE_SESSION_DISCONNECTED';
+const STALE_LIVE_CONNECTION_GRACE_WINDOW_MS = 30 * 60 * 1000;
+const NOISE_SESSION_HOST_PATTERNS = [
+    /(^|\.)adtrafficquality\.google$/i,
+    /(^|\.)doubleclick\.net$/i,
+    /(^|\.)googlesyndication\.com$/i,
+    /(^|\.)googleadservices\.com$/i,
+    /(^|\.)recaptcha\.net$/i,
+    /(^|\.)gstatic\.com$/i,
+];
+const NOISE_SESSION_PATH_PATTERNS = [/\/sodar/i, /\/recaptcha/i, /runner\.html$/i];
 const NETWORK_CALL_SELECT_COLUMNS = `
   request_id, session_id, trace_id, tab_id, ts_start, duration_ms, method, url, origin, status, initiator, error_class, response_size_est,
   request_content_type, request_body_text, request_body_json, request_body_bytes, request_body_truncated, request_body_chunk_ref,
@@ -551,84 +1329,849 @@ function resolveLastUrl(payload) {
     }
     return undefined;
 }
-function mapEventRecord(row, profile = 'legacy', options = {}) {
-    const payload = readJsonPayload(row.payload_json);
-    if (profile === 'compact') {
-        const compact = {
-            eventId: row.event_id,
-            sessionId: row.session_id,
-            timestamp: row.ts,
-            type: row.type,
-            summary: describeEvent(row.type, payload),
+function classifySessionUrl(urlValue) {
+    if (!urlValue) {
+        return {
+            kind: 'unknown',
+            note: 'No session URL is available yet.',
         };
-        if (row.type === 'console') {
-            compact.level = typeof payload.level === 'string' ? payload.level : undefined;
-            compact.message = typeof payload.message === 'string' ? payload.message : undefined;
-        }
-        if (row.type === 'nav') {
-            compact.url = resolveLastUrl(payload);
+    }
+    try {
+        const parsed = new URL(urlValue);
+        const host = parsed.hostname.toLowerCase();
+        const pathname = parsed.pathname.toLowerCase();
+        const origin = parsed.origin;
+        const isLocalhost = host === 'localhost' || host === '127.0.0.1';
+        if (NOISE_SESSION_HOST_PATTERNS.some((pattern) => pattern.test(host))
+            || NOISE_SESSION_PATH_PATTERNS.some((pattern) => pattern.test(pathname))) {
+            return {
+                kind: 'likely_iframe_noise',
+                note: 'Last URL looks like third-party iframe/ad traffic rather than the app surface.',
+                origin,
+                host,
+                isLocalhost,
+            };
         }
-        if (options.includePayload === true) {
-            compact.payload = payload;
+        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            return {
+                kind: 'top_level_page',
+                note: isLocalhost
+                    ? 'Last URL looks like a local top-level app page.'
+                    : 'Last URL looks like a top-level app page.',
+                origin,
+                host,
+                isLocalhost,
+            };
         }
-        return compact;
+    }
+    catch {
+        return {
+            kind: 'unknown',
+            note: 'Session URL could not be parsed.',
+        };
     }
     return {
-        eventId: row.event_id,
-        sessionId: row.session_id,
-        timestamp: row.ts,
-        type: row.type,
-        tabId: row.tab_id ?? (typeof payload.tabId === 'number' ? payload.tabId : undefined),
-        origin: row.origin
-            ?? (typeof payload.origin === 'string' ? payload.origin : undefined)
-            ?? undefined,
-        payload,
+        kind: 'unknown',
+        note: 'Session URL does not use an http(s) page origin.',
     };
 }
-function classifyNetworkFailure(status, errorClass) {
-    if (errorClass && errorClass.length > 0) {
-        return errorClass;
+function getSessionStatus(row) {
+    if (row.ended_at) {
+        return 'ended';
     }
-    if (typeof status === 'number' && status >= 400) {
-        return 'http_error';
+    if (row.paused_at) {
+        return 'paused';
     }
-    return 'unknown';
+    return 'active';
 }
-function buildNetworkFailureFilter(errorType) {
-    if (typeof errorType !== 'string' || errorType.length === 0) {
-        return '(error_class IS NOT NULL OR COALESCE(status, 0) >= 400)';
-    }
-    if (errorType === 'http_error') {
-        return "(error_class = 'http_error' OR (error_class IS NULL AND COALESCE(status, 0) >= 400))";
+function buildOverrideProfileRecords() {
+    const summary = getOverridePocConfigSummary();
+    return summary.profiles.map((profile) => ({
+        profileId: profile.profileId,
+        name: profile.name,
+        active: profile.profileId === summary.activeProfileId,
+        configEnabled: summary.configEnabled,
+        enabled: profile.enabled,
+        effectiveEnabled: summary.configEnabled && profile.enabled && profile.enabledRuleCount > 0,
+        autoReload: profile.autoReload,
+        configPath: summary.configPath,
+        fileExists: profile.fileExists,
+        ruleCount: profile.ruleCount,
+        enabledRuleCount: profile.enabledRuleCount,
+        rules: profile.rules,
+    }));
+}
+function resolveOverrideProfileRecord(value) {
+    const profiles = buildOverrideProfileRecords();
+    const fallbackProfileId = typeof profiles[0]?.profileId === 'string' ? profiles[0].profileId : 'poc';
+    const requestedProfileId = typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallbackProfileId;
+    const profile = profiles.find((candidate) => candidate.profileId === requestedProfileId);
+    if (!profile) {
+        throw new Error(`Unknown override profile: ${requestedProfileId}`);
     }
-    return 'error_class = ?';
+    return profile;
 }
-function resolveWindowSeconds(value, fallback, maxValue) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+function sha256Text(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function isRecordWithRscFlightMetadata(value) {
+    return isRecord(value)
+        && (value.productionMode === 'structured-flight-v1' && value.patchKind === 'string-value-text'
+            || value.productionMode === 'literal-response-v1' && value.patchKind === 'literal-text')
+        && value.source !== undefined
+        && value.patchKind !== undefined;
+}
+function buildRscFlightRuleIssues(rule) {
+    const ruleId = String(rule.ruleId ?? 'unknown');
+    const issues = [];
+    const rscFlight = rule.rscFlight;
+    if (!isRecordWithRscFlightMetadata(rscFlight)) {
+        return [{
+                code: 'UNSUPPORTED_RSC_FLIGHT_RULE',
+                severity: 'error',
+                message: `Rule ${ruleId} targets a Next.js RSC flight response without production RSC metadata generated by the response planner.`,
+            }];
     }
-    const floored = Math.floor(value);
-    if (floored < 1) {
-        return fallback;
+    const source = rscFlight.source;
+    if (source !== 'cdp-response' && source !== 'extension-fetch') {
+        issues.push({
+            code: 'RSC_FLIGHT_METADATA_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC metadata source must be cdp-response or extension-fetch.`,
+        });
     }
-    return Math.min(floored, maxValue);
-}
-function resolveOptionalTimestamp(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return undefined;
+    if (!Array.isArray(rscFlight.textPatches) || rscFlight.textPatches.length === 0) {
+        issues.push({
+            code: 'RSC_FLIGHT_PATCHES_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight metadata must include string-value text patches.`,
+        });
     }
-    const floored = Math.floor(value);
-    return floored < 0 ? undefined : floored;
-}
-function resolveChunkBytes(value, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
+    else {
+        for (const [index, patch] of rscFlight.textPatches.entries()) {
+            if (!isRecord(patch)
+                || typeof patch.search !== 'string'
+                || patch.search.length === 0
+                || typeof patch.replacement !== 'string'
+                || typeof patch.expectedCount !== 'number'
+                || !Number.isFinite(patch.expectedCount)
+                || patch.expectedCount < 0) {
+                issues.push({
+                    code: 'RSC_FLIGHT_PATCHES_INVALID',
+                    severity: 'error',
+                    message: `Rule ${ruleId} RSC flight textPatches[${index}] is invalid.`,
+                });
+            }
+        }
     }
-    const floored = Math.floor(value);
-    if (floored < 1) {
-        return fallback;
+    if (rule.requestMethod !== 'GET') {
+        issues.push({
+            code: 'RSC_FLIGHT_METHOD_UNSUPPORTED',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight overrides only support GET requests.`,
+        });
     }
-    return Math.min(floored, MAX_SNAPSHOT_ASSET_CHUNK_BYTES);
+    const targetAssetUrl = typeof rule.targetAssetUrl === 'string' ? rule.targetAssetUrl : '';
+    try {
+        const parsed = new URL(targetAssetUrl);
+        if (!parsed.searchParams.has('_rsc')) {
+            issues.push({
+                code: 'RSC_FLIGHT_TARGET_INVALID',
+                severity: 'error',
+                message: `Rule ${ruleId} RSC flight targetAssetUrl must include the _rsc search parameter.`,
+            });
+        }
+    }
+    catch {
+        issues.push({
+            code: 'RSC_FLIGHT_TARGET_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight targetAssetUrl must be an absolute http(s) URL.`,
+        });
+    }
+    const contentType = typeof rule.contentType === 'string' ? rule.contentType : '';
+    const metadataContentType = typeof rscFlight.contentType === 'string' ? rscFlight.contentType : '';
+    if (!contentType.toLowerCase().includes('text/x-component') || !metadataContentType.toLowerCase().includes('text/x-component')) {
+        issues.push({
+            code: 'RSC_FLIGHT_CONTENT_TYPE_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight overrides require text/x-component content types.`,
+        });
+    }
+    const originalSha256 = typeof rscFlight.originalSha256 === 'string' ? rscFlight.originalSha256 : '';
+    const patchedSha256 = typeof rscFlight.patchedSha256 === 'string' ? rscFlight.patchedSha256 : '';
+    if (!SHA256_HEX_PATTERN.test(originalSha256) || !SHA256_HEX_PATTERN.test(patchedSha256) || originalSha256 === patchedSha256) {
+        issues.push({
+            code: 'RSC_FLIGHT_HASH_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight metadata must include distinct original and patched sha256 hashes.`,
+        });
+    }
+    const patchedBytes = typeof rscFlight.patchedBytes === 'number' && Number.isFinite(rscFlight.patchedBytes)
+        ? Math.floor(rscFlight.patchedBytes)
+        : null;
+    if (patchedBytes === null || patchedBytes < 1) {
+        issues.push({
+            code: 'RSC_FLIGHT_BYTES_INVALID',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight metadata must include a positive patchedBytes value.`,
+        });
+    }
+    const fileSizeBytes = typeof rule.fileSizeBytes === 'number' && Number.isFinite(rule.fileSizeBytes)
+        ? Math.floor(rule.fileSizeBytes)
+        : null;
+    if (patchedBytes !== null && fileSizeBytes !== null && patchedBytes !== fileSizeBytes) {
+        issues.push({
+            code: 'RSC_FLIGHT_LOCAL_FILE_MISMATCH',
+            severity: 'error',
+            message: `Rule ${ruleId} local RSC file size does not match patchedBytes metadata.`,
+        });
+    }
+    const resolvedLocalFilePath = typeof rule.resolvedLocalFilePath === 'string' ? rule.resolvedLocalFilePath : '';
+    if (resolvedLocalFilePath && existsSync(resolvedLocalFilePath) && SHA256_HEX_PATTERN.test(patchedSha256)) {
+        const body = readFileSync(resolvedLocalFilePath, 'utf8');
+        if (!/(^|\n)\d+:/u.test(body)) {
+            issues.push({
+                code: 'RSC_FLIGHT_BODY_INVALID',
+                severity: 'error',
+                message: `Rule ${ruleId} local RSC file does not match the supported Flight payload shape.`,
+            });
+        }
+        if (sha256Text(body) !== patchedSha256) {
+            issues.push({
+                code: 'RSC_FLIGHT_LOCAL_FILE_MISMATCH',
+                severity: 'error',
+                message: `Rule ${ruleId} local RSC file hash does not match patchedSha256 metadata.`,
+            });
+        }
+    }
+    return issues;
+}
+function buildOverrideProfileIssues(profile) {
+    const issues = [];
+    const rules = Array.isArray(profile.rules)
+        ? profile.rules.filter((rule) => isRecord(rule))
+        : [];
+    if (profile.configEnabled !== true) {
+        issues.push({
+            code: 'CONFIG_DISABLED',
+            severity: 'warning',
+            message: 'The override config is disabled and cannot replace requests until enabled.',
+        });
+    }
+    if (profile.enabled !== true) {
+        issues.push({
+            code: 'PROFILE_DISABLED',
+            severity: 'warning',
+            message: 'The override profile is disabled and cannot replace requests until enabled.',
+        });
+    }
+    if (rules.length === 0 || !rules.some((rule) => rule.enabled === true)) {
+        issues.push({
+            code: 'NO_ENABLED_RULES',
+            severity: 'error',
+            message: 'The override profile has no enabled rules.',
+        });
+    }
+    for (const rule of rules) {
+        if (rule.enabled !== true) {
+            continue;
+        }
+        if (typeof rule.targetAssetUrl !== 'string' || !rule.targetAssetUrl.startsWith('http')) {
+            issues.push({
+                code: 'TARGET_URL_INVALID',
+                severity: 'error',
+                message: `Rule ${String(rule.ruleId ?? 'unknown')} targetAssetUrl must be an absolute http(s) URL.`,
+            });
+        }
+        if (rule.fileExists !== true) {
+            issues.push({
+                code: 'LOCAL_FILE_MISSING',
+                severity: 'error',
+                message: `Rule ${String(rule.ruleId ?? 'unknown')} local override file does not exist.`,
+            });
+        }
+        issues.push(...classifyOverrideResponseRequestCapability({
+            ruleId: rule.ruleId,
+            requestMethod: rule.requestMethod,
+            requestHeaders: rule.requestHeaders,
+            ruleType: rule.ruleType,
+        }).issues.map((issue) => ({ ...issue })));
+        if (rule.ruleType === 'rsc-flight') {
+            issues.push(...buildRscFlightRuleIssues(rule));
+        }
+    }
+    return issues;
+}
+function buildOverrideProfileNextActions(profile, issues) {
+    if (issues.some((issue) => issue.code === 'SERVER_ACTION_UNSUPPORTED')) {
+        return [{
+                code: 'REPLAN_SERVER_ACTION_OVERRIDE',
+                message: 'Server actions stay unsupported in production override mode; replace the flow with a GET document/data/API response path instead.',
+            }];
+    }
+    if (issues.some((issue) => issue.code === 'MUTATION_REPLAY_UNSUPPORTED')) {
+        return [{
+                code: 'REPLAN_MUTATION_OVERRIDE',
+                message: 'Mutation responses are not replay-safe; move the override to a GET document/data/API response or remove the non-GET rule.',
+            }];
+    }
+    if (issues.some((issue) => issue.code === 'UNSAFE_REQUEST_METHOD')) {
+        return [{
+                code: 'REPLAN_GET_ONLY_OVERRIDE',
+                message: 'Response override rules are production-safe only for GET requests; regenerate or remove non-GET rules.',
+            }];
+    }
+    if (issues.some((issue) => issue.code === 'LOCAL_FILE_MISSING')) {
+        return [{
+                code: 'REBUILD_OR_FIX_LOCAL_PATHS',
+                message: 'Rebuild the local app or fix localFilePath values before enabling overrides.',
+            }];
+    }
+    if (issues.some((issue) => issue.code === 'NO_ENABLED_RULES')) {
+        return [{
+                code: 'ENABLE_RULES',
+                message: 'Enable at least one rule in the selected override profile.',
+            }];
+    }
+    if (issues.some((issue) => issue.code === 'TARGET_URL_INVALID')) {
+        return [{
+                code: 'FIX_TARGET_URLS',
+                message: 'Use absolute http(s) production URLs for every targetAssetUrl.',
+            }];
+    }
+    if (issues.some((issue) => typeof issue.code === 'string' && issue.code.startsWith('RSC_FLIGHT_'))
+        || issues.some((issue) => issue.code === 'UNSUPPORTED_RSC_FLIGHT_RULE')) {
+        return [{
+                code: 'REPLAN_RSC_RESPONSE_OVERRIDE',
+                message: 'Regenerate the RSC rule with plan_override_response_patch from a captured text/x-component response body.',
+            }];
+    }
+    if (profile.configEnabled !== true) {
+        return [{
+                code: 'ENABLE_CONFIG',
+                message: 'Set the root override config enabled=true after reviewing the profile.',
+            }];
+    }
+    if (profile.enabled !== true) {
+        return [{
+                code: 'ENABLE_PROFILE',
+                message: 'Set the selected override profile enabled=true after reviewing its rules.',
+            }];
+    }
+    return [{
+            code: 'ENABLE_OVERRIDES',
+            message: 'Enable overrides on a connected session, then reload the target tab if needed.',
+        }];
+}
+function hasEnabledExperimentalRscFlightRule(profile) {
+    const rules = Array.isArray(profile.rules)
+        ? profile.rules.filter((rule) => isRecord(rule))
+        : [];
+    return rules.some((rule) => {
+        return rule.enabled === true
+            && rule.ruleType === 'rsc-flight'
+            && rule.allowExperimentalRscFlightFulfillment === true;
+    });
+}
+function canBypassPreflightForExperimentalRsc(profile, blockingCodes) {
+    return blockingCodes.length > 0
+        && blockingCodes.every((code) => code === 'UNSUPPORTED_RSC_FLIGHT_RULE')
+        && hasEnabledExperimentalRscFlightRule(profile);
+}
+const OVERRIDE_VARIANT_HEADER_ALLOWLIST = new Set([
+    'accept',
+    'content-type',
+    'next-router-prefetch',
+    'next-router-state-tree',
+    'purpose',
+    'rsc',
+    'x-nextjs-data',
+]);
+function normalizeOverrideVariantHeaders(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const normalized = {};
+    for (const [rawName, rawValue] of Object.entries(value)) {
+        const name = rawName.trim().toLowerCase();
+        if (!OVERRIDE_VARIANT_HEADER_ALLOWLIST.has(name)) {
+            continue;
+        }
+        if (typeof rawValue === 'string' && rawValue.trim().length > 0) {
+            normalized[name] = rawValue.trim();
+            continue;
+        }
+        if (typeof rawValue === 'number' || typeof rawValue === 'boolean') {
+            normalized[name] = String(rawValue);
+        }
+    }
+    return normalized;
+}
+function buildOverrideVariantContext(options) {
+    const targetUrl = normalizeOptionalString(options.targetUrl);
+    if (!targetUrl) {
+        return null;
+    }
+    const requestMethod = normalizeOverrideRequestMethod(options.requestMethod);
+    const matchMode = normalizeOptionalString(options.matchMode) ?? 'exact';
+    const ruleType = normalizeOptionalString(options.ruleType) ?? 'document';
+    const captureMode = normalizeOptionalString(options.captureMode);
+    const source = normalizeOptionalString(options.source);
+    const headers = normalizeOverrideVariantHeaders(options.requestHeaders);
+    const isPrefetchVariant = headers['next-router-prefetch'] === '1'
+        || headers.purpose?.toLowerCase() === 'prefetch';
+    const isRscRequest = ruleType === 'rsc-flight' || headers.rsc === '1';
+    let isNextDataRequest = ruleType === 'next-data' || headers['x-nextjs-data'] === '1';
+    let origin;
+    let pathname;
+    let searchParams = [];
+    try {
+        const parsed = new URL(targetUrl);
+        origin = parsed.origin;
+        pathname = parsed.pathname;
+        searchParams = Array.from(parsed.searchParams.entries()).map(([name, value]) => ({ name, value }));
+        if (pathname.startsWith('/_next/data/')) {
+            isNextDataRequest = true;
+        }
+    }
+    catch {
+        pathname = undefined;
+    }
+    const searchParamKeys = [...new Set(searchParams.map((entry) => entry.name))].sort();
+    const variantBasis = {
+        targetUrl,
+        origin: origin ?? null,
+        pathname: pathname ?? null,
+        searchParams,
+        requestMethod,
+        matchMode,
+        ruleType,
+        captureMode: captureMode ?? null,
+        source: source ?? null,
+        triggerReload: options.triggerReload === true,
+        headers,
+        isPrefetchVariant,
+        isRscRequest,
+        isNextDataRequest,
+    };
+    return {
+        ...variantBasis,
+        searchParamKeys,
+        variantKey: sha256Text(JSON.stringify(variantBasis)),
+    };
+}
+function extractPlanVariantContext(plan) {
+    if (isRecord(plan.patchSummary) && isRecord(plan.patchSummary.variantContext)) {
+        return plan.patchSummary.variantContext;
+    }
+    if (isRecord(plan.capturedFromLiveSession)) {
+        if (isRecord(plan.capturedFromLiveSession.variantContext)) {
+            return plan.capturedFromLiveSession.variantContext;
+        }
+        return buildOverrideVariantContext({
+            targetUrl: plan.capturedFromLiveSession.targetUrl ?? plan.targetAssetUrl,
+            requestMethod: plan.capturedFromLiveSession.requestMethod ?? plan.requestMethod,
+            matchMode: plan.capturedFromLiveSession.matchMode ?? plan.matchMode,
+            ruleType: plan.capturedFromLiveSession.ruleType ?? plan.ruleType,
+            captureMode: plan.capturedFromLiveSession.captureMode,
+            source: plan.capturedFromLiveSession.source,
+            triggerReload: plan.capturedFromLiveSession.triggerReload,
+            requestHeaders: plan.capturedFromLiveSession.requestHeaders,
+        });
+    }
+    return buildOverrideVariantContext({
+        targetUrl: plan.targetAssetUrl,
+        requestMethod: plan.requestMethod,
+        matchMode: plan.matchMode,
+        ruleType: plan.ruleType,
+    });
+}
+function pushOverridePreflightIssue(issues, issue) {
+    const code = typeof issue.code === 'string' ? issue.code : '';
+    const source = typeof issue.source === 'string' ? issue.source : '';
+    const message = typeof issue.message === 'string' ? issue.message : '';
+    if (issues.some((existing) => existing.code === code && existing.source === source && existing.message === message)) {
+        return;
+    }
+    issues.push(issue);
+}
+function buildOverridePreflight(options) {
+    const session = options.db
+        .prepare(`
+      SELECT
+        session_id,
+        created_at,
+        last_seen_at,
+        paused_at,
+        ended_at,
+        tab_id,
+        window_id,
+        url_start,
+        url_last,
+        user_agent,
+        viewport_w,
+        viewport_h,
+        dpr,
+        safe_mode,
+        pinned
+      FROM sessions
+      WHERE session_id = ?
+      LIMIT 1
+    `)
+        .get(options.sessionId);
+    const profile = resolveOverrideProfileRecord(options.profileId);
+    const issues = [];
+    const observedAssets = session
+        ? listObservedOverrideAssets(options.db, { sessionId: options.sessionId, limit: 200 })
+        : [];
+    const latestRun = session ? listOverridePocRuns(options.db, options.sessionId, 1, 0).runs[0] ?? null : null;
+    const recentPlans = session
+        ? listOverridePlanAudits(options.db, { sessionId: options.sessionId, limit: 5, offset: 0 }).plans
+        : [];
+    const variantContexts = [...new Map(recentPlans
+            .map((plan) => extractPlanVariantContext(plan))
+            .filter((context) => context !== null)
+            .map((context) => [String(context.variantKey ?? JSON.stringify(context)), context])).values()];
+    const sessionState = options.getSessionConnectionState?.(options.sessionId);
+    const diagnosis = session ? diagnoseOverridePoc(options.db, options.sessionId, latestRun?.runId) : null;
+    for (const issue of buildOverrideProfileIssues(profile)) {
+        pushOverridePreflightIssue(issues, { ...issue, source: 'profile' });
+    }
+    if (!session) {
+        pushOverridePreflightIssue(issues, {
+            code: 'SESSION_NOT_FOUND',
+            severity: 'error',
+            source: 'session',
+            message: `Session not found: ${options.sessionId}`,
+        });
+    }
+    else {
+        const sessionStatus = getSessionStatus(session);
+        if (sessionStatus === 'paused') {
+            pushOverridePreflightIssue(issues, {
+                code: 'SESSION_PAUSED',
+                severity: 'error',
+                source: 'session',
+                message: `Session ${options.sessionId} is paused and cannot enable overrides until it resumes.`,
+            });
+        }
+        if (sessionStatus === 'ended') {
+            pushOverridePreflightIssue(issues, {
+                code: 'SESSION_ENDED',
+                severity: 'error',
+                source: 'session',
+                message: `Session ${options.sessionId} has ended and cannot enable overrides.`,
+            });
+        }
+        if (sessionState && sessionState.connected !== true) {
+            pushOverridePreflightIssue(issues, {
+                code: LIVE_SESSION_DISCONNECTED_CODE,
+                severity: 'error',
+                source: 'connection',
+                message: `Session ${options.sessionId} is not currently connected to the live extension bridge.`,
+            });
+        }
+    }
+    const enabledRules = Array.isArray(profile.rules)
+        ? profile.rules.filter((rule) => isRecord(rule) && rule.enabled === true)
+        : [];
+    const anyServiceWorkerControlled = observedAssets.some((asset) => asset.serviceWorkerControlled);
+    const cspMetaTags = [...new Set(observedAssets.flatMap((asset) => asset.cspMetaTags))];
+    if (observedAssets.length === 0) {
+        pushOverridePreflightIssue(issues, {
+            code: 'NO_OBSERVED_ASSETS',
+            severity: 'warning',
+            source: 'observed-assets',
+            message: 'No observed production assets are stored for this session yet.',
+        });
+    }
+    for (const rule of enabledRules) {
+        const ruleId = String(rule.ruleId ?? 'unknown');
+        const targetAssetUrl = normalizeOptionalString(rule.targetAssetUrl);
+        if (!targetAssetUrl) {
+            continue;
+        }
+        const requestMethod = normalizeOverrideRequestMethod(rule.requestMethod);
+        const matchingAssets = observedAssets.filter((asset) => {
+            return asset.url === targetAssetUrl
+                && normalizeOverrideRequestMethod(asset.requestMethod) === requestMethod;
+        });
+        if (observedAssets.length > 0 && matchingAssets.length === 0) {
+            pushOverridePreflightIssue(issues, {
+                code: 'TARGET_ASSET_NOT_OBSERVED',
+                severity: 'warning',
+                source: 'observed-assets',
+                message: `Rule ${ruleId} target asset was not observed for ${requestMethod} ${targetAssetUrl}.`,
+            });
+            continue;
+        }
+        for (const asset of matchingAssets) {
+            if (typeof asset.integrity === 'string' && asset.integrity.length > 0) {
+                pushOverridePreflightIssue(issues, {
+                    code: 'TARGET_ASSET_SRI_PRESENT',
+                    severity: 'error',
+                    source: 'observed-assets',
+                    message: `Rule ${ruleId} target asset ${asset.url} includes integrity="${asset.integrity}" and cannot be overridden safely.`,
+                });
+            }
+        }
+    }
+    if (anyServiceWorkerControlled) {
+        pushOverridePreflightIssue(issues, {
+            code: 'SERVICE_WORKER_CONTROLLED',
+            severity: 'warning',
+            source: 'observed-assets',
+            message: 'The observed page is service-worker controlled; verify the target requests still reach the network path that the debugger can fulfill.',
+        });
+    }
+    if (cspMetaTags.length > 0) {
+        pushOverridePreflightIssue(issues, {
+            code: 'CSP_META_PRESENT',
+            severity: 'warning',
+            source: 'observed-assets',
+            message: `The observed page emitted ${cspMetaTags.length} CSP meta tag(s); document or bootstrap rewrites may still be constrained by page policy.`,
+        });
+    }
+    const ready = !issues.some((issue) => issue.severity === 'error');
+    const nextActions = !ready
+        ? issues.some((issue) => issue.code === 'SERVER_ACTION_UNSUPPORTED')
+            ? [{
+                    code: 'REPLAN_SERVER_ACTION_OVERRIDE',
+                    message: 'Server actions stay unsupported in production override mode; move the override to a GET document/data/API response.',
+                }]
+            : issues.some((issue) => issue.code === 'MUTATION_REPLAY_UNSUPPORTED')
+                ? [{
+                        code: 'REPLAN_MUTATION_OVERRIDE',
+                        message: 'Mutation responses are not replay-safe; use a GET document/data/API response path instead.',
+                    }]
+                : issues.some((issue) => issue.code === 'UNSAFE_REQUEST_METHOD')
+                    ? [{ code: 'REPLAN_GET_ONLY_OVERRIDE', message: 'Remove or regenerate non-GET rules before enabling overrides.' }]
+                    : issues.some((issue) => issue.code === 'TARGET_ASSET_SRI_PRESENT')
+                        ? [{ code: 'CHOOSE_ANOTHER_OVERRIDE_PATH', message: 'Choose a document/data response path or remove SRI on the production asset before enabling overrides.' }]
+                        : issues.some((issue) => issue.code === 'SESSION_NOT_FOUND' || issue.code === 'SESSION_PAUSED' || issue.code === 'SESSION_ENDED' || issue.code === LIVE_SESSION_DISCONNECTED_CODE)
+                            ? [{ code: 'RECONNECT_SESSION', message: 'Reconnect or resume the target session before enabling overrides.' }]
+                            : buildOverrideProfileNextActions(profile, issues)
+        : observedAssets.length === 0
+            ? [{ code: 'OBSERVE_OVERRIDE_ASSETS', message: 'Run observe_override_assets on the target route before enabling overrides in production workflows.' }]
+            : [{ code: 'ENABLE_OVERRIDES', message: 'Preflight checks passed; the selected profile can be enabled on the live session.' }];
+    return {
+        ready,
+        profileId: profile.profileId,
+        profile,
+        session: session
+            ? {
+                sessionId: session.session_id,
+                status: getSessionStatus(session),
+                lastSeenAt: resolveSessionLastSeenAt(session, sessionState),
+                connected: sessionState?.connected === true,
+                disconnectedAt: sessionState?.disconnectedAt,
+                disconnectReason: sessionState?.disconnectReason,
+                urlLast: session.url_last ?? undefined,
+                tabId: session.tab_id ?? undefined,
+            }
+            : null,
+        issues,
+        checks: {
+            sessionFound: session !== undefined,
+            connected: sessionState?.connected === true,
+            observedAssetCount: observedAssets.length,
+            targetAssetObserved: issues.every((issue) => issue.code !== 'TARGET_ASSET_NOT_OBSERVED'),
+            serviceWorkerControlled: anyServiceWorkerControlled,
+            cspMetaTagCount: cspMetaTags.length,
+            recentPlanCount: recentPlans.length,
+            variantContextCount: variantContexts.length,
+        },
+        observedAssets: {
+            count: observedAssets.length,
+            serviceWorkerControlled: anyServiceWorkerControlled,
+            cspMetaTags,
+        },
+        latestRun,
+        recentPlans,
+        variantContexts,
+        diagnosis,
+        nextActions,
+    };
+}
+function normalizeOptionalBooleanInput(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'boolean') {
+        throw new Error(`${fieldName} must be a boolean when provided`);
+    }
+    return value;
+}
+function normalizeOptionalNumberInput(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`${fieldName} must be a finite number when provided`);
+    }
+    return value;
+}
+function normalizeOptionalStringArrayInput(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${fieldName} must be an array of strings when provided`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            throw new Error(`${fieldName}[${index}] must be a non-empty string`);
+        }
+        return entry.trim();
+    });
+}
+function resolveSessionLastSeenAt(row, state) {
+    return Math.max(row.created_at, row.last_seen_at ?? 0, row.paused_at ?? 0, row.ended_at ?? 0, state?.lastHeartbeatAt ?? 0);
+}
+function buildLiveConnectionRecord(row, scope, state) {
+    const status = getSessionStatus(row);
+    const lastSeenAt = resolveSessionLastSeenAt(row, state);
+    const heartbeatAt = state?.lastHeartbeatAt;
+    const heartbeatAgeMs = typeof heartbeatAt === 'number' ? Math.max(0, Date.now() - heartbeatAt) : undefined;
+    const likelyStale = Boolean(!state?.connected
+        && status === 'active'
+        && scope.kind !== 'likely_iframe_noise'
+        && typeof heartbeatAt === 'number'
+        && Date.now() - heartbeatAt <= STALE_LIVE_CONNECTION_GRACE_WINDOW_MS);
+    return {
+        connected: state?.connected === true,
+        connectedAt: state?.connectedAt,
+        lastHeartbeatAt: heartbeatAt,
+        heartbeatAgeMs,
+        disconnectedAt: state?.disconnectedAt,
+        disconnectReason: state?.disconnectReason ?? (status === 'ended' ? 'manual_stop' : undefined),
+        status: status === 'ended'
+            ? 'ended'
+            : status === 'paused'
+                ? 'paused'
+                : state?.connected
+                    ? 'connected'
+                    : likelyStale
+                        ? 'likely_stale'
+                        : 'disconnected',
+        captureReady: state?.connected === true && status === 'active',
+        recommendedForLiveCapture: state?.connected === true && status === 'active' && scope.kind !== 'likely_iframe_noise',
+        lastSeenAt,
+        activityAgeMs: Math.max(0, Date.now() - lastSeenAt),
+    };
+}
+function buildLiveSessionNextAction(liveConnection, scope) {
+    const liveStatus = typeof liveConnection.status === 'string' ? liveConnection.status : 'disconnected';
+    if (liveStatus === 'connected' && scope.kind !== 'likely_iframe_noise') {
+        return 'Use this session for live capture tools.';
+    }
+    if (liveStatus === 'connected' && scope.kind === 'likely_iframe_noise') {
+        return 'Reconnect on a top-level app tab before relying on live navigation or performance captures.';
+    }
+    if (liveStatus === 'likely_stale') {
+        return 'Retry list_sessions after a fresh app interaction or restart the session if live capture still fails.';
+    }
+    if (liveStatus === 'paused') {
+        return 'Resume the session from the extension popup before using live capture tools.';
+    }
+    if (liveStatus === 'ended') {
+        return 'Start a new extension session before using live capture tools.';
+    }
+    return 'Reconnect or restart the extension session before using live capture tools.';
+}
+function buildLiveSessionRecommendedAction(liveConnection, scope) {
+    const liveStatus = typeof liveConnection.status === 'string' ? liveConnection.status : 'disconnected';
+    if (liveStatus === 'connected' && scope.kind !== 'likely_iframe_noise') {
+        return 'ready';
+    }
+    if (liveStatus === 'ended') {
+        return 'start_new_session';
+    }
+    if (liveStatus === 'paused') {
+        return 'resume_session';
+    }
+    return 'reconnect_extension';
+}
+function mapEventRecord(row, profile = 'legacy', options = {}) {
+    const payload = readJsonPayload(row.payload_json);
+    if (profile === 'compact') {
+        const compact = {
+            eventId: row.event_id,
+            sessionId: row.session_id,
+            timestamp: row.ts,
+            type: row.type,
+            summary: describeEvent(row.type, payload),
+        };
+        if (row.type === 'console') {
+            compact.level = typeof payload.level === 'string' ? payload.level : undefined;
+            compact.message = typeof payload.message === 'string' ? payload.message : undefined;
+        }
+        if (row.type === 'nav') {
+            compact.url = resolveLastUrl(payload);
+        }
+        if (options.includePayload === true) {
+            compact.payload = payload;
+        }
+        return compact;
+    }
+    return {
+        eventId: row.event_id,
+        sessionId: row.session_id,
+        timestamp: row.ts,
+        type: row.type,
+        tabId: row.tab_id ?? (typeof payload.tabId === 'number' ? payload.tabId : undefined),
+        origin: row.origin
+            ?? (typeof payload.origin === 'string' ? payload.origin : undefined)
+            ?? undefined,
+        payload,
+    };
+}
+function classifyNetworkFailure(status, errorClass) {
+    if (errorClass && errorClass.length > 0) {
+        return errorClass;
+    }
+    if (typeof status === 'number' && status >= 400) {
+        return 'http_error';
+    }
+    return 'unknown';
+}
+function buildNetworkFailureFilter(errorType) {
+    if (typeof errorType !== 'string' || errorType.length === 0) {
+        return '(error_class IS NOT NULL OR COALESCE(status, 0) >= 400)';
+    }
+    if (errorType === 'http_error') {
+        return "(error_class = 'http_error' OR (error_class IS NULL AND COALESCE(status, 0) >= 400))";
+    }
+    return 'error_class = ?';
+}
+function resolveWindowSeconds(value, fallback, maxValue) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const floored = Math.floor(value);
+    if (floored < 1) {
+        return fallback;
+    }
+    return Math.min(floored, maxValue);
+}
+function resolveOptionalTimestamp(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const floored = Math.floor(value);
+    return floored < 0 ? undefined : floored;
+}
+function resolveChunkBytes(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const floored = Math.floor(value);
+    if (floored < 1) {
+        return fallback;
+    }
+    return Math.min(floored, MAX_SNAPSHOT_ASSET_CHUNK_BYTES);
 }
 function resolveDurationMs(value, fallback, maxValue) {
     if (typeof value !== 'number' || !Number.isFinite(value)) {
@@ -831,6 +2374,56 @@ function mapSnapshotMetadata(row) {
         createdAt: row.created_at,
     };
 }
+function mapAutomationRunRecord(row) {
+    return {
+        runId: row.run_id,
+        sessionId: row.session_id,
+        traceId: row.trace_id ?? undefined,
+        action: row.action ?? undefined,
+        tabId: row.tab_id ?? undefined,
+        selector: row.selector ?? undefined,
+        status: row.status,
+        startedAt: row.started_at,
+        completedAt: row.completed_at ?? undefined,
+        durationMs: typeof row.completed_at === 'number'
+            ? Math.max(0, row.completed_at - row.started_at)
+            : undefined,
+        stopReason: row.stop_reason ?? undefined,
+        target: parseJsonOrUndefined(row.target_summary_json),
+        failure: parseJsonOrUndefined(row.failure_json),
+        redaction: parseJsonOrUndefined(row.redaction_json),
+        stepCount: row.step_count,
+        lastStepAt: row.last_step_at ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        source: 'automation_runs',
+    };
+}
+function mapAutomationStepRecord(row) {
+    return {
+        stepId: row.step_id,
+        runId: row.run_id,
+        sessionId: row.session_id,
+        stepOrder: row.step_order,
+        traceId: row.trace_id ?? undefined,
+        action: row.action,
+        selector: row.selector ?? undefined,
+        status: row.status,
+        startedAt: row.started_at ?? undefined,
+        finishedAt: row.finished_at ?? undefined,
+        durationMs: row.duration_ms ?? undefined,
+        tabId: row.tab_id ?? undefined,
+        target: parseJsonOrUndefined(row.target_summary_json),
+        redaction: parseJsonOrUndefined(row.redaction_json),
+        failure: parseJsonOrUndefined(row.failure_json),
+        inputMetadata: parseJsonOrUndefined(row.input_metadata_json),
+        eventType: row.event_type,
+        eventId: row.event_id ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        source: 'automation_steps',
+    };
+}
 function formatUrlPath(url) {
     try {
         const parsed = new URL(url);
@@ -931,48 +2524,601 @@ function resolveCaptureAncestors(value, fallback) {
     }
     return Math.min(floored, 8);
 }
-function asStringArray(value, maxItems) {
-    if (!Array.isArray(value)) {
-        return [];
+function resolveStructuredMaxItems(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
     }
-    return value
-        .filter((entry) => typeof entry === 'string' && entry.length > 0)
-        .slice(0, maxItems);
+    const floored = Math.floor(value);
+    if (floored < 1) {
+        return fallback;
+    }
+    return Math.min(floored, 100);
 }
-const LIVE_CONSOLE_LEVELS = new Set(['log', 'info', 'warn', 'error', 'debug', 'trace']);
-function resolveLiveConsoleLevels(value) {
-    const levels = asStringArray(value, 16)
-        .map((entry) => entry.trim().toLowerCase())
-        .filter((entry) => LIVE_CONSOLE_LEVELS.has(entry));
-    return Array.from(new Set(levels));
+function resolveStructuredTextLength(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const floored = Math.floor(value);
+    if (floored < 8) {
+        return fallback;
+    }
+    return Math.min(floored, 200);
 }
-function asRecordArray(value) {
-    if (!Array.isArray(value)) {
-        return [];
+function resolveViewportDimension(value, axis) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`${axis} must be a finite number`);
     }
-    return value.filter((entry) => typeof entry === 'object' && entry !== null);
+    const floored = Math.floor(value);
+    const min = axis === 'width' ? 320 : 200;
+    const max = axis === 'width' ? 5120 : 4320;
+    if (floored < min || floored > max) {
+        throw new Error(`${axis} must be between ${min} and ${max}`);
+    }
+    return floored;
 }
-function mapLiveConsoleLogRecord(log, profile, options = {}) {
-    if (profile === 'compact') {
-        const compact = {
-            timestamp: typeof log.timestamp === 'number'
-                ? log.timestamp
-                : typeof log.ts === 'number'
-                    ? log.ts
-                    : undefined,
-            level: typeof log.level === 'string' ? log.level : undefined,
-            message: typeof log.message === 'string' ? log.message : '',
-        };
-        if (typeof log.count === 'number') {
-            compact.count = log.count;
-        }
-        if (typeof log.firstTimestamp === 'number') {
-            compact.firstTimestamp = log.firstTimestamp;
-        }
-        if (typeof log.lastTimestamp === 'number') {
-            compact.lastTimestamp = log.lastTimestamp;
-        }
-        if (options.includeArgs === true && Array.isArray(log.args)) {
+class WorkflowTargetResolutionError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'WorkflowTargetResolutionError';
+        this.code = code;
+        this.details = details;
+    }
+}
+function resolveOptionalMatcherString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function resolveOptionalMatcherBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function resolveOptionalMatcherCount(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const floored = Math.floor(value);
+    if (floored < 0) {
+        throw new Error(`${field} must be greater than or equal to 0`);
+    }
+    return floored;
+}
+function resolvePageStateScope(value) {
+    if (value === 'buttons' || value === 'inputs' || value === 'modals' || value === 'focused' || value === 'page') {
+        return value;
+    }
+    throw new Error('scope must be one of buttons, inputs, modals, focused, or page');
+}
+function resolvePageStateMatcher(input) {
+    const matcher = {
+        scope: resolvePageStateScope(input.scope),
+        selector: resolveOptionalMatcherString(input.selector),
+        testId: resolveOptionalMatcherString(input.testId),
+        textContains: resolveOptionalMatcherString(input.textContains),
+        labelContains: resolveOptionalMatcherString(input.labelContains),
+        titleContains: resolveOptionalMatcherString(input.titleContains),
+        urlContains: resolveOptionalMatcherString(input.urlContains),
+        language: resolveOptionalMatcherString(input.language),
+        disabled: resolveOptionalMatcherBoolean(input.disabled),
+        selected: resolveOptionalMatcherBoolean(input.selected),
+        pressed: resolveOptionalMatcherBoolean(input.pressed),
+        expanded: resolveOptionalMatcherBoolean(input.expanded),
+        readOnly: resolveOptionalMatcherBoolean(input.readOnly),
+        requiredField: resolveOptionalMatcherBoolean(input.requiredField),
+        tagName: resolveOptionalMatcherString(input.tagName)?.toLowerCase(),
+        type: resolveOptionalMatcherString(input.type)?.toLowerCase(),
+        countExactly: resolveOptionalMatcherCount(input.countExactly, 'countExactly'),
+        countAtLeast: resolveOptionalMatcherCount(input.countAtLeast, 'countAtLeast'),
+    };
+    if (matcher.countExactly !== undefined && matcher.countAtLeast !== undefined) {
+        throw new Error('countExactly and countAtLeast cannot both be set');
+    }
+    return matcher;
+}
+function includesNormalized(value, needle) {
+    if (!needle) {
+        return true;
+    }
+    return typeof value === 'string' && value.toLowerCase().includes(needle.toLowerCase());
+}
+function equalsNormalized(value, expected) {
+    if (!expected) {
+        return true;
+    }
+    return typeof value === 'string' && value.toLowerCase() === expected.toLowerCase();
+}
+function equalsOptionalBoolean(value, expected) {
+    if (expected === undefined) {
+        return true;
+    }
+    return value === expected;
+}
+function pickPageStateScopeItems(payload, scope) {
+    if (scope === 'buttons' || scope === 'inputs' || scope === 'modals') {
+        const value = payload[scope];
+        return asRecordArray(value);
+    }
+    if (scope === 'focused') {
+        const focused = payload.focused;
+        return typeof focused === 'object' && focused !== null ? [focused] : [];
+    }
+    return [payload];
+}
+function matchesPageStateItem(item, matcher) {
+    return (includesNormalized(item.selector, matcher.selector)
+        && equalsNormalized(item.testId, matcher.testId)
+        && includesNormalized(item.text, matcher.textContains)
+        && includesNormalized(item.label, matcher.labelContains)
+        && includesNormalized(item.title, matcher.titleContains)
+        && includesNormalized(item.url, matcher.urlContains)
+        && equalsNormalized(item.language, matcher.language)
+        && equalsNormalized(item.tagName, matcher.tagName)
+        && equalsNormalized(item.type, matcher.type)
+        && equalsOptionalBoolean(item.disabled, matcher.disabled)
+        && equalsOptionalBoolean(item.selected, matcher.selected)
+        && equalsOptionalBoolean(item.pressed, matcher.pressed)
+        && equalsOptionalBoolean(item.expanded, matcher.expanded)
+        && equalsOptionalBoolean(item.readOnly, matcher.readOnly)
+        && equalsOptionalBoolean(item.required, matcher.requiredField));
+}
+function evaluatePageStateAssertion(payload, matcher) {
+    const scopeItems = pickPageStateScopeItems(payload, matcher.scope);
+    const matchingItems = scopeItems.filter((item) => matchesPageStateItem(item, matcher));
+    const matchCount = matchingItems.length;
+    const matched = matcher.countExactly !== undefined
+        ? matchCount === matcher.countExactly
+        : matcher.countAtLeast !== undefined
+            ? matchCount >= matcher.countAtLeast
+            : matchCount >= 1;
+    return {
+        matched,
+        matchCount,
+        sampledMatches: matchingItems.slice(0, 5),
+        expectedCount: {
+            countExactly: matcher.countExactly,
+            countAtLeast: matcher.countAtLeast,
+        },
+        summary: typeof payload.summary === 'object' && payload.summary !== null
+            ? payload.summary
+            : undefined,
+    };
+}
+function extractPageSummarySnapshot(capture) {
+    if (!capture) {
+        return undefined;
+    }
+    const summary = typeof capture.payload.summary === 'object' && capture.payload.summary !== null
+        ? capture.payload.summary
+        : undefined;
+    const focused = typeof capture.payload.focused === 'object' && capture.payload.focused !== null
+        ? capture.payload.focused
+        : undefined;
+    return {
+        url: typeof capture.payload.url === 'string' ? capture.payload.url : undefined,
+        language: typeof capture.payload.language === 'string' ? capture.payload.language : undefined,
+        summary,
+        focusedText: typeof focused?.text === 'string' ? focused.text : undefined,
+    };
+}
+function createPageChangeSummary(previousCapture, currentCapture) {
+    const previous = extractPageSummarySnapshot(previousCapture);
+    const current = extractPageSummarySnapshot(currentCapture);
+    if (!current) {
+        return undefined;
+    }
+    const changes = [];
+    const previousSummary = previous?.summary;
+    const currentSummary = current.summary;
+    const summaryDelta = {};
+    for (const key of ['buttons', 'inputs', 'modals']) {
+        const previousValue = typeof previousSummary?.[key] === 'number' ? previousSummary[key] : undefined;
+        const currentValue = typeof currentSummary?.[key] === 'number' ? currentSummary[key] : undefined;
+        if (previousValue !== currentValue && currentValue !== undefined) {
+            summaryDelta[key] = {
+                previous: previousValue,
+                current: currentValue,
+            };
+            changes.push(`${key} ${previousValue ?? 0} -> ${currentValue}`);
+        }
+    }
+    if (previous?.url && current.url && previous.url !== current.url) {
+        changes.push(`url changed`);
+    }
+    if (previous?.language && current.language && previous.language !== current.language) {
+        changes.push(`language ${previous.language} -> ${current.language}`);
+    }
+    if ((previous?.focusedText ?? '') !== (current.focusedText ?? '') && current.focusedText) {
+        changes.push('focused element changed');
+    }
+    return {
+        changes,
+        previous: previous ?? null,
+        current,
+        summaryDelta,
+    };
+}
+function resolveInteractiveKinds(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return ['buttons', 'inputs', 'modals', 'focused'];
+    }
+    const allowed = new Set(['buttons', 'inputs', 'modals', 'focused']);
+    const kinds = value
+        .filter((entry) => typeof entry === 'string' && allowed.has(entry))
+        .map((entry) => entry);
+    return kinds.length > 0 ? Array.from(new Set(kinds)) : ['buttons', 'inputs', 'modals', 'focused'];
+}
+function collectInteractiveElementRefs(payload, kinds, maxItems) {
+    const refs = [];
+    for (const kind of kinds) {
+        if (kind === 'focused') {
+            const focused = typeof payload.focused === 'object' && payload.focused !== null
+                ? payload.focused
+                : undefined;
+            if (focused?.elementRef) {
+                refs.push({
+                    kind,
+                    ...focused,
+                });
+            }
+            continue;
+        }
+        for (const item of asRecordArray(payload[kind])) {
+            refs.push({
+                kind,
+                ...item,
+            });
+            if (refs.length >= maxItems) {
+                return refs.slice(0, maxItems);
+            }
+        }
+    }
+    return refs.slice(0, maxItems);
+}
+async function waitForPageStateConditionDetailed(sessionId, input, capturePageState, initialCapture) {
+    const matcher = resolvePageStateMatcher(input);
+    const timeoutMs = resolveTimeoutMs(input.timeoutMs, 5_000, 30_000);
+    const pollIntervalMs = resolveDurationMs(input.pollIntervalMs, 50, 2_000) ?? 200;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    let attempts = 0;
+    let lastCapture = initialCapture;
+    let lastAssertion;
+    if (lastCapture) {
+        lastAssertion = evaluatePageStateAssertion(lastCapture.payload, matcher);
+        if (lastAssertion.matched) {
+            return {
+                limitsApplied: lastCapture.limitsApplied,
+                matcher,
+                matched: true,
+                matchCount: lastAssertion.matchCount,
+                expectedCount: lastAssertion.expectedCount,
+                sampledMatches: lastAssertion.sampledMatches,
+                pageSummary: lastAssertion.summary,
+                page: {
+                    url: lastCapture.payload.url,
+                    title: lastCapture.payload.title,
+                    language: lastCapture.payload.language,
+                    viewport: lastCapture.payload.viewport,
+                },
+                waitedMs: 0,
+                attempts,
+                pollIntervalMs,
+                lastCapture,
+            };
+        }
+    }
+    while (Date.now() <= deadline) {
+        attempts += 1;
+        lastCapture = await capturePageState(sessionId, input);
+        lastAssertion = evaluatePageStateAssertion(lastCapture.payload, matcher);
+        if (lastAssertion.matched) {
+            return {
+                limitsApplied: lastCapture.limitsApplied,
+                matcher,
+                matched: true,
+                matchCount: lastAssertion.matchCount,
+                expectedCount: lastAssertion.expectedCount,
+                sampledMatches: lastAssertion.sampledMatches,
+                pageSummary: lastAssertion.summary,
+                page: {
+                    url: lastCapture.payload.url,
+                    title: lastCapture.payload.title,
+                    language: lastCapture.payload.language,
+                    viewport: lastCapture.payload.viewport,
+                },
+                waitedMs: Date.now() - startedAt,
+                attempts,
+                pollIntervalMs,
+                lastCapture,
+            };
+        }
+        await sleep(pollIntervalMs);
+    }
+    return {
+        limitsApplied: lastCapture?.limitsApplied ?? { maxResults: 0, truncated: false },
+        matcher,
+        matched: false,
+        matchCount: lastAssertion?.matchCount ?? 0,
+        expectedCount: lastAssertion?.expectedCount ?? {
+            countExactly: matcher.countExactly,
+            countAtLeast: matcher.countAtLeast,
+        },
+        sampledMatches: lastAssertion?.sampledMatches ?? [],
+        pageSummary: lastAssertion?.summary,
+        page: lastCapture
+            ? {
+                url: lastCapture.payload.url,
+                title: lastCapture.payload.title,
+                language: lastCapture.payload.language,
+                viewport: lastCapture.payload.viewport,
+            }
+            : undefined,
+        waitedMs: Date.now() - startedAt,
+        attempts,
+        pollIntervalMs,
+        timeoutMs,
+        lastCapture,
+    };
+}
+async function waitForPageStateCondition(sessionId, input, capturePageState) {
+    const detailed = await waitForPageStateConditionDetailed(sessionId, input, capturePageState);
+    const { lastCapture: _lastCapture, ...waited } = detailed;
+    return waited;
+}
+function candidateTextForWorkflowTarget(item) {
+    return [item.text, item.label, item.title]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join(' ')
+        .trim();
+}
+function describeWorkflowTargetCandidate(item) {
+    return {
+        text: candidateTextForWorkflowTarget(item) || undefined,
+        testId: typeof item.testId === 'string' ? item.testId : undefined,
+        selector: typeof item.selector === 'string' ? item.selector : undefined,
+        tagName: typeof item.tagName === 'string' ? item.tagName : undefined,
+        type: typeof item.type === 'string' ? item.type : undefined,
+        disabled: typeof item.disabled === 'boolean' ? item.disabled : undefined,
+        selected: typeof item.selected === 'boolean' ? item.selected : undefined,
+    };
+}
+function pickWorkflowTargetItems(payload, scope) {
+    if (scope) {
+        return pickPageStateScopeItems(payload, scope);
+    }
+    return [
+        ...pickPageStateScopeItems(payload, 'buttons'),
+        ...pickPageStateScopeItems(payload, 'inputs'),
+        ...pickPageStateScopeItems(payload, 'modals'),
+        ...pickPageStateScopeItems(payload, 'focused'),
+    ];
+}
+function matchesWorkflowActionTarget(item, target) {
+    return (equalsNormalized(item.testId, target.testId)
+        && includesNormalized(item.text, target.textContains)
+        && includesNormalized(item.label, target.labelContains)
+        && includesNormalized(item.title, target.titleContains)
+        && equalsNormalized(item.tagName, target.tagName)
+        && equalsNormalized(item.type, target.type)
+        && equalsOptionalBoolean(item.disabled, target.disabled)
+        && equalsOptionalBoolean(item.selected, target.selected)
+        && equalsOptionalBoolean(item.pressed, target.pressed)
+        && equalsOptionalBoolean(item.expanded, target.expanded)
+        && equalsOptionalBoolean(item.readOnly, target.readOnly)
+        && equalsOptionalBoolean(item.required, target.requiredField)
+        && (typeof item.elementRef === 'string' || typeof item.selector === 'string'));
+}
+function summarizeWorkflowTargetMatcher(target) {
+    return {
+        scope: target.scope,
+        selector: target.selector,
+        elementRef: target.elementRef,
+        testId: target.testId,
+        textContains: target.textContains,
+        labelContains: target.labelContains,
+        titleContains: target.titleContains,
+        tagName: target.tagName,
+        type: target.type,
+        disabled: target.disabled,
+        selected: target.selected,
+        pressed: target.pressed,
+        expanded: target.expanded,
+        readOnly: target.readOnly,
+        requiredField: target.requiredField,
+    };
+}
+async function resolveWorkflowActionTarget(sessionId, target, capturePageState, existingCapture) {
+    if (!target) {
+        return {
+            resolution: {
+                strategy: 'none',
+            },
+        };
+    }
+    if (target.elementRef || target.selector) {
+        return {
+            target: {
+                elementRef: target.elementRef,
+                selector: target.selector,
+                tabId: target.tabId,
+                frameId: target.frameId,
+                url: target.url,
+            },
+            resolution: {
+                strategy: target.elementRef ? 'elementRef' : 'selector',
+                matcher: summarizeWorkflowTargetMatcher(target),
+            },
+        };
+    }
+    const capture = existingCapture ?? await capturePageState(sessionId, {
+        includeButtons: target.scope ? target.scope === 'buttons' : true,
+        includeInputs: target.scope ? target.scope === 'inputs' : true,
+        includeModals: target.scope ? target.scope === 'modals' : true,
+        maxItems: 100,
+        maxTextLength: 120,
+    });
+    const candidates = pickWorkflowTargetItems(capture.payload, target.scope)
+        .filter((item) => matchesWorkflowActionTarget(item, target));
+    if (candidates.length === 0) {
+        throw new WorkflowTargetResolutionError('workflow_target_not_found', 'No interactive element matched the workflow target.', {
+            matcher: summarizeWorkflowTargetMatcher(target),
+            searchedScope: target.scope ?? 'all-interactive',
+            sampledCandidates: pickWorkflowTargetItems(capture.payload, target.scope)
+                .slice(0, 5)
+                .map((item) => describeWorkflowTargetCandidate(item)),
+        });
+    }
+    if (candidates.length > 1) {
+        throw new WorkflowTargetResolutionError('workflow_target_ambiguous', `Workflow target matched ${candidates.length} elements; refine the matcher.`, {
+            matcher: summarizeWorkflowTargetMatcher(target),
+            matchedCandidateCount: candidates.length,
+            sampledCandidates: candidates.slice(0, 5).map((item) => describeWorkflowTargetCandidate(item)),
+        });
+    }
+    const candidate = candidates[0];
+    return {
+        target: {
+            elementRef: typeof candidate.elementRef === 'string' ? candidate.elementRef : undefined,
+            selector: typeof candidate.selector === 'string' ? candidate.selector : undefined,
+            tabId: target.tabId,
+            frameId: target.frameId,
+            url: target.url,
+        },
+        resolution: {
+            strategy: typeof candidate.elementRef === 'string' ? 'semantic_elementRef' : 'semantic_selector',
+            matcher: summarizeWorkflowTargetMatcher(target),
+            matchedCandidateCount: candidates.length,
+            matched: describeWorkflowTargetCandidate(candidate),
+        },
+        pageCapture: capture,
+    };
+}
+function createWorkflowStepId(step, index) {
+    return step.id ?? `step_${index + 1}`;
+}
+async function captureWorkflowPageState(sessionId, capturePageState, mode) {
+    const maxItems = mode === 'fast' ? 12 : 20;
+    const maxTextLength = mode === 'fast' ? 60 : 80;
+    return capturePageState(sessionId, {
+        includeButtons: true,
+        includeInputs: true,
+        includeModals: true,
+        maxItems,
+        maxTextLength,
+    });
+}
+function normalizeWorkflowError(error) {
+    if (error instanceof WorkflowTargetResolutionError) {
+        return {
+            code: error.code,
+            message: `${error.message} ${JSON.stringify(error.details)}`,
+        };
+    }
+    if (error instanceof z.ZodError) {
+        return {
+            code: 'invalid_workflow_step',
+            message: error.issues.map((issue) => issue.message).join('; '),
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: 'workflow_step_failed',
+            message: error.message,
+        };
+    }
+    return {
+        code: 'workflow_step_failed',
+        message: 'Unknown workflow step failure',
+    };
+}
+function resolveWorkflowRecommendedAction(error) {
+    if (!error) {
+        return undefined;
+    }
+    if (error.code === LIVE_SESSION_DISCONNECTED_CODE
+        || error.message.includes(LIVE_SESSION_DISCONNECTED_CODE)
+        || error.message.toLowerCase().includes('transport closed')) {
+        return 'reconnect_session';
+    }
+    if (error.code === 'target_not_found') {
+        return 'inspect_page_state';
+    }
+    if (error.code === 'click_intercepted') {
+        return 'retry_step';
+    }
+    if (error.code === 'workflow_target_ambiguous') {
+        return 'refine_target';
+    }
+    if (error.code === 'workflow_target_not_found') {
+        return 'inspect_page_state';
+    }
+    if (error.code === 'page_state_not_matched' || error.code === 'page_state_assertion_failed') {
+        return 'inspect_page_state';
+    }
+    return undefined;
+}
+function resolveWorkflowFailureSelector(step, stepResultTarget) {
+    if (step.kind === 'action') {
+        if (typeof step.target?.selector === 'string' && step.target.selector.trim().length > 0) {
+            return step.target.selector.trim();
+        }
+        const actionTarget = isRecord(stepResultTarget?.actionTarget) ? stepResultTarget?.actionTarget : undefined;
+        if (typeof actionTarget?.selector === 'string' && actionTarget.selector.trim().length > 0) {
+            return actionTarget.selector.trim();
+        }
+        const resolution = isRecord(stepResultTarget?.resolution) ? stepResultTarget?.resolution : undefined;
+        const matched = isRecord(resolution?.matched) ? resolution.matched : undefined;
+        if (typeof matched?.selector === 'string' && matched.selector.trim().length > 0) {
+            return matched.selector.trim();
+        }
+    }
+    return undefined;
+}
+function asStringArray(value, maxItems) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry) => typeof entry === 'string' && entry.length > 0)
+        .slice(0, maxItems);
+}
+const LIVE_CONSOLE_LEVELS = new Set(['log', 'info', 'warn', 'error', 'debug', 'trace']);
+function resolveLiveConsoleLevels(value) {
+    const levels = asStringArray(value, 16)
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => LIVE_CONSOLE_LEVELS.has(entry));
+    return Array.from(new Set(levels));
+}
+function asRecordArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'object' && entry !== null);
+}
+function mapLiveConsoleLogRecord(log, profile, options = {}) {
+    if (profile === 'compact') {
+        const compact = {
+            timestamp: typeof log.timestamp === 'number'
+                ? log.timestamp
+                : typeof log.ts === 'number'
+                    ? log.ts
+                    : undefined,
+            level: typeof log.level === 'string' ? log.level : undefined,
+            message: typeof log.message === 'string' ? log.message : '',
+        };
+        if (typeof log.count === 'number') {
+            compact.count = log.count;
+        }
+        if (typeof log.firstTimestamp === 'number') {
+            compact.firstTimestamp = log.firstTimestamp;
+        }
+        if (typeof log.lastTimestamp === 'number') {
+            compact.lastTimestamp = log.lastTimestamp;
+        }
+        if (options.includeArgs === true && Array.isArray(log.args)) {
             compact.args = log.args;
         }
         return compact;
@@ -1027,6 +3173,243 @@ function ensureCaptureSuccess(result, sessionId) {
     }
     return result.payload ?? {};
 }
+function auditSessionExists(db, sessionId) {
+    const row = db.prepare('SELECT 1 FROM sessions WHERE session_id = ? LIMIT 1').get(sessionId);
+    return row !== undefined;
+}
+function hashLocalFileIfPresent(filePath) {
+    if (!filePath || !existsSync(filePath)) {
+        return { sha256: null, bytes: null };
+    }
+    const stat = statSync(filePath);
+    if (!stat.isFile()) {
+        return { sha256: null, bytes: null };
+    }
+    return {
+        sha256: createHash('sha256').update(readFileSync(filePath)).digest('hex'),
+        bytes: stat.size,
+    };
+}
+function resolveAuditProfileId(input) {
+    return normalizeOptionalString(input.profileId) ?? null;
+}
+function buildOverrideRollbackMetadata(options) {
+    return {
+        disableTool: 'disable_overrides',
+        validateTool: 'validate_override_profile',
+        sessionId: options.sessionId,
+        profileId: options.profileId,
+        configPath: options.configPath ?? null,
+        generatedFiles: Array.from(new Set(options.generatedFiles.filter((entry) => entry.trim().length > 0))),
+        generatedDirectories: Array.from(new Set((options.generatedDirectories ?? []).filter((entry) => entry.trim().length > 0))),
+        notes: [
+            'Disable overrides for this session before deleting generated files or config entries.',
+            'Re-run validate_override_profile after editing or removing generated config rules.',
+            options.note,
+        ].filter((entry) => typeof entry === 'string' && entry.length > 0),
+    };
+}
+function persistResponsePlanAudit(options) {
+    if (!options.sessionId || !options.plan.rule || !auditSessionExists(options.db, options.sessionId)) {
+        return undefined;
+    }
+    const profileId = resolveAuditProfileId(options.input);
+    const record = {
+        planId: randomUUID(),
+        sessionId: options.sessionId,
+        createdAt: Date.now(),
+        plannerKind: 'response-patch',
+        toolName: 'plan_override_response_patch',
+        profileId,
+        ruleId: options.plan.rule.ruleId,
+        ruleType: options.plan.rule.ruleType,
+        requestMethod: options.plan.requestMethod,
+        matchMode: options.plan.matchMode,
+        targetAssetUrl: options.plan.targetUrl,
+        localFilePath: options.plan.localFilePath ?? options.plan.rule.localFilePath,
+        configPath: options.plan.configPath ?? null,
+        contentType: options.plan.contentType,
+        originalSha256: options.plan.originalSha256,
+        patchedSha256: options.plan.patchedSha256,
+        originalBytes: options.plan.originalBytes,
+        patchedBytes: options.plan.patchedBytes,
+        patchSummary: {
+            textPatches: options.plan.patches,
+            jsonPatches: options.plan.jsonPatches,
+            documentPatches: options.plan.documentPatches,
+            ruleType: options.plan.ruleType,
+            configWritten: options.plan.configWritten,
+            rscFlight: options.plan.rule.rscFlight ?? null,
+            variantContext: options.variantContext ?? null,
+        },
+        preview: options.plan.preview ?? null,
+        warnings: options.plan.warnings,
+        blockers: options.plan.blockers,
+        capturedFromLiveSession: options.capturedFromLiveSession ?? null,
+        rollback: buildOverrideRollbackMetadata({
+            sessionId: options.sessionId,
+            profileId,
+            configPath: options.plan.configPath ?? null,
+            generatedFiles: options.plan.localFilePath ? [options.plan.localFilePath] : [],
+            note: 'Generated response override bodies are disposable once the override has been disabled.',
+        }),
+    };
+    return insertOverridePlanAudit(options.db, record);
+}
+function persistNextSourcePlanAudits(options) {
+    if (!options.sessionId || !auditSessionExists(options.db, options.sessionId)) {
+        return [];
+    }
+    const sessionId = options.sessionId;
+    const profileId = resolveAuditProfileId(options.input);
+    const generatedFiles = options.plan.rules.map((rule) => rule.localFilePath);
+    return options.plan.rules.map((rule) => {
+        const localFile = hashLocalFileIfPresent(rule.localFilePath);
+        const record = {
+            planId: randomUUID(),
+            sessionId: options.sessionId,
+            createdAt: Date.now(),
+            plannerKind: 'next-source-overlay',
+            toolName: 'plan_next_source_override',
+            profileId,
+            ruleId: rule.ruleId,
+            ruleType: rule.ruleType,
+            requestMethod: rule.requestMethod,
+            matchMode: rule.matchMode,
+            targetAssetUrl: rule.targetAssetUrl,
+            localFilePath: rule.localFilePath,
+            configPath: options.plan.configPath ?? null,
+            contentType: rule.contentType,
+            originalSha256: null,
+            patchedSha256: localFile.sha256,
+            originalBytes: null,
+            patchedBytes: localFile.bytes,
+            patchSummary: {
+                sourcePaths: options.plan.sourcePaths,
+                editsApplied: options.plan.editsApplied,
+                ruleReason: rule.reason,
+                confidence: rule.confidence,
+                score: rule.score,
+                matchedSourcePaths: rule.matchedSourcePaths,
+                originalAssetPath: rule.originalAssetPath ?? null,
+                build: options.plan.build,
+                configWritten: options.plan.configWritten,
+            },
+            preview: null,
+            warnings: [...options.plan.warnings, ...rule.blockers.map((blocker) => `rule ${rule.ruleId}: ${blocker}`)],
+            blockers: options.plan.blockers,
+            capturedFromLiveSession: null,
+            rollback: buildOverrideRollbackMetadata({
+                sessionId,
+                profileId,
+                configPath: options.plan.configPath ?? null,
+                generatedFiles,
+                generatedDirectories: [options.plan.overlayRoot],
+                note: 'Generated Next.js overlay folders are disposable once the override has been disabled.',
+            }),
+        };
+        return insertOverridePlanAudit(options.db, record);
+    });
+}
+function normalizeSnapshotResponsePayload(payload, options) {
+    const snapshotRecord = structuredClone(payload);
+    const snapshotRoot = snapshotRecord.snapshot;
+    if (typeof snapshotRoot === 'object' && snapshotRoot !== null) {
+        const snapshotObject = snapshotRoot;
+        if (!options.includeDom) {
+            delete snapshotObject.dom;
+        }
+        if (!options.includeStyles) {
+            delete snapshotObject.styles;
+        }
+    }
+    const png = snapshotRecord.png;
+    if (!options.includePngDataUrl && typeof png === 'object' && png !== null) {
+        delete png.dataUrl;
+    }
+    return snapshotRecord;
+}
+function resolveFailureEvidenceCaptureOptions(input) {
+    const raw = isRecord(input.captureOnFailure) ? input.captureOnFailure : undefined;
+    const enabled = raw !== undefined ? raw.enabled !== false : false;
+    const mode = raw?.mode === 'png' || raw?.mode === 'both' || raw?.mode === 'dom' ? raw.mode : 'dom';
+    const styleMode = raw?.styleMode === 'computed-full' || raw?.styleMode === 'computed-lite'
+        ? raw.styleMode
+        : 'computed-lite';
+    return {
+        enabled,
+        selector: typeof raw?.selector === 'string' && raw.selector.trim().length > 0 ? raw.selector.trim() : undefined,
+        mode,
+        styleMode,
+        explicitStyleMode: raw?.styleMode === 'computed-full' || raw?.styleMode === 'computed-lite',
+        maxDepth: resolveCaptureDepth(raw?.maxDepth, 3),
+        maxBytes: resolveCaptureBytes(raw?.maxBytes, 50_000),
+        maxAncestors: resolveCaptureAncestors(raw?.maxAncestors, 4),
+        includeDom: typeof raw?.includeDom === 'boolean' ? raw.includeDom : mode !== 'png',
+        includeStyles: typeof raw?.includeStyles === 'boolean' ? raw.includeStyles : mode !== 'png',
+        includePngDataUrl: typeof raw?.includePngDataUrl === 'boolean' ? raw.includePngDataUrl : mode !== 'png',
+    };
+}
+function resolveWorkflowFailurePolicy(step, stopOnFailure) {
+    const raw = isRecord(step.onFailure) ? step.onFailure : undefined;
+    const strategy = raw?.strategy === 'continue' || raw?.strategy === 'retry_once' || raw?.strategy === 'stop'
+        ? raw.strategy
+        : stopOnFailure === false
+            ? 'continue'
+            : 'stop';
+    const captureRaw = raw && isRecord(raw.capture)
+        ? {
+            captureOnFailure: {
+                ...raw.capture,
+                enabled: raw.capture.enabled ?? true,
+            },
+        }
+        : undefined;
+    return {
+        strategy,
+        captureOptions: captureRaw ? resolveFailureEvidenceCaptureOptions(captureRaw) : undefined,
+    };
+}
+async function captureFailureSnapshot(captureClient, sessionId, selector, options) {
+    if (!options.enabled) {
+        return undefined;
+    }
+    try {
+        const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_UI_SNAPSHOT', {
+            selector: options.selector ?? selector,
+            trigger: 'error',
+            mode: options.mode,
+            styleMode: options.styleMode,
+            explicitStyleMode: options.explicitStyleMode,
+            maxDepth: options.maxDepth,
+            maxBytes: options.maxBytes,
+            maxAncestors: options.maxAncestors,
+            includeDom: options.includeDom,
+            includeStyles: options.includeStyles,
+            includePngDataUrl: options.includePngDataUrl,
+            llmRequested: true,
+        }, 5_000);
+        const payload = ensureCaptureSuccess(capture, sessionId);
+        return {
+            captured: true,
+            limitsApplied: {
+                maxBytes: options.maxBytes,
+                truncated: capture.truncated ?? false,
+            },
+            snapshot: normalizeSnapshotResponsePayload(payload, options),
+        };
+    }
+    catch (error) {
+        const normalized = normalizeCaptureError(sessionId, error);
+        return {
+            captured: false,
+            error: normalized.message,
+        };
+    }
+}
+async function captureFailureEvidence(captureClient, sessionId, request, options) {
+    return captureFailureSnapshot(captureClient, sessionId, request.target?.selector, options);
+}
 export function createV1ToolHandlers(getDb, getSessionConnectionState) {
     return {
         list_sessions: async (input) => {
@@ -1038,7 +3421,12 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
             const where = [];
             const params = [];
             if (sinceMinutes !== undefined && Number.isFinite(sinceMinutes) && sinceMinutes > 0) {
-                where.push('created_at >= ?');
+                where.push(`
+          CASE
+            WHEN COALESCE(last_seen_at, 0) > created_at THEN COALESCE(last_seen_at, 0)
+            ELSE created_at
+          END >= ?
+        `);
                 params.push(Date.now() - Math.floor(sinceMinutes * 60_000));
             }
             const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
@@ -1046,6 +3434,7 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
         SELECT
           session_id,
           created_at,
+          last_seen_at,
           paused_at,
           ended_at,
           tab_id,
@@ -1060,49 +3449,48 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
           pinned
         FROM sessions
         ${whereClause}
-        ORDER BY created_at DESC
+        ORDER BY
+          CASE
+            WHEN COALESCE(last_seen_at, 0) > created_at THEN COALESCE(last_seen_at, 0)
+            ELSE created_at
+          END DESC,
+          created_at DESC
         LIMIT ? OFFSET ?
       `;
             const rows = db.prepare(sql).all(...params, limit + 1, offset);
             const truncatedByLimit = rows.length > limit;
-            const sessions = rows.slice(0, limit).map((row) => ({
-                sessionId: row.session_id,
-                createdAt: row.created_at,
-                pausedAt: row.paused_at ?? undefined,
-                endedAt: row.ended_at ?? undefined,
-                status: row.ended_at ? 'ended' : row.paused_at ? 'paused' : 'active',
-                tabId: row.tab_id ?? undefined,
-                windowId: row.window_id ?? undefined,
-                urlStart: row.url_start ?? undefined,
-                urlLast: row.url_last ?? undefined,
-                userAgent: row.user_agent ?? undefined,
-                viewport: row.viewport_w !== null && row.viewport_h !== null
-                    ? {
-                        width: row.viewport_w,
-                        height: row.viewport_h,
-                    }
-                    : undefined,
-                dpr: row.dpr ?? undefined,
-                safeMode: row.safe_mode === 1,
-                pinned: row.pinned === 1,
-                liveConnection: (() => {
-                    const state = getSessionConnectionState?.(row.session_id);
-                    if (!state) {
-                        return {
-                            connected: false,
-                            lastHeartbeatAt: undefined,
-                            disconnectReason: row.ended_at ? 'manual_stop' : undefined,
-                        };
-                    }
-                    return {
-                        connected: state.connected,
-                        connectedAt: state.connectedAt,
-                        lastHeartbeatAt: state.lastHeartbeatAt,
-                        disconnectedAt: state.disconnectedAt,
-                        disconnectReason: state.disconnectReason,
-                    };
-                })(),
-            }));
+            const sessions = rows.slice(0, limit).map((row) => {
+                const status = getSessionStatus(row);
+                const state = getSessionConnectionState?.(row.session_id);
+                const lastUrl = row.url_last ?? undefined;
+                const scope = classifySessionUrl(lastUrl);
+                const liveConnection = buildLiveConnectionRecord(row, scope, state);
+                return {
+                    sessionId: row.session_id,
+                    createdAt: row.created_at,
+                    lastSeenAt: resolveSessionLastSeenAt(row, state),
+                    pausedAt: row.paused_at ?? undefined,
+                    endedAt: row.ended_at ?? undefined,
+                    status,
+                    tabId: row.tab_id ?? undefined,
+                    windowId: row.window_id ?? undefined,
+                    urlStart: row.url_start ?? undefined,
+                    urlLast: lastUrl,
+                    lastUrl,
+                    userAgent: row.user_agent ?? undefined,
+                    viewport: row.viewport_w !== null && row.viewport_h !== null
+                        ? {
+                            width: row.viewport_w,
+                            height: row.viewport_h,
+                        }
+                        : undefined,
+                    dpr: row.dpr ?? undefined,
+                    safeMode: row.safe_mode === 1,
+                    pinned: row.pinned === 1,
+                    scope,
+                    liveConnection,
+                };
+            });
             const bytePage = applyByteBudget(sessions, maxResponseBytes);
             const truncated = truncatedByLimit || bytePage.truncatedByBytes;
             return {
@@ -1178,35 +3566,510 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
                 pinned: session.pinned === 1,
             };
         },
-        get_recent_events: async (input) => {
+        get_live_session_health: async (input) => {
             const db = getDb();
             const sessionId = getSessionId(input);
-            const origin = normalizeRequestedOrigin(input.url);
-            ensureSessionOrOriginFilter(sessionId, origin);
-            const limit = resolveLimit(input.limit, DEFAULT_EVENT_LIMIT);
-            const offset = resolveOffset(input.offset);
-            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
-            const responseProfile = resolveResponseProfile(input.responseProfile);
-            const includePayload = responseProfile === 'compact' && input.includePayload === true;
-            const requestedTypes = parseRequestedTypes(input.types ?? input.eventTypes);
-            const params = [];
-            const where = [];
-            if (sessionId) {
-                where.push('session_id = ?');
-                params.push(sessionId);
-            }
-            appendEventOriginFilter(where, params, origin);
-            if (requestedTypes.length > 0) {
-                const placeholders = requestedTypes.map(() => '?').join(', ');
-                where.push(`type IN (${placeholders})`);
-                params.push(...requestedTypes);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
             }
-            const rows = db
+            const session = db
                 .prepare(`
-        SELECT event_id, session_id, ts, type, payload_json, tab_id, origin
-        FROM events
-        WHERE ${where.join(' AND ')}
-        ORDER BY ts DESC
+          SELECT
+            session_id,
+            created_at,
+            last_seen_at,
+            paused_at,
+            ended_at,
+            tab_id,
+            window_id,
+            url_start,
+            url_last,
+            viewport_w,
+            viewport_h,
+            dpr,
+            safe_mode,
+            pinned
+          FROM sessions
+          WHERE session_id = ?
+        `)
+                .get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            const latestNav = db
+                .prepare(`
+          SELECT payload_json
+          FROM events
+          WHERE session_id = ? AND type = 'nav'
+          ORDER BY ts DESC
+          LIMIT 1
+        `)
+                .get(sessionId);
+            const navPayload = latestNav ? readJsonPayload(latestNav.payload_json) : {};
+            const lastUrl = resolveLastUrl(navPayload) ?? session.url_last ?? undefined;
+            const scope = classifySessionUrl(lastUrl);
+            const connectionState = getSessionConnectionState?.(sessionId);
+            const liveConnection = buildLiveConnectionRecord(session, scope, connectionState);
+            const status = getSessionStatus(session);
+            const lastSeenAt = resolveSessionLastSeenAt(session, connectionState);
+            const nextAction = buildLiveSessionNextAction(liveConnection, scope);
+            const recommendedAction = buildLiveSessionRecommendedAction(liveConnection, scope);
+            const sessionRecord = {
+                sessionId: session.session_id,
+                createdAt: session.created_at,
+                lastSeenAt,
+                pausedAt: session.paused_at ?? undefined,
+                endedAt: session.ended_at ?? undefined,
+                status,
+                tabId: session.tab_id ?? undefined,
+                windowId: session.window_id ?? undefined,
+                urlStart: session.url_start ?? undefined,
+                urlLast: session.url_last ?? undefined,
+                lastUrl,
+                viewport: session.viewport_w !== null && session.viewport_h !== null
+                    ? {
+                        width: session.viewport_w,
+                        height: session.viewport_h,
+                    }
+                    : undefined,
+                dpr: session.dpr ?? undefined,
+                safeMode: session.safe_mode === 1,
+                pinned: session.pinned === 1,
+            };
+            return {
+                ...createBaseResponse(sessionId),
+                status,
+                createdAt: session.created_at,
+                lastSeenAt,
+                pausedAt: session.paused_at ?? undefined,
+                endedAt: session.ended_at ?? undefined,
+                tabId: session.tab_id ?? undefined,
+                windowId: session.window_id ?? undefined,
+                lastUrl,
+                safeMode: session.safe_mode === 1,
+                pinned: session.pinned === 1,
+                session: sessionRecord,
+                scope,
+                liveConnection,
+                nextAction,
+                recommendedAction,
+            };
+        },
+        list_override_profiles: async () => {
+            const profiles = buildOverrideProfileRecords();
+            return {
+                ...createBaseResponse(),
+                limitsApplied: {
+                    maxResults: profiles.length,
+                    truncated: false,
+                },
+                profiles,
+                nextActions: profiles.length > 0
+                    ? [{ code: 'VALIDATE_PROFILE', message: 'Run validate_override_profile before enabling overrides.' }]
+                    : [{ code: 'CREATE_PROFILE', message: 'Run create_override_profile to generate a candidate profile.' }],
+            };
+        },
+        create_override_profile: async (input) => {
+            const adapterInput = normalizeOptionalString(input.adapter) ?? normalizeOptionalString(input.mode);
+            let adapter;
+            if (adapterInput !== undefined) {
+                if (!OVERRIDE_PROFILE_ADAPTERS.includes(adapterInput)) {
+                    throw new Error(`adapter must be one of: ${OVERRIDE_PROFILE_ADAPTERS.join(', ')}`);
+                }
+                adapter = adapterInput;
+            }
+            const targetBaseUrl = normalizeOptionalString(input.targetBaseUrl);
+            if (!targetBaseUrl) {
+                throw new Error('targetBaseUrl is required, for example https://example.com/_next/ or https://example.com/assets/');
+            }
+            const generated = createOverrideProfileConfig({
+                adapter,
+                targetBaseUrl,
+                projectRoot: normalizeOptionalString(input.projectRoot),
+                assetRoot: normalizeOptionalString(input.assetRoot),
+                nextDir: normalizeOptionalString(input.nextDir),
+                configPath: normalizeOptionalString(input.configPath),
+                profileId: normalizeOptionalString(input.profileId),
+                profileName: normalizeOptionalString(input.profileName),
+                enabled: normalizeOptionalBooleanInput(input.enabled, 'enabled'),
+                profileEnabled: normalizeOptionalBooleanInput(input.profileEnabled, 'profileEnabled'),
+                autoReload: normalizeOptionalBooleanInput(input.autoReload, 'autoReload'),
+                includeManifestFiles: normalizeOptionalBooleanInput(input.includeManifestFiles, 'includeManifestFiles'),
+                includeStaticFiles: normalizeOptionalBooleanInput(input.includeStaticFiles, 'includeStaticFiles'),
+                extensions: normalizeOptionalStringArrayInput(input.extensions, 'extensions'),
+                maxRules: normalizeOptionalNumberInput(input.maxRules, 'maxRules'),
+            });
+            const writeConfig = normalizeOptionalBooleanInput(input.writeConfig, 'writeConfig') ?? false;
+            const overwrite = normalizeOptionalBooleanInput(input.overwrite, 'overwrite') ?? false;
+            const write = {
+                written: false,
+                path: generated.suggestedConfigPath,
+            };
+            let nextActions = generated.nextActions;
+            if (writeConfig && generated.ruleCount === 0) {
+                write.failureCode = 'NO_RULES';
+                write.message = 'Generated profile has no rules; config was not written.';
+                nextActions = [{
+                        code: 'BUILD_APP',
+                        message: 'Build the app so local assets exist, then generate the profile again.',
+                    }];
+            }
+            else if (writeConfig && existsSync(generated.suggestedConfigPath) && !overwrite) {
+                write.failureCode = 'CONFIG_EXISTS';
+                write.message = 'Config file already exists; pass overwrite=true or choose another configPath.';
+                nextActions = [{
+                        code: 'OVERWRITE_OR_CHOOSE_CONFIG_PATH',
+                        message: 'Pass overwrite=true to replace the config file, or choose a different configPath.',
+                    }, ...generated.nextActions];
+            }
+            else if (writeConfig) {
+                mkdirSync(dirname(generated.suggestedConfigPath), { recursive: true });
+                writeFileSync(generated.suggestedConfigPath, generated.configJson, 'utf8');
+                write.written = true;
+                write.bytes = Buffer.byteLength(generated.configJson, 'utf8');
+                nextActions = generated.nextActions.filter((action) => action.code !== 'SAVE_LOCAL_CONFIG');
+            }
+            return {
+                ...createBaseResponse(),
+                limitsApplied: {
+                    maxResults: generated.ruleCount,
+                    truncated: generated.warnings.some((warning) => warning.startsWith('Rule generation was limited')),
+                },
+                adapter: generated.adapter,
+                mode: generated.mode,
+                projectRoot: generated.projectRoot,
+                assetRoot: generated.assetRoot,
+                nextDir: generated.nextDir,
+                targetBaseUrl: generated.targetBaseUrl,
+                suggestedConfigPath: generated.suggestedConfigPath,
+                ruleCount: generated.ruleCount,
+                manifestFiles: generated.manifestFiles,
+                staticFileCount: generated.staticFileCount,
+                missingManifestAssetCount: generated.missingManifestAssetCount,
+                warnings: generated.warnings,
+                nextActions,
+                write,
+                profile: generated.profile,
+                config: generated.config,
+                configJson: generated.configJson,
+            };
+        },
+        validate_override_profile: async (input) => {
+            const profile = resolveOverrideProfileRecord(input.profileId);
+            const issues = buildOverrideProfileIssues(profile);
+            return {
+                ...createBaseResponse(),
+                profileId: profile.profileId,
+                valid: !issues.some((issue) => issue.severity === 'error'),
+                issues,
+                nextActions: buildOverrideProfileNextActions(profile, issues),
+                profile,
+            };
+        },
+        preflight_overrides: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const preflight = buildOverridePreflight({
+                db,
+                sessionId,
+                profileId: input.profileId,
+                getSessionConnectionState,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                ...preflight,
+            };
+        },
+        list_observed_override_assets: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const assets = listObservedOverrideAssets(getDb(), {
+                sessionId,
+                limit: typeof input.limit === 'number' ? input.limit : undefined,
+                sinceTimestamp: typeof input.sinceTimestamp === 'number' ? input.sinceTimestamp : undefined,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: assets.length,
+                    truncated: false,
+                },
+                assets,
+            };
+        },
+        plan_override_response_patch: async (input) => {
+            const sessionId = getSessionId(input);
+            const plan = planOverrideResponsePatch(input);
+            const variantContext = buildOverrideVariantContext({
+                targetUrl: plan.targetUrl,
+                requestMethod: plan.requestMethod,
+                matchMode: plan.matchMode,
+                ruleType: plan.ruleType,
+                captureMode: input.captureMode,
+                source: input.source,
+                triggerReload: input.triggerReload,
+                requestHeaders: input.requestHeaders,
+            });
+            const auditPlan = persistResponsePlanAudit({
+                db: getDb(),
+                sessionId,
+                input,
+                plan,
+                variantContext,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: plan.rule ? 1 : 0,
+                    truncated: false,
+                },
+                variantContext,
+                audit: {
+                    persisted: auditPlan !== undefined,
+                    plans: auditPlan ? [auditPlan] : [],
+                },
+                ...plan,
+            };
+        },
+        map_next_override_assets: async (input) => {
+            const projectRoot = normalizeOptionalString(input.projectRoot);
+            if (!projectRoot) {
+                throw new Error('projectRoot is required');
+            }
+            const sessionId = getSessionId(input);
+            const observedAssets = Array.isArray(input.observedAssets)
+                ? input.observedAssets
+                : sessionId
+                    ? listObservedOverrideAssets(getDb(), { sessionId })
+                    : input.observedAssets;
+            const mapping = await mapNextOverrideAssetsWithDrift({
+                projectRoot,
+                nextDir: normalizeOptionalString(input.nextDir),
+                observedAssets,
+                sourcePaths: input.sourcePaths,
+                route: input.route,
+                maxResults: input.maxResults,
+                fetchProductionAssets: input.fetchProductionAssets,
+                productionFetchTimeoutMs: input.productionFetchTimeoutMs,
+                maxProductionAssetBytes: input.maxProductionAssetBytes,
+                maxDriftCandidates: input.maxDriftCandidates,
+                productionFetchConcurrency: input.productionFetchConcurrency,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: mapping.candidates.length,
+                    truncated: false,
+                },
+                observedFromPersisted: !Array.isArray(input.observedAssets) && sessionId
+                    ? { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 }
+                    : undefined,
+                ...mapping,
+            };
+        },
+        plan_next_source_override: async (input) => {
+            const projectRoot = normalizeOptionalString(input.projectRoot);
+            if (!projectRoot) {
+                throw new Error('projectRoot is required');
+            }
+            const sessionId = getSessionId(input);
+            const observedAssets = Array.isArray(input.observedAssets)
+                ? input.observedAssets
+                : sessionId
+                    ? listObservedOverrideAssets(getDb(), { sessionId })
+                    : input.observedAssets;
+            const plan = await planNextSourceOverride({
+                projectRoot,
+                nextDir: normalizeOptionalString(input.nextDir),
+                observedAssets,
+                sourceEdits: input.sourceEdits,
+                sourcePaths: input.sourcePaths,
+                route: input.route,
+                configPath: input.configPath,
+                writeConfig: input.writeConfig,
+                overwrite: input.overwrite,
+                enabled: input.enabled,
+                profileEnabled: input.profileEnabled,
+                autoReload: input.autoReload,
+                profileId: input.profileId,
+                profileName: input.profileName,
+                buildTimeoutMs: input.buildTimeoutMs,
+                maxRules: input.maxRules,
+                fetchProductionAssets: input.fetchProductionAssets,
+                productionFetchTimeoutMs: input.productionFetchTimeoutMs,
+                maxProductionAssetBytes: input.maxProductionAssetBytes,
+                maxDriftCandidates: input.maxDriftCandidates,
+                productionFetchConcurrency: input.productionFetchConcurrency,
+                overlayTtlMs: input.overlayTtlMs,
+            });
+            const auditPlans = persistNextSourcePlanAudits({
+                db: getDb(),
+                sessionId,
+                input,
+                plan,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: plan.rules.length,
+                    truncated: false,
+                },
+                observedFromPersisted: !Array.isArray(input.observedAssets) && sessionId
+                    ? { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 }
+                    : undefined,
+                audit: {
+                    persisted: auditPlans.length > 0,
+                    plans: auditPlans,
+                },
+                ...plan,
+            };
+        },
+        get_override_status: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            const profile = resolveOverrideProfileRecord(input.profileId);
+            const latestRun = sessionId ? listOverridePocRuns(db, sessionId, 1, 0).runs[0] ?? null : null;
+            const recentRequests = sessionId
+                ? listOverridePocRequests(db, sessionId, 5, 0, latestRun?.runId).requests
+                : [];
+            const recentPlans = sessionId
+                ? listOverridePlanAudits(db, { sessionId, limit: 5, offset: 0 }).plans
+                : [];
+            return {
+                ...createBaseResponse(sessionId),
+                profile,
+                latestRun,
+                recentRequests,
+                recentPlans,
+                preflight: sessionId
+                    ? buildOverridePreflight({
+                        db,
+                        sessionId,
+                        profileId: input.profileId,
+                        getSessionConnectionState,
+                    })
+                    : null,
+                diagnosis: sessionId ? diagnoseOverridePoc(db, sessionId, latestRun?.runId) : null,
+                nextActions: latestRun?.lastErrorCode
+                    ? [{ code: 'DIAGNOSE_OVERRIDES', message: 'Run diagnose_overrides for the latest failed override run.' }]
+                    : latestRun
+                        ? [{ code: 'GET_OVERRIDE_REQUEST_LOG', message: 'Inspect get_override_request_log for matched and fulfilled requests.' }]
+                        : [{ code: 'ENABLE_OVERRIDES', message: 'Enable overrides on a connected session after profile validation succeeds.' }],
+            };
+        },
+        get_override_request_log: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const limit = resolveLimit(input.limit, DEFAULT_EVENT_LIMIT);
+            const offset = resolveOffset(input.offset);
+            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
+            const runId = typeof input.runId === 'string' && input.runId.trim().length > 0
+                ? input.runId.trim()
+                : undefined;
+            const result = listOverridePocRequests(db, sessionId, limit, offset, runId);
+            const bytePage = applyByteBudget(result.requests, maxResponseBytes);
+            const truncated = result.hasMore || bytePage.truncatedByBytes;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: limit,
+                    truncated,
+                },
+                runId: runId ?? null,
+                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+                requests: bytePage.items,
+                nextActions: bytePage.items.length === 0
+                    ? [{ code: 'RELOAD_TAB', message: 'Reload the selected tab after enabling overrides so matching requests are observed.' }]
+                    : [{ code: 'DIAGNOSE_OVERRIDES', message: 'Run diagnose_overrides if any matched request failed or did not fulfill.' }],
+            };
+        },
+        get_override_plan_log: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const limit = resolveLimit(input.limit, DEFAULT_EVENT_LIMIT);
+            const offset = resolveOffset(input.offset);
+            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
+            const planId = typeof input.planId === 'string' && input.planId.trim().length > 0
+                ? input.planId.trim()
+                : undefined;
+            const result = listOverridePlanAudits(db, { sessionId, limit, offset, planId });
+            const bytePage = applyByteBudget(result.plans, maxResponseBytes);
+            const truncated = result.hasMore || bytePage.truncatedByBytes;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: limit,
+                    truncated,
+                },
+                planId: planId ?? null,
+                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+                plans: bytePage.items,
+                nextActions: bytePage.items.length === 0
+                    ? [{ code: 'PLAN_OVERRIDE', message: 'Run plan_override_response_patch or plan_next_source_override with sessionId to persist generated rule metadata.' }]
+                    : [{ code: 'REVIEW_ROLLBACK', message: 'Review rollback metadata before enabling or deleting generated override files.' }],
+            };
+        },
+        diagnose_overrides: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const runId = typeof input.runId === 'string' && input.runId.trim().length > 0
+                ? input.runId.trim()
+                : undefined;
+            const diagnosis = diagnoseOverridePoc(db, sessionId, runId);
+            const firstIssue = diagnosis.issues[0];
+            return {
+                ...createBaseResponse(sessionId),
+                diagnosis,
+                nextActions: firstIssue?.suggestedActions[0]
+                    ? [{ code: firstIssue.code, message: firstIssue.suggestedActions[0] }]
+                    : [{ code: 'NO_DIAGNOSIS_ISSUES', message: 'No diagnosis issues were found for the selected override run.' }],
+            };
+        },
+        get_recent_events: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            const origin = normalizeRequestedOrigin(input.url);
+            ensureSessionOrOriginFilter(sessionId, origin);
+            const limit = resolveLimit(input.limit, DEFAULT_EVENT_LIMIT);
+            const offset = resolveOffset(input.offset);
+            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
+            const responseProfile = resolveResponseProfile(input.responseProfile);
+            const includePayload = responseProfile === 'compact' && input.includePayload === true;
+            const requestedTypes = parseRequestedTypes(input.types ?? input.eventTypes);
+            const params = [];
+            const where = [];
+            if (sessionId) {
+                where.push('session_id = ?');
+                params.push(sessionId);
+            }
+            appendEventOriginFilter(where, params, origin);
+            if (requestedTypes.length > 0) {
+                const placeholders = requestedTypes.map(() => '?').join(', ');
+                where.push(`type IN (${placeholders})`);
+                params.push(...requestedTypes);
+            }
+            const rows = db
+                .prepare(`
+        SELECT event_id, session_id, ts, type, payload_json, tab_id, origin
+        FROM events
+        WHERE ${where.join(' AND ')}
+        ORDER BY ts DESC
         LIMIT ? OFFSET ?
       `)
                 .all(...params, limit + 1, offset);
@@ -2195,163 +5058,761 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
-                    maxResults: limit,
-                    truncated,
+                    maxResults: limit,
+                    truncated,
+                },
+                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+                snapshots: bytePage.items,
+            };
+        },
+        get_snapshot_for_event: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const eventId = typeof input.eventId === 'string' ? input.eventId : '';
+            if (!eventId) {
+                throw new Error('eventId is required');
+            }
+            const maxDeltaMs = resolveDurationMs(input.maxDeltaMs, 10_000, 60_000);
+            const event = db
+                .prepare('SELECT event_id, ts, type FROM events WHERE session_id = ? AND event_id = ? LIMIT 1')
+                .get(sessionId, eventId);
+            if (!event) {
+                throw new Error(`Event not found: ${eventId}`);
+            }
+            const byTriggerLink = db
+                .prepare(`SELECT
+            snapshot_id, session_id, trigger_event_id, ts, trigger, selector, url, mode, style_mode,
+            dom_json, styles_json, png_path, png_mime, png_bytes,
+            dom_truncated, styles_truncated, png_truncated, created_at
+           FROM snapshots
+           WHERE session_id = ? AND trigger_event_id = ?
+           ORDER BY ts ASC
+           LIMIT 1`)
+                .get(sessionId, eventId);
+            if (byTriggerLink) {
+                return {
+                    ...createBaseResponse(sessionId),
+                    limitsApplied: {
+                        maxResults: 1,
+                        truncated: false,
+                    },
+                    event: {
+                        eventId: event.event_id,
+                        timestamp: event.ts,
+                        type: event.type,
+                    },
+                    matchReason: 'trigger_event_id',
+                    snapshot: mapSnapshotMetadata(byTriggerLink),
+                };
+            }
+            const byTimestamp = db
+                .prepare(`SELECT
+            snapshot_id, session_id, trigger_event_id, ts, trigger, selector, url, mode, style_mode,
+            dom_json, styles_json, png_path, png_mime, png_bytes,
+            dom_truncated, styles_truncated, png_truncated, created_at
+           FROM snapshots
+           WHERE session_id = ? AND ts BETWEEN ? AND ?
+           ORDER BY ABS(ts - ?) ASC, ts ASC
+           LIMIT 1`)
+                .get(sessionId, event.ts, event.ts + maxDeltaMs, event.ts);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: false,
+                },
+                event: {
+                    eventId: event.event_id,
+                    timestamp: event.ts,
+                    type: event.type,
+                },
+                matchReason: byTimestamp ? 'nearest_timestamp' : 'none',
+                snapshot: byTimestamp ? mapSnapshotMetadata(byTimestamp) : null,
+            };
+        },
+        get_snapshot_asset: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const snapshotId = typeof input.snapshotId === 'string' ? input.snapshotId : '';
+            if (!snapshotId) {
+                throw new Error('snapshotId is required');
+            }
+            const assetType = input.asset === 'png' ? 'png' : 'png';
+            const encoding = input.encoding === 'raw' ? 'raw' : 'base64';
+            const offset = resolveOffset(input.offset);
+            const maxBytes = resolveChunkBytes(input.maxBytes, DEFAULT_SNAPSHOT_ASSET_CHUNK_BYTES);
+            const snapshot = db
+                .prepare(`SELECT snapshot_id, session_id, png_path, png_mime, png_bytes
+           FROM snapshots
+           WHERE session_id = ? AND snapshot_id = ?
+           LIMIT 1`)
+                .get(sessionId, snapshotId);
+            if (!snapshot) {
+                throw new Error(`Snapshot not found: ${snapshotId}`);
+            }
+            if (assetType !== 'png' || !snapshot.png_path) {
+                throw new Error('Requested snapshot asset is not available.');
+            }
+            const dbPath = getMainDbPath(db);
+            const absolutePath = resolveSnapshotAbsolutePath(dbPath, snapshot.png_path);
+            if (!existsSync(absolutePath)) {
+                throw new Error(`Snapshot asset is missing on disk: ${snapshot.png_path}`);
+            }
+            const fullBuffer = readFileSync(absolutePath);
+            if (offset >= fullBuffer.byteLength) {
+                return {
+                    ...createBaseResponse(sessionId),
+                    limitsApplied: {
+                        maxResults: maxBytes,
+                        truncated: false,
+                    },
+                    snapshotId,
+                    asset: assetType,
+                    assetUri: `snapshot://${encodeURIComponent(sessionId)}/${encodeURIComponent(snapshotId)}/${assetType}`,
+                    mime: snapshot.png_mime ?? 'image/png',
+                    totalBytes: fullBuffer.byteLength,
+                    offset,
+                    returnedBytes: 0,
+                    hasMore: false,
+                    nextOffset: null,
+                    encoding,
+                    chunk: encoding === 'raw' ? [] : undefined,
+                    chunkBase64: encoding === 'base64' ? '' : undefined,
+                };
+            }
+            const chunkBuffer = fullBuffer.subarray(offset, Math.min(offset + maxBytes, fullBuffer.byteLength));
+            const returnedBytes = chunkBuffer.byteLength;
+            const nextOffset = offset + returnedBytes;
+            const hasMore = nextOffset < fullBuffer.byteLength;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: maxBytes,
+                    truncated: hasMore,
+                },
+                snapshotId,
+                asset: assetType,
+                assetUri: `snapshot://${encodeURIComponent(sessionId)}/${encodeURIComponent(snapshotId)}/${assetType}`,
+                mime: snapshot.png_mime ?? 'image/png',
+                totalBytes: fullBuffer.byteLength,
+                offset,
+                returnedBytes,
+                hasMore,
+                nextOffset: hasMore ? nextOffset : null,
+                encoding,
+                chunk: encoding === 'raw' ? Array.from(chunkBuffer.values()) : undefined,
+                chunkBase64: encoding === 'base64' ? chunkBuffer.toString('base64') : undefined,
+            };
+        },
+        list_automation_runs: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const status = normalizeOptionalString(input.status);
+            const action = normalizeOptionalString(input.action);
+            const traceId = normalizeOptionalString(input.traceId);
+            const limit = resolveLimit(input.limit, DEFAULT_LIST_LIMIT);
+            const offset = resolveOffset(input.offset);
+            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
+            const where = ['r.session_id = ?'];
+            const params = [sessionId];
+            if (status) {
+                where.push('r.status = ?');
+                params.push(status);
+            }
+            if (action) {
+                where.push('r.action = ?');
+                params.push(action);
+            }
+            if (traceId) {
+                where.push('r.trace_id = ?');
+                params.push(traceId);
+            }
+            const rows = db.prepare(`SELECT
+           r.run_id,
+           r.session_id,
+           r.trace_id,
+           r.action,
+           r.tab_id,
+           r.selector,
+           r.status,
+           r.started_at,
+           r.completed_at,
+           r.stop_reason,
+           r.target_summary_json,
+           r.failure_json,
+           r.redaction_json,
+           r.created_at,
+           r.updated_at,
+           COALESCE(step_stats.step_count, 0) AS step_count,
+           step_stats.last_step_at
+         FROM automation_runs r
+         LEFT JOIN (
+           SELECT
+             run_id,
+             COUNT(*) AS step_count,
+             MAX(COALESCE(finished_at, started_at, created_at)) AS last_step_at
+           FROM automation_steps
+           GROUP BY run_id
+         ) step_stats ON step_stats.run_id = r.run_id
+         WHERE ${where.join(' AND ')}
+         ORDER BY r.started_at DESC, r.run_id DESC
+         LIMIT ? OFFSET ?`).all(...params, limit + 1, offset);
+            const truncatedByLimit = rows.length > limit;
+            const runs = rows.slice(0, limit).map((row) => mapAutomationRunRecord(row));
+            const bytePage = applyByteBudget(runs, maxResponseBytes);
+            const truncated = truncatedByLimit || bytePage.truncatedByBytes;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: limit,
+                    truncated,
+                },
+                filtersApplied: {
+                    sessionId,
+                    status,
+                    action,
+                    traceId,
+                },
+                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+                runs: bytePage.items,
+            };
+        },
+        get_automation_run: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const runId = normalizeOptionalString(input.runId);
+            if (!runId) {
+                throw new Error('runId is required');
+            }
+            const stepLimit = resolveLimit(input.stepLimit, DEFAULT_LIST_LIMIT);
+            const stepOffset = resolveOffset(input.stepOffset);
+            const maxResponseBytes = resolveMaxResponseBytes(input.maxResponseBytes);
+            const run = db.prepare(`SELECT
+           r.run_id,
+           r.session_id,
+           r.trace_id,
+           r.action,
+           r.tab_id,
+           r.selector,
+           r.status,
+           r.started_at,
+           r.completed_at,
+           r.stop_reason,
+           r.target_summary_json,
+           r.failure_json,
+           r.redaction_json,
+           r.created_at,
+           r.updated_at,
+           COALESCE(step_stats.step_count, 0) AS step_count,
+           step_stats.last_step_at
+         FROM automation_runs r
+         LEFT JOIN (
+           SELECT
+             run_id,
+             COUNT(*) AS step_count,
+             MAX(COALESCE(finished_at, started_at, created_at)) AS last_step_at
+           FROM automation_steps
+           GROUP BY run_id
+         ) step_stats ON step_stats.run_id = r.run_id
+         WHERE r.session_id = ? AND r.run_id = ?
+         LIMIT 1`).get(sessionId, runId);
+            if (!run) {
+                throw new Error(`Automation run not found: ${runId}`);
+            }
+            const stepRows = db.prepare(`SELECT
+           step_id,
+           run_id,
+           session_id,
+           step_order,
+           trace_id,
+           action,
+           selector,
+           status,
+           started_at,
+           finished_at,
+           duration_ms,
+           tab_id,
+           target_summary_json,
+           redaction_json,
+           failure_json,
+           input_metadata_json,
+           event_type,
+           event_id,
+           created_at,
+           updated_at
+         FROM automation_steps
+         WHERE session_id = ? AND run_id = ?
+         ORDER BY step_order ASC, created_at ASC
+         LIMIT ? OFFSET ?`).all(sessionId, runId, stepLimit + 1, stepOffset);
+            const truncatedByLimit = stepRows.length > stepLimit;
+            const steps = stepRows.slice(0, stepLimit).map((row) => mapAutomationStepRecord(row));
+            const bytePage = applyByteBudget(steps, maxResponseBytes);
+            const truncated = truncatedByLimit || bytePage.truncatedByBytes;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: stepLimit,
+                    truncated,
+                },
+                run: mapAutomationRunRecord(run),
+                steps: bytePage.items,
+                pagination: buildOffsetPagination(stepOffset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+            };
+        },
+    };
+}
+export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionState) {
+    const capturePageState = async (sessionId, input) => {
+        const maxItems = resolveStructuredMaxItems(input.maxItems, 40);
+        const maxTextLength = resolveStructuredTextLength(input.maxTextLength, 80);
+        const includeButtons = input.includeButtons !== false;
+        const includeInputs = input.includeInputs !== false;
+        const includeModals = input.includeModals !== false;
+        const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_PAGE_STATE', {
+            maxItems,
+            maxTextLength,
+            includeButtons,
+            includeInputs,
+            includeModals,
+        }, 4_000);
+        return {
+            limitsApplied: {
+                maxResults: maxItems,
+                truncated: capture.truncated ?? false,
+            },
+            payload: ensureCaptureSuccess(capture, sessionId),
+        };
+    };
+    return {
+        observe_override_assets: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const tabId = resolveOptionalTabId(input.tabId);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: input.includePerformance !== false }, 5_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
+            const assetCount = Array.isArray(payload.assets) ? payload.assets.length : 0;
+            const persisted = getDb
+                ? persistObservedOverrideAssets(getDb(), { ...payload, sessionId, tabId: payload.tabId ?? tabId })
+                : undefined;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: assetCount,
+                    truncated: capture.truncated ?? false,
+                },
+                persisted,
+                ...payload,
+                nextActions: assetCount > 0
+                    ? [{ code: 'MAP_NEXT_ASSETS', message: 'Run map_next_override_assets with projectRoot and sourcePaths to score override candidates.' }]
+                    : [{ code: 'LOAD_ROUTE', message: 'Load or interact with the target route so document, asset, and fetch resources are requested, then observe again.' }],
+            };
+        },
+        capture_override_response_body: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const targetUrl = normalizeOptionalString(input.targetUrl) ?? normalizeOptionalString(input.targetAssetUrl);
+            if (!targetUrl) {
+                throw new Error('targetUrl is required');
+            }
+            assertOverrideResponseRequestCaptureSafe({
+                requestMethod: input.requestMethod,
+                requestHeaders: input.requestHeaders,
+                subject: 'Response body capture request',
+            });
+            const tabId = resolveOptionalTabId(input.tabId);
+            const timeoutMs = resolveTimeoutMs(input.timeoutMs, 10_000, 60_000);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_RESPONSE_BODY', {
+                targetUrl,
+                tabId,
+                captureMode: normalizeOptionalString(input.captureMode),
+                triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
+                matchMode: normalizeOptionalString(input.matchMode),
+                requestMethod: input.requestMethod,
+                requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
+                timeoutMs,
+                maxBodyBytes: input.maxBodyBytes,
+                includeBody: input.includeBody === true,
+            }, timeoutMs + 2_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: capture.truncated ?? payload.truncated === true,
+                },
+                ...payload,
+                nextActions: payload.bodyCaptured === true
+                    ? [{ code: 'PLAN_RESPONSE_PATCH', message: 'Run plan_override_response_patch with textPatches or jsonPatches to generate an exact response override.' }]
+                    : [{ code: 'UNSUPPORTED_RESPONSE_BODY', message: 'Only bounded text-like response bodies can be patched safely.' }],
+            };
+        },
+        plan_override_response_patch: async (input) => {
+            const sessionId = getSessionId(input);
+            let plannerInput = input;
+            let capturedFromLiveSession;
+            const hasProvidedBody = typeof input.responseBodyText === 'string'
+                || typeof input.bodyText === 'string'
+                || typeof input.responseBodyBase64 === 'string'
+                || typeof input.bodyBase64 === 'string';
+            if (!hasProvidedBody && sessionId) {
+                const targetUrl = normalizeOptionalString(input.targetUrl) ?? normalizeOptionalString(input.targetAssetUrl);
+                if (!targetUrl) {
+                    throw new Error('targetUrl is required');
+                }
+                const tabId = resolveOptionalTabId(input.tabId);
+                const timeoutMs = resolveTimeoutMs(input.timeoutMs, 10_000, 60_000);
+                const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_RESPONSE_BODY', {
+                    targetUrl,
+                    tabId,
+                    captureMode: normalizeOptionalString(input.captureMode),
+                    triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
+                    matchMode: normalizeOptionalString(input.matchMode),
+                    requestMethod: input.requestMethod,
+                    requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
+                    timeoutMs,
+                    maxBodyBytes: input.maxBodyBytes,
+                    includeBody: true,
+                }, timeoutMs + 2_000);
+                const payload = ensureCaptureSuccess(capture, sessionId);
+                if (payload.truncated === true) {
+                    throw new Error('Captured response body was truncated; increase maxBodyBytes before planning a patch.');
+                }
+                if (typeof payload.bodyText !== 'string') {
+                    throw new Error('Captured response did not include a text body that can be patched.');
+                }
+                plannerInput = {
+                    ...input,
+                    responseBodyText: payload.bodyText,
+                    contentType: input.contentType ?? payload.contentType,
+                    ruleType: input.ruleType ?? payload.ruleType,
+                    requestMethod: input.requestMethod ?? payload.requestMethod,
+                    captureMode: input.captureMode ?? payload.captureMode,
+                    source: payload.source,
+                    requestHeaders: payload.requestHeaders,
+                };
+                const variantContext = buildOverrideVariantContext({
+                    targetUrl: payload.targetUrl,
+                    requestMethod: input.requestMethod ?? payload.requestMethod,
+                    matchMode: payload.matchMode,
+                    ruleType: input.ruleType ?? payload.ruleType,
+                    captureMode: payload.captureMode,
+                    source: payload.source,
+                    triggerReload: payload.triggerReload,
+                    requestHeaders: payload.requestHeaders,
+                });
+                capturedFromLiveSession = {
+                    sessionId,
+                    targetUrl: payload.targetUrl,
+                    requestMethod: input.requestMethod ?? payload.requestMethod,
+                    statusCode: payload.statusCode,
+                    contentType: payload.contentType,
+                    bodyBytes: payload.bodyBytes,
+                    capturedBytes: payload.capturedBytes,
+                    truncated: payload.truncated === true,
+                    ruleType: payload.ruleType,
+                    matchMode: payload.matchMode,
+                    captureMode: payload.captureMode,
+                    source: payload.source,
+                    tabId: payload.tabId,
+                    triggerReload: payload.triggerReload,
+                    requestHeaders: payload.requestHeaders,
+                    variantContext,
+                };
+            }
+            const plan = planOverrideResponsePatch(plannerInput);
+            const variantContext = buildOverrideVariantContext({
+                targetUrl: plan.targetUrl,
+                requestMethod: plan.requestMethod,
+                matchMode: plan.matchMode,
+                ruleType: plan.ruleType,
+                captureMode: plannerInput.captureMode,
+                source: plannerInput.source,
+                triggerReload: plannerInput.triggerReload,
+                requestHeaders: plannerInput.requestHeaders,
+            });
+            const auditPlan = getDb
+                ? persistResponsePlanAudit({
+                    db: getDb(),
+                    sessionId,
+                    input,
+                    plan,
+                    capturedFromLiveSession,
+                    variantContext,
+                })
+                : undefined;
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: plan.rule ? 1 : 0,
+                    truncated: false,
+                },
+                capturedFromLiveSession,
+                variantContext,
+                audit: {
+                    persisted: auditPlan !== undefined,
+                    plans: auditPlan ? [auditPlan] : [],
+                },
+                ...plan,
+            };
+        },
+        map_next_override_assets: async (input) => {
+            const projectRoot = normalizeOptionalString(input.projectRoot);
+            if (!projectRoot) {
+                throw new Error('projectRoot is required');
+            }
+            const sessionId = getSessionId(input);
+            let observedAssets = input.observedAssets;
+            let observedFromLiveTab;
+            let observedFromPersisted;
+            if (!Array.isArray(observedAssets) && sessionId) {
+                const tabId = resolveOptionalTabId(input.tabId);
+                try {
+                    const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: true }, 5_000);
+                    observedFromLiveTab = ensureCaptureSuccess(capture, sessionId);
+                    observedAssets = observedFromLiveTab.assets;
+                    if (getDb) {
+                        persistObservedOverrideAssets(getDb(), { ...observedFromLiveTab, sessionId, tabId: observedFromLiveTab.tabId ?? tabId });
+                    }
+                }
+                catch (error) {
+                    if (!getDb || !isLiveSessionDisconnectedError(error)) {
+                        throw error;
+                    }
+                    observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
+                    observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
+                }
+            }
+            const mapping = await mapNextOverrideAssetsWithDrift({
+                projectRoot,
+                nextDir: normalizeOptionalString(input.nextDir),
+                observedAssets,
+                sourcePaths: input.sourcePaths,
+                route: input.route,
+                maxResults: input.maxResults,
+                fetchProductionAssets: input.fetchProductionAssets,
+                productionFetchTimeoutMs: input.productionFetchTimeoutMs,
+                maxProductionAssetBytes: input.maxProductionAssetBytes,
+                maxDriftCandidates: input.maxDriftCandidates,
+                productionFetchConcurrency: input.productionFetchConcurrency,
+            });
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: mapping.candidates.length,
+                    truncated: false,
+                },
+                observedFromLiveTab: observedFromLiveTab
+                    ? {
+                        pageUrl: observedFromLiveTab.pageUrl,
+                        tabId: observedFromLiveTab.tabId,
+                        assetCount: Array.isArray(observedFromLiveTab.assets) ? observedFromLiveTab.assets.length : 0,
+                    }
+                    : undefined,
+                observedFromPersisted,
+                ...mapping,
+            };
+        },
+        plan_next_source_override: async (input) => {
+            const projectRoot = normalizeOptionalString(input.projectRoot);
+            if (!projectRoot) {
+                throw new Error('projectRoot is required');
+            }
+            const sessionId = getSessionId(input);
+            let observedAssets = input.observedAssets;
+            let observedFromLiveTab;
+            let observedFromPersisted;
+            if (!Array.isArray(observedAssets) && sessionId) {
+                const tabId = resolveOptionalTabId(input.tabId);
+                try {
+                    const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: true }, 5_000);
+                    observedFromLiveTab = ensureCaptureSuccess(capture, sessionId);
+                    observedAssets = observedFromLiveTab.assets;
+                    if (getDb) {
+                        persistObservedOverrideAssets(getDb(), { ...observedFromLiveTab, sessionId, tabId: observedFromLiveTab.tabId ?? tabId });
+                    }
+                }
+                catch (error) {
+                    if (!getDb || !isLiveSessionDisconnectedError(error)) {
+                        throw error;
+                    }
+                    observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
+                    observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
+                }
+            }
+            const plan = await planNextSourceOverride({
+                projectRoot,
+                nextDir: normalizeOptionalString(input.nextDir),
+                observedAssets,
+                sourceEdits: input.sourceEdits,
+                sourcePaths: input.sourcePaths,
+                route: input.route,
+                configPath: input.configPath,
+                writeConfig: input.writeConfig,
+                overwrite: input.overwrite,
+                enabled: input.enabled,
+                profileEnabled: input.profileEnabled,
+                autoReload: input.autoReload,
+                profileId: input.profileId,
+                profileName: input.profileName,
+                buildTimeoutMs: input.buildTimeoutMs,
+                maxRules: input.maxRules,
+                fetchProductionAssets: input.fetchProductionAssets,
+                productionFetchTimeoutMs: input.productionFetchTimeoutMs,
+                maxProductionAssetBytes: input.maxProductionAssetBytes,
+                maxDriftCandidates: input.maxDriftCandidates,
+                productionFetchConcurrency: input.productionFetchConcurrency,
+                overlayTtlMs: input.overlayTtlMs,
+            });
+            const auditPlans = getDb
+                ? persistNextSourcePlanAudits({
+                    db: getDb(),
+                    sessionId,
+                    input,
+                    plan,
+                })
+                : [];
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: plan.rules.length,
+                    truncated: false,
+                },
+                observedFromLiveTab: observedFromLiveTab
+                    ? {
+                        pageUrl: observedFromLiveTab.pageUrl,
+                        tabId: observedFromLiveTab.tabId,
+                        assetCount: Array.isArray(observedFromLiveTab.assets) ? observedFromLiveTab.assets.length : 0,
+                    }
+                    : undefined,
+                observedFromPersisted,
+                audit: {
+                    persisted: auditPlans.length > 0,
+                    plans: auditPlans,
+                },
+                ...plan,
+            };
+        },
+        get_override_status: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_GET_STATUS', {}, 3_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: capture.truncated ?? false,
                 },
-                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
-                responseBytes: bytePage.responseBytes,
-                snapshots: bytePage.items,
+                preflight: getDb
+                    ? buildOverridePreflight({
+                        db: getDb(),
+                        sessionId,
+                        profileId: input.profileId,
+                        getSessionConnectionState,
+                    })
+                    : null,
+                ...payload,
+                nextActions: payload.lastErrorCode
+                    ? [{ code: 'DIAGNOSE_OVERRIDES', message: 'Run diagnose_overrides for the latest override failure.' }]
+                    : payload.active === true
+                        ? [{ code: 'GET_OVERRIDE_REQUEST_LOG', message: 'Inspect get_override_request_log after the target tab loads matching assets.' }]
+                        : [{ code: 'ENABLE_OVERRIDES', message: 'Enable overrides after validating the selected profile.' }],
             };
         },
-        get_snapshot_for_event: async (input) => {
-            const db = getDb();
+        preflight_overrides: async (input) => {
             const sessionId = getSessionId(input);
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const eventId = typeof input.eventId === 'string' ? input.eventId : '';
-            if (!eventId) {
-                throw new Error('eventId is required');
+            if (!getDb) {
+                throw new Error('preflight_overrides requires database-backed override state');
             }
-            const maxDeltaMs = resolveDurationMs(input.maxDeltaMs, 10_000, 60_000);
-            const event = db
-                .prepare('SELECT event_id, ts, type FROM events WHERE session_id = ? AND event_id = ? LIMIT 1')
-                .get(sessionId, eventId);
-            if (!event) {
-                throw new Error(`Event not found: ${eventId}`);
+            return {
+                ...createBaseResponse(sessionId),
+                ...buildOverridePreflight({
+                    db: getDb(),
+                    sessionId,
+                    profileId: input.profileId,
+                    getSessionConnectionState,
+                }),
+            };
+        },
+        enable_overrides: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
             }
-            const byTriggerLink = db
-                .prepare(`SELECT
-            snapshot_id, session_id, trigger_event_id, ts, trigger, selector, url, mode, style_mode,
-            dom_json, styles_json, png_path, png_mime, png_bytes,
-            dom_truncated, styles_truncated, png_truncated, created_at
-           FROM snapshots
-           WHERE session_id = ? AND trigger_event_id = ?
-           ORDER BY ts ASC
-           LIMIT 1`)
-                .get(sessionId, eventId);
-            if (byTriggerLink) {
-                return {
-                    ...createBaseResponse(sessionId),
-                    limitsApplied: {
-                        maxResults: 1,
-                        truncated: false,
-                    },
-                    event: {
-                        eventId: event.event_id,
-                        timestamp: event.ts,
-                        type: event.type,
-                    },
-                    matchReason: 'trigger_event_id',
-                    snapshot: mapSnapshotMetadata(byTriggerLink),
-                };
+            const preflight = getDb
+                ? buildOverridePreflight({
+                    db: getDb(),
+                    sessionId,
+                    profileId: input.profileId,
+                    getSessionConnectionState,
+                })
+                : null;
+            if (preflight && preflight.ready !== true) {
+                const blockingCodes = Array.isArray(preflight.issues)
+                    ? preflight.issues
+                        .filter((issue) => isRecord(issue) && issue.severity === 'error')
+                        .map((issue) => String(issue.code ?? 'UNKNOWN'))
+                    : [];
+                const profile = isRecord(preflight.profile) ? preflight.profile : {};
+                if (!canBypassPreflightForExperimentalRsc(profile, blockingCodes)) {
+                    throw new Error(`Override preflight failed: ${blockingCodes.join(', ') || 'UNKNOWN'}`);
+                }
             }
-            const byTimestamp = db
-                .prepare(`SELECT
-            snapshot_id, session_id, trigger_event_id, ts, trigger, selector, url, mode, style_mode,
-            dom_json, styles_json, png_path, png_mime, png_bytes,
-            dom_truncated, styles_truncated, png_truncated, created_at
-           FROM snapshots
-           WHERE session_id = ? AND ts BETWEEN ? AND ?
-           ORDER BY ABS(ts - ?) ASC, ts ASC
-           LIMIT 1`)
-                .get(sessionId, event.ts, event.ts + maxDeltaMs, event.ts);
+            const tabId = resolveOptionalTabId(input.tabId);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_ENABLE', { tabId }, 8_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: 1,
-                    truncated: false,
-                },
-                event: {
-                    eventId: event.event_id,
-                    timestamp: event.ts,
-                    type: event.type,
+                    truncated: capture.truncated ?? false,
                 },
-                matchReason: byTimestamp ? 'nearest_timestamp' : 'none',
-                snapshot: byTimestamp ? mapSnapshotMetadata(byTimestamp) : null,
+                preflight,
+                ...payload,
+                nextActions: [{ code: 'RELOAD_OR_INTERACT', message: 'Reload or interact with the tab so configured asset requests occur under the active override.' }],
             };
         },
-        get_snapshot_asset: async (input) => {
-            const db = getDb();
+        disable_overrides: async (input) => {
             const sessionId = getSessionId(input);
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const snapshotId = typeof input.snapshotId === 'string' ? input.snapshotId : '';
-            if (!snapshotId) {
-                throw new Error('snapshotId is required');
-            }
-            const assetType = input.asset === 'png' ? 'png' : 'png';
-            const encoding = input.encoding === 'raw' ? 'raw' : 'base64';
-            const offset = resolveOffset(input.offset);
-            const maxBytes = resolveChunkBytes(input.maxBytes, DEFAULT_SNAPSHOT_ASSET_CHUNK_BYTES);
-            const snapshot = db
-                .prepare(`SELECT snapshot_id, session_id, png_path, png_mime, png_bytes
-           FROM snapshots
-           WHERE session_id = ? AND snapshot_id = ?
-           LIMIT 1`)
-                .get(sessionId, snapshotId);
-            if (!snapshot) {
-                throw new Error(`Snapshot not found: ${snapshotId}`);
-            }
-            if (assetType !== 'png' || !snapshot.png_path) {
-                throw new Error('Requested snapshot asset is not available.');
-            }
-            const dbPath = getMainDbPath(db);
-            const absolutePath = resolveSnapshotAbsolutePath(dbPath, snapshot.png_path);
-            if (!existsSync(absolutePath)) {
-                throw new Error(`Snapshot asset is missing on disk: ${snapshot.png_path}`);
-            }
-            const fullBuffer = readFileSync(absolutePath);
-            if (offset >= fullBuffer.byteLength) {
-                return {
-                    ...createBaseResponse(sessionId),
-                    limitsApplied: {
-                        maxResults: maxBytes,
-                        truncated: false,
-                    },
-                    snapshotId,
-                    asset: assetType,
-                    assetUri: `snapshot://${encodeURIComponent(sessionId)}/${encodeURIComponent(snapshotId)}/${assetType}`,
-                    mime: snapshot.png_mime ?? 'image/png',
-                    totalBytes: fullBuffer.byteLength,
-                    offset,
-                    returnedBytes: 0,
-                    hasMore: false,
-                    nextOffset: null,
-                    encoding,
-                    chunk: encoding === 'raw' ? [] : undefined,
-                    chunkBase64: encoding === 'base64' ? '' : undefined,
-                };
-            }
-            const chunkBuffer = fullBuffer.subarray(offset, Math.min(offset + maxBytes, fullBuffer.byteLength));
-            const returnedBytes = chunkBuffer.byteLength;
-            const nextOffset = offset + returnedBytes;
-            const hasMore = nextOffset < fullBuffer.byteLength;
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_DISABLE', {}, 5_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
-                    maxResults: maxBytes,
-                    truncated: hasMore,
+                    maxResults: 1,
+                    truncated: capture.truncated ?? false,
                 },
-                snapshotId,
-                asset: assetType,
-                assetUri: `snapshot://${encodeURIComponent(sessionId)}/${encodeURIComponent(snapshotId)}/${assetType}`,
-                mime: snapshot.png_mime ?? 'image/png',
-                totalBytes: fullBuffer.byteLength,
-                offset,
-                returnedBytes,
-                hasMore,
-                nextOffset: hasMore ? nextOffset : null,
-                encoding,
-                chunk: encoding === 'raw' ? Array.from(chunkBuffer.values()) : undefined,
-                chunkBase64: encoding === 'base64' ? chunkBuffer.toString('base64') : undefined,
+                ...payload,
+                nextActions: [{ code: 'VERIFY_DISABLED', message: 'Run get_override_status if you need to confirm the debugger override is inactive.' }],
             };
         },
-    };
-}
-export function createV2ToolHandlers(captureClient) {
-    return {
         get_dom_subtree: async (input) => {
             const sessionId = getSessionId(input);
             if (!sessionId) {
@@ -2445,6 +5906,345 @@ export function createV2ToolHandlers(captureClient) {
                 ...ensureCaptureSuccess(capture, sessionId),
             };
         },
+        get_page_state: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const capture = await capturePageState(sessionId, input);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: capture.limitsApplied,
+                ...capture.payload,
+            };
+        },
+        get_interactive_elements: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const kinds = resolveInteractiveKinds(input.kinds);
+            const normalizedInput = {
+                ...input,
+                includeButtons: kinds.includes('buttons'),
+                includeInputs: kinds.includes('inputs'),
+                includeModals: kinds.includes('modals'),
+            };
+            const capture = await capturePageState(sessionId, normalizedInput);
+            const refs = collectInteractiveElementRefs(capture.payload, kinds, capture.limitsApplied.maxResults);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: capture.limitsApplied.maxResults,
+                    truncated: capture.limitsApplied.truncated || refs.length >= capture.limitsApplied.maxResults,
+                },
+                kinds,
+                refs,
+                page: {
+                    url: capture.payload.url,
+                    title: capture.payload.title,
+                    language: capture.payload.language,
+                    viewport: capture.payload.viewport,
+                },
+                pageSummary: typeof capture.payload.summary === 'object' && capture.payload.summary !== null
+                    ? capture.payload.summary
+                    : undefined,
+            };
+        },
+        set_viewport: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const width = resolveViewportDimension(input.width, 'width');
+            const height = resolveViewportDimension(input.height, 'height');
+            const capture = await executeLiveCapture(captureClient, sessionId, 'SET_VIEWPORT', {
+                width,
+                height,
+            }, 5_000);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: capture.truncated ?? false,
+                },
+                ...ensureCaptureSuccess(capture, sessionId),
+            };
+        },
+        assert_page_state: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const matcher = resolvePageStateMatcher(input);
+            const capture = await capturePageState(sessionId, input);
+            const assertion = evaluatePageStateAssertion(capture.payload, matcher);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: capture.limitsApplied,
+                matcher,
+                matched: assertion.matched,
+                matchCount: assertion.matchCount,
+                expectedCount: assertion.expectedCount,
+                sampledMatches: assertion.sampledMatches,
+                pageSummary: assertion.summary,
+                page: {
+                    url: capture.payload.url,
+                    title: capture.payload.title,
+                    language: capture.payload.language,
+                    viewport: capture.payload.viewport,
+                },
+            };
+        },
+        wait_for_page_state: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const waited = await waitForPageStateCondition(sessionId, input, capturePageState);
+            return {
+                ...createBaseResponse(sessionId),
+                ...waited,
+            };
+        },
+        run_ui_steps: async (input) => {
+            const request = RunUIStepsSchema.parse(input);
+            const workflowTraceId = createUIWorkflowTraceId();
+            const workflowStartedAt = Date.now();
+            const stepResults = [];
+            let lastPageCapture;
+            let failedStepId;
+            let stoppedAtIndex = request.steps.length;
+            let stateCaptureCount = 0;
+            let failureCaptureCount = 0;
+            let retryCount = 0;
+            const workflowCapturePageState = async (sessionId, toolInput) => {
+                stateCaptureCount += 1;
+                return capturePageState(sessionId, toolInput);
+            };
+            for (const [index, step] of request.steps.entries()) {
+                const stepId = createWorkflowStepId(step, index);
+                const failurePolicy = resolveWorkflowFailurePolicy(step, request.stopOnFailure);
+                let executionAttempts = 0;
+                let finalStepResult;
+                let stepFailed = false;
+                while (true) {
+                    executionAttempts += 1;
+                    const startedAt = Date.now();
+                    const previousCapture = lastPageCapture;
+                    try {
+                        if (step.kind === 'action') {
+                            const resolvedTarget = await resolveWorkflowActionTarget(request.sessionId, step.target, workflowCapturePageState, request.mode === 'fast' ? lastPageCapture : undefined);
+                            const liveRequest = LiveUIActionRequestSchema.parse({
+                                action: step.action,
+                                target: resolvedTarget.target,
+                                traceId: step.traceId ?? `${workflowTraceId}:${stepId}`,
+                                ...(step.input ? { input: step.input } : {}),
+                            });
+                            const capture = await executeLiveCapture(captureClient, request.sessionId, 'EXECUTE_UI_ACTION', liveRequest, 5_000);
+                            const payload = ensureCaptureSuccess(capture, request.sessionId);
+                            const actionResult = payload;
+                            const failed = actionResult.status === 'failed' || actionResult.status === 'rejected';
+                            let currentCapture = resolvedTarget.pageCapture ?? lastPageCapture;
+                            if (!failed && request.mode === 'fast') {
+                                await sleep(75);
+                                currentCapture = await captureWorkflowPageState(request.sessionId, workflowCapturePageState, request.mode);
+                            }
+                            lastPageCapture = currentCapture;
+                            finalStepResult = {
+                                id: stepId,
+                                kind: step.kind,
+                                status: failed ? 'failed' : 'succeeded',
+                                durationMs: Math.max(0, Date.now() - startedAt),
+                                action: step.action,
+                                traceId: actionResult.traceId,
+                                target: {
+                                    resolution: resolvedTarget.resolution,
+                                    actionTarget: typeof actionResult.target === 'object' && actionResult.target !== null
+                                        ? actionResult.target
+                                        : undefined,
+                                },
+                                error: failed && actionResult.failureReason
+                                    ? {
+                                        code: actionResult.failureReason.code,
+                                        message: actionResult.failureReason.message,
+                                    }
+                                    : undefined,
+                                pageChangeSummary: createPageChangeSummary(previousCapture, currentCapture),
+                            };
+                        }
+                        else if (step.kind === 'waitFor') {
+                            const waitInput = {
+                                ...step.matcher,
+                                timeoutMs: step.matcher.timeoutMs ?? request.defaultTimeoutMs,
+                                pollIntervalMs: step.matcher.pollIntervalMs ?? request.defaultPollIntervalMs,
+                            };
+                            const waited = await waitForPageStateConditionDetailed(request.sessionId, waitInput, workflowCapturePageState, request.mode === 'fast' ? lastPageCapture : undefined);
+                            lastPageCapture = waited.lastCapture ?? lastPageCapture;
+                            finalStepResult = {
+                                id: stepId,
+                                kind: step.kind,
+                                status: waited.matched ? 'succeeded' : 'failed',
+                                durationMs: Math.max(0, Date.now() - startedAt),
+                                matcher: waited.matcher,
+                                matchCount: waited.matchCount,
+                                waitedMs: waited.waitedMs,
+                                attempts: waited.attempts,
+                                error: waited.matched
+                                    ? undefined
+                                    : {
+                                        code: 'page_state_not_matched',
+                                        message: 'Workflow wait step timed out before the requested page state appeared.',
+                                    },
+                                pageChangeSummary: createPageChangeSummary(previousCapture, waited.lastCapture),
+                            };
+                        }
+                        else {
+                            const capture = request.mode === 'fast' && lastPageCapture
+                                ? lastPageCapture
+                                : await workflowCapturePageState(request.sessionId, step.matcher);
+                            const assertion = evaluatePageStateAssertion(capture.payload, resolvePageStateMatcher(step.matcher));
+                            lastPageCapture = capture;
+                            finalStepResult = {
+                                id: stepId,
+                                kind: step.kind,
+                                status: assertion.matched ? 'succeeded' : 'failed',
+                                durationMs: Math.max(0, Date.now() - startedAt),
+                                matcher: step.matcher,
+                                matchCount: assertion.matchCount,
+                                error: assertion.matched
+                                    ? undefined
+                                    : {
+                                        code: 'page_state_assertion_failed',
+                                        message: 'Workflow assert step did not match the requested page state.',
+                                    },
+                                pageChangeSummary: createPageChangeSummary(previousCapture, capture),
+                            };
+                        }
+                    }
+                    catch (error) {
+                        const workflowError = error instanceof WorkflowTargetResolutionError ? error : undefined;
+                        finalStepResult = {
+                            id: stepId,
+                            kind: step.kind,
+                            status: 'failed',
+                            durationMs: Math.max(0, Date.now() - startedAt),
+                            action: step.kind === 'action' ? step.action : undefined,
+                            target: step.kind === 'action' && workflowError
+                                ? workflowError.details
+                                : undefined,
+                            matcher: step.kind === 'action' ? undefined : step.matcher,
+                            error: normalizeWorkflowError(error),
+                        };
+                    }
+                    stepFailed = finalStepResult.status === 'failed';
+                    if (stepFailed && failurePolicy.strategy === 'retry_once' && executionAttempts === 1) {
+                        retryCount += 1;
+                        await sleep(100);
+                        continue;
+                    }
+                    break;
+                }
+                finalStepResult.executionAttempts = executionAttempts;
+                finalStepResult.failurePolicy = {
+                    strategy: failurePolicy.strategy,
+                    captureEnabled: Boolean(failurePolicy.captureOptions?.enabled),
+                };
+                finalStepResult.recommendedAction = resolveWorkflowRecommendedAction(finalStepResult.error);
+                if (stepFailed && failurePolicy.captureOptions) {
+                    const evidence = await captureFailureSnapshot(captureClient, request.sessionId, resolveWorkflowFailureSelector(step, finalStepResult.target), failurePolicy.captureOptions);
+                    if (evidence) {
+                        failureCaptureCount += 1;
+                        finalStepResult.failureEvidence = evidence;
+                    }
+                }
+                stepResults.push(finalStepResult);
+                if (stepFailed) {
+                    failedStepId ??= stepId;
+                    if (failurePolicy.strategy !== 'continue') {
+                        stoppedAtIndex = index + 1;
+                        break;
+                    }
+                }
+            }
+            if (failedStepId && stoppedAtIndex < request.steps.length) {
+                for (const [index, step] of request.steps.slice(stoppedAtIndex).entries()) {
+                    stepResults.push({
+                        id: createWorkflowStepId(step, stoppedAtIndex + index),
+                        kind: step.kind,
+                        status: 'skipped',
+                        durationMs: 0,
+                        action: step.kind === 'action' ? step.action : undefined,
+                        matcher: step.kind === 'action' ? undefined : step.matcher,
+                        pageChangeSummary: undefined,
+                        error: {
+                            code: 'workflow_stopped_early',
+                            message: `Skipped because workflow stopped after failed step "${failedStepId}".`,
+                        },
+                    });
+                }
+            }
+            let finalPageSummary;
+            let finalPage;
+            let finalCaptureTruncated = false;
+            try {
+                const finalCapture = lastPageCapture ?? await captureWorkflowPageState(request.sessionId, workflowCapturePageState, request.mode);
+                finalPageSummary =
+                    typeof finalCapture.payload.summary === 'object' && finalCapture.payload.summary !== null
+                        ? finalCapture.payload.summary
+                        : undefined;
+                finalPage = {
+                    url: finalCapture.payload.url,
+                    title: finalCapture.payload.title,
+                    language: finalCapture.payload.language,
+                    viewport: finalCapture.payload.viewport,
+                };
+                finalCaptureTruncated = finalCapture.limitsApplied.truncated;
+            }
+            catch {
+                finalPageSummary = undefined;
+                finalPage = undefined;
+            }
+            const workflowFinishedAt = Date.now();
+            const succeededSteps = stepResults.filter((step) => step.status === 'succeeded').length;
+            const failedSteps = stepResults.filter((step) => step.status === 'failed').length;
+            const skippedSteps = stepResults.filter((step) => step.status === 'skipped').length;
+            const failedStep = failedStepId
+                ? stepResults.find((step) => step.id === failedStepId && step.status === 'failed')
+                : undefined;
+            return {
+                ...createBaseResponse(request.sessionId),
+                limitsApplied: {
+                    maxResults: request.steps.length,
+                    truncated: finalCaptureTruncated,
+                },
+                traceId: workflowTraceId,
+                mode: request.mode,
+                status: failedStepId ? 'failed' : 'succeeded',
+                startedAt: workflowStartedAt,
+                finishedAt: workflowFinishedAt,
+                durationMs: Math.max(0, workflowFinishedAt - workflowStartedAt),
+                requestedStepCount: request.steps.length,
+                completedStepCount: succeededSteps,
+                failedStepId,
+                stoppedEarly: Boolean(failedStepId && stoppedAtIndex < request.steps.length),
+                recommendedAction: failedStep?.recommendedAction,
+                stepCounts: {
+                    succeeded: succeededSteps,
+                    failed: failedSteps,
+                    skipped: skippedSteps,
+                },
+                workflowDiagnostics: {
+                    retryCount,
+                    stateCaptureCount,
+                    failureCaptureCount,
+                    usedCachedState: request.mode === 'fast',
+                },
+                steps: stepResults,
+                finalPageSummary,
+                finalPage,
+            };
+        },
         capture_ui_snapshot: async (input) => {
             const sessionId = getSessionId(input);
             if (!sessionId) {
@@ -2482,21 +6282,11 @@ export function createV2ToolHandlers(captureClient) {
                 llmRequested: true,
             }, 5_000);
             const payload = ensureCaptureSuccess(capture, sessionId);
-            const snapshotRecord = structuredClone(payload);
-            const snapshotRoot = snapshotRecord.snapshot;
-            if (typeof snapshotRoot === 'object' && snapshotRoot !== null) {
-                const snapshotObject = snapshotRoot;
-                if (!includeDom) {
-                    delete snapshotObject.dom;
-                }
-                if (!includeStyles) {
-                    delete snapshotObject.styles;
-                }
-            }
-            const png = snapshotRecord.png;
-            if (!includePngDataUrl && typeof png === 'object' && png !== null) {
-                delete png.dataUrl;
-            }
+            const snapshotRecord = normalizeSnapshotResponsePayload(payload, {
+                includeDom,
+                includeStyles,
+                includePngDataUrl,
+            });
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
@@ -2577,6 +6367,72 @@ export function createV2ToolHandlers(captureClient) {
                 bufferStats: payload.bufferStats,
             };
         },
+        execute_ui_action: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const actionInput = { ...input };
+            delete actionInput.sessionId;
+            delete actionInput.captureOnFailure;
+            const request = LiveUIActionRequestSchema.parse(actionInput);
+            const failureCaptureOptions = resolveFailureEvidenceCaptureOptions(input);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'EXECUTE_UI_ACTION', request, 5_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
+            const actionResult = payload;
+            const failed = actionResult.status === 'failed' || actionResult.status === 'rejected';
+            const failureEvidence = failed
+                ? await captureFailureEvidence(captureClient, sessionId, request, failureCaptureOptions)
+                : undefined;
+            const postActionWaitInput = typeof input.waitForPageState === 'object' && input.waitForPageState !== null
+                ? {
+                    ...input.waitForPageState,
+                }
+                : undefined;
+            const postActionState = actionResult.status === 'succeeded' && postActionWaitInput
+                ? await waitForPageStateCondition(sessionId, postActionWaitInput, capturePageState)
+                : undefined;
+            const evidenceTruncated = Boolean(failureEvidence
+                && typeof failureEvidence === 'object'
+                && failureEvidence !== null
+                && typeof failureEvidence.limitsApplied?.truncated === 'boolean'
+                && failureEvidence.limitsApplied.truncated);
+            const target = typeof actionResult.target === 'object' && actionResult.target !== null
+                ? actionResult.target
+                : {};
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: (capture.truncated ?? false)
+                        || evidenceTruncated
+                        || Boolean(postActionState?.limitsApplied.truncated),
+                },
+                action: actionResult.action,
+                status: actionResult.status,
+                traceId: actionResult.traceId,
+                startedAt: actionResult.startedAt,
+                finishedAt: actionResult.finishedAt,
+                durationMs: typeof actionResult.startedAt === 'number' && typeof actionResult.finishedAt === 'number'
+                    ? Math.max(0, actionResult.finishedAt - actionResult.startedAt)
+                    : undefined,
+                actionResult,
+                target,
+                tabContext: {
+                    tabId: typeof target.tabId === 'number' ? target.tabId : undefined,
+                    frameId: typeof target.frameId === 'number' ? target.frameId : 0,
+                    url: typeof target.url === 'string' ? target.url : undefined,
+                },
+                failureDetails: actionResult.failureReason,
+                postActionEvidence: failureEvidence,
+                postActionState,
+                supportedScopes: {
+                    executionScope: actionResult.executionScope,
+                    topDocumentOnly: true,
+                    opensNewBrowserSession: false,
+                },
+            };
+        },
     };
 }
 function isRecord(value) {
@@ -2634,7 +6490,9 @@ export async function routeToolCall(tools, toolName, input) {
 }
 export function createMCPServer(overrides = {}, options = {}) {
     const logger = options.logger ?? createDefaultMcpLogger();
-    const v2Handlers = options.captureClient ? createV2ToolHandlers(options.captureClient) : {};
+    const v2Handlers = options.captureClient
+        ? createV2ToolHandlers(options.captureClient, () => getConnection().db, options.getSessionConnectionState)
+        : {};
     const tools = createToolRegistry({
         ...createV1ToolHandlers(() => getConnection().db, options.getSessionConnectionState),
         ...v2Handlers,