browser-debug-mcp-bridge 1.10.0 → 1.11.0

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

@@ -1,10 +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`);
@@ -270,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: {
@@ -470,13 +487,6 @@ const TOOL_SCHEMAS = {
             maxTextLength: { type: 'number' },
         },
     },
-    get_live_session_health: {
-        type: 'object',
-        required: ['sessionId'],
-        properties: {
-            sessionId: { type: 'string' },
-        },
-    },
     set_viewport: {
         type: 'object',
         required: ['sessionId', 'width', 'height'],
@@ -577,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'],
@@ -841,6 +1068,22 @@ const TOOL_DESCRIPTIONS = {
     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',
@@ -870,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,
@@ -1074,7 +1327,772 @@ function resolveLastUrl(payload) {
             return candidate;
         }
     }
-    return undefined;
+    return undefined;
+}
+function classifySessionUrl(urlValue) {
+    if (!urlValue) {
+        return {
+            kind: 'unknown',
+            note: 'No session URL is available yet.',
+        };
+    }
+    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 (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,
+            };
+        }
+    }
+    catch {
+        return {
+            kind: 'unknown',
+            note: 'Session URL could not be parsed.',
+        };
+    }
+    return {
+        kind: 'unknown',
+        note: 'Session URL does not use an http(s) page origin.',
+    };
+}
+function getSessionStatus(row) {
+    if (row.ended_at) {
+        return 'ended';
+    }
+    if (row.paused_at) {
+        return 'paused';
+    }
+    return 'active';
+}
+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 profile;
+}
+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 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.`,
+        });
+    }
+    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.`,
+        });
+    }
+    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.`,
+                });
+            }
+        }
+    }
+    if (rule.requestMethod !== 'GET') {
+        issues.push({
+            code: 'RSC_FLIGHT_METHOD_UNSUPPORTED',
+            severity: 'error',
+            message: `Rule ${ruleId} RSC flight overrides only support GET requests.`,
+        });
+    }
+    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);
@@ -2155,6 +3173,144 @@ 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;
@@ -2265,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 ')}` : '';
@@ -2273,6 +3434,7 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
         SELECT
           session_id,
           created_at,
+          last_seen_at,
           paused_at,
           ended_at,
           tab_id,
@@ -2287,204 +3449,596 @@ 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
+            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 {
+                ...createBaseResponse(),
+                limitsApplied: {
+                    maxResults: limit,
+                    truncated,
+                },
+                pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
+                responseBytes: bytePage.responseBytes,
+                sessions: bytePage.items,
+            };
+        },
+        get_session_summary: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const session = db
+                .prepare('SELECT session_id, created_at, ended_at, url_last, pinned FROM sessions WHERE session_id = ?')
+                .get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            const counters = db
+                .prepare(`
+        SELECT
+          SUM(CASE WHEN type = 'error' THEN 1 ELSE 0 END) AS errors,
+          SUM(CASE WHEN type = 'console' AND json_extract(payload_json, '$.level') = 'warn' THEN 1 ELSE 0 END) AS warnings
+        FROM events
+        WHERE session_id = ?
+      `)
+                .get(sessionId);
+            const networkFails = db
+                .prepare(`
+        SELECT COUNT(*) AS count
+        FROM network
+        WHERE session_id = ?
+          AND (error_class IS NOT NULL OR COALESCE(status, 0) >= 400)
+      `)
+                .get(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 eventRange = db
+                .prepare(`
+        SELECT MIN(ts) AS start_ts, MAX(ts) AS end_ts
+        FROM events
+        WHERE session_id = ?
+      `)
+                .get(sessionId);
+            const navPayload = latestNav ? readJsonPayload(latestNav.payload_json) : {};
+            const lastUrl = resolveLastUrl(navPayload) ?? session.url_last ?? undefined;
+            return {
+                ...createBaseResponse(sessionId),
+                counts: {
+                    errors: counters.errors ?? 0,
+                    warnings: counters.warnings ?? 0,
+                    networkFails: networkFails.count,
+                },
+                lastUrl,
+                timeRange: {
+                    start: eventRange.start_ts ?? session.created_at,
+                    end: eventRange.end_ts ?? session.ended_at ?? session.created_at,
+                },
+                pinned: session.pinned === 1,
+            };
+        },
+        get_live_session_health: async (input) => {
+            const db = getDb();
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const session = db
+                .prepare(`
+          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: row.viewport_w,
-                        height: row.viewport_h,
+                        width: session.viewport_w,
+                        height: session.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 bytePage = applyByteBudget(sessions, maxResponseBytes);
-            const truncated = truncatedByLimit || bytePage.truncatedByBytes;
+                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(),
+                ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: limit,
                     truncated,
                 },
+                runId: runId ?? null,
                 pagination: buildOffsetPagination(offset, bytePage.items.length, truncated, maxResponseBytes),
                 responseBytes: bytePage.responseBytes,
-                sessions: bytePage.items,
+                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_live_session_health: async (input) => {
+        get_override_plan_log: async (input) => {
             const db = getDb();
             const sessionId = getSessionId(input);
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const session = db
-                .prepare(`
-          SELECT
-            session_id,
-            created_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 = ?
-          LIMIT 1
-        `)
-                .get(sessionId);
-            if (!session) {
-                throw new Error(`Session not found: ${sessionId}`);
-            }
-            const connection = getSessionConnectionState?.(sessionId);
-            const now = Date.now();
-            const lastSeenAt = connection?.connected
-                ? connection.lastHeartbeatAt
-                : connection?.disconnectedAt ?? session.ended_at ?? session.paused_at ?? session.created_at;
-            const staleForMs = lastSeenAt ? Math.max(0, now - lastSeenAt) : undefined;
+            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: 1,
-                    truncated: false,
-                },
-                session: {
-                    sessionId: session.session_id,
-                    createdAt: session.created_at,
-                    pausedAt: session.paused_at ?? undefined,
-                    endedAt: session.ended_at ?? undefined,
-                    status: session.ended_at ? 'ended' : session.paused_at ? 'paused' : 'active',
-                    tabId: session.tab_id ?? undefined,
-                    windowId: session.window_id ?? undefined,
-                    urlStart: session.url_start ?? undefined,
-                    urlLast: session.url_last ?? undefined,
-                    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,
+                    maxResults: limit,
+                    truncated,
                 },
-                liveConnection: connection
-                    ? {
-                        connected: connection.connected,
-                        connectedAt: connection.connectedAt,
-                        lastHeartbeatAt: connection.lastHeartbeatAt,
-                        disconnectedAt: connection.disconnectedAt,
-                        disconnectReason: connection.disconnectReason,
-                        staleForMs,
-                    }
-                    : {
-                        connected: false,
-                        staleForMs,
-                    },
-                recommendedAction: connection?.connected
-                    ? 'ready'
-                    : session.ended_at
-                        ? 'start_new_session'
-                        : 'reconnect_extension',
+                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.' }],
             };
         },
-        get_session_summary: async (input) => {
+        diagnose_overrides: async (input) => {
             const db = getDb();
             const sessionId = getSessionId(input);
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const session = db
-                .prepare('SELECT session_id, created_at, ended_at, url_last, pinned FROM sessions WHERE session_id = ?')
-                .get(sessionId);
-            if (!session) {
-                throw new Error(`Session not found: ${sessionId}`);
-            }
-            const counters = db
-                .prepare(`
-        SELECT
-          SUM(CASE WHEN type = 'error' THEN 1 ELSE 0 END) AS errors,
-          SUM(CASE WHEN type = 'console' AND json_extract(payload_json, '$.level') = 'warn' THEN 1 ELSE 0 END) AS warnings
-        FROM events
-        WHERE session_id = ?
-      `)
-                .get(sessionId);
-            const networkFails = db
-                .prepare(`
-        SELECT COUNT(*) AS count
-        FROM network
-        WHERE session_id = ?
-          AND (error_class IS NOT NULL OR COALESCE(status, 0) >= 400)
-      `)
-                .get(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 eventRange = db
-                .prepare(`
-        SELECT MIN(ts) AS start_ts, MAX(ts) AS end_ts
-        FROM events
-        WHERE session_id = ?
-      `)
-                .get(sessionId);
-            const navPayload = latestNav ? readJsonPayload(latestNav.payload_json) : {};
-            const lastUrl = resolveLastUrl(navPayload) ?? session.url_last ?? undefined;
+            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),
-                counts: {
-                    errors: counters.errors ?? 0,
-                    warnings: counters.warnings ?? 0,
-                    networkFails: networkFails.count,
-                },
-                lastUrl,
-                timeRange: {
-                    start: eventRange.start_ts ?? session.created_at,
-                    end: eventRange.end_ts ?? session.ended_at ?? session.created_at,
-                },
-                pinned: session.pinned === 1,
+                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) => {
@@ -3822,7 +5376,7 @@ export function createV1ToolHandlers(getDb, getSessionConnectionState) {
         },
     };
 }
-export function createV2ToolHandlers(captureClient) {
+export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionState) {
     const capturePageState = async (sessionId, input) => {
         const maxItems = resolveStructuredMaxItems(input.maxItems, 40);
         const maxTextLength = resolveStructuredTextLength(input.maxTextLength, 80);
@@ -3845,6 +5399,420 @@ export function createV2ToolHandlers(captureClient) {
         };
     };
     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,
+                },
+                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.' }],
+            };
+        },
+        preflight_overrides: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            if (!getDb) {
+                throw new Error('preflight_overrides requires database-backed override state');
+            }
+            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 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 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: capture.truncated ?? false,
+                },
+                preflight,
+                ...payload,
+                nextActions: [{ code: 'RELOAD_OR_INTERACT', message: 'Reload or interact with the tab so configured asset requests occur under the active override.' }],
+            };
+        },
+        disable_overrides: async (input) => {
+            const sessionId = getSessionId(input);
+            if (!sessionId) {
+                throw new Error('sessionId is required');
+            }
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_DISABLE', {}, 5_000);
+            const payload = ensureCaptureSuccess(capture, sessionId);
+            return {
+                ...createBaseResponse(sessionId),
+                limitsApplied: {
+                    maxResults: 1,
+                    truncated: capture.truncated ?? false,
+                },
+                ...payload,
+                nextActions: [{ code: 'VERIFY_DISABLED', message: 'Run get_override_status if you need to confirm the debugger override is inactive.' }],
+            };
+        },
         get_dom_subtree: async (input) => {
             const sessionId = getSessionId(input);
             if (!sessionId) {
@@ -4522,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,