screenhand 0.3.1 → 0.3.3

package/dist/mcp-desktop.js

@@ -55,7 +55,7 @@ import { WorldModel } from "./src/state/index.js";
 import { PerceptionManager } from "./src/perception/index.js";
 import { Planner, PlanExecutor, GoalStore, ToolRegistry } from "./src/planner/index.js";
 import { RecoveryEngine } from "./src/recovery/index.js";
-import { LearningEngine } from "./src/learning/index.js";
+import { LearningEngine, LocatorPolicy } from "./src/learning/index.js";
 import { discoverWebElements, testWebElement, compileReference, saveExploreResult, discoverNativeElements } from "./src/platform/explorer.js";
 import { buildDocUrls, crawlPage, compileLearnResult, saveLearnResult } from "./src/platform/learner.js";
 import { AccessibilityAdapter } from "./src/runtime/accessibility-adapter.js";
@@ -234,6 +234,10 @@ let CDP = null;
 async function ensureCDP(overridePort) {
     if (!CDP)
         CDP = (await import("chrome-remote-interface")).default;
+    // Validate port range (defense in depth — Zod validates at MCP boundary, this catches internal callers)
+    if (overridePort && (overridePort < 9222 || overridePort > 9999)) {
+        throw new Error(`Invalid CDP port ${overridePort} — must be 9222-9999`);
+    }
     // If caller specified a port, use it directly (e.g. 9333 for Electron apps)
     if (overridePort) {
         try {
@@ -318,6 +322,16 @@ const server = new McpServer({ name: "screenhand", version: "3.0.0" }, {
 - **supervisor_start()** — background daemon that detects stalled agents and recovers.
 - Pattern: session_claim() → do work → session_heartbeat() periodically → session_release()
 
+### Planning (let ScreenHand figure out the steps)
+- **plan_goal("Export video as H.264")** — describe WHAT you want, ScreenHand generates a step-by-step plan. It searches playbooks, saved strategies, and reference knowledge to build the plan. Does NOT execute — returns the plan for review.
+- **plan_execute(goalId)** — run the plan automatically. Deterministic steps (known selectors/flows) run internally. Pauses at LLM steps where your judgment is needed — resolve them with plan_step_resolve().
+- **plan_step(goalId)** — execute one step at a time (for more control than plan_execute).
+- **plan_step_resolve(goalId, tool, params)** — when a plan pauses at an LLM step, YOU decide which tool and params to use. The server executes it, verifies postconditions, and advances.
+- **plan_status(goalId)** — check progress: which step you're on, what's done, what's left.
+- **plan_list()** — see all goals (active, completed, failed).
+- **plan_cancel(goalId)** — abort a goal.
+- Pattern: plan_goal("do X") → review steps → plan_execute() → resolve LLM steps as they pause → on success, strategy auto-saved to memory
+
 ## Tool Selection Priority
 1. **ui_tree + ui_press** for native app elements (fastest, most reliable)
 2. **browser_* tools** for web content in Chrome/Electron
@@ -401,6 +415,17 @@ let lastSuccessfulToolName = "unknown";
 let lastKnownBundleId = null;
 contextTracker.setAppMap(appMap);
 perceptionManager.setAppMap(appMap);
+// Wire F10: connect ContextTracker to PerceptionCoordinator for per-app perception config
+perceptionManager.setContextTracker(contextTracker);
+// Wire #11: connect TopologyPolicy to AppMap for unified edge scoring
+appMap.setTopologyPolicy(learningEngine.topology);
+// Wire #14: seed TimingModel from AppMap's stored timing profiles (cold-start bootstrap)
+learningEngine.seedTimingFromAppMap(appMap);
+// Wire F5-F7: Cold-start bootstrap — seed all learning policies from AppMap data
+learningEngine.seedLocatorsFromAppMap(appMap);
+learningEngine.seedSensorsFromReadySignals(appMap);
+learningEngine.seedPatternsFromAppMap(appMap);
+learningEngine.seedRecoveryFromContracts(appMap);
 const _executablePlaybookStore = new PlaybookStore(playbooksDir);
 try {
     _executablePlaybookStore.load();
@@ -412,7 +437,9 @@ goalStore.init();
 const toolRegistry = new ToolRegistry();
 const recoveryEngine = new RecoveryEngine(worldModel, toolRegistry.toExecutor(), memory);
 recoveryEngine.setLearningEngine(learningEngine);
+recoveryEngine.setAppMap(appMap);
 planner.setToolRegistry(toolRegistry);
+planner.setAppMap(appMap);
 perceptionManager.setLearningEngine(learningEngine);
 const mcpRecorder = new McpPlaybookRecorder(playbooksDir);
 const referenceMerger = new ReferenceMerger(referencesDir);
@@ -503,6 +530,20 @@ server.tool = (...args) => {
         perceptionManager.notifyToolCall();
         // ── PRE-CALL: check for known error warnings (~0ms, in-memory) ──
         const knownError = memory.quickErrorCheck(toolName);
+        // Wire F11: Block execution for tools that fail repeatedly with known resolution (L2→L1)
+        // Exclude playbook-seeded errors (id starts with pb_err_) — those are generic platform warnings,
+        // not errors observed in this session. Only block on real runtime failures.
+        // Also exclude errors injected via memory_record_error API (empty params) — only runtime errors
+        // from the intelligence wrapper (which always have populated params) should trigger blocks.
+        const isRuntimeError = knownError && typeof knownError.params === "object" && knownError.params !== null && Object.keys(knownError.params).length > 0;
+        if (knownError && knownError.occurrences >= 5 && knownError.resolution && !knownError.id.startsWith("pb_err_") && isRuntimeError) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `⛔ Blocked: "${toolName}" has failed ${knownError.occurrences}x with: "${knownError.error}". Known fix: ${knownError.resolution}. Apply the fix first, then retry.`,
+                    }],
+            };
+        }
         // ── PRE-CALL: auto-start perception if not running ──
         if (!perceptionManager.isRunning && bridgeReady) {
             const focusApp = worldModel.getState().focusedApp;
@@ -538,6 +579,9 @@ server.tool = (...args) => {
         else if (typeof paramBundleId === "string" && paramBundleId) {
             lastKnownBundleId = paramBundleId;
         }
+        // Snapshot the bundleId for this tool's POST-CALL, so concurrent PRE-CALL
+        // overwrites of lastKnownBundleId don't contaminate this tool's context
+        const postCallBundleId = preBundleId ?? lastKnownBundleId;
         // Capture pre-call window title for navigation edge tracking
         const preWindowTitle = worldModel.getFocusedWindow()?.title.value ?? null;
         // Action tools = actually doing something. Navigation = just clicking around.
@@ -568,7 +612,7 @@ server.tool = (...args) => {
             contextTracker.recordOutcome(toolName, safeParams, true, null);
             // ── POST-CALL: Safari context gap + page context update ──
             const postFocusApp = worldModel.getState().focusedApp;
-            const postBundleIdForCtx = postFocusApp?.bundleId ?? lastKnownBundleId;
+            const postBundleIdForCtx = postFocusApp?.bundleId ?? postCallBundleId;
             if (postBundleIdForCtx) {
                 lastKnownBundleId = postBundleIdForCtx;
                 // Try focused window first, then search all windows for matching bundleId
@@ -612,7 +656,7 @@ server.tool = (...args) => {
                 }
             }
             // ── POST-CALL: feed learning engine (timing + locator outcomes) ──
-            const learnBundleId = worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId ?? "unknown";
+            const learnBundleId = worldModel.getState().focusedApp?.bundleId ?? postCallBundleId ?? "unknown";
             learningEngine.recordToolTiming({ tool: toolName, bundleId: learnBundleId, durationMs, success: true });
             // Record locator outcome if the tool used a target/selector
             const locatorTarget = safeParams.target ?? safeParams.selector ?? safeParams.locator
@@ -891,14 +935,17 @@ server.tool = (...args) => {
                         if (fromNode !== toNode) {
                             appMap.addNavNode(learnBundleId, fromNode, { type: "window", description: fromNode });
                             appMap.addNavNode(learnBundleId, toNode, { type: "window", description: toNode });
-                            appMap.recordEdgeOutcome(learnBundleId, fromNode, locatorTarget ?? toolName, toNode, true);
+                            const locatorSlug = locatorTarget ? String(locatorTarget).slice(0, 80) : null;
+                            const edgeAction = locatorSlug ? `${toolName}:${locatorSlug}` : toolName;
+                            // Wire #11: record topology FIRST so AppMap can read the updated Bayesian score
                             learningEngine.recordTopologyOutcome({
                                 bundleId: learnBundleId,
                                 fromNode,
-                                action: locatorTarget ?? toolName,
+                                action: edgeAction,
                                 toNode,
                                 success: true,
                             });
+                            appMap.recordEdgeOutcome(learnBundleId, fromNode, edgeAction, toNode, true);
                         }
                     }
                     // ── State machine: detect state changes from tool results ──
@@ -1256,7 +1303,7 @@ server.tool = (...args) => {
             // ── Record failure for playbook learning (in-memory only) ──
             contextTracker.recordOutcome(toolName, safeParams, false, errorMsg);
             // ── Feed learning engine (failure timing + locator) ──
-            const learnBundleIdErr = worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId ?? "unknown";
+            const learnBundleIdErr = worldModel.getState().focusedApp?.bundleId ?? postCallBundleId ?? "unknown";
             learningEngine.recordToolTiming({ tool: toolName, bundleId: learnBundleIdErr, durationMs, success: false });
             const failedLocator = safeParams.target ?? safeParams.selector ?? safeParams.locator
                 ?? (toolName === "click_text" ? safeParams.text : undefined);
@@ -1412,7 +1459,7 @@ server.tool("windows", "List all visible windows with IDs, positions, and sizes"
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 server.tool("focus", "Focus/activate an application (or a specific window by windowId)", {
-    bundleId: z.string().describe("App bundle ID, e.g. com.apple.Safari"),
+    bundleId: z.string().regex(/^[a-zA-Z0-9._-]+$/, "Invalid bundleId format").describe("App bundle ID, e.g. com.apple.Safari"),
     windowId: z.number().optional().describe("Specific window ID from windows() — raises that exact window. Use when multiple instances of the same app exist."),
 }, async ({ bundleId, windowId }) => {
     await ensureBridge();
@@ -1518,8 +1565,8 @@ server.tool("focus", "Focus/activate an application (or a specific window by win
     }
 });
 server.tool("launch", "Launch an application. Chrome/Chromium browsers are launched with CDP enabled (port 9222) for browser_* tools.", {
-    bundleId: z.string().describe("App bundle ID"),
-    cdpPort: z.number().optional().describe("CDP port for Chrome/Chromium (default: 9222). Ignored for non-browser apps."),
+    bundleId: z.string().regex(/^[a-zA-Z0-9._-]+$/, "Invalid bundleId format").describe("App bundle ID"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port for Chrome/Chromium (default: 9222). Ignored for non-browser apps."),
 }, async ({ bundleId, cdpPort }) => {
     await ensureBridge();
     const riskyBundleIds = {
@@ -1920,7 +1967,7 @@ server.tool("click_text", "SLOW fallback: Find text on screen via OCR and click
 server.tool("type_text", "Type text using the keyboard. Auto-detects Electron apps and routes through CDP for reliable editor input.", {
     text: z.string().describe("Text to type"),
     pid: z.number().optional().describe("Target process ID for PID-targeted event delivery"),
-    cdpPort: z.number().optional().describe("CDP port for Electron apps (e.g. 9229). When set, types via CDP instead of AX — fixes Copilot/panel focus theft."),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port for Electron apps (e.g. 9229). When set, types via CDP instead of AX — fixes Copilot/panel focus theft."),
 }, async ({ text, pid, cdpPort: portOverride }) => {
     await ensureBridge();
     // Auto-resolve frontmost PID when none provided — global HID posting
@@ -2168,7 +2215,7 @@ function randomDelay(min, max) {
 // BROWSER — control Chrome pages via CDP (10ms, not OCR)
 // ═══════════════════════════════════════════════
 server.tool("browser_tabs", "List all open Chrome/Electron tabs. Use cdpPort to connect to a specific app (e.g. 9333 for Codex Desktop).", {
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps). Omit to auto-detect."),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps). Omit to auto-detect."),
 }, async ({ cdpPort: portOverride }) => {
     const { CDP: cdp, port } = await ensureCDP(portOverride);
     const targets = await cdp.List({ port });
@@ -2178,7 +2225,7 @@ server.tool("browser_tabs", "List all open Chrome/Electron tabs. Use cdpPort to
 });
 server.tool("browser_open", "Open a URL in Chrome/Electron (creates new tab)", {
     url: z.string().describe("URL to open"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ url, cdpPort: portOverride }) => {
     // L2-71 fix: Block dangerous URL protocols
     const BLOCKED_PROTOCOLS = ["javascript:", "data:", "blob:", "vbscript:"];
@@ -2202,7 +2249,7 @@ server.tool("browser_open", "Open a URL in Chrome/Electron (creates new tab)", {
 server.tool("browser_navigate", "Navigate the active Chrome/Electron tab to a URL", {
     url: z.string().describe("URL to navigate to"),
     tabId: z.string().optional().describe("Tab ID (from browser_tabs). Omit for most recent tab."),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ url, tabId, cdpPort: portOverride }) => {
     // L2-71 fix: Block dangerous URL protocols that could execute arbitrary code
     const BLOCKED_PROTOCOLS = ["javascript:", "data:", "blob:", "vbscript:"];
@@ -2247,7 +2294,7 @@ server.tool("browser_navigate", "Navigate the active Chrome/Electron tab to a UR
 server.tool("browser_js", "Execute JavaScript in a Chrome/Electron tab. Returns the result. WARNING: This runs arbitrary JS in the browser context — avoid on sensitive pages (banking, email). All executions are audit-logged.", {
     code: z.string().describe("JavaScript to execute. Must be an expression that returns a value. Use (() => { ... })() for multi-line."),
     tabId: z.string().optional().describe("Tab ID. Omit for most recent tab."),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ code, tabId, cdpPort: portOverride }) => {
     auditLog("browser_js", { code, tabId });
     const { CDP: cdp, port } = await ensureCDP(portOverride);
@@ -2281,7 +2328,7 @@ server.tool("browser_dom", "Query the DOM of a Chrome/Electron page. Returns mat
     selector: z.string().describe("CSS selector, e.g. 'button', '.nav a', '#main h2'"),
     tabId: z.string().optional().describe("Tab ID. Omit for most recent tab."),
     limit: z.number().optional().describe("Max results (default 20)"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ selector, tabId, limit, cdpPort: portOverride }) => {
     // Capture bundleId before any async CDP calls to avoid race condition
     const browserBundleId = worldModel.getState().focusedApp?.bundleId ?? "com.google.Chrome";
@@ -2332,7 +2379,7 @@ server.tool("browser_dom", "Query the DOM of a Chrome/Electron page. Returns mat
 server.tool("browser_click", "Click an element in Chrome/Electron by CSS selector. Uses CDP Input.dispatchMouseEvent for realistic mouse events.", {
     selector: z.string().describe("CSS selector of element to click"),
     tabId: z.string().optional().describe("Tab ID. Omit for most recent tab."),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ selector, tabId, cdpPort: portOverride }) => {
     const { client } = await getCDPClient(tabId, portOverride);
     await client.Runtime.enable();
@@ -2365,7 +2412,7 @@ server.tool("browser_type", "Type into an input field in Chrome/Electron. Uses C
     text: z.string().describe("Text to type"),
     clear: z.boolean().optional().describe("Clear field first (default true)"),
     tabId: z.string().optional().describe("Tab ID"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ selector, text, clear, tabId, cdpPort: portOverride }) => {
     const { client } = await getCDPClient(tabId, portOverride);
     await client.Runtime.enable();
@@ -2406,7 +2453,7 @@ server.tool("browser_wait", "Wait for a condition on a Chrome/Electron page", {
     condition: z.string().describe("JS expression that returns truthy when ready. e.g. 'document.querySelector(\".loaded\")'"),
     timeoutMs: z.number().optional().describe("Timeout in ms (default 10000)"),
     tabId: z.string().optional().describe("Tab ID"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ condition, timeoutMs, tabId, cdpPort: portOverride }) => {
     const { CDP: cdp, port } = await ensureCDP(portOverride);
     let targetId = tabId;
@@ -2434,7 +2481,7 @@ server.tool("browser_wait", "Wait for a condition on a Chrome/Electron page", {
 });
 server.tool("browser_page_info", "Get current page title, URL, and text content summary", {
     tabId: z.string().optional().describe("Tab ID"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ tabId, cdpPort: portOverride }) => {
     // Capture bundleId BEFORE CDP call to prevent focus-change race
     const browserBundleId = worldModel.getState().focusedApp?.bundleId ?? "com.google.Chrome";
@@ -2509,7 +2556,7 @@ if (origQuery) {
 `;
 server.tool("browser_stealth", "Inject anti-detection patches into Chrome/Electron page. Call once after navigating to a protected site. Hides webdriver flag, patches plugins/languages/permissions.", {
     tabId: z.string().optional().describe("Tab ID. Omit for most recent tab."),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ tabId, cdpPort: portOverride }) => {
     const { client } = await getCDPClient(tabId, portOverride);
     await client.Page.enable();
@@ -2529,7 +2576,7 @@ server.tool("browser_fill_form", "Fill a form field with human-like typing (anti
     clear: z.boolean().optional().describe("Clear field first (default true)"),
     delayMs: z.number().optional().describe("Avg delay between keystrokes in ms (default 50)"),
     tabId: z.string().optional().describe("Tab ID"),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ selector, text, clear, delayMs, tabId, cdpPort: portOverride }) => {
     const { client } = await getCDPClient(tabId, portOverride);
     await client.Runtime.enable();
@@ -2573,7 +2620,7 @@ server.tool("browser_fill_form", "Fill a form field with human-like typing (anti
 server.tool("browser_human_click", "Alias for browser_click — both use realistic mouseMoved → mousePressed → mouseReleased events. Prefer browser_click directly.", {
     selector: z.string().describe("CSS selector of element to click"),
     tabId: z.string().optional().describe("Tab ID. Omit for most recent tab."),
-    cdpPort: z.number().optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port override (e.g. 9333 for Electron apps)"),
 }, async ({ selector, tabId, cdpPort: portOverride }) => {
     const { client } = await getCDPClient(tabId, portOverride);
     await client.Runtime.enable();
@@ -2981,7 +3028,7 @@ server.tool("playbook_record", "Macro recorder: start recording, do the flow, st
     platform: z.string().optional().describe("Platform name (required for start)"),
     name: z.string().optional().describe("Playbook name (required for stop)"),
     description: z.string().optional().describe("Playbook description (for stop)"),
-    cdpPort: z.number().optional().describe("CDP port if needed for browser_js steps (e.g. 9333 for Codex)"),
+    cdpPort: z.number().min(9222).max(9999).optional().describe("CDP port if needed for browser_js steps (e.g. 9333 for Codex)"),
 }, async ({ action, platform, name, description, cdpPort }) => {
     switch (action) {
         case "start": {
@@ -3152,6 +3199,27 @@ server.tool("applescript", "Run an AppleScript command. For controlling Finder,
     if (process.platform === "win32") {
         return { content: [{ type: "text", text: "AppleScript is not supported on Windows. Use ui_tree, ui_press, and other accessibility tools instead." }] };
     }
+    // Block shell execution vectors in AppleScript — allowlist approach for safety-critical commands
+    const scriptLower = script.toLowerCase();
+    const BLOCKED_PATTERNS = [
+        /do\s+shell\s+script/i, // direct shell execution
+        /run\s+shell\s+script/i, // variant
+        /run\s+script/i, // dynamic AppleScript eval (can construct blocked commands)
+        /do\s+script/i, // Terminal.app shell execution
+        /«class\s/i, // raw Apple Event codes (bypass text-level blocks)
+        /system\s+events.*process/i, // process spawning via System Events
+        /NSAppleScript/i, // Objective-C bridge
+        /ObjC\.import/i, // JXA Objective-C bridge
+        /\bshell\b/i, // catch-all for shell-related commands
+        /do\s+JavaScript/i, // JXA execution
+    ];
+    if (BLOCKED_PATTERNS.some(p => p.test(script))) {
+        return { content: [{ type: "text", text: "Blocked: this AppleScript contains a restricted command (shell execution, dynamic eval, or process spawning). Use the Bash tool for shell commands." }] };
+    }
+    // Block string concatenation that could reassemble blocked commands
+    if (/&/.test(script) && (/script/i.test(script) || /shell/i.test(script))) {
+        return { content: [{ type: "text", text: "Blocked: AppleScript with string concatenation containing 'script' or 'shell' — potential bypass attempt." }] };
+    }
     try {
         const result = execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, {
             encoding: "utf-8",
@@ -3712,7 +3780,7 @@ import { METHOD_CAPABILITIES, DEFAULT_RETRY_POLICY, planExecution, executeWithFa
 server.tool("execution_plan", "Show the execution plan for an action type. Returns the ordered fallback chain based on available infrastructure.", {
     action: z.enum(["click", "type", "read", "locate", "select", "scroll"]).describe("Action type"),
 }, async ({ action }) => {
-    const plan = planExecution(action, { hasBridge: true, hasCDP: cdpPort !== null });
+    const plan = planExecution(action, { hasBridge: true, hasCDP: cdpPort !== null }, getSensorRanking());
     const lines = plan.map((method, i) => {
         const cap = METHOD_CAPABILITIES[method];
         return `${i + 1}. ${method} (~${cap.avgLatencyMs}ms)${i === 0 ? " ← primary" : ""}`;
@@ -3754,26 +3822,161 @@ function infra() {
     return { hasBridge: true, hasCDP: cdpPort !== null };
 }
 /**
- * Get a retry policy adapted by the learning engine's adaptive budgets.
- * If the learning engine shows the current app responds quickly, reduce retry delays.
+ * Get sensor rankings for the current app from the learning engine.
+ * Used by planExecution() to reorder fallback methods based on learned success rates.
+ * Returns undefined if no bundleId is known (falls back to canonical order).
+ */
+function getSensorRanking(overrideBundleId) {
+    // Use override bundleId when provided (from tool params), else worldModel, else lastKnown
+    const bundleId = overrideBundleId ?? worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId;
+    if (!bundleId)
+        return undefined;
+    const ranked = learningEngine.rankSensors(bundleId);
+    return ranked.length > 0 ? ranked : undefined;
+}
+/**
+ * Get a retry policy adapted by the learning engine's adaptive budgets
+ * AND the AppMap's timing profiles (L7→L1).
+ *
+ * Priority: AppMap timing > Learning budget > Default
+ * AppMap stores per-tool/per-action avg durations from real executions.
+ * Learning budget stores per-app adaptive budgets from outcome stats.
  */
-function getAdaptedRetryPolicy() {
-    if (!currentAdaptiveBudget)
+function getAdaptedRetryPolicy(toolName, overrideBundleId) {
+    let typicalMs = null;
+    // L7→L1: Check AppMap timing profiles for the action type.
+    // Timing keys are stored as "click::Submit", "click_text::Login", etc.
+    // Fallback tools pass "click_with_fallback" — extract the action prefix to match.
+    const bundleId = overrideBundleId ?? worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId;
+    if (bundleId && toolName) {
+        const actionPrefix = toolName.replace(/_with_fallback$/, "");
+        // Get all timing profiles for this app, then filter by action prefix
+        const allTimings = appMap.getTimingProfile(bundleId);
+        const matchingTimings = allTimings.filter((t) => t.key.startsWith(actionPrefix + "::") || t.key === actionPrefix);
+        if (matchingTimings.length > 0) {
+            // Use element_response type if available, compute median avgMs across all matching entries
+            const responseTimes = matchingTimings
+                .filter((t) => t.type === "element_response")
+                .map((t) => t.avgMs);
+            if (responseTimes.length > 0) {
+                responseTimes.sort((a, b) => a - b);
+                const mid = Math.floor(responseTimes.length / 2);
+                typicalMs = responseTimes.length % 2 === 1
+                    ? responseTimes[mid]
+                    : (responseTimes[mid - 1] + responseTimes[mid]) / 2;
+            }
+            else {
+                typicalMs = matchingTimings[0].avgMs;
+            }
+        }
+    }
+    // Fall back to L5 adaptive budget
+    if (typicalMs == null && currentAdaptiveBudget) {
+        typicalMs = Math.max(currentAdaptiveBudget.locateMs, currentAdaptiveBudget.actMs);
+    }
+    if (typicalMs == null)
         return DEFAULT_RETRY_POLICY;
-    // Use the max of locate+act as a guide for retry delay — faster apps need shorter delays
-    const typicalMs = Math.max(currentAdaptiveBudget.locateMs, currentAdaptiveBudget.actMs);
     // Retry delay = max(100ms, typical * 1.5), capped at the default
     const adaptedDelay = Math.min(DEFAULT_RETRY_POLICY.delayBetweenRetriesMs, Math.max(100, Math.ceil(typicalMs * 1.5)));
     if (adaptedDelay === DEFAULT_RETRY_POLICY.delayBetweenRetriesMs)
         return DEFAULT_RETRY_POLICY;
     return { ...DEFAULT_RETRY_POLICY, delayBetweenRetriesMs: adaptedDelay };
 }
-function formatResult(action, target, result) {
+function formatResult(action, target, result, preCheckWarnings) {
+    const prefix = preCheckWarnings && preCheckWarnings.length > 0
+        ? preCheckWarnings.join("\n") + "\n"
+        : "";
     if (result.ok) {
         const fallbackNote = result.fallbackFrom ? ` (fell back from ${result.fallbackFrom})` : "";
-        return { content: [{ type: "text", text: `${action} "${result.target ?? target}" via ${result.method}${fallbackNote} in ${result.durationMs}ms` }] };
+        return { content: [{ type: "text", text: `${prefix}${action} "${result.target ?? target}" via ${result.method}${fallbackNote} in ${result.durationMs}ms` }] };
+    }
+    return { content: [{ type: "text", text: `${prefix}Failed to ${action} "${target}" — all methods exhausted. Last error: ${result.error}` }] };
+}
+/**
+ * L3→L1: Pre-execution worldModel check.
+ * Verifies the target app is focused and not blocked by dialogs.
+ * Auto-focuses the app if it's in the background. Returns warnings
+ * that should be prepended to the result.
+ */
+async function preExecutionCheck(bundleId) {
+    const warnings = [];
+    try {
+        const state = worldModel.getState();
+        const targetBundleId = bundleId ?? lastKnownBundleId ?? state.focusedApp?.bundleId;
+        if (!targetBundleId)
+            return warnings;
+        // Check if target app is focused — use correct bridge method "app.focus"
+        if (state.focusedApp && state.focusedApp.bundleId !== targetBundleId) {
+            warnings.push(`[L3→L1] Target app ${targetBundleId} is not focused (current: ${state.focusedApp.bundleId}). Auto-focusing...`);
+            try {
+                await bridge.call("app.focus", { bundleId: targetBundleId });
+            }
+            catch {
+                warnings.push(`[L3→L1] Auto-focus failed — proceeding anyway`);
+            }
+        }
+        // Re-fetch state after auto-focus to get current focused app
+        const postFocusState = worldModel.getState();
+        // Check for blocking dialogs — scoped to target app only.
+        // Observer-sourced dialogs have windowId=0 (no real window ID),
+        // so fall back to checking if the focused app matches.
+        const relevantDialogs = postFocusState.activeDialogs.filter((d) => {
+            if (d.windowId === 0) {
+                return postFocusState.focusedApp?.bundleId === targetBundleId;
+            }
+            const win = postFocusState.windows.get(d.windowId);
+            return win?.bundleId === targetBundleId;
+        });
+        if (relevantDialogs.length > 0) {
+            const dialogTitles = relevantDialogs
+                .map((d) => d.title || d.type)
+                .join(", ");
+            warnings.push(`[L3→L1] Active dialog(s) detected: ${dialogTitles} — may block interaction`);
+        }
+        // Check if target window is off-screen
+        for (const [, win] of state.windows) {
+            if (win.bundleId === targetBundleId && !win.isOnScreen) {
+                warnings.push(`[L3→L1] Window "${win.title.value}" is off-screen or minimized`);
+            }
+        }
+        // Check if world state is stale (>10s since last update)
+        const staleThresholdMs = 10_000;
+        const lastUpdate = new Date(state.updatedAt).getTime();
+        if (!Number.isNaN(lastUpdate) && Date.now() - lastUpdate > staleThresholdMs && state.confidence < 0.5) {
+            warnings.push(`[L3→L1] World state is stale (${Math.round((Date.now() - lastUpdate) / 1000)}s old, confidence ${state.confidence.toFixed(2)}) — screen may have changed`);
+        }
     }
-    return { content: [{ type: "text", text: `Failed to ${action} "${target}" — all methods exhausted. Last error: ${result.error}` }] };
+    catch {
+        // Pre-check is best-effort advisory — never crash the tool call
+    }
+    return warnings;
+}
+/**
+ * L7→L1: Try to resolve an element's position from the AppMap.
+ * Returns known screen coordinates if the map has a position for this label
+ * AND we can get the current window bounds. Returns null otherwise.
+ */
+function resolveMapPosition(target, bundleId) {
+    const bid = bundleId ?? worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId;
+    if (!bid)
+        return null;
+    // Get window bounds from worldModel for coordinate conversion
+    const state = worldModel.getState();
+    const focusedWinId = state.focusedWindowId;
+    if (focusedWinId == null)
+        return null;
+    const win = state.windows.get(focusedWinId);
+    if (!win || win.bundleId !== bid)
+        return null;
+    const bounds = win.bounds.value;
+    // Guard: reject stale bounds (>5s old) to prevent clicking at wrong position after window move
+    const boundsAge = Date.now() - new Date(win.bounds.updatedAt).getTime();
+    if (boundsAge > 5000 || boundsAge < 0)
+        return null; // stale or future timestamp
+    // Guard: reject uninitialized/zero-size bounds to prevent clicking at (0,0)
+    if (bounds.width < 50 || bounds.height < 50)
+        return null;
+    return appMap.resolvePosition(bid, target, bounds);
 }
 // ── click_with_fallback ──
 server.tool("click_with_fallback", "Click a target by text using the canonical fallback chain: AX → CDP → OCR. Automatically retries and falls through methods.", {
@@ -3781,10 +3984,37 @@ server.tool("click_with_fallback", "Click a target by text using the canonical f
     bundleId: z.string().optional().describe("App bundle ID (for AX path)"),
 }, async ({ target, bundleId }) => {
     await ensureBridge();
-    const plan = planExecution("click", infra())
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    // L7→L1: If AppMap knows this element's position, try coordinates first.
+    // WARNING: Coordinate clicks are unverified — if the window moved or a modal
+    // appeared, the click may hit the wrong target. On failure, falls through to
+    // the standard AX/CDP/OCR chain which verifies element identity.
+    // Skip map-guided shortcut if precheck detected blocking conditions (dialogs, off-screen)
+    const hasBlockingCondition = preCheckWarnings.some((w) => w.includes("dialog") || w.includes("off-screen") || w.includes("not frontmost"));
+    const mapPos = !hasBlockingCondition ? resolveMapPosition(target, bundleId) : null;
+    if (mapPos) {
+        try {
+            const start = Date.now();
+            await bridge.call("cg.mouseClick", { x: mapPos.x, y: mapPos.y });
+            preCheckWarnings.push(`[L7→L1] Used map position (${mapPos.x}, ${mapPos.y}) for "${target}" — UNVERIFIED coordinate click`);
+            return formatResult("Clicked", target, {
+                ok: true, method: "coordinates", durationMs: Date.now() - start,
+                fallbackFrom: null, retries: 0, error: null, target: `${target} at (${mapPos.x},${mapPos.y}) [map-guided, unverified]`,
+            }, preCheckWarnings);
+        }
+        catch {
+            preCheckWarnings.push(`[L7→L1] Map position click failed — falling back to standard chain`);
+        }
+    }
+    const plan = planExecution("click", infra(), getSensorRanking())
         .filter((m) => m !== "coordinates");
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("click", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    // L2→L1: Resolve known selector from references for direct injection
+    const knownSelector = contextTracker.getSelector(target);
+    if (knownSelector) {
+        preCheckWarnings.push(`[L2→L1] Injecting known selector: ${knownSelector}`);
+    }
+    const result = await executeWithFallback("click", plan, getAdaptedRetryPolicy("click_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -3819,15 +4049,28 @@ server.tool("click_with_fallback", "Click a target by text using the canonical f
                     const client = await CDPClient({ port });
                     try {
                         const { Runtime } = client;
-                        const evalResult = await Runtime.evaluate({
-                            expression: `(() => {
-                const el = Array.from(document.querySelectorAll('*')).find(e =>
+                        // L2→L1: Try known selector first (wrapped in try/catch to handle
+                        // invalid selectors gracefully), then fall back to text search.
+                        const textSearchExpr = `Array.from(document.querySelectorAll('*')).find(e =>
                   e.textContent?.trim() === ${JSON.stringify(target)} ||
-                  e.getAttribute('aria-label') === ${JSON.stringify(target)}
-                );
+                  e.getAttribute('aria-label') === ${JSON.stringify(target)})`;
+                        const selectorExpr = knownSelector
+                            ? `(() => {
+                try {
+                  const el = document.querySelector(${JSON.stringify(knownSelector)});
+                  if (el) { el.click(); return 'clicked'; }
+                } catch(e) { /* invalid selector — fall through to text search */ }
+                const fallback = ${textSearchExpr};
+                if (fallback) { fallback.click(); return 'clicked'; }
+                return null;
+              })()`
+                            : `(() => {
+                const el = ${textSearchExpr};
                 if (el) { el.click(); return 'clicked'; }
                 return null;
-              })()`,
+              })()`;
+                        const evalResult = await Runtime.evaluate({
+                            expression: selectorExpr,
                             returnByValue: true,
                         });
                         if (evalResult.result?.value === "clicked") {
@@ -3862,7 +4105,7 @@ server.tool("click_with_fallback", "Click a target by text using the canonical f
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target };
         }
     });
-    return formatResult("Clicked", target, result);
+    return formatResult("Clicked", target, result, preCheckWarnings);
 });
 // ── type_with_fallback ──
 server.tool("type_with_fallback", "Type text into a target field using the canonical fallback chain: AX → CDP → coordinates. Finds the field by label/placeholder, focuses it, then types.", {
@@ -3872,9 +4115,12 @@ server.tool("type_with_fallback", "Type text into a target field using the canon
     clearFirst: z.boolean().optional().describe("Select-all and clear the field before typing (default: false)"),
 }, async ({ target, text, bundleId, clearFirst }) => {
     await ensureBridge();
-    const plan = planExecution("type", infra());
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    const plan = planExecution("type", infra(), getSensorRanking());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("type", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    // L2→L1: Resolve known selector for direct injection
+    const knownSelector = contextTracker.getSelector(target);
+    const result = await executeWithFallback("type", plan, getAdaptedRetryPolicy("type_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -3962,17 +4208,30 @@ server.tool("type_with_fallback", "Type text into a target field using the canon
                     const client = await CDPClient({ port });
                     try {
                         const { Runtime, DOM, Input } = client;
-                        const evalResult = await Runtime.evaluate({
-                            expression: `(() => {
-                const el = Array.from(document.querySelectorAll('input, textarea, [contenteditable]')).find(e =>
+                        // L2→L1: Try known selector first (with try/catch for invalid selectors),
+                        // then fall back to attribute search.
+                        const fieldSearchExpr = `Array.from(document.querySelectorAll('input, textarea, [contenteditable]')).find(e =>
                   e.getAttribute('placeholder') === ${JSON.stringify(target)} ||
                   e.getAttribute('aria-label') === ${JSON.stringify(target)} ||
                   e.getAttribute('name') === ${JSON.stringify(target)} ||
-                  (e.labels && Array.from(e.labels).some(l => l.textContent?.trim() === ${JSON.stringify(target)}))
-                );
+                  (e.labels && Array.from(e.labels).some(l => l.textContent?.trim() === ${JSON.stringify(target)})))`;
+                        const fieldExpr = knownSelector
+                            ? `(() => {
+                try {
+                  const el = document.querySelector(${JSON.stringify(knownSelector)});
+                  if (el) { el.focus(); return true; }
+                } catch(e) { /* invalid selector — fall through */ }
+                const fallback = ${fieldSearchExpr};
+                if (fallback) { fallback.focus(); return true; }
+                return false;
+              })()`
+                            : `(() => {
+                const el = ${fieldSearchExpr};
                 if (el) { el.focus(); return true; }
                 return false;
-              })()`,
+              })()`;
+                        const evalResult = await Runtime.evaluate({
+                            expression: fieldExpr,
                             returnByValue: true,
                         });
                         if (!evalResult.result?.value)
@@ -3999,7 +4258,7 @@ server.tool("type_with_fallback", "Type text into a target field using the canon
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target };
         }
     });
-    return formatResult("Typed into", target, result);
+    return formatResult("Typed into", target, result, preCheckWarnings);
 });
 // ── read_with_fallback ──
 server.tool("read_with_fallback", "Read text content from the screen or a specific element using the canonical fallback chain: AX → CDP → OCR. Returns the text found.", {
@@ -4007,9 +4266,15 @@ server.tool("read_with_fallback", "Read text content from the screen or a specif
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ target, bundleId }) => {
     await ensureBridge();
-    const plan = planExecution("read", infra());
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    const plan = planExecution("read", infra(), getSensorRanking());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("read", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    // L2→L1: Resolve known selector from references for direct injection
+    const knownSelector = target ? contextTracker.getSelector(target) : null;
+    if (knownSelector) {
+        preCheckWarnings.push(`[L2→L1] Injecting known selector: ${knownSelector}`);
+    }
+    const result = await executeWithFallback("read", plan, getAdaptedRetryPolicy("read_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -4116,14 +4381,25 @@ server.tool("read_with_fallback", "Read text content from the screen or a specif
                     try {
                         const { Runtime } = client;
                         if (target) {
-                            const evalResult = await Runtime.evaluate({
-                                expression: `(() => {
-                  const el = Array.from(document.querySelectorAll('*')).find(e =>
+                            // L2→L1: Try known selector first, then fall back to text search
+                            const textSearch = `Array.from(document.querySelectorAll('*')).find(e =>
                     e.getAttribute('aria-label') === ${JSON.stringify(target)} ||
-                    e.textContent?.trim() === ${JSON.stringify(target)}
-                  );
-                  return el ? (el.value ?? el.textContent ?? '').trim() : null;
-                })()`,
+                    e.textContent?.trim() === ${JSON.stringify(target)})`;
+                            const expr = knownSelector
+                                ? `(() => {
+                    try {
+                      const el = document.querySelector(${JSON.stringify(knownSelector)});
+                      if (el) return (el.value ?? el.textContent ?? '').trim();
+                    } catch(e) {}
+                    const fallback = ${textSearch};
+                    return fallback ? (fallback.value ?? fallback.textContent ?? '').trim() : null;
+                  })()`
+                                : `(() => {
+                    const el = ${textSearch};
+                    return el ? (el.value ?? el.textContent ?? '').trim() : null;
+                  })()`;
+                            const evalResult = await Runtime.evaluate({
+                                expression: expr,
                                 returnByValue: true,
                             });
                             if (evalResult.result?.value == null)
@@ -4163,11 +4439,13 @@ server.tool("read_with_fallback", "Read text content from the screen or a specif
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target: null };
         }
     });
+    // Custom format (not formatResult) — read results include content inline
+    const prefix = preCheckWarnings.length > 0 ? preCheckWarnings.join("\n") + "\n" : "";
     if (result.ok) {
         const fallbackNote = result.fallbackFrom ? ` (fell back from ${result.fallbackFrom})` : "";
-        return { content: [{ type: "text", text: `Read via ${result.method}${fallbackNote} in ${result.durationMs}ms:\n\n${result.target}` }] };
+        return { content: [{ type: "text", text: `${prefix}Read via ${result.method}${fallbackNote} in ${result.durationMs}ms:\n\n${result.target}` }] };
     }
-    return { content: [{ type: "text", text: `Failed to read${target ? ` "${target}"` : ""} — all methods exhausted. Last error: ${result.error}` }] };
+    return { content: [{ type: "text", text: `${prefix}Failed to read${target ? ` "${target}"` : ""} — all methods exhausted. Last error: ${result.error}` }] };
 });
 // ── locate_with_fallback ──
 server.tool("locate_with_fallback", "Find an element's position on screen using the canonical fallback chain: AX → CDP → OCR. Returns bounds (x, y, width, height).", {
@@ -4175,9 +4453,22 @@ server.tool("locate_with_fallback", "Find an element's position on screen using
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ target, bundleId }) => {
     await ensureBridge();
-    const plan = planExecution("locate", infra());
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    // L7→L1: If AppMap knows this element's position, return it immediately
+    const mapPos = resolveMapPosition(target, bundleId);
+    if (mapPos) {
+        // Map provides center point only — use as hint, not authoritative bounds.
+        // Fall through to full locate chain for accurate bounds.
+        preCheckWarnings.push(`[L7→L1] Map hint: "${target}" expected near (${mapPos.x}, ${mapPos.y}) — verifying via locate chain`);
+    }
+    const plan = planExecution("locate", infra(), getSensorRanking());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("locate", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    // L2→L1: Resolve known selector from references for direct injection
+    const knownSelector = contextTracker.getSelector(target);
+    if (knownSelector) {
+        preCheckWarnings.push(`[L2→L1] Injecting known selector: ${knownSelector}`);
+    }
+    const result = await executeWithFallback("locate", plan, getAdaptedRetryPolicy("locate_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -4210,16 +4501,29 @@ server.tool("locate_with_fallback", "Find an element's position on screen using
                     const client = await CDPClient({ port });
                     try {
                         const { Runtime } = client;
-                        const evalResult = await Runtime.evaluate({
-                            expression: `(() => {
-                const el = Array.from(document.querySelectorAll('*')).find(e =>
+                        // L2→L1: Try known selector first, then fall back to text search
+                        const textSearch = `Array.from(document.querySelectorAll('*')).find(e =>
                   e.textContent?.trim() === ${JSON.stringify(target)} ||
-                  e.getAttribute('aria-label') === ${JSON.stringify(target)}
-                );
-                if (!el) return null;
-                const r = el.getBoundingClientRect();
-                return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
-              })()`,
+                  e.getAttribute('aria-label') === ${JSON.stringify(target)})`;
+                        const expr = knownSelector
+                            ? `(() => {
+                  try {
+                    const el = document.querySelector(${JSON.stringify(knownSelector)});
+                    if (el) { const r = el.getBoundingClientRect(); return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) }; }
+                  } catch(e) {}
+                  const fallback = ${textSearch};
+                  if (!fallback) return null;
+                  const r = fallback.getBoundingClientRect();
+                  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+                })()`
+                            : `(() => {
+                  const el = ${textSearch};
+                  if (!el) return null;
+                  const r = el.getBoundingClientRect();
+                  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+                })()`;
+                        const evalResult = await Runtime.evaluate({
+                            expression: expr,
                             returnByValue: true,
                         });
                         const bounds = evalResult.result?.value;
@@ -4250,7 +4554,7 @@ server.tool("locate_with_fallback", "Find an element's position on screen using
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target: null };
         }
     });
-    return formatResult("Located", target, result);
+    return formatResult("Located", target, result, preCheckWarnings);
 });
 // ── select_with_fallback ──
 server.tool("select_with_fallback", "Select an option from a dropdown/menu using the canonical fallback chain: AX → CDP. Finds the control, opens it, and picks the specified option.", {
@@ -4259,9 +4563,15 @@ server.tool("select_with_fallback", "Select an option from a dropdown/menu using
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ target, option, bundleId }) => {
     await ensureBridge();
-    const plan = planExecution("select", infra());
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    const plan = planExecution("select", infra(), getSensorRanking());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("select", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    // L2→L1: Resolve known selector from references for direct injection
+    const knownSelector = contextTracker.getSelector(target);
+    if (knownSelector) {
+        preCheckWarnings.push(`[L2→L1] Injecting known selector: ${knownSelector}`);
+    }
+    const result = await executeWithFallback("select", plan, getAdaptedRetryPolicy("select_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -4291,20 +4601,34 @@ server.tool("select_with_fallback", "Select an option from a dropdown/menu using
                     const client = await CDPClient({ port });
                     try {
                         const { Runtime } = client;
-                        const evalResult = await Runtime.evaluate({
-                            expression: `(() => {
-                const sel = Array.from(document.querySelectorAll('select')).find(s =>
+                        // L2→L1: Try known selector first for the select element
+                        const textSearch = `Array.from(document.querySelectorAll('select')).find(s =>
                   s.getAttribute('aria-label') === ${JSON.stringify(target)} ||
                   s.getAttribute('name') === ${JSON.stringify(target)} ||
-                  (s.labels && Array.from(s.labels).some(l => l.textContent?.trim() === ${JSON.stringify(target)}))
-                );
-                if (!sel) return null;
-                const opt = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
-                if (!opt) return 'no_option';
-                sel.value = opt.value;
-                sel.dispatchEvent(new Event('change', { bubbles: true }));
-                return 'selected';
-              })()`,
+                  (s.labels && Array.from(s.labels).some(l => l.textContent?.trim() === ${JSON.stringify(target)})))`;
+                        const selectExpr = knownSelector
+                            ? `(() => {
+                  let sel = null;
+                  try { sel = document.querySelector(${JSON.stringify(knownSelector)}); } catch(e) {}
+                  if (!sel || sel.tagName !== 'SELECT') sel = ${textSearch};
+                  if (!sel) return null;
+                  const opt = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
+                  if (!opt) return 'no_option';
+                  sel.value = opt.value;
+                  sel.dispatchEvent(new Event('change', { bubbles: true }));
+                  return 'selected';
+                })()`
+                            : `(() => {
+                  const sel = ${textSearch};
+                  if (!sel) return null;
+                  const opt = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
+                  if (!opt) return 'no_option';
+                  sel.value = opt.value;
+                  sel.dispatchEvent(new Event('change', { bubbles: true }));
+                  return 'selected';
+                })()`;
+                        const evalResult = await Runtime.evaluate({
+                            expression: selectExpr,
                             returnByValue: true,
                         });
                         if (evalResult.result?.value === "selected") {
@@ -4325,7 +4649,7 @@ server.tool("select_with_fallback", "Select an option from a dropdown/menu using
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target: null };
         }
     });
-    return formatResult("Selected", `${target} → ${option}`, result);
+    return formatResult("Selected", `${target} → ${option}`, result, preCheckWarnings);
 });
 // ── scroll_with_fallback ──
 server.tool("scroll_with_fallback", "Scroll within an element or the active window using the canonical fallback chain: AX → CDP → coordinates. Scrolls until target text is visible, or by a fixed amount.", {
@@ -4335,9 +4659,15 @@ server.tool("scroll_with_fallback", "Scroll within an element or the active wind
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ direction, amount, target, bundleId }) => {
     await ensureBridge();
-    const plan = planExecution("scroll", infra());
+    const preCheckWarnings = await preExecutionCheck(bundleId);
+    const plan = planExecution("scroll", infra(), getSensorRanking());
     const targetPid = await resolvePid(bundleId);
     const scrollAmount = amount ?? 300;
+    // L2→L1: Resolve known selector from references for scroll container
+    const knownSelector = target ? contextTracker.getSelector(target) : null;
+    if (knownSelector) {
+        preCheckWarnings.push(`[L2→L1] Injecting known selector: ${knownSelector}`);
+    }
     // Resolve scroll coordinates — center of the frontmost window
     let scrollX = 400, scrollY = 400;
     try {
@@ -4373,7 +4703,7 @@ server.tool("scroll_with_fallback", "Scroll within an element or the active wind
         return { content: [{ type: "text", text: `Scrolled ${direction} 10 times but "${target}" not found.` }] };
     }
     // Fixed-amount scroll via fallback chain
-    const result = await executeWithFallback("scroll", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
+    const result = await executeWithFallback("scroll", plan, getAdaptedRetryPolicy("scroll_with_fallback"), async (method, attempt) => {
         const start = Date.now();
         try {
             const deltaX = direction === "left" ? -scrollAmount : direction === "right" ? scrollAmount : 0;
@@ -4391,9 +4721,18 @@ server.tool("scroll_with_fallback", "Scroll within an element or the active wind
                     const client = await CDPClient({ port });
                     try {
                         const { Runtime } = client;
-                        await Runtime.evaluate({
-                            expression: `window.scrollBy(${deltaX}, ${deltaY})`,
-                        });
+                        // L2→L1: Try scrolling known selector container first
+                        const scrollExpr = knownSelector
+                            ? `(() => {
+                  try {
+                    const el = document.querySelector(${JSON.stringify(knownSelector)});
+                    if (el) { el.scrollBy(${deltaX}, ${deltaY}); return 'scrolled'; }
+                  } catch(e) {}
+                  window.scrollBy(${deltaX}, ${deltaY});
+                  return 'scrolled';
+                })()`
+                            : `window.scrollBy(${deltaX}, ${deltaY})`;
+                        await Runtime.evaluate({ expression: scrollExpr });
                         return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: `${direction} ${scrollAmount}px` };
                     }
                     finally {
@@ -4411,7 +4750,7 @@ server.tool("scroll_with_fallback", "Scroll within an element or the active wind
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target: null };
         }
     });
-    return formatResult("Scrolled", `${direction} ${scrollAmount}px`, result);
+    return formatResult("Scrolled", `${direction} ${scrollAmount}px`, result, preCheckWarnings);
 });
 // ── wait_for_state ──
 server.tool("wait_for_state", "Wait until a condition is met on screen: text appears, text disappears, or element becomes available. Polls at intervals using the fallback chain.", {
@@ -4741,6 +5080,8 @@ function getJobRunner() {
         const locCache = new LocatorCache();
         locCache.setLearningEngine(learningEngine);
         const runtimeService = new AutomationRuntimeService(adapter, logger, locCache);
+        // Wire #15: connect AppMap to Executor for skip-verify optimization
+        runtimeService.setAppMap(appMap);
         const playbookEngine = new PlaybookEngine(runtimeService);
         activePlaybookEngine = playbookEngine;
         // Wire CDP into playbook engine for browser_js / cdp_key_event steps
@@ -4889,7 +5230,7 @@ originalTool("worker_status", "Get the current status of the worker daemon (read
 // ═══════════════════════════════════════════════
 // PLANNER — goal-oriented planning
 // ═══════════════════════════════════════════════
-originalTool("plan_goal", "Create a goal and generate an execution plan. Returns the plan source (playbook/strategy/llm), steps, and confidence. Does NOT execute — use the returned plan for review or pass to job system.", {
+originalTool("plan_goal", "Describe WHAT you want to achieve — ScreenHand builds a step-by-step plan by searching playbooks, saved strategies, and platform references. Returns steps with confidence scores. Does NOT execute — review the plan, then use plan_execute() or plan_step() to run it. Use for complex multi-step workflows instead of figuring out each step yourself.", {
     goal: z.string().describe("What you want to achieve (e.g. 'Export Premiere Pro timeline as H.264')"),
 }, async ({ goal: goalDescription }) => {
     const goal = planner.createGoal(goalDescription);
@@ -4924,7 +5265,7 @@ originalTool("plan_goal", "Create a goal and generate an execution plan. Returns
         _meta: { goalId: goal.id, plan },
     };
 });
-originalTool("plan_execute", "Execute a goal's plan automatically. Runs deterministic steps internally. Pauses at LLM steps and returns the step description for you to resolve with plan_step_resolve. On completion, saves the strategy to memory for future reuse.", {
+originalTool("plan_execute", "Run a plan automatically. Known steps (from playbooks/references) execute internally at full speed. Pauses at LLM steps where YOUR judgment is needed — call plan_step_resolve() to provide the tool+params. On completion, the successful strategy is auto-saved to memory for future reuse.", {
     goalId: z.string().describe("Goal ID from plan_goal"),
 }, async ({ goalId }) => {
     const goal = goalStore.get(goalId);
@@ -4933,6 +5274,7 @@ originalTool("plan_execute", "Execute a goal's plan automatically. Runs determin
     }
     const adaptiveBudget = learningEngine.getAdaptiveBudget(worldModel.getState().focusedApp?.bundleId ?? "unknown");
     const executor = new PlanExecutor(worldModel, planner, toolRegistry.toExecutor(), { postconditionWaitMs: adaptiveBudget.verifyMs, defaultStepTimeout: Math.max(30_000, adaptiveBudget.actMs * 2) }, recoveryEngine, learningEngine);
+    executor.setAppMap(appMap);
     const result = await executor.executeGoal(goal);
     goalStore.update(goalId, goal);
     // Check if paused at an LLM step
@@ -4994,6 +5336,7 @@ originalTool("plan_step", "Execute the next single step of a goal. For increment
     }
     const adaptiveBudget = learningEngine.getAdaptiveBudget(worldModel.getState().focusedApp?.bundleId ?? "unknown");
     const executor = new PlanExecutor(worldModel, planner, toolRegistry.toExecutor(), { postconditionWaitMs: adaptiveBudget.verifyMs, defaultStepTimeout: Math.max(30_000, adaptiveBudget.actMs * 2) }, recoveryEngine, learningEngine);
+    executor.setAppMap(appMap);
     const result = await executor.executeNextStep(goal);
     goalStore.update(goalId, goal);
     if ("paused" in result) {
@@ -5037,6 +5380,7 @@ originalTool("plan_step_resolve", "Resolve a paused LLM step by providing the to
     }
     const adaptiveBudget = learningEngine.getAdaptiveBudget(worldModel.getState().focusedApp?.bundleId ?? "unknown");
     const executor = new PlanExecutor(worldModel, planner, toolRegistry.toExecutor(), { postconditionWaitMs: adaptiveBudget.verifyMs, defaultStepTimeout: Math.max(30_000, adaptiveBudget.actMs * 2) }, recoveryEngine, learningEngine);
+    executor.setAppMap(appMap);
     const result = await executor.resolveStep(goal, tool, params ?? {});
     goalStore.update(goalId, goal);
     return {
@@ -5277,6 +5621,10 @@ originalTool("perception_start", "Start continuous screen monitoring — ScreenH
         return { content: [{ type: "text", text: `Perception already running (started ${stats.startedAt}). Use perception_stop first to restart, or pass bundleId to switch target.` }] };
     }
     let app = worldModel.getState().focusedApp;
+    // Validate bundleId format before it touches AppleScript/exec
+    if (overrideBundleId && !/^[a-zA-Z0-9._-]+$/.test(overrideBundleId)) {
+        return { content: [{ type: "text", text: "Error: Invalid bundleId format. Only alphanumeric characters, dots, hyphens, and underscores are allowed." }] };
+    }
     // If bundleId override provided, try to resolve app info via bridge or AppleScript
     if (overrideBundleId && (!app || app.bundleId !== overrideBundleId)) {
         try {
@@ -5758,7 +6106,37 @@ server.tool("scan_menu_bar", "Scan an app's menu bar via AX tree. Extracts all m
         safePath = safePath.replace(/Log Out [^\n:]+/g, "Log Out [USER]");
         lines.push(`  ${safePath}: ${keys}`);
     }
-    let output = lines.join("\n");
+    // Wire #12: L6→L7 — bootstrap AppMap zones from menu scan
+    let bootstrapInfo = "";
+    if (appMap) {
+        const bootstrapped = appMap.bootstrapFromMenuScan(bundleId, appName, result);
+        // Clear hint unconditionally — the scan was attempted regardless of bootstrap outcome
+        contextTracker.clearMenuScanHint();
+        if (bootstrapped) {
+            bootstrapInfo = `\nAppMap: bootstrapped zones from menu structure (new app)`;
+        }
+    }
+    // Wire F8: Seed learning from menu scan shortcuts (L6→L5)
+    // Use successCount=5 and score=0.6 so seeds pass recommend() thresholds
+    // (minSamples=5 for locators, score > 0.5 for patterns)
+    if (learningEngine && result.shortcuts) {
+        for (const [menuPath, keys] of Object.entries(result.shortcuts)) {
+            const key = LocatorPolicy.makeKey(bundleId, "key");
+            learningEngine.locators.seedEntry({
+                key, locator: keys, method: "ax",
+                successCount: 5, failCount: 0, score: 0.6,
+                lastUsed: new Date().toISOString(),
+            });
+            // Also seed as pattern: menu_click with the menu path
+            learningEngine.patterns.seedEntry({
+                key: `${bundleId}::menu_click::${menuPath}`,
+                bundleId, tool: "menu_click", locator: menuPath,
+                method: "ax", successCount: 3, failCount: 0, score: 0.6,
+                lastSeen: new Date().toISOString(),
+            });
+        }
+    }
+    let output = lines.join("\n") + bootstrapInfo;
     output = redactUsername(output);
     output = output.replace(/Log Out [^\n:]+/g, "Log Out [USER]");
     return { content: [{ type: "text", text: output }] };
@@ -5803,6 +6181,24 @@ server.tool("ingest_documentation", "Parse a documentation page (HTML, markdown,
             lines.push(`  - ${t}`);
         }
     }
+    // Wire F8: Seed learning from ingested documentation flows (L6→L5)
+    if (learningEngine && result.flows) {
+        for (const flow of result.flows) {
+            for (const step of flow.steps) {
+                if (!step.tool)
+                    continue;
+                const target = (step.params?.text ?? step.params?.title ?? step.params?.target ?? step.description);
+                if (target) {
+                    learningEngine.patterns.seedEntry({
+                        key: `${bundleId}::${step.tool}::${target}`,
+                        bundleId, tool: step.tool, locator: String(target),
+                        method: "ax", successCount: 3, failCount: 0, score: 0.6,
+                        lastSeen: new Date().toISOString(),
+                    });
+                }
+            }
+        }
+    }
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 server.tool("ingest_tutorial", "Extract structured playbook steps from a video transcript (e.g. YouTube captions). Converts tutorial narration into actionable automation steps with tool mappings.", {
@@ -5927,6 +6323,14 @@ originalTool("community_fetch", "Search community playbooks for a platform or wo
         lines.push(`    Score: ${pb.ratings.score} | By: ${pb.metadata.author}`);
         lines.push("");
     }
+    // Wire F9: Import community playbooks into AppMap (L6→L7)
+    if (appMap) {
+        for (const pb of results) {
+            if (pb.bundleId && pb.steps.length > 0) {
+                appMap.importFromPlaybook(pb.bundleId, pb.name, pb.steps);
+            }
+        }
+    }
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // ═══════════════════════════════════════════════