screenhand 0.5.0 → 0.5.2

package/dist/src/ingestion/reference-merger.js

@@ -112,6 +112,39 @@ export class ReferenceMerger {
         const filePath = this.save(ref);
         return { filePath, added: newFeatures.length };
     }
+    /**
+     * Merge selectors from platform_explore into the main reference file.
+     * Prevents data fragmentation between *-explore.json and the main reference.
+     */
+    mergeExploreSelectors(selectors, errors, bundleId, appName) {
+        const ref = this.loadOrCreate(bundleId, appName);
+        if (!ref.selectors)
+            ref.selectors = {};
+        let added = 0;
+        for (const [group, entries] of Object.entries(selectors)) {
+            if (!ref.selectors[group]) {
+                ref.selectors[group] = {};
+            }
+            for (const [name, selector] of Object.entries(entries)) {
+                if (!ref.selectors[group][name]) {
+                    ref.selectors[group][name] = selector;
+                    added++;
+                }
+            }
+        }
+        // Also merge errors
+        if (!ref.errors)
+            ref.errors = [];
+        const existingErrors = new Set(ref.errors.map((e) => e.error.toLowerCase()));
+        for (const err of errors) {
+            if (!existingErrors.has(err.error.toLowerCase())) {
+                ref.errors.push(err);
+                existingErrors.add(err.error.toLowerCase());
+            }
+        }
+        const filePath = this.save(ref);
+        return { filePath, added };
+    }
     /**
      * Merge errors/solutions into reference.
      */

package/dist/src/memory/recall.js

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
 import { MemoryStore } from "./store.js";
+/** Screenshot/OCR tools that should be auto-pruned from strategy hints */
+const SCREENSHOT_TOOL_NAMES = new Set(["screenshot", "screenshot_file", "ocr"]);
 export class RecallEngine {
     store;
     constructor(store) {
@@ -158,15 +160,77 @@ export class RecallEngine {
             const strategyToolPrefix = s.steps.slice(0, recentTools.length).map((st) => st.tool);
             const matches = recentTools.every((t, i) => t === strategyToolPrefix[i]);
             if (matches) {
+                // Auto-prune: skip screenshot/ocr steps — they add latency on browser apps
+                // and the world model already provides UI state visibility
+                let nextIdx = recentTools.length;
+                while (nextIdx < s.steps.length && SCREENSHOT_TOOL_NAMES.has(s.steps[nextIdx].tool)) {
+                    nextIdx++;
+                }
+                if (nextIdx >= s.steps.length)
+                    continue; // entire remainder was screenshots — skip strategy
                 return {
                     strategy: s,
-                    nextStep: s.steps[recentTools.length],
+                    nextStep: s.steps[nextIdx],
                     fingerprint: s.fingerprint ?? MemoryStore.makeFingerprint(s.steps.map((st) => st.tool)),
                 };
             }
         }
         return null;
     }
+    /**
+     * Check if the current tool sequence matches a PROVEN strategy that can be
+     * auto-executed without LLM intervention.
+     *
+     * Requirements for auto-execution (conservative):
+     * - 10+ successes, 0 failures
+     * - Remaining steps are all concrete tools (no LLM/screenshot steps)
+     * - At least 2 tools in the prefix match (no single-tool triggers)
+     *
+     * Returns ALL remaining steps (not just next) so the caller can batch-execute.
+     */
+    getAutoExecutableStrategy(recentTools, currentBundleId) {
+        if (recentTools.length < 2)
+            return null;
+        const strategies = this.store.readStrategies();
+        const MIN_SUCCESS = 10;
+        for (const s of strategies) {
+            if (s.steps.length <= recentTools.length)
+                continue;
+            // Must be proven: 10+ successes, 0 failures
+            const failCount = s.failCount ?? 0;
+            if (s.successCount < MIN_SUCCESS || failCount > 0)
+                continue;
+            // App context check
+            if (currentBundleId) {
+                const taskLower = s.task.toLowerCase();
+                const bundleLower = currentBundleId.toLowerCase();
+                const appName = bundleLower.split(".").pop() ?? "";
+                const mentionsCurrentApp = taskLower.includes(appName) || taskLower.includes(bundleLower);
+                const mentionsOtherApp = !mentionsCurrentApp && /com\.\w+\.\w+/.test(s.task);
+                if (mentionsOtherApp)
+                    continue;
+            }
+            // Check prefix match
+            const strategyToolPrefix = s.steps.slice(0, recentTools.length).map((st) => st.tool);
+            const matches = recentTools.every((t, i) => t === strategyToolPrefix[i]);
+            if (!matches)
+                continue;
+            // Collect remaining steps, skipping screenshot/ocr
+            const remaining = s.steps.slice(recentTools.length).filter((st) => !SCREENSHOT_TOOL_NAMES.has(st.tool));
+            if (remaining.length === 0)
+                continue;
+            // All remaining steps must be concrete tools (no "llm_interpret" or similar)
+            const LLM_TOOLS = new Set(["llm_interpret", "llm_decide", "ask_user"]);
+            if (remaining.some((st) => LLM_TOOLS.has(st.tool)))
+                continue;
+            return {
+                strategy: s,
+                remainingSteps: remaining,
+                fingerprint: s.fingerprint ?? MemoryStore.makeFingerprint(s.steps.map((st) => st.tool)),
+            };
+        }
+        return null;
+    }
     /** Find error patterns for a specific tool or all tools */
     recallErrors(tool, params) {
         const errors = this.store.readErrors();

package/dist/src/memory/research.js

@@ -16,7 +16,7 @@
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
 export function backgroundResearch(store, tool, params, errorMessage) {
     // Fire-and-forget — never blocks, never throws
-    doResearch(store, tool, params, errorMessage).catch(() => { });
+    doResearch(store, tool, params, errorMessage).catch((e) => { process.stderr.write(`[research] background research failed: ${e instanceof Error ? e.message : String(e)}\n`); });
 }
 async function doResearch(store, tool, params, errorMessage) {
     const query = `macOS automation: "${tool}" failed with "${errorMessage.slice(0, 200)}"`;

package/dist/src/memory/service.js

@@ -117,11 +117,21 @@ export class MemoryService {
             try {
                 const raw = fs.readFileSync(snapPath, "utf-8");
                 const loaded = JSON.parse(raw);
-                // Restore mission and policy from previous run
-                if (loaded.mission)
+                // Validate shape before merging — reject obviously corrupted data
+                if (loaded.mission && typeof loaded.mission === "string") {
                     this.snapshot.mission = loaded.mission;
-                if (loaded.policy)
-                    this.snapshot.policy = { ...DEFAULT_POLICY, ...loaded.policy };
+                }
+                if (loaded.policy && typeof loaded.policy === "object" && !Array.isArray(loaded.policy)) {
+                    // Validate numeric fields before merging
+                    const p = loaded.policy;
+                    if (typeof p.maxConsecutiveErrors !== "number" || !Number.isFinite(p.maxConsecutiveErrors)) {
+                        delete p.maxConsecutiveErrors;
+                    }
+                    if (typeof p.maxErrorsBeforeBlock !== "number" || !Number.isFinite(p.maxErrorsBeforeBlock)) {
+                        delete p.maxErrorsBeforeBlock;
+                    }
+                    this.snapshot.policy = { ...DEFAULT_POLICY, ...p };
+                }
             }
             catch {
                 // Corrupted snapshot — start fresh
@@ -299,7 +309,14 @@ export class MemoryService {
     writeLearningsAsync() {
         this.ensureMemDir();
         const data = this.learningsCache.map((l) => JSON.stringify(l)).join("\n") + (this.learningsCache.length ? "\n" : "");
-        fs.writeFile(this.filePath("learnings.jsonl"), data, () => { });
+        // Use atomic write to prevent race conditions: two rapid calls would clobber
+        // each other with fs.writeFile's async no-op callback.
+        try {
+            writeFileAtomicSync(this.filePath("learnings.jsonl"), data);
+        }
+        catch {
+            // Non-critical — in-memory cache is still correct
+        }
     }
     // ── Recall (delegates to RecallEngine) ───────────
     /** Search error patterns, optionally filtered by tool. */
@@ -318,6 +335,10 @@ export class MemoryService {
     quickStrategyHint(recentTools, currentBundleId) {
         return this.recall.quickStrategyHint(recentTools, currentBundleId);
     }
+    /** Check if the current tool sequence matches a proven strategy for auto-execution. */
+    getAutoExecutableStrategy(recentTools, currentBundleId) {
+        return this.recall.getAutoExecutableStrategy(recentTools, currentBundleId);
+    }
     /** Record strategy outcome for feedback loop. */
     recordStrategyOutcome(fingerprint, success) {
         this.store.recordStrategyOutcome(fingerprint, success);

package/dist/src/memory/store.js

@@ -103,32 +103,41 @@ export class MemoryStore {
     }
     // ── file locking ──────────────────────────────
     acquireLock() {
-        try {
-            // Try to create lock atomically first (avoids TOCTOU race between exists-check and write)
+        // Retry loop closes the TOCTOU window: if another process grabs the lock
+        // between our unlink and write, the wx flag fails and we retry.
+        const MAX_RETRIES = 3;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
             try {
+                // Atomic create — fails if file already exists
                 fs.writeFileSync(this.lockPath, String(process.pid), { flag: "wx" });
+                this.hasLock = true;
+                return;
             }
             catch {
-                // Lock file exists — check if it's stale (PID no longer running)
-                const lockContent = fs.readFileSync(this.lockPath, "utf-8").trim();
-                const lockPid = parseInt(lockContent, 10);
-                if (lockPid && !this.isProcessRunning(lockPid)) {
-                    // Stale lock — remove and retry with wx
-                    fs.unlinkSync(this.lockPath);
-                    fs.writeFileSync(this.lockPath, String(process.pid), { flag: "wx" });
+                // Lock file exists — check if stale
+                try {
+                    const lockContent = fs.readFileSync(this.lockPath, "utf-8").trim();
+                    const lockPid = parseInt(lockContent, 10);
+                    if (lockPid && !this.isProcessRunning(lockPid)) {
+                        // Stale lock — remove and retry (another process may also remove it)
+                        try {
+                            fs.unlinkSync(this.lockPath);
+                        }
+                        catch { /* already removed by competitor */ }
+                        continue; // Retry the wx write
+                    }
+                    // Lock held by active process — don't retry
+                    break;
                 }
-                else {
-                    throw new Error("Lock held by active process");
+                catch {
+                    // Can't read lock file (removed between our check) — retry
+                    continue;
                 }
             }
-            this.hasLock = true;
-        }
-        catch (err) {
-            // Another instance holds the lock — we still work but skip writes
-            // to avoid corruption. Reads are from our own cache (stale but safe).
-            console.error(`[MemoryStore] Lock acquisition failed — writes disabled: ${err instanceof Error ? err.message : err}`);
-            this.hasLock = false;
         }
+        // All retries failed — work in read-only mode
+        process.stderr.write(`[MemoryStore] Lock acquisition failed after ${MAX_RETRIES} attempts — writes disabled\n`);
+        this.hasLock = false;
     }
     releaseLock() {
         if (this.hasLock) {
@@ -285,7 +294,13 @@ export class MemoryStore {
                 this.ensureDir();
                 const data = this.pendingActionWrites.join("");
                 this.pendingActionWrites = [];
-                fs.appendFile(this.filePath("actions.jsonl"), data, () => { });
+                try {
+                    fs.appendFileSync(this.filePath("actions.jsonl"), data);
+                }
+                catch {
+                    // Non-critical — push data back for next flush attempt
+                    this.pendingActionWrites.unshift(data);
+                }
             }, 100);
         }
     }
@@ -325,10 +340,14 @@ export class MemoryStore {
         this.strategiesCache = this.strategiesCache.slice(-MAX_STRATEGIES);
     }
     appendStrategy(strategy) {
-        // Ensure fingerprint exists
-        if (!strategy.fingerprint) {
-            strategy.fingerprint = MemoryStore.makeFingerprint(strategy.steps.map((s) => s.tool));
-        }
+        // Auto-prune screenshot/ocr steps — they add latency on browser apps
+        // and the world model provides UI visibility without them
+        const PRUNE_TOOLS = new Set(["screenshot", "screenshot_file", "ocr"]);
+        strategy.steps = strategy.steps.filter((s) => !PRUNE_TOOLS.has(s.tool));
+        if (strategy.steps.length === 0)
+            return; // strategy was all screenshots — discard
+        // Ensure fingerprint exists (recompute after pruning)
+        strategy.fingerprint = MemoryStore.makeFingerprint(strategy.steps.map((s) => s.tool));
         const idx = this.strategiesCache.findIndex((s) => s.task === strategy.task);
         if (idx >= 0) {
             const old = this.strategiesCache[idx];

package/dist/src/native/bridge-client.js

@@ -212,7 +212,7 @@ export class BridgeClient extends EventEmitter {
                 // Force restart if bridge appears stalled
                 if (this.consecutiveTimeouts >= BridgeClient.MAX_CONSECUTIVE_TIMEOUTS) {
                     this.consecutiveTimeouts = 0;
-                    this.restart().catch(() => { });
+                    this.restart().catch((e) => { process.stderr.write(`[bridge] restart after timeout failed: ${e instanceof Error ? e.message : String(e)}\n`); });
                 }
             }, effectiveTimeout);
             this.pending.set(id, {
@@ -275,14 +275,14 @@ export class BridgeClient extends EventEmitter {
             this.emit("error", msg);
             // Only auto-restart if this is still the active process
             if (this.started && this.process === spawnedProcess) {
-                this.restart().catch(() => { });
+                this.restart().catch((e) => { process.stderr.write(`[bridge] restart after error failed: ${e instanceof Error ? e.message : String(e)}\n`); });
             }
         });
         child.on("exit", (code) => {
             this.emit("exit", code);
             // Only auto-restart if this is still the active process and not mid-restart
             if (this.started && !this.restarting && this.process === spawnedProcess) {
-                this.restart().catch(() => { });
+                this.restart().catch((e) => { process.stderr.write(`[bridge] restart after exit failed: ${e instanceof Error ? e.message : String(e)}\n`); });
             }
         });
         // Parse stdout line by line

package/dist/src/perception/coordinator.js

@@ -50,6 +50,10 @@ export class PerceptionCoordinator extends EventEmitter {
     slowTimer = null;
     activePid = null;
     activeWindowId = null;
+    /** Track consecutive failures per loop for diagnostics */
+    fastErrors = 0;
+    mediumErrors = 0;
+    slowErrors = 0;
     activeAppContext = null;
     cdpClient = null;
     /** CDP connection factory — called to create/reconnect persistent clients */
@@ -151,7 +155,12 @@ export class PerceptionCoordinator extends EventEmitter {
                     if (this.fastInFlight)
                         return;
                     this.fastInFlight = true;
-                    void this.fastCycle().catch(() => { }).finally(() => { this.fastInFlight = false; });
+                    void this.fastCycle().then(() => { this.fastErrors = 0; }).catch((e) => {
+                        this.fastErrors++;
+                        if (this.fastErrors <= 3 || this.fastErrors % 50 === 0) {
+                            process.stderr.write(`[perception] fast cycle error #${this.fastErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                        }
+                    }).finally(() => { this.fastInFlight = false; });
                 }, this.config.fastIntervalMs);
             }
             if (this.mediumTimer) {
@@ -160,7 +169,12 @@ export class PerceptionCoordinator extends EventEmitter {
                     if (this.mediumInFlight)
                         return;
                     this.mediumInFlight = true;
-                    void this.mediumCycle().catch(() => { }).finally(() => { this.mediumInFlight = false; });
+                    void this.mediumCycle().then(() => { this.mediumErrors = 0; }).catch((e) => {
+                        this.mediumErrors++;
+                        if (this.mediumErrors <= 3 || this.mediumErrors % 50 === 0) {
+                            process.stderr.write(`[perception] medium cycle error #${this.mediumErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                        }
+                    }).finally(() => { this.mediumInFlight = false; });
                 }, this.config.mediumIntervalMs);
             }
             if (this.slowTimer) {
@@ -169,7 +183,12 @@ export class PerceptionCoordinator extends EventEmitter {
                     if (this.slowInFlight)
                         return;
                     this.slowInFlight = true;
-                    void this.slowCycle().catch(() => { }).finally(() => { this.slowInFlight = false; });
+                    void this.slowCycle().then(() => { this.slowErrors = 0; }).catch((e) => {
+                        this.slowErrors++;
+                        if (this.slowErrors <= 3 || this.slowErrors % 50 === 0) {
+                            process.stderr.write(`[perception] slow cycle error #${this.slowErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                        }
+                    }).finally(() => { this.slowInFlight = false; });
                 }, this.config.slowIntervalMs);
             }
         }
@@ -185,7 +204,7 @@ export class PerceptionCoordinator extends EventEmitter {
             this.emit("wake");
             // Start stream capture on wake for fast perception (only if running)
             if (this.running && this.visionSource && this.activeWindowId && !this.visionSource.isStreaming) {
-                void this.visionSource.startStream(this.activeWindowId).catch(() => { });
+                void this.visionSource.startStream(this.activeWindowId).catch((e) => { process.stderr.write(`[perception] vision stream start on wake failed: ${e instanceof Error ? e.message : String(e)}\n`); });
             }
         }
     }
@@ -201,7 +220,7 @@ export class PerceptionCoordinator extends EventEmitter {
             this.emit("idle");
             // Stop stream capture to save battery at idle
             if (this.visionSource?.isStreaming) {
-                void this.visionSource.stopStream().catch(() => { });
+                void this.visionSource.stopStream().catch((e) => { process.stderr.write(`[perception] vision stream stop on idle failed: ${e instanceof Error ? e.message : String(e)}\n`); });
             }
         }
         return shouldIdle;
@@ -234,7 +253,7 @@ export class PerceptionCoordinator extends EventEmitter {
         }
         // Start continuous stream capture for fast perception (non-blocking, best-effort)
         if (this.config.enableVision && this.visionSource && this.activeWindowId) {
-            void this.visionSource.startStream(this.activeWindowId).catch(() => { });
+            void this.visionSource.startStream(this.activeWindowId).catch((e) => { process.stderr.write(`[perception] vision stream start failed: ${e instanceof Error ? e.message : String(e)}\n`); });
         }
         // Start AX observation
         if (this.config.enableAX && this.axSource && this.activePid) {
@@ -256,24 +275,42 @@ export class PerceptionCoordinator extends EventEmitter {
         }
         // Start interval loops — in-flight guards prevent pileup when async cycle
         // takes longer than the interval (e.g. bridge latency spike).
+        this.fastErrors = 0;
+        this.mediumErrors = 0;
+        this.slowErrors = 0;
         this.fastTimer = setInterval(() => {
             if (this.fastInFlight)
                 return;
             this.fastInFlight = true;
-            void this.fastCycle().catch(() => { }).finally(() => { this.fastInFlight = false; });
+            void this.fastCycle().then(() => { this.fastErrors = 0; }).catch((e) => {
+                this.fastErrors++;
+                if (this.fastErrors <= 3 || this.fastErrors % 50 === 0) {
+                    process.stderr.write(`[perception] fast cycle error #${this.fastErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+            }).finally(() => { this.fastInFlight = false; });
         }, this.config.fastIntervalMs);
         this.mediumTimer = setInterval(() => {
             if (this.mediumInFlight)
                 return;
             this.mediumInFlight = true;
-            void this.mediumCycle().catch(() => { }).finally(() => { this.mediumInFlight = false; });
+            void this.mediumCycle().then(() => { this.mediumErrors = 0; }).catch((e) => {
+                this.mediumErrors++;
+                if (this.mediumErrors <= 3 || this.mediumErrors % 50 === 0) {
+                    process.stderr.write(`[perception] medium cycle error #${this.mediumErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+            }).finally(() => { this.mediumInFlight = false; });
         }, this.config.mediumIntervalMs);
         if (this.config.enableVision) {
             this.slowTimer = setInterval(() => {
                 if (this.slowInFlight)
                     return;
                 this.slowInFlight = true;
-                void this.slowCycle().catch(() => { }).finally(() => { this.slowInFlight = false; });
+                void this.slowCycle().then(() => { this.slowErrors = 0; }).catch((e) => {
+                    this.slowErrors++;
+                    if (this.slowErrors <= 3 || this.slowErrors % 50 === 0) {
+                        process.stderr.write(`[perception] slow cycle error #${this.slowErrors}: ${e instanceof Error ? e.message : String(e)}\n`);
+                    }
+                }).finally(() => { this.slowInFlight = false; });
             }, this.config.slowIntervalMs);
         }
         this.emit("started", appContext);
@@ -295,7 +332,7 @@ export class PerceptionCoordinator extends EventEmitter {
         }
         // Stop stream capture
         if (this.visionSource?.isStreaming) {
-            void this.visionSource.stopStream().catch(() => { });
+            void this.visionSource.stopStream().catch((e) => { process.stderr.write(`[perception] vision stream stop failed: ${e instanceof Error ? e.message : String(e)}\n`); });
         }
         if (this.fastTimer) {
             clearInterval(this.fastTimer);
@@ -538,7 +575,9 @@ export class PerceptionCoordinator extends EventEmitter {
             try {
                 await this.browserEnricher();
             }
-            catch { /* best-effort */ }
+            catch (e) {
+                process.stderr.write(`[perception] browser enricher failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
         }
         this.stats.mediumCycles++;
         // Wire #9: L3→L7 — auto-update AppMap from perception (every 5th cycle, skip cycle 1)
@@ -937,7 +976,9 @@ export class PerceptionCoordinator extends EventEmitter {
                     ? currentTitle.slice(0, 80).trim() : currentTitle;
                 this.appMap.recordPageTransition(bundleId, fromTitle, toTitle, "perception_detected");
             }
-            catch { /* best-effort — limits, PII filter, etc. */ }
+            catch (e) {
+                process.stderr.write(`[perception] recordPageTransition failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
         }
         this.lastPerceptionTitle = currentTitle;
         // 2. Dialog state change detection
@@ -949,7 +990,9 @@ export class PerceptionCoordinator extends EventEmitter {
                 try {
                     this.appMap.recordStateChange(bundleId, "dialog_state", from, to, "perception_detected");
                 }
-                catch { /* best-effort */ }
+                catch (e) {
+                    process.stderr.write(`[perception] recordStateChange dialog failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
             }
             this.lastPerceptionDialogCount = currentDialogCount;
         }
@@ -987,7 +1030,9 @@ export class PerceptionCoordinator extends EventEmitter {
                 this.appMap.recordElementOutcome(bundleId, "auto", label, true, pageContext);
                 added++;
             }
-            catch { /* best-effort — zone limits, PII filter, etc. */ }
+            catch (e) {
+                process.stderr.write(`[perception] recordElementOutcome failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
         }
     }
     /**
@@ -1028,7 +1073,9 @@ export class PerceptionCoordinator extends EventEmitter {
                 this.appMap.recordElementVisibility(bundleId, text, pageContext, true);
                 recorded++;
             }
-            catch { /* best-effort */ }
+            catch (e) {
+                process.stderr.write(`[perception] recordElementVisibility failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
         }
     }
     // ── Wire #10: L7→L3 — zone ROI → targeted OCR ──

package/dist/src/perception/manager.js

@@ -150,7 +150,9 @@ export class PerceptionManager extends EventEmitter {
                 windowId = (frontmost ?? matching[0])?.windowId;
             }
         }
-        catch { /* best-effort */ }
+        catch (e) {
+            process.stderr.write(`[perception-mgr] window ID lookup failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
         const ctx = {
             bundleId: focusedApp.bundleId,
             appName: focusedApp.bundleId,
@@ -189,9 +191,44 @@ export class PerceptionManager extends EventEmitter {
     notifyToolCall() {
         this.coordinator?.notifyToolCall();
     }
+    // ── Focus/Crash Tracking ──
+    expectedBundleId = null;
+    lastUIChangeTs = Date.now();
+    stallCheckInterval = null;
+    /** Set the expected focused app — enables focus_lost and app_crash detection. */
+    setExpectedApp(bundleId) {
+        this.expectedBundleId = bundleId;
+        this.lastUIChangeTs = Date.now();
+    }
+    /** Start stall detection (fires stall_detected if no UI changes for stallMs). */
+    startStallDetection(stallMs = 30_000) {
+        this.stopStallDetection();
+        this.lastUIChangeTs = Date.now();
+        this.stallCheckInterval = setInterval(() => {
+            if (!this.expectedBundleId)
+                return;
+            const elapsed = Date.now() - this.lastUIChangeTs;
+            if (elapsed >= stallMs) {
+                this.emit("stall_detected", {
+                    bundleId: this.expectedBundleId,
+                    stallMs: elapsed,
+                });
+                // Reset so we don't fire every interval tick
+                this.lastUIChangeTs = Date.now();
+            }
+        }, 5_000);
+    }
+    stopStallDetection() {
+        if (this.stallCheckInterval) {
+            clearInterval(this.stallCheckInterval);
+            this.stallCheckInterval = null;
+        }
+    }
     handleReactiveEvent(event) {
         if (event.data?.type === "ax_events" && Array.isArray(event.data.events)) {
             for (const uiEvent of event.data.events) {
+                // Track any UI change for stall detection
+                this.lastUIChangeTs = Date.now();
                 if (uiEvent.type === "dialog_appeared") {
                     this.emit("dialog_detected", {
                         title: uiEvent.windowTitle ?? "",
@@ -205,6 +242,33 @@ export class PerceptionManager extends EventEmitter {
                         bundleId: uiEvent.bundleId,
                         pid: uiEvent.pid,
                     });
+                    // Focus loss detection: if we expected a specific app and a different one took focus
+                    if (this.expectedBundleId && uiEvent.bundleId !== this.expectedBundleId) {
+                        this.emit("focus_lost", {
+                            expectedBundleId: this.expectedBundleId,
+                            actualBundleId: uiEvent.bundleId,
+                            pid: uiEvent.pid,
+                        });
+                    }
+                }
+                // App crash detection: when expected app deactivates, check if PID is still alive.
+                // Only emit app_crash if the process is actually gone (not just lost focus).
+                if (uiEvent.type === "app_deactivated" &&
+                    uiEvent.bundleId &&
+                    uiEvent.bundleId === this.expectedBundleId &&
+                    uiEvent.pid) {
+                    try {
+                        // process.kill(pid, 0) throws if PID doesn't exist
+                        process.kill(uiEvent.pid, 0);
+                        // PID alive — just a focus switch, handled by focus_lost above
+                    }
+                    catch {
+                        // PID dead — app crashed
+                        this.emit("app_crash", {
+                            bundleId: uiEvent.bundleId,
+                            pid: uiEvent.pid,
+                        });
+                    }
                 }
             }
         }

package/dist/src/planner/executor.js

@@ -429,7 +429,9 @@ export class PlanExecutor {
                         }
                     }
                 }
-                catch { /* best-effort contract check */ }
+                catch (e) {
+                    process.stderr.write(`[planner] contract precondition check failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
             }
         }
         // 4. Focus validation: for type_text, verify a text field is focused
@@ -785,7 +787,9 @@ export class PlanExecutor {
                         }
                     }
                 }
-                catch { /* best-effort */ }
+                catch (e) {
+                    process.stderr.write(`[planner] contract outcome inference failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
             }
         }
         // Navigation or state-changing click → next step's target should be visible