Merge pull request #439

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

src/remote-hosts.ts

@@ -540,6 +540,32 @@ export function remoteDisplayPath(
   return `${remote.username}@${remote.host}:${path}`;
 }
 
+/**
+ * Refresh HOST-level config on a RESTORED `SessionRemote`.
+ *
+ * A session's `remote` block is persisted at launch time (mux-sessions.json /
+ * state.json) and recovery uses that snapshot, so a field ADDED to the host config
+ * later never reaches an already-running session — not even across a Codeman
+ * restart. That is exactly how a `wakeCommand` added to `remote-hosts.json` would
+ * silently do nothing until the session is relaunched (which for an owned remote
+ * session means killing the remote tmux).
+ *
+ * Deliberately narrow: ONLY `wakeCommand`/`wakeMac` are taken from the host config,
+ * and the host is authoritative for them (removing one in the config turns that
+ * wake path off again). The other host-level fields (`commands`, ssh options) stay as
+ * persisted so this cannot silently change how an existing pane connects.
+ */
+export function rehydrateRemoteHostFields<T extends { hostId: string; wakeCommand?: string; wakeMac?: string }>(
+  remote: T | undefined,
+  hostsById: ReadonlyMap<string, RemoteHost>
+): T | undefined {
+  if (!remote) return remote;
+  const host = hostsById.get(remote.hostId);
+  if (!host) return remote;
+  if (remote.wakeCommand === host.wakeCommand && remote.wakeMac === host.wakeMac) return remote;
+  return { ...remote, wakeCommand: host.wakeCommand, wakeMac: host.wakeMac };
+}
+
 export function toSessionRemote(host: RemoteHost, remoteCase: RemoteCase): SessionRemote {
   return {
     hostId: host.id,
@@ -549,6 +575,10 @@ export function toSessionRemote(host: RemoteHost, remoteCase: RemoteCase): Sessi
     port: host.port,
     remotePath: remoteCase.remotePath,
     commands: host.commands,
+    // Wake-on-LAN command/MAC travel with the session so the input route can wake a
+    // sleeping host without a second config read (see remote-wake.ts).
+    wakeCommand: host.wakeCommand,
+    wakeMac: host.wakeMac,
     // COD-105 — the COD-104 launch path creates the remote session, so we own it
     // (an explicit kill may propagate a remote kill-session). Discovered+attached
     // sessions go through `toAttachedSessionRemote` with `owned: false`.
@@ -587,6 +617,10 @@ export function toAttachedSessionRemote(
     port: host.port,
     remotePath,
     commands: host.commands,
+    // An attached session can be woken exactly the same way — the identity of the
+    // creator does not change whether the host is asleep.
+    wakeCommand: host.wakeCommand,
+    wakeMac: host.wakeMac,
     // Discovered + attached — another Codeman created it. Detach-not-kill.
     owned: false,
     remoteSessionName,

src/types/session.ts

@@ -115,6 +115,25 @@ export interface RemoteHost extends RemoteSshOptions {
   username: string;
   port?: number;
   commands?: Partial<Record<RemoteCommandMode, string>>;
+  /**
+   * Optional Wake-on-LAN MAC address(es), comma-separated (e.g.
+   * `04:d9:f5:80:c6:58`). Codeman sends the magic packet itself (UDP port 9
+   * broadcast), so the common case needs no external script. A SLEEPING host's
+   * port-22 probe still fails, which is what triggers the wake — this only
+   * controls HOW the host is woken.
+   */
+  wakeMac?: string;
+  /**
+   * Optional Wake-on-LAN command that powers this host on from SLEEP (e.g. a
+   * wrapper script like `/home/joe/bin/whuff`). TAKES PRECEDENCE over `wakeMac`
+   * (an explicit override for hosts that need a router/other-host wake). Absent
+   * = no wake support and today's behavior exactly. Executed WITHOUT a shell (a
+   * single executable path, never a command line), only from user input or an
+   * explicit wake request on a session whose host is unreachable — never from
+   * the auto-reconnect/boot-recovery path, which would re-wake a host seconds
+   * after each suspend.
+   */
+  wakeCommand?: string;
 }
 
 export interface RemoteCase {
@@ -155,6 +174,13 @@ export interface SessionRemote extends RemoteSshOptions {
    * session was created elsewhere. Only meaningful when `owned === false`.
    */
   remoteSessionName?: string;
+  /**
+   * Wake-on-LAN command carried over from the host config (see `RemoteHost.wakeCommand`)
+   * so the input route can wake a sleeping host without re-reading the host list.
+   */
+  wakeCommand?: string;
+  /** Wake-on-LAN MAC address(es) from the host config (see `RemoteHost.wakeMac`). */
+  wakeMac?: string;
 }
 
 /**

src/web/public/app.js

@@ -219,7 +219,8 @@ const _SSE_HANDLER_MAP = [
   // Remote auto-reconnect (COD-108)
   [SSE_EVENTS.REMOTE_SESSION_RECONNECTED, '_onRemoteSessionReconnected'],
   [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'],
@@ -1824,6 +1825,9 @@ class CodemanApp {
   _onInit(data) {
     _crashDiag.log(`INIT: ${data.sessions?.length || 0} sessions`);
     this.handleInit(data);
+    // Start the remote-host reachability poller even if no session switch follows
+    // (a page loaded with the remote tab already active) — see host-wake-ui.js.
+    this._ensureHostWakePoller?.();
   }
 
   _onSessionCreated(data) {
@@ -6190,6 +6194,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/constants.js

@@ -1148,6 +1148,9 @@ const SSE_EVENTS = {
   REMOTE_SESSION_DROPPED: 'remote:sessionDropped',
   REMOTE_SESSION_RECONNECTED: 'remote:sessionReconnected',
   REMOTE_RECONNECT_EXHAUSTED: 'remote:reconnectExhausted',
+  // Wake-on-LAN from user input on a sleeping remote host
+  REMOTE_HOST_WAKING: 'remote:hostWaking',
+  REMOTE_HOST_WAKE_FAILED: 'remote:hostWakeFailed',
 
   // Ralph
   SESSION_RALPH_LOOP_UPDATE: 'session:ralphLoopUpdate',

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

@@ -0,0 +1,440 @@
+/**
+ * @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:
+ *  - Asks `GET /api/sessions/:id/reachability` for the ACTIVE remote session only:
+ *    once when the tab is activated (a user action), and every `POLL_MS` while the tab
+ *    is visible ONLY for a host with a wake target. The timer is the one thing here that
+ *    is not user-driven, and each poll is a TCP connect to the host — the same
+ *    timer-driven traffic invariant #2 rejects keepalives for: it cannot wake a host,
+ *    but it can keep an activity-based suspend timer from firing. So a host Codeman
+ *    could not wake anyway is never polled on a timer. A host behind a jump host or
+ *    SOCKS proxy (`probeable: false`) is never polled at all: the probe cannot reach
+ *    it, so its answer would only ever be a false "asleep". 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
+ * @dependency app.js (CodemanApp class, this.sessions, this.activeSessionId, showToast)
+ * @dependency constants.js (SSE_EVENTS — the remote:hostWaking / remote:hostWakeFailed names)
+ * @loadorder 12.2 — loaded after session-ui.js, before webview-tabs.js
+ */
+
+const HOST_WAKE_POLL_MS = 30_000;
+
+Object.assign(CodemanApp.prototype, {
+  /** Per-tab banner state (single active session at a time). */
+  _hostWake: null,
+  /** The page-wide poller interval (created once, see `_ensureHostWakePoller`). */
+  _hostWakeTimer: null,
+
+  /** Fresh state for a session we just switched to. */
+  _hostWakeState() {
+    return {
+      sessionId: 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: '',
+      /**
+       * False for a host the server's probe cannot reach (behind a jump host or SOCKS
+       * proxy): its reachability is unknown, so there is no banner and no polling.
+       */
+      probeable: true,
+      /** True between clicking Wake and the answer coming back. */
+      waking: false,
+      /**
+       * True only when the server is actually holding bytes for this session (the typing
+       * path buffers them). Browser keystrokes go over the WebSocket, which never passes
+       * through the wake registry — so the Wake BUTTON must not claim input is queued.
+       */
+      queuedInput: 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.
+   *
+   * ⚠️ The POLLER is page-wide and independent of this call on purpose: a session
+   * switch is not the only way the active tab changes (boot restore, a page loaded with
+   * the tab already active, and `selectSession`'s own early return for the tab you are
+   * already on), and the banner must not depend on any single one of those paths
+   * running — that is exactly how it could silently never appear.
+   */
+  refreshHostWakeBanner(sessionId) {
+    this._ensureHostWakePoller();
+    const state = this._hostWake;
+    if (state && state.sessionId && state.sessionId !== sessionId) this._hostWake = null;
+    this._hostWakeTick();
+  },
+
+  /** Create the page-wide poller once (interval + a visibility wake-up). */
+  _ensureHostWakePoller() {
+    if (this._hostWakeTimer) return;
+    this._hostWakeTimer = setInterval(() => this._hostWakeTick({ periodic: true }), HOST_WAKE_POLL_MS);
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'visible') this._hostWakeTick({ periodic: true });
+    });
+  },
+
+  /**
+   * One poller tick: resolve the ACTIVE session, reset the banner when it changed, and
+   * ask the server. No-op while the page is hidden (a background tab must not poll).
+   *
+   * `periodic` marks the timer (and the visibility wake-up) as opposed to a tab
+   * activation: a periodic tick polls only a host with a wake target, see the module
+   * comment. The activation poll is what still offers "Configure WoL" for a sleeping
+   * host that has none — one connect, on a user action.
+   */
+  _hostWakeTick({ periodic = false } = {}) {
+    if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
+    const sessionId = this.activeSessionId;
+    const session = sessionId && this.sessions ? this.sessions.get(sessionId) : null;
+    if (!sessionId || !session || !session.remote) {
+      // Render unconditionally: `refreshHostWakeBanner` clears `_hostWake` BEFORE
+      // calling this tick, so a guard here would skip the repaint and leave the
+      // banner up on every chat (the clear and the repaint must not be coupled to
+      // whoever cleared the state). Idempotent — with a null state it just hides.
+      this._hostWake = null;
+      this._renderHostWakeBanner();
+      return;
+    }
+    let state = this._hostWake;
+    let fresh = false;
+    if (!state || state.sessionId !== sessionId) {
+      fresh = true;
+      state = this._hostWake = this._hostWakeState();
+      state.sessionId = sessionId;
+      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. The kind matters: the payload can say WHICH
+      // path is configured, so a command-only host is not mislabelled 'mac' until the
+      // first poll lands.
+      state.wakeConfigured = session.remote.wakeMac ? 'mac' : session.remote.wakeCommand ? 'command' : 'none';
+      // Known from the payload already: a proxied host is not probeable (the server
+      // says so too, on every answer), so not even the activation poll is worth a
+      // round trip whose verdict could only be a wrong "asleep".
+      state.probeable = !(session.remote.jumpHost || session.remote.socksProxy);
+      this._renderHostWakeBanner();
+    }
+    if (!state.probeable) return;
+    if (periodic && !fresh && state.wakeConfigured === 'none') return;
+    this._pollHostReachability();
+  },
+
+  /** 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;
+      // `reachable` is `null` (unknown, not unreachable) for a host the probe cannot
+      // reach — only a PROVEN `false` may raise the banner.
+      state.reachable = data.data.reachable !== false;
+      if (data.data.probeable === false) state.probeable = 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
+        ? state.queuedInput
+          ? 'input is queued until it is back'
+          : 'waiting for the host to come back'
+        : hasTarget
+          ? `ssh ${state.host}`
+          : 'no wake-on-LAN configured';
+    }
+    // After a FAILED wake the only useful next step is fixing the target (wrong MAC,
+    // host moved NIC, command gone) — otherwise a configured-but-broken host would be
+    // stuck behind a button that keeps failing with no way to edit it.
+    const offerConfig = !hasTarget || Boolean(state.error);
+    action.textContent = state.waking ? 'Waking …' : offerConfig ? 'Configure WoL' : 'Wake';
+    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' || state.error) {
+      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;
+    // The button path holds nothing: whatever the user typed went into the stalled pane
+    // over the WebSocket and is gone. Saying otherwise is a promise the next keystroke
+    // disproves.
+    state.queuedInput = false;
+    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) {
+        // The ROUTE is the authority on whether a target is configured, so ask it again
+        // (`/reachability` reports `wakeConfigured`) rather than pattern-matching the
+        // error message: the message is prose, and the code is generic (`INVALID_INPUT`
+        // covers "Not a remote session" too).
+        state.error = data.error || 'Wake failed';
+        this._renderHostWakeBanner();
+        await this._pollHostReachability(true);
+        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();
+    }
+  },
+
+  /**
+   * Why the host could not be read. In multi-user mode `GET /api/remote-hosts` returns
+   * `[]` to a non-admin, so "Remote host not found" would blame a config the user simply
+   * is not allowed to see — the save is admin-only, and that is what it should say.
+   */
+  _wakeConfigUnavailableMessage() {
+    const me = window.__codemanUser || {};
+    return me.multiUser && me.role !== 'admin' ? 'Wake-on-LAN configuration is admin-only' : 'Remote host not found';
+  },
+
+  /** 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 || '';
+      } else if (!host && this._wakeConfigHostId === hostId && status) {
+        // Say it up front rather than only when Save fails.
+        status.textContent = this._wakeConfigUnavailableMessage();
+      }
+    } 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(this._wakeConfigUnavailableMessage());
+      // 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).
+   *
+   * ⚠️ The ONLY definition of this handler: `panels-ui.js` must not define it too.
+   * Both mix into `Codeman.prototype` and this file loads later, so a second copy
+   * would be silently shadowed (the guard in `sse-dispatch-table.test.ts` sees that a
+   * handler exists, not that two modules claim the same name). The toast is
+   * deliberately UNCONDITIONAL — a wake can start for a background session (input on
+   * a non-active tab) where there is no banner to update.
+   */
+  _onRemoteHostWaking(data) {
+    const label = data && data.label ? data.label : 'Remote host';
+    // A create-path wake (the user pressed Run / Attach) has no session yet, so
+    // nothing is queued behind it — the wording has to say what actually happens.
+    const forNewSession = Boolean(data && data.forNewSession);
+    // Only the typing path buffers bytes; the wake button and the send-and-wait path
+    // hold none, and a browser keystroke never reaches the registry at all.
+    const queuedInput = Boolean(data && data.queuedInput);
+    // Long enough to cover the wake + attach (~10s measured on a warm S3), and it
+    // is replaced by `remote:sessionReconnected` the moment the pane is back.
+    this.showToast(
+      forNewSession
+        ? `Waking ${label} … the session starts when it is back`
+        : queuedInput
+          ? `Waking ${label} … input is queued`
+          : `Waking ${label} … waiting for it to come back`,
+      'info',
+      { duration: 12000 }
+    );
+    const state = this._hostWake;
+    if (!state || !data || state.sessionId !== data.sessionId) return;
+    state.waking = true;
+    state.queuedInput = queuedInput;
+    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 label = data && data.label ? data.label : 'Remote host';
+    const forNewSession = Boolean(data && data.forNewSession);
+    const queuedInput = Boolean(data && data.queuedInput);
+    this.showToast(
+      forNewSession
+        ? `${label} did not wake up — no session was started`
+        : queuedInput
+          ? `${label} did not wake up — queued input is still held`
+          : `${label} did not wake up`,
+      'error',
+      { duration: 15000 }
+    );
+    const state = this._hostWake;
+    if (!state || !data || state.sessionId !== data.sessionId) return;
+    state.waking = false;
+    state.queuedInput = queuedInput;
+    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>
+
     <!-- Reboot-restore offer: shown when the server found sessions a host reboot
          killed and is asking whether to rebuild them. Populated by
          reboot-restore-ui.js; nothing is created until the user clicks. -->
@@ -2878,6 +2890,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">
@@ -2886,6 +2903,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">
@@ -3481,6 +3503,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">
@@ -3556,6 +3608,7 @@
   <script defer src="reboot-restore-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) {
@@ -116,6 +119,16 @@ Object.assign(CodemanApp.prototype, {
   },
 
 
+  // Wake-on-LAN from user input on a sleeping remote host (see remote-wake.ts).
+  // ⚠️ The `remote:hostWaking` / `remote:hostWakeFailed` HANDLERS live in
+  // `host-wake-ui.js`, which owns the banner state. They are NOT redefined here:
+  // both files mix into `CodemanApp.prototype` and `host-wake-ui.js` is loaded
+  // later, so a second definition would silently shadow the banner update (and the
+  // toast would never fire — the exact silent no-op `sse-dispatch-table.test.ts`
+  // exists to prevent, which cannot see shadowing). The toasts are shown from the
+  // host-wake-ui handlers instead.
+
+
   // Bash tools
   _onBashToolStart(data) {
     this.handleBashToolStart(data.sessionId, data.tool);

src/web/public/session-ui.js

@@ -2512,6 +2512,10 @@ Object.assign(CodemanApp.prototype, {
       'remoteHostSocksProxy',
       'remoteHostJumpHost',
       'remoteHostExtraSshOptions',
+      // Wake-on-LAN: they belong to the HOST being configured, so leaving them filled in
+      // would carry one host's MAC/command onto the next host this form saves.
+      'remoteHostWakeMac',
+      'remoteHostWakeCommand',
     ];
     remoteFields.forEach(id => {
       const el = document.getElementById(id);
@@ -3109,6 +3113,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())
@@ -3146,6 +3153,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', {
@@ -3606,6 +3615,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())
@@ -3625,6 +3637,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

@@ -15389,6 +15389,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

@@ -28,6 +28,7 @@ import {
   type GrokConfig,
   type DeepSeekConfig,
   type OmpConfig,
+  type RemoteHost,
 } from '../../types.js';
 import { Session, isAltScreenStripMode, isExternalCliMode, isMuxAltScreenOnlyStripMode } from '../../session.js';
 import type { PaneCaptureOptions } from '../../mux-interface.js';
@@ -68,6 +69,13 @@ import {
   type WaitSignal,
   type SignalWaitResult,
 } from '../session-wait-registry.js';
+import {
+  RemoteWakeRegistry,
+  REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS,
+  createDefaultRemoteWakeDeps,
+  isProbeable,
+  type WakeableRemote,
+} from '../../remote-wake.js';
 import { clampWaitMs, MAX_BUFFER_SCAN_BYTES } from '../../config/agent-wait.js';
 import {
   autoConfigureRalph,
@@ -135,6 +143,7 @@ import {
   checkRemoteTmuxAvailable,
   readRemoteCases,
   readRemoteHosts,
+  rehydrateRemoteHostFields,
   toAttachedSessionRemote,
   toSessionRemote,
 } from '../../remote-hosts.js';
@@ -750,10 +759,65 @@ export function resolveOmpConfigForCreate(
   return resolvedId ? { ...ompConfig, resumeSessionId: resolvedId } : ompConfig;
 }
 
+/**
+ * `RemoteHost` → the wake registry's host shape. They differ in one field name only
+ * (`id` in host config vs `hostId` on a session's `remote`), but the rename is load-
+ * bearing: the registry keys its per-host wake state on `hostId`. The proxy fields
+ * travel too: they are what tells the registry its probe cannot reach this host.
+ */
+function wakeableHost(host: RemoteHost): WakeableRemote {
+  return {
+    hostId: host.id,
+    label: host.label,
+    host: host.host,
+    port: host.port,
+    wakeMac: host.wakeMac,
+    wakeCommand: host.wakeCommand,
+    jumpHost: host.jumpHost,
+    socksProxy: host.socksProxy,
+    extraSshOptions: host.extraSshOptions,
+  };
+}
+
 export function registerSessionRoutes(
   app: FastifyInstance,
-  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort
-): void {
+  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort,
+  /** Test seam: inject a registry with fake IO instead of the real TCP/WoL probes. */
+  options: { remoteWake?: RemoteWakeRegistry } = {}
+): RemoteWakeRegistry {
+  // Wake-on-LAN for sleeping remote hosts (see remote-wake.ts). One registry per
+  // route registration (= one web server) — the same shape as the process-wide
+  // `sessionWaits` singleton, but without the global.
+  //
+  // ⚠️ The ONLY caller that may wake a host is the input route below. The
+  // auto-reconnect watcher and boot recovery deliberately have no access to this
+  // registry: waking there would re-wake the host seconds after every suspend, so
+  // it could never stay asleep.
+  const remoteWake =
+    options.remoteWake ??
+    new RemoteWakeRegistry(
+      createDefaultRemoteWakeDeps({
+        noteReconnected: (sessionId, success) => {
+          // Duck-typed exactly like server.ts: TmuxManager owns the COD-108 backoff
+          // state, and the port interface does not expose it.
+          const mux = ctx.mux as unknown as { noteRemoteReconnect?: (id: string, ok: boolean) => void };
+          mux.noteRemoteReconnect?.(sessionId, success);
+        },
+        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 the host config is
+        // authoritative in BOTH directions (removing the field turns the feature off
+        // for a live session too).
+        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])));
+        },
+      })
+    );
   // ═══════════════════════════════════════════════════════════════
   // Auth
   // ═══════════════════════════════════════════════════════════════
@@ -825,9 +889,33 @@ export function registerSessionRoutes(
     // creation (owned durable sessions) is handled by the dedicated case-create
     // endpoint below, which #145 consolidated remote-host resolution into.
     if (body.attachRemoteSession) {
+      // Remote hosts are admin-only infrastructure everywhere else (the list answers
+      // `[]` to a non-admin; write and discovery routes are `adminOnly`), and the wake
+      // below spawns the host's `wakeCommand` or broadcasts a packet. So the gate comes
+      // FIRST — before the host is even looked up — or an unprivileged account could
+      // invoke that executable for any configured `hostId` and only then be told the
+      // workingDir was outside its workspace (reproduced upstream: wake spy fired, 403).
+      if (isMultiUserMode() && !isAdmin(req)) {
+        return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Remote hosts are admin-only in multi-user mode');
+      }
       const { hostId, remoteSessionName } = body.attachRemoteSession;
       const host = (await readRemoteHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === hostId);
       if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Remote host not found');
+      // An explicit wake request is the only thing that may wake a host, and the user
+      // pressing Attach IS one (see quick-start for the same gate, and
+      // `remote-wake.ts` for what must never call this). Without it a sleeping host
+      // answers with an ssh failure that blames anything but the machine being asleep.
+      const hostWake = await remoteWake.ensureHostAwake(wakeableHost(host), {
+        timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS,
+        // No session yet, so the wake events name their requester (multi-user routing).
+        requestedBy: ownerFor(req),
+      });
+      if (hostWake === 'failed') {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          `${host.label} did not come back after a wake-on-LAN request — nothing was attached`
+        );
+      }
       workingDir = `${host.username}@${host.host}:${remoteSessionName}`;
       remote = toAttachedSessionRemote(host, remoteSessionName, workingDir);
     }
@@ -1215,6 +1303,8 @@ export function registerSessionRoutes(
     }
 
     const session = findSessionOrFail(ctx, id, req);
+    // Wake state is dropped by `cleanupSession` itself (server.ts), on EVERY cleanup
+    // path — not here: the scheduled-run and admin paths clean up without this route.
     await ctx.cleanupSession(session.id, killMux, 'user_delete');
     return {};
   });
@@ -1450,6 +1540,67 @@ 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, probeable: true, wakeConfigured: 'none' as const } };
+    }
+    const force = (req.query as { force?: string })?.force === '1';
+    // `reachable: null` + `probeable: false` for a host behind a jump host / SOCKS proxy:
+    // the probe cannot reach it, so the UI shows no banner and stops polling.
+    const reachable = await remoteWake.checkReachable(session, { force });
+    return {
+      success: true,
+      data: {
+        reachable,
+        probeable: isProbeable(remote),
+        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)'
+      );
+    }
+    // The button is pressed from the SAME dashboard the create/attach paths are, under
+    // the same reverse proxy — so it holds the request open the same way and needs the
+    // same request budget, not the 90 s session default (see remote-wake.ts).
+    const woke = await remoteWake.ensureAwake(session, {
+      force: true,
+      timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS,
+    });
+    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) => {
@@ -1491,6 +1642,42 @@ export function registerSessionRoutes(
       return {};
     }
 
+    // Wake-on-LAN (remote-wake.ts): a wake-enabled remote host that suspended leaves
+    // the local ssh pane STALLED, and `send-keys` succeeds against it — the bytes
+    // would vanish with no error anywhere. Give the registry the chance to probe the
+    // host, wake it, reattach, and own delivery before we write into nothing.
+    //
+    // Costs nothing for non-wake hosts (the `wakeCommand` guard) or while the host is
+    // 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 && (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).
+        // A host that never comes back is an error here, as on the create/attach
+        // paths: writing into the stalled pane would answer `delivered:true` plus a
+        // timeout, which is the combination the API docs send callers to the wrong
+        // recovery for.
+        if (!(await remoteWake.ensureAwake(session))) {
+          return createErrorResponse(
+            ApiErrorCode.OPERATION_FAILED,
+            `${session.remote?.label ?? 'the remote host'} did not come back after a wake-on-LAN request — nothing was sent`
+          );
+        }
+      } else {
+        const outcome = await remoteWake.handleInput(session, inputStr);
+        // The registry holds the bytes and flushes them in order once the pane is
+        // reattached. The client's ACK is this 200 — a tagged retry is deduped
+        // (`shouldApplyInput` above already consumed the seq), so nothing is lost.
+        // `buffered` is additive to the historical bare `{}`; `dropped` says the chunk
+        // was over the wake buffer's cap and is GONE (a 200 with no field could not
+        // tell delivered from buffered from dropped).
+        if (outcome === 'buffered') return { buffered: true };
+        if (outcome === 'dropped') return { buffered: true, dropped: true };
+      }
+    }
+
     // Only a waiting request pays for the tmux probe: the browser's plain input path
     // (thousands of calls per session) must stay exec-free.
     const workerDead = wantsWait && workerIsDead(ctx.mux, session);
@@ -3125,11 +3312,44 @@ export function registerSessionRoutes(
         );
       }
 
+      // The user pressing "Run" on a case whose host is asleep IS an explicit wake
+      // request (docs/remote-sessions.md §Wake-on-LAN), and the tmux probe below would
+      // otherwise fail with "could not verify tmux on remote host …" — an ssh failure
+      // that blames tmux for a machine that is merely suspended. Wired HERE, in the HTTP
+      // route, and deliberately NOT in the shared session service: `cron-service.ts`
+      // builds sessions through the service, and a wake down there would re-wake the
+      // host on every schedule (the failure invariant #1 exists to prevent).
+      const hostWake = await remoteWake.ensureHostAwake(wakeableHost(host), {
+        timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS,
+        // No session yet, so the wake events name their requester (multi-user routing).
+        requestedBy: ownerFor(req),
+      });
+      if (hostWake === 'failed') {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          `${host.label} did not come back after a wake-on-LAN request — the session was not started`
+        );
+      }
+
       // tmux is a hard prerequisite on the remote host (the agent runs inside a remote
       // tmux server so it survives ssh drops). Probe before spawning so a missing tmux
       // surfaces a clear, structured error instead of a dead "tmux: command not found" pane.
       const tmuxCheck = await checkRemoteTmuxAvailable(host);
       if (!tmuxCheck.ok) {
+        // An unreachable host and a host without tmux fail the same way over ssh, so the
+        // probe's own message would send the user hunting for a tmux install. Ask the
+        // registry (which just probed, when it woke the host) which of the two it is.
+        // `=== false` on purpose: a proxied host answers `null` (the probe cannot reach
+        // it), and an unknown verdict must not replace the real ssh error with
+        // "not reachable" over a host that is fine.
+        if ((await remoteWake.checkHostReachable(wakeableHost(host))) === false) {
+          return createErrorResponse(
+            ApiErrorCode.OPERATION_FAILED,
+            hostWake === 'no-target'
+              ? `${host.label} (${host.host}) is not reachable, and this host has no wake-on-LAN target — configure a MAC address or a wake command first`
+              : `${host.label} (${host.host}) is not reachable`
+          );
+        }
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'remote host is missing tmux');
       }
 
@@ -4688,4 +4908,10 @@ export function registerSessionRoutes(
 
     return { path: filepath, filename };
   });
+
+  // Returned so the server can own the registry's LIFETIME (drop state when a session is
+  // cleaned up on any of its paths, resolve in-flight wakes on shutdown). The wake-CAPABLE
+  // code stays here: `test/remote-wake.test.ts` pins that `server.ts` calls nothing but
+  // `drop`/`stop` on this handle, so no timer path can reach a wake through it.
+  return remoteWake;
 }

src/web/schemas.ts

@@ -737,6 +737,30 @@ export const RemoteHostSchema = z.object({
     .max(32)
     .optional(),
   commands: RemoteCommandOverridesSchema,
+  // Wake-on-LAN: a single executable path (no arguments, no shell) run to power a
+  // SLEEPING host back on, e.g. `/home/joe/bin/whuff`. Executed via spawn without
+  // a shell, so there is no shell layer to escape; the regexes are belt-and-braces
+  // (and the no-whitespace rule rejects an argument list before it can fail as a
+  // confusing ENOENT at wake time). See docs/remote-sessions.md §Wake-on-LAN.
+  wakeCommand: z
+    .string()
+    .min(1)
+    .max(4096)
+    .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({

src/web/server.ts

@@ -43,6 +43,8 @@ import { hostname as getHostname, uptime as osUptime } from 'node:os';
 import { looksLikeHostReboot, newestPersistedActivity, planRebootRestore } from '../reboot-restore.js';
 import { rebootRestoreRegistry } from './reboot-restore-registry.js';
 import { dataPath, getDataDir, CODEMAN_INSTANCE } from '../config/instance.js';
+import { readRemoteHosts, rehydrateRemoteHostFields } from '../remote-hosts.js';
+import type { RemoteWakeRegistry } from '../remote-wake.js';
 import { normalizeBasePath, stripBasePath, joinBasePath } from '../config/base-path.js';
 import { GLYPH, palette } from '../cli-style.js';
 import { getHookSecret } from '../config/hook-secret.js';
@@ -270,6 +272,14 @@ export class WebServer extends EventEmitter {
   private scheduledRuns: Map<string, ScheduledRun> = new Map();
   /** Cron service (assigned in setupRoutes). */
   private cronService!: CronService;
+  /**
+   * Wake-on-LAN registry, returned by `registerSessionRoutes`. Held for its LIFETIME
+   * only — `drop()` on session cleanup, `stop()` on shutdown. Waking from here would
+   * re-wake a host on every timer tick (the invariant `remote-wake.ts` documents), so
+   * the wiring guard in `test/remote-wake.test.ts` pins that this file calls nothing
+   * but `drop`/`stop` on it.
+   */
+  private remoteWake: RemoteWakeRegistry | null = null;
   private sse: SseStreamManager;
   private store = getStore();
   private tabLayouts!: TabLayoutService;
@@ -1070,7 +1080,9 @@ export class WebServer extends EventEmitter {
     registerStatusTelemetryRoutes(this.app, ctx);
     registerSystemRoutes(this.app, ctx);
     registerCaseRoutes(this.app, ctx);
-    registerSessionRoutes(this.app, ctx);
+    // The registry's lifetime is the server's: it drops per-session wake state on every
+    // cleanup path and resolves in-flight wakes on shutdown.
+    this.remoteWake = registerSessionRoutes(this.app, ctx);
     registerRespawnRoutes(this.app, ctx);
     registerRalphRoutes(this.app, ctx);
     registerPlanRoutes(this.app, ctx);
@@ -1461,6 +1473,11 @@ export class WebServer extends EventEmitter {
     sessionWaits.notifySignal(sessionId, 'exit');
     sessionWaits.cancelAll(sessionId);
     approvalInbox.resolveForSession(sessionId, 'session_ended');
+    // Wake state goes with the session on EVERY cleanup path (delete routes, the cron
+    // and admin paths, scheduled-run teardown, error paths) — that is why it lives here
+    // rather than in the two delete routes, where it left an entry behind, including up
+    // to 4 KB of the user's buffered keystrokes.
+    this.remoteWake?.drop(sessionId);
 
     this.broadcast(SseEvent.SessionDeleted, { id: sessionId });
   }
@@ -2332,11 +2349,19 @@ export class WebServer extends EventEmitter {
       'scheduled:',
       'team:',
       'case:',
+      'remote:',
     ];
     if (SESSION_PREFIXES.some((p) => event.startsWith(p))) {
-      const d = (data ?? {}) as { sessionId?: string; id?: string; session?: { id?: string } };
+      const d = (data ?? {}) as { sessionId?: string; id?: string; session?: { id?: string }; username?: string };
       const sessionId = d.sessionId ?? d.id ?? d.session?.id;
       const owner = sessionId ? this.sessions.get(sessionId)?.owner : undefined;
+      // `remote:hostWaking` / `remote:hostWakeFailed` for a create/attach wake have no
+      // session yet (nothing exists until the host is up), so the registry names the
+      // requesting user instead; the payload carries `hostId`/`label`, which non-admins
+      // are not shown elsewhere. No session and no requester: admins only (fail closed).
+      if (!sessionId && event.startsWith('remote:') && d.username) {
+        return { username: d.username, sessionScoped: true };
+      }
       return { owner, sessionScoped: true };
     }
     // #20/#38: clipboard:write writes into the receiver's OS clipboard — route it to
@@ -3116,6 +3141,9 @@ export class WebServer extends EventEmitter {
 
         // For each alive mux session, create a Session object if it doesn't exist
         const muxSessions = this.mux.getSessions();
+        // Host-level config lives in remote-hosts.json, not in the persisted session
+        // snapshot, so refresh the fields that only exist there (see the helper).
+        const remoteHostsById = new Map((await readRemoteHosts(getDataDir())).map((host) => [host.id, host]));
         for (const muxSession of muxSessions) {
           if (!this.sessions.has(muxSession.sessionId)) {
             // Restore session settings from state.json (single source of truth)
@@ -3193,7 +3221,9 @@ export class WebServer extends EventEmitter {
               // respawn rebuilds a LOCAL command, breaking the pane and silently
               // erasing `remote` from state.json on the next persist. mux-sessions.json
               // round-trips MuxSession.remote; state.json carries SessionState.remote.
-              remote: muxSession.remote ?? savedState?.remote,
+              // Host-level fields are refreshed from remote-hosts.json on top, or a
+              // field added to the host config after launch would never arrive.
+              remote: rehydrateRemoteHostFields(muxSession.remote ?? savedState?.remote, remoteHostsById),
               // Docker metadata round-trips the same way (mux-sessions.json carries
               // MuxSession.docker; state.json carries SessionState.docker), so recovery
               // rebuilds the `docker exec` launch instead of a broken local command.
@@ -3587,6 +3617,10 @@ export class WebServer extends EventEmitter {
     // response), so without this a 10-minute wait holds shutdown open.
     sessionWaits.cancelEverything();
     approvalInbox.stop();
+    // Same reason as `cancelEverything` above: an in-flight wake is awaited by a request,
+    // and `app.close()` (the last line of this method) does not abort in-flight requests —
+    // so without this a restart during a wake waits out the readiness poll.
+    this.remoteWake?.stop();
 
     this.lastRecordedTokens.clear();
 

src/web/sse-events.ts

@@ -5,7 +5,7 @@
  * and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
  * Both files MUST be kept in sync.
  *
- * 158 event constants organized by category:
+ * 160 event constants organized by category:
  * - **Core** (1): init
  * - **Transport** (1): sse:heartbeat
  * - **Session lifecycle** (23): created, updated, deleted, terminal, idle, working, ...
@@ -14,7 +14,7 @@
  * - **Session: Plan** (4): planTaskUpdate, planCheckpoint, planRollback, planTaskAdded
  * - **Tasks** (4): created, completed, failed, updated
  * - **Mux** (4): created, killed, died, statsUpdated
- * - **Remote auto-reconnect** (3): sessionDropped, sessionReconnected, reconnectExhausted
+ * - **Remote auto-reconnect / wake** (5): sessionDropped, sessionReconnected, reconnectExhausted, hostWaking, hostWakeFailed
  * - **Respawn** (24): stateChanged, cycleStarted/Completed, step*, aiCheck*, planCheck*, timer*, log, ...
  * - **Subagents** (7): discovered, updated, tool_call, tool_result, progress, message, completed
  * - **Workflow runs** (3): run_discovered, run_updated, run_removed (ultracode / Workflow tool)
@@ -176,7 +176,9 @@ export const MuxDied = 'mux:died' as const;
 /** tmux session stats refreshed. */
 export const MuxStatsUpdated = 'mux:statsUpdated' as const;
 
-// ─── Remote auto-reconnect (COD-108) ─────────────────────────────────────────
+// ─── Remote auto-reconnect (COD-108) + wake-on-LAN ───────────────────────────
+// Session-scoped in multi-user mode (`deriveSseHint`): routed to the session's owner,
+// or — for a wake with no session yet — to the requesting `username` in the payload.
 
 /** A remote session's local ssh pane died; an auto-reconnect attempt is starting. */
 export const RemoteSessionDropped = 'remote:sessionDropped' as const;
@@ -184,6 +186,15 @@ export const RemoteSessionDropped = 'remote:sessionDropped' as const;
 export const RemoteSessionReconnected = 'remote:sessionReconnected' as const;
 /** Auto-reconnect gave up after the bounded backoff cap — manual reconnect needed. */
 export const RemoteReconnectExhausted = 'remote:reconnectExhausted' as const;
+/**
+ * User input arrived for a session whose host is unreachable, so a Wake-on-LAN
+ * command was started (see `remote-wake.ts`). Input sent meanwhile is buffered.
+ * Payload: `sessionId` (session wake) or `forNewSession: true` + `username`
+ * (create/attach wake), `hostId`, `label`, `queuedInput`.
+ */
+export const RemoteHostWaking = 'remote:hostWaking' as const;
+/** The host did not come back within the wake timeout — buffered input is still held. */
+export const RemoteHostWakeFailed = 'remote:hostWakeFailed' as const;
 
 // ─── Respawn ─────────────────────────────────────────────────────────────────
 
@@ -535,6 +546,8 @@ export const SseEvent = {
   RemoteSessionDropped,
   RemoteSessionReconnected,
   RemoteReconnectExhausted,
+  RemoteHostWaking,
+  RemoteHostWakeFailed,
 
   // Respawn
   RespawnStarted,