[luma-founder]

Summary

• First in-core plugin. When a managed user is locked, every device they own with a MAC gets its AdGuard client upstream set to 0.0.0.0 (configurable). On unlock, upstreams clear.
• Auto-registers AdGuard clients on first lock — curfew is the source of truth for managed devices, so no separate push step is required to make locking work end-to-end. (Bulk hygiene push for unmanaged adult devices waits for the plugin actions surface from ADR-018.)
• Idempotent on both legs (safety-net resync re-runs reconcile periodically). HTTP errors → ReconcileResult.error → audited as plugin.reconcile_failed per PLUGINS.md.
• Per ADR-013's secret convention, AdGuard admin password is read from an env var named in config (password_env), never stored in state.sqlite.

Files

• plugins/adguard/manifest.toml, plugins/adguard/plugin.py — plugin (Pydantic Config + httpx.AsyncClient with Basic auth).
• core/tests/test_adguard_plugin.py — 18 unit tests using httpx.MockTransport (no respx dep needed).

Config

{
  "url": "http://adguard.lan",
  "username": "admin",
  "password_env": "ADGUARD_PASSWORD",
  "sinkhole_upstream": "0.0.0.0"
}

Test plan

• just check clean (lint, mypy, all Python tests, web, build)
• 18 unit tests cover: auto-register on lock, update on wrong upstream, idempotent skip when already sinkholed, MAC matching by any of a device's MACs, case-insensitive MAC lookup, multi-MAC consolidation into one client, unblock clears upstream / no-op when missing or already cleared, leaves non-sinkhole operator-set upstreams alone, empty-MAC and unmanaged devices skipped, no-devices short-circuit (no GET issued), AdGuard 5xx → ReconcileResult.error, custom sinkhole upstream, missing-env-var fails at __init__
• Discovery sanity-checked locally (discover_plugins("plugins") returns adguard: AdGuard Home v1.0.0)
• Live smoke against a real AdGuard Home (only useful if you have one running)