Wake-on-LAN — complete the mobile.ts stub (relay-aware, audit-traced, /24 fallback)

[bdunncompany]

Why

apps/api/src/routes/mobile.ts:880-891 accepts a wake action and inserts a device_commands row addressed to the offline target itself. apps/docs/src/content/docs/features/mobile.mdx:74 describes the action as available for all devices. apps/api/src/routes/devices/schemas.ts:44 doesn't list 'wake' in createCommandSchema.type, so the mobile UI's POST /devices/:id/commands call at apps/mobile/src/services/api.ts:466 hits a validator error before reaching that stub.

Net effect: the existing wake scaffolding is incomplete — the schema, route, and docs each have partial entries but they don't connect to an executing agent handler. This proposal finishes wiring those pieces.

What this proposes

A relay-aware Wake-on-LAN implementation that fits Breeze's existing command pipeline:

1. New API service (apps/api/src/services/wakeOnLan.ts) — dispatchWake(targetDeviceId, userId, options) returns a discriminated union: WakeSuccess or one of seven WakeFailureCodes (TARGET_NOT_FOUND, NO_MACS, NO_SUBNET, IPV6_ONLY, NO_RELAY, RELAY_OVERRIDE_INVALID, WS_SEND_FAILED).
2. Relay selection — same site_id as target, online status, target's most-recent active IPv4 subnet matches an online peer's most-recent active IPv4 subnet. Most-recent lastSeen wins. Verifies WS connection before claiming.
3. MAC discovery — prefer device_network (live inventory), fall back to device_ip_history for legacy data. Includes every NIC's MAC, not just primary.
4. Subnet — read from device_ip_history.subnet_mask. Falls back to /24 when the column is null (pre-existing upstream gap; fix proposed below).
5. Row addressing — device_commands.deviceId = the relay's deviceId so the result handler at apps/api/src/routes/agentWs.ts:1248 matches. Payload carries { targetDeviceId, macs, broadcast, ports: [7, 9], wakeAttemptId }.
6. Audit — single auditLogs row addressed to the target (action = device.wake_on_lan). Details include relay info, broadcast, mask, maskSource: 'agent' | 'fallback_24', MAC list.
7. Route wiring — POST /devices/:id/commands with type: 'wake' calls dispatchWake. Returns 202 with {commandId, wakeAttemptId, relay, network, broadcast, macs} or 412 with {code, error}. Mobile-actions endpoint (/mobile/devices/:id/actions) wired in parallel for the legacy stub call site.
8. Agent handler (agent/internal/remote/tools/wake_on_lan.go) — pure-stdlib MagicPacket(mac) builder + WakeOnLan(payload) that fires 3 rounds × N MACs × M ports (default 7+9), 500 ms between rounds. Bind UDP to the broadcast address; rely on the kernel's interface selection. SO_BROADCAST is skipped because directed-broadcast (e.g., 192.168.1.255) works on Linux/macOS/Windows without it for this case; could be added behind a build-split helper if field testing shows otherwise.
9. Agent collector fix (separate concern — happy to split into a parallel PR) — agent/internal/collectors/inventory.go's NetworkAdapterInfo had no SubnetMask field, so ip_tracking.go:366-372 never populated it. Result: device_ip_history.subnet_mask is null on 100% of rows in production. Adds the field + populates from *net.IPNet.Mask returned by net.ParseCIDR. After this lands and agents heartbeat, the API-side /24 fallback becomes dead code for new data.
10. Web UI — Lightning-bolt Wake button on DeviceActions (compact + full bars), visible only when device.status === 'offline'. Renders the 7 failure codes as friendly toast text.
11. Mobile UI — existing Wake button surfaces the new structured response; ApiError-shaped 412s map to friendly text.
12. Docs — apps/docs/src/content/docs/features/mobile.mdx:74 rewritten with accurate semantics + a new pre-flight reference table.

No schema migration. All required columns already exist on devices, device_network, device_ip_history, sites, device_commands, audit_logs.

Live test result

Overnight on our prod fork: an offline workstation (10.10.144.172 last-known) → web Wake click → API auto-picked an online peer (10.10.144.126/24) → agent fired 18 packets (3 MACs × 2 ports × 3 rounds) to 10.10.144.255 in 1037 ms → target reported online 3 seconds later. End-to-end works.

Tests

• apps/api/src/services/wakeOnLan.test.ts — 10 helper unit tests (ipv4ToInt, intToIpv4, computeBroadcast across /8 /16 /23 /24 /32 + malformed input). All pass.
• agent/internal/remote/tools/wake_on_lan_test.go — 11 tests including magic-packet byte equality, MAC format parsing (colon/hyphen/cisco-dot/whitespace), IPv4-only enforcement, port range validation, and a full loopback dispatch test that opens a real UDP listener on 127.0.0.1 and verifies the 102-byte packet arrives.

Open questions for upstream

1. Relay override UI. The service accepts relayDeviceIdOverride; only auto-pick is wired through the UI. For troubleshooting multi-VLAN sites it'd help to expose a dropdown when 2+ candidates exist. Preference?
2. Bulk wake? I left bulkCommandSchema.type unchanged — bulk wake isn't sensible until relay capacity is reasoned about. Worth allowing?
3. Agent SubnetMask fix scope. The collector fix is functionally independent of WoL and could ship as a separate PR (cleaner blame story for the data-quality fix). Preference?
4. Permission gate. Currently uses DEVICES_EXECUTE (matching the /devices/:id/commands route's existing gate). Want to tighten to a new DEVICES_WAKE permission?

Test plan

• Pre-flight: NO_MACS, NO_SUBNET, IPV6_ONLY, NO_RELAY surfaced as 412 with code in body
• Happy path: 202 + relay info + audit row written
• Agent receives wake_on_lan command, fires packets, returns completed with packetsSent/packetsTotal
• Target wakes (BIOS WoL + Magic Packet enabled at NIC)
• /24 fallback exercised when subnet_mask is null (covered by service unit test)
• Web bundle: Wake button visible only when status=offline
• Mobile: 412 surfaces friendly text instead of [object Object]

PR is ready to open whenever you give the nod.

[ToddHebebrand]

Green light — PR welcome. The half-wired wake scaffolding has been a sharp edge for a while and the relay-aware design fits cleanly into the existing command pipeline.

A couple of nudges before you open the PR:

• Schema/RLS: device_commands is one of the agent-write hot tables (Shape 5 in CLAUDE.md), so the row addressed to the relay needs to carry org_id already-denormalized. No new policies required, just don't forget the column.
• Audit shape: actorType: 'user' with details.targetDeviceId is the right call — keeps the audit row queryable from the target's device timeline without dual-writes.
• Agent collector fix: happy to take that as a parallel PR as you suggested. Keep the wake PR scoped to API + agent handler + UI; the collector backfill can ship on its own track.

One open question before you start: would you like the wakeAttemptId to be a server-generated UUID returned in the 202 response, or do you want the client to mint it for idempotency? Either is fine, just want consistency with how we issue command IDs elsewhere (server-generated today).

[bdunncompany]

Thanks for the green light. Two of the three nudges land cleanly — wakeAttemptId is already randomUUID() server-side, and the audit details only needs targetDeviceId added alongside the existing resourceId: target.id. I'll fold that in.

One clarification before I open the PR: I read your device_commands note as "this table is Shape 5 — denormalize org_id on the relay row." But the schema in apps/api/src/db/schema/devices.ts:245-255 doesn't define an org_id column on device_commands, and the Tenant Isolation section of the project CLAUDE.md explicitly lists device_commands under "Intentionally system-scoped (agent WS path)" — i.e. NOT Shape 5. Production confirms: \d device_commands shows no org_id column.

So the nudge could mean any of:

1. Just don't forget the column — but it doesn't exist yet, and adding it is a real migration (NOT NULL backfill on a hot agent-write table) that I'd want to scope outside the WoL PR.
2. Shape 5 designation supersedes the CLAUDE.md "intentionally system-scoped" entry — i.e. CLAUDE.md is stale and this PR should add the migration.
3. I'm misreading the nudge entirely.

Which one matches your intent? I'd rather ask than guess given the table's traffic profile.

[ToddHebebrand]

Good catch — you're right, I was sloppy. Retracting nudge #1.

device_commands is intentionally system-scoped (the entry in CLAUDE.md is correct and current), and the agent WS path is the reason. No migration, no org_id column. Leave the table alone. Your existing addressing (relay's deviceId + payload carrying targetDeviceId) is exactly right.

The reason I half-typed that nudge was a stale mental model — I was thinking about the hot agent-write tables that do denormalize org_id (Shape 5 proper), and device_commands is sitting in the same neighborhood code-wise but is the explicit exception. Sorry for the noise.

Carry on with the PR as designed. The other two nudges still stand (server-generated wakeAttemptId ✅, audit details.targetDeviceId alongside resourceId ✅).

[ToddHebebrand]

Shipped — relay-aware Wake-on-LAN with audit trail, /24 fallback, and the agent magic-packet handler landed on main in #703 (merged 2026-05-15).

The half-wired wake scaffolding is now complete and consistent across schema, route, and docs, and device_commands stayed intentionally system-scoped (no org_id column) as we settled on in-thread. Thanks @bdunncompany. Closing as resolved — reopen if you hit anything.