fix(observer): ocr_enabled flag — bypass screencapture popup storm

[AVADSA25]

Summary

User report (2026-05-02 morning): after merging Step 5 and starting codec-observer, the macOS Screen Recording permission popup fired "over a hundred times" — the user clicked Allow but it kept coming back.

Root cause

Two-part bug in _get_screenshot_ocr:

1. macOS Allow is one-shot. Persistent grant requires the System Settings toggle, not the popup's Allow button. Clicking Allow on the popup only authorizes that single call.

2. ThreadPoolExecutor.__exit__ blocks on shutdown. When the popup appears, screencapture's subprocess hangs waiting for the user. My code:

   with ThreadPoolExecutor(max_workers=1) as ex:
       future = ex.submit(_screencapture_and_ocr_blocking)
       return future.result(timeout=timeout_s)

   __exit__ calls shutdown(wait=True) — blocks until the thread finishes. The thread can't finish until the popup is dismissed. The "100ms timeout" actually waited ~5s (subprocess.run's own 2s+3s chain). And the Q5.1 retry triggered a SECOND popup. Per poll: ~2 popups + 5s blocking.

Fix

Add ocr_enabled config flag (default True — preserves Step 5 behavior on permission-granted installs). When false, poll() skips _get_screenshot_ocr entirely. Buffer still captures active_window + clipboard + recent_files; only OCR is bypassed.

// ~/.codec/config.json
"observer": {
    "ocr_enabled": false   // disable per-machine until permissions granted
}

Test plan

• 3 new tests added in tests/test_observer.py:
  • test_ocr_enabled_false_skips_screenshot_call — sentinel-based, raises if _get_screenshot_ocr is called despite the flag
  • test_ocr_enabled_default_is_true — preserves existing behavior
  • test_ocr_enabled_true_calls_screenshot — sanity check for the default path
• pytest tests/test_observer.py → 33/33 passing in 0.21s. Zero side effects (Apple Reminders=0, /tmp/codec_*.txt=0).

Deployment

This PR ships the code change. The user's runtime config has ALREADY been edited to ocr_enabled: false (atomic write, backup at ~/.codec/config.json.bak-1777736987). After merge:

pm2 restart codec-observer

Observer resumes polling without OCR. No popups possible.

Permanent fix (out of scope for this hotfix)

Two follow-ups for a future PR:

1. Permissions docs in AGENTS.md: how to grant Screen Recording + Accessibility to node AND python3.13 via System Settings. Persistent grant survives restarts.
2. Subprocess-leak fix: replace ThreadPoolExecutor + future.result(timeout=...) with subprocess.Popen + explicit proc.kill() on timeout. The current shutdown-wait pattern is the underlying root cause; the ocr_enabled flag is just the immediate off-switch.

🤖 Generated with Claude Code