feat(remote): wake a sleeping host (Wake-on-LAN) from input, banner and native magic packet

[Randalix]

What this does

Adds Wake-on-LAN for remote (SSH) sessions, so a sleeping host can be woken instead of silently swallowing input.

A remote host is armed by either of two RemoteHost fields in remote-hosts.json:

• wakeMac (new, the normal case) — a comma-separated MAC list. Codeman builds and sends the magic packet itself over dgram (UDP 9, broadcast), dependency-free.
• wakeCommand (kept) — a single executable path, run without a shell (spawn(command, [], { stdio: 'ignore' })), for waking via a router, another machine, or a script. It takes precedence over wakeMac when both are set.

Two triggers, both gated on a real user action:

• Input — POST /api/sessions/:id/input probes the host (bare TCP connect, throttled to one probe per 30 s per session, wake-enabled hosts only) and, if it is down, wakes it, calls reattachRemote(), and flushes buffered input in order.
• Banner — an amber "host not reachable" banner with a Wake button, backed by GET /api/sessions/:id/reachability (probe only, never wakes) and POST /api/sessions/:id/wake. With no wake target configured, the button opens the existing host-config dialog pre-filled for that host.

Closes #433.

The two invariants

#1 — only user input or an explicit wake request may wake a host. The auto-reconnect watcher (COD-108), handleRemoteSessionDropped and boot recovery have no access to the registry. A wake there would re-wake the host seconds after every suspend, so it could never stay asleep — a worse bug than the one this fixes. This is asserted as a wiring guard (a src/ scan in test/remote-wake.test.ts), not a comment. GET …/reachability probes and never wakes (regression test: probe a sleeping fake host → the wake spy stays empty).

#2 — no ServerAliveInterval. Keepalives would move bytes into an otherwise idle connection every interval, which is exactly what the byte-threshold idle detector on the sleeping host must not read as activity. The probe (~200 B / 30 s) sits far below it and cannot wake anyone by SYN. The reasoning paragraph lives in docs/architecture-invariants.md, where you asked for it, so the next person does not "fix" the stalled pane by adding keepalives.

wakeCommand gating

The config dialog writes through PUT /api/remote-hosts/:id, which is already admin-only in multi-user mode (adminOnly, case-routes.ts:682) — same as the rest of the host config — so a non-admin cannot name an executable for the server to run. The schema accepts a single executable path only (no arguments, no $/backticks), and it is spawned with shell: false.

Pending buffer

• Bounded at 4 KB per session, drop-oldest, with a log line ([RemoteWake] pending buffer cap reached for session … — oldest input dropped). Keeping the tail preserves what the user just typed; a silently unbounded buffer keyed on user input would be a memory leak.
• Memory-only. It lives in the per-session registry state and goes away with the session — nothing is persisted. So if the wake fails and the host stays down, the keystrokes are held for the life of that session and then discarded. (Dropping them immediately was also defensible; this is the one I chose, so it is spelled out rather than left to inference.)
• If a flush write fails part-way, the remaining chunks are retained in the same in-memory buffer, not dropped.
• Send-and-wait blocks on the wake instead of buffering, because buffering would break the wait contract.

The dgram finding (in the code, not just the commit message)

setBroadcast() on an unbound socket throws EBADF on Linux, the following send fails with EACCES, and the function reports success — the magic packet never left the machine and it looked like "the host just did not come back". The order is load-bearing, so the broadcast flag is set inside the bind callback, with a ⚠️ comment at the call site (src/remote-wake.ts). The socket is injectable so a test asserts the bind → setBroadcast order (a real UDP broadcast in CI would be unwelcome). This is the bug the live test caught; unit tests with mocks would never have found it.

Testing

• New: test/remote-wake.test.ts (decision table, single-flight, buffer order + drop-oldest, wiring guard, socket order), test/routes/session-remote-wake.test.ts (route behavior), test/sse-dispatch-table.test.ts (frontend SSE dispatch guard).
• Extended: test/remote-hosts.test.ts (schema + rehydration), test/mocks/mock-session.ts.
• tsc --noEmit, eslint, prettier, check:frontend-syntax, check:public-assets — clean.
• Full npm test: 7303 passed, 15 skipped.
• Live against a real sleeping machine: the magic packet brought the host back over SSH in ~9 s; POST /api/sessions/:id/wake returned {woke:true, reachable:true} in 12 s including reattach, and the durable remote tmux session — and the agent conversation — survived the suspend. The banner was verified in a real browser (appears, Wake → "Waking…" → gone in 10.0 s, no console errors).

test/quick-start.test.ts is red in my environment only: it binds 127.0.0.1:3100, which a local Docker container already holds (EADDRINUSE). Unrelated to this change — the port comes from TEST_PORT + 1 off 3099, which is why grepping the file for 3100 finds nothing. Flagging it in case the suite is not fully green for you either.

Review pass over the branch (commit 8dfc965d) found and fixed two things, both worth knowing since they are the silent-failure kind:

• _onRemoteHostWaking / _onRemoteHostWakeFailed were defined in two frontend modules (panels-ui.js for the toast, host-wake-ui.js for the banner). Both mix into CodemanApp.prototype and host-wake-ui.js loads later, so the toast copy was silently shadowed — and a wake for a background session produced no notification at all. The handlers now live only in host-wake-ui.js.
• appendBoundedPending dropped only whole chunks, so a single input value over the cap (one large paste is one input, up to 100 KB by the input schema) was kept in full — "bounded at 4 KB" held per chunk, not per session. The surviving chunk's head is now trimmed, code-point aware.

Both now have a guard: every SSE dispatch handler must be defined in exactly one module (the existing test only asserted one exists somewhere), and a test asserts a single oversized chunk is trimmed rather than kept.

No changeset, per your note.

[Randalix]

One more wake path — asking before I push it

I have one more commit for this branch (d0a5a583) and have not pushed it, since the PR is with you now. It is the same feature, so my instinct is that it belongs here rather than in a second PR — but it changes the behaviour of two existing routes, which is not something I want to slide in mid-review. Say the word and I push it; say "not now" and it stays local.

The gap

Waking was reachable from input and from the banner button, but not from opening a session — which is the moment you actually decide to use that host. POST /api/quick-start resolves a remote case and then probes tmux (checkRemoteTmuxAvailable), and on a suspended host that probe fails over ssh:

OPERATION_FAILED: could not verify tmux on remote host 192.168.50.137: ssh: connect to host …

i.e. an error that blames tmux for a machine that is merely asleep, with nothing in the log. POST /api/sessions + attachRemoteSession had no wake path at all.

What the commit does

• RemoteWakeRegistry.ensureHostAwake() runs the existing probe → wake → wait-for-readiness machinery for a host that has no session yet (host-scoped state, single-flight per host, so a double click or two cases on one host send one packet), plus checkHostReachable(), which only asks and never wakes.
• Wired into those two user-initiated routes only, and deliberately not in the shared session service: cron-service.ts creates sessions there with nobody waiting on the answer, so a wake on that path would power the host on for every schedule — the timer-driven re-wake invariant feat: add HTTP Basic Auth for web interface security #1 exists to prevent. Kept as wiring rather than prose: only session-routes.ts may import remote-wake, and ensureHostAwake has exactly one caller file (test/remote-wake.test.ts, which also keeps the existing importers guard). A rejection from the wake IO is caught, so a broken target fails the wake and not the route.
• A host with no wake target is not probed at all — 'no-target' returns before the first TCP connect, so its behaviour and latency are byte-identical to before.
• Blocking, with its own budget: 40 s (REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS) rather than the 90 s session default. The deployment this was built against serves the dashboard through a reverse proxy whose default proxy_read_timeout is 60 s, so a longer wait is cut off at the proxy while the session is still being created — the browser reports a failure for a session that exists. 40 s + 1.5 s probe + the tmux probe's own 15 s timeout = 56.5 s worst case, and a wake on this setup measures 9–12 s.
• Failure is honest now: a wake that does not come back says the host did not come back, and an unreachable host without a target says … is not reachable, and this host has no wake-on-LAN target instead of pointing at tmux. (Both branches are regression-tested.)
• remote:hostWaking / remote:hostWakeFailed carry a forNewSession flag in the session-less case, where the existing toast text ("input is queued") would be untrue — it reads "the session starts when it is back".
• Docs in the same commit: docs/remote-sessions.md §Wake-on-LAN and docs/architecture-invariants.md. The invariant wording had to move from "only real user input or an explicit wake request may wake a host" to "an explicit request — input, the wake button, or the user's own create/attach — and never a timer, probe or list path", with cron-service.ts named as the reason the create wake lives in the route.

Verification

	before	now
quick-start on a remote case, host suspended	aborted with the tmux error	session created and attached in 9 s
second run, host awake	—	no wake, 2 s
attachRemoteSession, host awake	no wake path	attaches, no wake

Test sessions were deleted afterwards, and the remote tmux sessions with them (an attempt against a discovered, non-owned session detaches and leaves it alone).

npm test: 7316 passed, 15 skipped. Same environmental test/quick-start.test.ts red as before (127.0.0.1:3100 is held by an unrelated container here), plus one boundary flake in test/qr-auth.test.ts on the exact 90 s grace boundary that is green in isolation — flagging both rather than reporting a clean run.

No changeset, same as before.