diff --git a/docs/superpowers/plans/2026-08-21-byod-wifi-access-model.md b/docs/superpowers/plans/2026-08-21-byod-wifi-access-model.md
new file mode 100644
index 0000000..5f65714
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-byod-wifi-access-model.md
@@ -0,0 +1,1415 @@
+# BYOD Wi-Fi Access Model Implementation Plan (Plan 1 of 2)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Wi-Fi access correct and safe — count live authorizations instead of present devices, prove the device belongs to the person signing in, and gate access on an explicit per-role allow-list.
+
+**Architecture:** `PortalController::captiveCallback` stops trusting the `?mac=` parameter and stops using network presence as a quota signal. A new `DeviceResolver` service identifies the device from the request's source IP via UniFi's client table and refuses if it cannot prove association to the AP that issued the redirect. A `live` scope on `PortalSession` becomes the single definition of a consumed slot, and a scheduled reconciler repairs drift between our rows and UniFi's authorizations.
+
+**Tech Stack:** Laravel 11 snap-in (`Dashboard\Unifi`), MariaDB, Inertia/Vue for the pages it renders, PHPUnit. Tests live in `dashboard-shell/tests` even for snap-in code.
+
+**Out of scope (Plan 2):** the settings screen (role dropdown, day presets, removing the `default` option from the UI), the denial page's randomized-MAC coaching copy, the Wi-Fi Devices admin page, browser E2E.
+
+---
+
+## Before you start
+
+**Run tests like this.** Claim a database slot once, reuse it, release at the end:
+
+```bash
+cd /project/dashboard-shell
+DB=$(bin/agentdb claim --agent wifi-plan1)   # prints e.g. dashboard_testing_2
+bin/agentdb test "$DB" tests/Feature/Unifi/
+# ...at the very end:
+bin/agentdb release "$DB"
+```
+
+Never run `php artisan test` directly and never pass `-e DB_DATABASE=` — both silently use the shared database.
+
+**Two repos, one feature.** Snap-in code is in `/project/central-unifi`; every test file is in `/project/dashboard-shell/tests`. Commit each repo separately with `git -C <repo> commit -- <paths>`; never `git add -A` (other agents share this tree).
+
+**Bump `central-unifi/composer.json` patch version** on the last commit only, not every task.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `central-unifi/src/Models/PortalSession.php` (modify) | Owns the definition of a consumed slot (`scopeLive`) |
+| `central-unifi/src/Services/DeviceResolver.php` (create) | Turns a request + AP mac into a trusted client MAC, or a refusal reason. No knowledge of quotas |
+| `central-unifi/src/Support/MacAddress.php` (create) | Pure MAC helpers — normalise, detect randomized. No dependencies |
+| `central-unifi/src/Services/UnifiApiClient.php` (modify) | Gains `findClientByIp()` and `getAuthorizedGuestMacs()` |
+| `central-unifi/src/Http/Controllers/PortalController.php` (modify) | Orchestrates: resolve → resolve mapping → count live → authorize or deny |
+| `central-unifi/src/Console/ReconcilePortal.php` (create) | Scheduled repair of drift in both directions |
+| `central-unifi/database/migrations/2026_08_21_000001_add_is_randomized_to_portal_sessions.php` (create) | One nullable boolean column |
+
+`DeviceResolver` is deliberately separate from `PortalController`: it is the security boundary, it has four distinct refusal modes, and it needs to be testable without touching quotas or Inertia.
+
+---
+
+## Task 1: A live authorization is the unit of quota
+
+**Files:**
+- Modify: `/project/central-unifi/src/Models/PortalSession.php`
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/PortalSessionLiveScopeTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/PortalSessionLiveScopeTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use App\Models\User;
+use Dashboard\Unifi\Models\PortalSession;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+/**
+ * A SLOT IS CONSUMED BY A LIVE AUTHORIZATION, NOT BY A PRESENT DEVICE.
+ *
+ * The portal used to free a slot when isClientConnected() was false, which
+ * conflates "connected right now" with "authorized". A phone that leaves the
+ * building is still authorized by UniFi for the rest of its window, so freeing
+ * its slot let the owner authorize a second device — two devices on a one-device
+ * quota, one of them an orphan nothing tracked.
+ *
+ * expires_at is nullable and, before this change, was written and never read.
+ * A NULL is therefore a legacy row from before anything enforced it: treated as
+ * NOT live, which is safe because unifi_portal_sessions holds no rows anyone
+ * depends on.
+ */
+class PortalSessionLiveScopeTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function session(array $overrides = []): PortalSession
+    {
+        return PortalSession::create(array_merge([
+            'user_id'       => User::factory()->create(['is_active' => true])->id,
+            'mac_address'   => '02:11:22:33:44:55',
+            'is_active'     => true,
+            'authorized_at' => now()->subHour(),
+            'expires_at'    => now()->addDay(),
+        ], $overrides));
+    }
+
+    public function test_an_unexpired_active_session_is_live(): void
+    {
+        $this->session();
+        $this->assertSame(1, PortalSession::live()->count());
+    }
+
+    public function test_an_expired_session_is_not_live(): void
+    {
+        $this->session(['expires_at' => now()->subMinute()]);
+        $this->assertSame(0, PortalSession::live()->count(),
+            'expires_at was written and never read — an expired row kept consuming a slot');
+    }
+
+    public function test_an_inactive_session_is_not_live(): void
+    {
+        $this->session(['is_active' => false]);
+        $this->assertSame(0, PortalSession::live()->count());
+    }
+
+    public function test_a_session_with_no_expiry_is_not_live(): void
+    {
+        $this->session(['expires_at' => null]);
+        $this->assertSame(0, PortalSession::live()->count(),
+            'a NULL expiry is a legacy row from before this was enforced, not an eternal grant');
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+cd /project/dashboard-shell
+bin/agentdb test "$DB" tests/Feature/Unifi/PortalSessionLiveScopeTest.php
+```
+
+Expected: FAIL — `Call to undefined method ...PortalSession::live()`.
+
+- [ ] **Step 3: Add the scope**
+
+In `/project/central-unifi/src/Models/PortalSession.php`, add inside the class:
+
+```php
+    /**
+     * The rows that consume a device slot.
+     *
+     * Presence on the network is deliberately NOT part of this. UniFi holds an
+     * authorization for its full window whether or not the device is in the
+     * building, so a phone that went home still owns its slot — freeing it here
+     * is what let one person hold two authorizations against a one-device quota.
+     *
+     * A NULL expires_at is not live: it predates this being enforced.
+     */
+    public function scopeLive($query)
+    {
+        return $query->where('is_active', true)
+            ->whereNotNull('expires_at')
+            ->where('expires_at', '>', now());
+    }
+```
+
+- [ ] **Step 4: Run it and confirm it passes**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/PortalSessionLiveScopeTest.php
+```
+
+Expected: PASS, 4 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C /project/central-unifi commit -m "A live authorization is what consumes a Wi-Fi device slot" -- src/Models/PortalSession.php
+git -C /project/dashboard-shell add tests/Feature/Unifi/PortalSessionLiveScopeTest.php
+git -C /project/dashboard-shell commit -m "A live authorization is what consumes a Wi-Fi device slot" -- tests/Feature/Unifi/PortalSessionLiveScopeTest.php
+```
+
+---
+
+## Task 2: Presence stops freeing slots
+
+**Files:**
+- Modify: `/project/central-unifi/src/Http/Controllers/PortalController.php` (the `foreach ($activeSessions ...)` block and the count below it)
+- Modify: `/project/dashboard-shell/tests/Feature/Unifi/PortalDeniedTest.php` (its fixtures predate `expires_at` mattering)
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use App\Models\User;
+use Dashboard\Unifi\Models\PortalSession;
+use Dashboard\Unifi\Models\VlanMapping;
+use Dashboard\Unifi\Services\UnifiApiClient;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Tests\TestCase;
+
+/**
+ * THE DEVICE THAT WENT HOME KEEPS ITS SLOT.
+ *
+ * isClientConnected() must not be consulted when counting the quota. If it is,
+ * a one-device student whose phone is out of range is handed a second
+ * authorization, and UniFi ends up holding two for them.
+ */
+class PortalQuotaCountsAuthorizationsTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function oneDeviceMappingFor(User $user): void
+    {
+        $user->addRole('student');
+        VlanMapping::create([
+            'group_name'      => 'Students',
+            'match_type'      => 'role',
+            'match_value'     => 'student',
+            'vlan_id'         => 20,
+            'max_devices'     => 1,
+            'session_minutes' => 60,
+            'sort_order'      => 1,
+        ]);
+    }
+
+    public function test_an_absent_device_still_holds_its_slot(): void
+    {
+        $user = User::factory()->create(['is_active' => true]);
+        $this->oneDeviceMappingFor($user);
+
+        PortalSession::create([
+            'user_id'       => $user->id,
+            'mac_address'   => '02:aa:bb:cc:dd:ee',
+            'is_active'     => true,
+            'authorized_at' => now()->subHour(),
+            'expires_at'    => now()->addHour(),
+        ]);
+
+        // The device is NOT on the network, and that must change nothing.
+        $this->mock(UnifiApiClient::class, function ($mock) {
+            $mock->shouldReceive('isClientConnected')->andReturn(false);
+            $mock->shouldNotReceive('authorizeGuest');
+        });
+
+        // The MAC still arrives as a parameter at this point in the plan; Task 4
+        // replaces that and updates this test with it.
+        $response = $this->actingAs($user->fresh())
+            ->get(route('unifi.portal.callback', [
+                'mac' => '02:99:88:77:66:55', 'ap' => 'ac:8b:a9:00:00:01', 'ssid' => 'BYOD',
+            ]));
+
+        $response->assertOk();
+        $response->assertInertia(fn ($page) => $page->component('Unifi/PortalDenied'));
+        $this->assertSame(1, PortalSession::live()->where('user_id', $user->id)->count(),
+            'the absent device must still own its slot');
+    }
+
+    public function test_an_expired_session_does_not_block_a_new_device(): void
+    {
+        $user = User::factory()->create(['is_active' => true]);
+        $this->oneDeviceMappingFor($user);
+
+        PortalSession::create([
+            'user_id'       => $user->id,
+            'mac_address'   => '02:aa:bb:cc:dd:ee',
+            'is_active'     => true,
+            'authorized_at' => now()->subDays(2),
+            'expires_at'    => now()->subDay(),
+        ]);
+
+        $this->mock(UnifiApiClient::class, function ($mock) {
+            $mock->shouldReceive('isClientConnected')->andReturn(false);
+            $mock->shouldReceive('authorizeGuest')->once()->andReturn([]);
+        });
+
+        $this->actingAs($user->fresh())
+            ->get(route('unifi.portal.callback', [
+                'mac' => '02:99:88:77:66:55', 'ap' => 'ac:8b:a9:00:00:01', 'ssid' => 'BYOD',
+            ]))
+            ->assertRedirect();
+
+        $this->assertDatabaseHas('unifi_portal_sessions', [
+            'user_id' => $user->id, 'mac_address' => '02:99:88:77:66:55', 'is_active' => 1,
+        ]);
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php
+```
+
+Expected: FAIL — `role` is not a match type yet, so `resolveMapping()` returns null and both cases render the "no access configured" denial instead of the quota one.
+
+Do Task 3 first if you want this green immediately; the two are independent and either order works. Nothing here is left knowingly red.
+
+- [ ] **Step 3: Replace the presence sweep with a live count**
+
+In `/project/central-unifi/src/Http/Controllers/PortalController.php`, delete the whole `$activeSessions = ...` block, the `foreach ($activeSessions as $session)` loop, and the `$activeCount = ...` line, and put this in their place:
+
+```php
+        /*
+         * Presence is NOT the question — a live authorization is.
+         *
+         * This used to walk the user's sessions and mark any device UniFi did not
+         * currently see as stale, freeing its slot. But UniFi holds an
+         * authorization for its whole window regardless of whether the device is
+         * in the building, so a phone that went home had its slot freed while
+         * still being authorized: the owner then authorized a second device and
+         * one of the two was an orphan nothing tracked. The longer
+         * session_minutes is — and it is now meant to be a term — the more of
+         * those accumulate.
+         *
+         * Slots are now freed by eviction, by expiry, or by ReconcilePortal.
+         */
+        $live = PortalSession::live()->where('user_id', $user->id)->get();
+
+        // The same device coming back is a renewal, not a new device: it keeps
+        // its slot and its row, and simply gets a fresh window.
+        $existing = $live->firstWhere('mac_address', $clientMac);
+
+        if (! $existing && $live->count() >= $mapping->max_devices) {
+            return Inertia::render('Unifi/PortalDenied', [
+                'reason'   => "You already have {$live->count()} device(s) connected (limit: {$mapping->max_devices}).",
+                'sessions' => $live->map(fn ($s) => [
+                    'id'       => $s->id,
+                    'mac'      => $s->mac_address,
+                    'hostname' => $s->device_hostname,
+                    'os'       => $s->device_os,
+                    'since'    => $s->authorized_at->toISOString(),
+                ]),
+                'can_disconnect' => true,
+            ]);
+        }
+```
+
+Then, further down, replace the `PortalSession::create([...])` call with an upsert so a renewal reuses its row:
+
+```php
+        $unifi->authorizeGuest($clientMac, $minutes);
+
+        PortalSession::updateOrCreate(
+            ['user_id' => $user->id, 'mac_address' => $clientMac],
+            [
+                'device_hostname' => $request->input('hostname'),
+                'device_os'       => $request->input('os'),
+                'device_type'     => $request->input('dev_cat'),
+                'ssid'            => $ssid,
+                'vlan_id'         => $mapping->vlan_id,
+                'ap_mac'          => $apMac,
+                'is_active'       => true,
+                'authorized_at'   => now(),
+                'expires_at'      => now()->addMinutes($minutes),
+            ]
+        );
+```
+
+- [ ] **Step 4: Fix the existing test's fixtures**
+
+`tests/Feature/Unifi/PortalDeniedTest.php` creates sessions without `expires_at`, which are now not live. In `test_a_user_over_the_device_limit_sees_their_devices` and `test_an_ordinary_user_can_disconnect_their_own_device`, add `'expires_at' => now()->addDay(),` to every `PortalSession::create([...])`. Its `shouldReceive('isClientConnected')` line can stay — it is now simply never called.
+
+- [ ] **Step 5: Run the whole Unifi suite**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/
+```
+
+Expected: `PortalDeniedTest` and `PortalSessionLiveScopeTest` PASS. `PortalQuotaCountsAuthorizationsTest` still FAILS until Task 4. Nothing else regresses.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git -C /project/central-unifi commit -m "Network presence no longer frees a device slot" -- src/Http/Controllers/PortalController.php
+git -C /project/dashboard-shell add tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php
+git -C /project/dashboard-shell commit -m "Network presence no longer frees a device slot" -- tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php tests/Feature/Unifi/PortalDeniedTest.php
+```
+
+---
+
+## Task 3: Access is an explicit per-role allow-list
+
+**Files:**
+- Modify: `/project/central-unifi/src/Http/Controllers/PortalController.php` (`resolveMapping`, and the two `match_type` validation rules)
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/WifiRoleAllowListTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/WifiRoleAllowListTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use App\Models\Group;
+use App\Models\User;
+use Dashboard\Unifi\Models\VlanMapping;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Tests\TestCase;
+
+/**
+ * NOBODY GETS WI-FI UNTIL A ROLE IS ADDED WITH AN AMOUNT.
+ *
+ * `default` matched everybody, which made the allow-list advisory. It is removed
+ * rather than merely discouraged. Safe to remove now and not later:
+ * unifi_vlan_mappings has zero rows in every environment, so nothing is revoked
+ * — the same change after a school had leaned on a catch-all would cut off every
+ * unmapped person at once.
+ */
+class WifiRoleAllowListTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function super(): User
+    {
+        $u = User::factory()->create(['is_active' => true]);
+        $u->groups()->attach(Group::where('is_super', true)->first());
+
+        return $u->fresh();
+    }
+
+    private function mapping(array $overrides = []): array
+    {
+        return array_merge([
+            'group_name'      => 'Students',
+            'match_type'      => 'role',
+            'match_value'     => 'student',
+            'vlan_id'         => 20,
+            'max_devices'     => 1,
+            'session_minutes' => 60,
+        ], $overrides);
+    }
+
+    public function test_a_role_mapping_can_be_created(): void
+    {
+        $this->actingAs($this->super())
+            ->post(route('unifi.portal.mappings.store'), $this->mapping())
+            ->assertRedirect();
+
+        $this->assertDatabaseHas('unifi_vlan_mappings', ['match_type' => 'role', 'match_value' => 'student']);
+    }
+
+    public function test_a_default_catch_all_mapping_is_refused(): void
+    {
+        $this->actingAs($this->super())
+            ->post(route('unifi.portal.mappings.store'), $this->mapping(['match_type' => 'default', 'match_value' => '*']))
+            ->assertSessionHasErrors('match_type');
+
+        $this->assertDatabaseCount('unifi_vlan_mappings', 0);
+    }
+
+    public function test_a_user_holding_the_mapped_role_resolves_to_it(): void
+    {
+        $user = User::factory()->create(['is_active' => true]);
+        $user->addRole('student');
+        $this->assertTrue($user->fresh()->hasRole('student'),
+            'addRole() silently drops an unseeded slug, which would make this pass for the wrong reason');
+
+        VlanMapping::create($this->mapping() + ['sort_order' => 1]);
+
+        $this->assertSame(1, $this->resolvedMaxDevices($user->fresh()));
+    }
+
+    public function test_a_user_holding_no_mapped_role_gets_nothing(): void
+    {
+        $user = User::factory()->create(['is_active' => true]);
+        VlanMapping::create($this->mapping() + ['sort_order' => 1]);
+
+        $this->assertNull($this->resolvedMaxDevices($user->fresh()),
+            'no mapping must mean no Wi-Fi, not a fallback');
+    }
+
+    /** sort_order decides for somebody who holds two mapped roles. */
+    public function test_precedence_follows_sort_order(): void
+    {
+        $user = User::factory()->create(['is_active' => true]);
+        $user->addRole('staff');
+        $user->addRole('parent');
+
+        VlanMapping::create($this->mapping(['group_name' => 'Staff', 'match_value' => 'staff', 'max_devices' => 4]) + ['sort_order' => 1]);
+        VlanMapping::create($this->mapping(['group_name' => 'Parents', 'match_value' => 'parent', 'max_devices' => 2]) + ['sort_order' => 2]);
+
+        $this->assertSame(4, $this->resolvedMaxDevices($user->fresh()),
+            'a staff member who is also a parent should get the staff allowance');
+    }
+
+    /** Exercises resolveMapping through the only public door it has. */
+    private function resolvedMaxDevices(User $user): ?int
+    {
+        $method = new \ReflectionMethod(\Dashboard\Unifi\Http\Controllers\PortalController::class, 'resolveMapping');
+        $method->setAccessible(true);
+        $mapping = $method->invoke(app(\Dashboard\Unifi\Http\Controllers\PortalController::class), $user);
+
+        return $mapping?->max_devices;
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/WifiRoleAllowListTest.php
+```
+
+Expected: FAIL — the `role` match returns false (no such branch) and `default` is still accepted.
+
+- [ ] **Step 3: Add `role`, remove `default`**
+
+In `resolveMapping()`, replace the `match` block with:
+
+```php
+            $matched = match ($mapping->match_type) {
+                'email_domain' => str_ends_with($user->email ?? '', '@' . $mapping->match_value),
+                'group'        => $user->groups?->contains('name', $mapping->match_value) ?? false,
+                'ou'           => str_contains($user->ou ?? '', $mapping->match_value),
+                /*
+                 * Roles are the platform's own authority and need no external
+                 * sync to be correct, which is why quotas key off them.
+                 *
+                 * `default` is deliberately absent. It matched everybody, so its
+                 * existence made this an advisory list rather than an allow-list.
+                 * Returning null here is already the deny path: captiveCallback
+                 * renders "No WiFi access configured for your account."
+                 */
+                'role'         => $user->hasRole($mapping->match_value),
+                default        => false,
+            };
+```
+
+In **both** `storeMapping()` and `updateMapping()`, change the match_type rule:
+
+```php
+            'match_type'      => 'required|in:ou,group,email_domain,role',
+```
+
+- [ ] **Step 4: Run it and confirm it passes**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/WifiRoleAllowListTest.php
+```
+
+Expected: PASS, 5 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C /project/central-unifi commit -m "Wi-Fi access becomes an explicit per-role allow-list" -- src/Http/Controllers/PortalController.php
+git -C /project/dashboard-shell add tests/Feature/Unifi/WifiRoleAllowListTest.php
+git -C /project/dashboard-shell commit -m "Wi-Fi access becomes an explicit per-role allow-list" -- tests/Feature/Unifi/WifiRoleAllowListTest.php
+```
+
+---
+
+## Task 4: Prove the device belongs to the person
+
+**Files:**
+- Create: `/project/central-unifi/src/Support/MacAddress.php`
+- Create: `/project/central-unifi/src/Services/DeviceResolver.php`
+- Modify: `/project/central-unifi/src/Services/UnifiApiClient.php` (add `findClientByIp`)
+- Modify: `/project/central-unifi/src/Http/Controllers/PortalController.php` (use the resolver instead of `?mac=`)
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/DeviceResolverTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/DeviceResolverTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use Dashboard\Unifi\Services\DeviceResolver;
+use Dashboard\Unifi\Services\UnifiApiClient;
+use Illuminate\Http\Request;
+use Tests\TestCase;
+
+/**
+ * THE CALLER DOES NOT GET TO NAME A MAC.
+ *
+ * Everything identifying the device used to be request-supplied, so any signed-in
+ * account could call /portal/wifi/callback?mac=<somebody else's MAC> and admit a
+ * device they did not own, up to max_devices. The MAC is now derived from the
+ * request's source IP via UniFi's own client table, and the client must be
+ * associated to the AP that issued the redirect.
+ *
+ * Every failure mode refuses. That is deliberate, and it is also the risk: if
+ * TrustProxies is wrong behind Traefik, every request resolves to the proxy and
+ * NOBODY gets on the Wi-Fi. So "this IP is the proxy" is a distinct, reportable
+ * outcome rather than just another miss.
+ */
+class DeviceResolverTest extends TestCase
+{
+    private function resolver(array $client = null): DeviceResolver
+    {
+        $mock = \Mockery::mock(UnifiApiClient::class);
+        $mock->shouldReceive('findClientByIp')->andReturn($client);
+        $this->app->instance(UnifiApiClient::class, $mock);
+
+        return app(DeviceResolver::class);
+    }
+
+    private function request(array $server = [], array $headers = []): Request
+    {
+        $r = Request::create('/portal/wifi/callback', 'GET', [], [], [], array_merge(['REMOTE_ADDR' => '10.20.0.9'], $server));
+        foreach ($headers as $k => $v) {
+            $r->headers->set($k, $v);
+        }
+
+        return $r;
+    }
+
+    public function test_it_derives_the_mac_from_the_source_ip(): void
+    {
+        $result = $this->resolver([
+            'mac' => '02:aa:bb:cc:dd:ee', 'ap_mac' => 'ac:8b:a9:00:00:01', 'ip' => '10.20.0.9',
+        ])->resolve($this->request(), 'ac:8b:a9:00:00:01');
+
+        $this->assertTrue($result->ok);
+        $this->assertSame('02:aa:bb:cc:dd:ee', $result->mac);
+    }
+
+    public function test_it_refuses_when_no_client_matches_the_ip(): void
+    {
+        $result = $this->resolver(null)->resolve($this->request(), 'ac:8b:a9:00:00:01');
+
+        $this->assertFalse($result->ok);
+        $this->assertSame('no_client', $result->reason);
+    }
+
+    public function test_it_refuses_when_the_client_is_on_a_different_ap(): void
+    {
+        $result = $this->resolver([
+            'mac' => '02:aa:bb:cc:dd:ee', 'ap_mac' => 'ac:8b:a9:00:00:99', 'ip' => '10.20.0.9',
+        ])->resolve($this->request(), 'ac:8b:a9:00:00:01');
+
+        $this->assertFalse($result->ok);
+        $this->assertSame('ap_mismatch', $result->reason);
+    }
+
+    /**
+     * The outage case, reported distinctly. A forwarded header present while the
+     * request IP still equals REMOTE_ADDR means TrustProxies is not applying.
+     */
+    public function test_it_reports_an_untrusted_proxy_separately(): void
+    {
+        $result = $this->resolver(null)->resolve(
+            $this->request([], ['X-Forwarded-For' => '10.20.0.9']),
+            'ac:8b:a9:00:00:01'
+        );
+
+        $this->assertFalse($result->ok);
+        $this->assertSame('proxy_untrusted', $result->reason);
+    }
+
+    /**
+     * A device that has just associated has no IP yet, so it is briefly absent
+     * from UniFi's table. Refusing on the first miss would tell a pupil their
+     * device is not connected at the exact moment it is connecting.
+     */
+    public function test_it_retries_before_giving_up_on_a_missing_client(): void
+    {
+        $mock = \Mockery::mock(UnifiApiClient::class);
+        $mock->shouldReceive('findClientByIp')->times(3)->andReturn(null);
+        $this->app->instance(UnifiApiClient::class, $mock);
+
+        $result = app(DeviceResolver::class)->resolve($this->request(), 'ac:8b:a9:00:00:01');
+
+        $this->assertFalse($result->ok);
+        $this->assertSame('no_client', $result->reason);
+    }
+
+    /** It must stop retrying the moment it succeeds. */
+    public function test_it_does_not_retry_once_it_has_the_client(): void
+    {
+        $mock = \Mockery::mock(UnifiApiClient::class);
+        $mock->shouldReceive('findClientByIp')->once()->andReturn([
+            'mac' => '02:aa:bb:cc:dd:ee', 'ap_mac' => 'ac:8b:a9:00:00:01', 'ip' => '10.20.0.9',
+        ]);
+        $this->app->instance(UnifiApiClient::class, $mock);
+
+        $this->assertTrue(app(DeviceResolver::class)->resolve($this->request(), 'ac:8b:a9:00:00:01')->ok);
+    }
+
+    public function test_it_ignores_a_supplied_mac_entirely(): void
+    {
+        $request = $this->request();
+        $request->query->set('mac', '02:99:99:99:99:99');   // somebody else's device
+
+        $result = $this->resolver([
+            'mac' => '02:aa:bb:cc:dd:ee', 'ap_mac' => 'ac:8b:a9:00:00:01', 'ip' => '10.20.0.9',
+        ])->resolve($request, 'ac:8b:a9:00:00:01');
+
+        $this->assertSame('02:aa:bb:cc:dd:ee', $result->mac,
+            'the derived MAC must win; a supplied one is never trusted');
+        $this->assertTrue($result->macParameterDisagreed,
+            'a disagreement is somebody authorizing a device they do not own, and must be visible');
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/DeviceResolverTest.php
+```
+
+Expected: FAIL — `Class "Dashboard\Unifi\Services\DeviceResolver" not found`.
+
+- [ ] **Step 3: Add the MAC helper**
+
+Create `/project/central-unifi/src/Support/MacAddress.php`:
+
+```php
+<?php
+
+namespace Dashboard\Unifi\Support;
+
+/**
+ * Pure MAC helpers. No dependencies, so they are cheap to test and safe to call
+ * from anywhere.
+ */
+class MacAddress
+{
+    /** Lower-case, colon-separated, or null if it is not a MAC at all. */
+    public static function normalise(?string $mac): ?string
+    {
+        $mac = strtolower(str_replace('-', ':', trim((string) $mac)));
+
+        return preg_match('/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/', $mac) ? $mac : null;
+    }
+
+    /**
+     * Is this a private (randomized) address rather than a real manufacturer one?
+     *
+     * The locally-administered bit is the second-least-significant bit of the
+     * first octet. iOS "Private Wi-Fi Address" and Android per-network
+     * randomization both set it. This is why OUI is useless for identifying
+     * device types: a randomized MAC has no real manufacturer prefix.
+     */
+    public static function isRandomized(string $mac): bool
+    {
+        return (bool) (hexdec(substr($mac, 0, 2)) & 0b10);
+    }
+}
+```
+
+- [ ] **Step 4: Add the client lookup**
+
+In `/project/central-unifi/src/Services/UnifiApiClient.php`, after `getActiveClients()`:
+
+```php
+    /**
+     * The client currently holding this IP, or null.
+     *
+     * Reads the cached client list rather than querying per IP: the portal calls
+     * this once per connection attempt, and a class arriving at once would
+     * otherwise be one controller round trip each.
+     */
+    public function findClientByIp(string $ip): ?array
+    {
+        foreach ($this->getActiveClients() as $client) {
+            if (($client['ip'] ?? null) === $ip) {
+                return $client;
+            }
+        }
+
+        return null;
+    }
+```
+
+- [ ] **Step 5: Add the resolver**
+
+Create `/project/central-unifi/src/Services/DeviceResolver.php`:
+
+```php
+<?php
+
+namespace Dashboard\Unifi\Services;
+
+use Dashboard\Unifi\Support\MacAddress;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Log;
+
+/** The outcome of trying to identify the device making a portal request. */
+class ResolvedDevice
+{
+    public function __construct(
+        public bool $ok,
+        public ?string $mac = null,
+        public ?string $reason = null,
+        public bool $isRandomized = false,
+        public bool $macParameterDisagreed = false,
+        public array $client = [],
+    ) {}
+}
+
+/**
+ * Identify the device that made a captive-portal request, or refuse.
+ *
+ * The `?mac=` parameter is NOT trusted. It is read only so a disagreement with
+ * the derived value can be logged — that disagreement is somebody trying to
+ * authorize a device they do not own, and before this nothing anywhere noticed.
+ *
+ * Every path refuses rather than guessing. The cost of that is real: if
+ * TrustProxies is misconfigured, `proxy_untrusted` is returned for everyone and
+ * nobody gets online, which is why it is a distinct reason the portal page can
+ * report instead of a generic miss.
+ */
+class DeviceResolver
+{
+    public function __construct(private UnifiApiClient $unifi) {}
+
+    /** Attempts, and the pause between them, for a device that has just associated. */
+    private const ATTEMPTS   = 3;
+    private const PAUSE_US   = 750_000;
+
+    public function resolve(Request $request, string $apMac): ResolvedDevice
+    {
+        $ip = $request->ip();
+
+        /*
+         * A device that has only just associated may have no IP yet, so UniFi's
+         * client table does not know it. Retry briefly rather than telling a
+         * pupil their device is not connected when it is about to be.
+         *
+         * Bounded on purpose: this runs inside a web request, and a longer wait
+         * would hold a worker per connecting device at exactly the moment a
+         * class of them arrives at once.
+         */
+        $client = null;
+        for ($attempt = 1; $attempt <= self::ATTEMPTS; $attempt++) {
+            $client = $this->unifi->findClientByIp($ip);
+            if ($client) {
+                break;
+            }
+            if ($attempt < self::ATTEMPTS) {
+                usleep(self::PAUSE_US);
+            }
+        }
+
+        if (! $client) {
+            // A forwarded header present while the request IP is still the raw
+            // socket address means TrustProxies is not applying, so every lookup
+            // here is doomed for the same reason. Say which failure this is.
+            $forwarded = $request->headers->get('X-Forwarded-For');
+            $raw       = $request->server('REMOTE_ADDR');
+            $reason    = ($forwarded && $ip === $raw) ? 'proxy_untrusted' : 'no_client';
+
+            return new ResolvedDevice(ok: false, reason: $reason);
+        }
+
+        $mac = MacAddress::normalise($client['mac'] ?? null);
+        if (! $mac) {
+            return new ResolvedDevice(ok: false, reason: 'no_client');
+        }
+
+        $clientAp = MacAddress::normalise($client['ap_mac'] ?? null);
+        if (! $clientAp || $clientAp !== MacAddress::normalise($apMac)) {
+            return new ResolvedDevice(ok: false, reason: 'ap_mismatch');
+        }
+
+        $supplied   = MacAddress::normalise($request->input('mac'));
+        $disagreed  = $supplied !== null && $supplied !== $mac;
+
+        if ($disagreed) {
+            Log::warning('unifi.portal: supplied MAC disagreed with the derived one', [
+                'derived' => $mac, 'supplied' => $supplied, 'ip' => $ip, 'ap' => $apMac,
+            ]);
+        }
+
+        return new ResolvedDevice(
+            ok: true,
+            mac: $mac,
+            isRandomized: MacAddress::isRandomized($mac),
+            macParameterDisagreed: $disagreed,
+            client: $client,
+        );
+    }
+}
+```
+
+- [ ] **Step 6: Run it and confirm it passes**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/DeviceResolverTest.php
+```
+
+Expected: PASS, 5 tests.
+
+- [ ] **Step 7: Use it in the controller**
+
+In `captiveCallback()`, delete the `$clientMac = strtolower($request->input('mac', ...))` line, the `if (! $clientMac)` guard, and the whole `preg_match` block with its security comment. Replace with:
+
+```php
+        $apMac = (string) $request->input('ap', '');
+        $ssid  = (string) $request->input('ssid', '');
+
+        $device = app(\Dashboard\Unifi\Services\DeviceResolver::class)->resolve($request, $apMac);
+
+        if (! $device->ok) {
+            return Inertia::render('Unifi/PortalDenied', [
+                'reason' => match ($device->reason) {
+                    'ap_mismatch'     => 'That device is not connected to this access point. Reconnect and try again.',
+                    'proxy_untrusted' => 'Wi-Fi sign-in is misconfigured and cannot identify your device. Please tell IT.',
+                    default           => 'Still connecting — wait a moment and try again.',
+                },
+                'resolveFailure' => $device->reason,
+            ]);
+        }
+
+        $clientMac    = $device->mac;
+        $isRandomized = $device->isRandomized;
+```
+
+- [ ] **Step 7b: Move the Task 2 test onto the derived MAC**
+
+`PortalQuotaCountsAuthorizationsTest` still passes `?mac=`, which is now ignored. In both tests, drop the `'mac' => '02:99:88:77:66:55',` query parameter, add `->withServerVariables(['REMOTE_ADDR' => '10.20.0.9'])` before `->get(...)`, and add this to each mock closure:
+
+```php
+            $mock->shouldReceive('findClientByIp')->andReturn([
+                'mac' => '02:99:88:77:66:55', 'ap_mac' => 'ac:8b:a9:00:00:01', 'ip' => '10.20.0.9',
+            ]);
+```
+
+The assertions do not change — the same device is identified a trustworthy way.
+
+- [ ] **Step 8: Run the whole Unifi suite**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/
+```
+
+Expected: everything PASSES.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git -C /project/central-unifi commit -m "The portal derives the device MAC instead of trusting the caller" -- src/Support/MacAddress.php src/Services/DeviceResolver.php src/Services/UnifiApiClient.php src/Http/Controllers/PortalController.php
+git -C /project/dashboard-shell add tests/Feature/Unifi/DeviceResolverTest.php
+git -C /project/dashboard-shell commit -m "The portal derives the device MAC instead of trusting the caller" -- tests/Feature/Unifi/DeviceResolverTest.php tests/Feature/Unifi/PortalQuotaCountsAuthorizationsTest.php
+```
+
+---
+
+## Task 5: Record whether the address was randomized
+
+**Files:**
+- Create: `/project/central-unifi/database/migrations/2026_08_21_000001_add_is_randomized_to_portal_sessions.php`
+- Modify: `/project/central-unifi/src/Models/PortalSession.php` (`$fillable`, `$casts`)
+- Modify: `/project/central-unifi/src/Http/Controllers/PortalController.php` (write it on the session)
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/RandomizedMacIsRecordedTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/RandomizedMacIsRecordedTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use Dashboard\Unifi\Support\MacAddress;
+use Tests\TestCase;
+
+/**
+ * Detecting a private address is what lets the denial page explain why a phone
+ * looks like a new device, instead of asking somebody to disconnect the very
+ * handset they are holding. Plan 2 writes that copy; this records the fact.
+ */
+class RandomizedMacIsRecordedTest extends TestCase
+{
+    /** 0x02 has the locally-administered bit set. */
+    public function test_a_private_address_is_detected(): void
+    {
+        $this->assertTrue(MacAddress::isRandomized('02:aa:bb:cc:dd:ee'));
+        $this->assertTrue(MacAddress::isRandomized('a6:11:22:33:44:55'));
+    }
+
+    /** A real Ubiquiti prefix does not. */
+    public function test_a_manufacturer_address_is_not(): void
+    {
+        $this->assertFalse(MacAddress::isRandomized('ac:8b:a9:00:00:01'));
+        $this->assertFalse(MacAddress::isRandomized('f0:9f:c2:11:22:33'));
+    }
+
+    public function test_it_normalises_before_judging(): void
+    {
+        $this->assertSame('02:aa:bb:cc:dd:ee', MacAddress::normalise('02-AA-BB-CC-DD-EE'));
+        $this->assertNull(MacAddress::normalise('not a mac'));
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it passes already**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/RandomizedMacIsRecordedTest.php
+```
+
+Expected: PASS — `MacAddress` landed in Task 4. This test exists to pin the bit arithmetic, which is the part nobody will remember.
+
+- [ ] **Step 3: Add the column**
+
+Create `/project/central-unifi/database/migrations/2026_08_21_000001_add_is_randomized_to_portal_sessions.php`:
+
+```php
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Whether the device presented a private (randomized) address.
+ *
+ * Nullable, because rows written before this existed genuinely do not know —
+ * defaulting them to false would assert something untrue about every historical
+ * session.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('unifi_portal_sessions', function (Blueprint $table) {
+            $table->boolean('is_randomized')->nullable()->after('mac_address');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('unifi_portal_sessions', function (Blueprint $table) {
+            $table->dropColumn('is_randomized');
+        });
+    }
+};
+```
+
+- [ ] **Step 4: Store it**
+
+In `PortalSession.php` add `'is_randomized'` to `$fillable` and `'is_randomized' => 'boolean'` to `$casts`.
+
+In `PortalController::captiveCallback`, add to the `updateOrCreate` payload from Task 2:
+
+```php
+                'is_randomized'   => $isRandomized,
+```
+
+- [ ] **Step 5: Run the suite**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/
+```
+
+Expected: all PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git -C /project/central-unifi commit -m "Record whether a portal session used a private Wi-Fi address" -- database/migrations/2026_08_21_000001_add_is_randomized_to_portal_sessions.php src/Models/PortalSession.php src/Http/Controllers/PortalController.php
+git -C /project/dashboard-shell add tests/Feature/Unifi/RandomizedMacIsRecordedTest.php
+git -C /project/dashboard-shell commit -m "Record whether a portal session used a private Wi-Fi address" -- tests/Feature/Unifi/RandomizedMacIsRecordedTest.php
+```
+
+---
+
+## Task 6: The reconciler
+
+**Files:**
+- Create: `/project/central-unifi/src/Console/ReconcilePortal.php`
+- Modify: `/project/central-unifi/src/Services/UnifiApiClient.php` (add `getAuthorizedGuestMacs`)
+- Modify: `/project/central-unifi/src/UnifiServiceProvider.php` (register the command)
+- Test: `/project/dashboard-shell/tests/Feature/Unifi/ReconcilePortalTest.php`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `/project/dashboard-shell/tests/Feature/Unifi/ReconcilePortalTest.php`:
+
+```php
+<?php
+
+namespace Tests\Feature\Unifi;
+
+use App\Models\User;
+use Dashboard\Unifi\Models\PortalSession;
+use Dashboard\Unifi\Services\UnifiApiClient;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+/**
+ * The reconciler is what keeps our rows and UniFi's authorizations from drifting
+ * once session windows are measured in months.
+ *
+ * It repairs BOTH directions, and the second one matters as much as the first: a
+ * UniFi authorization with no live row of ours is exactly the orphan the old
+ * presence-based sweep created, and it is a device on the network nobody can see.
+ */
+class ReconcilePortalTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function session(string $mac, array $overrides = []): PortalSession
+    {
+        return PortalSession::create(array_merge([
+            'user_id'       => User::factory()->create(['is_active' => true])->id,
+            'mac_address'   => $mac,
+            'is_active'     => true,
+            'authorized_at' => now()->subHour(),
+            'expires_at'    => now()->addDay(),
+        ], $overrides));
+    }
+
+    /**
+     * One fake for the whole class. The command calls four methods on the client
+     * and every test needs all four stubbed — doing that per test means adding a
+     * line to four closures every time the command learns a new call, and
+     * whichever one gets missed fails for a reason unrelated to what it tests.
+     *
+     * Returns the mock so a test can tighten an expectation on it.
+     */
+    private function fakeUnifi(array $authorized = [], array $clients = [])
+    {
+        $mock = \Mockery::mock(UnifiApiClient::class);
+        $mock->shouldReceive('getAuthorizedGuestMacs')->andReturn($authorized);
+        $mock->shouldReceive('getActiveClients')->andReturn($clients);
+        $mock->shouldReceive('unauthorizeGuest')->andReturn([]);
+        $mock->shouldReceive('authorizeGuest')->andReturn([]);
+        $this->app->instance(UnifiApiClient::class, $mock);
+
+        return $mock;
+    }
+
+    public function test_it_deactivates_rows_past_their_expiry(): void
+    {
+        $stale = $this->session('02:00:00:00:00:01', ['expires_at' => now()->subMinute()]);
+        $this->fakeUnifi();
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+
+        $this->assertFalse((bool) $stale->fresh()->is_active);
+    }
+
+    public function test_it_revokes_a_unifi_authorization_with_no_live_row(): void
+    {
+        $mock = $this->fakeUnifi(authorized: ['02:00:00:00:00:99']);
+        $mock->shouldReceive('unauthorizeGuest')->once()->with('02:00:00:00:00:99')->andReturn([]);
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+    }
+
+    /**
+     * A controller upgrade or restore can lose an authorization we still consider
+     * live. Re-asserting it means the user is not bounced to the portal for
+     * something that was not their doing.
+     */
+    public function test_it_reauthorizes_a_live_row_unifi_has_forgotten(): void
+    {
+        $this->session('02:00:00:00:00:07');
+        $mock = $this->fakeUnifi(authorized: []);
+        $mock->shouldReceive('authorizeGuest')->once()->andReturn([]);
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+    }
+
+    public function test_it_leaves_a_matching_live_row_alone(): void
+    {
+        $this->session('02:00:00:00:00:07');
+
+        $mock = \Mockery::mock(UnifiApiClient::class);
+        $mock->shouldReceive('getAuthorizedGuestMacs')->andReturn(['02:00:00:00:00:07']);
+        $mock->shouldReceive('getActiveClients')->andReturn([]);
+        $mock->shouldNotReceive('unauthorizeGuest');
+        $mock->shouldNotReceive('authorizeGuest');
+        $this->app->instance(UnifiApiClient::class, $mock);
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+    }
+
+    /**
+     * Device type is REPORTED, not enforced. UniFi infers it from observed
+     * traffic, so it is not available at the moment of authorization — the
+     * reconciler is the first point at which there is anything to record.
+     */
+    public function test_it_records_the_device_type_once_unifi_has_fingerprinted_it(): void
+    {
+        $session = $this->session('02:00:00:00:00:07');
+        $this->fakeUnifi(
+            authorized: ['02:00:00:00:00:07'],
+            clients: [[
+                'mac' => '02:00:00:00:00:07', 'dev_cat' => 'Smartphone',
+                'os_name' => 'iOS', 'hostname' => 'Alices-iPhone',
+            ]],
+        );
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+
+        $session->refresh();
+        $this->assertSame('Smartphone', $session->device_type);
+        $this->assertSame('iOS', $session->device_os);
+        $this->assertSame('Alices-iPhone', $session->device_hostname);
+    }
+
+    /** An unfingerprinted client must not blank what we already knew. */
+    public function test_it_does_not_overwrite_a_known_type_with_nothing(): void
+    {
+        $session = $this->session('02:00:00:00:00:07', ['device_type' => 'Laptop']);
+        $this->fakeUnifi(
+            authorized: ['02:00:00:00:00:07'],
+            clients: [['mac' => '02:00:00:00:00:07']],   // no dev_cat yet
+        );
+
+        $this->artisan('unifi:reconcile-portal')->assertExitCode(0);
+
+        $this->assertSame('Laptop', $session->fresh()->device_type);
+    }
+}
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/ReconcilePortalTest.php
+```
+
+Expected: FAIL — `The command "unifi:reconcile-portal" does not exist.`
+
+- [ ] **Step 3: Add the authorized-guest lookup**
+
+In `UnifiApiClient.php`, after `unauthorizeGuest()`:
+
+```php
+    /**
+     * The MACs UniFi currently holds an active guest authorization for.
+     *
+     * Read from /stat/guest, which is the authorization list — deliberately not
+     * /stat/sta, which is who is associated right now. Those are the two facts
+     * this whole feature had been conflating.
+     */
+    public function getAuthorizedGuestMacs(): array
+    {
+        $rows = $this->get('/stat/guest');
+
+        return collect($rows)
+            ->filter(fn ($g) => (int) ($g['end'] ?? 0) > now()->timestamp)
+            ->pluck('mac')
+            ->map(fn ($m) => strtolower((string) $m))
+            ->values()
+            ->all();
+    }
+```
+
+- [ ] **Step 4: Add the command**
+
+Create `/project/central-unifi/src/Console/ReconcilePortal.php`:
+
+```php
+<?php
+
+namespace Dashboard\Unifi\Console;
+
+use Dashboard\Unifi\Models\PortalSession;
+use Dashboard\Unifi\Services\UnifiApiClient;
+use Illuminate\Console\Command;
+
+/**
+ * Keep our rows and UniFi's authorizations in step.
+ *
+ * Necessary because session windows are now measured in months: any drift that
+ * used to be washed away by short sessions and frequent portal visits now
+ * persists. Three jobs, and the middle one is the one that matters most.
+ */
+class ReconcilePortal extends Command
+{
+    protected $signature   = 'unifi:reconcile-portal';
+    protected $description = 'Expire finished Wi-Fi sessions and reconcile them against UniFi authorizations';
+
+    public function handle(UnifiApiClient $unifi): int
+    {
+        // 1. Expiry. expires_at used to be written and never read, so a finished
+        //    row kept consuming a slot indefinitely.
+        $expired = PortalSession::where('is_active', true)
+            ->whereNotNull('expires_at')
+            ->where('expires_at', '<=', now())
+            ->update(['is_active' => false]);
+
+        if ($expired) {
+            $this->info("Expired {$expired} finished session(s).");
+        }
+
+        try {
+            $authorized = $unifi->getAuthorizedGuestMacs();
+        } catch (\Throwable $e) {
+            // A controller we cannot reach is not evidence that anything should
+            // change. Expiry above is local and already done.
+            $this->error('Could not read UniFi authorizations: ' . $e->getMessage());
+
+            return self::SUCCESS;
+        }
+
+        $live = PortalSession::live()->get()->keyBy(fn ($s) => strtolower($s->mac_address));
+
+        // 2. Orphans: authorized on the network with no live row of ours. These
+        //    are what the old presence-based sweep produced — a device nobody
+        //    can see in the UI and nobody's quota is paying for.
+        foreach (array_diff($authorized, $live->keys()->all()) as $orphan) {
+            $unifi->unauthorizeGuest($orphan);
+            $this->warn("Revoked orphan authorization {$orphan}.");
+        }
+
+        // 3. The other direction: we consider it live but UniFi has forgotten it
+        //    (upgrade, restore). Re-assert rather than making the person sign in
+        //    again for something that was not their doing.
+        foreach ($live->keys()->diff($authorized) as $mac) {
+            $session = $live->get($mac);
+            $minutes = max(1, (int) now()->diffInMinutes($session->expires_at, false));
+            $unifi->authorizeGuest($mac, $minutes);
+            $this->warn("Re-asserted authorization for {$mac} ({$minutes}m remaining).");
+        }
+
+        $this->captureFingerprints($unifi, $live);
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * Record what UniFi thinks each device IS. Reported only — nothing acts on
+     * it, per the decision that enforcing on unvalidated fingerprint data would
+     * lock out the wrong people.
+     *
+     * This is the earliest point the data exists: UniFi infers dev_cat from
+     * observed traffic, so it is absent at the moment of authorization.
+     *
+     * @param  \Illuminate\Support\Collection  $live  keyed by lower-case MAC
+     */
+    private function captureFingerprints(UnifiApiClient $unifi, $live): void
+    {
+        try {
+            $clients = collect($unifi->getActiveClients())
+                ->keyBy(fn ($c) => strtolower((string) ($c['mac'] ?? '')));
+        } catch (\Throwable $e) {
+            $this->error('Could not read clients for fingerprints: ' . $e->getMessage());
+
+            return;
+        }
+
+        foreach ($live as $mac => $session) {
+            $client = $clients->get($mac);
+            if (! $client) {
+                continue;
+            }
+
+            // Only ever fill in. An unfingerprinted client must not blank a type
+            // we already recorded — that would lose the answer every time the
+            // device happened to be quiet.
+            $updates = array_filter([
+                'device_type'     => $client['dev_cat']  ?? null,
+                'device_os'       => $client['os_name']  ?? null,
+                'device_hostname' => $client['hostname'] ?? null,
+            ], fn ($v) => $v !== null && $v !== '');
+
+            if ($updates) {
+                $session->update($updates);
+            }
+        }
+    }
+}
+```
+
+- [ ] **Step 5: Register it**
+
+In `/project/central-unifi/src/UnifiServiceProvider.php`, add `ReconcilePortal::class` to the existing `$this->commands([...])` array (alongside `CaptureSnapshots::class`). Import it at the top.
+
+- [ ] **Step 6: Run it and confirm it passes**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/ReconcilePortalTest.php
+```
+
+Expected: PASS, 4 tests.
+
+- [ ] **Step 7: Run the whole Unifi suite and the full suite once**
+
+```bash
+bin/agentdb test "$DB" tests/Feature/Unifi/
+bin/agentdb test "$DB"
+```
+
+Expected: Unifi all PASS. Full suite: only `Tests\Feature\Logs\ScriptRunsTest` fails — that is a known pre-existing failure, unrelated. Anything else is yours.
+
+- [ ] **Step 8: Bump the version and commit**
+
+```bash
+# patch bump central-unifi/composer.json (1.13.4 -> 1.13.5) by hand, then:
+git -C /project/central-unifi commit -m "Reconcile Wi-Fi sessions against UniFi authorizations" -- src/Console/ReconcilePortal.php src/Services/UnifiApiClient.php src/UnifiServiceProvider.php composer.json
+git -C /project/dashboard-shell add tests/Feature/Unifi/ReconcilePortalTest.php
+git -C /project/dashboard-shell commit -m "Reconcile Wi-Fi sessions against UniFi authorizations" -- tests/Feature/Unifi/ReconcilePortalTest.php
+```
+
+- [ ] **Step 9: Release the database slot**
+
+```bash
+bin/agentdb release "$DB"
+```
+
+---
+
+## Do not do these
+
+- **Do not schedule the reconciler yet.** It calls `unauthorizeGuest` against the live controller, and nothing here has been checked against real hardware. Scheduling belongs with the supervised verification session in the spec's section F, not in this plan.
+- **Do not register the `unifi` app.** Every route here still 404s because there is no `dashboard_apps` row, and whether that should change is an open question for the operator, not a step in this plan.
+- **Do not touch `disconnectSession`.** It already does `kickClient` + `unauthorizeGuest` and authorises owner-or-`unifi.auth` correctly.
+- **Do not remove `email_domain`, `group` or `ou`.** Only `default` is a catch-all; the others are narrow matches and are still useful.