fix(desktop): SSH launcher waits for desktop updates before starting a server#23007

@@ -125,7 +130,51 @@ const runtimePort = Command.make("runtime-port", {
   ),
 );
 
+const UpdateMarker = Schema.fromJsonString(
+  Schema.Struct({ startedAt: Schema.optional(Schema.Unknown), expiresAt: Schema.Number }),
+);
+
+export const updateRemaining = Effect.fn("sshHelper.updateRemaining")(function* (

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Evidence driver for PR #23005 (issue #22990): runs the real SSH launch
+# script against a throwaway HOME, with real servers, for one fixture row.
+#
+#   scripts/evidence/pr-23005-ssh-update-race.sh <checkout> <row> [workdir]
+#
+# <checkout> is the tree under test (before or after the fix); the launch
+# script is generated from its own packages/ssh/src/tunnel.ts. Rows: F1 F2
+# F2b F3 F3b F3c F4 F5 F6 F7 F8 F8-archive F8b desktop-warmup F13 F14.
+# F8b also needs OLD_CHECKOUT=<pre-fix checkout> for the remote t3 that lacks
+# update-remaining. F13/F14 run the dev desktop (`vp run dev:desktop`) under
+# headless-desktop with --home-dir $FAKE/.t3 and an isolated
+# XDG_CONFIG_HOME; run desktop-warmup first so the build does not eat the
+# marker window. Stills land in $WORK/shots.
+#
+# The launcher's readiness probe wants GET / to answer 2xx, so the checkout
+# needs apps/web/dist/index.html (a real web build or a one-line stub).
+#
+# Safety: every HOME is a fresh mktemp dir under the workdir, never the real
+# one, and only PIDs recorded at spawn or in $FAKE/.t3/ssh-launch/k1/pid are
+# killed.
+set -euo pipefail
+
+CO="$(cd "${1:?checkout}" && pwd)"
+ROW="${2:?row}"
+WORK="${3:-/tmp/ev-23005/driver}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ARCHIVE_VERSION="9.9.9"
+MARKER_REL=".t3/runtime/desktop-update-in-progress"
+mkdir -p "$WORK"
+# Version-manager shims resolve node under $HOME; pin the real binary so the
+# throwaway HOMEs do not each install a runtime.
+PATH="$(dirname "$(node -p process.execPath)"):$PATH"
+export PATH
+
+ts() { date +%T.%3N; }
+say() { printf '[%s] %s\n' "$(ts)" "$*"; }
+
+capture_scripts() {
+  local helper="$CO/packages/ssh/src/.ev-capture-launcher.ts"
+  cp "$HERE/pr-23005-capture-launcher.ts" "$helper"
+  node "$helper" "$WORK/launch-node.sh" node "$CO/apps/server/src/bin.ts" >/dev/null 2>&1
+  node "$helper" "$WORK/launch-archive.sh" archive "$ARCHIVE_VERSION" >/dev/null 2>&1
+  rm -f "$helper"
+}
+
+STARTED_PIDS=()
+FAKE=""
+cleanup() {
+  local pid
+  if [ -n "$FAKE" ] && [ -f "$FAKE/.t3/ssh-launch/k1/pid" ]; then
+    STARTED_PIDS+=("$(cat "$FAKE/.t3/ssh-launch/k1/pid")")
+  fi
+  if [ -n "${DESKTOP_PGID:-}" ]; then
+    kill -TERM -- "-$DESKTOP_PGID" 2>/dev/null || true
+    while kill -0 -- "-$DESKTOP_PGID" 2>/dev/null; do sleep 0.2; done
+    DESKTOP_PGID=""
+  fi
+  for pid in "${STARTED_PIDS[@]}"; do
+    kill "$pid" 2>/dev/null || true
+  done
+  for pid in "${STARTED_PIDS[@]}"; do
+    while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done
+  done
+  STARTED_PIDS=()
+}
+trap cleanup EXIT
+
+new_home() {
+  cleanup
+  FAKE="$(mktemp -d "$WORK/home.XXXX")"
+  mkdir -p "$FAKE/.t3/runtime"
+  say "fresh HOME=$FAKE"
+}
+
+# write_marker <startedAt offset ms> <expiresAt offset ms> | write_raw <text>
+write_marker() {
+  node -e 'const n=Date.now();process.stdout.write(JSON.stringify({startedAt:n+Number(process.argv[1]),expiresAt:n+Number(process.argv[2])}))' \
+    -- "$1" "$2" >"$FAKE/$MARKER_REL"
+  say "marker written: $(cat "$FAKE/$MARKER_REL") (now=$(node -p 'Date.now()'))"
+}
+write_raw() {
+  printf '%s' "$1" >"$FAKE/$MARKER_REL"
+  say "marker written: $1"
+}
+show_marker() {
+  if [ -e "$FAKE/$MARKER_REL" ]; then say "marker PRESENT: $(cat "$FAKE/$MARKER_REL")"; else say "marker ABSENT"; fi
+}
+
+free_port() {
+  node -e 'const s=require("net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})'
+}
+
+# Stands in for the updated desktop backend: a real server on the default home.
+start_replacement() {
+  local port
+  port="$(free_port)"
+  HOME="$FAKE" T3CODE_NO_BROWSER=1 nohup node "$CO/apps/server/src/bin.ts" serve \
+    --host 127.0.0.1 --port "$port" --base-dir "$FAKE/.t3" >"$FAKE/replacement.log" 2>&1 </dev/null &
+  REPLACEMENT_PID=$!
+  STARTED_PIDS+=("$REPLACEMENT_PID")
+  say "replacement server spawned pid=$REPLACEMENT_PID port=$port"
+}
+runtime_json() { tr -d '\n' <"$FAKE/.t3/userdata/server-runtime.json" 2>/dev/null | cut -c1-120; }
+# The launcher's own server shares this base dir, so wait for the file to name
+# the replacement's PID, not just to exist.
+wait_runtime_file() {
+  local i=0
+  while ! grep -q "\"pid\":$REPLACEMENT_PID," "$FAKE/.t3/userdata/server-runtime.json" 2>/dev/null; do
+    i=$((i + 1))
+    if [ "$i" -ge 300 ]; then
+      say "replacement did not publish server-runtime.json within 30 s; file now: $(runtime_json)"
+      return 0
+    fi
+    sleep 0.1
+  done
+  say "replacement (pid $REPLACEMENT_PID) wrote server-runtime.json: $(runtime_json)"
+}
+
+seed_archive() {
+  local bin="$1" dir="$FAKE/.t3/runtime/versions/$ARCHIVE_VERSION"
+  mkdir -p "$dir"
+  printf '#!/bin/sh\nexec node %s "$@"\n' "$bin" >"$dir/t3"
+  chmod 755 "$dir/t3"
+  printf '%s\n' "$ARCHIVE_VERSION" >"$dir/.install-complete"
+  say "seeded archive runtime $ARCHIVE_VERSION -> node $bin"
+}
+
+LAUNCH_T0=0
+launch_bg() {
+  local mode="${1:-node}"
+  LAUNCH_T0=$(date +%s%3N)
+  say "launcher START ($mode mode)"
+  (
+    rc=0
+    HOME="$FAKE" sh -l -s -- k1 <"$WORK/launch-$mode.sh" >"$FAKE/launch.out" 2>"$FAKE/launch.err" || rc=$?
+    printf '%s %s %s\n' "$rc" "$(date +%s%3N)" "$(date +%T.%3N)" >"$FAKE/launch.end"
+  ) &
+  LAUNCH_PID=$!
+}
+launch_wait() {
+  local rc end_ms end_ts
+  wait "$LAUNCH_PID" || true
+  read -r rc end_ms end_ts <"$FAKE/launch.end"
+  say "launcher EXIT rc=$rc at $end_ts, $(( end_ms - LAUNCH_T0 )) ms after START; stdout: $(tail -n1 "$FAKE/launch.out")"
+  if [ "$rc" -ne 0 ]; then say "launcher stderr: $(grep -v '[▀█▄]' "$FAKE/launch.err" | tail -n3 | tr '\n' ' ')"; fi
+  report_servers
+}
+launch_fg() { launch_bg "${1:-node}"; launch_wait; }
+
+report_servers() {
+  local f="$FAKE/.t3/ssh-launch/k1"
+  say "state: managed=$(cat "$f/managed" 2>/dev/null || echo -) pid=$(cat "$f/pid" 2>/dev/null || echo -) port=$(cat "$f/port" 2>/dev/null || echo -)"
+  say "server processes on this HOME ($(ps -eo pid=,args= | grep -F -- "--base-dir $FAKE/.t3" | grep -v grep | wc -l)):"
+  ps -eo pid=,args= | grep -F -- "--base-dir $FAKE/.t3" | grep -v grep | sed "s|^|    |" || true
+  show_marker
+}
+
+# Starts the dev desktop with its data dir at $FAKE/.t3, in its own session
+# so it stops by the process group captured here.
+DESKTOP_PGID=""
+start_desktop() {
+  local cfg="$WORK/xdg-config"
+  mkdir -p "$cfg" "$WORK/shots"
+  rm -f "$WORK/display"
+  ( cd "$CO" && XDG_CONFIG_HOME="$cfg" exec setsid headless-desktop bash -c \

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Evidence driver for PR #23005 (issue #22990): runs the real SSH launch
+# script against a throwaway HOME, with real servers, for one fixture row.
+#
+#   scripts/evidence/pr-23005-ssh-update-race.sh <checkout> <row> [workdir]
+#
+# <checkout> is the tree under test (before or after the fix); the launch
+# script is generated from its own packages/ssh/src/tunnel.ts. Rows: F1 F2
+# F2b F3 F3b F3c F4 F5 F6 F7 F8 F8-archive F8b desktop-warmup F13 F14.
+# F8b also needs OLD_CHECKOUT=<pre-fix checkout> for the remote t3 that lacks
+# update-remaining. F13/F14 run the dev desktop (`vp run dev:desktop`) under
+# headless-desktop with --home-dir $FAKE/.t3 and an isolated
+# XDG_CONFIG_HOME; run desktop-warmup first so the build does not eat the
+# marker window. Stills land in $WORK/shots.
+#
+# The launcher's readiness probe wants GET / to answer 2xx, so the checkout
+# needs apps/web/dist/index.html (a real web build or a one-line stub).
+#
+# Safety: every HOME is a fresh mktemp dir under the workdir, never the real
+# one, and only PIDs recorded at spawn or in $FAKE/.t3/ssh-launch/k1/pid are
+# killed.
+set -euo pipefail
+
+CO="$(cd "${1:?checkout}" && pwd)"
+ROW="${2:?row}"
+WORK="${3:-/tmp/ev-23005/driver}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ARCHIVE_VERSION="9.9.9"
+MARKER_REL=".t3/runtime/desktop-update-in-progress"
+mkdir -p "$WORK"
+# Version-manager shims resolve node under $HOME; pin the real binary so the
+# throwaway HOMEs do not each install a runtime.
+PATH="$(dirname "$(node -p process.execPath)"):$PATH"
+export PATH
+
+ts() { date +%T.%3N; }
+say() { printf '[%s] %s\n' "$(ts)" "$*"; }
+
+capture_scripts() {
+  local helper="$CO/packages/ssh/src/.ev-capture-launcher.ts"
+  cp "$HERE/pr-23005-capture-launcher.ts" "$helper"
+  node "$helper" "$WORK/launch-node.sh" node "$CO/apps/server/src/bin.ts" >/dev/null 2>&1
+  node "$helper" "$WORK/launch-archive.sh" archive "$ARCHIVE_VERSION" >/dev/null 2>&1
+  rm -f "$helper"
+}
+
+STARTED_PIDS=()
+FAKE=""
+cleanup() {
+  local pid
+  if [ -n "$FAKE" ] && [ -f "$FAKE/.t3/ssh-launch/k1/pid" ]; then
+    STARTED_PIDS+=("$(cat "$FAKE/.t3/ssh-launch/k1/pid")")
+  fi
+  if [ -n "${DESKTOP_PGID:-}" ]; then
+    kill -TERM -- "-$DESKTOP_PGID" 2>/dev/null || true
+    while kill -0 -- "-$DESKTOP_PGID" 2>/dev/null; do sleep 0.2; done
+    DESKTOP_PGID=""
+  fi
+  for pid in "${STARTED_PIDS[@]}"; do
+    kill "$pid" 2>/dev/null || true
+  done
+  for pid in "${STARTED_PIDS[@]}"; do
+    while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Evidence driver for PR #23005 (issue #22990): runs the real SSH launch
+# script against a throwaway HOME, with real servers, for one fixture row.
+#
+#   scripts/evidence/pr-23005-ssh-update-race.sh <checkout> <row> [workdir]
+#
+# <checkout> is the tree under test (before or after the fix); the launch
+# script is generated from its own packages/ssh/src/tunnel.ts. Rows: F1 F2
+# F2b F3 F3b F3c F4 F5 F6 F7 F8 F8-archive F8b desktop-warmup F13 F14.
+# F8b also needs OLD_CHECKOUT=<pre-fix checkout> for the remote t3 that lacks
+# update-remaining. F13/F14 run the dev desktop (`vp run dev:desktop`) under
+# headless-desktop with --home-dir $FAKE/.t3 and an isolated
+# XDG_CONFIG_HOME; run desktop-warmup first so the build does not eat the
+# marker window. Stills land in $WORK/shots.
+#
+# The launcher's readiness probe wants GET / to answer 2xx, so the checkout
+# needs apps/web/dist/index.html (a real web build or a one-line stub).
+#
+# Safety: every HOME is a fresh mktemp dir under the workdir, never the real
+# one, and only PIDs recorded at spawn or in $FAKE/.t3/ssh-launch/k1/pid are
+# killed.
+set -euo pipefail
+
+CO="$(cd "${1:?checkout}" && pwd)"
+ROW="${2:?row}"
+WORK="${3:-/tmp/ev-23005/driver}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ARCHIVE_VERSION="9.9.9"
+MARKER_REL=".t3/runtime/desktop-update-in-progress"
+mkdir -p "$WORK"
+# Version-manager shims resolve node under $HOME; pin the real binary so the
+# throwaway HOMEs do not each install a runtime.
+PATH="$(dirname "$(node -p process.execPath)"):$PATH"
+export PATH
+
+ts() { date +%T.%3N; }
+say() { printf '[%s] %s\n' "$(ts)" "$*"; }
+
+capture_scripts() {
+  local helper="$CO/packages/ssh/src/.ev-capture-launcher.ts"
+  cp "$HERE/pr-23005-capture-launcher.ts" "$helper"
+  node "$helper" "$WORK/launch-node.sh" node "$CO/apps/server/src/bin.ts" >/dev/null 2>&1
+  node "$helper" "$WORK/launch-archive.sh" archive "$ARCHIVE_VERSION" >/dev/null 2>&1
+  rm -f "$helper"
+}
+
+STARTED_PIDS=()
+FAKE=""
+cleanup() {
+  local pid
+  if [ -n "$FAKE" ] && [ -f "$FAKE/.t3/ssh-launch/k1/pid" ]; then
+    STARTED_PIDS+=("$(cat "$FAKE/.t3/ssh-launch/k1/pid")")
+  fi
+  if [ -n "${DESKTOP_PGID:-}" ]; then
+    kill -TERM -- "-$DESKTOP_PGID" 2>/dev/null || true
+    while kill -0 -- "-$DESKTOP_PGID" 2>/dev/null; do sleep 0.2; done
+    DESKTOP_PGID=""
+  fi
+  for pid in "${STARTED_PIDS[@]}"; do
+    kill "$pid" 2>/dev/null || true
+  done
+  for pid in "${STARTED_PIDS[@]}"; do
+    while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done
+  done
+  STARTED_PIDS=()
+}
+trap cleanup EXIT
+
+new_home() {
+  cleanup
+  FAKE="$(mktemp -d "$WORK/home.XXXX")"
+  mkdir -p "$FAKE/.t3/runtime"
+  say "fresh HOME=$FAKE"
+}
+
+# write_marker <startedAt offset ms> <expiresAt offset ms> | write_raw <text>
+write_marker() {
+  node -e 'const n=Date.now();process.stdout.write(JSON.stringify({startedAt:n+Number(process.argv[1]),expiresAt:n+Number(process.argv[2])}))' \
+    -- "$1" "$2" >"$FAKE/$MARKER_REL"
+  say "marker written: $(cat "$FAKE/$MARKER_REL") (now=$(node -p 'Date.now()'))"
+}
+write_raw() {
+  printf '%s' "$1" >"$FAKE/$MARKER_REL"
+  say "marker written: $1"
+}
+show_marker() {
+  if [ -e "$FAKE/$MARKER_REL" ]; then say "marker PRESENT: $(cat "$FAKE/$MARKER_REL")"; else say "marker ABSENT"; fi
+}
+
+free_port() {
+  node -e 'const s=require("net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})'
+}
+
+# Stands in for the updated desktop backend: a real server on the default home.
+start_replacement() {
+  local port
+  port="$(free_port)"
+  HOME="$FAKE" T3CODE_NO_BROWSER=1 nohup node "$CO/apps/server/src/bin.ts" serve \
+    --host 127.0.0.1 --port "$port" --base-dir "$FAKE/.t3" >"$FAKE/replacement.log" 2>&1 </dev/null &
+  REPLACEMENT_PID=$!
+  STARTED_PIDS+=("$REPLACEMENT_PID")
+  say "replacement server spawned pid=$REPLACEMENT_PID port=$port"
+}
+runtime_json() { tr -d '\n' <"$FAKE/.t3/userdata/server-runtime.json" 2>/dev/null | cut -c1-120; }
+# The launcher's own server shares this base dir, so wait for the file to name
+# the replacement's PID, not just to exist.
+wait_runtime_file() {
+  local i=0
+  while ! grep -q "\"pid\":$REPLACEMENT_PID," "$FAKE/.t3/userdata/server-runtime.json" 2>/dev/null; do
+    i=$((i + 1))
+    if [ "$i" -ge 300 ]; then
+      say "replacement did not publish server-runtime.json within 30 s; file now: $(runtime_json)"
+      return 0
+    fi
+    sleep 0.1
+  done
+  say "replacement (pid $REPLACEMENT_PID) wrote server-runtime.json: $(runtime_json)"
+}
+
+seed_archive() {
+  local bin="$1" dir="$FAKE/.t3/runtime/versions/$ARCHIVE_VERSION"
+  mkdir -p "$dir"
+  printf '#!/bin/sh\nexec node %s "$@"\n' "$bin" >"$dir/t3"

@@ -0,0 +1,61 @@
+// @effect-diagnostics nodeBuiltinImport:off - Evidence helper; copied next to tunnel.ts in the checkout under test.
+// Prints the exact launch script launchOrReuseRemoteServer sends over SSH.
+// Uses only the public launchOrReuseRemoteServer so it runs unchanged on
+// checkouts that predate launcherTestHarness.ts.
+// Usage: node <checkout>/packages/ssh/src/<this file> <out.sh> node <bin.ts> | archive <version>
+// Writes to a file because the Effect logger prints to stdout.
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeFS from "node:fs";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/process";
+import { launchOrReuseRemoteServer } from "./tunnel.ts";

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Evidence driver for PR #23005 (issue #22990): runs the real SSH launch
+# script against a throwaway HOME, with real servers, for one fixture row.
+#
+#   scripts/evidence/pr-23005-ssh-update-race.sh <checkout> <row> [workdir]
+#
+# <checkout> is the tree under test (before or after the fix); the launch
+# script is generated from its own packages/ssh/src/tunnel.ts. Rows: F1 F2
+# F2b F3 F3b F3c F4 F5 F6 F7 F8 F8-archive F8b desktop-warmup F13 F14.
+# F8b also needs OLD_CHECKOUT=<pre-fix checkout> for the remote t3 that lacks
+# update-remaining. F13/F14 run the dev desktop (`vp run dev:desktop`) under
+# headless-desktop with --home-dir $FAKE/.t3 and an isolated
+# XDG_CONFIG_HOME; run desktop-warmup first so the build does not eat the
+# marker window. Stills land in $WORK/shots.
+#
+# The launcher's readiness probe wants GET / to answer 2xx, so the checkout
+# needs apps/web/dist/index.html (a real web build or a one-line stub).
+#
+# Safety: every HOME is a fresh mktemp dir under the workdir, never the real
+# one, and only PIDs recorded at spawn or in $FAKE/.t3/ssh-launch/k1/pid are
+# killed.
+set -euo pipefail
+
+CO="$(cd "${1:?checkout}" && pwd)"
+ROW="${2:?row}"
+WORK="${3:-/tmp/ev-23005/driver}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ARCHIVE_VERSION="9.9.9"
+MARKER_REL=".t3/runtime/desktop-update-in-progress"
+mkdir -p "$WORK"
+# Version-manager shims resolve node under $HOME; pin the real binary so the
+# throwaway HOMEs do not each install a runtime.
+PATH="$(dirname "$(node -p process.execPath)"):$PATH"
+export PATH
+
+ts() { date +%T.%3N; }
+say() { printf '[%s] %s\n' "$(ts)" "$*"; }
+
+capture_scripts() {
+  local helper="$CO/packages/ssh/src/.ev-capture-launcher.ts"
+  cp "$HERE/pr-23005-capture-launcher.ts" "$helper"
+  node "$helper" "$WORK/launch-node.sh" node "$CO/apps/server/src/bin.ts" >/dev/null 2>&1
+  node "$helper" "$WORK/launch-archive.sh" archive "$ARCHIVE_VERSION" >/dev/null 2>&1
+  rm -f "$helper"