command-center/agent/managed-skills/wol-wake-sleeping-fleet-host/SKILL.md at 689228e60dce2ed15206bac016d570384b6ec602

0 Fork 0

Files

T

Frank 689228e60d docs: purge the retired workstation from the knowledge base

Second half of the purge (the first covered the persona, AGENTS.md, README.md,
and the distillation of the per-host pages). Every remaining identifier is
gone: hostname, both LAN addresses, and the Wi-Fi SSID.

34 count-checked substitutions across 22 files — indexes, tool/research pages,
the inventory census, the changelog, one generated HTML report, and five
managed skills. Facts kept, names dropped: a history entry keeps its four-page
listing as a nameless summary, the syslog excerpts keep every timestamp and
line, and the census keeps the .zcompdump rows (the zsh version stamps are the
useful part, the hostname was not).

Deliberately unchanged: install.sh's --host case list and the
packages/<hostname>.pkgs filename, where the hostname is the lookup key.

Left out of scope by Frank's call: agent/memories/** — past-session records the
learn pipeline rewrites.

kb-lint: 0 violations. Residual grep for the hostname, its two IPs, and the
SSID across omp-docs/ and agent/managed-skills/: no hits.

2026-09-28 16:37:38 -07:00

2.8 KiB

Raw Blame History

name, description

name	description
wol-wake-sleeping-fleet-host	Wake a sleeping fleet host (e.g. the FrankBook-Pro Mac mini) over the network with a Wake-on-LAN magic packet, and diagnose why it silently fails.

Wake a sleeping fleet host over the network with a Wake-on-LAN (WoL) magic packet.

When

A fleet host is asleep (100% ping loss; ip neigh show <ip> shows STALE or FAILED) and you need it up — e.g. the Playwright e2e 11-admin spec needs the Mac mini, or a service on it is down. Recurring on the FrankBook-Pro Mac mini, which sleeps and breaks the e2e suite.

1. Find the MAC (the host is asleep, so you can't ask it)

ip neigh show <ip> — even a STALE entry carries the MAC. Fastest source.
Fallback: Pi-hole / dnsmasq leases, the DHCP server, or fleet docs.
Known: FrankBook-Pro Mac mini = 192.168.0.112, MAC de:6b:6d:c1:52:23.

2. Send the magic packet

Format: 6×0xFF + 16×MAC = 102 bytes, UDP to port 9 (and 7), broadcast.
The workstation has TWO interfaces on 192.168.0.0/24: a Wi-Fi link and a wired USB-Ethernet link (the default route, metric 100). A plain sendto("255.255.255.255", 9) leaves only the default-route interface. Bind explicitly to each interface's local IP and target the subnet broadcast 192.168.0.255 as well as 255.255.255.255.
wakeonlan is not installed; use a raw UDP socket with SO_BROADCAST=1.
Send a burst (~15 packets per interface, ~0.2s apart).

3. Poll for the wake

A Mac mini takes 30–90 s to boot after a WoL wake. Poll ping -c 1 -W 1 <ip> every 5 s for ~2–3 min before concluding failure.

4. If it does NOT wake (the common case) — diagnose the setting

macOS honors a WoL packet only when BOTH are enabled on the mini:

System Settings → Battery → Options → "Wake for network access" = ON, and
the active network port's "Enable Wake for LAN" (Network → [interface] → Details).

If either is off, no packet from any source wakes it, and you cannot change it while the host is asleep. A full power-off (smart plug cycled) also ignores WoL entirely. In that case: ask the user to toggle the setting (the durable fix so future wakes work), then re-fire the packet.

Reference sender (raw socket, per-interface)

import socket, time
MAC = "de:6b:6d:c1:52:23"
mac = bytes(int(x,16) for x in MAC.split(":"))
pkt = b"\xff"*6 + mac*16          # 102 bytes
for local, dest in [("192.168.0.83","192.168.0.255"),("192.168.0.104","192.168.0.255"),
                    ("192.168.0.83","255.255.255.255"),("192.168.0.104","255.255.255.255")]:
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    s.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
    s.bind((local, 0))
    for _ in range(15):
        s.sendto(pkt,(dest,9)); s.sendto(pkt,(dest,7)); time.sleep(0.2)
    s.close()

2.8 KiB Raw Blame History Unescape Escape