fix(browser): recover display after SSH reconnect

Refresh workspace-local display and Xauthority state on each initialize run, prefer mounted Wayland when available, and probe SSH X11 before launching Chrome.

Add parallel-workspace and stale-display smoke coverage while keeping headless behavior unchanged.

Author: codegeist-ai

.gitignore

@@ -1,8 +1,16 @@
 /compose.local.gen.yml
+/compose.local.gen.yml.*
 /compose.user.gen.yml
+/compose.user.gen.yml.*
 /Dockerfile.merged.gen
 /.env
+/.env.*
+/.Xauthority.gen
+/.Xauthority.gen.*
 /.devcontainer/.env
+/.devcontainer/.env.*
+/.devcontainer/.Xauthority.gen
+/.devcontainer/.Xauthority.gen.*
 /.codegeist/.local.env
 /.oc_local/
 /.worktrees/

README.md

@@ -116,6 +116,7 @@ The first start creates local and generated files when missing:
 - `.codegeist/.local.env`
 - `.chrome/`
 - `.devcontainer/.env`
+- `.devcontainer/.Xauthority.gen`
 - `.devcontainer/Dockerfile.merged.gen`
 - `.devcontainer/compose.local.gen.yml`
 - `.devcontainer/compose.user.gen.yml`, an ignored bridge to optional
@@ -144,9 +145,10 @@ file does not exist. It does not delete the legacy files and does not migrate a
 root `Dockerfile`; move devcontainer image extensions to `.codegeist/Dockerfile`
 manually if needed.
 
-Do not edit `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`, or
-`.devcontainer/compose.local.gen.yml` or `.devcontainer/compose.user.gen.yml`;
-they are regenerated by `initialize.sh`. Put manual runtime overrides in
+Do not edit `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+`.devcontainer/Dockerfile.merged.gen`, `.devcontainer/compose.local.gen.yml`, or
+`.devcontainer/compose.user.gen.yml`; they are regenerated by `initialize.sh`.
+Put manual runtime overrides in
 `.codegeist/.local.env`, local Compose overrides in `.codegeist/compose.local.yml`,
 and devcontainer image extensions in `.codegeist/Dockerfile` instead. Create the
 Compose and Dockerfile override files only when the repository needs them.
@@ -223,26 +225,34 @@ chrome https://example.test
 ```
 
 The visible command does not start VNC or noVNC, and it does not treat a non-empty
-display variable as proof that a display server is reachable. A Wayland candidate
-is usable only when `WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` identify an existing
-Unix socket. When that socket exists, the launcher prefers it, removes an
-inherited invalid `DISPLAY`, and starts Chrome with `--ozone-platform=wayland`.
-A local X11 value such as `DISPLAY=:0` is usable only when the matching
-`/tmp/.X11-unix/X0` socket exists inside the container. The shared Compose config
-does not mount `/tmp/.X11-unix` by default. SSH-forwarded values such as
-`DISPLAY=localhost:10.0` remain supported through host networking and Xauthority
-normalization; explicitly configured remote X11 host values are passed through as
-caller-managed connections.
-
-`initialize.sh` still writes the host-side `DISPLAY` visible to
-`initializeCommand` into `.devcontainer/.env` as `DEVCONTAINER_DISPLAY`, and
-Compose passes that candidate into the container on create. The launcher rereads
-the mounted file before starting visible Chrome, so a VS Code reopen can refresh
-SSH X11 state when the existing container is reused. If no usable Wayland or X11
-backend exists, the launcher exits before Google Chrome starts and reports the
-missing socket paths. Use `chrome --headless ...`, SSH X11 forwarding, or an
-explicit project-local socket mount instead of broad host access such as
-`xhost +`.
+display variable as proof that a display server is reachable. During
+`initializeCommand`, `initialize.sh` detects an existing host Wayland socket from
+`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` (or `/run/user/<uid>/wayland-0`) and adds a
+generated bind for only that socket. When the mounted socket is reachable, the
+launcher prefers it, removes inherited `DISPLAY`, and starts Chrome with
+`--ozone-platform=wayland`. A local X11 value such as `DISPLAY=:0` remains usable
+only when `/tmp/.X11-unix/X0` exists inside the container; the shared Compose
+config does not mount local X11 sockets by default.
+
+VS Code SSH reconnects can allocate a new loopback display number while reusing
+an existing container. Each initialize run atomically refreshes the selected
+workspace's `.devcontainer/.env` and ignored `.devcontainer/.Xauthority.gen`.
+The launcher rereads those files on every visible start, probes
+`DISPLAY=localhost:N.0` or `127.0.0.1:N.0` with a short `xdpyinfo` check, and, if
+needed, normalizes the matching `/unix:N` cookie through unique temporary
+Xauthority aliases. It
+exits before Google Chrome starts when no candidate is reachable. Worktrees keep
+separate generated state and `.chrome` profiles, so multiple VS Code instances
+on one host do not overwrite each other's runtime display files. Explicit
+non-loopback X11 hosts remain caller-managed.
+
+Wayland discovery can mount only a socket that exists when the container is
+created. `initialize.sh` cannot create a graphical host session, and a socket
+that appears later cannot be added to an already running container without
+recreation. SSH X11 reconnect recovery does not have that limitation because it
+uses host networking and workspace-local refreshed authority state. Use
+`chrome --headless ...` when no visible backend is available; broad host access
+such as `xhost +` is neither required nor recommended.
 
 Plain visible `chrome` uses `$DEVCONTAINER_WORKSPACE_FOLDER/.chrome` unless the
 caller passes an explicit `--user-data-dir`. Visible Chrome also disables
@@ -543,10 +553,10 @@ The same generated root files must still be ignored by the consuming repository:
 /.chrome/
 ```
 
-The `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`,
-`.devcontainer/compose.local.gen.yml`, and `.devcontainer/compose.user.gen.yml`
-files are generated by the kit inside the submodule checkout and intentionally
-ignored there.
+The `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+`.devcontainer/Dockerfile.merged.gen`, `.devcontainer/compose.local.gen.yml`, and
+`.devcontainer/compose.user.gen.yml` files are generated by the kit inside the
+submodule checkout and intentionally ignored there.
 
 The kit also creates root `.oc_local/` for `OPENCODE_CONFIG_DIR` so OpenCode can
 bootstrap in fresh devcontainers. When the consuming repository does not track a
@@ -620,9 +630,10 @@ It may:
   `compose.local.yml` there when it already exists and the new file is missing;
   this file is not ignored automatically
 - create root `.oc_local/` for workspace-local OpenCode config
-- write `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`, and
-  `.devcontainer/compose.local.gen.yml` generated runtime values such as the
-  container hostname, hostname loopback resolution, and numeric runtime user
+- write `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+  `.devcontainer/Dockerfile.merged.gen`, and `.devcontainer/compose.local.gen.yml`
+  generated runtime values such as display state, container hostname, hostname
+  loopback resolution, and numeric runtime user
 - update generated local env values when their content changed
 - compute host UID
 - compute a stable project name
@@ -641,22 +652,22 @@ Preferred pattern:
 1. `initialize.sh` writes `.codegeist/.local.env`.
 2. `initialize.sh` migrates a legacy root `compose.local.yml` into
    `.codegeist/compose.local.yml` only when that legacy file exists.
-3. `initialize.sh` writes `.devcontainer/.env`, including the host-side
-   `DISPLAY` value as `DEVCONTAINER_DISPLAY` when one is present.
-4. `initialize.sh` writes `.devcontainer/Dockerfile.merged.gen`.
-5. `initialize.sh` writes `.devcontainer/compose.local.gen.yml`.
-6. `initialize.sh` writes `.devcontainer/compose.user.gen.yml`, either empty or
+3. `initialize.sh` writes `.devcontainer/.env`, including host display state.
+4. `initialize.sh` atomically refreshes `.devcontainer/.Xauthority.gen`.
+5. `initialize.sh` writes `.devcontainer/Dockerfile.merged.gen`.
+6. `initialize.sh` writes `.devcontainer/compose.local.gen.yml`.
+7. `initialize.sh` writes `.devcontainer/compose.user.gen.yml`, either empty or
    copied from `.codegeist/compose.local.yml`.
-7. `.devcontainer/docker-compose.yml` reads `.env` and
+8. `.devcontainer/docker-compose.yml` reads `.env` and
    `../.codegeist/.local.env` with `env_file`.
-8. `devcontainer.json` includes `compose.local.gen.yml` and
+9. `devcontainer.json` includes `compose.local.gen.yml` and
    `compose.user.gen.yml`.
-9. `.devcontainer/docker-compose.yml` owns the workspace and parent Git mounts.
-10. `devcontainer.json` uses `${localEnv:USER}` for `remoteUser` and
-   `containerUser`.
-11. `docker-compose.yml` passes `DEVCONTAINER_DISPLAY` into the container as
-    `DISPLAY` so SSH X11 forwarding follows the initialize-time environment.
-12. Container-side tools read normal environment variables from Compose.
+10. `.devcontainer/docker-compose.yml` owns the workspace and parent Git mounts.
+11. `devcontainer.json` uses `${localEnv:USER}` for `remoteUser` and
+    `containerUser`.
+12. `docker-compose.yml` passes initial display values into the container; the
+    Chrome launcher rereads the workspace files after SSH reconnects.
+13. Container-side tools read normal environment variables from Compose.
 
 Example Compose shape:
 
@@ -744,7 +755,8 @@ The tests should verify at least:
 - `.codegeist/.local.env` is created or preserved by `initializeCommand`
 - root `.oc_local/` is created for OpenCode and ignored unless the repository
   tracks a project overlay there
-- `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`,
+- `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+  `.devcontainer/Dockerfile.merged.gen`,
   `.devcontainer/compose.local.gen.yml`, and
   `.devcontainer/compose.user.gen.yml` are regenerated by `initializeCommand`
 - the generated container hostname matches host, repo, and branch context
@@ -893,7 +905,8 @@ migrates a legacy root `.local.env` into `.codegeist/.local.env` when needed,
 and links the worktree `.codegeist/.local.env` back to the main root file. When
 the devcontainer starts from an already selected checkout, `initializeCommand`
 writes that checkout's
-`.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`,
+`.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+`.devcontainer/Dockerfile.merged.gen`,
 `.devcontainer/compose.local.gen.yml`, and `.devcontainer/compose.user.gen.yml`
 without nesting another worktree for the same branch.
 
@@ -959,6 +972,7 @@ Typical examples:
 
 - `.codegeist/.local.env`
 - `.devcontainer/.env`
+- `.devcontainer/.Xauthority.gen`
 - `.devcontainer/Dockerfile.merged.gen`
 - `.devcontainer/compose.local.gen.yml`
 - `.devcontainer/compose.user.gen.yml`

README_release.md

@@ -57,10 +57,10 @@ repository's root `.gitignore`. It never writes generated-file ignores to
 `.git/info/exclude`, so review and commit intentional `.gitignore` changes like
 normal repository state.
 
-The generated `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`,
-`.devcontainer/compose.local.gen.yml`, and `.devcontainer/compose.user.gen.yml`
-files are written inside the submodule checkout and are ignored by the release
-kit itself.
+The generated `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+`.devcontainer/Dockerfile.merged.gen`, `.devcontainer/compose.local.gen.yml`, and
+`.devcontainer/compose.user.gen.yml` files are written inside the submodule
+checkout and are ignored by the release kit itself.
 
 ## OpenCode Agent Setup
 
@@ -183,6 +183,7 @@ The first start creates local runtime files when missing:
 - root `.worktrees/`; `.worktrees/<branch>` as a worktree or current-branch
   symlink alias when `BRANCH` is set
 - `.devcontainer/.env`
+- `.devcontainer/.Xauthority.gen`
 - `.devcontainer/Dockerfile.merged.gen`
 - `.devcontainer/compose.local.gen.yml`
 - `.devcontainer/compose.user.gen.yml`, an ignored bridge to optional
@@ -273,24 +274,34 @@ chrome https://example.test
 ```
 
 The visible command does not start VNC or noVNC, and it validates display
-transport before starting Google Chrome. A Wayland candidate is usable only when
-`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` identify an existing Unix socket. When
-that socket exists, the launcher prefers it, removes an inherited invalid
-`DISPLAY`, and starts Chrome with `--ozone-platform=wayland`. A local X11 value
-such as `DISPLAY=:0` is usable only when `/tmp/.X11-unix/X0` exists inside the
-container; the shared Compose config does not mount `/tmp/.X11-unix` by default.
-SSH-forwarded values such as `DISPLAY=localhost:10.0` remain supported through
-host networking and Xauthority normalization. Explicit remote X11 host values
-remain caller-managed and are passed through.
-
-`initialize.sh` still writes the host-side `DISPLAY` visible to
-`initializeCommand` into `.devcontainer/.env` as `DEVCONTAINER_DISPLAY`, and
-Compose passes that candidate into the container on create. The launcher rereads
-the mounted file before starting visible Chrome, so a VS Code reopen can refresh
-SSH X11 state when the existing container is reused. If no usable backend exists,
-the launcher exits before Google Chrome starts and reports the missing socket
-paths. Use `chrome --headless ...`, SSH X11 forwarding, or an explicit
-project-local socket mount instead of broad host access such as `xhost +`.
+transport before starting Google Chrome. During `initializeCommand`,
+`initialize.sh` detects an existing host Wayland socket from `WAYLAND_DISPLAY`
+and `XDG_RUNTIME_DIR` (or `/run/user/<uid>/wayland-0`) and adds a generated bind
+for only that socket. When the mounted socket is reachable, the launcher prefers
+it, removes inherited `DISPLAY`, and starts Chrome with
+`--ozone-platform=wayland`. A local X11 value such as `DISPLAY=:0` is usable only
+when `/tmp/.X11-unix/X0` exists; the shared Compose config does not mount local
+X11 sockets by default.
+
+VS Code SSH reconnects can allocate a new loopback display number while reusing
+an existing container. Each initialize run atomically refreshes the selected
+workspace's `.devcontainer/.env` and ignored `.devcontainer/.Xauthority.gen`.
+The launcher rereads those files on every visible start, probes
+`DISPLAY=localhost:N.0` or `127.0.0.1:N.0` with a short `xdpyinfo` check, and, if
+needed, normalizes the matching `/unix:N` cookie through unique temporary
+Xauthority aliases. It
+exits before Google Chrome starts when no candidate is reachable. Worktrees keep
+separate generated state and `.chrome` profiles, so multiple VS Code instances
+on one host do not overwrite each other's runtime display files. Explicit
+non-loopback X11 hosts remain caller-managed.
+
+Wayland discovery can mount only a socket that exists when the container is
+created. `initialize.sh` cannot create a graphical host session, and a socket
+that appears later cannot be added to an existing container without recreation.
+SSH X11 reconnect recovery does not have that limitation because it uses host
+networking and refreshed workspace-local authority state. Use
+`chrome --headless ...` when no visible backend is available; broad host access
+such as `xhost +` is neither required nor recommended.
 
 Plain visible `chrome` uses `$DEVCONTAINER_WORKSPACE_FOLDER/.chrome` unless the
 caller passes an explicit `--user-data-dir`. Visible Chrome also disables
@@ -422,9 +433,10 @@ not as ordinary project source.
 
 - Do not edit files inside `.devcontainer/` directly to customize one consuming
   project.
-- Do not commit `.devcontainer/.env`, `.devcontainer/Dockerfile.merged.gen`,
-  `.devcontainer/compose.local.gen.yml`, `.devcontainer/compose.user.gen.yml`,
-  `.codegeist/.local.env`, or generated `.worktrees/` files. Keep
+- Do not commit `.devcontainer/.env`, `.devcontainer/.Xauthority.gen`,
+  `.devcontainer/Dockerfile.merged.gen`, `.devcontainer/compose.local.gen.yml`,
+  `.devcontainer/compose.user.gen.yml`, `.codegeist/.local.env`, or generated
+  `.worktrees/` files. Keep
   `.codegeist/compose.local.yml` visible to Git and keep `.codegeist/Dockerfile`
   visible to Git without `FROM`; commit either only when its overrides are
   intentional repository state.

docker-compose.yml

@@ -34,8 +34,14 @@
 # - DEVCONTAINER_DISPLAY is generated by initialize.sh from the host-side DISPLAY
 #   visible to initializeCommand. Compose injects it when the container is
 #   created; the Chrome launcher rereads and validates the candidate so VS Code
-#   reopen can refresh SSH X11 state without a rebuild. This Compose file does not
-#   mount host-local `/tmp/.X11-unix` sockets automatically.
+#   SSH reconnect can refresh X11 state without recreating the container.
+# - DEVCONTAINER_XAUTHORITY points into the selected workspace. initialize.sh
+#   atomically refreshes that ignored file after an SSH reconnect, avoiding a
+#   stale bind mount when the host replaces its original Xauthority file.
+# - When initialize.sh sees a live host Wayland socket, compose.local.gen.yml
+#   mounts only that socket and sets its container-side runtime variables. Static
+#   Wayland mounts are avoided so SSH-only hosts never receive an invalid bind.
+#   This Compose file does not mount host-local `/tmp/.X11-unix` sockets.
 # - OPENCODE_DIR_CONFIG, OPENCODE_DIR_SHARE, and OPENCODE_DIR_STATE select the
 #   host-side OpenCode state directories mounted into the container.
 # - initialize.sh writes `.devcontainer/Dockerfile.merged.gen` before Compose
@@ -88,12 +94,11 @@ services:
       OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER: ${OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER:-true}
       DEVCONTAINER_WORKSPACE_FOLDER: ${DEVCONTAINER_WORKSPACE_FOLDER:?DEVCONTAINER_WORKSPACE_FOLDER must be generated by initialize.sh}
       DISPLAY: ${DEVCONTAINER_DISPLAY:-}
-      XAUTHORITY: /home/${USER:-vscode}/.Xauthority
+      XAUTHORITY: ${DEVCONTAINER_XAUTHORITY:-${DEVCONTAINER_WORKSPACE_FOLDER}/.devcontainer/.Xauthority.gen}
       QT_X11_NO_MITSHM: "1"
     volumes:
       - ${DEVCONTAINER_WORKSPACE_FOLDER:?DEVCONTAINER_WORKSPACE_FOLDER must be generated by initialize.sh}:${DEVCONTAINER_WORKSPACE_FOLDER:?DEVCONTAINER_WORKSPACE_FOLDER must be generated by initialize.sh}:cached
       - ${DEVCONTAINER_REPO_ROOT:?DEVCONTAINER_REPO_ROOT must be generated by initialize.sh}:${DEVCONTAINER_REPO_ROOT:?DEVCONTAINER_REPO_ROOT must be generated by initialize.sh}:cached
       - ${OPENCODE_DIR_CONFIG:-/home/${USER:-vscode}/.config/opencode}:/home/${USER:-vscode}/.config/opencode
       - ${OPENCODE_DIR_SHARE:-/home/${USER:-vscode}/.local/share/opencode}:/home/${USER:-vscode}/.local/share/opencode
       - ${OPENCODE_DIR_STATE:-/home/${USER:-vscode}/.local/state/opencode}:/home/${USER:-vscode}/.local/state/opencode
-      - ${HOME}/.Xauthority:/home/${USER:-vscode}/.Xauthority