feat(remote): host-unreachable banner, manual wake, and native MAC wake-on-LAN

The reactive wake (typing into a session whose host slept) left the state invisible:
nothing told the user the machine was asleep, and with no wake target configured
there was nothing to do about it. Adds:

- RemoteHost.wakeMac (comma-separated) - Codeman builds and broadcasts the magic
  packet itself (UDP port 9), so the common case needs no external script. The
  existing wakeCommand stays as the explicit override.
- GET /api/sessions/:id/reachability - probes (throttled, cached, and it never
  wakes) and reports HOW the host can be woken, or that nothing is configured.
- POST /api/sessions/:id/wake - wakes, waits, reattaches the pane and flushes
  buffered input; 400 with a routable message when no target is configured.
- The amber host-unreachable banner + its 'Wake' / 'Configure WoL' action, and a
  small config dialog that saves via PUT /api/remote-hosts/:id.
- RemoteWakeDeps.resolveRemote: host config is re-resolved for LIVE sessions
  (throttled + cached), so saving the dialog takes effect without a restart.

src/web/public/app.js

@@ -221,7 +221,6 @@ const _SSE_HANDLER_MAP = [
   [SSE_EVENTS.REMOTE_RECONNECT_EXHAUSTED, '_onRemoteReconnectExhausted'],
   [SSE_EVENTS.REMOTE_HOST_WAKING, '_onRemoteHostWaking'],
   [SSE_EVENTS.REMOTE_HOST_WAKE_FAILED, '_onRemoteHostWakeFailed'],
-
   // Ralph
   [SSE_EVENTS.SESSION_RALPH_LOOP_UPDATE, '_onRalphLoopUpdate'],
   [SSE_EVENTS.SESSION_RALPH_TODO_UPDATE, '_onRalphTodoUpdate'],
@@ -6076,6 +6075,9 @@ class CodemanApp {
     // bar (issue #262). Also disarms a one-shot Ctrl left over from the tab we
     // just left, so it can never fire against the session we just opened.
     if (typeof KeyboardAccessoryBar !== 'undefined') KeyboardAccessoryBar.refreshForActiveSession();
+    // Remote-host reachability banner: only meaningful for a remote session, so this
+    // also clears it when the newly active tab is local.
+    this.refreshHostWakeBanner?.(sessionId);
 
     // Restore flushed offset AND text IMMEDIATELY so backspace/typing work during
     // the async buffer load.  Without this, the offset is 0 during the

src/web/public/host-wake-ui.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Remote-host wake-on-LAN: the "host unreachable" banner + its config dialog.
+ *
+ * A sleeping remote host does not fail loudly. The local tmux pane runs `ssh`, and when
+ * the machine suspends, that ssh child stalls: `tmux send-keys` still SUCCEEDS, so typed
+ * input disappears with no error and the pane looks alive. The server side
+ * (`src/remote-wake.ts`) buffers input and wakes the host when the user types; this
+ * module makes the state VISIBLE and gives it a button, which is what turns "why is
+ * nothing happening" into one click.
+ *
+ * Behavior:
+ *  - Polls `GET /api/sessions/:id/reachability` for the ACTIVE remote session only
+ *    (on tab activation and every `POLL_MS` while the tab is visible). The endpoint
+ *    shares the server's probe cache with the input path, so opening the tab also
+ *    primes the wake path.
+ *  - Unreachable + a configured wake target → "Wake" button → `POST /api/sessions/:id/wake`
+ *    (which wakes, waits, reattaches the pane and flushes buffered input).
+ *  - Unreachable + NO wake target → "Configure WoL" → `#wakeConfigModal`, a small form
+ *    for this host's MAC/command that saves via `PUT /api/remote-hosts/:id`. The server
+ *    re-resolves host config while the session is live, so saving takes effect without
+ *    restarting the session.
+ *  - SSE (`remote:hostWaking`, `remote:hostWakeFailed`, `remote:sessionReconnected`)
+ *    keeps the banner in sync while a wake is running.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ */
+
+const HOST_WAKE_POLL_MS = 30_000;
+
+Object.assign(CodemanApp.prototype, {
+  /** Per-tab banner state (single active session at a time). */
+  _hostWake: null,
+
+  /** Fresh state for a session we just switched to. */
+  _hostWakeState() {
+    return {
+      sessionId: null,
+      timer: null,
+      /** Last reachability answer, or null before the first poll. */
+      reachable: null,
+      /** 'command' | 'mac' | 'none' — what the banner action should do. */
+      wakeConfigured: 'none',
+      host: '',
+      label: '',
+      /** True between clicking Wake and the answer coming back. */
+      waking: false,
+      /** Set when the last wake attempt or poll failed. */
+      error: '',
+    };
+  },
+
+  /**
+   * Entry point from the session switcher — called for every active session, remote or
+   * not, so it must be cheap and must clear the banner for local sessions.
+   */
+  refreshHostWakeBanner(sessionId) {
+    const state = (this._hostWake = this._hostWakeState());
+    if (state.timer) clearInterval(state.timer);
+    state.sessionId = sessionId || null;
+
+    const session = sessionId && this.sessions ? this.sessions.get(sessionId) : null;
+    if (!session || !session.remote) {
+      this._renderHostWakeBanner();
+      return;
+    }
+
+    state.host = session.remote.host || '';
+    state.label = session.remote.label || 'Remote host';
+    // Text from the session payload first (instant, no round trip), corrected by the
+    // poll — a session whose wake config was added after launch only knows it after
+    // the server resolves host config.
+    state.wakeConfigured = session.remote.wakeMac || session.remote.wakeCommand ? 'mac' : 'none';
+    this._renderHostWakeBanner();
+
+    this._pollHostReachability();
+    if (state.timer) clearInterval(state.timer);
+    state.timer = setInterval(() => {
+      if (document.visibilityState === 'hidden') return;
+      if (this.activeSessionId !== state.sessionId) return;
+      this._pollHostReachability();
+    }, HOST_WAKE_POLL_MS);
+  },
+
+  /** One reachability check for the active remote session. */
+  async _pollHostReachability(force = false) {
+    const state = this._hostWake;
+    if (!state || !state.sessionId) return;
+    const sessionId = state.sessionId;
+    try {
+      const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/reachability${force ? '?force=1' : ''}`);
+      const data = await res.json();
+      if (!data.success) return;
+      // The tab may have changed while this was in flight.
+      if (this._hostWake !== state || state.sessionId !== sessionId) return;
+      state.reachable = data.data.reachable !== false;
+      state.wakeConfigured = data.data.wakeConfigured || 'none';
+      if (data.data.host) state.host = data.data.host;
+      if (data.data.label) state.label = data.data.label;
+      if (state.reachable) {
+        state.waking = false;
+        state.error = '';
+      }
+      this._renderHostWakeBanner();
+    } catch {
+      /* A failed poll is not a state change: leave the banner as it was. */
+    }
+  },
+
+  /** Draw the banner from `_hostWake`. */
+  _renderHostWakeBanner() {
+    const state = this._hostWake;
+    const banner = this.$('hostWakeBanner');
+    const text = this.$('hostWakeBannerText');
+    const detail = this.$('hostWakeBannerDetail');
+    const action = this.$('hostWakeBannerAction');
+    if (!banner || !text || !action) return;
+
+    const visible = Boolean(state && state.sessionId && state.reachable === false);
+    banner.hidden = !visible;
+    if (!visible) return;
+
+    const hasTarget = state.wakeConfigured !== 'none';
+    const target = state.label || state.host || 'Remote host';
+    if (state.waking) {
+      text.textContent = `Waking ${target} …`;
+    } else if (state.error) {
+      text.textContent = `${target} did not wake up`;
+    } else {
+      text.textContent = `${target} is not reachable`;
+    }
+    if (detail) {
+      detail.textContent = state.waking
+        ? 'input is queued until it is back'
+        : hasTarget
+          ? `ssh ${state.host}`
+          : 'no wake-on-LAN configured';
+    }
+    action.textContent = state.waking ? 'Waking …' : hasTarget ? 'Wake' : 'Configure WoL';
+    action.disabled = state.waking;
+  },
+
+  /** Banner button: wake the host, or open the setup dialog when nothing is configured. */
+  hostWakeAction() {
+    const state = this._hostWake;
+    if (!state || !state.sessionId || state.waking) return;
+    if (state.wakeConfigured === 'none') {
+      this.openWakeConfigDialog();
+      return;
+    }
+    this.wakeRemoteHost();
+  },
+
+  /** POST the manual wake for the active session and follow the result. */
+  async wakeRemoteHost() {
+    const state = this._hostWake;
+    if (!state || !state.sessionId) return;
+    const sessionId = state.sessionId;
+    state.waking = true;
+    state.error = '';
+    this._renderHostWakeBanner();
+    try {
+      const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/wake`, { method: 'POST' });
+      const data = await res.json();
+      if (this._hostWake !== state || state.sessionId !== sessionId) return;
+      state.waking = false;
+      if (!data.success) {
+        // Most likely: no wake target configured after all (the route is the authority).
+        state.error = data.error || 'Wake failed';
+        if (String(data.error || '').includes('No wake-on-LAN target')) state.wakeConfigured = 'none';
+        this._renderHostWakeBanner();
+        return;
+      }
+      state.reachable = data.data.reachable !== false;
+      state.wakeConfigured = data.data.wakeConfigured || state.wakeConfigured;
+      if (state.reachable) {
+        this.showToast(`${state.label || 'Remote host'} is awake`, 'success');
+      } else {
+        state.error = 'timeout';
+      }
+      this._renderHostWakeBanner();
+    } catch (err) {
+      if (this._hostWake !== state) return;
+      state.waking = false;
+      state.error = err && err.message ? err.message : 'Wake failed';
+      this._renderHostWakeBanner();
+    }
+  },
+
+  /** Open the small WoL dialog for the banner's host, pre-filled from the host config. */
+  async openWakeConfigDialog() {
+    const state = this._hostWake;
+    const session = state && state.sessionId && this.sessions ? this.sessions.get(state.sessionId) : null;
+    if (!session || !session.remote) return;
+    const hostId = session.remote.hostId;
+    const label = this.$('wakeConfigHostLabel');
+    const mac = this.$('wakeConfigMac');
+    const command = this.$('wakeConfigCommand');
+    const status = this.$('wakeConfigStatus');
+    if (!mac || !command) return;
+
+    mac.value = session.remote.wakeMac || '';
+    command.value = session.remote.wakeCommand || '';
+    if (label) label.textContent = session.remote.label || hostId;
+    if (status) status.textContent = '';
+    this._wakeConfigHostId = hostId;
+    const modal = this.$('wakeConfigModal');
+    if (modal) modal.classList.add('active');
+
+    // Read the saved host so the dialog shows what is actually persisted (the session
+    // payload may predate a change made in another tab).
+    try {
+      const res = await fetch('/api/remote-hosts');
+      const data = await res.json();
+      const hosts = data.success ? data.data : [];
+      const host = Array.isArray(hosts) ? hosts.find((item) => item.id === hostId) : null;
+      if (host && this._wakeConfigHostId === hostId) {
+        mac.value = host.wakeMac || '';
+        command.value = host.wakeCommand || '';
+      }
+    } catch {
+      /* The form is already usable from the session payload. */
+    }
+  },
+
+  closeWakeConfigDialog() {
+    const modal = this.$('wakeConfigModal');
+    if (modal) modal.classList.remove('active');
+    this._wakeConfigHostId = null;
+  },
+
+  /** Save MAC/command for the host, then re-check whether the session can wake now. */
+  async saveWakeConfig() {
+    const hostId = this._wakeConfigHostId;
+    const mac = this.$('wakeConfigMac');
+    const command = this.$('wakeConfigCommand');
+    const status = this.$('wakeConfigStatus');
+    const save = this.$('wakeConfigSave');
+    if (!hostId || !mac || !command) return;
+
+    const macValue = mac.value.trim();
+    const commandValue = command.value.trim();
+    if (
+      macValue &&
+      !/^[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5}(\s*,\s*[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5})*$/.test(macValue)
+    ) {
+      if (status) status.textContent = 'MAC must look like 04:d9:f5:80:c6:58 (comma-separated for several).';
+      return;
+    }
+    if (commandValue && /\s/.test(commandValue)) {
+      if (status) status.textContent = 'The wake command must be a single executable path (no arguments).';
+      return;
+    }
+
+    if (save) save.disabled = true;
+    if (status) status.textContent = 'Saving …';
+    try {
+      const listRes = await fetch('/api/remote-hosts');
+      const listData = await listRes.json();
+      const hosts = listData.success ? listData.data : [];
+      const host = Array.isArray(hosts) ? hosts.find((item) => item.id === hostId) : null;
+      if (!host) throw new Error('Remote host not found');
+      // PUT takes the whole host (schema-validated), so send back everything we know and
+      // only replace the wake fields. `undefined` drops the key entirely.
+      const payload = {
+        ...host,
+        wakeMac: macValue || undefined,
+        wakeCommand: commandValue || undefined,
+      };
+      const res = await fetch(`/api/remote-hosts/${encodeURIComponent(hostId)}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Save failed');
+      this.showToast('Wake settings saved', 'success');
+      this.closeWakeConfigDialog();
+      // The server re-resolves host config for live sessions, so the banner can offer
+      // the wake right away — probe fresh instead of waiting out the poll interval.
+      await this._pollHostReachability(true);
+    } catch (err) {
+      if (status) status.textContent = err && err.message ? err.message : 'Save failed';
+    } finally {
+      if (save) save.disabled = false;
+    }
+  },
+
+  /** SSE `remote:hostWaking` — a wake is running (ours or one started by typing). */
+  _onRemoteHostWaking(data) {
+    const state = this._hostWake;
+    if (!state || !data || state.sessionId !== data.sessionId) return;
+    state.waking = true;
+    state.error = '';
+    if (data.label) state.label = data.label;
+    this._renderHostWakeBanner();
+  },
+
+  /** SSE `remote:hostWakeFailed` — the host did not come back in time. */
+  _onRemoteHostWakeFailed(data) {
+    const state = this._hostWake;
+    if (!state || !data || state.sessionId !== data.sessionId) return;
+    state.waking = false;
+    state.error = 'timeout';
+    state.reachable = false;
+    this._renderHostWakeBanner();
+  },
+});

src/web/public/index.html

@@ -213,6 +213,18 @@
       <button class="offline-banner-retry" id="offlineBannerRetry" onclick="app.retryConnection()">Retry now</button>
     </div>
 
+    <!-- Remote-host unreachable: the machine SLEEPS, the local ssh pane stalls
+         silently (send-keys succeeds against it, so typed input would vanish) and
+         Codeman can wake it. Amber, not red: the session is fine, the host is
+         asleep. Without a configured wake target the action becomes "Configure
+         WoL" and opens the small config dialog. -->
+    <div class="offline-banner host-wake-banner" id="hostWakeBanner" role="status" hidden>
+      <span class="offline-banner-dot" aria-hidden="true"></span>
+      <span class="offline-banner-text" id="hostWakeBannerText">Remote host is unreachable</span>
+      <span class="offline-banner-detail" id="hostWakeBannerDetail"></span>
+      <button class="offline-banner-retry" id="hostWakeBannerAction" onclick="app.hostWakeAction()">Wake</button>
+    </div>
+
     <!-- Timer Banner (shown when timed run is active) -->
     <div class="timer-banner" id="timerBanner" style="display: none;">
       <div class="timer-content">
@@ -2853,6 +2865,11 @@
               <input type="number" id="remoteHostPort" placeholder="22" min="1" max="65535" autocomplete="off">
               <span class="form-hint">Optional. Leave blank for the default port 22.</span>
             </div>
+            <div class="form-row">
+              <label>Wake-on-LAN MAC</label>
+              <input type="text" id="remoteHostWakeMac" placeholder="04:d9:f5:80:c6:58" autocomplete="off" autocapitalize="off" spellcheck="false">
+              <span class="form-hint">Optional. Comma-separated for several NICs. Codeman sends the magic packet itself so a sleeping host can be woken from the session banner.</span>
+            </div>
             <div class="form-row">
               <label>Codex Command Override</label>
               <input type="text" id="remoteHostCodexCommand" placeholder="exec codx personal" autocomplete="off" autocapitalize="off" spellcheck="false">
@@ -2861,6 +2878,11 @@
             <details class="advanced-options">
               <summary><svg class="set-adv-chev" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg><span>Advanced SSH</span></summary>
               <div class="advanced-options-content">
+                <div class="form-row">
+                  <label>Wake Command</label>
+                  <input type="text" id="remoteHostWakeCommand" placeholder="/home/user/bin/wake-this-host" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+                  <span class="form-hint">Optional override for the MAC above (takes precedence). A single executable path, run without a shell — use it when the host needs a router/other machine to send the packet.</span>
+                </div>
                 <div class="form-row">
                   <label>Identity File</label>
                   <input type="text" id="remoteHostIdentityFile" placeholder="~/.ssh/remote_ed25519" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
@@ -3456,6 +3478,36 @@
        text is set via value/textContent only: predictor output derives from
        observable (injectable) content, and the explicit click here is the
        security boundary (nothing is ever auto-sent). -->
+  <!-- Wake-on-LAN setup for a remote host whose session cannot be woken yet. Kept
+       deliberately small (host is fixed, only the wake fields are editable) so it can
+       be opened from the banner with one click. Persists via PUT /api/remote-hosts/:id. -->
+  <div class="modal" id="wakeConfigModal">
+    <div class="modal-backdrop" onclick="app.closeWakeConfigDialog()"></div>
+    <div class="modal-content">
+      <div class="modal-header">
+        <h3>Wake-on-LAN &middot; <span id="wakeConfigHostLabel"></span></h3>
+        <button class="modal-close" onclick="app.closeWakeConfigDialog()" aria-label="Close">&times;</button>
+      </div>
+      <div class="modal-body">
+        <div class="form-row">
+          <label>MAC address(es)</label>
+          <input type="text" id="wakeConfigMac" placeholder="04:d9:f5:80:c6:58" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+          <span class="form-hint">Comma-separated for several NICs. Codeman sends the magic packet itself (UDP port 9, broadcast).</span>
+        </div>
+        <div class="form-row">
+          <label>Wake command (optional)</label>
+          <input type="text" id="wakeConfigCommand" placeholder="/home/user/bin/wake-this-host" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+          <span class="form-hint">Takes precedence over the MAC. A single executable path, run without a shell.</span>
+        </div>
+        <div class="form-hint" id="wakeConfigStatus"></div>
+      </div>
+      <div class="modal-footer">
+        <button class="btn-toolbar" onclick="app.closeWakeConfigDialog()">Cancel</button>
+        <button class="btn-toolbar btn-primary" id="wakeConfigSave" onclick="app.saveWakeConfig()">Save</button>
+      </div>
+    </div>
+  </div>
+
   <div class="modal" id="readMyMindModal">
     <div class="modal-backdrop" onclick="app.closeReadMyMind()"></div>
     <div class="modal-content readmymind-modal">
@@ -3530,6 +3582,7 @@
   <script defer src="approvals-ui.js"></script>
   <script defer src="admin-ui.js"></script>
   <script defer src="session-ui.js"></script>
+  <script defer src="host-wake-ui.js"></script>
   <script defer src="webview-tabs.js"></script>
   <script defer src="mobile-overview.js"></script>
   <script defer src="home-sessions.js"></script>

src/web/public/panels-ui.js

@@ -92,6 +92,9 @@ Object.assign(CodemanApp.prototype, {
   _onRemoteSessionReconnected(data) {
     const id = this.getShortId(data.sessionId);
     this.showToast(`Remote session ${id} reconnected`, 'success');
+    // A successful reattach (the wake flow's own, or the watcher's) means the host is
+    // back: drop the "unreachable" banner without waiting out the poll interval.
+    if (this.activeSessionId === data.sessionId) this._pollHostReachability?.(true);
   },
 
   _onRemoteReconnectExhausted(data) {

src/web/public/session-ui.js

@@ -3071,6 +3071,9 @@ Object.assign(CodemanApp.prototype, {
     const identityFile = document.getElementById('remoteHostIdentityFile').value.trim();
     const socksProxy = document.getElementById('remoteHostSocksProxy').value.trim();
     const jumpHost = document.getElementById('remoteHostJumpHost').value.trim();
+    // Wake-on-LAN: keep in sync with `_readRemoteHostFromForm` (the Discover path).
+    const wakeMac = document.getElementById('remoteHostWakeMac').value.trim();
+    const wakeCommand = document.getElementById('remoteHostWakeCommand').value.trim();
     const extraSshOptions = document.getElementById('remoteHostExtraSshOptions').value
       .split('\n')
       .map(line => line.trim())
@@ -3108,6 +3111,8 @@ Object.assign(CodemanApp.prototype, {
         ...(socksProxy ? { socksProxy } : {}),
         ...(jumpHost ? { jumpHost } : {}),
         ...(extraSshOptions.length ? { extraSshOptions } : {}),
+        ...(wakeMac ? { wakeMac } : {}),
+        ...(wakeCommand ? { wakeCommand } : {}),
         ...(codexCommand ? { commands: { codex: codexCommand } } : {}),
       };
       const hostRes = await fetch('/api/remote-hosts', {
@@ -3568,6 +3573,9 @@ Object.assign(CodemanApp.prototype, {
     const socksProxy = document.getElementById('remoteHostSocksProxy').value.trim();
     const jumpHost = document.getElementById('remoteHostJumpHost').value.trim();
     const codexCommand = document.getElementById('remoteHostCodexCommand').value.trim();
+    // Wake-on-LAN: keep in sync with `linkRemoteCase`'s inline payload.
+    const wakeMac = document.getElementById('remoteHostWakeMac').value.trim();
+    const wakeCommand = document.getElementById('remoteHostWakeCommand').value.trim();
     const extraSshOptions = document.getElementById('remoteHostExtraSshOptions').value
       .split('\n')
       .map(line => line.trim())
@@ -3587,6 +3595,8 @@ Object.assign(CodemanApp.prototype, {
       ...(socksProxy ? { socksProxy } : {}),
       ...(jumpHost ? { jumpHost } : {}),
       ...(extraSshOptions.length ? { extraSshOptions } : {}),
+      ...(wakeMac ? { wakeMac } : {}),
+      ...(wakeCommand ? { wakeCommand } : {}),
       ...(codexCommand ? { commands: { codex: codexCommand } } : {}),
     };
   },

src/web/public/styles.css

@@ -15306,6 +15306,18 @@ html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
   background: rgba(255, 255, 255, 0.24);
 }
 
+/* Remote-host unreachable (host asleep, can be woken). Reuses the offline-banner
+   layout and children; amber instead of red because the Codeman session itself is
+   perfectly healthy — only the machine is asleep. */
+.host-wake-banner {
+  background: linear-gradient(90deg, #b45309, #92400e);
+}
+
+.host-wake-banner .offline-banner-retry:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
 /* Above the mobile fixed header (1200) and modals (1300): this is a blocking
    "nothing works right now" state, and it only appears before any session
    state has loaded, so there is no modal underneath to bury. Stays below the

src/web/routes/session-routes.ts

@@ -134,6 +134,7 @@ import {
   checkRemoteTmuxAvailable,
   readRemoteCases,
   readRemoteHosts,
+  rehydrateRemoteHostFields,
   toAttachedSessionRemote,
   toSessionRemote,
 } from '../../remote-hosts.js';
@@ -841,6 +842,16 @@ export function registerSessionRoutes(
         },
         broadcast: (event, payload) => ctx.broadcast(event, payload),
         log: (message) => console.log(message),
+        // The session's `remote` block is a launch-time snapshot, so a wake target
+        // configured later (banner's config dialog, or a hand-edited remote-hosts.json)
+        // is resolved here — throttled by the registry, and only for sessions that
+        // have no usable target of their own.
+        resolveRemote: async (session) => {
+          const remote = session.remote;
+          if (!remote) return undefined;
+          const hosts = await readRemoteHosts(CODEMAN_CONFIG_DIR);
+          return rehydrateRemoteHostFields(remote, new Map(hosts.map((host) => [host.id, host])));
+        },
       })
     );
   // ═══════════════════════════════════════════════════════════════
@@ -1541,6 +1552,56 @@ export function registerSessionRoutes(
   // Terminal I/O (input, resize, buffer)
   // ═══════════════════════════════════════════════════════════════
 
+  // ========== Wake-on-LAN: state + manual trigger ==========
+  //
+  // Both routes are session-scoped (not host-scoped) because the wake flow needs the
+  // SESSION: a woken host whose pane is not reattached is still a dead terminal, and an
+  // exhausted COD-108 backoff never retries on its own. The probe in `/reachability` is
+  // the same cheap TCP connect the input path uses and it NEVER wakes a host — the UI
+  // decides that, with the button.
+
+  app.get('/api/sessions/:id/reachability', async (req) => {
+    const { id } = req.params as { id: string };
+    const session = findSessionOrFail(ctx, id, req);
+    const remote = session.remote;
+    if (!remote) return { success: true, data: { reachable: true, wakeConfigured: 'none' as const } };
+    const force = (req.query as { force?: string })?.force === '1';
+    const reachable = await remoteWake.checkReachable(session, { force });
+    return {
+      success: true,
+      data: {
+        reachable,
+        wakeConfigured: await remoteWake.wakeConfigured(session),
+        host: remote.host,
+        label: remote.label,
+      },
+    };
+  });
+
+  app.post('/api/sessions/:id/wake', async (req) => {
+    const { id } = req.params as { id: string };
+    const session = findSessionOrFail(ctx, id, req);
+    if (!session.remote) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Not a remote session');
+    }
+    // The UI uses this to route to the host config dialog instead of a dead button.
+    if (!(await remoteWake.hasWakeTarget(session))) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'No wake-on-LAN target configured for this host (set a MAC address or a wake command)'
+      );
+    }
+    const woke = await remoteWake.ensureAwake(session, { force: true });
+    return {
+      success: true,
+      data: {
+        woke,
+        reachable: await remoteWake.checkReachable(session),
+        wakeConfigured: await remoteWake.wakeConfigured(session),
+      },
+    };
+  });
+
   // ========== Send Input ==========
 
   app.post('/api/sessions/:id/input', async (req, reply) => {
@@ -1591,7 +1652,7 @@ export function registerSessionRoutes(
     // known reachable inside the probe throttle window; the probe itself is a bare
     // TCP connect on wake-enabled hosts only, at most once per
     // REMOTE_WAKE_PROBE_MIN_INTERVAL_MS.
-    if (!duplicate && session.remote?.wakeCommand) {
+    if (!duplicate && (await remoteWake.hasWakeTarget(session))) {
       if (wantsWait) {
         // Send-and-wait keeps the response open anyway, so blocking on the wake is
         // simpler and more correct than buffering (buffering would break the wait).

src/web/schemas.ts

@@ -749,6 +749,18 @@ export const RemoteHostSchema = z.object({
     .regex(/^\S+$/, 'Wake command must be a single executable path (no arguments)')
     .regex(NO_SHELL_META, 'Invalid characters in wake command')
     .optional(),
+  // Wake-on-LAN MAC address(es), comma-separated. Structural: only hex pairs with
+  // `:`/`-` separators, so nothing here can be a shell token even by accident (the
+  // value never reaches a shell — Codeman builds the magic packet itself).
+  wakeMac: z
+    .string()
+    .min(11)
+    .max(128)
+    .regex(
+      /^[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5}(\s*,\s*[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5})*$/,
+      'Wake MAC must be one or more MAC addresses, comma-separated'
+    )
+    .optional(),
 });
 
 export const RemoteCaseLinkSchema = z.object({