screenhand 0.2.0 → 0.3.1

package/dist/src/playbook/mcp-recorder.js

@@ -0,0 +1,204 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * McpPlaybookRecorder — captures MCP tool calls as PlaybookSteps.
+ *
+ * Start recording → agent does the flow → stop → saves as executable playbook.
+ * Like a macro recorder, but for AI tool calls.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomicSync } from "../util/atomic-write.js";
+import { redactPII } from "../util/sanitize.js";
+/** Tools that are observation-only — not recorded as steps */
+const SKIP_TOOLS = new Set([
+    "screenshot", "screenshot_file",
+    "ui_tree", "ui_find", "browser_dom", "browser_page_info", "browser_tabs",
+    "ocr", "apps", "windows", "memory_recall", "memory_save", "memory_snapshot",
+    "memory_stats", "memory_errors", "memory_query_patterns", "memory_record_error",
+    "memory_record_learning", "memory_clear", "platform_guide", "playbook_preflight",
+    "export_playbook", "playbook_record", "job_create", "job_status", "job_list",
+    "job_run", "job_run_all", "job_create_chain", "job_remove", "job_transition",
+    "job_step_done", "job_step_fail", "job_resume", "job_dequeue",
+    "worker_start", "worker_stop", "worker_status",
+    "supervisor_status", "supervisor_start", "supervisor_stop",
+    "supervisor_pause", "supervisor_resume", "supervisor_install", "supervisor_uninstall",
+    "session_claim", "session_heartbeat", "session_release",
+    "recovery_queue_add", "recovery_queue_list",
+    "codex_monitor_start", "codex_monitor_status", "codex_monitor_add_task",
+    "codex_monitor_tasks", "codex_monitor_assign_now", "codex_monitor_stop",
+    "platform_learn", "platform_explore",
+]);
+/** Map MCP tool names to PlaybookStep actions */
+function mapToolToAction(toolName) {
+    switch (toolName) {
+        case "browser_navigate": return "navigate";
+        case "click":
+        case "click_text":
+        case "browser_click":
+        case "click_with_fallback":
+        case "ui_press": return "press";
+        case "type_text":
+        case "browser_type":
+        case "type_with_fallback": return "type_into";
+        case "key": return "key";
+        case "menu_click": return "menu_click";
+        case "scroll":
+        case "scroll_with_fallback": return "scroll";
+        case "browser_js": return "browser_js";
+        case "screenshot":
+        case "screenshot_file": return "screenshot";
+        case "browser_wait":
+        case "wait_for_state": return "wait";
+        case "focus":
+        case "launch": return null; // useful context but not a step
+        case "drag": return null; // drag is complex, skip for now
+        default: return null;
+    }
+}
+/** Build a PlaybookStep from an MCP tool call */
+function buildStep(toolName, params, success) {
+    const action = mapToolToAction(toolName);
+    if (!action)
+        return null;
+    const step = { action };
+    switch (action) {
+        case "navigate":
+            step.url = String(params.url ?? "");
+            step.description = `Navigate to ${step.url}`;
+            break;
+        case "press":
+            step.target = String(params.selector ?? params.text ?? params.title ?? params.target ?? "");
+            step.description = `Click ${step.target}`;
+            break;
+        case "type_into":
+            step.target = String(params.selector ?? params.target ?? params.field ?? "");
+            step.text = String(params.text ?? params.value ?? "");
+            step.description = `Type "${step.text.substring(0, 50)}" into ${step.target}`;
+            break;
+        case "key":
+        case "key_combo": {
+            const combo = String(params.combo ?? params.key ?? "");
+            step.keys = combo.split("+").map(k => k.trim());
+            step.description = `${action === "key" ? "Key" : "Key combo"}: ${combo}`;
+            break;
+        }
+        case "menu_click": {
+            const menuPath = Array.isArray(params.menuPath)
+                ? params.menuPath.map((part) => String(part).trim()).filter(Boolean)
+                : String(params.menuPath ?? "").split("/").map((part) => part.trim()).filter(Boolean);
+            step.menuPath = menuPath;
+            step.description = `Menu click: ${menuPath.join(" > ")}`;
+            break;
+        }
+        case "scroll":
+            step.direction = params.direction ?? "down";
+            if (params.amount != null)
+                step.amount = Number(params.amount);
+            step.description = `Scroll ${step.direction}`;
+            break;
+        case "browser_js":
+            step.code = String(params.code ?? "");
+            step.description = `Execute JS: ${step.code.substring(0, 60)}...`;
+            break;
+        case "screenshot":
+            step.description = "Take screenshot";
+            break;
+        case "wait":
+            step.ms = Number(params.timeout ?? params.ms ?? params.timeoutMs ?? 1000);
+            step.description = `Wait ${step.ms}ms`;
+            break;
+    }
+    if (!success) {
+        step.optional = true;
+    }
+    return step;
+}
+export class McpPlaybookRecorder {
+    playbooksDir;
+    recording = false;
+    platform = "";
+    steps = [];
+    startTime = "";
+    cdpPort;
+    constructor(playbooksDir) {
+        this.playbooksDir = playbooksDir;
+    }
+    get isRecording() { return this.recording; }
+    get stepCount() { return this.steps.length; }
+    getSteps() { return [...this.steps]; }
+    start(platform, cdpPort) {
+        this.recording = true;
+        this.platform = platform;
+        this.steps = [];
+        this.startTime = new Date().toISOString();
+        if (cdpPort !== undefined)
+            this.cdpPort = cdpPort;
+    }
+    captureToolCall(toolName, params, success, _result, _durationMs) {
+        if (!this.recording)
+            return;
+        if (SKIP_TOOLS.has(toolName))
+            return;
+        const step = buildStep(toolName, params, success);
+        if (!step)
+            return;
+        // Deduplicate consecutive identical steps
+        const last = this.steps[this.steps.length - 1];
+        if (last &&
+            last.action === step.action &&
+            last.target === step.target &&
+            last.text === step.text &&
+            last.code === step.code &&
+            JSON.stringify(last.keys ?? []) === JSON.stringify(step.keys ?? []) &&
+            JSON.stringify(last.menuPath ?? []) === JSON.stringify(step.menuPath ?? [])) {
+            return; // skip duplicate
+        }
+        this.steps.push(step);
+    }
+    stop(name, description) {
+        this.recording = false;
+        // Sanitize platform to prevent path traversal in filename
+        const safePlatform = this.platform.replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 100);
+        const id = safePlatform + "-" + Date.now().toString(36);
+        // S75 Option C: Redact PII in persisted playbook steps and metadata
+        const redactedSteps = this.steps.map(s => ({
+            ...s,
+            ...(s.text ? { text: redactPII(s.text) } : {}),
+            ...(typeof s.target === "string" ? { target: redactPII(s.target) } : {}),
+            ...(s.url ? { url: redactPII(s.url) } : {}),
+            ...(s.code ? { code: redactPII(s.code) } : {}),
+            ...(s.description ? { description: redactPII(s.description) } : {}),
+        }));
+        const playbook = {
+            id,
+            name: redactPII(name),
+            description: redactPII(description),
+            platform: this.platform,
+            version: "1.0.0",
+            tags: [this.platform, "recorded"],
+            successCount: 0,
+            failCount: 0,
+            steps: redactedSteps,
+        };
+        if (this.cdpPort) {
+            playbook.cdpPort = this.cdpPort;
+        }
+        // Save to playbooks dir
+        if (!fs.existsSync(this.playbooksDir)) {
+            fs.mkdirSync(this.playbooksDir, { recursive: true });
+        }
+        const safeFilename = `${id}.json`;
+        const resolved = path.resolve(path.join(this.playbooksDir, safeFilename));
+        if (!resolved.startsWith(path.resolve(this.playbooksDir))) {
+            throw new Error("Invalid playbook path — refusing to write outside playbooks directory");
+        }
+        writeFileAtomicSync(resolved, JSON.stringify(playbook, null, 2));
+        this.steps = [];
+        return playbook;
+    }
+    cancel() {
+        this.recording = false;
+        this.steps = [];
+    }
+}

package/dist/src/playbook/recorder.js

@@ -332,11 +332,12 @@ ${events.map((e, i) => `${i + 1}. [${e.timestamp}] ${e.type}: ${JSON.stringify(e
 ${screenshots.length > 0 ? `\n${screenshots.length} screenshots were taken during recording. The first and last are attached below for visual context.\n` : ""}
 Convert these into a JSON array of playbook steps. Each step:
 {
-  "action": "navigate" | "press" | "type_into" | "key_combo" | "scroll" | "wait" | "screenshot",
+  "action": "navigate" | "press" | "type_into" | "key" | "key_combo" | "menu_click" | "scroll" | "wait" | "screenshot",
   "target": "CSS selector, text label, or {\"selector\": \"...\"}",
   "url": "for navigate",
   "text": "for type_into",
-  "keys": ["for", "key_combo"],
+  "keys": ["for", "key or key_combo"],
+  "menuPath": ["for", "menu_click"],
   "ms": 1000,
   "description": "human-readable description of what this step does",
   "verify": "optional CSS selector or text to verify success",

package/dist/src/playbook/runner.js

@@ -231,7 +231,7 @@ Current UI state:
 ${pageState}
 ${playbookContext ? `\n--- PLAYBOOK REFERENCE ---\n${playbookContext}\nUse the selectors, flows, and error solutions above to guide your actions. Prefer data-testid selectors over text matching.\n---\n` : ""}
 What's the next step? Respond with ONE step as JSON:
-{ "action": "press|type_into|navigate|key_combo|scroll|wait", "target": "...", "text": "...", "url": "...", "keys": [...], "ms": 1000, "description": "..." }
+{ "action": "press|type_into|navigate|key|key_combo|menu_click|scroll|wait", "target": "...", "text": "...", "url": "...", "keys": [...], "menuPath": ["File", "Save"], "ms": 1000, "description": "..." }
 
 Or if done: { "action": "done", "description": "Task complete" }`;
             try {

package/dist/src/playbook/store.js

@@ -24,6 +24,20 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomicSync } from "../util/atomic-write.js";
+/** Extract hostname from a URL or URL pattern string */
+function extractHost(urlOrPattern) {
+    const cleaned = urlOrPattern.replace(/^\*/, "").replace(/\\/g, "");
+    try {
+        // Try parsing as a URL
+        const u = new URL(cleaned.startsWith("http") ? cleaned : "https://" + cleaned);
+        return u.hostname.toLowerCase();
+    }
+    catch {
+        // Fallback: extract domain-like portion
+        const match = cleaned.match(/(?:https?:\/\/)?([a-z0-9.-]+)/i);
+        return match ? match[1].toLowerCase() : "";
+    }
+}
 export class PlaybookStore {
     dir;
     playbooks = new Map();
@@ -57,6 +71,84 @@ export class PlaybookStore {
     get(id) {
         return this.playbooks.get(id);
     }
+    /** Find best playbook matching a domain (e.g., "x.com", "figma.com"). */
+    matchByDomain(domain) {
+        const domainLower = domain.toLowerCase();
+        if (domainLower.length === 0)
+            return null;
+        // Extract the meaningful part of the domain (before first dot)
+        const domainPrefix = domainLower.split(".")[0];
+        let best = null;
+        let bestScore = 0;
+        for (const p of this.playbooks.values()) {
+            let score = 0;
+            // Check platform name — require prefix to be at least 3 chars to avoid phantom matches
+            if (domainPrefix.length >= 3 && p.platform.toLowerCase().includes(domainPrefix))
+                score += 2;
+            // Check URL patterns — extract hostname and compare exactly (no subdomain matching)
+            // e.g. "google.com" should NOT match "adstransparency.google.com"
+            if (p.urlPatterns?.some((pat) => {
+                const host = extractHost(pat);
+                return host === domainLower || host === "www." + domainLower;
+            }))
+                score += 3;
+            // Check URLs map — extract hostname and compare exactly
+            if (p.urls) {
+                const hasUrl = Object.values(p.urls).some((u) => {
+                    const host = extractHost(u);
+                    return host === domainLower || host === "www." + domainLower;
+                });
+                if (hasUrl)
+                    score += 3;
+            }
+            // Check tags — require tag to be at least 4 chars to avoid phantom matches (e.g. "x" matching "example.com")
+            if (p.tags.some((t) => t.length >= 4 && domainLower.includes(t.toLowerCase())))
+                score += 1;
+            // Weight by reliability — floor at 0.1 so valid matches are never zeroed out
+            if (score > 0 && p.successCount + p.failCount > 0) {
+                score *= Math.max(0.1, p.successCount / (p.successCount + p.failCount));
+            }
+            if (score > bestScore) {
+                bestScore = score;
+                best = p;
+            }
+        }
+        return bestScore > 0 ? best : null;
+    }
+    /** Find best playbook matching a macOS bundle ID (e.g., "com.blackmagic-design.DaVinciResolveLite"). */
+    matchByBundleId(bundleId) {
+        const idLower = bundleId.toLowerCase();
+        // Extract the short app name from bundleId (e.g., "davinciresolvelite" from "com.blackmagic-design.DaVinciResolveLite")
+        const shortName = idLower.split(".").pop() ?? idLower;
+        let best = null;
+        let bestScore = 0;
+        for (const p of this.playbooks.values()) {
+            let score = 0;
+            // Direct bundleId match (if the reference stores it)
+            if (p.bundleId?.toLowerCase() === idLower)
+                score += 10;
+            // Check platform name against short app name
+            const platLower = p.platform.toLowerCase().replace(/[^a-z0-9]/g, "");
+            const shortClean = shortName.replace(/[^a-z0-9]/g, "");
+            if (platLower.includes(shortClean) || shortClean.includes(platLower))
+                score += 3;
+            // Check tags — require tag to be at least 4 chars to avoid phantom matches (e.g. "com")
+            if (p.tags.some((t) => {
+                const cleaned = t.toLowerCase().replace(/[^a-z0-9.]/g, "");
+                return cleaned.length >= 4 && idLower.includes(cleaned);
+            }))
+                score += 1;
+            // Weight by reliability — floor at 0.1 so valid matches are never zeroed out
+            if (score > 0 && p.successCount + p.failCount > 0) {
+                score *= Math.max(0.1, p.successCount / (p.successCount + p.failCount));
+            }
+            if (score > bestScore) {
+                bestScore = score;
+                best = p;
+            }
+        }
+        return bestScore > 0 ? best : null;
+    }
     /** Find playbooks matching a URL. */
     matchByUrl(url) {
         return this.getAll().filter((p) => {
@@ -64,7 +156,15 @@ export class PlaybookStore {
                 return false;
             return p.urlPatterns.some((pattern) => {
                 try {
-                    return new RegExp(pattern).test(url);
+                    // Guard against ReDoS: reject patterns that could cause catastrophic backtracking
+                    if (/([+*])\1|(\([^)]*[+*][^)]*\))[+*]/.test(pattern)) {
+                        return url.includes(pattern);
+                    }
+                    const re = new RegExp(pattern);
+                    // Use a timeout-safe approach: test with a length limit
+                    if (url.length > 2048)
+                        return false;
+                    return re.test(url);
                 }
                 catch {
                     return url.includes(pattern);
@@ -86,38 +186,65 @@ export class PlaybookStore {
             .sort((a, b) => b.successCount - a.successCount);
     }
     /** Find best playbook for a task description (simple keyword matching). */
-    matchByTask(task) {
-        const tokens = task.toLowerCase().split(/\W+/).filter((w) => w.length >= 3);
+    matchByTask(task, currentBundleId) {
+        // Filter out very common words that cause false matches across unrelated playbooks
+        const STOP_WORDS = new Set([
+            "the", "and", "for", "with", "from", "into", "that", "this", "then",
+            "type", "click", "open", "close", "save", "new", "text", "file",
+            "app", "use", "set", "get", "add", "run", "start", "stop",
+            "page", "post", "button", "menu", "tab", "window", "link",
+            "send", "copy", "paste", "delete", "create", "edit", "view",
+            "show", "hide", "move", "drag", "drop", "enter", "press",
+            "input", "form", "image", "video", "upload", "download",
+            "navigate", "select", "find", "wait", "about",
+        ]);
+        const tokens = task.toLowerCase().split(/\W+/)
+            .filter((w) => w.length >= 3 && !STOP_WORDS.has(w));
         if (tokens.length === 0)
             return null;
         let best = null;
         let bestScore = 0;
+        let bestRawScore = 0;
         for (const p of this.playbooks.values()) {
             const haystack = `${p.name} ${p.description} ${p.tags.join(" ")} ${p.platform}`.toLowerCase();
-            let score = 0;
+            let rawScore = 0;
             for (const token of tokens) {
                 if (haystack.includes(token))
-                    score++;
+                    rawScore++;
+            }
+            // Boost playbooks whose bundleId matches the current app
+            if (currentBundleId && p.bundleId && p.bundleId.toLowerCase() === currentBundleId.toLowerCase()) {
+                rawScore += 2;
             }
-            // Weight by reliability
+            // Weight by reliability for ranking, but check threshold against raw score
             const reliability = p.successCount + p.failCount > 0
                 ? p.successCount / (p.successCount + p.failCount)
                 : 0.5;
-            score *= reliability;
+            const score = rawScore * reliability;
             if (score > bestScore) {
                 bestScore = score;
+                bestRawScore = rawScore;
                 best = p;
             }
         }
-        return bestScore > 0 ? best : null;
+        // Require at least 50% of meaningful tokens to match (raw, before reliability weighting)
+        // AND at least 2 raw token matches to prevent single-word false positives
+        const minRawScore = Math.max(Math.ceil(tokens.length * 0.5), 2);
+        return bestRawScore >= minRawScore ? best : null;
     }
     /** Save a playbook to disk. */
     save(playbook) {
         if (!fs.existsSync(this.dir)) {
             fs.mkdirSync(this.dir, { recursive: true });
         }
-        const filename = `${playbook.id}.json`;
-        writeFileAtomicSync(path.join(this.dir, filename), JSON.stringify(playbook, null, 2) + "\n");
+        // Sanitize ID to prevent path traversal, truncate to avoid ENAMETOOLONG (max 255 on macOS/Linux)
+        const safeId = playbook.id.replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 200);
+        const filename = `${safeId}.json`;
+        const resolved = path.resolve(path.join(this.dir, filename));
+        if (!resolved.startsWith(path.resolve(this.dir))) {
+            return; // Path traversal attempt — refuse to write
+        }
+        writeFileAtomicSync(resolved, JSON.stringify(playbook, null, 2) + "\n");
         this.playbooks.set(playbook.id, playbook);
     }
     /** Record a run outcome. */
@@ -169,6 +296,8 @@ export class PlaybookStore {
             successCount: 0,
             failCount: 0,
             // Preserve rich metadata
+            ...(raw.bundleId ? { bundleId: raw.bundleId } : {}),
+            ...(raw.cdpPort ? { cdpPort: raw.cdpPort } : {}),
             ...(raw.urls ? { urls: raw.urls } : {}),
             ...(raw.selectors ? { selectors: raw.selectors } : {}),
             ...(raw.flows ? { flows: raw.flows } : {}),

package/dist/src/recovery/detectors.js

@@ -0,0 +1,156 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+const PERMISSION_PATTERNS = /access|allow|permission|accessibility|camera|microphone|location|contacts/i;
+const LOGIN_PATTERNS = /sign in|log in|login|session expired|authenticate/i;
+const CAPTCHA_PATTERNS = /captcha|verify you.re human|are you a robot/i;
+const RATE_LIMIT_PATTERNS = /rate limit|too many requests|slow down/i;
+const NETWORK_ERROR_PATTERNS = /network error|failed to load|no internet|connection refused/i;
+const CRASH_DIALOG_PATTERNS = /not responding|crashed|quit unexpectedly/i;
+const POPUP_BLOCKED_PATTERNS = /popup.*block|pop-up.*block|blocked.*popup|blocked.*pop-up|window\.open.*blocked/i;
+/**
+ * Scan the WorldModel and error text to detect blockers, sorted by priority.
+ * Returns an empty array only if no blockers can be inferred.
+ */
+export function detectBlockers(worldModel, failedStepError, expectedBundleId) {
+    const blockers = [];
+    const state = worldModel.getState();
+    const pidFields = state.focusedApp?.pid != null ? { pid: state.focusedApp.pid } : {};
+    // 1. Dialog-based blockers (highest priority)
+    const dialogs = worldModel.getActiveDialogs();
+    for (const dialog of dialogs) {
+        const type = classifyDialogType(dialog.title, dialog.type);
+        blockers.push({
+            type,
+            description: `${type}: "${dialog.title || dialog.type}"`,
+            bundleId: expectedBundleId,
+            ...pidFields,
+            dialogTitle: dialog.title,
+        });
+    }
+    // 2. Focus loss
+    if (expectedBundleId !== null) {
+        const focusedApp = state.focusedApp;
+        if (focusedApp && focusedApp.bundleId !== expectedBundleId) {
+            blockers.push({
+                type: "focus_lost",
+                description: `Expected ${expectedBundleId}, got ${focusedApp.bundleId}`,
+                bundleId: expectedBundleId,
+                ...pidFields,
+            });
+        }
+        if (!focusedApp && state.windows.size === 0) {
+            blockers.push({
+                type: "app_crashed",
+                description: `No windows tracked for ${expectedBundleId}`,
+                bundleId: expectedBundleId,
+                ...pidFields,
+            });
+        }
+    }
+    // 3. Many stale controls = world model outdated
+    const staleControls = worldModel.getStaleControls(10_000);
+    if (staleControls.length > 10) {
+        blockers.push({
+            type: "unknown_state",
+            description: `${staleControls.length} stale controls`,
+            bundleId: expectedBundleId,
+            ...pidFields,
+        });
+    }
+    // 4. Error text pattern matching
+    const err = failedStepError.toLowerCase();
+    if (CAPTCHA_PATTERNS.test(err)) {
+        blockers.push({ type: "captcha", description: `Captcha: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (RATE_LIMIT_PATTERNS.test(err)) {
+        blockers.push({ type: "rate_limited", description: `Rate limited: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (LOGIN_PATTERNS.test(err) && !blockers.some((b) => b.type === "login_required")) {
+        blockers.push({ type: "login_required", description: `Login required: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (NETWORK_ERROR_PATTERNS.test(err)) {
+        blockers.push({ type: "network_error", description: `Network error: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (POPUP_BLOCKED_PATTERNS.test(err)) {
+        blockers.push({ type: "permission_dialog", description: `Popup blocked: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (/timed\s+out|timeout\s+(exceeded|error|after)|request\s+timeout/i.test(err) ||
+        /loading\s+(stuck|failed|error|taking)/i.test(err) ||
+        (err.includes("loading") && (err.includes("fail") || err.includes("error") || err.includes("stuck")))) {
+        blockers.push({ type: "loading_stuck", description: `Loading stuck: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+    }
+    if (err.includes("not found") || err.includes("locate_failed") || /element.*(gone|missing|disappear|not found)/i.test(err)) {
+        blockers.push({ type: "element_gone", description: `Element gone: ${failedStepError}`, bundleId: expectedBundleId, ...pidFields });
+        // 4a. selector_drift: element gone but UI controls were recently updated
+        // This means the element moved/changed rather than disappearing entirely
+        const focusedWindowId = state.focusedWindowId;
+        if (focusedWindowId !== null) {
+            const win = state.windows.get(focusedWindowId);
+            if (win && win.controls.size > 0) {
+                const FRESH_THRESHOLD = 5_000;
+                let hasFreshControls = false;
+                for (const ctrl of win.controls.values()) {
+                    if (Date.now() - new Date(ctrl.value.updatedAt).getTime() < FRESH_THRESHOLD) {
+                        hasFreshControls = true;
+                        break;
+                    }
+                }
+                if (hasFreshControls) {
+                    blockers.push({
+                        type: "selector_drift",
+                        description: `Selector drift: element not found but UI is fresh (${win.controls.size} controls)`,
+                        bundleId: expectedBundleId,
+                        ...pidFields,
+                    });
+                }
+            }
+        }
+    }
+    // 5. Fallback
+    if (blockers.length === 0) {
+        blockers.push({
+            type: "unknown_state",
+            description: `Unclassified: ${failedStepError}`,
+            bundleId: expectedBundleId,
+            ...pidFields,
+        });
+    }
+    // Deduplicate by type
+    const seen = new Set();
+    return blockers.filter((b) => {
+        if (seen.has(b.type))
+            return false;
+        seen.add(b.type);
+        return true;
+    });
+}
+function classifyDialogType(title, dialogRole) {
+    const titleLower = title.toLowerCase();
+    if (/pop-up|popup|blocked/i.test(titleLower))
+        return "permission_dialog";
+    if (PERMISSION_PATTERNS.test(titleLower))
+        return "permission_dialog";
+    if (LOGIN_PATTERNS.test(titleLower))
+        return "login_required";
+    if (CAPTCHA_PATTERNS.test(titleLower))
+        return "captcha";
+    if (CRASH_DIALOG_PATTERNS.test(titleLower))
+        return "app_crashed";
+    if (dialogRole === "alert")
+        return "unexpected_dialog";
+    return "unexpected_dialog";
+}