screenhand 0.3.2 → 0.3.4

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 {
@@ -263,84 +267,100 @@ async function ensureCDP(overridePort) {
     throw new Error("Chrome not running with --remote-debugging-port. Launch with: /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug");
 }
 const server = new McpServer({ name: "screenhand", version: "3.0.0" }, {
-    instructions: `ScreenHand gives you native desktop control on macOS/Windows. 111 tools across 7 capability tiers.
+    instructions: `ScreenHand gives you native desktop control on macOS/Windows. 111 tools. Never click blind — always follow: KNOW → SEE → NAVIGATE → ACT → VERIFY → STOP.
+
+## The Golden Sequence (follow this order)
+
+### 1. KNOW (before touching anything)
+platform_guide("figma")          → get selectors, flows, known errors for this app/site
+memory_recall("figma export")    → check if you've done this before — reuse past strategies
+scan_menu_bar()                  → discover all menu items in the current app
+
+If platform_guide() has no data: platform_explore("bundleId") to auto-discover the app, or platform_learn("domain") for websites.
+
+### 2. SEE (understand current state)
+apps()                           → what's running?
+perception_start()               → turn on continuous monitoring (3-rate: 100ms/300ms/1000ms)
+world_state()                    → current app, windows, controls, dialogs
+screenshot()                     → visual confirmation if needed
+
+perception_start() keeps world_state() continuously updated. Use it for complex multi-step workflows.
 
-## Quick Patterns
+### 3. NAVIGATE (get to the right place)
+focus("com.figma.Desktop")       → bring app to front
+ui_tree()                        → see all clickable elements with roles and labels
+ui_find("Export")                → check if a specific target exists before clicking
 
-**Click something**: ui_find("Search") → ui_press("Search") (~50ms, no screenshot needed)
-**Type text**: click target first, then type_text("hello") or key("cmd+a") for shortcuts
-**Read screen**: ui_tree() for structured elements, screenshot() + ocr() for visual content
-**Browser**: browser_navigate/browser_js/browser_click — works in background via CDP (~10ms)
-**Cross-app**: focus("com.apple.Notes") → type_text() → key("cmd+s") — chain apps freely
+### 4. ACT (do the thing)
+click_with_fallback("Export")    → click element (auto-tries AX → CDP → OCR → coordinates)
+type_with_fallback("filename")   → type text with auto-fallback
+key("cmd+shift+e")               → keyboard shortcuts
+drag(fromX, fromY, toX, toY)     → drag and drop
+scroll(direction)                → scroll up/down/left/right
 
-## When to Use Advanced Features
+Always prefer *_with_fallback tools over bare click/type — they auto-recover when one method fails.
 
-### World State & Perception (know what's on screen)
-- **perception_start()** — turn on continuous screen monitoring (3-rate: 100ms/300ms/1000ms). Use BEFORE complex multi-step workflows so you always know what's on screen.
-- **world_state()** — check current app, windows, controls, dialogs. Use to verify state before acting. Use verbose=true to see all controls.
-- **world_state_diff()** — find stale/outdated UI elements. Use after long pauses to check what changed.
-- **perception_stop()** — turn off when done to save resources.
-- Pattern: perception_start() → do work → world_state() to verify → perception_stop()
+### 5. VERIFY (confirm it worked)
+world_state()                    → did UI change as expected?
+world_state_diff()               → what exactly changed since last check?
+screenshot()                     → visual proof
 
-### Learning & Memory (get smarter over time)
-- **Learning is automatic** — every tool call teaches ScreenHand which selectors work, which fail, optimal timing per app. No action needed.
-- **memory_save(key, value)** — save a strategy or finding for future sessions (persists to disk).
-- **memory_recall(query)** — retrieve saved strategies, past errors, what worked before. ALWAYS recall before attempting unfamiliar platforms.
-- **learning_status()** — see what ScreenHand has learned: locator preferences, recovery rankings, timing budgets per app.
-- **learning_reset()** — nuclear option, clears all learning. Rarely needed.
-- Pattern: memory_recall("instagram post") → use recalled strategy → if new approach works, memory_save() it
+### 6. STOP (clean up)
+perception_stop()                → stop monitoring (save resources)
+memory_save("figma_export", ...) → save successful strategy for next time
 
-### Self-Healing & Recovery (handle errors automatically)
-- **Recovery is automatic** — when a tool fails, ScreenHand tries alternative strategies (AX → CDP → OCR → coordinates) without you doing anything.
-- **recovery_status()** — see cooldowns, active strategies, which fixes are cached.
-- **recovery_configure()** — adjust recovery budget (max time, max strategies to try).
-- ***_with_fallback tools** (click_with_fallback, type_with_fallback, etc.) — use these instead of bare click/type when reliability matters. They auto-try multiple methods.
-- Pattern: Use *_with_fallback tools for critical actions. If something still fails, check recovery_status() to understand why.
+## For Web/Browser (Chrome, Electron apps)
+browser_navigate("https://...")  → go to URL
+browser_stealth()                → activate FIRST if site has bot detection
+browser_dom()                    → read page structure (CSS selectors)
+browser_click("#submit")         → click element by CSS selector
+browser_type("input", "text")    → type into form field
+browser_fill_form({...})         → fill multiple fields at once (human-like timing)
+browser_js("return ...")         → run JavaScript for complex extraction/actions
+browser_wait("selector")         → wait for element to appear
+browser_human_click(x, y)        → human-like click with randomized timing
 
-### Platform Knowledge (know HOW to automate an app)
-- **platform_guide("figma")** — get selectors, flows, known errors for a platform. Call FIRST when automating any app/site.
-- **platform_explore("bundleId")** — auto-discover an unknown app's UI structure.
-- **platform_learn("domain")** — learn a website's structure by crawling.
-- **scan_menu_bar()** — discover all menu items in the current app.
-- Pattern: platform_guide() first → if not found, platform_explore() → then automate
+All browser tools work in the background (~10ms) — no need to focus Chrome.
 
-### Jobs & Multi-Step Workflows (survive restarts)
-- **job_create(name, steps[])** — define a multi-step workflow that persists to disk.
-- **job_run(jobId)** — execute a job. Survives MCP client restarts.
-- **worker_start()** — start background daemon that processes jobs autonomously.
-- **playbook_record()** / **export_playbook()** — record your actions into reusable playbooks.
-- Pattern: For repeatable workflows, record as playbook → export → job_create from playbook → worker_start
+## For Complex Multi-Step Tasks (let ScreenHand plan it)
+plan_goal("Export video as H.264")  → describe WHAT you want — ScreenHand generates steps from playbooks, strategies, and references
+plan_execute(goalId)                → auto-run deterministic steps, pauses at LLM steps for your judgment
+plan_step_resolve(goalId, tool, params) → you provide the tool+params for LLM steps
+plan_status(goalId)                 → check progress
+plan_cancel(goalId)                 → abort if needed
 
-### Multi-Agent Coordination (multiple AI agents sharing one machine)
-- **session_claim()** — claim exclusive access to an app window (lease-based).
-- **session_heartbeat()** — keep your lease alive.
-- **session_release()** — release when done.
-- **supervisor_start()** — background daemon that detects stalled agents and recovers.
-- Pattern: session_claim() → do work → session_heartbeat() periodically → session_release()
+On success, the strategy is auto-saved to memory for future reuse.
 
-### 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
+## For Repeatable Workflows (automate once, run forever)
+playbook_record()                → start recording your actions
+... do the work ...
+export_playbook()                → save as reusable playbook
+job_create("daily post", steps)  → make it a persistent job
+worker_start()                   → background daemon runs jobs autonomously
 
-## Tool Selection Priority
-1. **ui_tree + ui_press** for native app elements (fastest, most reliable)
-2. **browser_* tools** for web content in Chrome/Electron
-3. ***_with_fallback** when you're unsure which method will work
-4. **screenshot + ocr** only for canvas apps or visual verification
-5. **applescript** for macOS-specific automation (Finder, Mail, etc.)
+Jobs survive MCP client restarts. worker_start() runs independently.
 
-## Tips
-- Always call platform_guide() before automating a new app/site
-- Use memory_recall() before attempting something you might have done before
-- Start perception_start() for complex workflows, stop when done
-- Prefer *_with_fallback tools over bare tools for reliability
-- browser_stealth() before visiting sites with bot detection
+## For Multi-Agent Coordination
+session_claim()                  → claim exclusive access to an app window (lease-based)
+session_heartbeat()              → keep your lease alive (call periodically)
+session_release()                → release when done
+supervisor_start()               → daemon that detects stalled agents and auto-recovers
+
+## Self-Healing (automatic — no action needed)
+When any tool fails, ScreenHand automatically tries alternative strategies (AX → CDP → OCR → coordinates). Learning is also automatic — every tool call teaches which selectors work, optimal timing, and recovery rankings per app. Check with:
+- learning_status()              → see learned preferences per app
+- recovery_status()              → see active cooldowns and cached strategies
+- recovery_configure()           → tune recovery budget (max time, max retries)
+
+## Tool Speed Priority
+1. **ui_tree + ui_press** — native Accessibility API, ~50ms (fastest, most reliable)
+2. **browser_* tools** — Chrome DevTools Protocol, ~10ms (background, no focus needed)
+3. ***_with_fallback** — auto-tries multiple methods (~100-500ms)
+4. **screenshot + ocr** — visual capture, ~600ms (only for canvas apps)
+5. **applescript** — macOS scripting (Finder, Mail, Safari, etc.)
+
+## Key Rule
+Never click blind. Always: KNOW → SEE → NAVIGATE → ACT → VERIFY.
 `,
 });
 // ═══════════════════════════════════════════════
@@ -411,6 +431,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();
@@ -422,7 +453,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);
@@ -513,6 +546,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;
@@ -548,6 +595,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.
@@ -578,7 +628,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
@@ -622,7 +672,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
@@ -901,14 +951,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 ──
@@ -1266,7 +1319,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);
@@ -1422,7 +1475,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();
@@ -1528,8 +1581,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 = {
@@ -1930,7 +1983,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
@@ -2178,7 +2231,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 });
@@ -2188,7 +2241,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:"];
@@ -2212,7 +2265,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:"];
@@ -2257,7 +2310,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);
@@ -2291,7 +2344,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";
@@ -2342,7 +2395,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();
@@ -2375,7 +2428,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();
@@ -2416,7 +2469,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;
@@ -2444,7 +2497,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";
@@ -2519,7 +2572,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();
@@ -2539,7 +2592,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();
@@ -2583,7 +2636,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();
@@ -2991,7 +3044,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": {
@@ -3162,6 +3215,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",
@@ -3722,7 +3796,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" : ""}`;
@@ -3764,26 +3838,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 getAdaptedRetryPolicy() {
-    if (!currentAdaptiveBudget)
+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(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: `Failed to ${action} "${target}" — all methods exhausted. Last error: ${result.error}` }] };
+    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`);
+        }
+    }
+    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.", {
@@ -3791,10 +4000,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) {
@@ -3829,15 +4065,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") {
@@ -3872,7 +4121,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.", {
@@ -3882,9 +4131,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) {
@@ -3972,17 +4224,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)
@@ -4009,7 +4274,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.", {
@@ -4017,9 +4282,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) {
@@ -4126,14 +4397,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)
@@ -4173,11 +4455,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).", {
@@ -4185,9 +4469,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) {
@@ -4220,16 +4517,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;
@@ -4260,7 +4570,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.", {
@@ -4269,9 +4579,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) {
@@ -4301,20 +4617,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") {
@@ -4335,7 +4665,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.", {
@@ -4345,9 +4675,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 {
@@ -4383,7 +4719,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;
@@ -4401,9 +4737,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 {
@@ -4421,7 +4766,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.", {
@@ -4751,6 +5096,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
@@ -4943,6 +5290,7 @@ originalTool("plan_execute", "Run a plan automatically. Known steps (from playbo
     }
     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
@@ -5004,6 +5352,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) {
@@ -5047,6 +5396,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 {
@@ -5287,6 +5637,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 {
@@ -5768,7 +6122,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 }] };
@@ -5813,6 +6197,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.", {
@@ -5937,6 +6339,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") }] };
 });
 // ═══════════════════════════════════════════════