feat(privacy): add watcher-side privacy filter (drop/redact before send)

[TimeToBuildBob]

Summary

Adds a client-side privacy filter that drops or redacts window events before they are sent to aw-server, so sensitive data never leaves the machine at all.

This mirrors the server-side privacy_filters engine that landed in aw-server-rust#600, allowing users to enforce the same rules at both layers. Previously the watcher only supported dropping titles via exclude_title/exclude_titles (redact to "excluded"). This PR adds explicit drop and redact actions with user-configurable regex patterns and replacement strings.

What changed

• aw_watcher_window/privacy_filter.py (new) — pure Python, no new deps:
  • compile_privacy_rules(raw) — validates and compiles regex patterns; invalid regexes and unknown actions are skipped with an error log rather than crashing
  • apply_privacy_filters(window, rules) — returns None (drop) or a filtered copy (redact); never mutates the input dict
• aw_watcher_window/config.py — exposes privacy_filter_rules from [[aw-watcher-window.privacy_filter]] TOML array of tables
• aw_watcher_window/main.py — privacy filter runs first in transform_window; a None return skips the heartbeat; heartbeat_loop threads the rules through
• tests/test_privacy_filter.py (new) — 23 tests covering compile, drop, redact, input immutability, edge cases
• README.md — documents the new config section with examples

Config example

# Drop private-browsing windows entirely
[[aw-watcher-window.privacy_filter]]
pattern = "(?i)private browsing|incognito"
action  = "drop"

# Redact banking titles
[[aw-watcher-window.privacy_filter]]
pattern     = "(?i)bank|my account"
action      = "redact"
replacement = "REDACTED"   # optional; defaults to "excluded"

# Drop by app name (not title)
[[aw-watcher-window.privacy_filter]]
pattern = "(?i)signal"
field   = "app"
action  = "drop"

Rule fields: pattern (Python regex), field (default "title"), action ("drop" or "redact"), replacement (for redact; default "excluded").

Ordering

Privacy filter runs before Research Edition and exclude_title transforms. A "drop" rule exits immediately — subsequent rules are not evaluated for that event.

macOS note

The default swift strategy bypasses this Python transform (same as Research Edition). Use --strategy jxa or --strategy applescript to enable watcher-side privacy filtering on macOS.

Test plan

• python3 -m pytest tests/test_privacy_filter.py -v — 23 passed
• python3 -m pytest tests/test_main.py -v — 12 passed (no regressions)
• Normal run with no config: zero behaviour change
• drop rule matching title: heartbeat skipped
• redact rule matching title: heartbeat sent with replacement value
• Invalid regex in rule: rule skipped with error log, watcher continues

[greptile-apps]

Greptile Summary

Adds watcher-side privacy filtering before window events are sent to the server.

• Loads privacy-filter rules from TOML configuration.
• Compiles valid drop and redact rules while skipping malformed rules.
• Applies filtering before existing research and title-exclusion transforms.
• Skips heartbeats for dropped events and documents configuration and macOS limitations.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the current code catches both regex syntax errors and TypeError from non-string pattern values, logs the malformed rule, and continues startup.

Important Files Changed

Filename	Overview
aw_watcher_window/privacy_filter.py	Implements rule compilation and immutable drop/redact filtering; the previously reported non-string-pattern crash is fixed by catching TypeError.
aw_watcher_window/main.py	Integrates filtering before existing transforms and suppresses heartbeats for dropped events.
aw_watcher_window/config.py	Exposes configured privacy-filter tables through parsed arguments.
tests/test_privacy_filter.py	Covers rule validation, malformed non-string patterns, filtering order, custom fields, and input immutability.
README.md	Documents privacy-filter configuration, behavior, ordering, and the macOS strategy limitation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Read current window] --> B[Apply privacy-filter rules]
    B -->|Drop| C[Skip heartbeat]
    B -->|Pass or redact| D[Apply research/title transforms]
    D --> E[Create window event]
    E --> F[Send heartbeat to aw-server]

Loading

_{Reviews (2): Last reviewed commit: "fix(privacy): skip non-string regex patt..." | Re-trigger Greptile}

[TimeToBuildBob]

@greptileai review

[ErikBjare]

@TimeToBuildBob The watcher-side privacy filter should also be configurable via webui (non-technical user-facing central config) similar to the server-side privacy filter (but watcher-only config should also be supported, if e.g. server is untrusted).

[TimeToBuildBob]

Good point. The TOML config in this PR covers the watcher-only path you described (useful when the server is untrusted or the user wants filtering before data ever leaves the machine).

For webui configurability, the shape I'd expect is:

• aw-server exposes a config endpoint for watcher-side privacy rules (similar to how server-side privacy_filters are managed)
• aw-webui adds a settings panel for configuring those rules
• The watcher fetches its config from the server when available, falling back to TOML when disconnected or server is untrusted

That touches aw-server and aw-webui (separate repos), so it's naturally a follow-up rather than something that fits cleanly into this PR. Would you prefer I scope it here (which would expand the PR significantly) or open a follow-up issue to track it?

Also resolved the rebase conflict with master (#136, #137) — the branch is up to date now.

[TimeToBuildBob]

Still waiting for direction on scope — whether to include the webui-configurable path in this PR or track it as a follow-up. The watcher-only TOML config path is ready, CI green, and rebased. Happy to expand or split depending on your preference.

[TimeToBuildBob]

CI-green and mergeable (Greptile 5/5) — waiting only on a maintainer click.

This PR is ready to merge, but the bot has pull-only access to this repo and can't self-merge — surfacing it here so it isn't lost. The monitoring loop will stop re-flagging it now that this note is posted.

[TimeToBuildBob]

🤖 AI code review

Safe to merge — 2 findings disposed (fixed in 1d68a6b; rejected)

_{Updated after inline dispositions on finding threads — this is the current state; the verdict below is frozen at review time and is kept as the historical record of that pass.}

Finding disposition

Finding	Severity	State
aw_watcher_window/main.py:102	P1	fixed in 1d68a6b
aw_watcher_window/main.py:224	P1	rejected — The verification said: "the exclude_titles loop at main.py line 235-237 mutates the original current_window, but the fun
aw_watcher_window/main.py:102	P2	rejected

Adds a watcher-side privacy filter that drops or redacts window events before they are sent to aw-server. New privacy_filter.py compiles and applies regex rules; config.py reads [[aw-watcher-window.privacy_filter]] TOML tables; main.py runs the filter first in transform_window and skips heartbeats for dropped events, and refuses to start under the macOS swift strategy when rules are configured. Adds tests for the filter, config parsing, and the swift refusal, plus README documentation and CodeQL action version bumps.

Needs a look — P2 only

Confidence 4/5

1 finding · ⚠️ 1 P2

⚠️ P2 medium — aw_watcher_window/main.py:102

The swift strategy refusal check only runs when sys.platform == 'darwin' and args.strategy == 'swift', but the default strategy on macOS is 'swift' (config default strategy_macos = "swift"). However, the check is placed after compile_privacy_rules, which is fine. The real issue: the refusal only happens in main() when the Python process starts. But the swift strategy is also the default for macOS, and the README says the watcher refuses to start. The check is correct. Wait, let me look for actual bugs. The privacy filter runs in transform_window, which is only called in the Python heartbeat_loop path. The swift strategy path calls build_swift_command and Popen, and the refusal happens before that. That's fine. But what about the case where privacy_filter_rules is configured but the swift strategy is used on a non-macOS platform? The check is guarded by sys.platform == 'darwin

_{How this was verified: Checked main() flow: compile_privacy_rules at line 99, then the swift check at line 102. On non-darwin, the else branch calls heartbeat_loop, which applies the filter. On darwin with swift, it exits. No bug here.}

Files changed (8) — the diff as I read it

• .github/workflows/codeql.yml — Bumps actions/checkout from v3 to v4 and codeql-action from v2 to v3.
• README.md — Documents the new privacy_filter config section with examples and a macOS swift strategy note.
• aw_watcher_window/config.py — Reads privacy_filter from config, wrapping a single TOML table into a list, and attaches privacy_filter_rules to parsed args.
• aw_watcher_window/main.py — Compiles privacy rules, refuses to start under swift strategy when rules exist, threads rules through heartbeat_loop, and skips heartbeat when transform returns None.
• aw_watcher_window/privacy_filter.py — New module with compile_privacy_rules and apply_privacy_filters for drop/redact actions.
• tests/test_config.py — Adds tests for wrapping a single privacy_filter table and preserving an array of rules.
• tests/test_main.py — Adds tests for exclude_titles interaction with privacy rules and swift refusal to start.
• tests/test_privacy_filter.py — New test file covering compile validation and apply drop/redact behavior.

Previous review passes

commit	score	findings	engine	when
1bdacd80303b	2/5	2	llm	2026-09-16 08:52 UTC

_{Reviewed 1d68a6b12d6d · openrouter/deepseek/deepseek-v4-flash-0731 · llm engine · 30s · about this reviewer}

_{Maintainer commands}

_{@TimeToBuildBob review (own line) — fresh review · @TimeToBuildBob fix — a worker acts on the findings. Once per comment; 👀 = received.}