screenhand 0.2.0 → 0.3.0

package/dist/mcp-desktop.js

@@ -34,10 +34,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
+import { execSync, exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
 import fs from "node:fs";
 import { BridgeClient } from "./src/native/bridge-client.js";
 import { writeFileAtomicSync, readJsonWithRecovery } from "./src/util/atomic-write.js";
+import { sanitizeUrl, redactSensitiveLabel, redactUsername, redactPII } from "./src/util/sanitize.js";
 import { MemoryService } from "./src/memory/service.js";
 import { backgroundResearch } from "./src/memory/research.js";
 import { SessionSupervisor, LeaseManager } from "./src/supervisor/supervisor.js";
@@ -46,11 +49,30 @@ import { JobRunner } from "./src/jobs/runner.js";
 import { getWorkerLiveStatus, getWorkerDaemonPid, WORKER_LOG_FILE } from "./src/jobs/worker.js";
 import { PlaybookEngine } from "./src/playbook/engine.js";
 import { PlaybookStore } from "./src/playbook/store.js";
+import { ContextTracker } from "./src/context-tracker.js";
+import { McpPlaybookRecorder } from "./src/playbook/mcp-recorder.js";
+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 { 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";
 import { AutomationRuntimeService } from "./src/runtime/service.js";
+import { LocatorCache } from "./src/runtime/locator-cache.js";
 import { TimelineLogger } from "./src/logging/timeline-logger.js";
+import { readObserverState, getObserverDaemonPid, submitObserverCommand, getObserverCommand } from "./src/observer/state.js";
+import { OBSERVER_LOG_FILE } from "./src/observer/types.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
+import { MenuScanner } from "./src/ingestion/menu-scanner.js";
+import { DocParser } from "./src/ingestion/doc-parser.js";
+import { TutorialExtractor } from "./src/ingestion/tutorial-extractor.js";
+import { CoverageAuditor } from "./src/ingestion/coverage-auditor.js";
+import { ReferenceMerger } from "./src/ingestion/reference-merger.js";
+import { PlaybookPublisher } from "./src/community/publisher.js";
+import { PlaybookFetcher } from "./src/community/fetcher.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // ── Audit logging for dangerous tools ──
 const AUDIT_LOG_PATH = path.resolve(__dirname, ".audit-log.jsonl");
@@ -73,18 +95,155 @@ const bridgePath = process.platform === "win32"
     : path.resolve(__dirname, "native/macos-bridge/.build/release/macos-bridge");
 const bridge = new BridgeClient(bridgePath);
 let bridgeReady = false;
+// Focus mutex — only one focus() call runs at a time since only one app can be frontmost.
+// Prevents N concurrent focus calls from generating N*5 bridge calls that overwhelm the bridge.
+let focusLock = Promise.resolve();
 async function ensureBridge() {
     if (!bridgeReady) {
         await bridge.start();
         bridgeReady = true;
+        perceptionManager.createSources(bridge);
     }
 }
+/** Window titles that indicate auxiliary/utility windows — deprioritize these */
+const AUXILIARY_WINDOW_TITLES = new Set([
+    "Privacy Report", "Downloads", "Extensions", "Bookmarks",
+    "History", "Preferences", "Settings", "Web Inspector",
+]);
+/**
+ * L3-04 fix: Check if a PID is running — checks app.list first, then falls back to
+ * app.frontmost and window list. Some Electron apps (Slack, Discord) don't appear in
+ * NSWorkspace.runningApplications but are visible via CGWindowList and frontmost checks.
+ */
+async function isPidRunning(pid) {
+    try {
+        const apps = await bridge.call("app.list", {});
+        if (apps?.some((a) => a.pid === pid))
+            return true;
+    }
+    catch { /* ignore */ }
+    // Fallback 1: check frontmost
+    try {
+        const front = await bridge.call("app.frontmost", {});
+        if (front.pid === pid)
+            return true;
+    }
+    catch { /* ignore */ }
+    // Fallback 2: check window list
+    try {
+        const wins = await bridge.call("app.windows");
+        if (wins?.some((w) => (w.pid || w.ownerPid) === pid))
+            return true;
+    }
+    catch { /* ignore */ }
+    return false;
+}
+/** Resolve the native windowId for a given PID via the AX bridge. */
+async function resolveWindowId(pid) {
+    // Prefer AX-enriched window.list — returns focused/isMain fields from AX API
+    try {
+        const wins = await bridge.call("window.list", {});
+        const matching = wins?.filter((w) => w.pid === pid);
+        if (matching && matching.length > 0) {
+            // Filter out auxiliary windows (Privacy Report, Downloads, etc.)
+            const contentWindows = matching.filter((w) => !AUXILIARY_WINDOW_TITLES.has(w.title) && w.subrole !== "AXFloatingWindow");
+            const candidates = contentWindows.length > 0 ? contentWindows : matching;
+            // Prefer focused > isMain > first content window
+            const focused = candidates.find((w) => w.focused);
+            if (focused?.windowId != null)
+                return focused.windowId;
+            const main = candidates.find((w) => w.isMain);
+            if (main?.windowId != null)
+                return main.windowId;
+            const win = candidates[0];
+            if (win?.windowId != null)
+                return win.windowId;
+        }
+    }
+    catch { /* fall through */ }
+    try {
+        // Fallback to CG-based app.windows (no focused/isMain, may crash on GPU-heavy windows)
+        const wins = await bridge.call("app.windows");
+        const matching = wins?.filter((w) => w.pid === pid);
+        if (matching && matching.length > 0) {
+            // Still filter auxiliary windows even in fallback path
+            const content = matching.filter((w) => !AUXILIARY_WINDOW_TITLES.has(w.title));
+            const win = content.length > 0 ? content[0] : matching[0];
+            if (win?.windowId != null)
+                return win.windowId;
+        }
+    }
+    catch { /* ignore */ }
+    return undefined;
+}
+/** Check if the focused app is a browser — used to enable safeCLI capture mode */
+function isBrowserApp() {
+    const bundleId = worldModel.getState().focusedApp?.bundleId ?? "";
+    return /^com\.(apple\.Safari|google\.Chrome|microsoft\.edgemac)$|^org\.mozilla\.firefox$/.test(bundleId);
+}
+/**
+ * Install async Safari browser enricher on the perception coordinator.
+ * Non-blocking — uses async exec instead of execSync.
+ * Only installs if bundleId is Safari; clears enricher otherwise.
+ */
+function installSafariEnricher(bundleId) {
+    const coord = perceptionManager.getCoordinator();
+    if (!coord)
+        return;
+    if (bundleId !== "com.apple.Safari") {
+        coord.setBrowserEnricher(null);
+        return;
+    }
+    coord.setBrowserEnricher(async () => {
+        const script = `tell application "Safari"
+  set t to current tab of front window
+  set tabInfo to name of t & "|" & URL of t
+  set tabList to ""
+  set tabIdx to 1
+  repeat with w in windows
+    repeat with tb in tabs of w
+      set isActive to (tb = current tab of w) as string
+      set tabList to tabList & tabIdx & "|" & name of tb & "|" & URL of tb & "|" & isActive & "\\n"
+      set tabIdx to tabIdx + 1
+    end repeat
+  end repeat
+  return tabInfo & "\\n---\\n" & tabList
+end tell`;
+        const { stdout } = await execAsync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        const result = (stdout ?? "").trim();
+        if (result) {
+            const [currentLine, , ...tabLines] = result.split("\n");
+            const [title, url] = (currentLine ?? "").split("|");
+            const tabs = tabLines
+                .filter((l) => l.includes("|"))
+                .map((l) => {
+                const [idx, tTitle, tUrl, active] = l.split("|");
+                return { index: parseInt(idx ?? "0", 10), title: tTitle ?? "", url: tUrl ?? "", isActive: active === "true" };
+            });
+            if (url)
+                worldModel.ingestSafariBrowserState(url, title ?? "", tabs.length > 0 ? tabs : undefined);
+        }
+    });
+}
 // CDP connection cache
 let cdpPort = null;
 let CDP = null;
-async function ensureCDP() {
+async function ensureCDP(overridePort) {
     if (!CDP)
         CDP = (await import("chrome-remote-interface")).default;
+    // If caller specified a port, use it directly (e.g. 9333 for Electron apps)
+    if (overridePort) {
+        try {
+            await CDP.Version({ port: overridePort });
+            return { CDP, port: overridePort };
+        }
+        catch {
+            throw new Error(`CDP not available on port ${overridePort}. Ensure the app is running with --remote-debugging-port=${overridePort}`);
+        }
+    }
     if (cdpPort) {
         try {
             await CDP.Version({ port: cdpPort });
@@ -92,8 +251,8 @@ async function ensureCDP() {
         }
         catch { }
     }
-    // Try common ports
-    for (const p of [9222, 9223, 9224]) {
+    // Try common ports (9222-9224 = Chrome, 9333 = Codex desktop)
+    for (const p of [9222, 9223, 9224, 9333]) {
         try {
             await CDP.Version({ port: p });
             cdpPort = p;
@@ -103,7 +262,7 @@ async function ensureCDP() {
     }
     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: "2.0.0" });
+const server = new McpServer({ name: "screenhand", version: "3.0.0" });
 // ═══════════════════════════════════════════════
 // LEARNING MEMORY — cached, auto-recall, non-blocking
 // ═══════════════════════════════════════════════
@@ -118,7 +277,82 @@ jobManager.init();
 // Direct lease manager that shares the filesystem lock dir with the daemon
 const LOCK_DIR = path.join(os.homedir(), ".screenhand", "locks");
 const leaseManager = new LeaseManager(LOCK_DIR);
-// Skip logging for memory tools themselves
+// ── Context tracker — connects tool execution to playbook knowledge ──
+// References dir holds curated platform knowledge (selectors, flows, errors)
+// Playbooks dir holds only executable step sequences for job_create
+// Resolution order: local dev paths → npm dist paths → ~/.screenhand/ user paths
+function resolveDataDir(name) {
+    // 1. Local dev path (when running from source)
+    const local = path.resolve(__dirname, name);
+    if (fs.existsSync(local) && fs.readdirSync(local).some(f => f.endsWith(".json"))) {
+        return local;
+    }
+    // 2. npm dist path (when installed via npx/npm)
+    const dist = path.resolve(__dirname, `dist-${name}`);
+    if (fs.existsSync(dist) && fs.readdirSync(dist).some(f => f.endsWith(".json"))) {
+        return dist;
+    }
+    // 3. User home path (always available for user-generated content)
+    const userDir = path.join(os.homedir(), ".screenhand", name);
+    if (!fs.existsSync(userDir)) {
+        fs.mkdirSync(userDir, { recursive: true });
+    }
+    return userDir;
+}
+const referencesDir = resolveDataDir("references");
+const _playbookStoreForContext = new PlaybookStore(referencesDir);
+_playbookStoreForContext.load();
+const playbooksDir = resolveDataDir("playbooks");
+const contextTracker = new ContextTracker(_playbookStoreForContext, playbooksDir);
+const worldModel = new WorldModel();
+const perceptionManager = new PerceptionManager(worldModel);
+const learningEngine = new LearningEngine();
+learningEngine.init();
+import { AppMap } from "./src/state/app-map.js";
+// Seed app maps: check npm dist path first, then local dev path
+const seedAppMapsDir = (() => {
+    const dist = path.resolve(__dirname, "dist-app-maps");
+    if (fs.existsSync(dist))
+        return dist;
+    const local = path.resolve(__dirname, "seed-app-maps");
+    if (fs.existsSync(local))
+        return local;
+    return undefined;
+})();
+const appMap = new AppMap(seedAppMapsDir ? { seedDir: seedAppMapsDir } : undefined);
+appMap.init();
+// Cross-feature workflow tracking: per-app buffer of distinct features hit by action tools
+const crossFeatureBuffer = new Map();
+// Visibility tracking throttle: run conditional UI check every 10th tool call
+let visibilityCheckCounter = 0;
+// Previous tool name for ready-signal recording (what action preceded a wait)
+let lastSuccessfulToolName = "unknown";
+// Last known bundleId — survives focusedApp being nulled by app_deactivated events
+let lastKnownBundleId = null;
+contextTracker.setAppMap(appMap);
+perceptionManager.setAppMap(appMap);
+const _executablePlaybookStore = new PlaybookStore(playbooksDir);
+try {
+    _executablePlaybookStore.load();
+}
+catch { /* dir may not exist */ }
+const planner = new Planner(_executablePlaybookStore, memory, contextTracker, worldModel, learningEngine);
+const goalStore = new GoalStore(path.join(os.homedir(), ".screenhand", "planner"));
+goalStore.init();
+const toolRegistry = new ToolRegistry();
+const recoveryEngine = new RecoveryEngine(worldModel, toolRegistry.toExecutor(), memory);
+recoveryEngine.setLearningEngine(learningEngine);
+planner.setToolRegistry(toolRegistry);
+perceptionManager.setLearningEngine(learningEngine);
+const mcpRecorder = new McpPlaybookRecorder(playbooksDir);
+const referenceMerger = new ReferenceMerger(referencesDir);
+const communityPublisher = new PlaybookPublisher();
+const communityFetcher = new PlaybookFetcher();
+// Tools excluded from the intelligence wrapper (memory/context hints).
+// Memory, supervisor, job, and daemon lifecycle tools skip the wrapper to avoid recursion
+// and because they don't benefit from playbook hints.
+// NOTE: platform knowledge tools (platform_guide, playbook_preflight, export_playbook)
+// are NOT excluded — they benefit from context-aware hints.
 const MEMORY_TOOLS = new Set([
     "memory_snapshot", "memory_recall", "memory_save", "memory_record_error",
     "memory_record_learning", "memory_query_patterns", "memory_errors",
@@ -131,19 +365,49 @@ const MEMORY_TOOLS = new Set([
     "job_step_done", "job_step_fail", "job_resume", "job_dequeue", "job_remove",
     "job_run", "job_run_all",
     "worker_start", "worker_stop", "worker_status",
+    "job_create_chain",
+    "observer_start", "observer_stop", "observer_status", "observer_ocr_roi",
+    "orchestrator_start", "orchestrator_stop", "orchestrator_submit", "orchestrator_status",
+    "world_state", "world_state_diff", "perception_status", "perception_start", "perception_stop",
+    "learning_status", "learning_reset",
+    "plan_goal", "plan_execute", "plan_step", "plan_step_resolve", "plan_status", "plan_list", "plan_cancel",
+    "recovery_status", "recovery_configure",
+    "community_publish", "community_fetch",
 ]);
 // Track the strategy we're currently following (for feedback loop)
 let activeStrategyFingerprint = null;
+let currentAdaptiveBudget = null;
 // Intercept all tool registrations to auto-log + auto-recall
-const originalTool = server.tool.bind(server);
+const _rawOriginalTool = server.tool.bind(server);
+// Wrap originalTool to also register handlers in the tool registry
+const originalTool = ((...args) => {
+    const handlerIdx = args.findIndex((a) => typeof a === "function");
+    if (handlerIdx !== -1) {
+        const name = args[0];
+        const handler = args[handlerIdx];
+        // Wrap handler to ensure world model session rebinding (same as server.tool wrapper)
+        const wrappedHandler = async (params, extra) => {
+            const sessionId = memory.getSessionId();
+            if (sessionId && worldModel.getState().sessionId !== sessionId) {
+                worldModel.init(sessionId);
+            }
+            return handler(params, extra);
+        };
+        args[handlerIdx] = wrappedHandler;
+        toolRegistry.register(name, (params) => handler(params, {}));
+    }
+    return _rawOriginalTool(...args);
+});
 function extractText(result) {
     if (!result?.content)
         return "";
-    return result.content
+    const full = result.content
         .filter((c) => c.type === "text")
         .map((c) => c.text)
-        .join("\n")
-        .slice(0, 500);
+        .join("\n");
+    if (full.length > 500)
+        return full.slice(0, 500) + " [TRUNCATED]";
+    return full;
 }
 server.tool = (...args) => {
     const handlerIdx = args.findIndex((a) => typeof a === "function");
@@ -151,6 +415,8 @@ server.tool = (...args) => {
         return originalTool(...args);
     const originalHandler = args[handlerIdx];
     const toolName = args[0];
+    // Register the original (unwrapped) handler for internal tool dispatch
+    toolRegistry.register(toolName, (params) => originalHandler(params, {}));
     const wrappedHandler = async (params, extra) => {
         // Skip intercepting memory tools to avoid recursion
         if (MEMORY_TOOLS.has(toolName)) {
@@ -159,8 +425,59 @@ server.tool = (...args) => {
         const sessionId = memory.getSessionId();
         const safeParams = typeof params === "object" && params !== null ? params : {};
         const start = Date.now();
+        // ── PRE-CALL: lazy-init world model on first session ──
+        if (sessionId && worldModel.getState().sessionId !== sessionId) {
+            worldModel.init(sessionId);
+        }
+        // ── PRE-CALL: notify perception to stay active (idle gating) ──
+        perceptionManager.notifyToolCall();
         // ── PRE-CALL: check for known error warnings (~0ms, in-memory) ──
         const knownError = memory.quickErrorCheck(toolName);
+        // ── PRE-CALL: auto-start perception if not running ──
+        if (!perceptionManager.isRunning && bridgeReady) {
+            const focusApp = worldModel.getState().focusedApp;
+            if (focusApp?.bundleId && focusApp?.pid) {
+                perceptionManager.tryAutoStart(focusApp, bridge).catch(() => { });
+                installSafariEnricher(focusApp.bundleId);
+            }
+        }
+        // ── PRE-CALL: update context tracker (fires playbook lookup only on domain change) ──
+        contextTracker.updateContext(toolName, safeParams);
+        const playbookHints = contextTracker.getHints(toolName, safeParams);
+        // ── PRE-CALL: compute adaptive budget from learning engine ──
+        const budgetBundleId = worldModel.getState().focusedApp?.bundleId;
+        if (budgetBundleId) {
+            const budget = learningEngine.getAdaptiveBudget(budgetBundleId);
+            if (budget.locateMs !== 800 || budget.actMs !== 200 || budget.verifyMs !== 2000) {
+                currentAdaptiveBudget = budget;
+            }
+            else {
+                currentAdaptiveBudget = null;
+            }
+        }
+        else {
+            currentAdaptiveBudget = null;
+        }
+        // Capture pre-call focused app for focus drift detection
+        const preBundleId = worldModel.getState().focusedApp?.bundleId ?? null;
+        // Update last known bundleId from world model, tool params, or context tracker
+        const paramBundleId = safeParams.bundleId ?? safeParams.pid;
+        if (preBundleId) {
+            lastKnownBundleId = preBundleId;
+        }
+        else if (typeof paramBundleId === "string" && paramBundleId) {
+            lastKnownBundleId = paramBundleId;
+        }
+        // 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.
+        const ACTION_TOOLS = new Set([
+            "type_text", "key", "drag", "scroll", "menu_click", "applescript",
+            "ui_set_value", "ui_press",
+            "browser_type", "browser_click", "browser_fill_form", "browser_human_click",
+            "browser_js", "browser_navigate",
+            "type_with_fallback", "select_with_fallback", "scroll_with_fallback",
+        ]);
         try {
             const result = await originalHandler(params, extra);
             const durationMs = Date.now() - start;
@@ -177,15 +494,647 @@ server.tool = (...args) => {
                 error: null,
             };
             memory.recordEvent(entry); // non-blocking write + session tracking
+            // ── POST-CALL: record success for playbook learning (in-memory only) ──
+            contextTracker.recordOutcome(toolName, safeParams, true, null);
+            // ── POST-CALL: Safari context gap + page context update ──
+            const postFocusApp = worldModel.getState().focusedApp;
+            const postBundleIdForCtx = postFocusApp?.bundleId ?? lastKnownBundleId;
+            if (postBundleIdForCtx) {
+                lastKnownBundleId = postBundleIdForCtx;
+                // Try focused window first, then search all windows for matching bundleId
+                let winTitle = null;
+                const focWin = worldModel.getFocusedWindow();
+                if (focWin?.title.value) {
+                    winTitle = focWin.title.value;
+                }
+                else if (postFocusApp?.pid) {
+                    // Focused window lost — search state for any window from this app
+                    for (const [, win] of worldModel.getState().windows) {
+                        if (win.pid === postFocusApp.pid && win.title.value) {
+                            winTitle = win.title.value;
+                            break;
+                        }
+                    }
+                }
+                if (winTitle) {
+                    contextTracker.updateContextFromWindowTitle(postBundleIdForCtx, winTitle);
+                    contextTracker.updatePageContext(winTitle);
+                }
+                else {
+                    // Don't null out page context if we just can't find the window —
+                    // keep the last known page context to avoid losing it on transient events
+                }
+            }
+            // ── POST-CALL: record page transitions for navigation graph ──
+            const pageTransition = contextTracker.consumePageTransition();
+            if (pageTransition && postBundleIdForCtx) {
+                try {
+                    appMap.recordPageTransition(postBundleIdForCtx, pageTransition.from, pageTransition.to, toolName);
+                }
+                catch { /* non-critical — don't break tool execution for nav tracking */ }
+            }
+            // ── POST-CALL: detect focus drift ──
+            const postBundleId = worldModel.getState().focusedApp?.bundleId ?? null;
+            if (preBundleId && postBundleId && preBundleId !== postBundleId) {
+                const driftWarning = `⚠ Focus changed: ${preBundleId} → ${postBundleId}. Use \`focus\` to return.`;
+                if (result?.content && Array.isArray(result.content)) {
+                    result.content.unshift({ type: "text", text: driftWarning });
+                }
+            }
+            // ── POST-CALL: feed learning engine (timing + locator outcomes) ──
+            const learnBundleId = worldModel.getState().focusedApp?.bundleId ?? lastKnownBundleId ?? "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
+                ?? (toolName === "click_text" ? safeParams.text : undefined);
+            if (typeof locatorTarget === "string" && locatorTarget) {
+                const method = toolName.startsWith("browser_") ? "cdp"
+                    : toolName.includes("ocr") ? "ocr"
+                        : "ax";
+                learningEngine.recordLocatorOutcome({
+                    bundleId: learnBundleId,
+                    actionKey: toolName,
+                    locator: locatorTarget,
+                    method,
+                    success: true,
+                });
+                // Auto-record verified pattern to patterns.jsonl via learning engine
+                learningEngine.recordPattern({
+                    bundleId: learnBundleId,
+                    tool: toolName,
+                    locator: locatorTarget,
+                    method,
+                    success: true,
+                });
+            }
+            // ── POST-CALL: update app mastery map from successful action ──
+            // Check if the result signals an error (e.g. click_text "not found" returns isError: true)
+            const resultIsError = !!result?.isError;
+            const isActionTool = ACTION_TOOLS.has(toolName);
+            if (resultIsError && learnBundleId !== "unknown") {
+                // Redirect to failure mastery recording + count as edge case handled
+                try {
+                    const failedLocatorSoft = safeParams.target ?? safeParams.selector ?? safeParams.locator
+                        ?? (toolName === "click_text" ? safeParams.text : undefined);
+                    if (typeof failedLocatorSoft === "string" && failedLocatorSoft) {
+                        appMap.recordElementOutcome(learnBundleId, "auto", failedLocatorSoft, false, contextTracker.currentPageContext ?? undefined);
+                    }
+                    if (isActionTool) {
+                        appMap.recordActionOutcome(learnBundleId, false);
+                    }
+                    // Track as edge case: encountering an error is an unexpected state
+                    const edgeMapData = appMap.getLoaded(learnBundleId);
+                    if (edgeMapData) {
+                        edgeMapData.edgeCasesHandled = (edgeMapData.edgeCasesHandled ?? 0) + 1;
+                        appMap.save(edgeMapData, true);
+                    }
+                    const failMapDataSoft = appMap.getLoaded(learnBundleId);
+                    if (failMapDataSoft?.featureLadder) {
+                        const failSignalSoft = [toolName, typeof failedLocatorSoft === "string" ? failedLocatorSoft : ""].join(" ").toLowerCase();
+                        const failGenSignalsSoft = appMap.getGeneratedSignals(learnBundleId) ?? {};
+                        for (const feature of failMapDataSoft.featureLadder) {
+                            const fm = failMapDataSoft.featureMastery?.[feature.id];
+                            if (!fm || fm.depth === 0)
+                                continue;
+                            const featureInSignal = failSignalSoft.includes(feature.id.replace(/_/g, " "));
+                            const keywords = failGenSignalsSoft[feature.id];
+                            const keywordMatch = keywords?.some((kw) => failSignalSoft.includes(kw));
+                            if (featureInSignal || keywordMatch) {
+                                appMap.recordFeatureSignal(learnBundleId, feature.id, fm.depth, false);
+                            }
+                        }
+                    }
+                }
+                catch { /* non-fatal */ }
+            }
+            if (!resultIsError && learnBundleId !== "unknown") {
+                try {
+                    if (!appMap.load(learnBundleId)) {
+                        const focApp = worldModel.getState().focusedApp;
+                        appMap.createEmpty(learnBundleId, focApp?.appName ?? learnBundleId);
+                    }
+                    // Record element outcome for tools with a locator target
+                    if (typeof locatorTarget === "string" && locatorTarget) {
+                        appMap.recordElementOutcome(learnBundleId, "auto", locatorTarget, true, contextTracker.currentPageContext ?? undefined);
+                        // Write relative position from click coordinates
+                        const resultText = extractText(result);
+                        const screenMatch = resultText.match(/at screen \((\d+),\s*(\d+)\)/);
+                        const windowMatch = resultText.match(/\[window: \((\d+),\s*(\d+)\) (\d+)[x×](\d+)\]/);
+                        if (screenMatch && windowMatch) {
+                            const sx = parseInt(screenMatch[1], 10);
+                            const sy = parseInt(screenMatch[2], 10);
+                            const wx = parseInt(windowMatch[1], 10);
+                            const wy = parseInt(windowMatch[2], 10);
+                            const ww = parseInt(windowMatch[3], 10);
+                            const wh = parseInt(windowMatch[4], 10);
+                            if (ww > 0 && wh > 0) {
+                                const relX = Math.max(0, Math.min(1, (sx - wx) / ww));
+                                const relY = Math.max(0, Math.min(1, (sy - wy) / wh));
+                                appMap.updateElementPosition(learnBundleId, "auto_discovered", locatorTarget, relX, relY);
+                            }
+                        }
+                    }
+                    // Record action outcome (only for tools that DO something, not navigation)
+                    if (isActionTool) {
+                        appMap.recordActionOutcome(learnBundleId, true);
+                    }
+                    // ── Record input/output contract for element interaction tools ──
+                    {
+                        const CONTRACT_TOOLS = new Set(["click", "click_text", "type_text", "key", "menu_click"]);
+                        if (CONTRACT_TOOLS.has(toolName) && typeof locatorTarget === "string" && locatorTarget) {
+                            // Use "auto" to search all zones — page-specific zones may not exist yet
+                            appMap.recordContract(learnBundleId, "auto", locatorTarget, toolName, ["action succeeded"]);
+                        }
+                    }
+                    // ── Track shortcut usage (keyboard combos with modifier keys) ──
+                    if (toolName === "key" && typeof safeParams.combo === "string") {
+                        const combo = safeParams.combo.toLowerCase();
+                        if (combo.includes("cmd+") || combo.includes("ctrl+") || combo.includes("alt+") || combo.includes("shift+")) {
+                            const mapDataShortcut = appMap.getLoaded(learnBundleId);
+                            if (mapDataShortcut) {
+                                mapDataShortcut.shortcutsUsed = (mapDataShortcut.shortcutsUsed ?? 0) + 1;
+                                appMap.save(mapDataShortcut, true);
+                            }
+                        }
+                    }
+                    // ── Track edge case handling (escape = dialog/popup dismissal) ──
+                    if (toolName === "key" && safeParams.combo === "escape") {
+                        const mapDataEdge = appMap.getLoaded(learnBundleId);
+                        if (mapDataEdge) {
+                            mapDataEdge.edgeCasesHandled = (mapDataEdge.edgeCasesHandled ?? 0) + 1;
+                            appMap.save(mapDataEdge, true);
+                        }
+                    }
+                    // ── Auto-detect feature depth from tool usage signals ──
+                    // Depth: 1=navigated (screenshot/focus), 2=basic action (click/type),
+                    //        3=multi-step workflow (action tools in sequence), 4=verified outcome
+                    {
+                        const mapData = appMap.getLoaded(learnBundleId);
+                        if (mapData?.featureLadder) {
+                            const signalText = [
+                                toolName,
+                                typeof locatorTarget === "string" ? locatorTarget : "",
+                                typeof safeParams.text === "string" ? safeParams.text : "",
+                                preWindowTitle ?? "",
+                                worldModel.getFocusedWindow()?.title.value ?? "",
+                            ].join(" ").toLowerCase();
+                            // Determine depth from tool type and history:
+                            // depth 1 = navigated (screenshot/focus/ocr)
+                            // depth 2 = basic action (click/type/key on the feature)
+                            // depth 3 = multi-step workflow (already at depth 2, hit again with different action tool)
+                            // depth 4 = verified outcome (at depth 3, then verified via screenshot/ocr)
+                            const NAV_TOOLS = new Set(["screenshot", "screenshot_file", "focus", "ocr", "ui_tree", "ui_find", "windows", "apps", "browser_tabs", "browser_page_info", "browser_dom"]);
+                            const VERIFY_TOOLS = new Set(["screenshot", "screenshot_file", "ocr", "ui_tree", "ui_find", "browser_dom", "browser_page_info"]);
+                            const isNavTool = NAV_TOOLS.has(toolName);
+                            const isVerifyTool = VERIFY_TOOLS.has(toolName);
+                            // Keyword map: featureId → keywords that signal the feature was used
+                            // Hardcoded signals for apps with BUILTIN_LADDERS
+                            const BUILTIN_FEATURE_SIGNALS = {
+                                // Discord
+                                browse_channels: ["channel", "server", "sidebar", "lounge", "information"],
+                                send_message: ["message", "type_text", "browser_type", "chatter", "chat"],
+                                direct_messages: ["direct message", "dm", "group chat", "friends"],
+                                voice_video: ["voice", "stage", "listen", "audio", "video", "call", "screen share", "activity"],
+                                threads_forums: ["thread", "forum", "post", "topic", "discussion"],
+                                roles_permissions: ["role", "permission", "override", "hidden channel"],
+                                notification_control: ["notification", "mention", "mute", "suppress"],
+                                events_stage: ["event", "stage", "trivia", "interested", "schedule"],
+                                onboarding_funnel: ["onboarding", "welcome", "get started", "rules screening", "starter", "channels & roles", "customize", "browse channels", "choose your channels"],
+                                moderation_system: ["moderation", "automod", "ban", "modmail", "audit", "report", "rules", "safety", "raid"],
+                                bot_ecosystem: ["bot", "automod", "integration", "app directory", "slash command", "verification", "add app", "add to server", "mee6", "webhook"],
+                                server_architecture: ["category", "channel taxonomy", "channels & roles", "server guide", "server settings"],
+                                community_growth: ["announcement", "event", "reward", "retention", "engagement"],
+                                analytics_health: ["analytics", "insights", "server insights", "activity", "member count"],
+                                monetization_membership: ["premium", "boost", "subscription", "tier", "monetiz"],
+                                crisis_handling: ["raid", "spam", "harassment", "lockdown", "ban wave"],
+                                cross_platform: ["github", "notion", "twitch", "stripe", "zapier", "webhook"],
+                                staff_system: ["moderator", "staff", "escalation", "internal", "mod channel"],
+                                brand_culture: ["community", "identity", "ritual", "culture", "recognition"],
+                                governance_policy: ["rules", "policy", "enforcement", "appeal", "governance"],
+                                // Safari
+                                browse_navigate: ["navigate", "browser_navigate", "browser_open", "url"],
+                                tabs_windows: ["tab", "browser_tabs", "window"],
+                                bookmarks: ["bookmark", "reading list"],
+                                history_search: ["history", "search"],
+                                tab_groups: ["tab group", "profile"],
+                                extensions: ["extension"],
+                                dev_tools: ["inspector", "developer", "console", "browser_js"],
+                                privacy_settings: ["privacy", "cookie", "blocker"],
+                                web_apps: ["add to dock", "web app"],
+                                // Finder
+                                browse_files: ["finder", "file", "folder", "browse"],
+                                copy_move: ["copy", "move", "rename", "delete", "trash"],
+                                search: ["search", "spotlight"],
+                                views_sort: ["view", "sort", "column", "icon", "list"],
+                                tags_favorites: ["tag", "favorite", "sidebar"],
+                                quick_actions: ["quick look", "quick action", "service"],
+                                automator_scripts: ["automator", "terminal", "script", "applescript"],
+                                // Generic (fallback for apps with generic ladders)
+                                basic_navigation: ["navigate", "open", "browse", "launch"],
+                                core_action: ["type_text", "click", "press", "key"],
+                                settings: ["settings", "preferences", "config"],
+                                advanced_features: ["advanced", "power", "shortcut", "automation"],
+                            };
+                            // Auto-generate ladder from reference if no builtin exists
+                            if (!appMap.hasGeneratedLadder(learnBundleId)) {
+                                const ref = _playbookStoreForContext.matchByBundleId(learnBundleId);
+                                if (ref?.selectors && Object.keys(ref.selectors).length >= 2) {
+                                    const generated = appMap.generateLadderFromRef(learnBundleId, ref);
+                                    if (generated) {
+                                        // Reload mapData with new ladder
+                                        const refreshed = appMap.getLoaded(learnBundleId);
+                                        if (refreshed) {
+                                            Object.assign(mapData, refreshed);
+                                        }
+                                    }
+                                }
+                            }
+                            // Merge auto-generated signals with builtins (generated takes priority)
+                            const generatedSignals = appMap.getGeneratedSignals(learnBundleId);
+                            const mergedSignals = { ...BUILTIN_FEATURE_SIGNALS };
+                            if (generatedSignals) {
+                                for (const [fid, kws] of Object.entries(generatedSignals)) {
+                                    mergedSignals[fid] = kws;
+                                }
+                            }
+                            const hitFeatures = [];
+                            for (const feature of mapData.featureLadder) {
+                                const keywords = mergedSignals[feature.id];
+                                if (!keywords)
+                                    continue;
+                                if (keywords.some((kw) => signalText.includes(kw))) {
+                                    // Compute depth based on current state + tool type
+                                    const existing = mapData.featureMastery?.[feature.id];
+                                    const currentDepth = existing?.depth ?? 0;
+                                    let signalDepth;
+                                    if (isVerifyTool && currentDepth >= 3) {
+                                        // Verifying after a workflow = verified outcome (depth 4)
+                                        signalDepth = 4;
+                                    }
+                                    else if (!isNavTool && currentDepth >= 2 && (existing?.repeatCount ?? 0) >= 3) {
+                                        // Repeated action tool on a feature we've already actioned = workflow (depth 3)
+                                        signalDepth = 3;
+                                    }
+                                    else if (isNavTool) {
+                                        signalDepth = 1;
+                                    }
+                                    else {
+                                        signalDepth = 2;
+                                    }
+                                    appMap.recordFeatureSignal(learnBundleId, feature.id, signalDepth, true);
+                                    // Healing detection: success after prior failure = recovery
+                                    if (existing && existing.failCount > (existing.healingCount ?? 0)) {
+                                        appMap.recordHealing(learnBundleId, feature.id);
+                                    }
+                                    if (!isNavTool)
+                                        hitFeatures.push(feature.id);
+                                }
+                            }
+                            // Cross-feature workflow detection: track distinct features hit by action tools.
+                            // When 3+ distinct features are hit in a rolling window, record a cross-feature workflow.
+                            if (!crossFeatureBuffer.has(learnBundleId)) {
+                                crossFeatureBuffer.set(learnBundleId, { features: [], lastRecordedAt: 0 });
+                            }
+                            const cfBuf = crossFeatureBuffer.get(learnBundleId);
+                            for (const fid of hitFeatures) {
+                                if (!cfBuf.features.includes(fid))
+                                    cfBuf.features.push(fid);
+                            }
+                            // Trim to last 10 features
+                            if (cfBuf.features.length > 10)
+                                cfBuf.features = cfBuf.features.slice(-10);
+                            // Record a cross-feature workflow every 3 distinct features (throttled)
+                            if (cfBuf.features.length >= 3 && Date.now() - cfBuf.lastRecordedAt > 30_000) {
+                                appMap.recordCrossFeatureWorkflow(learnBundleId);
+                                cfBuf.lastRecordedAt = Date.now();
+                                cfBuf.features = []; // Reset for next workflow
+                            }
+                        }
+                    }
+                    // Record navigation edge when window title changes (screen transition)
+                    const postWindowTitle = worldModel.getFocusedWindow()?.title.value ?? null;
+                    if (preWindowTitle && postWindowTitle && preWindowTitle !== postWindowTitle) {
+                        const appName = worldModel.getState().focusedApp?.appName ?? "";
+                        const titleSuffix = appName ? new RegExp(` - ${appName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`) : null;
+                        const fromNode = titleSuffix ? preWindowTitle.replace(titleSuffix, "") : preWindowTitle;
+                        const toNode = titleSuffix ? postWindowTitle.replace(titleSuffix, "") : postWindowTitle;
+                        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);
+                            learningEngine.recordTopologyOutcome({
+                                bundleId: learnBundleId,
+                                fromNode,
+                                action: locatorTarget ?? toolName,
+                                toNode,
+                                success: true,
+                            });
+                        }
+                    }
+                    // ── State machine: detect state changes from tool results ──
+                    // Two detection paths:
+                    // 1. Keyword matching on result text (original regex patterns)
+                    // 2. Structural detection: key combos that open/close UI elements
+                    {
+                        const stateResultText = extractText(result).toLowerCase();
+                        const stateTrigger = locatorTarget ?? toolName;
+                        // --- Structural state detection from tool + combo patterns ---
+                        // Keyboard shortcuts that toggle UI state (works even when result text has no keywords)
+                        if (toolName === "key" && typeof safeParams.combo === "string") {
+                            const combo = safeParams.combo.toLowerCase();
+                            // Cmd+K / Ctrl+K / Cmd+P = search/command palette (dialog open)
+                            if (combo === "cmd+k" || combo === "ctrl+k" || combo === "cmd+p" || combo === "ctrl+p") {
+                                const prevState = appMap.getCurrentState(learnBundleId);
+                                const from = prevState["modal_state"] ?? "closed";
+                                appMap.recordStateChange(learnBundleId, "modal_state", from, "open", combo);
+                            }
+                            // Escape = dismiss dialog/modal
+                            if (combo === "escape") {
+                                const prevState = appMap.getCurrentState(learnBundleId);
+                                if (prevState["modal_state"] === "open") {
+                                    appMap.recordStateChange(learnBundleId, "modal_state", "open", "closed", combo);
+                                }
+                            }
+                            // Cmd+\ or Cmd+Shift+S = sidebar toggle (common pattern)
+                            if (combo === "cmd+\\" || combo === "ctrl+\\" || combo === "cmd+shift+s") {
+                                const prevState = appMap.getCurrentState(learnBundleId);
+                                const currentSidebar = prevState["sidebar_state"] ?? "expanded";
+                                const newSidebar = currentSidebar === "expanded" ? "collapsed" : "expanded";
+                                appMap.recordStateChange(learnBundleId, "sidebar_state", currentSidebar, newSidebar, combo);
+                            }
+                        }
+                        // --- Keyword matching on result text (original patterns) ---
+                        // Modal/dialog state
+                        // V4: Require noun+verb proximity to prevent false injection from element labels.
+                        if (/\b(modal|dialog|popup|alert|sheet|search|command palette)\s+\w*\s*\b(opened|appeared|shown|displayed|presented)\b/.test(stateResultText) ||
+                            /\b(opened|appeared|shown|displayed|presented)\s+\w*\s*\b(modal|dialog|popup|alert|sheet)\b/.test(stateResultText) ||
+                            /\b(modal|dialog|popup|alert|sheet)\s+(is|was|has been)\s+(opened|shown|displayed|presented)\b/.test(stateResultText)) {
+                            const prevState = appMap.getCurrentState(learnBundleId);
+                            const from = prevState["modal_state"] ?? "closed";
+                            appMap.recordStateChange(learnBundleId, "modal_state", from, "open", stateTrigger);
+                        }
+                        else if (/\b(modal|dialog|popup|alert|sheet)\s+\w*\s*\b(closed|dismissed|hidden|disappeared)\b/.test(stateResultText) ||
+                            /\b(closed|dismissed|hidden|disappeared)\s+\w*\s*\b(modal|dialog|popup|alert|sheet)\b/.test(stateResultText) ||
+                            /\b(modal|dialog|popup|alert|sheet)\s+(is|was|has been)\s+(closed|dismissed|hidden)\b/.test(stateResultText)) {
+                            const prevState = appMap.getCurrentState(learnBundleId);
+                            const from = prevState["modal_state"] ?? "open";
+                            appMap.recordStateChange(learnBundleId, "modal_state", from, "closed", stateTrigger);
+                        }
+                        // Sidebar/panel state
+                        if (/\b(sidebar|panel)\s+\w*\s*\b(collapsed|hidden|closed|minimized)\b/.test(stateResultText) ||
+                            /\b(collapsed|hidden|closed|minimized)\s+\w*\s*\b(sidebar|panel)\b/.test(stateResultText) ||
+                            /\b(sidebar|panel)\s+(is|was|has been)\s+(collapsed|hidden|closed|minimized)\b/.test(stateResultText)) {
+                            const prevState = appMap.getCurrentState(learnBundleId);
+                            const from = prevState["sidebar_state"] ?? "expanded";
+                            appMap.recordStateChange(learnBundleId, "sidebar_state", from, "collapsed", stateTrigger);
+                        }
+                        else if (/\b(sidebar|panel)\s+\w*\s*\b(expanded|shown|opened|visible|maximized)\b/.test(stateResultText) ||
+                            /\b(expanded|shown|opened|visible|maximized)\s+\w*\s*\b(sidebar|panel)\b/.test(stateResultText) ||
+                            /\b(sidebar|panel)\s+(is|was|has been)\s+(expanded|shown|opened|visible|maximized)\b/.test(stateResultText)) {
+                            const prevState = appMap.getCurrentState(learnBundleId);
+                            const from = prevState["sidebar_state"] ?? "collapsed";
+                            appMap.recordStateChange(learnBundleId, "sidebar_state", from, "expanded", stateTrigger);
+                        }
+                        // View mode state (e.g., board/list/table/grid/timeline)
+                        const viewModeMatch = stateResultText.match(/\b(board|list|table|grid|timeline|calendar|gallery|kanban)\s*view\b/);
+                        if (!viewModeMatch) {
+                            const altViewMatch = stateResultText.match(/(?:switched\s+to|view:\s*)\s*(board|list|table|grid|timeline|calendar|gallery|kanban)\b/);
+                            if (altViewMatch) {
+                                const newView = altViewMatch[1];
+                                const prevState = appMap.getCurrentState(learnBundleId);
+                                const from = prevState["view_mode"] ?? "unknown";
+                                if (from !== newView) {
+                                    appMap.recordStateChange(learnBundleId, "view_mode", from, newView, stateTrigger);
+                                }
+                            }
+                        }
+                        else {
+                            const newView = viewModeMatch[1];
+                            const prevState = appMap.getCurrentState(learnBundleId);
+                            const from = prevState["view_mode"] ?? "unknown";
+                            if (from !== newView) {
+                                appMap.recordStateChange(learnBundleId, "view_mode", from, newView, stateTrigger);
+                            }
+                        }
+                    }
+                    // ── Hierarchy extraction from UI inspection tools ──
+                    // Extract parent/child containment from any tool that reveals structure
+                    {
+                        const HIERARCHY_TOOLS = new Set(["ui_tree", "ui_find", "screenshot", "ocr"]);
+                        if (HIERARCHY_TOOLS.has(toolName)) {
+                            try {
+                                const treeText = extractText(result);
+                                if (treeText) {
+                                    const lines = treeText.split("\n");
+                                    const hierarchyZone = contextTracker.currentPageContext
+                                        ? `page::${contextTracker.currentPageContext}` : "auto_discovered";
+                                    if (toolName === "ui_tree" || toolName === "ui_find") {
+                                        // Parse indented AX tree: depth 0 = root, depth 1 = top containers, depth 2 = children
+                                        // Format: "  ".repeat(depth) + role "title" ...
+                                        const containers = [];
+                                        for (const line of lines) {
+                                            const stripped = line.replace(/\s+$/, "");
+                                            const indent = stripped.length - stripped.trimStart().length;
+                                            const depth = Math.floor(indent / 2);
+                                            const titleMatch = stripped.match(/"([^"]+)"/);
+                                            if (!titleMatch)
+                                                continue;
+                                            const label = titleMatch[1];
+                                            if (!label || label.length > 200)
+                                                continue;
+                                            if (depth <= 1) {
+                                                containers.push({ label, depth, children: [] });
+                                            }
+                                            else if (depth === 2 && containers.length > 0) {
+                                                const parent = containers[containers.length - 1];
+                                                if (parent && parent.children.length < 50) {
+                                                    parent.children.push(label);
+                                                }
+                                            }
+                                        }
+                                        for (const container of containers) {
+                                            if (container.children.length > 0) {
+                                                appMap.recordHierarchy(learnBundleId, hierarchyZone, container.label, container.children, "ax_tree");
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        // screenshot/ocr: extract spatial grouping from OCR lines
+                                        // OCR text is top-to-bottom — consecutive lines within the same
+                                        // vertical region (heading followed by items) form parent/child
+                                        const ocrLabels = [];
+                                        for (const line of lines) {
+                                            const trimmed = line.trim();
+                                            if (trimmed && trimmed.length >= 2 && trimmed.length <= 100) {
+                                                ocrLabels.push(trimmed);
+                                            }
+                                        }
+                                        // Heuristic: detect section headings from OCR text.
+                                        // A heading is a short label (1-2 words, <=20 chars) followed by 2+ lines,
+                                        // or a title-case label followed by bullet-prefixed items.
+                                        // Catches "Recents", "Private", "Tasks Tracker" in Notion, etc.
+                                        let currentParent = null;
+                                        let currentChildren = [];
+                                        const flushGroup = () => {
+                                            if (currentParent && currentChildren.length > 0) {
+                                                appMap.recordHierarchy(learnBundleId, hierarchyZone, currentParent, currentChildren.slice(0, 50), "ocr_spatial");
+                                            }
+                                            currentParent = null;
+                                            currentChildren = [];
+                                        };
+                                        for (let i = 0; i < ocrLabels.length; i++) {
+                                            const label = ocrLabels[i];
+                                            const isAllCaps = /^[A-Z][A-Z\s]{2,}$/.test(label);
+                                            const hasColon = label.endsWith(":");
+                                            // Short single/double-word section name (e.g. "Recents", "Private", "New database")
+                                            const isShortSection = /^[A-Z][a-z]+(\s+[a-z]+)?$/.test(label) && label.length <= 20;
+                                            // Title-case heading: 1-4 words
+                                            const isTitleCase = /^[A-Z][a-zA-Z]+(\s+[A-Za-z]+){0,3}$/.test(label) && label.length <= 30;
+                                            const hasFollowingContent = i + 2 < ocrLabels.length;
+                                            // Bullet/icon items (strong signal)
+                                            const nextHasBullet = (idx) => {
+                                                const next = ocrLabels[idx];
+                                                return next != null && /^[•\*\+\-\u2022\u25CF※®=¿]/.test(next);
+                                            };
+                                            const followedByBullets = hasFollowingContent && nextHasBullet(i + 1);
+                                            const isHeading = isAllCaps || hasColon || (isShortSection && hasFollowingContent) || (isTitleCase && followedByBullets);
+                                            if (isHeading) {
+                                                flushGroup();
+                                                currentParent = label.replace(/:$/, "");
+                                            }
+                                            else if (currentParent) {
+                                                currentChildren.push(label);
+                                            }
+                                        }
+                                        flushGroup();
+                                    }
+                                }
+                            }
+                            catch { /* hierarchy extraction non-fatal */ }
+                        }
+                    }
+                    // ── Conditional UI visibility tracking (throttled) ──
+                    // Every 3rd inspection-like tool call, compare discovered elements against
+                    // known map elements to detect which appear/disappear by page context.
+                    {
+                        const VISIBILITY_TOOLS = new Set([
+                            "ui_tree", "ocr", "ui_find", "screenshot", "click_text",
+                            "windows", "browser_dom", "browser_page_info",
+                        ]);
+                        if (VISIBILITY_TOOLS.has(toolName)) {
+                            visibilityCheckCounter++;
+                        }
+                        if (visibilityCheckCounter % 3 === 0 && VISIBILITY_TOOLS.has(toolName)) {
+                            try {
+                                const visMapData = appMap.getLoaded(learnBundleId);
+                                const visPageCtx = contextTracker.currentPageContext ?? "";
+                                if (visMapData && visPageCtx) {
+                                    // Collect element labels from the result text
+                                    const visResultText = extractText(result);
+                                    const discoveredLabels = new Set();
+                                    // Extract quoted labels (from ui_tree/ui_find format)
+                                    const labelMatches = visResultText.matchAll(/"([^"]{1,100})"/g);
+                                    for (const m of labelMatches) {
+                                        if (m[1])
+                                            discoveredLabels.add(m[1]);
+                                    }
+                                    // Also extract unquoted OCR/screenshot text lines as potential labels
+                                    for (const line of visResultText.split("\n")) {
+                                        const trimmed = line.trim();
+                                        if (trimmed && trimmed.length >= 2 && trimmed.length <= 80 && !/^[\[\(]/.test(trimmed)) {
+                                            discoveredLabels.add(trimmed);
+                                        }
+                                    }
+                                    // For known elements in the map, record whether they were seen or absent
+                                    const knownElements = new Set();
+                                    for (const zone of Object.values(visMapData.zones)) {
+                                        for (const el of zone.elements) {
+                                            knownElements.add(el.label);
+                                        }
+                                    }
+                                    for (const label of knownElements) {
+                                        const seen = discoveredLabels.has(label);
+                                        appMap.recordElementVisibility(learnBundleId, label, visPageCtx, seen);
+                                    }
+                                }
+                            }
+                            catch { /* visibility tracking non-fatal */ }
+                        }
+                    }
+                    // ── Timing recording: track tool response times per element ──
+                    {
+                        const TIMING_TOOLS = new Set([
+                            "click", "click_text", "type_text", "key", "menu_click",
+                            "browser_click", "browser_type",
+                        ]);
+                        if (TIMING_TOOLS.has(toolName)) {
+                            const timingLabel = locatorTarget ?? toolName;
+                            appMap.recordTiming(learnBundleId, toolName + "::" + timingLabel, "element_response", durationMs);
+                        }
+                        // Ready-signal recording
+                        // 1. Explicit wait tools
+                        if (toolName === "browser_wait" || toolName === "wait_for_state") {
+                            appMap.recordReadySignal(learnBundleId, lastSuccessfulToolName, "wait_completed", durationMs);
+                        }
+                        // 2. Any interaction tool that took notably long (>1.5s) = implicit wait
+                        // This captures slow page loads, animation waits, network-bound actions
+                        if (durationMs > 1500 && TIMING_TOOLS.has(toolName)) {
+                            appMap.recordReadySignal(learnBundleId, toolName, "slow_response", durationMs);
+                        }
+                        // 3. Screenshot/OCR after a navigation click = page-ready signal
+                        if ((toolName === "screenshot" || toolName === "ocr") && lastSuccessfulToolName === "click_text") {
+                            appMap.recordReadySignal(learnBundleId, "click_text", "page_ready", durationMs);
+                        }
+                    }
+                    // Refresh mastery level after updates
+                    appMap.refreshMastery(learnBundleId);
+                }
+                catch { /* app map update non-fatal */ }
+            }
+            // Track last successful tool name for ready-signal context
+            lastSuccessfulToolName = toolName;
+            // ── POST-CALL: capture for playbook recording if active ──
+            if (mcpRecorder.isRecording) {
+                const fullResultText = Array.isArray(result?.content) ? result.content.map((c) => c.text ?? "").join(" ") : "";
+                const resultText = fullResultText.length > 500 ? fullResultText.substring(0, 500) + " [TRUNCATED]" : fullResultText;
+                mcpRecorder.captureToolCall(toolName, safeParams, true, resultText, durationMs);
+            }
             // ── POST-CALL: auto-recall hints (~0ms, in-memory) ──
             const hints = [];
-            // Warn about known errors for this tool
+            // Playbook-aware hints (errors, selectors, job suggestions)
+            for (const h of playbookHints) {
+                hints.push(h);
+            }
+            // World model summary (window/control state)
+            const wmSummary = worldModel.toSummary();
+            if (wmSummary && worldModel.getState().windows.size > 0) {
+                hints.push(`World: ${wmSummary.split("\n")[0]}`);
+            }
+            // Perception freshness
+            if (perceptionManager.isRunning) {
+                hints.push(perceptionManager.getFreshnessSummary());
+            }
+            // Learning engine recommendations
+            const patternRec = learningEngine.recommendPattern(learnBundleId, toolName);
+            if (patternRec) {
+                const rate = ((patternRec.successCount / Math.max(1, patternRec.successCount + patternRec.failCount)) * 100).toFixed(0);
+                hints.push(`Pattern: "${patternRec.locator}" (${patternRec.method}, ${rate}% over ${patternRec.successCount + patternRec.failCount} uses)`);
+            }
+            const learnLocator = learningEngine.recommendLocator(learnBundleId, toolName);
+            if (learnLocator) {
+                hints.push(`Learning: best locator for ${toolName} → "${learnLocator.locator}" (${learnLocator.method}, ${learnLocator.score.toFixed(2)} score, ${learnLocator.successCount}/${learnLocator.successCount + learnLocator.failCount} success)`);
+            }
+            const adaptiveBudget = learningEngine.getAdaptiveBudget(learnBundleId);
+            if (adaptiveBudget.locateMs !== 800 || adaptiveBudget.actMs !== 200 || adaptiveBudget.verifyMs !== 2000) {
+                hints.push(`Learning: adaptive budgets → locate=${adaptiveBudget.locateMs}ms, act=${adaptiveBudget.actMs}ms, verify=${adaptiveBudget.verifyMs}ms`);
+            }
+            // Warn about known errors for this tool (from memory)
             if (knownError) {
                 hints.push(`⚡ Memory: "${toolName}" has failed before: "${knownError.error}" (${knownError.occurrences}x). Fix: ${knownError.resolution}`);
             }
             // Suggest next step if we're mid-strategy
             const recentTools = memory.getRecentToolNames();
-            const strategyHint = memory.quickStrategyHint(recentTools);
+            const strategyHint = memory.quickStrategyHint(recentTools, worldModel.getState().focusedApp?.bundleId);
             if (strategyHint) {
                 activeStrategyFingerprint = strategyHint.fingerprint;
                 const nextParams = Object.keys(strategyHint.nextStep.params).length > 0
@@ -203,10 +1152,16 @@ server.tool = (...args) => {
                 memory.recordStrategyOutcome(activeStrategyFingerprint, true);
                 activeStrategyFingerprint = null;
             }
-            // Attach hints as _meta (doesn't pollute tool output for MCP clients)
+            // Attach hints in BOTH content (visible) and _meta (for programmatic access)
             if (hints.length > 0) {
+                const hintText = hints.join("\n");
+                const resultContent = Array.isArray(result?.content) ? result.content : [];
                 return {
                     ...result,
+                    content: [
+                        ...resultContent,
+                        { type: "text", text: `\n---\n${hintText}` },
+                    ],
                     _meta: { ...(result?._meta ?? {}), memoryHints: hints },
                 };
             }
@@ -228,6 +1183,69 @@ server.tool = (...args) => {
                 error: errorMsg,
             };
             memory.recordEvent(entry); // non-blocking write + session tracking
+            // ── 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";
+            learningEngine.recordToolTiming({ tool: toolName, bundleId: learnBundleIdErr, durationMs, success: false });
+            const failedLocator = safeParams.target ?? safeParams.selector ?? safeParams.locator
+                ?? (toolName === "click_text" ? safeParams.text : undefined);
+            if (typeof failedLocator === "string" && failedLocator) {
+                const method = toolName.startsWith("browser_") ? "cdp"
+                    : toolName.includes("ocr") ? "ocr"
+                        : "ax";
+                learningEngine.recordLocatorOutcome({
+                    bundleId: learnBundleIdErr,
+                    actionKey: toolName,
+                    locator: failedLocator,
+                    method,
+                    success: false,
+                });
+                // Record failed pattern to patterns.jsonl
+                learningEngine.recordPattern({
+                    bundleId: learnBundleIdErr,
+                    tool: toolName,
+                    locator: failedLocator,
+                    method,
+                    success: false,
+                });
+            }
+            // ── POST-CALL: record failure in app mastery map ──
+            if (learnBundleIdErr !== "unknown") {
+                try {
+                    if (typeof failedLocator === "string" && failedLocator) {
+                        appMap.recordElementOutcome(learnBundleIdErr, "auto", failedLocator, false, contextTracker.currentPageContext ?? undefined);
+                    }
+                    // Record action failure
+                    const isFailedAction = ACTION_TOOLS.has(toolName);
+                    if (isFailedAction) {
+                        appMap.recordActionOutcome(learnBundleIdErr, false);
+                    }
+                    // Record feature signal failure (affects confidence and reliability)
+                    const failMapData = appMap.getLoaded(learnBundleIdErr);
+                    if (failMapData?.featureLadder) {
+                        const failSignal = [toolName, typeof failedLocator === "string" ? failedLocator : ""].join(" ").toLowerCase();
+                        const failGeneratedSignals = appMap.getGeneratedSignals(learnBundleIdErr) ?? {};
+                        for (const feature of failMapData.featureLadder) {
+                            const fm = failMapData.featureMastery?.[feature.id];
+                            if (!fm || fm.depth === 0)
+                                continue; // Only track failures on features we've seen
+                            // Check feature ID match OR keyword match (same as success path)
+                            const featureInSignal = failSignal.includes(feature.id.replace(/_/g, " "));
+                            const keywords = failGeneratedSignals[feature.id];
+                            const keywordMatch = keywords?.some((kw) => failSignal.includes(kw));
+                            if (featureInSignal || keywordMatch) {
+                                appMap.recordFeatureSignal(learnBundleIdErr, feature.id, fm.depth, false);
+                            }
+                        }
+                    }
+                }
+                catch { /* app map update non-fatal */ }
+            }
+            // ── Capture failure for playbook recording ──
+            if (mcpRecorder.isRecording) {
+                mcpRecorder.captureToolCall(toolName, safeParams, false, errorMsg, durationMs);
+            }
             // Record strategy failure if we were following one
             if (activeStrategyFingerprint) {
                 memory.recordStrategyOutcome(activeStrategyFingerprint, false);
@@ -252,6 +1270,9 @@ server.tool = (...args) => {
             }
             throw err;
         }
+        finally {
+            currentAdaptiveBudget = null;
+        }
     };
     const newArgs = [...args];
     newArgs[handlerIdx] = wrappedHandler;
@@ -263,31 +1284,236 @@ server.tool = (...args) => {
 server.tool("apps", "List all running applications with bundle IDs and PIDs", {}, async () => {
     await ensureBridge();
     const apps = await bridge.call("app.list");
+    // L3-04 fix: Some Electron apps (Slack, Discord) don't appear in NSWorkspace.runningApplications
+    // despite being visible with windows. Augment with frontmost app if missing from list.
+    try {
+        const front = await bridge.call("app.frontmost", {});
+        if (front.pid && !apps.some((a) => a.pid === front.pid)) {
+            apps.push({ ...front, isActive: true });
+        }
+    }
+    catch { /* ignore */ }
+    // Also augment from window list — any app with visible windows should appear.
+    // Filter out XPC services and system helpers that own tiny overlay windows.
+    try {
+        const wins = await bridge.call("app.windows");
+        const appPids = new Set(apps.map((a) => a.pid));
+        const seenWinPids = new Set();
+        for (const w of wins) {
+            const wPid = w.pid || w.ownerPid;
+            const bid = w.bundleId || "";
+            // Skip XPC services, system helpers, and loginwindow — not real user apps
+            if (!wPid || appPids.has(wPid) || seenWinPids.has(wPid))
+                continue;
+            if (bid.includes(".xpc.") || bid === "com.apple.loginwindow" || bid === "unknown" || bid === "")
+                continue;
+            // Only include if the window has meaningful size (>50x50)
+            const b = w.bounds || {};
+            if ((b.width || 0) < 50 || (b.height || 0) < 50)
+                continue;
+            seenWinPids.add(wPid);
+            apps.push({
+                bundleId: bid,
+                name: w.appName || "Unknown",
+                pid: wPid,
+                isActive: false,
+            });
+        }
+    }
+    catch { /* ignore */ }
     const lines = apps.map((a) => `${a.name} (${a.bundleId}) pid=${a.pid}${a.isActive ? " ← active" : ""}`);
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 server.tool("windows", "List all visible windows with IDs, positions, and sizes", {}, async () => {
     await ensureBridge();
     const wins = await bridge.call("app.windows");
-    const lines = wins.map((w) => {
+    // Filter to meaningful windows: must have a title or reasonable size (>50x50)
+    const meaningful = wins.filter((w) => {
+        const b = w.bounds || {};
+        const hasTitle = w.title && w.title.length > 0;
+        const hasSize = (b.width || 0) > 50 && (b.height || 0) > 50;
+        return hasTitle || hasSize;
+    });
+    const lines = meaningful.map((w) => {
         const b = w.bounds || {};
-        return `[${w.windowId}] ${w.appName} "${w.title}" (${Math.round(b.x || 0)},${Math.round(b.y || 0)}) ${Math.round(b.width || 0)}x${Math.round(b.height || 0)}`;
+        const onScreen = w.isOnScreen === false ? " [minimized]" : "";
+        return `[${w.windowId}] ${w.appName} "${w.title}" (${Math.round(b.x || 0)},${Math.round(b.y || 0)}) ${Math.round(b.width || 0)}x${Math.round(b.height || 0)}${onScreen}`;
     });
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
-server.tool("focus", "Focus/activate an application", {
+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"),
-}, async ({ bundleId }) => {
+    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();
-    await bridge.call("app.focus", { bundleId });
-    return { content: [{ type: "text", text: "Focused " + bundleId }] };
+    // Serialize focus calls — only one can run at a time since only one app can be frontmost.
+    // Without this, N concurrent focus() calls generate N*5 bridge calls that crash the bridge.
+    let resolve;
+    const prev = focusLock;
+    focusLock = new Promise(r => { resolve = r; });
+    await prev;
+    try {
+        // Step 0: Verify the app is actually running — fail fast with error content
+        const runningApps = await bridge.call("app.list", {});
+        let targetApp = runningApps?.find((a) => a.bundleId === bundleId);
+        if (!targetApp) {
+            // L3-04 fix: Some Electron apps (Slack, Discord) don't appear in app.list.
+            // Check if they have visible windows before rejecting.
+            try {
+                const wins = await bridge.call("app.windows");
+                const appWin = wins?.find((w) => w.bundleId === bundleId);
+                if (appWin) {
+                    targetApp = { bundleId, name: appWin.appName, pid: appWin.pid || appWin.ownerPid };
+                }
+            }
+            catch { /* ignore */ }
+            if (!targetApp) {
+                return { content: [{ type: "text", text: `Error: ${bundleId} is not running. Use launch("${bundleId}") first.` }], isError: true };
+            }
+        }
+        // Step 1: Focus — use window.focus(windowId) when provided (L3-01 fix: precise window targeting)
+        // This solves multi-instance Electron apps where bundleId-based focus raises the wrong window.
+        let bridgeFocusError;
+        try {
+            if (windowId != null) {
+                await bridge.call("window.focus", { windowId });
+            }
+            else {
+                await bridge.call("app.focus", { bundleId });
+            }
+        }
+        catch (e) {
+            bridgeFocusError = e?.message ?? String(e);
+        }
+        // Step 2: Verify IMMEDIATELY — 150ms settle for macOS window server async transition.
+        // 50ms was too short on cold start; 150ms handles even first-launch activation delays.
+        await new Promise(r => setTimeout(r, 150));
+        let focusMsg = "Focused " + bundleId;
+        try {
+            const front = await bridge.call("app.frontmost", {});
+            if (front.bundleId !== bundleId) {
+                // MCP-level retry: AppleScript activation as final fallback
+                try {
+                    await bridge.call("as.run", { script: `tell application id "${bundleId}" to activate` });
+                    await new Promise(r => setTimeout(r, 200));
+                    const front2 = await bridge.call("app.frontmost", {});
+                    if (front2.bundleId === bundleId) {
+                        focusMsg = "Focused " + bundleId;
+                    }
+                    else {
+                        focusMsg = `Warning: focus requested for ${bundleId} but ${front2.bundleId} (${front2.name}) is frontmost. Try again or use launch() first.`;
+                    }
+                }
+                catch {
+                    focusMsg = `Warning: focus requested for ${bundleId} but ${front.bundleId} (${front.name}) is frontmost. Try again or use launch() first.`;
+                }
+            }
+        }
+        catch {
+            if (bridgeFocusError) {
+                focusMsg = `Warning: ${bridgeFocusError}. Call apps() to check if ${bundleId} is running.`;
+            }
+        }
+        // Step 3: World model + perception (best-effort, after verification)
+        try {
+            const apps = await bridge.call("app.list", {});
+            const app = apps?.find((a) => a.bundleId === bundleId);
+            if (app) {
+                let windowId;
+                try {
+                    windowId = await resolveWindowId(app.pid);
+                }
+                catch { /* best-effort */ }
+                if (windowId != null) {
+                    try {
+                        await bridge.call("window.focus", { windowId });
+                    }
+                    catch { /* best-effort */ }
+                }
+                const ctx = { bundleId, appName: app.name ?? bundleId, pid: app.pid, windowTitle: "", ...(windowId != null ? { windowId } : {}) };
+                worldModel.updateFocusedApp(ctx);
+                lastKnownBundleId = bundleId;
+                try {
+                    await perceptionManager.ensureStarted(ctx);
+                    installSafariEnricher(bundleId);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch { /* app.list failed — world model update is best-effort */ }
+        return { content: [{ type: "text", text: focusMsg }] };
+    }
+    finally {
+        resolve();
+    }
 });
-server.tool("launch", "Launch an application", {
+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"),
-}, async ({ bundleId }) => {
+    cdpPort: z.number().optional().describe("CDP port for Chrome/Chromium (default: 9222). Ignored for non-browser apps."),
+}, async ({ bundleId, cdpPort }) => {
     await ensureBridge();
-    const r = await bridge.call("app.launch", { bundleId });
-    return { content: [{ type: "text", text: `Launched ${r.appName} pid=${r.pid}` }] };
+    const riskyBundleIds = {
+        "com.apple.Terminal": "Terminal",
+        "com.apple.ScriptEditor2": "Script Editor",
+        "com.googlecode.iterm2": "iTerm",
+        "com.apple.ActivityMonitor": "Activity Monitor",
+    };
+    // Chrome/Chromium: launch with CDP enabled so browser_* tools work immediately
+    const chromeBundleIds = {
+        "com.google.Chrome": "Google Chrome",
+        "com.google.Chrome.canary": "Google Chrome Canary",
+        "com.brave.Browser": "Brave Browser",
+        "com.microsoft.edgemac": "Microsoft Edge",
+        "org.chromium.Chromium": "Chromium",
+    };
+    const chromeAppName = chromeBundleIds[bundleId];
+    let r;
+    if (chromeAppName) {
+        const port = cdpPort ?? 9222;
+        try {
+            // Spawn Chrome binary directly with --remote-debugging-port.
+            // Must use a dedicated user-data-dir because Chrome ignores the CDP flag
+            // when the default profile is already locked by a previous instance.
+            const { spawn } = await import("child_process");
+            const os = await import("os");
+            const chromeBinary = `/Applications/${chromeAppName}.app/Contents/MacOS/${chromeAppName}`;
+            const cdpProfile = `${os.tmpdir()}/screenhand-cdp-${port}`;
+            const proc = spawn(chromeBinary, [
+                `--remote-debugging-port=${port}`,
+                `--user-data-dir=${cdpProfile}`,
+            ], { detached: true, stdio: "ignore" });
+            proc.unref();
+            // Wait for Chrome to start, then get its PID
+            await new Promise(res => setTimeout(res, 1500));
+            const apps = await bridge.call("app.list", {});
+            const chromeApp = apps?.find((a) => a.bundleId === bundleId);
+            r = { pid: chromeApp?.pid ?? 0, appName: chromeApp?.name ?? bundleId };
+        }
+        catch {
+            // Fallback to normal launch if CDP launch fails
+            r = await bridge.call("app.launch", { bundleId });
+        }
+    }
+    else {
+        r = await bridge.call("app.launch", { bundleId });
+    }
+    const riskyName = riskyBundleIds[bundleId];
+    // Auto-start perception for the launched app
+    try {
+        const windowId = await resolveWindowId(r.pid);
+        await perceptionManager.ensureStarted({ bundleId, appName: r.appName ?? bundleId, pid: r.pid, windowTitle: "", ...(windowId != null ? { windowId } : {}) });
+        installSafariEnricher(bundleId);
+    }
+    catch { /* perception start is best-effort */ }
+    let msg = `Launched ${r.appName} pid=${r.pid}`;
+    if (chromeAppName) {
+        const port = cdpPort ?? 9222;
+        msg += `\nCDP enabled on port ${port} — browser_* tools ready`;
+    }
+    if (riskyName) {
+        msg += `\nWarning: launching ${riskyName} \u2014 this app can execute arbitrary commands`;
+    }
+    return { content: [{ type: "text", text: msg }] };
 });
 // ═══════════════════════════════════════════════
 // INSPECT — see what's on screen (debugging/design)
@@ -298,12 +1524,27 @@ server.tool("screenshot", "Take a screenshot and OCR it. Returns all visible tex
     await ensureBridge();
     let shot;
     if (windowId) {
-        shot = await bridge.call("cg.captureWindow", { windowId });
+        shot = await bridge.call("cg.captureWindow", { windowId, safeCLI: isBrowserApp() });
     }
     else {
         shot = await bridge.call("cg.captureScreen");
     }
     const ocr = await bridge.call("vision.ocr", { imagePath: shot.path });
+    // Feed OCR regions into world model
+    try {
+        if (windowId && Array.isArray(ocr.regions) && ocr.regions.length > 0) {
+            worldModel.ingestOCRRegions(windowId, ocr.regions.map((r) => ({
+                text: r.text,
+                bounds: {
+                    x: r.bounds.x,
+                    y: r.bounds.y,
+                    width: r.bounds.width,
+                    height: r.bounds.height,
+                },
+            })));
+        }
+    }
+    catch { /* world model update is best-effort */ }
     return { content: [{ type: "text", text: `Screenshot: ${shot.width}x${shot.height} (${shot.path})\n\n${ocr.text}` }] };
 });
 server.tool("screenshot_file", "Take a screenshot and return the file path (for viewing the actual image)", {
@@ -312,7 +1553,7 @@ server.tool("screenshot_file", "Take a screenshot and return the file path (for
     await ensureBridge();
     let shot;
     if (windowId) {
-        shot = await bridge.call("cg.captureWindow", { windowId });
+        shot = await bridge.call("cg.captureWindow", { windowId, safeCLI: isBrowserApp() });
     }
     else {
         shot = await bridge.call("cg.captureScreen");
@@ -325,7 +1566,7 @@ server.tool("ocr", "OCR a window with element positions. SLOW — prefer ui_tree
     await ensureBridge();
     let shot;
     if (windowId) {
-        shot = await bridge.call("cg.captureWindow", { windowId });
+        shot = await bridge.call("cg.captureWindow", { windowId, safeCLI: isBrowserApp() });
     }
     else {
         shot = await bridge.call("cg.captureScreen");
@@ -337,7 +1578,28 @@ server.tool("ocr", "OCR a window with element positions. SLOW — prefer ui_tree
         const win = wins.find((w) => w.windowId === windowId);
         winBounds = win?.bounds;
     }
-    const regions = ocr.regions.map((r) => `"${r.text}" (${Math.round(r.bounds.x)},${Math.round(r.bounds.y)}) ${Math.round(r.bounds.width)}x${Math.round(r.bounds.height)}`);
+    const regions = ocr.regions.map((r) => {
+        let text = redactSensitiveLabel(r.text);
+        text = redactUsername(text);
+        // Redact URLs in OCR text
+        text = text.replace(/https?:\/\/[^\s"'`]+/g, (url) => sanitizeUrl(url));
+        return `"${text}" (${Math.round(r.bounds.x)},${Math.round(r.bounds.y)}) ${Math.round(r.bounds.width)}x${Math.round(r.bounds.height)}`;
+    });
+    // Feed OCR regions into world model
+    try {
+        if (windowId && Array.isArray(ocr.regions) && ocr.regions.length > 0) {
+            worldModel.ingestOCRRegions(windowId, ocr.regions.map((r) => ({
+                text: r.text,
+                bounds: {
+                    x: r.bounds.x,
+                    y: r.bounds.y,
+                    width: r.bounds.width,
+                    height: r.bounds.height,
+                },
+            })));
+        }
+    }
+    catch { /* world model update is best-effort */ }
     return {
         content: [{
                 type: "text",
@@ -358,13 +1620,32 @@ server.tool("ui_tree", "PREFERRED: Get the full UI element tree of an app via Ac
     maxDepth: z.number().optional().describe("Max depth (default 4). Use 2 for overview, 6+ for deep inspection."),
 }, async ({ pid, maxDepth }) => {
     await ensureBridge();
+    // Check if PID is running before querying AX tree (L3-04: uses fallback checks)
+    if (!(await isPidRunning(pid))) {
+        return { content: [{ type: "text", text: `PID ${pid} is not running. Call apps() to get current PIDs.` }] };
+    }
     const tree = await bridge.call("ax.getElementTree", { pid, maxDepth: maxDepth || 4 });
+    // Feed AX tree into world model for state tracking
+    try {
+        const wins = await bridge.call("window.list", {});
+        const win = wins?.find((w) => w.pid === pid);
+        if (win) {
+            worldModel.ingestAXTree(win.windowId, tree, {
+                bundleId: win.bundleId ?? "",
+                appName: win.bundleId ?? "",
+                pid,
+                windowTitle: win.title ?? "",
+                windowId: win.windowId,
+            });
+        }
+    }
+    catch { /* ignore — world model update is best-effort */ }
     function format(node, depth) {
         let line = "  ".repeat(depth) + (node.role || "?");
         if (node.title)
             line += ` "${node.title}"`;
         if (node.value)
-            line += ` =${String(node.value).slice(0, 60)}`;
+            line += ` =${String(node.value).slice(0, 200)}`;
         if (node.bounds)
             line += ` (${Math.round(node.bounds.x)},${Math.round(node.bounds.y)} ${Math.round(node.bounds.width)}x${Math.round(node.bounds.height)})`;
         let result = line;
@@ -374,34 +1655,107 @@ server.tool("ui_tree", "PREFERRED: Get the full UI element tree of an app via Ac
         }
         return result;
     }
-    return { content: [{ type: "text", text: format(tree, 0) }] };
+    return { content: [{ type: "text", text: redactUsername(format(tree, 0)) }] };
 });
-server.tool("ui_find", "Find a specific UI element by text/title. Returns its role, bounds, and path.", {
+server.tool("ui_find", "Find a specific UI element by text, title, or value. Falls back to value search if title match fails (e.g. finds Safari URL bar by URL).", {
     pid: z.number().describe("Process ID"),
-    title: z.string().describe("Text to search for (partial match)"),
-}, async ({ pid, title }) => {
+    title: z.string().describe("Text to search for — matches title first, then value (partial match)"),
+    role: z.string().optional().describe("AX role filter, e.g. AXButton, AXMenuItem, AXTextField"),
+    exact: z.boolean().optional().default(false).describe("Exact title match (default: partial)"),
+}, async ({ pid, title, role, exact }) => {
     await ensureBridge();
-    const r = await bridge.call("ax.findElement", { pid, title, exact: false });
+    if (!(await isPidRunning(pid))) {
+        return { content: [{ type: "text", text: `PID ${pid} is not running. Call apps() to get current PIDs.` }] };
+    }
+    let r;
+    try {
+        r = await bridge.call("ax.findElement", { pid, title, exact, ...(role ? { role } : {}) });
+    }
+    catch {
+        // Title search failed — retry searching by value (e.g. AXTextField with URL as value)
+        r = await bridge.call("ax.findElement", { pid, value: title, exact, ...(role ? { role } : {}) });
+    }
+    // Feed found element into world model as a minimal AX subtree
+    try {
+        if (r && r.role) {
+            const wins = await bridge.call("window.list", {});
+            const win = wins?.find((w) => w.pid === pid);
+            if (win) {
+                const subtree = {
+                    role: r.role,
+                    title: r.title ?? null,
+                    value: r.value ?? null,
+                    enabled: r.enabled ?? true,
+                    focused: r.focused ?? false,
+                    children: r.children ?? [],
+                };
+                if (r.bounds) {
+                    subtree.position = { x: r.bounds.x, y: r.bounds.y };
+                    subtree.size = { width: r.bounds.width, height: r.bounds.height };
+                }
+                worldModel.ingestAXTree(win.windowId, subtree, {
+                    bundleId: win.bundleId ?? "",
+                    appName: win.bundleId ?? "",
+                    pid,
+                    windowTitle: win.title ?? "",
+                    windowId: win.windowId,
+                });
+            }
+        }
+    }
+    catch { /* world model update is best-effort */ }
     return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
 });
 server.tool("ui_press", "PREFERRED: Find and press/click a UI element by its title via Accessibility. Faster and more reliable than click_text — no screenshot needed.", {
     pid: z.number().describe("Process ID"),
     title: z.string().describe("Element title to find and press"),
-}, async ({ pid, title }) => {
+    role: z.string().optional().describe("AX role filter, e.g. AXButton, AXMenuItem, AXTextField"),
+    exact: z.boolean().optional().default(false).describe("Exact title match (default: partial)"),
+}, async ({ pid, title, role, exact }) => {
     await ensureBridge();
-    const el = await bridge.call("ax.findElement", { pid, title, exact: false });
+    if (!(await isPidRunning(pid))) {
+        return { content: [{ type: "text", text: `PID ${pid} is not running. Call apps() to get current PIDs.` }] };
+    }
+    let el;
+    try {
+        el = await bridge.call("ax.findElement", { pid, title, exact, ...(role ? { role } : {}) });
+    }
+    catch {
+        try {
+            // Fallback: search by value (buttons/controls may have value instead of title)
+            el = await bridge.call("ax.findElement", { pid, value: title, exact, ...(role ? { role } : {}) });
+        }
+        catch {
+            // Check if a system dialog is blocking — different process owns the frontmost window
+            try {
+                const front = await bridge.call("app.frontmost", {});
+                if (front.pid !== pid) {
+                    return { content: [{ type: "text", text: `Element "${title}" not found in PID ${pid}. A system dialog from "${front.name}" (${front.bundleId}, PID ${front.pid}) may be blocking. Dismiss it first, or use click(x, y) to interact with the dialog directly.` }], isError: true };
+                }
+            }
+            catch { /* ignore frontmost check failure */ }
+            throw new Error(`Element "${title}" not found (searched title, value, and description)`);
+        }
+    }
     await bridge.call("ax.performAction", { pid, elementPath: el.elementPath, action: "AXPress" });
-    return { content: [{ type: "text", text: `Pressed "${el.title}" (${el.role})` }] };
+    return { content: [{ type: "text", text: `Pressed "${el.title || el.description || el.value}" (${el.role})` }] };
 });
-server.tool("ui_set_value", "Set the value of a UI element (text field, slider, etc.)", {
+server.tool("ui_set_value", "Set the value of a UI element (text field, slider, etc.). Searches by title first, falls back to value match.", {
     pid: z.number().describe("Process ID"),
     title: z.string().describe("Element title to find"),
     value: z.string().describe("Value to set"),
 }, async ({ pid, title, value }) => {
     await ensureBridge();
-    const el = await bridge.call("ax.findElement", { pid, title, exact: false });
+    let el;
+    try {
+        el = await bridge.call("ax.findElement", { pid, title, exact: false });
+    }
+    catch {
+        // Fallback: search by value (combo boxes, text fields often have no title)
+        el = await bridge.call("ax.findElement", { pid, value: title, exact: false });
+    }
     await bridge.call("ax.setElementValue", { pid, elementPath: el.elementPath, value });
-    return { content: [{ type: "text", text: `Set "${el.title}" = "${value}"` }] };
+    return { content: [{ type: "text", text: `Set "${el.title || el.value}" = "${value}"` }] };
 });
 server.tool("menu_click", "Click a menu item in an app's menu bar", {
     pid: z.number().describe("Process ID"),
@@ -417,73 +1771,309 @@ server.tool("menu_click", "Click a menu item in an app's menu bar", {
 server.tool("click", "Click at screen coordinates", {
     x: z.number().describe("Screen X"),
     y: z.number().describe("Screen Y"),
-}, async ({ x, y }) => {
+    button: z.enum(["left", "right", "middle"]).optional().default("left").describe("Mouse button (default: left)"),
+    clickCount: z.number().optional().default(1).describe("Click count: 1=single, 2=double (word select), 3=triple (line select)"),
+    modifiers: z.array(z.enum(["cmd", "shift", "alt", "ctrl"])).optional().describe("Hold modifier keys during click (e.g. ['cmd'] for cmd+click, ['shift'] for shift+click)"),
+    pid: z.number().optional().describe("Target process ID for PID-targeted event delivery"),
+}, async ({ x, y, button, clickCount, modifiers, pid }) => {
     await ensureBridge();
-    await bridge.call("cg.mouseMove", { x, y });
+    await bridge.call("cg.mouseMove", { x, y, targetPid: pid });
     await new Promise(r => setTimeout(r, 50));
-    await bridge.call("cg.mouseClick", { x, y });
-    return { content: [{ type: "text", text: `Clicked (${x}, ${y})` }] };
+    await bridge.call("cg.mouseClick", { x, y, button: button || "left", clickCount: clickCount || 1, modifiers: modifiers || [], targetPid: pid });
+    const extras = [];
+    if (modifiers?.length)
+        extras.push(modifiers.join("+"));
+    if (button && button !== "left")
+        extras.push(button);
+    if (clickCount && clickCount > 1)
+        extras.push(clickCount === 2 ? "double" : `${clickCount}x`);
+    return { content: [{ type: "text", text: `Clicked (${x}, ${y})${extras.length ? ` [${extras.join(", ")}]` : ""}` }] };
 });
 server.tool("click_text", "SLOW fallback: Find text on screen via OCR and click it. Use ui_press instead when possible — it's 10x faster. Only use this for canvas/image content where Accessibility doesn't work.", {
     windowId: z.number().describe("Window ID"),
     text: z.string().describe("Text to find and click"),
     offset_y: z.number().optional().describe("Y offset from text center (e.g. -25 for icon above label)"),
-}, async ({ windowId, text, offset_y }) => {
+    prefer: z.enum(["first", "largest", "topmost", "leftmost"]).optional().default("first").describe("Match preference when multiple OCR hits: largest (headers), topmost, leftmost (sidebar), first (OCR order)"),
+}, async ({ windowId, text, offset_y, prefer }) => {
     await ensureBridge();
     const wins = await bridge.call("app.windows");
     const win = wins.find((w) => w.windowId === windowId);
     if (!win)
         return { content: [{ type: "text", text: "Window not found" }] };
     const wb = win.bounds;
-    const shot = await bridge.call("cg.captureWindow", { windowId });
+    const shot = await bridge.call("cg.captureWindow", { windowId, safeCLI: isBrowserApp() });
     const ocr = await bridge.call("vision.ocr", { imagePath: shot.path });
-    const match = ocr.regions.find((r) => r.text.toLowerCase().includes(text.toLowerCase()));
-    if (!match) {
-        return { content: [{ type: "text", text: `"${text}" not found. Available: ${ocr.regions.map((r) => r.text).slice(0, 20).join(", ")}` }] };
-    }
-    const shadowL = (shot.width - wb.width * 2) / 2;
-    const shadowT = (shot.height - wb.height * 2) / 3;
-    const sx = wb.x + (match.bounds.x + match.bounds.width / 2 - shadowL) / 2;
-    const sy = wb.y + (match.bounds.y + match.bounds.height / 2 - shadowT) / 2 + (offset_y || 0);
+    const allMatches = ocr.regions.filter((r) => r.text.toLowerCase().includes(text.toLowerCase()));
+    if (allMatches.length === 0) {
+        return { content: [{ type: "text", text: `"${text}" not found. Available: ${ocr.regions.map((r) => r.text).slice(0, 20).join(", ")}` }], isError: true };
+    }
+    // Sort by preference strategy
+    if (prefer === "largest") {
+        allMatches.sort((a, b) => (b.bounds.width * b.bounds.height) - (a.bounds.width * a.bounds.height));
+    }
+    else if (prefer === "topmost") {
+        allMatches.sort((a, b) => a.bounds.y - b.bounds.y);
+    }
+    else if (prefer === "leftmost") {
+        allMatches.sort((a, b) => a.bounds.x - b.bounds.x);
+    }
+    const match = allMatches[0];
+    // Convert OCR pixel coordinates to screen coordinates.
+    // shot.width/height are in pixels; wb.width/height are in screen points.
+    // The scale factor handles both Retina (2x) and non-Retina (1x) displays.
+    //
+    // L3-05 fix: Window captures now use boundsIgnoreFraming to exclude shadow,
+    // so image dimensions match window bounds × backing scale (2x on Retina).
+    // Simple ratio mapping: OCR pixels → screen points.
+    const scaleX = shot.width > 0 ? wb.width / shot.width : 1;
+    const scaleY = shot.height > 0 ? wb.height / shot.height : 1;
+    const centerPixelX = match.bounds.x + match.bounds.width / 2;
+    const centerPixelY = match.bounds.y + match.bounds.height / 2;
+    let sx = Math.round(wb.x + centerPixelX * scaleX);
+    let sy = Math.round(wb.y + centerPixelY * scaleY + (offset_y || 0));
+    // Clamp to window bounds — OCR boxes can extend slightly beyond the window
+    sx = Math.max(wb.x + 2, Math.min(sx, wb.x + wb.width - 2));
+    sy = Math.max(wb.y + 2, Math.min(sy, wb.y + wb.height - 2));
     await bridge.call("cg.mouseMove", { x: sx, y: sy });
-    await new Promise(r => setTimeout(r, 50));
+    await new Promise(r => setTimeout(r, 80)); // 80ms dwell — longer than 50ms helps dense UIs register hover
     await bridge.call("cg.mouseClick", { x: sx, y: sy });
-    return { content: [{ type: "text", text: `Clicked "${match.text}" at (${Math.round(sx)}, ${Math.round(sy)})` }] };
+    let response = `Clicked "${match.text}" at screen (${Math.round(sx)}, ${Math.round(sy)}) ` +
+        `[OCR pixel: (${Math.round(match.bounds.x)}, ${Math.round(match.bounds.y)}) ${match.bounds.width}×${match.bounds.height}] ` +
+        `[window: (${wb.x}, ${wb.y}) ${wb.width}×${wb.height}] ` +
+        `[scale: ${scaleX.toFixed(3)}×${scaleY.toFixed(3)}]`;
+    if (allMatches.length > 1) {
+        response += ` [${allMatches.length} matches, used prefer="${prefer}"]`;
+        response += `\n⚠ ${allMatches.length} matches found. Use prefer param or offset_y to disambiguate.`;
+    }
+    return { content: [{ type: "text", text: response }] };
 });
-server.tool("type_text", "Type text using the keyboard", {
+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"),
-}, async ({ text }) => {
-    await ensureBridge();
-    await bridge.call("cg.typeText", { text });
-    return { content: [{ type: "text", text: "Typed: " + text }] };
-});
-server.tool("key", "Press a key combination", {
-    combo: z.string().describe("Key combo: 'cmd+c', 'enter', 'cmd+shift+n', 'space'. Use + to separate."),
-}, async ({ combo }) => {
+    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."),
+}, async ({ text, pid, cdpPort: portOverride }) => {
     await ensureBridge();
-    await bridge.call("cg.keyCombo", { keys: combo.split("+") });
-    return { content: [{ type: "text", text: "Key: " + combo }] };
-});
-server.tool("drag", "Drag from one point to another", {
-    fromX: z.number(), fromY: z.number(),
-    toX: z.number(), toY: z.number(),
-}, async ({ fromX, fromY, toX, toY }) => {
-    await ensureBridge();
-    await bridge.call("cg.mouseDrag", { fromX, fromY, toX, toY });
-    return { content: [{ type: "text", text: `Dragged (${fromX},${fromY}) → (${toX},${toY})` }] };
-});
-server.tool("scroll", "Scroll at a position", {
-    x: z.number(), y: z.number(),
+    // Auto-resolve frontmost PID when none provided — global HID posting
+    // fails silently in NSTextView apps (TextEdit, etc.), but PID-targeted
+    // delivery works reliably in all apps.
+    let targetPid = pid;
+    if (!targetPid) {
+        try {
+            const front = await bridge.call("app.frontmost", {});
+            targetPid = front.pid;
+        }
+        catch {
+            // Fallback to global posting if frontmost detection fails
+        }
+    }
+    // Verify the target process exists and has windows
+    if (targetPid) {
+        try {
+            const apps = await bridge.call("app.list", {});
+            let app = apps?.find((a) => a.pid === targetPid);
+            if (!app) {
+                // L3-04 fix: Some Electron apps (Slack, Discord) don't appear in NSWorkspace.runningApplications
+                // despite being frontmost. Check app.frontmost as fallback before rejecting.
+                try {
+                    const front = await bridge.call("app.frontmost", {});
+                    if (front.pid === targetPid) {
+                        app = front;
+                    }
+                }
+                catch { /* ignore */ }
+                if (!app) {
+                    return { content: [{ type: "text", text: `PID ${targetPid} is not running. Call apps() to get current PIDs.` }] };
+                }
+            }
+            const wins = await bridge.call("window.list", { pid: targetPid });
+            if (!wins || wins.length === 0) {
+                return { content: [{ type: "text", text: `Warning: PID ${targetPid} (${app.name}) has no windows. Keystrokes may be lost. Open a document first.` }] };
+            }
+        }
+        catch {
+            // Best-effort check — proceed with typing if validation fails
+        }
+    }
+    // L3-02 fix: Raise the specific window before typing to ensure keystrokes land correctly.
+    // Without this, Electron apps with multiple instances can lose keystrokes to the wrong window,
+    // or text can go to a non-editor area (e.g. Walkthrough tab instead of editor).
+    if (targetPid) {
+        try {
+            const winId = await resolveWindowId(targetPid);
+            if (winId != null) {
+                await bridge.call("window.focus", { windowId: winId });
+            }
+        }
+        catch { /* best-effort — proceed with typing */ }
+    }
+    // L3-02 fix: Electron CDP typing — routes through CDP Input.dispatchKeyEvent
+    // when cdpPort is specified or auto-detected. Solves Copilot chat / panel focus
+    // theft where AX keystrokes go to chat input instead of Monaco editor.
+    let electronCdpPort = portOverride;
+    if (!electronCdpPort && targetPid) {
+        // Auto-detect: probe Electron-common CDP ports, but ONLY use if the CDP target
+        // belongs to the same app we're targeting. Without this check, typing to Slack
+        // could get routed through VS Code's CDP port 9229.
+        try {
+            // Look up target app name for matching
+            let targetAppName = "";
+            try {
+                const apps = await bridge.call("app.list", {});
+                const app = apps?.find((a) => a.pid === targetPid);
+                targetAppName = (app?.name || "").toLowerCase();
+                if (!targetAppName) {
+                    const front = await bridge.call("app.frontmost", {});
+                    if (front.pid === targetPid)
+                        targetAppName = (front.name || "").toLowerCase();
+                }
+            }
+            catch { /* ignore */ }
+            for (const p of [9229, 9333]) {
+                try {
+                    if (!CDP)
+                        CDP = (await import("chrome-remote-interface")).default;
+                    const version = await CDP.Version({ port: p });
+                    // Verify the CDP target matches the target app — check if the browser name
+                    // or any page title contains the app name (e.g. "Code" in VS Code page titles)
+                    const browserName = (version?.Browser || "").toLowerCase();
+                    if (targetAppName && !browserName.includes(targetAppName)) {
+                        // Double-check against page titles
+                        try {
+                            const targets = await CDP.List({ port: p });
+                            const titleMatch = targets?.some((t) => (t.title || "").toLowerCase().includes(targetAppName));
+                            if (!titleMatch)
+                                continue; // CDP doesn't belong to target app — skip
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    electronCdpPort = p;
+                    break;
+                }
+                catch { /* not available on this port */ }
+            }
+        }
+        catch { /* auto-detect is best-effort */ }
+    }
+    if (electronCdpPort) {
+        // CDP path: click editor to ensure focus, then type via key events
+        try {
+            const { client } = await getCDPClient(undefined, electronCdpPort);
+            // Click the editor area to grab focus from Copilot/panels
+            await client.Runtime.evaluate({
+                expression: `(() => {
+          const editor = document.querySelector('.monaco-editor .view-lines');
+          if (editor) { editor.click(); return true; }
+          // Generic fallback: focus the first contenteditable or active editor context
+          const editable = document.querySelector('[contenteditable="true"]') || document.querySelector('.native-edit-context');
+          if (editable) { editable.focus(); return true; }
+          return false;
+        })()`,
+                returnByValue: true,
+            });
+            await randomDelay(30, 60);
+            // Type character by character via CDP Input.dispatchKeyEvent
+            for (const char of text) {
+                await client.Input.dispatchKeyEvent({ type: "keyDown", text: char, key: char, unmodifiedText: char });
+                await client.Input.dispatchKeyEvent({ type: "keyUp", text: char, key: char, unmodifiedText: char });
+                await randomDelay(10, 30);
+            }
+            await client.close();
+            const msg = `Typed via CDP (port ${electronCdpPort}): "${text}"`;
+            return { content: [{ type: "text", text: msg }] };
+        }
+        catch (cdpErr) {
+            // CDP failed — fall through to AX typing
+        }
+    }
+    // AX path: standard cg.typeText via native bridge
+    // L2-66 fix: Auto-chunk long text to prevent bridge timeout.
+    // cg.typeText simulates individual keystrokes, so >500 chars can be slow.
+    const CHUNK_SIZE = 500;
+    if (text.length > CHUNK_SIZE) {
+        for (let i = 0; i < text.length; i += CHUNK_SIZE) {
+            const chunk = text.slice(i, i + CHUNK_SIZE);
+            await bridge.call("cg.typeText", { text: chunk, targetPid });
+        }
+    }
+    else {
+        await bridge.call("cg.typeText", { text, targetPid });
+    }
+    const msg = targetPid ? `Typed to PID ${targetPid}: "${text}"` : "Typed: " + text;
+    return { content: [{ type: "text", text: msg }] };
+});
+server.tool("key", "Press a key combination", {
+    combo: z.string().describe("Key combo: 'cmd+c', 'enter', 'cmd+shift+n', 'space'. Use + to separate."),
+    holdMs: z.number().optional().describe("Hold the key for this many ms (for accent picker, long-press menus). Default: tap."),
+    pid: z.number().optional().describe("Target process ID for PID-targeted event delivery"),
+}, async ({ combo, holdMs, pid }) => {
+    await ensureBridge();
+    // Auto-resolve frontmost PID when none provided — ensures keystrokes
+    // reach the correct app (same pattern as type_text auto-PID).
+    let targetPid = pid;
+    if (!targetPid) {
+        try {
+            const front = await bridge.call("app.frontmost", {});
+            targetPid = front.pid;
+        }
+        catch { /* fallback to global posting */ }
+    }
+    const keys = combo.split("+");
+    const hasModifier = keys.some(k => ["cmd", "ctrl", "alt", "shift"].includes(k.toLowerCase()));
+    // macOS only processes modifier shortcuts (cmd+c, cmd+n, etc.) for the frontmost app.
+    // When pid is targeted with modifiers, raise the specific window first.
+    // L3-01 fix: use window.focus(windowId) instead of app.focus(bundleId) to avoid
+    // targeting the wrong instance when multiple Electron apps share the same bundleId.
+    if (targetPid && hasModifier) {
+        try {
+            const winId = await resolveWindowId(targetPid);
+            if (winId != null) {
+                await bridge.call("window.focus", { windowId: winId });
+            }
+            else {
+                // Fallback to bundleId-based focus if no window found
+                const apps = await bridge.call("app.list", {});
+                const target = apps.find(a => a.pid === targetPid);
+                if (target) {
+                    await bridge.call("app.focus", { bundleId: target.bundleId });
+                }
+            }
+        }
+        catch { /* focus is best-effort */ }
+    }
+    // Press-and-hold mode for accent picker / long-press menus
+    if (holdMs && !hasModifier && keys.length === 1) {
+        await bridge.call("cg.keyPressAndHold", { key: keys[0], durationMs: holdMs, targetPid });
+        return { content: [{ type: "text", text: `Key held: ${combo} (${holdMs}ms)` + (targetPid ? ` (PID ${targetPid})` : "") }] };
+    }
+    await bridge.call("cg.keyCombo", { keys, targetPid });
+    return { content: [{ type: "text", text: `Key: ${combo}` + (targetPid ? ` (PID ${targetPid})` : "") }] };
+});
+server.tool("drag", "Drag from one point to another", {
+    fromX: z.number(), fromY: z.number(),
+    toX: z.number(), toY: z.number(),
+    modifiers: z.array(z.enum(["cmd", "shift", "alt", "ctrl"])).optional().describe("Hold modifier keys during drag (e.g. ['alt'] for option+drag copy in Finder)"),
+    pid: z.number().optional().describe("Target process ID for PID-targeted event delivery"),
+}, async ({ fromX, fromY, toX, toY, modifiers, pid }) => {
+    await ensureBridge();
+    await bridge.call("cg.mouseDrag", { fromX, fromY, toX, toY, modifiers: modifiers || [], targetPid: pid });
+    const modStr = modifiers?.length ? ` [${modifiers.join("+")}]` : "";
+    return { content: [{ type: "text", text: `Dragged (${fromX},${fromY}) → (${toX},${toY})${modStr}` }] };
+});
+server.tool("scroll", "Scroll at a position", {
+    x: z.number(), y: z.number(),
     deltaX: z.number().optional().describe("Horizontal scroll (default 0)"),
     deltaY: z.number().describe("Vertical scroll (negative = down)"),
-}, async ({ x, y, deltaX, deltaY }) => {
+    pid: z.number().optional().describe("Target process ID for PID-targeted event delivery"),
+}, async ({ x, y, deltaX, deltaY, pid }) => {
     await ensureBridge();
-    await bridge.call("cg.scroll", { x, y, deltaX: deltaX || 0, deltaY });
+    await bridge.call("cg.scroll", { x, y, deltaX: deltaX || 0, deltaY, targetPid: pid });
     return { content: [{ type: "text", text: "Scrolled" }] };
 });
 // ── CDP helper: get client for a tab ──
-async function getCDPClient(tabId) {
-    const { CDP: cdp, port } = await ensureCDP();
+async function getCDPClient(tabId, overridePort) {
+    const { CDP: cdp, port } = await ensureCDP(overridePort);
     let targetId = tabId;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -493,6 +2083,11 @@ async function getCDPClient(tabId) {
         targetId = page.id;
     }
     const client = await cdp({ port, target: targetId });
+    // Activate CDP source in perception when a browser connection is established
+    try {
+        perceptionManager.activateCDP(client);
+    }
+    catch { /* best-effort */ }
     return { client, targetId: targetId, CDP: cdp, port };
 }
 // ── Random delay helper ──
@@ -502,25 +2097,54 @@ function randomDelay(min, max) {
 // ═══════════════════════════════════════════════
 // BROWSER — control Chrome pages via CDP (10ms, not OCR)
 // ═══════════════════════════════════════════════
-server.tool("browser_tabs", "List all open Chrome tabs", {}, async () => {
-    const { CDP: cdp, port } = await ensureCDP();
+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."),
+}, async ({ cdpPort: portOverride }) => {
+    const { CDP: cdp, port } = await ensureCDP(portOverride);
     const targets = await cdp.List({ port });
     const pages = targets.filter((t) => t.type === "page");
     const lines = pages.map((t) => `[${t.id}] ${t.title} — ${t.url}`);
     return { content: [{ type: "text", text: lines.join("\n") || "No tabs open" }] };
 });
-server.tool("browser_open", "Open a URL in Chrome (creates new tab)", {
+server.tool("browser_open", "Open a URL in Chrome/Electron (creates new tab)", {
     url: z.string().describe("URL to open"),
-}, async ({ url }) => {
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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:"];
+    const urlLower = url.trim().toLowerCase();
+    for (const proto of BLOCKED_PROTOCOLS) {
+        if (urlLower.startsWith(proto)) {
+            throw new Error(`Blocked: "${proto}" URLs are not allowed in browser_open for security reasons.`);
+        }
+    }
+    // Capture bundleId BEFORE CDP call to prevent focus-change race
+    const browserBundleId = worldModel.getState().focusedApp?.bundleId ?? "com.google.Chrome";
+    const { CDP: cdp, port } = await ensureCDP(portOverride);
     const target = await cdp.New({ port, url });
+    // Feed new tab into world model
+    try {
+        worldModel.ingestCDPSnapshot(browserBundleId, url, target.title ?? url);
+    }
+    catch { /* world model update is best-effort */ }
     return { content: [{ type: "text", text: `Opened: ${target.id} — ${url}` }] };
 });
-server.tool("browser_navigate", "Navigate the active Chrome tab to a URL", {
+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."),
-}, async ({ url, tabId }) => {
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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:"];
+    const urlLower = url.trim().toLowerCase();
+    for (const proto of BLOCKED_PROTOCOLS) {
+        if (urlLower.startsWith(proto)) {
+            throw new Error(`Blocked: "${proto}" URLs are not allowed in browser_navigate for security reasons. Use browser_js for JavaScript execution.`);
+        }
+    }
+    // Capture bundleId BEFORE CDP call to prevent focus-change race
+    const browserBundleId = worldModel.getState().focusedApp?.bundleId ?? "com.google.Chrome";
+    const { CDP: cdp, port } = await ensureCDP(portOverride);
     let targetId = tabId;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -540,16 +2164,23 @@ server.tool("browser_navigate", "Navigate the active Chrome tab to a URL", {
             break;
         await new Promise(r => setTimeout(r, 200));
     }
-    const title = await client.Runtime.evaluate({ expression: "document.title", returnByValue: true });
+    const titleResult = await client.Runtime.evaluate({ expression: "document.title", returnByValue: true });
+    const pageTitle = titleResult.result.value ?? "";
     await client.close();
-    return { content: [{ type: "text", text: `Navigated to: ${title.result.value}` }] };
+    // Feed navigation result into world model
+    try {
+        worldModel.ingestCDPSnapshot(browserBundleId, url, pageTitle);
+    }
+    catch { /* world model update is best-effort */ }
+    return { content: [{ type: "text", text: `Navigated to: ${pageTitle}` }] };
 });
-server.tool("browser_js", "Execute JavaScript in a Chrome tab. Returns the result. WARNING: This runs arbitrary JS in the browser context — avoid on sensitive pages (banking, email). All executions are audit-logged.", {
+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."),
-}, async ({ code, tabId }) => {
-    auditLog("browser_js", { code: code.slice(0, 500), tabId });
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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);
     let targetId = tabId;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -570,15 +2201,21 @@ server.tool("browser_js", "Execute JavaScript in a Chrome tab. Returns the resul
         return { content: [{ type: "text", text: `JS Error: ${result.exceptionDetails.text}\n${result.exceptionDetails.exception?.description || ""}` }] };
     }
     const val = result.result.value;
-    const text = typeof val === "object" ? JSON.stringify(val, null, 2) : String(val ?? "undefined");
+    let text = typeof val === "object" ? JSON.stringify(val, null, 2) : String(val ?? "undefined");
+    // Redact sensitive URLs and tokens in JS output
+    text = text.replace(/https?:\/\/[^\s"'`]+/g, (url) => sanitizeUrl(url));
+    text = redactSensitiveLabel(text);
     return { content: [{ type: "text", text }] };
 });
-server.tool("browser_dom", "Query the DOM of a Chrome page. Returns matching elements' text, attributes, and structure.", {
+server.tool("browser_dom", "Query the DOM of a Chrome/Electron page. Returns matching elements' text, attributes, and structure.", {
     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)"),
-}, async ({ selector, tabId, limit }) => {
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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";
+    const { CDP: cdp, port } = await ensureCDP(portOverride);
     let targetId = tabId;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -607,14 +2244,27 @@ server.tool("browser_dom", "Query the DOM of a Chrome page. Returns matching ele
     })()`,
         returnByValue: true,
     });
+    // Feed page info into world model while client is still open
+    try {
+        const pageInfo = await client.Runtime.evaluate({
+            expression: `({ url: location.href, title: document.title })`,
+            returnByValue: true,
+        });
+        const info = pageInfo.result.value;
+        if (info?.url) {
+            worldModel.ingestCDPSnapshot(browserBundleId, info.url, info.title ?? "");
+        }
+    }
+    catch { /* world model update is best-effort */ }
     await client.close();
     return { content: [{ type: "text", text: JSON.stringify(result.result.value, null, 2) }] };
 });
-server.tool("browser_click", "Click an element in Chrome by CSS selector. Uses CDP Input.dispatchMouseEvent for realistic mouse events.", {
+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."),
-}, async ({ selector, tabId }) => {
-    const { client } = await getCDPClient(tabId);
+    cdpPort: z.number().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();
     const result = await client.Runtime.evaluate({
         expression: `(() => {
@@ -640,13 +2290,14 @@ server.tool("browser_click", "Click an element in Chrome by CSS selector. Uses C
     await client.close();
     return { content: [{ type: "text", text: `Clicked: "${val.text}" at (${Math.round(x)}, ${Math.round(y)})` }] };
 });
-server.tool("browser_type", "Type into an input field in Chrome. Uses CDP Input.dispatchKeyEvent for real keyboard events (works with React/Angular).", {
+server.tool("browser_type", "Type into an input field in Chrome/Electron. Uses CDP Input.dispatchKeyEvent for real keyboard events (works with React/Angular).", {
     selector: z.string().describe("CSS selector of the input"),
     text: z.string().describe("Text to type"),
     clear: z.boolean().optional().describe("Clear field first (default true)"),
     tabId: z.string().optional().describe("Tab ID"),
-}, async ({ selector, text, clear, tabId }) => {
-    const { client } = await getCDPClient(tabId);
+    cdpPort: z.number().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();
     // Focus the element
     const focusResult = await client.Runtime.evaluate({
@@ -681,12 +2332,13 @@ server.tool("browser_type", "Type into an input field in Chrome. Uses CDP Input.
     await client.close();
     return { content: [{ type: "text", text: `Typed "${text}"` }] };
 });
-server.tool("browser_wait", "Wait for a condition on a Chrome page", {
+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"),
-}, async ({ condition, timeoutMs, tabId }) => {
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -712,8 +2364,11 @@ server.tool("browser_wait", "Wait for a condition on a Chrome page", {
 });
 server.tool("browser_page_info", "Get current page title, URL, and text content summary", {
     tabId: z.string().optional().describe("Tab ID"),
-}, async ({ tabId }) => {
-    const { CDP: cdp, port } = await ensureCDP();
+    cdpPort: z.number().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";
+    const { CDP: cdp, port } = await ensureCDP(portOverride);
     let targetId = tabId;
     if (!targetId) {
         const targets = await cdp.List({ port });
@@ -733,6 +2388,14 @@ server.tool("browser_page_info", "Get current page title, URL, and text content
         returnByValue: true,
     });
     await client.close();
+    // Feed page info into world model
+    try {
+        const info = result.result.value;
+        if (info?.url) {
+            worldModel.ingestCDPSnapshot(browserBundleId, info.url, info.title ?? "");
+        }
+    }
+    catch { /* world model update is best-effort */ }
     return { content: [{ type: "text", text: JSON.stringify(result.result.value, null, 2) }] };
 });
 // ═══════════════════════════════════════════════
@@ -774,10 +2437,11 @@ if (origQuery) {
   };
 }
 `;
-server.tool("browser_stealth", "Inject anti-detection patches into Chrome page. Call once after navigating to a protected site. Hides webdriver flag, patches plugins/languages/permissions.", {
+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."),
-}, async ({ tabId }) => {
-    const { client } = await getCDPClient(tabId);
+    cdpPort: z.number().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();
     await client.Page.addScriptToEvaluateOnNewDocument({ source: STEALTH_SCRIPT });
     // Also evaluate immediately on current page
@@ -795,8 +2459,9 @@ 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"),
-}, async ({ selector, text, clear, delayMs, tabId }) => {
-    const { client } = await getCDPClient(tabId);
+    cdpPort: z.number().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();
     // Focus the element
     const focusResult = await client.Runtime.evaluate({
@@ -834,14 +2499,15 @@ server.tool("browser_fill_form", "Fill a form field with human-like typing (anti
     await client.close();
     return { content: [{ type: "text", text: `Typed "${text}" (${text.length} chars, human-like)` }] };
 });
-server.tool("browser_human_click", "Click an element with realistic mouse events (anti-detection). Dispatches mouseMoved → mousePressed → mouseReleased at element coordinates.", {
+// browser_human_click — alias for browser_click (both already use realistic mouse events)
+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."),
-}, async ({ selector, tabId }) => {
-    const { client } = await getCDPClient(tabId);
+    cdpPort: z.number().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();
-    // Get element center coordinates
-    const rectResult = await client.Runtime.evaluate({
+    const result = await client.Runtime.evaluate({
         expression: `(() => {
       const el = document.querySelector(${JSON.stringify(selector)});
       if (!el) return { ok: false, reason: "Element not found: ${selector.replace(/"/g, '\\"')}" };
@@ -851,13 +2517,12 @@ server.tool("browser_human_click", "Click an element with realistic mouse events
     })()`,
         returnByValue: true,
     });
-    const val = rectResult.result.value;
+    const val = result.result.value;
     if (!val?.ok) {
         await client.close();
         return { content: [{ type: "text", text: val?.reason || "Element not found" }] };
     }
     const { x, y } = val;
-    // Simulate realistic mouse event sequence
     await client.Input.dispatchMouseEvent({ type: "mouseMoved", x, y });
     await randomDelay(30, 60);
     await client.Input.dispatchMouseEvent({ type: "mousePressed", x, y, button: "left", clickCount: 1 });
@@ -869,19 +2534,30 @@ server.tool("browser_human_click", "Click an element with realistic mouse events
 // ═══════════════════════════════════════════════
 // PLATFORM PLAYBOOKS — lazy-loaded site knowledge
 // ═══════════════════════════════════════════════
-const playbooksDir = path.resolve(__dirname, "playbooks");
-server.tool("platform_guide", "Get automation guide for a platform (selectors, URLs, flows, error solutions). Available: devpost. Zero cost — only loads when called.", {
-    platform: z.string().describe("Platform name, e.g. 'devpost'"),
+const coverageAuditor = new CoverageAuditor(referencesDir, playbooksDir, learningEngine, goalStore);
+server.tool("platform_guide", "Get automation guide for a platform (selectors, URLs, flows, error solutions). Reads from references/ (curated knowledge). Zero cost — only loads when called.", {
+    platform: z.string().describe("Platform name, e.g. 'figma', 'x-twitter', 'devpost'"),
     section: z.enum(["all", "urls", "flows", "selectors", "errors", "detection"]).optional().describe("Section to return (default: all). Use 'errors' for just error+solution pairs."),
 }, async ({ platform, section }) => {
-    const filePath = path.resolve(playbooksDir, `${platform.toLowerCase()}.json`);
+    const safePlatName = platform.toLowerCase().replace(/[^a-z0-9_\-]/g, "_").slice(0, 100);
+    const filePath = path.resolve(referencesDir, `${safePlatName}.json`);
+    if (!filePath.startsWith(path.resolve(referencesDir))) {
+        return { content: [{ type: "text", text: `Error: invalid platform name "${platform}"` }] };
+    }
     if (!fs.existsSync(filePath)) {
-        const available = fs.existsSync(playbooksDir)
-            ? fs.readdirSync(playbooksDir).filter(f => f.endsWith(".json")).map(f => f.replace(".json", ""))
+        const available = fs.existsSync(referencesDir)
+            ? fs.readdirSync(referencesDir).filter(f => f.endsWith(".json")).map(f => f.replace(".json", ""))
             : [];
         return { content: [{ type: "text", text: `No playbook for "${platform}". Available: ${available.join(", ") || "none"}` }] };
     }
-    const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    // L2-73 fix: Gracefully handle malformed reference JSON
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch (parseErr) {
+        return { content: [{ type: "text", text: `Warning: reference file for "${platform}" is malformed and was skipped. Error: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}` }] };
+    }
     const s = section || "all";
     if (s === "errors") {
         const errors = data.errors || [];
@@ -915,6 +2591,152 @@ server.tool("platform_guide", "Get automation guide for a platform (selectors, U
     // "all" — return full playbook
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
+server.tool("playbook_preflight", "Quick feasibility check before automating a platform. Scans the page for known blockers (captchas, WebGL, iframes), checks against playbook errors, tests selector availability. Returns go/yellow/red.", {
+    url: z.string().describe("URL to check, e.g. 'https://x.com'"),
+    task: z.string().optional().describe("What you want to automate, e.g. 'post a tweet'"),
+    tabId: z.string().optional().describe("Tab ID if page is already open"),
+}, async ({ url, task, tabId }) => {
+    const issues = [];
+    const warnings = [];
+    const good = [];
+    // 1. Extract domain and find matching playbook
+    let domain;
+    try {
+        domain = new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return { content: [{ type: "text", text: `❌ Invalid URL: ${url}` }] };
+    }
+    // Check references/ for curated knowledge
+    const reference = _playbookStoreForContext.matchByDomain(domain);
+    if (reference) {
+        good.push(`Found reference: "${reference.id}" (${reference.successCount} successes, ${reference.failCount} failures)`);
+        // Check known errors
+        if (reference.errors && reference.errors.length > 0) {
+            for (const err of reference.errors) {
+                if (err.severity === "high") {
+                    issues.push(`🔴 ${err.error} → ${err.solution}`);
+                }
+                else {
+                    warnings.push(`🟡 ${err.error} → ${err.solution}`);
+                }
+            }
+        }
+        // Check selector availability
+        if (reference.selectors) {
+            const selectorCount = Object.values(reference.selectors).reduce((sum, group) => sum + Object.keys(group).length, 0);
+            good.push(`${selectorCount} selectors documented in reference`);
+        }
+        if (reference.flows && Object.keys(reference.flows).length > 0) {
+            good.push(`${Object.keys(reference.flows).length} flows documented`);
+        }
+    }
+    else {
+        warnings.push(`🟡 No playbook exists for ${domain} — first-time automation, expect trial and error`);
+    }
+    // Check playbooks/ for executable steps
+    const execPlaybookPath = path.resolve(playbooksDir, `${reference?.id ?? domain.split(".")[0]}.json`);
+    if (fs.existsSync(execPlaybookPath)) {
+        try {
+            const execPb = JSON.parse(fs.readFileSync(execPlaybookPath, "utf-8"));
+            if (Array.isArray(execPb.steps) && execPb.steps.length > 0) {
+                good.push(`Executable playbook found: ${execPb.steps.length} steps — use job_create(playbookId="${execPb.id}") for auto-run`);
+            }
+        }
+        catch { /* skip */ }
+    }
+    else if (reference) {
+        warnings.push(`🟡 Reference exists but no executable playbook — manual execution needed`);
+    }
+    // 2. Scan the page if we have CDP access
+    try {
+        const { CDP: cdp, port } = await ensureCDP();
+        let targetId = tabId;
+        if (!targetId) {
+            const targets = await cdp.List({ port });
+            const page = targets.find((t) => t.type === "page" && t.url?.includes(domain));
+            targetId = page?.id;
+        }
+        if (targetId) {
+            const client = await cdp({ port, target: targetId });
+            // Check for common blockers
+            const checks = await client.Runtime.evaluate({
+                expression: `(() => {
+          const results = {};
+          // Captcha detection
+          results.hasCaptcha = !!(
+            document.querySelector('[class*="captcha"]') ||
+            document.querySelector('[class*="recaptcha"]') ||
+            document.querySelector('[data-sitekey]') ||
+            document.querySelector('iframe[src*="captcha"]') ||
+            document.querySelector('iframe[src*="recaptcha"]')
+          );
+          // WebGL canvas (can't click via DOM)
+          results.hasWebGL = !!(document.querySelector('canvas[data-engine]') || document.querySelector('canvas.webgl'));
+          // Shadow DOM
+          const allEls = document.querySelectorAll('*');
+          let shadowCount = 0;
+          for (const el of allEls) { if (el.shadowRoot) shadowCount++; }
+          results.shadowDomCount = shadowCount;
+          // Iframes
+          results.iframeCount = document.querySelectorAll('iframe').length;
+          // React/SPA detection
+          results.isReact = !!(window.__REACT_DEVTOOLS_GLOBAL_HOOK__ || document.querySelector('[data-reactroot]'));
+          results.isNextJs = !!document.querySelector('#__next');
+          results.pageTitle = document.title;
+          results.url = location.href;
+          return results;
+        })()`,
+                returnByValue: true,
+            });
+            await client.close();
+            const r = checks.result.value;
+            if (r) {
+                good.push(`Page loaded: "${r.pageTitle}"`);
+                if (r.hasCaptcha)
+                    issues.push(`🔴 CAPTCHA detected — cannot be automated, needs manual solve`);
+                if (r.hasWebGL)
+                    warnings.push(`🟡 WebGL canvas detected — DOM clicks won't work, use Input.dispatchMouseEvent or coordinates`);
+                if (r.shadowDomCount > 0)
+                    warnings.push(`🟡 ${r.shadowDomCount} Shadow DOM elements — standard selectors may not reach them`);
+                if (r.iframeCount > 0)
+                    warnings.push(`🟡 ${r.iframeCount} iframes — may need to switch context`);
+                if (r.isReact)
+                    warnings.push(`🟡 React app — el.value assignment may not work, use browser_fill_form instead`);
+            }
+        }
+        else {
+            warnings.push(`🟡 Page not open in Chrome — open ${url} first for deeper scan`);
+        }
+    }
+    catch {
+        warnings.push(`🟡 Chrome CDP not available — can't scan page. Launch Chrome with --remote-debugging-port=9222`);
+    }
+    // 3. Check memory for past errors on this domain
+    const memErrors = memory.readErrors();
+    const domainErrors = memErrors.filter(e => {
+        const paramStr = JSON.stringify(e.params ?? {});
+        return paramStr.includes(domain);
+    });
+    if (domainErrors.length > 0) {
+        warnings.push(`🟡 ${domainErrors.length} past error(s) recorded for ${domain} in memory`);
+    }
+    // 4. Build verdict
+    const rating = issues.length > 0 ? "🔴 RED" : warnings.length > 2 ? "🟡 YELLOW" : "🟢 GREEN";
+    const lines = [
+        `# Preflight: ${domain}`,
+        `Rating: ${rating}`,
+        "",
+        ...good.map(g => `✅ ${g}`),
+        ...(issues.length > 0 ? ["", "## Blockers", ...issues] : []),
+        ...(warnings.length > 0 ? ["", "## Warnings", ...warnings] : []),
+        "",
+        issues.length > 0
+            ? "⛔ Some tasks may not be fully automatable. Review blockers above."
+            : "✅ Looks feasible. Proceed with automation.",
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
 server.tool("export_playbook", "Generate a playbook JSON from your session. Extracts URLs, selectors, errors+solutions from memory. Share the output with ScreenHand to help others automate this platform.", {
     platform: z.string().describe("Platform name, e.g. 'linkedin', 'twitter'"),
     domain: z.string().describe("Domain to filter actions by, e.g. 'linkedin.com'"),
@@ -968,7 +2790,7 @@ server.tool("export_playbook", "Generate a playbook JSON from your session. Extr
         s.tags.some(t => t.toLowerCase().includes(platform.toLowerCase())));
     // 2. Scan current page for selectors if tab is available
     let pageSelectors = {};
-    if (tabId || true) {
+    if (tabId) {
         try {
             const { client } = await getCDPClient(tabId);
             await client.Runtime.enable();
@@ -1008,13 +2830,24 @@ server.tool("export_playbook", "Generate a playbook JSON from your session. Extr
         description: description || `Automation playbook for ${platform}`,
         urls: Object.fromEntries(Array.from(urlSet).sort().map((u, i) => {
             const urlObj = new URL(u);
+            // L2-69 fix: Redact sensitive query params before exporting
+            const sensitiveParams = new Set(["code", "token", "access_token", "refresh_token", "id_token",
+                "secret", "password", "key", "api_key", "apikey", "auth",
+                "session", "session_id", "sessionid", "state", "nonce"]);
+            for (const paramName of urlObj.searchParams.keys()) {
+                if (sensitiveParams.has(paramName.toLowerCase())) {
+                    urlObj.searchParams.set(paramName, "[REDACTED]");
+                }
+            }
+            const safeUrl = urlObj.toString();
             const pathKey = urlObj.pathname.replace(/^\//, "").replace(/\//g, "_").replace(/[^a-zA-Z0-9_]/g, "") || "home";
-            return [pathKey, u];
+            return [pathKey, safeUrl];
         })),
         flows: {
             discovered: {
+                // S75 Option C: Redact PII from exported strategy steps
                 steps: domainStrategies.length > 0
-                    ? domainStrategies[0].steps.map((s) => `${s.tool}(${JSON.stringify(s.params)})`)
+                    ? domainStrategies[0].steps.map((s) => redactPII(`${s.tool}(${JSON.stringify(s.params)})`))
                     : ["No strategies recorded yet. Use the platform, then call export_playbook again."],
                 selectors: pageSelectors,
             },
@@ -1037,16 +2870,30 @@ server.tool("export_playbook", "Generate a playbook JSON from your session. Extr
             strategies_count: domainStrategies.length,
         },
     };
-    // 4. Save to playbooks dir
-    const outPath = path.resolve(playbooksDir, `${platform.toLowerCase()}.json`);
+    // 4. Save to references dir (curated knowledge, not executable steps)
+    const safePlatformName = platform.toLowerCase().replace(/[^a-z0-9_\-]/g, "_").slice(0, 100);
+    const outPath = path.resolve(referencesDir, `${safePlatformName}.json`);
+    // Guard: refuse to write outside references dir
+    if (!outPath.startsWith(path.resolve(referencesDir))) {
+        return { content: [{ type: "text", text: `Error: invalid platform name "${platform}" — path traversal detected` }] };
+    }
     const exists = fs.existsSync(outPath);
-    if (!fs.existsSync(playbooksDir))
-        fs.mkdirSync(playbooksDir, { recursive: true });
+    if (!fs.existsSync(referencesDir))
+        fs.mkdirSync(referencesDir, { recursive: true });
     fs.writeFileSync(outPath, JSON.stringify(playbook, null, 2));
+    // Track playbook export for teaching ability rating factor
+    const expBundleId = worldModel.getState().focusedApp?.bundleId;
+    if (expBundleId) {
+        const expMapData = appMap.getLoaded(expBundleId);
+        if (expMapData) {
+            expMapData.playbooksExported = (expMapData.playbooksExported ?? 0) + 1;
+            appMap.save(expMapData, true);
+        }
+    }
     return {
         content: [{
                 type: "text",
-                text: `${exists ? "Updated" : "Created"} playbook: playbooks/${platform.toLowerCase()}.json\n\n` +
+                text: `${exists ? "Updated" : "Created"} reference: references/${platform.toLowerCase()}.json\n\n` +
                     `URLs found: ${urlSet.size}\n` +
                     `Selectors found: ${Object.keys(pageSelectors).length}\n` +
                     `Errors documented: ${domainErrors.length}\n` +
@@ -1057,12 +2904,181 @@ server.tool("export_playbook", "Generate a playbook JSON from your session. Extr
     };
 });
 // ═══════════════════════════════════════════════
+// PLAYBOOK RECORD — macro recorder for MCP tool calls
+// ═══════════════════════════════════════════════
+server.tool("playbook_record", "Macro recorder: start recording, do the flow, stop to save as executable playbook. Captures every click/type/navigate tool call as a PlaybookStep.", {
+    action: z.enum(["start", "stop", "cancel", "status"]).describe("start/stop/cancel/status"),
+    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)"),
+}, async ({ action, platform, name, description, cdpPort }) => {
+    switch (action) {
+        case "start": {
+            if (!platform)
+                return { content: [{ type: "text", text: "Error: platform is required for start" }] };
+            if (mcpRecorder.isRecording)
+                return { content: [{ type: "text", text: "Already recording. Call stop or cancel first." }] };
+            mcpRecorder.start(platform, cdpPort ?? undefined);
+            return { content: [{ type: "text", text: `Recording started for "${platform}". All subsequent tool calls will be captured.\nCall playbook_record(action="stop", name="...") when done.` }] };
+        }
+        case "stop": {
+            if (!mcpRecorder.isRecording)
+                return { content: [{ type: "text", text: "No active recording." }] };
+            if (!name)
+                return { content: [{ type: "text", text: "Error: name is required for stop" }] };
+            const playbook = mcpRecorder.stop(name, description ?? name);
+            // Track playbook export for teaching ability rating factor
+            const pbBundleId = worldModel.getState().focusedApp?.bundleId;
+            if (pbBundleId) {
+                const pbMapData = appMap.getLoaded(pbBundleId);
+                if (pbMapData) {
+                    pbMapData.playbooksExported = (pbMapData.playbooksExported ?? 0) + 1;
+                    appMap.save(pbMapData, true);
+                }
+            }
+            const stepList = playbook.steps.map((s, i) => `  ${i + 1}. [${s.action}] ${s.description ?? ""}`).join("\n");
+            return { content: [{ type: "text", text: `Playbook saved: playbooks/${playbook.id}.json (${playbook.steps.length} steps)\n\n${stepList}` }] };
+        }
+        case "cancel": {
+            mcpRecorder.cancel();
+            return { content: [{ type: "text", text: "Recording cancelled." }] };
+        }
+        case "status": {
+            if (!mcpRecorder.isRecording)
+                return { content: [{ type: "text", text: "Not recording." }] };
+            const steps = mcpRecorder.getSteps().map((s, i) => `  ${i + 1}. [${s.action}] ${s.description ?? ""}`).join("\n");
+            return { content: [{ type: "text", text: `Recording active: ${mcpRecorder.stepCount} steps captured\n${steps}` }] };
+        }
+    }
+});
+// ═══════════════════════════════════════════════
+// PLATFORM EXPLORE — autonomous app exploration
+// ═══════════════════════════════════════════════
+server.tool("platform_explore", "Autonomously explore an app or website. Maps all interactive elements, tries each one, records working selectors and broken paths. Outputs a reference JSON.", {
+    platform: z.string().describe("Platform name for the output file, e.g. 'figma', 'canva'"),
+    url: z.string().optional().describe("URL for web app. Requires Chrome with --remote-debugging-port."),
+    bundleId: z.string().optional().describe("macOS bundle ID for native app, e.g. 'com.figma.Desktop'"),
+    maxElements: z.number().optional().describe("Max elements to test (default: 30)"),
+    tabId: z.string().optional().describe("Existing Chrome tab ID if page is already open"),
+}, async ({ platform, url, bundleId, maxElements, tabId }) => {
+    const max = maxElements ?? 30;
+    if (url || tabId) {
+        // Web exploration via CDP
+        const { CDP: cdp, port } = await ensureCDP();
+        let targetId = tabId;
+        if (!targetId) {
+            if (url) {
+                // Navigate to URL in a new tab
+                const targets = await cdp.List({ port });
+                const page = targets.find((t) => t.type === "page");
+                if (!page)
+                    throw new Error("No Chrome tabs open");
+                targetId = page.id;
+                const client = await cdp({ port, target: targetId });
+                await client.Page.enable();
+                await client.Page.navigate({ url });
+                await new Promise(r => setTimeout(r, 3000));
+                await client.close();
+            }
+        }
+        if (!targetId)
+            throw new Error("No tab available");
+        const client = await cdp({ port, target: targetId });
+        await client.Runtime.enable();
+        const evaluate = async (expr) => {
+            return client.Runtime.evaluate({ expression: expr, returnByValue: true, awaitPromise: true });
+        };
+        // Discover elements
+        const elements = await discoverWebElements(evaluate, max);
+        // Test each element
+        const tested = [];
+        for (const el of elements) {
+            const result = await testWebElement(evaluate, el);
+            tested.push(result);
+            await new Promise(r => setTimeout(r, 300 + Math.random() * 500));
+        }
+        await client.close();
+        // Compile and save
+        const result = compileReference(platform, "web", tested, url);
+        const filePath = saveExploreResult(referencesDir, result);
+        return { content: [{ type: "text", text: `Exploration complete: ${filePath}\n\nElements found: ${elements.length}\nTested: ${result.testedElements}\nWorking selectors: ${result.workingSelectors}\nErrors: ${result.errors.length}\n\nKey discoveries:\n${result.keyDiscoveries.map(d => `  - ${d}`).join("\n")}` }] };
+    }
+    else if (bundleId) {
+        // Native app exploration via bridge
+        await ensureBridge();
+        const apps = await bridge.call("app.list");
+        const app = apps.find(a => a.bundleId === bundleId);
+        if (!app) {
+            await bridge.call("app.launch", { bundleId });
+            await new Promise(r => setTimeout(r, 3000));
+        }
+        const appList = await bridge.call("app.list");
+        const target = appList.find(a => a.bundleId === bundleId);
+        if (!target)
+            throw new Error(`App ${bundleId} not running`);
+        const elements = await discoverNativeElements(bridge, target.pid, max);
+        // For native apps, we record discovery but don't auto-click (too risky)
+        const result = compileReference(platform, "native", elements.map(el => ({
+            ...el, clickWorked: true, result: "discovered_not_tested",
+        })), undefined, bundleId);
+        const filePath = saveExploreResult(referencesDir, result);
+        return { content: [{ type: "text", text: `Native app exploration complete: ${filePath}\n\nElements discovered: ${elements.length}\n(Native elements discovered but not auto-clicked for safety. Use playbook_record to test interactively.)` }] };
+    }
+    else {
+        return { content: [{ type: "text", text: "Error: Provide either url (for web apps) or bundleId (for native apps)." }] };
+    }
+});
+// ═══════════════════════════════════════════════
+// PLATFORM LEARN — scrape docs/help/shortcuts
+// ═══════════════════════════════════════════════
+server.tool("platform_learn", "Scrape official docs, help center, keyboard shortcuts for a platform. Crawls pages via Chrome and extracts structured data into a reference JSON.", {
+    platform: z.string().describe("Platform name, e.g. 'figma', 'notion', 'slack'"),
+    url: z.string().optional().describe("Root URL to start from. If omitted, guesses from platform name."),
+    maxPages: z.number().optional().describe("Max pages to crawl (default: 5)"),
+}, async ({ platform, url, maxPages }) => {
+    const max = maxPages ?? 5;
+    const urls = buildDocUrls(platform, url);
+    const { CDP: cdp, port } = await ensureCDP();
+    const targets = await cdp.List({ port });
+    const page = targets.find((t) => t.type === "page");
+    if (!page)
+        throw new Error("No Chrome tabs open. Open Chrome first.");
+    const client = await cdp({ port, target: page.id });
+    await client.Runtime.enable();
+    await client.Page.enable();
+    const crawled = [];
+    let successCount = 0;
+    for (const docUrl of urls) {
+        if (successCount >= max)
+            break;
+        try {
+            const result = await crawlPage(client, docUrl, 8000);
+            if (result.success && result.content && result.content.text.length > 100) {
+                crawled.push({ url: docUrl, content: result.content, ...(result.shortcuts ? { shortcuts: result.shortcuts } : {}), ...(result.selectors ? { selectors: result.selectors } : {}) });
+                successCount++;
+            }
+        }
+        catch {
+            // Skip failed URLs silently
+        }
+        await new Promise(r => setTimeout(r, 1000 + Math.random() * 1000));
+    }
+    await client.close();
+    if (crawled.length === 0) {
+        return { content: [{ type: "text", text: `No documentation pages found for "${platform}". Try providing a specific URL.` }] };
+    }
+    const result = compileLearnResult(platform, crawled);
+    const filePath = saveLearnResult(referencesDir, result);
+    return { content: [{ type: "text", text: `Learning complete: ${filePath}\n\nPages crawled: ${crawled.length}\nShortcuts found: ${Object.keys(result.shortcuts).length}\nFeatures found: ${result.features.length}\nSelectors found: ${Object.values(result.selectors).reduce((n, g) => n + Object.keys(g).length, 0)}\nAPI endpoints: ${result.apiEndpoints.length}\nKnown limitations: ${result.knownLimitations.length}` }] };
+});
+// ═══════════════════════════════════════════════
 // APPLESCRIPT — control scriptable apps directly
 // ═══════════════════════════════════════════════
 server.tool("applescript", "Run an AppleScript command. For controlling Finder, Safari, Mail, Notes, etc. (macOS only). WARNING: Executes arbitrary AppleScript — can perform destructive actions (delete files, send emails). All executions are audit-logged.", {
     script: z.string().describe("AppleScript code to execute"),
 }, async ({ script }) => {
-    auditLog("applescript", { script: script.slice(0, 500) });
+    auditLog("applescript", { script });
     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." }] };
     }
@@ -1190,6 +3206,15 @@ originalTool("session_claim", "Claim exclusive control of an app window. Prevent
     app: z.string().describe("Bundle ID of the app (e.g., 'com.google.Chrome')"),
     windowId: z.number().describe("Window ID to claim (get from 'windows' tool)"),
 }, async ({ clientId, clientType, app, windowId }) => {
+    // Validate window ID exists
+    try {
+        await ensureBridge();
+        const wins = await bridge.call("window.list", {});
+        if (wins && !wins.some((w) => w.windowId === windowId)) {
+            return { content: [{ type: "text", text: `Window ${windowId} does not exist. Use the windows() tool to get valid window IDs.` }] };
+        }
+    }
+    catch { /* best-effort validation — proceed if bridge unavailable */ }
     // Use filesystem-backed lease manager directly (shared with daemon)
     const lease = leaseManager.claim({ id: clientId, type: clientType, startedAt: new Date().toISOString() }, app, windowId);
     if (!lease) {
@@ -1211,6 +3236,8 @@ originalTool("session_heartbeat", "Keep your session lease alive. Call every 60
 originalTool("session_release", "Release your session lease so other clients can use the window.", {
     sessionId: z.string().describe("Session ID to release"),
 }, async ({ sessionId }) => {
+    // Flush playbook learnings before releasing session
+    contextTracker.flush();
     // Use filesystem-backed lease manager directly (shared with daemon)
     const released = leaseManager.release(sessionId);
     return { content: [{ type: "text", text: released ? `Session ${sessionId} released.` : `Session ${sessionId} not found.` }] };
@@ -1397,6 +3424,18 @@ originalTool("recovery_queue_add", "Add a manual recovery instruction for a stal
     type: z.enum(["nudge", "restart", "escalate", "custom"]).describe("Recovery type"),
     instruction: z.string().describe("What to do (e.g., 'Click the login button', 'Restart Chrome')"),
 }, async ({ sessionId, type, instruction }) => {
+    // Validate that the session ID looks reasonable (basic format check)
+    // Accept both lease-style (lease_*) and generic session IDs
+    if (!sessionId || sessionId.length < 3 || sessionId.length > 200) {
+        return { content: [{ type: "text", text: `Error: Invalid session ID "${sessionId}". Must be 3-200 characters.` }] };
+    }
+    // Validate session is active — reject orphaned recovery instructions
+    const activeSessions = leaseManager.getActive();
+    const isActive = activeSessions.some(s => s.sessionId === sessionId);
+    if (!isActive) {
+        return { content: [{ type: "text", text: `Session "${sessionId}" is not active. Use supervisor_status to find active sessions.` }] };
+    }
+    const warning = "";
     const recovery = {
         id: "recv_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 8),
         sessionId,
@@ -1409,9 +3448,19 @@ originalTool("recovery_queue_add", "Add a manual recovery instruction for a stal
     };
     // Write to daemon's filesystem state so the daemon picks it up
     const recoveries = readDaemonRecoveries();
-    recoveries.push(recovery);
-    writeDaemonRecoveries(recoveries);
-    return { content: [{ type: "text", text: `Recovery queued: ${recovery.id} (type=${type})` }] };
+    // Prune old completed/failed entries (keep last 50, drop entries older than 24h)
+    const MAX_QUEUE_SIZE = 50;
+    const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+    const cutoff = Date.now() - MAX_AGE_MS;
+    const pruned = recoveries.filter((r) => {
+        if (r.status === "pending")
+            return true; // always keep pending
+        const age = new Date(r.createdAt).getTime();
+        return age > cutoff;
+    }).slice(-MAX_QUEUE_SIZE);
+    pruned.push(recovery);
+    writeDaemonRecoveries(pruned);
+    return { content: [{ type: "text", text: `Recovery queued: ${recovery.id} (type=${type})${warning}` }] };
 });
 originalTool("recovery_queue_list", "List recovery actions, optionally filtered by status.", {
     status: z.enum(["pending", "attempted", "succeeded", "failed"]).optional().describe("Filter by status"),
@@ -1590,7 +3639,7 @@ originalTool("supervisor_uninstall", "Uninstall the supervisor system service. S
 // EXECUTION CONTRACT — canonical fallback chain
 // ═══════════════════════════════════════════════
 import { METHOD_CAPABILITIES, DEFAULT_RETRY_POLICY, planExecution, executeWithFallback, } from "./src/runtime/execution-contract.js";
-originalTool("execution_plan", "Show the execution plan for an action type. Returns the ordered fallback chain based on available infrastructure.", {
+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 });
@@ -1598,7 +3647,18 @@ originalTool("execution_plan", "Show the execution plan for an action type. Retu
         const cap = METHOD_CAPABILITIES[method];
         return `${i + 1}. ${method} (~${cap.avgLatencyMs}ms)${i === 0 ? " ← primary" : ""}`;
     });
-    lines.push("", `Retry policy: ${DEFAULT_RETRY_POLICY.maxRetriesPerMethod}/method, ${DEFAULT_RETRY_POLICY.maxTotalRetries} total, escalate after ${DEFAULT_RETRY_POLICY.escalateAfter}`);
+    const policy = getAdaptedRetryPolicy();
+    lines.push("", `Retry policy: ${policy.maxRetriesPerMethod}/method, ${policy.maxTotalRetries} total, escalate after ${policy.escalateAfter}, delay ${policy.delayBetweenRetriesMs}ms`);
+    const appBundleId = worldModel.getState().focusedApp?.bundleId;
+    if (appBundleId) {
+        const budget = learningEngine.getAdaptiveBudget(appBundleId);
+        lines.push(`Adaptive budgets: locate=${budget.locateMs}ms, act=${budget.actMs}ms, verify=${budget.verifyMs}ms`);
+    }
+    // Include app-specific hints from reference files and context tracker
+    const hints = contextTracker.getHints(action, {});
+    if (hints.length > 0) {
+        lines.push("", "App-specific context:", ...hints.slice(0, 5));
+    }
     return { content: [{ type: "text", text: `Execution plan for "${action}":\n${lines.join("\n")}` }] };
 });
 // ── Shared helpers for resilient action tools ──
@@ -1623,6 +3683,21 @@ async function resolvePid(bundleId) {
 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.
+ */
+function getAdaptedRetryPolicy() {
+    if (!currentAdaptiveBudget)
+        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) {
     if (result.ok) {
         const fallbackNote = result.fallbackFrom ? ` (fell back from ${result.fallbackFrom})` : "";
@@ -1631,7 +3706,7 @@ function formatResult(action, target, result) {
     return { content: [{ type: "text", text: `Failed to ${action} "${target}" — all methods exhausted. Last error: ${result.error}` }] };
 }
 // ── click_with_fallback ──
-originalTool("click_with_fallback", "Click a target by text using the canonical fallback chain: AX → CDP → OCR. Automatically retries and falls through methods.", {
+server.tool("click_with_fallback", "Click a target by text using the canonical fallback chain: AX → CDP → OCR. Automatically retries and falls through methods.", {
     target: z.string().describe("Text, title, or identifier of the element to click"),
     bundleId: z.string().optional().describe("App bundle ID (for AX path)"),
 }, async ({ target, bundleId }) => {
@@ -1639,17 +3714,27 @@ originalTool("click_with_fallback", "Click a target by text using the canonical
     const plan = planExecution("click", infra())
         .filter((m) => m !== "coordinates");
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("click", plan, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("click", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
                 case "ax": {
-                    // Find element by title, then perform AXPress action
-                    const found = await bridge.call("ax.findElement", {
-                        pid: targetPid,
-                        title: target,
-                        exact: false,
-                    });
+                    // L2-65 fix: Try exact match first to avoid wrong-window match on minimized windows
+                    let found;
+                    try {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: true,
+                        });
+                    }
+                    catch {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: false,
+                        });
+                    }
                     await bridge.call("ax.performAction", {
                         pid: targetPid,
                         elementPath: found.elementPath,
@@ -1710,7 +3795,7 @@ originalTool("click_with_fallback", "Click a target by text using the canonical
     return formatResult("Clicked", target, result);
 });
 // ── type_with_fallback ──
-originalTool("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.", {
+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.", {
     target: z.string().describe("Label, placeholder, or title of the field to type into"),
     text: z.string().describe("Text to type"),
     bundleId: z.string().optional().describe("App bundle ID"),
@@ -1719,16 +3804,81 @@ originalTool("type_with_fallback", "Type text into a target field using the cano
     await ensureBridge();
     const plan = planExecution("type", infra());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("type", plan, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("type", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
                 case "ax": {
-                    const found = await bridge.call("ax.findElement", {
-                        pid: targetPid,
-                        title: target,
-                        exact: false,
-                    });
+                    // L2-65 fix: Try exact match first to avoid wrong-window match on minimized windows
+                    let found;
+                    try {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: true,
+                        });
+                    }
+                    catch {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: false,
+                        });
+                    }
+                    // L2-62+L2-68 fix: If matched element is a window (short elementPath), find
+                    // the child AXTextArea/AXTextField SCOPED to the target window.
+                    const isLikelyWindow = found.elementPath.length <= 1;
+                    if (isLikelyWindow) {
+                        // Try window-scoped search first via getElementTree
+                        let scopedFound = false;
+                        try {
+                            const wins = await bridge.call("app.windows");
+                            const matchWin = wins.find((w) => w.title === target) ?? wins.find((w) => w.title?.includes(target));
+                            if (matchWin?.windowId) {
+                                const windowTree = await bridge.call("ax.getElementTree", {
+                                    pid: targetPid,
+                                    windowId: matchWin.windowId,
+                                    maxDepth: 8,
+                                });
+                                const findInTree = (node, path) => {
+                                    if (node?.role && (node.role === "AXTextArea" || node.role === "AXTextField")) {
+                                        return path;
+                                    }
+                                    if (node?.children && Array.isArray(node.children)) {
+                                        for (let i = 0; i < node.children.length; i++) {
+                                            const r = findInTree(node.children[i], [...path, i]);
+                                            if (r)
+                                                return r;
+                                        }
+                                    }
+                                    return null;
+                                };
+                                const textPath = findInTree(windowTree, found.elementPath);
+                                if (textPath) {
+                                    found = found.bounds
+                                        ? { elementPath: textPath, bounds: found.bounds }
+                                        : { elementPath: textPath };
+                                    scopedFound = true;
+                                }
+                            }
+                        }
+                        catch { /* fall through to unscoped search */ }
+                        // Fallback: unscoped search (original L2-62 behavior)
+                        if (!scopedFound) {
+                            for (const role of ["AXTextArea", "AXTextField"]) {
+                                try {
+                                    const textEl = await bridge.call("ax.findElement", {
+                                        pid: targetPid,
+                                        role,
+                                        maxDepth: 10,
+                                    });
+                                    found = textEl;
+                                    break;
+                                }
+                                catch { /* try next role */ }
+                            }
+                        }
+                    }
                     if (clearFirst) {
                         await bridge.call("ax.setElementValue", { pid: targetPid, elementPath: found.elementPath, value: "" });
                     }
@@ -1758,8 +3908,9 @@ originalTool("type_with_fallback", "Type text into a target field using the cano
                         if (!evalResult.result?.value)
                             throw new Error("Field not found via CDP");
                         if (clearFirst) {
-                            await Input.dispatchKeyEvent({ type: "keyDown", key: "a", code: "KeyA", modifiers: 2 });
-                            await Input.dispatchKeyEvent({ type: "keyUp", key: "a", code: "KeyA", modifiers: 2 });
+                            const selectAllMod = process.platform === "darwin" ? 4 : 2; // Cmd on macOS, Ctrl on Windows/Linux
+                            await Input.dispatchKeyEvent({ type: "keyDown", key: "a", code: "KeyA", modifiers: selectAllMod });
+                            await Input.dispatchKeyEvent({ type: "keyUp", key: "a", code: "KeyA", modifiers: selectAllMod });
                         }
                         for (const char of text) {
                             await Input.dispatchKeyEvent({ type: "keyDown", key: char, text: char });
@@ -1781,28 +3932,103 @@ originalTool("type_with_fallback", "Type text into a target field using the cano
     return formatResult("Typed into", target, result);
 });
 // ── read_with_fallback ──
-originalTool("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.", {
+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.", {
     target: z.string().optional().describe("Element label/title to read from (omit for full-screen OCR)"),
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ target, bundleId }) => {
     await ensureBridge();
     const plan = planExecution("read", infra());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("read", plan, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("read", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
                 case "ax": {
                     if (target) {
-                        const found = await bridge.call("ax.findElement", {
-                            pid: targetPid,
-                            title: target,
-                            exact: false,
-                        });
+                        // L2-65 fix: Try exact match first to avoid reading from the wrong
+                        // window when multiple windows share a title prefix (e.g. "Untitled 39" vs "Untitled 40").
+                        // Minimized windows may be skipped by the bridge search, so an inexact match
+                        // can silently return a sibling window's content with no warning.
+                        let found;
+                        try {
+                            found = await bridge.call("ax.findElement", {
+                                pid: targetPid,
+                                title: target,
+                                exact: true,
+                            });
+                        }
+                        catch {
+                            // Exact match failed — fall back to fuzzy match
+                            found = await bridge.call("ax.findElement", {
+                                pid: targetPid,
+                                title: target,
+                                exact: false,
+                            });
+                        }
                         const val = await bridge.call("ax.getElementValue", {
                             pid: targetPid,
                             elementPath: found.elementPath,
                         });
+                        // L2-59+L2-61+L2-68 fix: If matched element has no value (e.g. AXWindow), find a
+                        // text-bearing child element SCOPED to the target window.
+                        // L2-68: Previously used unscoped ax.findElement(role) which returned AXTextArea from
+                        // ANY window. Now uses ax.getElementTree(windowId) to scope the search.
+                        if (!val.value) {
+                            // Try to find the matching CG windowId by title
+                            let windowTree = null;
+                            try {
+                                const wins = await bridge.call("app.windows");
+                                const matchWin = wins.find((w) => w.title === target) ?? wins.find((w) => w.title?.includes(target));
+                                if (matchWin?.windowId) {
+                                    windowTree = await bridge.call("ax.getElementTree", {
+                                        pid: targetPid,
+                                        windowId: matchWin.windowId,
+                                        maxDepth: 8,
+                                    });
+                                }
+                            }
+                            catch { /* fall through to unscoped search */ }
+                            // Walk the window tree to find first text-bearing element
+                            const textRoles = new Set(["AXTextArea", "AXTextField", "AXWebArea"]);
+                            const findTextInTree = (node, path) => {
+                                if (node?.role && textRoles.has(node.role) && node.value) {
+                                    return { value: node.value, path };
+                                }
+                                if (node?.children && Array.isArray(node.children)) {
+                                    for (let i = 0; i < node.children.length; i++) {
+                                        const result = findTextInTree(node.children[i], [...path, i]);
+                                        if (result)
+                                            return result;
+                                    }
+                                }
+                                return null;
+                            };
+                            if (windowTree) {
+                                const textNode = findTextInTree(windowTree, found.elementPath);
+                                if (textNode?.value) {
+                                    return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: textNode.value };
+                                }
+                            }
+                            // Fallback: unscoped search (original L2-59 behavior) if window-scoped search fails
+                            const fallbackRoles = ["AXTextArea", "AXTextField", "AXWebArea"];
+                            for (const role of fallbackRoles) {
+                                try {
+                                    const textEl = await bridge.call("ax.findElement", {
+                                        pid: targetPid,
+                                        role,
+                                        maxDepth: 10,
+                                    });
+                                    const textVal = await bridge.call("ax.getElementValue", {
+                                        pid: targetPid,
+                                        elementPath: textEl.elementPath,
+                                    });
+                                    if (textVal.value) {
+                                        return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: textVal.value };
+                                    }
+                                }
+                                catch { /* try next role */ }
+                            }
+                        }
                         return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: val.value ?? "" };
                     }
                     // No specific target — get the full element tree text
@@ -1874,23 +4100,34 @@ originalTool("read_with_fallback", "Read text content from the screen or a speci
     return { content: [{ type: "text", text: `Failed to read${target ? ` "${target}"` : ""} — all methods exhausted. Last error: ${result.error}` }] };
 });
 // ── locate_with_fallback ──
-originalTool("locate_with_fallback", "Find an element's position on screen using the canonical fallback chain: AX → CDP → OCR. Returns bounds (x, y, width, height).", {
+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).", {
     target: z.string().describe("Text, title, or identifier of the element to locate"),
     bundleId: z.string().optional().describe("App bundle ID"),
 }, async ({ target, bundleId }) => {
     await ensureBridge();
     const plan = planExecution("locate", infra());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("locate", plan, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("locate", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
                 case "ax": {
-                    const found = await bridge.call("ax.findElement", {
-                        pid: targetPid,
-                        title: target,
-                        exact: false,
-                    });
+                    // L2-65 fix: Try exact match first
+                    let found;
+                    try {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: true,
+                        });
+                    }
+                    catch {
+                        found = await bridge.call("ax.findElement", {
+                            pid: targetPid,
+                            title: target,
+                            exact: false,
+                        });
+                    }
                     if (!found.bounds)
                         throw new Error("Element found but has no bounds");
                     const b = found.bounds;
@@ -1946,7 +4183,7 @@ originalTool("locate_with_fallback", "Find an element's position on screen using
     return formatResult("Located", target, result);
 });
 // ── select_with_fallback ──
-originalTool("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.", {
+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.", {
     target: z.string().describe("Label or title of the dropdown/menu control"),
     option: z.string().describe("Text of the option to select"),
     bundleId: z.string().optional().describe("App bundle ID"),
@@ -1954,7 +4191,7 @@ originalTool("select_with_fallback", "Select an option from a dropdown/menu usin
     await ensureBridge();
     const plan = planExecution("select", infra());
     const targetPid = await resolvePid(bundleId);
-    const result = await executeWithFallback("select", plan, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("select", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             switch (method) {
@@ -2021,7 +4258,7 @@ originalTool("select_with_fallback", "Select an option from a dropdown/menu usin
     return formatResult("Selected", `${target} → ${option}`, result);
 });
 // ── scroll_with_fallback ──
-originalTool("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.", {
+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.", {
     direction: z.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
     amount: z.number().optional().describe("Scroll amount in pixels (default: 300)"),
     target: z.string().optional().describe("Scroll until this text is visible (overrides amount)"),
@@ -2031,6 +4268,17 @@ originalTool("scroll_with_fallback", "Scroll within an element or the active win
     const plan = planExecution("scroll", infra());
     const targetPid = await resolvePid(bundleId);
     const scrollAmount = amount ?? 300;
+    // Resolve scroll coordinates — center of the frontmost window
+    let scrollX = 400, scrollY = 400;
+    try {
+        const wins = await bridge.call("cg.windows", {});
+        if (wins && wins.length > 0) {
+            const w = wins[0];
+            scrollX = Math.round(w.x + w.width / 2);
+            scrollY = Math.round(w.y + w.height / 2);
+        }
+    }
+    catch { /* fallback to default coords */ }
     // If target is specified, scroll in a loop until text is visible (max 10 scrolls)
     if (target) {
         for (let i = 0; i < 10; i++) {
@@ -2049,26 +4297,21 @@ originalTool("scroll_with_fallback", "Scroll within an element or the active win
             // Scroll once
             const deltaX = direction === "left" ? -scrollAmount : direction === "right" ? scrollAmount : 0;
             const deltaY = direction === "up" ? -scrollAmount : direction === "down" ? scrollAmount : 0;
-            await bridge.call("cg.scroll", { deltaX, deltaY });
+            await bridge.call("cg.scroll", { x: scrollX, y: scrollY, deltaX, deltaY });
             await new Promise((r) => setTimeout(r, 400));
         }
         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, DEFAULT_RETRY_POLICY, async (method, attempt) => {
+    const result = await executeWithFallback("scroll", plan, getAdaptedRetryPolicy(), async (method, attempt) => {
         const start = Date.now();
         try {
             const deltaX = direction === "left" ? -scrollAmount : direction === "right" ? scrollAmount : 0;
             const deltaY = direction === "up" ? -scrollAmount : direction === "down" ? scrollAmount : 0;
             switch (method) {
                 case "ax": {
-                    // Use AX scroll action on the focused element
-                    const tree = await bridge.call("ax.getElementTree", {
-                        pid: targetPid,
-                        maxDepth: 1,
-                    });
-                    // Fall through to cg.scroll since AX scroll is less reliable
-                    await bridge.call("cg.scroll", { deltaX, deltaY });
+                    // AX scroll is unreliable — use CG scroll directly (works on the focused app)
+                    await bridge.call("cg.scroll", { x: scrollX, y: scrollY, deltaX, deltaY });
                     return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: `${direction} ${scrollAmount}px` };
                 }
                 case "cdp": {
@@ -2088,7 +4331,7 @@ originalTool("scroll_with_fallback", "Scroll within an element or the active win
                     }
                 }
                 case "coordinates": {
-                    await bridge.call("cg.scroll", { deltaX, deltaY });
+                    await bridge.call("cg.scroll", { x: scrollX, y: scrollY, deltaX, deltaY });
                     return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: `${direction} ${scrollAmount}px` };
                 }
             }
@@ -2101,7 +4344,7 @@ originalTool("scroll_with_fallback", "Scroll within an element or the active win
     return formatResult("Scrolled", `${direction} ${scrollAmount}px`, result);
 });
 // ── wait_for_state ──
-originalTool("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.", {
+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.", {
     condition: z.enum(["text_appears", "text_disappears", "element_exists"]).describe("What to wait for"),
     target: z.string().describe("Text or element to watch for"),
     timeoutMs: z.number().optional().describe("Maximum wait time in ms (default: 10000)"),
@@ -2123,13 +4366,29 @@ originalTool("wait_for_state", "Wait until a condition is met on screen: text ap
                 found = true;
             }
             else {
-                // Text-based: try OCR
-                const shot = await bridge.call("cg.captureScreen", {});
-                const matches = await bridge.call("vision.findText", {
-                    imagePath: shot.path,
-                    searchText: target,
-                });
-                found = Array.isArray(matches) && matches.length > 0;
+                // L2-67 fix: Try AX text search first (works for non-frontmost apps),
+                // then fall back to OCR if AX doesn't find it.
+                try {
+                    const axEl = await bridge.call("ax.findElement", { pid: targetPid, title: target, exact: false });
+                    found = true;
+                }
+                catch {
+                    // AX title search failed — also try reading text content via AX tree
+                    try {
+                        const tree = await bridge.call("ax.getElementTree", { pid: targetPid, maxDepth: 4 });
+                        const desc = tree.description ?? JSON.stringify(tree);
+                        found = desc.includes(target);
+                    }
+                    catch {
+                        // AX unavailable — fall back to OCR
+                        const shot = await bridge.call("cg.captureScreen", {});
+                        const matches = await bridge.call("vision.findText", {
+                            imagePath: shot.path,
+                            searchText: target,
+                        });
+                        found = Array.isArray(matches) && matches.length > 0;
+                    }
+                }
             }
         }
         catch {
@@ -2172,13 +4431,13 @@ originalTool("wait_for_state", "Wait until a condition is met on screen: text ap
 // ═══════════════════════════════════════════════
 // JOBS — persistent multi-step automation with resume
 // ═══════════════════════════════════════════════
-originalTool("job_create", "Create a new automation job. Jobs persist across restarts and can be resumed from the last successful step.", {
+originalTool("job_create", "Create a new automation job. Jobs persist across restarts and can be resumed from the last successful step. Supports chaining: set dependsOn to wait for another job, and vars for template substitution (e.g. {PROMPT_TEXT}).", {
     task: z.string().describe("Human-readable description of what this job should do"),
     playbookId: z.string().optional().describe("Playbook ID to drive this job (optional — AI-only if omitted)"),
     bundleId: z.string().optional().describe("Target application bundle ID (e.g., 'com.apple.Safari'). Omit for app-agnostic jobs."),
     windowId: z.number().optional().describe("Target window ID within the application. Omit for app-agnostic jobs."),
     steps: z.array(z.object({
-        action: z.string().describe("Action name (e.g., navigate, click, type_text, screenshot, key)"),
+        action: z.string().describe("Action name (e.g., navigate, click, type_text, screenshot, key, browser_js, cdp_key_event)"),
         target: z.string().optional().describe("Target element or URL"),
         description: z.string().optional().describe("Human-readable description"),
         text: z.string().optional().describe("Text payload for type_text/type_into actions"),
@@ -2189,7 +4448,10 @@ originalTool("job_create", "Create a new automation job. Jobs persist across res
     priority: z.number().optional().describe("Priority (lower = higher priority, default: 10)"),
     maxRetries: z.number().optional().describe("Max retry attempts on failure (default: 3)"),
     sessionId: z.string().optional().describe("Bind to an existing supervisor session"),
-}, async ({ task, playbookId, bundleId, windowId, steps, tags, priority, maxRetries, sessionId }) => {
+    chainId: z.string().optional().describe("Chain ID to group linked jobs into a flow"),
+    dependsOn: z.string().optional().describe("Job ID this job depends on — won't run until dependency is done"),
+    vars: z.record(z.string(), z.string()).optional().describe("Variables for template substitution in playbook steps (e.g. {PROMPT_TEXT} → 'hello world'). Use {prev.outputKey} to reference outputs from dependsOn job."),
+}, async ({ task, playbookId, bundleId, windowId, steps, tags, priority, maxRetries, sessionId, chainId, dependsOn, vars }) => {
     const createOpts = { task };
     if (playbookId !== undefined)
         createOpts.playbookId = playbookId;
@@ -2207,8 +4469,50 @@ originalTool("job_create", "Create a new automation job. Jobs persist across res
         createOpts.maxRetries = maxRetries;
     if (sessionId !== undefined)
         createOpts.sessionId = sessionId;
+    if (chainId !== undefined)
+        createOpts.chainId = chainId;
+    if (dependsOn !== undefined)
+        createOpts.dependsOn = dependsOn;
+    if (vars !== undefined)
+        createOpts.vars = vars;
     const job = jobManager.create(createOpts);
-    return { content: [{ type: "text", text: `Job created: ${job.id}\nTask: ${job.task}\nState: ${job.state}\nSteps: ${job.steps.length}\nPriority: ${job.priority}\nTarget: ${job.bundleId ?? "(any app)"}${job.windowId != null ? ` window ${job.windowId}` : ""}` }] };
+    const extra = [];
+    if (job.chainId)
+        extra.push(`Chain: ${job.chainId}`);
+    if (job.dependsOn)
+        extra.push(`Depends on: ${job.dependsOn}`);
+    if (job.vars && Object.keys(job.vars).length > 0)
+        extra.push(`Vars: ${Object.keys(job.vars).join(", ")}`);
+    return { content: [{ type: "text", text: `Job created: ${job.id}\nTask: ${job.task}\nState: ${job.state}\nSteps: ${job.steps.length}\nPriority: ${job.priority}\nTarget: ${job.bundleId ?? "(any app)"}${job.windowId != null ? ` window ${job.windowId}` : ""}${extra.length > 0 ? "\n" + extra.join("\n") : ""}` }] };
+});
+originalTool("job_create_chain", "Create a chain of linked jobs that run sequentially. Each job waits for the previous one to finish. Use vars with {prev.outputKey} to pass data between jobs.", {
+    jobs: z.array(z.object({
+        task: z.string().describe("What this job does"),
+        playbookId: z.string().optional().describe("Playbook ID"),
+        bundleId: z.string().optional().describe("Target app bundle ID"),
+        vars: z.record(z.string(), z.string()).optional().describe("Variables — use {prev.Read_Codex_response} to get output from prior job step"),
+        tags: z.array(z.string()).optional(),
+    })).describe("Ordered list of jobs to chain"),
+}, async ({ jobs }) => {
+    const cleanJobs = jobs.map(j => {
+        const clean = { task: j.task };
+        if (j.playbookId)
+            clean.playbookId = j.playbookId;
+        if (j.bundleId)
+            clean.bundleId = j.bundleId;
+        if (j.vars)
+            clean.vars = j.vars;
+        if (j.tags)
+            clean.tags = j.tags;
+        return clean;
+    });
+    const chain = jobManager.createChain({ jobs: cleanJobs });
+    const lines = [`Chain created: ${chain[0]?.chainId ?? "unknown"} (${chain.length} jobs)`];
+    for (const job of chain) {
+        lines.push(`  ${job.id}: ${job.task}${job.dependsOn ? ` (after ${job.dependsOn})` : " (first)"}`);
+    }
+    lines.push("", "Run with: job_run_all() to execute the full chain sequentially.");
+    return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 originalTool("job_status", "Get detailed status of a job including step progress and resume point.", {
     jobId: z.string().describe("Job ID"),
@@ -2232,6 +4536,12 @@ originalTool("job_status", "Get detailed status of a job including step progress
         `Resume point: ${resume ? `step ${resume.stepIndex} — ${resume.step.description ?? resume.step.action}` : "(none — all done or no pending steps)"}`,
         `Retries: ${job.retries}/${job.maxRetries}`,
     ];
+    if (job.chainId)
+        lines.push(`Chain: ${job.chainId}`);
+    if (job.dependsOn)
+        lines.push(`Depends on: ${job.dependsOn}`);
+    if (job.vars && Object.keys(job.vars).length > 0)
+        lines.push(`Vars: ${JSON.stringify(job.vars)}`);
     if (job.blockReason)
         lines.push(`Block reason: ${job.blockReason}`);
     if (job.lastError)
@@ -2245,6 +4555,8 @@ originalTool("job_status", "Get detailed status of a job including step progress
         for (const s of job.steps) {
             const icon = s.status === "done" ? "✓" : s.status === "failed" ? "✗" : s.status === "skipped" ? "–" : "○";
             lines.push(`  ${icon} [${s.index}] ${s.description ?? s.action}${s.error ? ` (${s.error})` : ""}${s.durationMs != null ? ` ${s.durationMs}ms` : ""}`);
+            if (s.output)
+                lines.push(`      → ${s.output.substring(0, 200)}${s.output.length > 200 ? "..." : ""}`);
         }
     }
     return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -2342,22 +4654,42 @@ originalTool("job_remove", "Remove a job entirely (any state).", {
     return { content: [{ type: "text", text: ok ? `Job ${jobId} removed.` : `Job ${jobId} not found.` }] };
 });
 // ── Job Runner + Worker ─────────────────────────
-const PLAYBOOKS_DIR = path.join(os.homedir(), ".screenhand", "playbooks");
+const PLAYBOOKS_DIR = playbooksDir; // Use same dir as recorder (project-local ./playbooks/)
 let activeJobRunner = null;
+let activePlaybookStore = null;
+let activePlaybookEngine = null;
 function getJobRunner() {
+    // Always reload playbooks from disk (new files may have been added)
+    if (!activePlaybookStore) {
+        activePlaybookStore = new PlaybookStore(PLAYBOOKS_DIR);
+    }
+    activePlaybookStore.load();
     if (!activeJobRunner) {
         // Build playbook engine stack: adapter → runtime → engine
         const adapter = new AccessibilityAdapter(bridge);
         const logger = new TimelineLogger();
-        const runtimeService = new AutomationRuntimeService(adapter, logger);
+        const locCache = new LocatorCache();
+        locCache.setLearningEngine(learningEngine);
+        const runtimeService = new AutomationRuntimeService(adapter, logger, locCache);
         const playbookEngine = new PlaybookEngine(runtimeService);
-        const playbookStore = new PlaybookStore(PLAYBOOKS_DIR);
-        playbookStore.load();
+        activePlaybookEngine = playbookEngine;
+        // Wire CDP into playbook engine for browser_js / cdp_key_event steps
+        playbookEngine.setCDPConnect(async (overridePort) => {
+            if (overridePort) {
+                if (!CDP)
+                    CDP = (await import("chrome-remote-interface")).default;
+                const client = await CDP({ port: overridePort });
+                return { Runtime: client.Runtime, Input: client.Input, close: () => client.close() };
+            }
+            const { CDP: CDPClient, port } = await ensureCDP();
+            const client = await CDPClient({ port });
+            return { Runtime: client.Runtime, Input: client.Input, close: () => client.close() };
+        });
         activeJobRunner = new JobRunner(bridge, jobManager, leaseManager, supervisor, (() => {
             const cfg = {
                 hasCDP: cdpPort !== null,
                 playbookEngine,
-                playbookStore,
+                playbookStore: activePlaybookStore,
                 runtimeService,
             };
             if (cdpPort) {
@@ -2485,243 +4817,1056 @@ originalTool("worker_status", "Get the current status of the worker daemon (read
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // ═══════════════════════════════════════════════
-// CODEX MONITOR — watch VS Code terminals, auto-assign tasks
+// PLANNER — goal-oriented planning
 // ═══════════════════════════════════════════════
-// Daemon state directory
-const MONITOR_DIR = path.join(os.homedir(), ".screenhand", "monitor");
-const MONITOR_STATE = path.join(MONITOR_DIR, "state.json");
-const MONITOR_TASKS = path.join(MONITOR_DIR, "tasks.json");
-const MONITOR_PID = path.join(MONITOR_DIR, "daemon.pid");
-const MONITOR_LOG = path.join(MONITOR_DIR, "daemon.log");
-const DAEMON_SCRIPT = path.resolve(__dirname, "scripts", "codex-monitor-daemon.ts");
-function isDaemonRunning() {
-    try {
-        if (!fs.existsSync(MONITOR_PID))
-            return { running: false, pid: null };
-        const pid = Number(fs.readFileSync(MONITOR_PID, "utf-8").trim());
-        // Check if process is alive
-        process.kill(pid, 0);
-        return { running: true, pid };
+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.", {
+    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);
+    await planner.planGoal(goal);
+    goalStore.add(goal);
+    const sg = goal.subgoals[0];
+    const plan = sg.plan;
+    if (!plan) {
+        return { content: [{ type: "text", text: "No plan could be generated." }] };
     }
-    catch {
-        return { running: false, pid: null };
+    const lines = [
+        `Goal: ${goalDescription}`,
+        `Plan source: ${plan.source}${plan.sourceId ? ` (${plan.sourceId})` : ""}`,
+        `Confidence: ${(plan.confidence * 100).toFixed(0)}%`,
+        `Steps: ${plan.steps.length}`,
+        "",
+    ];
+    for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        const params = Object.keys(step.params).length > 0
+            ? ` ${JSON.stringify(step.params)}`
+            : "";
+        const llmTag = step.requiresLLM ? " [LLM]" : "";
+        const postcond = step.expectedPostcondition
+            ? ` → verify: ${step.expectedPostcondition.type}(${step.expectedPostcondition.target})`
+            : "";
+        lines.push(`  ${i + 1}. ${step.tool || step.description}${params}${llmTag}${postcond}`);
     }
-}
-function readDaemonState() {
-    try {
-        if (!fs.existsSync(MONITOR_STATE))
-            return null;
-        return JSON.parse(fs.readFileSync(MONITOR_STATE, "utf-8"));
+    lines.push("", `Goal ID: ${goal.id}`);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        _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.", {
+    goalId: z.string().describe("Goal ID from plan_goal"),
+}, async ({ goalId }) => {
+    const goal = goalStore.get(goalId);
+    if (!goal) {
+        return { content: [{ type: "text", text: `Goal not found: ${goalId}` }] };
     }
-    catch {
-        return null;
+    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);
+    const result = await executor.executeGoal(goal);
+    goalStore.update(goalId, goal);
+    // Check if paused at an LLM step
+    if ("paused" in result) {
+        const pause = result;
+        return {
+            content: [{ type: "text", text: [
+                        `PAUSED at step ${pause.stepIndex + 1}/${pause.totalSteps} — requires your interpretation.`,
+                        `Step: ${pause.stepDescription}`,
+                        "",
+                        "Use plan_step_resolve to provide the tool + params for this step,",
+                        "then call plan_execute again to continue.",
+                    ].join("\n") }],
+            _meta: { goalId, paused: true, stepIndex: pause.stepIndex },
+        };
     }
-}
-function readDaemonTasks() {
-    try {
-        if (!fs.existsSync(MONITOR_TASKS))
-            return [];
-        return JSON.parse(fs.readFileSync(MONITOR_TASKS, "utf-8"));
+    // Completed — save strategy to memory if successful
+    if (result.success) {
+        try {
+            const sg = goal.subgoals.find((s) => s.status === "completed");
+            if (sg?.plan) {
+                const steps = sg.plan.steps
+                    .filter((s) => s.status === "completed" && s.tool)
+                    .map((s) => ({ tool: s.tool, params: s.params }));
+                if (steps.length > 0) {
+                    memory.appendStrategy({
+                        id: "str_plan_" + Date.now().toString(36),
+                        task: goal.description,
+                        steps,
+                        totalDurationMs: result.durationMs,
+                        successCount: 1,
+                        failCount: 0,
+                        lastUsed: new Date().toISOString(),
+                        tags: ["auto-plan", sg.plan.source],
+                        fingerprint: "",
+                    });
+                }
+            }
+        }
+        catch { /* strategy recording is best-effort */ }
     }
-    catch {
-        return [];
+    const lines = [
+        result.success ? "Goal completed successfully." : `Goal failed: ${result.error}`,
+        `Steps: ${result.stepsExecuted} executed, ${result.replans} replans`,
+        `Duration: ${result.durationMs}ms`,
+        `Subgoals: ${result.subgoalsCompleted}/${result.totalSubgoals} completed`,
+        "",
+        "── EXECUTION LOG ──",
+        ...("executionLog" in result ? result.executionLog : []),
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("plan_step", "Execute the next single step of a goal. For incremental client-driven execution. Returns the step result, or pauses at LLM steps for you to interpret.", {
+    goalId: z.string().describe("Goal ID from plan_goal"),
+}, async ({ goalId }) => {
+    const goal = goalStore.get(goalId);
+    if (!goal) {
+        return { content: [{ type: "text", text: `Goal not found: ${goalId}` }] };
     }
-}
-function writeDaemonTasks(tasks) {
-    fs.mkdirSync(MONITOR_DIR, { recursive: true });
-    fs.writeFileSync(MONITOR_TASKS, JSON.stringify(tasks, null, 2));
-}
-server.tool("codex_monitor_start", "Start a background daemon that monitors VS Code terminals for Codex/AI agent activity. Runs independently — survives Claude Code restarts. Watches terminal output via OCR, detects running/idle/done.", {
-    vscodePid: z.number().describe("Process ID of VS Code (get from 'apps' tool)"),
-    windowId: z.number().optional().describe("Window ID of the VS Code window (get from 'windows' tool). Auto-detected if omitted."),
-    label: z.string().optional().describe("Label for this terminal (default: 'Terminal')"),
-    pollIntervalMs: z.number().optional().describe("How often to poll in ms (default: 3000)"),
-    autoAssign: z.boolean().optional().describe("Auto-assign queued tasks when terminal goes idle (default: true)"),
-}, async ({ vscodePid, windowId, label, pollIntervalMs, autoAssign }) => {
-    const { running, pid } = isDaemonRunning();
-    if (running) {
-        return { content: [{ type: "text", text: `Daemon already running (pid=${pid}). Use codex_monitor_stop first to restart.` }] };
-    }
-    // Build daemon args
-    const daemonArgs = ["tsx", DAEMON_SCRIPT, "--pid", String(vscodePid)];
-    if (windowId)
-        daemonArgs.push("--window", String(windowId));
-    if (pollIntervalMs)
-        daemonArgs.push("--poll", String(pollIntervalMs));
-    if (label)
-        daemonArgs.push("--label", label);
-    if (autoAssign === false)
-        daemonArgs.push("--no-auto-assign");
-    // Spawn detached daemon
-    const child = spawn("npx", daemonArgs, {
-        detached: true,
-        stdio: "ignore",
-        cwd: __dirname,
-    });
-    child.unref();
-    const daemonPid = child.pid;
-    // Wait a moment for daemon to start and write state
-    await new Promise((r) => setTimeout(r, 3000));
-    const state = readDaemonState();
-    const terminalId = state?.terminals?.[0]?.id ?? "pending";
+    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);
+    const result = await executor.executeNextStep(goal);
+    goalStore.update(goalId, goal);
+    if ("paused" in result) {
+        const pause = result;
+        return {
+            content: [{ type: "text", text: [
+                        `Step ${pause.stepIndex + 1}/${pause.totalSteps} requires LLM interpretation:`,
+                        `  ${pause.stepDescription}`,
+                        "",
+                        "Use plan_step_resolve to provide tool + params, or execute the step yourself and call plan_step again.",
+                    ].join("\n") }],
+        };
+    }
+    if ("goalId" in result) {
+        // PlanResult — goal completed
+        return {
+            content: [{ type: "text", text: result.success
+                        ? `Goal completed: ${result.subgoalsCompleted}/${result.totalSubgoals} subgoals done.`
+                        : `Goal failed: ${result.error}` }],
+        };
+    }
+    // StepResult
+    const sr = result;
     return {
-        content: [{
-                type: "text",
-                text: `Background daemon started!\n` +
-                    `Daemon PID: ${daemonPid}\n` +
-                    `Terminal ID: ${terminalId}\n` +
-                    `VS Code PID: ${vscodePid}\n` +
-                    `Window ID: ${windowId ?? "auto-detecting"}\n` +
-                    `Poll interval: ${pollIntervalMs ?? 3000}ms\n` +
-                    `Auto-assign: ${autoAssign !== false}\n` +
-                    `Log: ${MONITOR_LOG}\n` +
-                    `State: ${MONITOR_STATE}\n\n` +
-                    `The daemon runs independently — survives Claude Code restarts.\n` +
-                    `Use codex_monitor_status to check on it anytime.`,
-            }],
+        content: [{ type: "text", text: [
+                    sr.success ? `Step completed: ${sr.step.tool}` : `Step failed: ${sr.error}`,
+                    `Duration: ${sr.durationMs}ms`,
+                    sr.usedFallback ? "(used fallback tool)" : "",
+                    sr.postconditionMet ? "" : "Warning: postcondition not met",
+                ].filter(Boolean).join("\n") }],
     };
 });
-server.tool("codex_monitor_status", "Get status of the background monitor daemon. Shows terminal status, agent activity, task queue, and daemon health.", {
-    tail_log: z.number().optional().describe("Show last N lines of daemon log (default: 0, max: 50)"),
-}, async ({ tail_log }) => {
-    const { running, pid } = isDaemonRunning();
-    const state = readDaemonState();
-    const tasks = readDaemonTasks();
+originalTool("plan_step_resolve", "Resolve a paused LLM step by providing the tool and params to use. The server executes the tool, verifies postconditions, and advances the plan.", {
+    goalId: z.string().describe("Goal ID"),
+    tool: z.string().describe("MCP tool name to execute for this step"),
+    params: z.record(z.string(), z.unknown()).optional().describe("Tool parameters"),
+}, async ({ goalId, tool, params }) => {
+    const goal = goalStore.get(goalId);
+    if (!goal) {
+        return { content: [{ type: "text", text: `Goal not found: ${goalId}` }] };
+    }
+    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);
+    const result = await executor.resolveStep(goal, tool, params ?? {});
+    goalStore.update(goalId, goal);
+    return {
+        content: [{ type: "text", text: result.success
+                    ? `Step resolved and completed: ${tool}`
+                    : `Step failed: ${result.error}` }],
+    };
+});
+originalTool("plan_status", "Check the current status of a goal: subgoal progress, current step, completion state.", {
+    goalId: z.string().describe("Goal ID"),
+}, async ({ goalId }) => {
+    const goal = goalStore.get(goalId);
+    if (!goal) {
+        return { content: [{ type: "text", text: `Goal not found: ${goalId}` }] };
+    }
+    const lines = [
+        `Goal: ${goal.description}`,
+        `Status: ${goal.status}`,
+        `Created: ${goal.createdAt}`,
+        goal.completedAt ? `Completed: ${goal.completedAt}` : "",
+        "",
+    ].filter(Boolean);
+    for (let i = 0; i < goal.subgoals.length; i++) {
+        const sg = goal.subgoals[i];
+        const plan = sg.plan;
+        const progress = plan
+            ? `${plan.currentStepIndex}/${plan.steps.length} steps`
+            : "no plan";
+        lines.push(`  Subgoal ${i + 1}: ${sg.status} (${progress}, ${sg.attempts} attempts)`);
+        if (sg.lastError)
+            lines.push(`    Error: ${sg.lastError}`);
+    }
+    if (goal.pausedAt) {
+        lines.push("", `Paused at: subgoal ${goal.pausedAt.subgoalIndex + 1}, step ${goal.pausedAt.stepIndex + 1}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("plan_list", "List all goals (active, completed, failed). Optionally filter by status.", {
+    status: z.string().optional().describe("Filter by status: pending, active, completed, failed"),
+}, async ({ status }) => {
+    const goals = status
+        ? goalStore.list(status)
+        : goalStore.list();
+    if (goals.length === 0) {
+        return { content: [{ type: "text", text: "No goals found." }] };
+    }
+    const lines = goals.map((g) => {
+        const sgDone = g.subgoals.filter((s) => s.status === "completed").length;
+        return `  ${g.id}: ${g.status} — "${g.description}" (${sgDone}/${g.subgoals.length} subgoals, ${g.createdAt})`;
+    });
+    return { content: [{ type: "text", text: [`${goals.length} goal(s):`, ...lines].join("\n") }] };
+});
+// ═══════════════════════════════════════════════
+// PERCEPTION + WORLD MODEL — continuous state tracking
+// ═══════════════════════════════════════════════
+originalTool("perception_status", "Get continuous perception status: multi-rate loop stats, freshness of AX/CDP/vision sources, and event counts.", {}, async () => {
+    const stats = perceptionManager.getStats();
+    const freshness = perceptionManager.getFreshnessSummary();
+    const lines = [
+        freshness,
+        `Running: ${perceptionManager.isRunning}`,
+    ];
+    if (stats.started) {
+        lines.push(`Started: ${stats.startedAt}`);
+        lines.push("");
+        const pcConfig = perceptionManager.getConfig();
+        lines.push("Loop cycles:");
+        lines.push(`  Fast  (${pcConfig?.fastIntervalMs ?? 100}ms): ${stats.fastCycles} cycles`);
+        lines.push(`  Medium (${pcConfig?.mediumIntervalMs ?? 500}ms): ${stats.mediumCycles} cycles`);
+        lines.push(`  Slow  (${pcConfig?.slowIntervalMs ?? 2000}ms): ${stats.slowCycles} cycles`);
+        lines.push("");
+        lines.push("Events processed:");
+        lines.push(`  AX events: ${stats.axEventsProcessed}`);
+        lines.push(`  AX tree polls: ${stats.axTreePolls}`);
+        lines.push(`  CDP mutations: ${stats.cdpMutationsProcessed}`);
+        lines.push(`  CDP snapshots: ${stats.cdpSnapshots}`);
+        lines.push(`  Vision diffs: ${stats.visionDiffs}`);
+        lines.push(`  Vision OCRs: ${stats.visionOCRs}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("world_state", "Get the current world model state: focused app, window/control counts, active dialogs, and last scan age. Use verbose=true to dump all controls.", {
+    verbose: z.boolean().optional().default(false).describe("Dump all controls with roles, labels, positions, and confidence"),
+}, async ({ verbose }) => {
+    const state = worldModel.getState();
+    const summary = worldModel.toSummary();
+    const focused = worldModel.getFocusedWindow();
+    const dialogs = worldModel.getActiveDialogs();
     const lines = [];
-    lines.push(`Daemon: ${running ? "RUNNING" : "STOPPED"} (pid=${pid ?? "none"})`);
-    if (state?.terminals) {
-        for (const t of state.terminals) {
-            const lastOutput = (t.lastOutput || "").split("\n").slice(-5).join("\n").trim();
-            lines.push("");
-            lines.push(`--- ${t.id} ---`);
-            lines.push(`  Status: ${(t.status || "unknown").toUpperCase()}`);
-            lines.push(`  VS Code PID: ${t.vscodePid}`);
-            lines.push(`  Window ID: ${t.windowId ?? "unknown"}`);
-            lines.push(`  Current task: ${t.lastTask ?? "none"}`);
-            lines.push(`  Tasks completed: ${t.tasksCompleted}`);
-            lines.push(`  Last poll: ${t.lastPollAt}`);
-            lines.push(`  Last output (tail):`);
-            lines.push(`    ${lastOutput.split("\n").join("\n    ")}`);
-        }
-    }
-    else if (!running) {
-        lines.push("\nNo monitor running. Use codex_monitor_start first.");
-    }
-    const queued = tasks.filter((t) => t.status === "queued").length;
-    const runningTasks = tasks.filter((t) => t.status === "running").length;
-    const completed = tasks.filter((t) => t.status === "completed").length;
+    // Warn when world model is empty
+    if (state.windows.size === 0 && !state.focusedApp) {
+        if (!perceptionManager.isRunning) {
+            lines.push("Warning: World model is empty. Run perception_start or use focus()/ui_tree to populate state.");
+        }
+        else {
+            lines.push("World model is empty — perception is running but no data received yet.");
+        }
+        lines.push("");
+    }
+    lines.push(summary);
+    if (focused) {
+        lines.push(`\nFocused window: "${focused.title.value}" (id=${focused.windowId}, ${focused.controls.size} controls, confidence=${focused.title.confidence.toFixed(2)})`);
+    }
+    if (dialogs.length > 0) {
+        lines.push("\nActive dialogs:");
+        for (const d of dialogs) {
+            lines.push(`  - ${d.type}: "${d.title}" (${d.controls.size} controls, detected ${d.detectedAt})`);
+        }
+    }
+    lines.push(`\nSession: ${state.sessionId || "(not initialized)"}`);
+    // Show browser domain state (URL, title, tabs) if available
+    for (const [bid, domain] of state.appDomains) {
+        if (domain.family === "browser") {
+            const bs = domain;
+            if (bs.url?.value || bs.title?.value) {
+                lines.push(`\nBrowser (${bid}):`);
+                if (bs.url?.value)
+                    lines.push(`  URL: ${bs.url.value}`);
+                if (bs.title?.value)
+                    lines.push(`  Title: ${bs.title.value}`);
+                if (bs.tabs && bs.tabs.length > 0) {
+                    lines.push(`  Tabs (${bs.tabs.length}):`);
+                    for (const tab of bs.tabs) {
+                        lines.push(`    ${tab.index}. ${tab.isActive ? "▸ " : "  "}${tab.title} | ${tab.url}`);
+                    }
+                }
+            }
+        }
+    }
+    // Show tracked entities
+    const entities = worldModel.getTrackedEntities();
+    if (entities.size > 0) {
+        lines.push(`\nTracked entities (${entities.size}):`);
+        for (const entity of entities.values()) {
+            const lastPos = entity.positions[entity.positions.length - 1];
+            const posStr = lastPos ? `(${lastPos.x},${lastPos.y})` : "";
+            lines.push(`  - ${entity.type}: "${entity.label}" ${posStr} (seen ${entity.positions.length}x, since ${entity.firstSeen})`);
+        }
+    }
+    if (verbose) {
+        lines.push("\n── ALL CONTROLS ──");
+        for (const [winId, win] of state.windows) {
+            lines.push(`\nWindow ${winId}: "${win.title.value}" (${win.bundleId ?? "?"})`);
+            if (win.focusedElement) {
+                lines.push(`  Focused: ${win.focusedElement.role} "${win.focusedElement.label.value}" @ (${win.focusedElement.position.x}, ${win.focusedElement.position.y})`);
+            }
+            // Group by role for readability
+            const byRole = new Map();
+            for (const ctrl of win.controls.values()) {
+                const role = ctrl.role;
+                if (!byRole.has(role))
+                    byRole.set(role, []);
+                byRole.get(role).push({
+                    label: ctrl.label.value || "(no label)",
+                    pos: `${Math.round(ctrl.position.x)},${Math.round(ctrl.position.y)}`,
+                    size: `${ctrl.size.width}x${ctrl.size.height}`,
+                    conf: ctrl.label.confidence.toFixed(2),
+                    focused: ctrl.focused,
+                });
+            }
+            for (const [role, controls] of [...byRole.entries()].sort((a, b) => b[1].length - a[1].length)) {
+                lines.push(`  [${role}] (${controls.length})`);
+                for (const c of controls.slice(0, 50)) {
+                    const focus = c.focused ? " *FOCUSED*" : "";
+                    lines.push(`    "${c.label}" @ (${c.pos}) ${c.size} conf=${c.conf}${focus}`);
+                }
+                if (controls.length > 50)
+                    lines.push(`    ... +${controls.length - 50} more`);
+            }
+        }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("world_state_diff", "Get stale UI controls that haven't been refreshed within a threshold. Useful for finding controls whose state may be outdated.", {
+    thresholdMs: z.number().optional().describe("Stale threshold in ms (default: 5 minutes)"),
+}, async ({ thresholdMs }) => {
+    const stale = worldModel.getStaleControls(thresholdMs);
+    if (stale.length === 0) {
+        // Distinguish "no data" from "all fresh"
+        const totalControls = Array.from(worldModel.getState().windows.values()).reduce((sum, w) => sum + w.controls.size, 0);
+        if (totalControls === 0) {
+            const hint = perceptionManager.isRunning
+                ? "Perception is running but no controls tracked yet."
+                : "Run perception_start or ui_tree to populate state.";
+            return { content: [{ type: "text", text: `World model has no tracked controls. ${hint}` }] };
+        }
+        return { content: [{ type: "text", text: "No stale controls — all state is fresh." }] };
+    }
+    const lines = [`${stale.length} stale control(s):`];
+    for (const c of stale.slice(0, 20)) {
+        const age = Math.round((Date.now() - new Date(c.value.updatedAt).getTime()) / 1000);
+        lines.push(`  ${c.stableId} ${c.role} "${c.label.value}" — ${age}s old`);
+    }
+    if (stale.length > 20)
+        lines.push(`  ... and ${stale.length - 20} more`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("learning_status", "Get learning engine stats: locator preferences, recovery strategy rankings, adaptive budgets, and sensor preferences for a given app.", {
+    bundleId: z.string().optional().describe("App bundle ID to query (default: currently focused app)"),
+}, async ({ bundleId }) => {
+    const bid = bundleId ?? worldModel.getState().focusedApp?.bundleId ?? "unknown";
+    const summary = learningEngine.getAppSummary(bid);
+    const lines = [
+        `Learning stats for ${bid}:`,
+        `  Locator entries: ${summary.locatorEntries}`,
+        `  Recovery entries: ${summary.recoveryEntries}`,
+        `  Timing samples: ${summary.timingSamples}`,
+        `  Sensor entries: ${summary.sensorEntries}`,
+    ];
+    if (summary.topLocatorMethod) {
+        lines.push(`  Best locator method: ${summary.topLocatorMethod}`);
+    }
+    if (summary.topSensor) {
+        lines.push(`  Best sensor: ${summary.topSensor}`);
+    }
     lines.push("");
-    lines.push(`Tasks: ${queued} queued, ${runningTasks} running, ${completed} completed`);
-    // Optionally show daemon log tail
-    if (tail_log && tail_log > 0) {
+    lines.push("Adaptive budgets:");
+    lines.push(`  Locate: ${summary.adaptiveBudget.locateMs}ms`);
+    lines.push(`  Act: ${summary.adaptiveBudget.actMs}ms`);
+    lines.push(`  Verify: ${summary.adaptiveBudget.verifyMs}ms`);
+    const sensors = learningEngine.rankSensors(bid);
+    if (sensors.length > 0) {
+        lines.push("");
+        lines.push("Sensor ranking:");
+        for (const s of sensors) {
+            lines.push(`  ${s.sourceType}: score=${s.score.toFixed(3)}, avg=${Math.round(s.avgLatencyMs)}ms`);
+        }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+// ── Perception lifecycle ──
+originalTool("perception_start", "Start continuous perception for the currently focused app (or specify bundleId). Begins multi-rate AX/CDP/vision polling loop: FAST (100ms AX events), MEDIUM (300ms AX/CDP poll), SLOW (1000ms vision/OCR).", {
+    bundleId: z.string().optional().describe("Optional: specify app bundle ID directly instead of using focused app"),
+}, async ({ bundleId: overrideBundleId }) => {
+    // Already running check
+    if (perceptionManager.isRunning && !overrideBundleId) {
+        const stats = perceptionManager.getStats();
+        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;
+    // If bundleId override provided, try to resolve app info via bridge or AppleScript
+    if (overrideBundleId && (!app || app.bundleId !== overrideBundleId)) {
         try {
-            const logContent = fs.readFileSync(MONITOR_LOG, "utf-8");
-            const logLines = logContent.trim().split("\n").slice(-(Math.min(tail_log, 50)));
-            lines.push("");
-            lines.push("--- Daemon Log ---");
-            lines.push(logLines.join("\n"));
+            await ensureBridge();
+            const apps = await bridge.call("app.list", {});
+            const found = apps?.find((a) => a.bundleId === overrideBundleId);
+            if (found) {
+                app = { bundleId: overrideBundleId, appName: found.name ?? overrideBundleId, pid: found.pid };
+                worldModel.updateFocusedApp({ bundleId: overrideBundleId, appName: found.name ?? overrideBundleId, pid: found.pid, windowTitle: "" });
+            }
         }
-        catch {
-            lines.push("\n(no log file found)");
+        catch { /* Bridge unavailable — fall through to AppleScript */ }
+        // AppleScript fallback: bridge may not list windowless apps (e.g. freshly launched/killed TextEdit)
+        if (!app || app.bundleId !== overrideBundleId) {
+            try {
+                const { stdout } = await execAsync(`osascript -e 'tell application "System Events" to get unix id of (first process whose bundle identifier is "${overrideBundleId.replace(/'/g, "'\\''")}")'`, { encoding: "utf-8", timeout: 5000 });
+                const pid = parseInt((stdout ?? "").trim(), 10);
+                if (!isNaN(pid)) {
+                    app = { bundleId: overrideBundleId, appName: overrideBundleId, pid };
+                    worldModel.updateFocusedApp({ bundleId: overrideBundleId, appName: overrideBundleId, pid, windowTitle: "" });
+                }
+            }
+            catch { /* AppleScript also failed — app truly not running */ }
+        }
+    }
+    // If bundleId was explicitly provided but we couldn't find the app, error out
+    // instead of silently falling back to the frontmost app
+    if (overrideBundleId && (!app || app.bundleId !== overrideBundleId)) {
+        return { content: [{ type: "text", text: `Error: App with bundleId "${overrideBundleId}" is not running. Launch it first with launch(bundleId: "${overrideBundleId}").` }] };
+    }
+    // If still no app, try AppleScript to detect frontmost app
+    if (!app) {
+        try {
+            const asScript = `tell application "System Events"
+set fp to first process whose frontmost is true
+return (bundle identifier of fp) & "|" & (name of fp) & "|" & (unix id of fp)
+end tell`;
+            const { stdout: asOut } = await execAsync(`osascript -e '${asScript.replace(/'/g, "'\\''")}'`, { encoding: "utf-8", timeout: 5000 });
+            const result = asOut ?? "";
+            const [bid, name, pidStr] = result.trim().split("|");
+            const pid = parseInt(pidStr ?? "", 10);
+            if (bid && !isNaN(pid)) {
+                app = { bundleId: bid, appName: name ?? bid, pid };
+                worldModel.updateFocusedApp({ bundleId: bid, appName: name ?? bid, pid, windowTitle: "" });
+            }
         }
+        catch { /* AppleScript fallback failed */ }
+    }
+    if (!app) {
+        return { content: [{ type: "text", text: "Error: No focused app detected. Focus an app with focus() first, or pass bundleId directly." }] };
+    }
+    let bridgeAvailable = false;
+    try {
+        await ensureBridge();
+        bridgeAvailable = true;
+    }
+    catch { /* bridge unavailable — proceed without AX/vision */ }
+    let windowId;
+    if (bridgeAvailable) {
+        try {
+            windowId = await resolveWindowId(app.pid);
+        }
+        catch { /* best-effort */ }
+    }
+    const ctx = { bundleId: app.bundleId, appName: app.appName, pid: app.pid, windowTitle: "", ...(windowId != null ? { windowId } : {}) };
+    await perceptionManager.ensureStarted(ctx);
+    // Auto-connect CDP for browser apps — pass a connect factory so the
+    // perception coordinator can reconnect when the WebSocket drops
+    let cdpStatus = "skipped (not browser)";
+    const isBrowser = isBrowserApp();
+    console.error(`[perception_start] app=${app.bundleId} pid=${app.pid} windowId=${windowId} isBrowser=${isBrowser}`);
+    if (isBrowser) {
+        try {
+            console.error("[perception_start] calling ensureCDP...");
+            const { CDP: cdp, port } = await ensureCDP();
+            console.error(`[perception_start] ensureCDP ok, port=${port}`);
+            const connectFn = async () => {
+                const targets = await cdp.List({ port });
+                const page = targets.find((t) => t.type === "page");
+                if (!page)
+                    throw new Error("No CDP page target");
+                return cdp({ port, target: page.id });
+            };
+            const client = await connectFn();
+            console.error(`[perception_start] CDP client created, client keys: ${Object.keys(client).slice(0, 5).join(",")}`);
+            const coordinator = perceptionManager.getCoordinator();
+            console.error(`[perception_start] coordinator exists: ${!!coordinator}, isRunning: ${coordinator?.isRunning}`);
+            if (coordinator) {
+                coordinator.activateCDP(client, connectFn);
+                cdpStatus = `connected (port ${port})`;
+            }
+            else {
+                cdpStatus = "no coordinator";
+            }
+        }
+        catch (e) {
+            cdpStatus = `failed: ${e?.message ?? e}`;
+            console.error(`[perception_start] CDP error: ${cdpStatus}`);
+        }
+    }
+    console.error(`[perception_start] CDP status: ${cdpStatus}`);
+    // Set up Safari browser enricher (or clear it for non-Safari)
+    installSafariEnricher(app.bundleId);
+    return { content: [{ type: "text", text: `Perception started for ${app.bundleId} (${app.appName}). CDP: ${cdpStatus}` }] };
+});
+originalTool("perception_stop", "Stop continuous perception loop.", {}, async () => {
+    if (!perceptionManager.isRunning) {
+        return { content: [{ type: "text", text: "Perception was not running." }] };
+    }
+    const stats = perceptionManager.getStats();
+    await perceptionManager.stop();
+    const lines = ["Perception stopped."];
+    if (stats.started) {
+        lines.push(`Processed: ${stats.axEventsProcessed} AX events, ${stats.cdpSnapshots} CDP snapshots, ${stats.visionDiffs} vision diffs, ${stats.visionOCRs} OCRs.`);
+        lines.push(`Cycles: ${stats.fastCycles} fast, ${stats.mediumCycles} medium, ${stats.slowCycles} slow.`);
     }
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
-server.tool("codex_monitor_add_task", "Add a task to the daemon's queue. When a monitored terminal goes idle, the next task is automatically typed in and executed.", {
-    prompt: z.string().describe("The prompt/command to send to Codex when a terminal is available"),
-    priority: z.number().optional().describe("Priority (lower = higher priority, default: 10)"),
-    terminalId: z.string().optional().describe("Assign to a specific terminal (omit for any available)"),
-}, async ({ prompt, priority, terminalId }) => {
-    const tasks = readDaemonTasks();
-    const task = {
-        id: "task_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
-        prompt,
-        priority: priority ?? 10,
-        terminalId: terminalId ?? null,
-        status: "queued",
-        createdAt: new Date().toISOString(),
-        assignedAt: null,
-        completedAt: null,
-        result: null,
-    };
-    tasks.push(task);
-    tasks.sort((a, b) => a.priority - b.priority);
-    writeDaemonTasks(tasks);
-    const queued = tasks.filter((t) => t.status === "queued").length;
-    return {
-        content: [{
-                type: "text",
-                text: `Task queued!\n` +
-                    `ID: ${task.id}\n` +
-                    `Prompt: "${prompt.slice(0, 100)}${prompt.length > 100 ? "..." : ""}"\n` +
-                    `Priority: ${task.priority}\n` +
-                    `Target terminal: ${task.terminalId ?? "any available"}\n` +
-                    `Queue size: ${queued}`,
-            }],
-    };
+// ── Plan lifecycle ──
+originalTool("plan_cancel", "Cancel an active goal, marking it as failed.", {
+    goalId: z.string().describe("Goal ID to cancel"),
+}, async ({ goalId }) => {
+    const goal = goalStore.get(goalId);
+    if (!goal) {
+        return { content: [{ type: "text", text: `Goal not found: ${goalId}` }] };
+    }
+    goal.status = "failed";
+    goal.completedAt = new Date().toISOString();
+    goalStore.update(goalId, goal);
+    return { content: [{ type: "text", text: `Goal cancelled: ${goalId}` }] };
 });
-server.tool("codex_monitor_tasks", "List all tasks in the daemon's queue with their status.", {
-    status: z.enum(["all", "queued", "running", "completed", "failed"]).optional().describe("Filter by status (default: all)"),
-}, async ({ status }) => {
-    let tasks = readDaemonTasks();
-    if (status && status !== "all") {
-        tasks = tasks.filter((t) => t.status === status);
-    }
-    if (tasks.length === 0) {
-        return { content: [{ type: "text", text: `No ${status ?? ""} tasks.` }] };
-    }
-    const lines = tasks.map((t, i) => {
-        const parts = [
-            `${i + 1}. [${t.status.toUpperCase()}] "${(t.prompt || "").slice(0, 80)}"`,
-            `   ID: ${t.id} | Priority: ${t.priority}`,
-            `   Terminal: ${t.terminalId ?? "any"}`,
-            `   Created: ${t.createdAt}`,
-        ];
-        if (t.assignedAt)
-            parts.push(`   Assigned: ${t.assignedAt}`);
-        if (t.completedAt)
-            parts.push(`   Completed: ${t.completedAt}`);
-        if (t.result)
-            parts.push(`   Result: ${(t.result || "").slice(0, 100)}`);
-        return parts.join("\n");
-    });
-    return { content: [{ type: "text", text: lines.join("\n\n") }] };
+// ── Recovery status + configure ──
+originalTool("recovery_status", "Get recovery engine status: cooldowns, reference cache, learning engine connection.", {}, async () => {
+    const status = recoveryEngine.getStatus();
+    const lines = [
+        "Recovery Engine Status:",
+        `  Active cooldowns: ${status.cooldownCount}`,
+        `  Reference cache entries: ${status.referenceCacheSize}`,
+        `  Learning engine connected: ${status.learningEngineConnected}`,
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
 });
-server.tool("codex_monitor_assign_now", "Immediately type a prompt into the VS Code terminal (bypasses queue). Focuses VS Code, types, presses Enter.", {
-    prompt: z.string().describe("The prompt/command to type into the terminal"),
-}, async ({ prompt }) => {
-    await ensureBridge();
+originalTool("recovery_configure", "Update recovery engine default budget configuration.", {
+    maxRecoveryTimeMs: z.number().optional().describe("Max time for recovery attempts in ms"),
+    maxStrategies: z.number().optional().describe("Max number of strategies to try"),
+}, async ({ maxRecoveryTimeMs, maxStrategies }) => {
+    const updates = {};
+    if (maxRecoveryTimeMs !== undefined)
+        updates.maxRecoveryTimeMs = maxRecoveryTimeMs;
+    if (maxStrategies !== undefined)
+        updates.maxStrategies = maxStrategies;
+    recoveryEngine.configure(updates);
+    return { content: [{ type: "text", text: `Recovery config updated: ${JSON.stringify(updates)}` }] };
+});
+// ── Learning lifecycle ──
+originalTool("learning_reset", "Clear ALL learning data (locators, recovery, timing, sensors). Requires confirm=true.", {
+    confirm: z.boolean().describe("Must be true to proceed"),
+}, async ({ confirm }) => {
+    if (!confirm) {
+        return { content: [{ type: "text", text: "Aborted: set confirm=true to clear all learning data." }] };
+    }
+    learningEngine.reset();
+    return { content: [{ type: "text", text: "All learning data cleared and flushed to disk." }] };
+});
+// ═══════════════════════════════════════════════
+// ORCHESTRATOR — multi-agent task routing
+// ═══════════════════════════════════════════════
+const ORCHESTRATOR_DAEMON_SCRIPT = path.resolve(__dirname, "scripts", "orchestrator-daemon.ts");
+server.tool("orchestrator_start", "Start the multi-agent orchestrator daemon. Manages parallel worker slots: web tasks (CDP) run in parallel, native tasks (AX/keyboard) are serialized per-app. Survives restarts.", {
+    webSlots: z.number().optional().describe("Number of parallel web worker slots (default: 4)"),
+    nativeSlots: z.number().optional().describe("Number of native worker slots (default: 1)"),
+    pollMs: z.number().optional().describe("Poll interval in ms (default: 1000)"),
+}, async ({ webSlots, nativeSlots, pollMs }) => {
+    const existingPid = getOrchestratorPid();
+    if (existingPid !== null) {
+        return { content: [{ type: "text", text: `Orchestrator already running (pid=${existingPid}). Use orchestrator_stop first.` }] };
+    }
+    const compiledPath = fs.existsSync(path.resolve(__dirname, "scripts", "orchestrator-daemon.js"))
+        ? path.resolve(__dirname, "scripts", "orchestrator-daemon.js")
+        : path.resolve(__dirname, "dist", "scripts", "orchestrator-daemon.js");
+    const daemonArgs = [];
+    let child;
+    let usedCompiled = false;
+    if (fs.existsSync(compiledPath)) {
+        daemonArgs.push(compiledPath);
+        if (webSlots)
+            daemonArgs.push("--web-slots", String(webSlots));
+        if (nativeSlots)
+            daemonArgs.push("--native-slots", String(nativeSlots));
+        if (pollMs)
+            daemonArgs.push("--poll", String(pollMs));
+        child = spawn("node", daemonArgs, { detached: true, stdio: "ignore", cwd: __dirname });
+        usedCompiled = true;
+    }
+    else {
+        daemonArgs.push("tsx", ORCHESTRATOR_DAEMON_SCRIPT);
+        if (webSlots)
+            daemonArgs.push("--web-slots", String(webSlots));
+        if (nativeSlots)
+            daemonArgs.push("--native-slots", String(nativeSlots));
+        if (pollMs)
+            daemonArgs.push("--poll", String(pollMs));
+        child = spawn("npx", daemonArgs, { detached: true, stdio: "ignore", cwd: __dirname });
+    }
+    child.unref();
+    await new Promise((r) => setTimeout(r, 3000));
+    const verifyPid = getOrchestratorPid();
+    if (!verifyPid) {
+        return { content: [{ type: "text", text: `Orchestrator failed to start (mode=${usedCompiled ? "compiled" : "tsx"}).\nCheck log: ${ORCH_LOG_FILE}` }] };
+    }
+    return { content: [{ type: "text", text: `Orchestrator started (pid=${verifyPid}).\nWeb slots: ${webSlots ?? 4} (parallel CDP) | Native slots: ${nativeSlots ?? 1} (serialized per-app)\nPoll: ${pollMs ?? 1000}ms\nLog: ${ORCH_LOG_FILE}\n\nSubmit tasks with orchestrator_submit. Web tasks run in parallel, native tasks queue per-app.` }] };
+});
+server.tool("orchestrator_stop", "Stop the orchestrator daemon. Running tasks finish before exit.", {}, async () => {
+    const pid = getOrchestratorPid();
+    if (!pid) {
+        return { content: [{ type: "text", text: "No orchestrator daemon running." }] };
+    }
     try {
-        await bridge.call("app.focus", { bundleId: "com.microsoft.VSCode" });
-        await new Promise((r) => setTimeout(r, 300));
-        await bridge.call("cg.typeText", { text: prompt });
-        await new Promise((r) => setTimeout(r, 100));
-        await bridge.call("cg.keyCombo", { keys: ["enter"] });
-        return { content: [{ type: "text", text: `Typed and sent: "${prompt.slice(0, 100)}"` }] };
+        process.kill(pid, "SIGTERM");
+        await new Promise((r) => setTimeout(r, 2000));
+        return { content: [{ type: "text", text: `Orchestrator stopped (pid=${pid}).` }] };
     }
     catch (err) {
-        return { content: [{ type: "text", text: `Failed: ${err.message}` }] };
+        return { content: [{ type: "text", text: `Failed to stop: ${err.message}` }] };
     }
 });
-server.tool("codex_monitor_stop", "Stop the background monitor daemon.", {}, async () => {
-    const { running, pid } = isDaemonRunning();
-    if (!running) {
-        return { content: [{ type: "text", text: "No daemon running." }] };
+server.tool("orchestrator_submit", "Submit a task to the orchestrator. Web tasks (CDP) run in parallel, native tasks queue per-app. Returns immediately — task is processed asynchronously.", {
+    task: z.string().describe("What to do"),
+    mode: z.enum(["web", "native", "mixed"]).optional().describe("Execution mode: web (parallel CDP), native (serialized AX/keyboard), mixed (default: auto-detect)"),
+    playbookId: z.string().optional().describe("Playbook to execute"),
+    bundleId: z.string().optional().describe("Target app bundle ID (required for native tasks)"),
+    windowId: z.number().optional().describe("Target window ID"),
+    vars: z.record(z.string(), z.string()).optional().describe("Variables for playbook substitution"),
+    priority: z.number().optional().describe("Priority: lower = higher (default: 10)"),
+}, async ({ task, mode, playbookId, bundleId, windowId, vars, priority }) => {
+    const state = readOrchState();
+    if (!state?.running) {
+        return { content: [{ type: "text", text: "Orchestrator not running. Use orchestrator_start first." }] };
+    }
+    const newTask = createOrchestratorTask(task, {
+        mode: mode ?? detectMode(playbookId, bundleId),
+        ...(playbookId !== undefined ? { playbookId } : {}),
+        ...(bundleId !== undefined ? { bundleId } : {}),
+        ...(windowId !== undefined ? { windowId } : {}),
+        ...(vars ? { vars } : {}),
+        ...(priority !== undefined ? { priority } : {}),
+    });
+    state.tasks.push(newTask);
+    state.totalSubmitted++;
+    writeOrchState(state);
+    const slotInfo = newTask.mode === "web"
+        ? `→ will run on next free web slot (${state.webSlots} available)`
+        : `→ will run on native slot (serialized for ${bundleId ?? "unknown app"})`;
+    return { content: [{ type: "text", text: `Task submitted: ${newTask.id}\nMode: ${newTask.mode} ${slotInfo}\nPriority: ${newTask.priority}\n\nThe orchestrator will pick it up on the next poll cycle.` }] };
+});
+server.tool("orchestrator_status", "Get orchestrator status — worker slots, task queue, active/completed tasks.", {}, async () => {
+    const state = readOrchState();
+    if (!state) {
+        return { content: [{ type: "text", text: "Orchestrator not running. Use orchestrator_start first." }] };
+    }
+    const lines = [
+        `Running: ${state.running}${state.pid ? ` (pid=${state.pid})` : ""}`,
+        `Started: ${state.startedAt}`,
+        `Slots: ${state.webSlots} web (parallel) + ${state.nativeSlots} native (per-app serial)`,
+        "",
+        "Workers:",
+    ];
+    for (const w of state.workers) {
+        const status = w.busy ? `BUSY → ${w.currentTaskId}` : "idle";
+        lines.push(`  [${w.id}] ${w.type} — ${status} (done: ${w.tasksCompleted}, failed: ${w.tasksFailed})`);
+    }
+    const queued = state.tasks.filter(t => t.status === "queued");
+    const running = state.tasks.filter(t => t.status === "running" || t.status === "assigned");
+    const done = state.tasks.filter(t => t.status === "done");
+    const failed = state.tasks.filter(t => t.status === "failed");
+    const blocked = state.tasks.filter(t => t.status === "blocked");
+    lines.push("", `Tasks: ${state.totalSubmitted} submitted, ${state.totalCompleted} done, ${state.totalFailed} failed`);
+    lines.push(`Queue: ${queued.length} queued, ${running.length} running, ${blocked.length} blocked`);
+    if (running.length > 0) {
+        lines.push("", "Running:");
+        for (const t of running) {
+            lines.push(`  ${t.id}: "${t.task.slice(0, 60)}" [${t.mode}] → slot ${t.assignedWorker}`);
+        }
+    }
+    if (queued.length > 0) {
+        lines.push("", `Queued (next ${Math.min(queued.length, 5)}):`);
+        for (const t of queued.slice(0, 5)) {
+            lines.push(`  ${t.id}: "${t.task.slice(0, 60)}" [${t.mode}] priority=${t.priority}`);
+        }
+    }
+    if (done.length > 0) {
+        lines.push("", `Recent completed (last ${Math.min(done.length, 5)}):`);
+        for (const t of done.slice(-5)) {
+            lines.push(`  ${t.id}: "${t.task.slice(0, 60)}" → ${t.result?.slice(0, 80) ?? "ok"}`);
+        }
+    }
+    if (failed.length > 0) {
+        lines.push("", `Recent failed (last ${Math.min(failed.length, 3)}):`);
+        for (const t of failed.slice(-3)) {
+            lines.push(`  ${t.id}: "${t.task.slice(0, 60)}" → ${t.error?.slice(0, 80) ?? "unknown"}`);
+        }
+    }
+    if (Object.keys(state.nativeLocks).length > 0) {
+        lines.push("", "Native app locks:");
+        for (const [app, slot] of Object.entries(state.nativeLocks)) {
+            lines.push(`  ${app} → slot ${slot}`);
+        }
+    }
+    lines.push("", `Log: ${ORCH_LOG_FILE}`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+// Helper aliases to keep tool code concise
+import { readOrchestratorState as readOrchState, writeOrchestratorState as writeOrchState, getOrchestratorDaemonPid as getOrchestratorPid, createTask as createOrchestratorTask, detectTaskMode as detectMode } from "./src/orchestrator/state.js";
+import { ORCHESTRATOR_LOG_FILE as ORCH_LOG_FILE } from "./src/orchestrator/types.js";
+// ═══════════════════════════════════════════════
+// OBSERVER — background app-level visual monitor
+// ═══════════════════════════════════════════════
+const OBSERVER_DAEMON_SCRIPT = path.resolve(__dirname, "scripts", "observer-daemon.ts");
+server.tool("observer_start", "Start the observer daemon to continuously watch an app window. Captures frames via CGWindowListCreateImage, runs OCR only when pixels change, detects popups. Zero overhead on engine — reads a JSON file.", {
+    bundleId: z.string().describe("Bundle ID of the app to watch (e.g. com.blackmagic-design.DaVinciResolve)"),
+    windowId: z.number().describe("Window ID to capture (get from the 'windows' tool)"),
+    intervalMs: z.number().optional().describe("Capture interval in ms (default: 2000). Lower = more responsive but more CPU"),
+}, async ({ bundleId, windowId, intervalMs }) => {
+    const existingPid = getObserverDaemonPid();
+    if (existingPid !== null) {
+        return { content: [{ type: "text", text: `Observer daemon already running (pid=${existingPid}). Use observer_stop first.` }] };
+    }
+    const compiledPath = fs.existsSync(path.resolve(__dirname, "scripts", "observer-daemon.js"))
+        ? path.resolve(__dirname, "scripts", "observer-daemon.js")
+        : path.resolve(__dirname, "dist", "scripts", "observer-daemon.js");
+    const daemonArgs = [];
+    let child;
+    let usedCompiled = false;
+    if (fs.existsSync(compiledPath)) {
+        daemonArgs.push(compiledPath, "--bundleId", bundleId, "--windowId", String(windowId));
+        if (intervalMs)
+            daemonArgs.push("--interval", String(intervalMs));
+        child = spawn("node", daemonArgs, { detached: true, stdio: "ignore", cwd: __dirname });
+        usedCompiled = true;
+    }
+    else {
+        daemonArgs.push("tsx", OBSERVER_DAEMON_SCRIPT, "--bundleId", bundleId, "--windowId", String(windowId));
+        if (intervalMs)
+            daemonArgs.push("--interval", String(intervalMs));
+        child = spawn("npx", daemonArgs, { detached: true, stdio: "ignore", cwd: __dirname });
+    }
+    child.unref();
+    await new Promise((r) => setTimeout(r, 2000));
+    const verifyPid = getObserverDaemonPid();
+    if (!verifyPid) {
+        return { content: [{ type: "text", text: `Observer daemon failed to start (mode=${usedCompiled ? "compiled" : "tsx"}).\nCheck log: ${OBSERVER_LOG_FILE}` }] };
+    }
+    // Enable popup checks in the playbook engine (lazy-init if needed)
+    if (!activePlaybookEngine) {
+        getJobRunner(); // initializes activePlaybookEngine as a side effect
+    }
+    if (activePlaybookEngine)
+        activePlaybookEngine.setPopupCheck(true);
+    return { content: [{ type: "text", text: `Observer daemon started (pid=${verifyPid}).\nWatching: ${bundleId} (window ${windowId})\nInterval: ${intervalMs ?? 2000}ms\nLog: ${OBSERVER_LOG_FILE}\n\nPopup auto-dismiss enabled in playbook engine.\nUse observer_status to check frames/popups.` }] };
+});
+server.tool("observer_stop", "Stop the observer daemon.", {}, async () => {
+    const pid = getObserverDaemonPid();
+    if (!pid) {
+        return { content: [{ type: "text", text: "No observer daemon running." }] };
     }
     try {
         process.kill(pid, "SIGTERM");
-        // Wait for it to clean up
         await new Promise((r) => setTimeout(r, 1000));
-        return { content: [{ type: "text", text: `Daemon stopped (pid=${pid}).` }] };
+        if (activePlaybookEngine)
+            activePlaybookEngine.setPopupCheck(false);
+        return { content: [{ type: "text", text: `Observer daemon stopped (pid=${pid}).` }] };
     }
     catch (err) {
-        return { content: [{ type: "text", text: `Failed to stop daemon: ${err.message}` }] };
+        return { content: [{ type: "text", text: `Failed to stop: ${err.message}` }] };
+    }
+});
+server.tool("observer_status", "Get observer daemon status — frames captured, OCR text, popup detection.", {}, async () => {
+    const state = readObserverState();
+    if (!state) {
+        return { content: [{ type: "text", text: "Observer not running. Use observer_start to begin watching an app." }] };
+    }
+    const lines = [
+        `Running: ${state.running}${state.pid ? ` (pid=${state.pid})` : ""}`,
+        `Watching: ${state.bundleId} (window ${state.windowId})`,
+        `Interval: ${state.intervalMs}ms`,
+        `Frames: ${state.framesCaptured} captured, ${state.framesChanged} changed, ${state.ocrRuns} OCR runs`,
+    ];
+    if (state.lastFrame) {
+        lines.push(`Last frame: ${state.lastFrame.capturedAt} (changed: ${state.lastFrame.changed})`);
+        const ocrPreview = state.lastFrame.ocrText.substring(0, 500);
+        lines.push(`OCR text (first 500 chars):\n${ocrPreview}`);
+    }
+    if (state.popup) {
+        lines.push(`\nPOPUP DETECTED: "${state.popup.pattern}"`);
+        lines.push(`  Action: ${state.popup.dismissAction}`);
+        lines.push(`  Detected: ${state.popup.detectedAt}`);
+    }
+    if (state.lastError) {
+        lines.push(`\nLast error: ${state.lastError}`);
+    }
+    lines.push(`\nLog: ${OBSERVER_LOG_FILE}`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+server.tool("observer_ocr_roi", "Submit a targeted ROI OCR command to the running observer daemon. The daemon captures the window region, runs OCR, and stores the result. Non-blocking — returns a command ID you can poll with a second call.", {
+    x: z.number().describe("X offset of the region (window-relative)"),
+    y: z.number().describe("Y offset of the region (window-relative)"),
+    width: z.number().describe("Width of the region"),
+    height: z.number().describe("Height of the region"),
+    windowId: z.number().optional().describe("Window ID (defaults to daemon's watched window)"),
+    commandId: z.string().optional().describe("If provided, poll an existing command instead of submitting a new one"),
+}, async ({ x, y, width, height, windowId, commandId }) => {
+    // Poll mode — check result of a previously submitted command
+    if (commandId) {
+        const cmd = getObserverCommand(commandId);
+        if (!cmd) {
+            return { content: [{ type: "text", text: `Command ${commandId} not found.` }] };
+        }
+        if (cmd.status === "pending" || cmd.status === "running") {
+            return { content: [{ type: "text", text: `Command ${commandId}: ${cmd.status} — call again to poll.` }] };
+        }
+        if (cmd.status === "error") {
+            return { content: [{ type: "text", text: `Command ${commandId} failed: ${cmd.error}` }] };
+        }
+        // done
+        const r = cmd.result;
+        const lines = [
+            `Command ${commandId}: done at ${r.completedAt}`,
+            `Text: ${r.text.substring(0, 1000)}`,
+            `Regions: ${r.regions.length}`,
+        ];
+        for (const region of r.regions.slice(0, 20)) {
+            lines.push(`  "${region.text}" @ (${region.bounds.x}, ${region.bounds.y}, ${region.bounds.width}×${region.bounds.height})`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // Submit mode — create a new command
+    const pid = getObserverDaemonPid();
+    if (!pid) {
+        return { content: [{ type: "text", text: "Observer daemon not running. Use observer_start first." }] };
+    }
+    const cmd = {
+        type: "ocr_roi",
+        roi: { x, y, width, height },
+    };
+    if (windowId !== undefined)
+        cmd.windowId = windowId;
+    const id = submitObserverCommand(cmd);
+    return { content: [{ type: "text", text: `ROI OCR command submitted: ${id}\nRegion: (${x}, ${y}, ${width}×${height})\nThe daemon will process this on its next cycle. Call observer_ocr_roi with commandId="${id}" to poll the result.` }] };
+});
+// ═══════════════════════════════════════════════
+// PHASE 6: TOOL MASTERY — Ingestion + Community
+// ═══════════════════════════════════════════════
+server.tool("scan_menu_bar", "Scan an app's menu bar via AX tree. Extracts all menu paths, keyboard shortcuts, and enabled/disabled states. Automatically merges discovered shortcuts into the reference file.", {
+    pid: z.number().describe("Process ID of the running app"),
+    bundleId: z.string().describe("macOS bundle ID (e.g. com.adobe.Photoshop)"),
+    appName: z.string().describe("Human-readable app name (e.g. Photoshop)"),
+    mergeToReference: z.boolean().optional().describe("Merge discovered shortcuts into the reference file (default true)"),
+}, async ({ pid, bundleId, appName, mergeToReference }) => {
+    await ensureBridge();
+    const scanner = new MenuScanner(bridge);
+    const result = await scanner.scan(pid, bundleId, appName);
+    // Auto-merge to reference unless explicitly disabled
+    let mergeInfo = "";
+    if (mergeToReference !== false) {
+        const merge = referenceMerger.mergeMenuScan(result);
+        mergeInfo = `\nReference updated: ${merge.filePath} (${merge.added} added, ${merge.updated} updated)`;
+    }
+    const lines = [
+        `Menu scan: ${result.appName} (${result.bundleId})`,
+        `Total menus: ${result.totalMenus}, Total items: ${result.totalItems}`,
+        `Shortcuts found: ${Object.keys(result.shortcuts).length}`,
+        mergeInfo,
+        "",
+        "Shortcuts:",
+    ];
+    for (const [menuPath, keys] of Object.entries(result.shortcuts)) {
+        // Redact username from menu paths + catch "Log Out <name>" pattern inline
+        let safePath = redactUsername(menuPath);
+        safePath = safePath.replace(/Log Out [^\n:]+/g, "Log Out [USER]");
+        lines.push(`  ${safePath}: ${keys}`);
+    }
+    let output = lines.join("\n");
+    output = redactUsername(output);
+    output = output.replace(/Log Out [^\n:]+/g, "Log Out [USER]");
+    return { content: [{ type: "text", text: output }] };
+});
+server.tool("ingest_documentation", "Parse a documentation page (HTML, markdown, or text) and extract shortcuts, workflows, and tips. Merges extracted knowledge into the app's reference file.", {
+    content: z.string().describe("The documentation content (HTML, markdown, or plain text)"),
+    url: z.string().describe("Source URL of the documentation"),
+    format: z.enum(["html", "markdown", "text"]).optional().describe("Content format (default html)"),
+    bundleId: z.string().describe("macOS bundle ID for the app this documentation covers"),
+    appName: z.string().describe("Human-readable app name"),
+    mergeToReference: z.boolean().optional().describe("Merge extracted knowledge into reference file (default true)"),
+}, async ({ content, url, format, bundleId, appName, mergeToReference }) => {
+    const parser = new DocParser();
+    const result = parser.parse(content, url, format ?? "html");
+    let mergeInfo = "";
+    if (mergeToReference !== false) {
+        const shortcutMerge = referenceMerger.mergeDocShortcuts(result.shortcuts, bundleId, appName);
+        const flowMerge = referenceMerger.mergeDocFlows(result, bundleId, appName);
+        mergeInfo = `\nReference updated: ${shortcutMerge.filePath}\n  Shortcuts: ${shortcutMerge.added} added, ${shortcutMerge.updated} updated\n  Flows: ${flowMerge.added} added`;
+    }
+    const lines = [
+        `Documentation parsed: ${result.title}`,
+        `Source: ${result.url}`,
+        `Shortcuts: ${result.shortcuts.length}, Flows: ${result.flows.length}, Tips: ${result.tips.length}`,
+        mergeInfo,
+    ];
+    if (result.shortcuts.length > 0) {
+        lines.push("", "Shortcuts:");
+        for (const s of result.shortcuts.slice(0, 30)) {
+            lines.push(`  ${s.name}: ${s.keys}${s.category ? ` (${s.category})` : ""}`);
+        }
+    }
+    if (result.flows.length > 0) {
+        lines.push("", "Workflows:");
+        for (const f of result.flows.slice(0, 10)) {
+            lines.push(`  ${f.name} (${f.steps.length} steps)`);
+        }
+    }
+    if (result.tips.length > 0) {
+        lines.push("", "Tips:");
+        for (const t of result.tips.slice(0, 10)) {
+            lines.push(`  - ${t}`);
+        }
+    }
+    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.", {
+    segments: z.array(z.object({
+        text: z.string(),
+        startTime: z.number(),
+        duration: z.number(),
+    })).describe("Transcript segments (text + timing from YouTube captions or similar)"),
+    title: z.string().describe("Video title"),
+    platform: z.string().describe("Target platform name (e.g. davinci-resolve, figma)"),
+}, async ({ segments, title, platform }) => {
+    const extractor = new TutorialExtractor();
+    const result = extractor.extract(segments, title, platform);
+    const playbookSteps = extractor.toPlaybookSteps(result);
+    const lines = [
+        `Tutorial extracted: ${result.title}`,
+        `Platform: ${result.platform}`,
+        `Raw segments: ${result.rawSegments}, Action steps: ${result.actionSegments}`,
+        `Playbook-ready steps: ${playbookSteps.length}`,
+        "",
+        "Steps:",
+    ];
+    for (let i = 0; i < result.steps.length; i++) {
+        const step = result.steps[i];
+        lines.push(`  ${i + 1}. [${step.tool ?? "?"}] ${step.description}`);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: lines.join("\n"),
+            }],
+    };
+});
+server.tool("coverage_report", "Generate a coverage report for an app — shows what knowledge we have (shortcuts, selectors, flows, playbooks, errors) and identifies gaps with recommendations.", {
+    bundleId: z.string().describe("macOS bundle ID (e.g. com.blackmagic-design.DaVinciResolveLite)"),
+    appName: z.string().describe("Human-readable app name"),
+    includeLiveMenuScan: z.boolean().optional().describe("Also scan the live menu bar for comparison (requires app to be running, needs pid)"),
+    pid: z.number().optional().describe("Process ID (required if includeLiveMenuScan is true)"),
+}, async ({ bundleId, appName, includeLiveMenuScan, pid }) => {
+    let menuScan;
+    if (includeLiveMenuScan && pid) {
+        await ensureBridge();
+        const scanner = new MenuScanner(bridge);
+        menuScan = await scanner.scan(pid, bundleId, appName);
     }
+    const report = coverageAuditor.audit(bundleId, appName, menuScan);
+    const lines = [
+        `Coverage Report: ${report.app} (${report.bundleId})`,
+        "",
+        "Knowledge inventory:",
+        `  Shortcuts: ${report.shortcutsKnown}`,
+        `  Selectors: ${report.selectorsKnown}`,
+        `  Flows: ${report.flowsKnown}`,
+        `  Playbooks: ${report.playbooksAvailable}`,
+        `  Error patterns: ${report.errorsDocumented}`,
+    ];
+    if (report.selectorStabilityScore > 0) {
+        lines.push(`  Selector stability: ${(report.selectorStabilityScore * 100).toFixed(0)}%`);
+    }
+    if (report.highValueGaps.length > 0) {
+        lines.push("", "High-value gaps:");
+        for (const gap of report.highValueGaps) {
+            lines.push(`  - ${gap}`);
+        }
+    }
+    if (report.shortcutsNotInReference.length > 0) {
+        lines.push("", `Undocumented shortcuts (${report.shortcutsNotInReference.length}):`);
+        for (const s of report.shortcutsNotInReference.slice(0, 20)) {
+            lines.push(`  ${s}`);
+        }
+    }
+    if (report.workflowsWithNoPlaybook.length > 0) {
+        lines.push("", `Missing playbooks for common workflows: ${report.workflowsWithNoPlaybook.join(", ")}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+originalTool("community_publish", "Publish a validated local playbook to the community repository. Requires the playbook to have been executed successfully multiple times. Strips sensitive data (passwords, file paths).", {
+    playbookId: z.string().describe("ID of the local playbook to publish"),
+    successRate: z.number().min(0).max(1).describe("Success rate from testing (0.0-1.0)"),
+    executionCount: z.number().describe("Number of times the playbook has been executed"),
+    minRuns: z.number().optional().describe("Minimum successful runs required (default 3)"),
+}, async ({ playbookId, successRate, executionCount }) => {
+    // Look up the playbook from the store
+    const playbook = _executablePlaybookStore.get(playbookId);
+    if (!playbook) {
+        return { content: [{ type: "text", text: `Playbook "${playbookId}" not found. Use export_playbook to list available playbooks.` }] };
+    }
+    // Server enforces minimum of 3 runs using playbook's own tracked data — client values are ignored
+    const result = communityPublisher.publish(playbook, successRate, executionCount);
+    if (!result) {
+        const actualRuns = playbook.successCount + playbook.failCount;
+        return { content: [{ type: "text", text: `Playbook not published. Requirements: at least 3 tracked executions and >50% success rate. Actual: ${actualRuns} tracked runs, ${actualRuns > 0 ? ((playbook.successCount / actualRuns) * 100).toFixed(0) : 0}% success.` }] };
+    }
+    communityFetcher.invalidateCache();
+    return { content: [{ type: "text", text: `Published to community: ${result.id}\nName: ${result.name}\nSteps: ${result.steps.length}\nSuccess rate: ${(result.metadata.successRate * 100).toFixed(0)}%` }] };
+});
+originalTool("community_fetch", "Search community playbooks for a platform or workflow. Returns ranked results by success rate.", {
+    platform: z.string().optional().describe("Filter by platform name"),
+    bundleId: z.string().optional().describe("Filter by macOS bundle ID"),
+    workflow: z.string().optional().describe("Search by workflow name/description"),
+    limit: z.number().optional().describe("Max results (default 20)"),
+}, async ({ platform, bundleId, workflow, limit }) => {
+    const query = {};
+    if (platform !== undefined)
+        query.platform = platform;
+    if (bundleId !== undefined)
+        query.bundleId = bundleId;
+    if (workflow !== undefined)
+        query.workflow = workflow;
+    if (limit !== undefined)
+        query.limit = limit;
+    const results = await communityFetcher.fetchWithRemote(query);
+    if (results.length === 0) {
+        return { content: [{ type: "text", text: "No community playbooks found matching the query." }] };
+    }
+    const lines = [`Community playbooks (${results.length} results):`, ""];
+    for (const pb of results) {
+        lines.push(`  ${pb.id}`);
+        lines.push(`    Name: ${pb.name}`);
+        lines.push(`    Platform: ${pb.platform} | Steps: ${pb.steps.length}`);
+        lines.push(`    Success: ${(pb.metadata.successRate * 100).toFixed(0)}% (${pb.metadata.executionCount} runs)`);
+        lines.push(`    Score: ${pb.ratings.score} | By: ${pb.metadata.author}`);
+        lines.push("");
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // ═══════════════════════════════════════════════
 // START
 // ═══════════════════════════════════════════════
 async function main() {
+    // Flush playbook learnings on graceful shutdown
+    process.on("SIGINT", () => { void perceptionManager.stop(); contextTracker.flush(); learningEngine.flush(); appMap.flush(); process.exit(0); });
+    process.on("SIGTERM", () => { void perceptionManager.stop(); contextTracker.flush(); learningEngine.flush(); appMap.flush(); process.exit(0); });
+    process.on("beforeExit", () => { void perceptionManager.stop(); contextTracker.flush(); learningEngine.flush(); appMap.flush(); });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }