feat(observer): continuous observation loop (Phase 2 Step 5)

[AVADSA25]

Summary

Phase 2 Step 5 — turns CODEC from "AI assistant that responds to commands" into "AI colleague that observes context." A background PM2 service polls four cheap signals (active window, screenshot OCR, clipboard delta, recent files) into a 10-min RAM-only ring buffer; chat + voice handlers conditionally prepend a ≤200-token summary to the LLM's system prompt, gated per the §X "Observation injection contract" so we don't leak screen content to cloud LLMs on every turn.

Implements docs/PHASE2-STEP5-DESIGN.md as designed. Locked Q1-Q6 user resolutions (60s/5min cadence, 10-min buffer, declarative skill triggers, CGEventSource idle, gated injection, no per-app blocklist) honored verbatim. Q5.1-Q5.7 design-phase open questions all resolved with my recommendations (already approved before implementation began).

Commits (a-e)

sha	what
eac65c9	docs/PHASE2-BLUEPRINT.md — Phase 2 plan with Q5 override folded in as §X
cf48384	docs/PHASE2-STEP5-DESIGN.md — Step 5 design doc (§0-§10 + §9 open questions)
d799e61	codec_audit.py — 4 new event constants + PHASE2_STEP5_EVENTS frozenset + 3 extra-field docs
02b87cb	codec_observer.py NEW — RingBuffer + poll + injection helper + run_daemon + Q5.7 forward-compat API
09d8bb3	tests/test_observer.py NEW — 30 tests, 100% passing in 0.18s
62d6a4e	codec_dashboard.py chat handler + codec_voice.py voice handler integration + PWA /api/observer/buffer?debug=1 (Q5.6)
38b398e	ecosystem.config.js PM2 entry + AGENTS.md §3+§6+§10 updates

§X Observation injection contract (Q5 override)

Cheap text-pattern gating, no relevance model:

transport == "local"   → INJECT (always)         reason="always_local"
transport == "mcp"     → SKIP (client owns it)   reason="skipped_no_match"
transport ∈ {"chat",   ┌─ possessive_match*  → INJECT  reason="possessive_match"
            "voice",   ├─ continuation_match → INJECT  reason="continuation_match"
            "http"}    ├─ skill_flag         → INJECT  reason="skill_flag"
                       └─ otherwise          → SKIP    reason="skipped_no_match"

* Possessive uses (my|this|that|these|those|the) <noun> filtered against a 25-word stop-noun list (question, time, thing, etc.) — ~/.codec/config.json:observer.stop_nouns overrides.

Test plan

• pytest tests/test_observer.py → 30 passed in 0.18s
• All polling primitives mocked (osascript / pbpaste / Quartz / screencapture) — tests pass on any platform, NO Apple state, NO Terminal popups
• METADATA-only audit-emit verified by serializing extra dict and asserting raw content strings absent
• Per Step 4 contract: did NOT run full pytest suite (avoids destructive-skill cascade)
• Post-test state files clean: pending_questions=0, Apple Reminders=0, /tmp/codec_*.txt=0, ~/.codec/observation_summaries=0

Privacy contract — 4 layers

1. RAM only. collections.deque(maxlen=N). Process restart wipes. By design.
2. METADATA-only audit emits. observation_tick carries lengths, counts, content_type tags but NEVER raw window titles, OCR text, clipboard content, or file paths. Audit log is for operators, not for re-deriving screen state.
3. Cloud-transport injection gating per §X above.
4. No new system permissions. Reads via existing skills (active_window, screenshot_text) and existing primitives (pbpaste, getmtime, Quartz). No new install-time prompts.

Q5.7 forward-compat API for Steps 6 + 7

Step 5 ships the API surface Steps 6 and 7 will need (per Q5.7 recommendation — locks the contract now, prevents Step 5→6 churn later):

• get_global_buffer() -> RingBuffer — Step 6 (Triggers) reads .snapshot() for trigger evaluation
• persist_for_shift_report() -> Path | None — Step 7 (Shift Report) calls at assembly time; writes summary to ~/.codec/observation_summaries/<ts>.md (the ONLY persistent observer output)

Cost: ~+30 LOC in codec_observer.py. Worth it.

PWA debug endpoint (Q5.6)

GET /api/observer/buffer?debug=1 (auth-gated by existing dashboard middleware):

• Returns metadata-only summary, NOT raw entries (raw contains titles + OCR + clipboard content — too sensitive even for authed callers)
• Every call emits observer_buffer_inspected audit event with client_ip + buffer_entries_returned
• NOT linked from main UI; only for explicit debugging

Kill switch

OBSERVER_ENABLED=false env var → polling AND injection both no-op. No separate injection kill switch — buffer is always populated when enabled, only injection is gated by §X.

Out of scope (explicit, per intake contract)

• No Apple Reminders / Notes / Calendar entries created anywhere in this PR.
• No osascript for user-facing UI — observer's osascript usage is bounded to System Events (active window read) and Vision (OCR), both backend probes.
• _HTTP_BLOCKED not touched.
• Step 6 + Step 7 are not in this PR — Phase 2 ships per-step. Step 6 (Triggers) and Step 7 (Shift Report) will follow as separate PRs after this lands and burns in.

After merge

1. cp plugin pattern from Phase 1 Step 4 doesn't apply here — this is a PM2 service, not a hook plugin. Just pm2 start ecosystem.config.js --only codec-observer after merge + pull.
2. pm2 restart codec-dashboard codec-voice so the chat/voice integration loads codec_observer.
3. Watch ~/.codec/audit.log for first observation_tick (per-poll) and observation_summary_injected (gated inject) — both should appear within 60s of activity.
4. Per intake: NO Apple Reminders for any post-merge watch. If a watch is needed, launchd plist or skip entirely — your call.

🤖 Generated with Claude Code