fix(serena): harden codex dashboard startup

Author: rldyourmnd

codex/os/linux/runtime/README.md

@@ -15,6 +15,7 @@ It was exported from the source Linux machine and is the active reference payloa
 ## Truth Boundaries
 
 - `config/config.template.toml` defines the current portable config baseline.
+- The Linux Serena MCP entry in `config/config.template.toml` includes a small environment recovery wrapper so Codex-launched Serena sessions can still auto-open the web dashboard when GUI session variables are missing.
 - `rules/default.rules.source.snapshot` preserves the exported source-machine rules.
 - `rules/default.rules` and `rules/default.rules.template` are derived outputs, not hand-maintained policy files.
 - `meta/toolchain.lock` is the runtime version contract used by verification scripts.

codex/os/linux/runtime/config/config.template.toml

@@ -28,5 +28,34 @@ command = "npx"
 args = ["-y", "chrome-devtools-mcp@latest"]
 
 [mcp_servers.serena]
-command = "uvx"
-args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex", "--enable-web-dashboard", "--open-web-dashboard"]
+startup_timeout_sec = 60
+command = "/usr/bin/bash"
+args = [
+  "-lc",
+  '''
+uid="$(id -u)"
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/${uid}}"
+if [[ -z "${DBUS_SESSION_BUS_ADDRESS:-}" && -S "${XDG_RUNTIME_DIR}/bus" ]]; then
+  export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"
+fi
+if [[ -z "${WAYLAND_DISPLAY:-}" ]]; then
+  for wayland_socket in "${XDG_RUNTIME_DIR}"/wayland-*; do
+    if [[ -S "$wayland_socket" ]]; then
+      export WAYLAND_DISPLAY="${wayland_socket##*/}"
+      export XDG_SESSION_TYPE="${XDG_SESSION_TYPE:-wayland}"
+      break
+    fi
+  done
+fi
+if [[ -z "${DISPLAY:-}" ]]; then
+  for x_socket in /tmp/.X11-unix/X*; do
+    if [[ -S "$x_socket" ]]; then
+      export DISPLAY=":${x_socket##*/X}"
+      export XDG_SESSION_TYPE="${XDG_SESSION_TYPE:-x11}"
+      break
+    fi
+  done
+fi
+exec uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context codex --enable-web-dashboard true --open-web-dashboard true
+'''
+]

docs/setup/PORTABLE_SETUP.md

@@ -115,6 +115,7 @@ scripts/self-test.sh
 - If `codex mcp list` is unavailable, install or upgrade Codex CLI first.
 - If the curated install step fails, rerun with `--skip-curated`.
 - If toolchain mismatch is reported, run `scripts/sync-codex-version.sh --apply`.
+- On Linux, the portable Serena MCP entry restores missing GUI session variables before launch so the web dashboard can auto-open under Codex. If the browser still does not open after install, restart Codex and use the dashboard URL shown in Serena logs as a fallback.
 
 ## Related Documents
 

scripts/codex-activate.sh

@@ -18,6 +18,10 @@ if ! command -v codex >/dev/null 2>&1; then
   echo "[ERROR] codex CLI is not installed or not in PATH"
   exit 1
 fi
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[ERROR] python3 is not installed or not in PATH"
+  exit 1
+fi
 
 CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
 CONFIG_FILE="$CODEX_HOME_DIR/config.toml"
@@ -75,9 +79,24 @@ warn() { echo "[WARN] $*"; warn_count=$((warn_count + 1)); }
 err() { echo "[ERROR] $*"; err_count=$((err_count + 1)); }
 
 say "Collecting MCP status..."
-MCP_LIST="$(codex mcp list || true)"
-if [[ -z "$MCP_LIST" ]]; then
-  err "Unable to read MCP status via 'codex mcp list'"
+MCP_LIST_JSON="$(codex mcp list --json || true)"
+if [[ -z "$MCP_LIST_JSON" ]]; then
+  err "Unable to read MCP status via 'codex mcp list --json'"
+fi
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  if grep -Eq -- '--enable-web-dashboard' "$CONFIG_FILE" && grep -Eq -- '--open-web-dashboard' "$CONFIG_FILE"; then
+    say "Serena dashboard flags found in Codex config"
+  else
+    warn "Serena MCP config is missing dashboard startup flags"
+  fi
+  if grep -Eq 'DBUS_SESSION_BUS_ADDRESS|WAYLAND_DISPLAY|/tmp/\.X11-unix/X' "$CONFIG_FILE"; then
+    say "Serena display environment recovery found in Codex config"
+  else
+    warn "Serena MCP config is missing display environment recovery for browser auto-open"
+  fi
+else
+  warn "Codex config not found at $CONFIG_FILE"
 fi
 
 enable_mcp() {
@@ -93,11 +112,21 @@ enable_mcp() {
 }
 
 for mcp in "${REQUIRED_MCPS[@]}"; do
-  if ! grep -Eq "^${mcp}[[:space:]]+" <<<"$MCP_LIST"; then
+  state="$(printf '%s' "$MCP_LIST_JSON" | python3 -c '
+import json
+import sys
+
+name = sys.argv[1]
+for entry in json.load(sys.stdin):
+    if entry.get("name") == name:
+        print("enabled" if entry.get("enabled") else "disabled")
+        raise SystemExit(0)
+raise SystemExit(1)
+' "$mcp")" || {
     err "Missing MCP config: $mcp"
     continue
-  fi
-  if grep -Eq "^${mcp}[[:space:]]+.*[[:space:]]enabled[[:space:]]" <<<"$MCP_LIST"; then
+  }
+  if [[ "$state" == "enabled" ]]; then
     say "MCP present/enabled: $mcp"
   else
     warn "MCP configured but disabled: $mcp"
@@ -106,16 +135,35 @@ for mcp in "${REQUIRED_MCPS[@]}"; do
 
 done
 
-MCP_LIST_AFTER="$(codex mcp list || true)"
-MCP_LIST_AFTER_CLEAN="$(printf '%s\n' "$MCP_LIST_AFTER" | tr -d '\r' | sed -E 's/\x1B\\[[0-9;]*[[:alpha:]]//g')"
-if grep -Eiq "context7.*not logged in" <<<"$MCP_LIST_AFTER_CLEAN"; then
+MCP_LIST_AFTER_JSON="$(codex mcp list --json || true)"
+context7_auth="$(printf '%s' "$MCP_LIST_AFTER_JSON" | python3 -c '
+import json
+import sys
+
+for entry in json.load(sys.stdin):
+    if entry.get("name") == "context7":
+        print(entry.get("auth_status") or "")
+        raise SystemExit(0)
+raise SystemExit(1)
+')"
+if [[ "$context7_auth" == "not_logged_in" ]]; then
   if [[ -f "$CONFIG_FILE" ]] && grep -Eq '^CONTEXT7_API_KEY = "[^"]+"' "$CONFIG_FILE" && ! grep -q '__CONTEXT7_API_KEY__' "$CONFIG_FILE"; then
     say "context7 reports not logged in, but token header is configured in config.toml (can be expected with token-based auth)."
   else
     warn "context7 MCP is enabled but not logged in (check CONTEXT7_API_KEY)"
   fi
 fi
-if grep -Eiq "github.*not logged in" <<<"$MCP_LIST_AFTER_CLEAN"; then
+github_auth="$(printf '%s' "$MCP_LIST_AFTER_JSON" | python3 -c '
+import json
+import sys
+
+for entry in json.load(sys.stdin):
+    if entry.get("name") == "github":
+        print(entry.get("auth_status") or "")
+        raise SystemExit(0)
+raise SystemExit(1)
+')"
+if [[ "$github_auth" == "not_logged_in" ]]; then
   if [[ -f "$CONFIG_FILE" ]] && grep -Eq '^Authorization = "Bearer [^"]+"' "$CONFIG_FILE" && ! grep -q '__GITHUB_MCP_TOKEN__' "$CONFIG_FILE"; then
     say "github reports not logged in, but bearer header is configured in config.toml (can be expected with token-based auth)."
   else

scripts/verify.sh

@@ -50,6 +50,10 @@ if ! command -v codex >/dev/null 2>&1; then
   err "codex CLI not found"
   exit 1
 fi
+if ! command -v python3 >/dev/null 2>&1; then
+  err "python3 not found"
+  exit 1
+fi
 
 if [[ "$REQUESTED_PROFILE" != "$PROFILE_OS" ]]; then
   warn "Profile '$REQUESTED_PROFILE' has no payload, using '$PROFILE_OS'"
@@ -90,18 +94,28 @@ if [[ -d "$SKILLS_DIR/custom" && ! -d "$SKILLS_DIR/agent-development" ]]; then
   SKILLS_ROOT="$SKILLS_DIR/custom"
 fi
 
-status="$(codex mcp list || true)"
-if [[ -z "$status" ]]; then
-  err "Failed to read MCP table"
+status_json="$(codex mcp list --json || true)"
+if [[ -z "$status_json" ]]; then
+  err "Failed to read MCP table as JSON"
   exit 1
 fi
 
 for mcp in "${REQUIRED_MCPS[@]}"; do
-  if ! grep -Eq "^${mcp}[[:space:]]+" <<<"$status"; then
+  state="$(printf '%s' "$status_json" | python3 -c '
+import json
+import sys
+
+name = sys.argv[1]
+for entry in json.load(sys.stdin):
+    if entry.get("name") == name:
+        print("enabled" if entry.get("enabled") else "disabled")
+        raise SystemExit(0)
+raise SystemExit(1)
+' "$mcp")" || {
     err "Missing MCP: $mcp"
     exit 1
-  fi
-  if ! grep -E "^${mcp}[[:space:]].*[[:space:]]enabled([[:space:]]|$)" <<<"$status" >/dev/null; then
+  }
+  if [[ "$state" != "enabled" ]]; then
     err "MCP configured but not enabled: $mcp"
     exit 1
   fi
@@ -119,6 +133,20 @@ else
   warn "Config still contains GitHub MCP placeholder"
 fi
 
+if grep -Eq -- '--enable-web-dashboard' "$CONFIG_FILE" && grep -Eq -- '--open-web-dashboard' "$CONFIG_FILE"; then
+  say "Serena dashboard auto-open flags found"
+else
+  err "Serena MCP missing dashboard startup flags"
+  exit 1
+fi
+
+if grep -Eq 'DBUS_SESSION_BUS_ADDRESS|WAYLAND_DISPLAY|/tmp/\.X11-unix/X' "$CONFIG_FILE"; then
+  say "Serena display environment recovery wrapper found"
+else
+  err "Serena MCP missing display environment recovery wrapper"
+  exit 1
+fi
+
 if ! grep -Eiq 'think step by step' "$GLOBAL_AGENTS_FILE"; then
   err "Global AGENTS does not include expected baseline phrase: 'think step by step'"
   exit 1