Headless connect times out when TeamSpeak is blocked by modal dialogs

[spi3]

Summary

ts connect can time out in headless mode when the TeamSpeak client is blocked by GUI modal dialogs, even though the local plugin bridge is available and responsive. The CLI currently reports a generic timeout / disconnected state, which makes the failure look like a network or plugin transport problem.

In my case the server was reachable and the client/plugin were running, but the Xvfb display had these top-level TeamSpeak windows blocking progress:

• License agreement
• Identities
• Introducing the next generation of TeamSpeak

Once those dialogs were accepted/closed through X11 tooling, the exact same ts --profile wormhole connect succeeded immediately.

Environment

• ts version: 0.7.2
• backend: plugin
• plugin: ts3cli-plugin 0.7.2
• linked TeamSpeak client library: 3.6.2 [Build: 1695203293]
• OS: Linux, headless TeamSpeak launched under Xvfb by ts client start
• TeamSpeak profile: plugin backend, nickname set, host/port configured

What happened

1. Started/restarted the headless TeamSpeak client with ts client start.

2. ts --profile <profile> plugin info showed the plugin available and the control socket responsive.

3. ts --profile <profile> status reported disconnected.

4. ts --profile <profile> connect timed out:

   {
     "connected": false,
     "lifecycle": [],
     "result": "timeout",
     "state": {
       "backend": "plugin",
       "phase": "disconnected"
     },
     "timed_out": true
   }

5. Direct ClientQuery auth worked, and serverconnectinfo showed the requested server/port, but whoami / clientlist stayed not connected.

6. Inspecting the Xvfb display showed TeamSpeak modal windows. Relevant xwininfo -root -tree excerpt:

   "License agreement": ("ts3client_linux_amd64" "TeamSpeak 3")
   "Identities": ("ts3client_linux_amd64" "TeamSpeak 3")
   "Introducing the next generation of TeamSpeak": ("ts3client_linux_amd64" "TeamSpeak 3")
   

7. TeamSpeak client logs also hinted at the blockers:

   License update available; version 5 to 5
   View license: version=5, language=en, require accept=1
   Found cached license for version 5 and language en
   Created default identity
   Trying to open html from: .../teamspeak5_intro/index.html
   

8. After accepting the license and closing the startup/identity dialogs through X11 automation, ts --profile <profile> connect succeeded immediately:

   {
     "connected": true,
     "result": "connected",
     "state": {
       "backend": "plugin",
       "phase": "connected"
     },
     "timed_out": false
   }

Expected behavior

For headless mode, the CLI should make this failure actionable. A generic connect timeout sends the operator down the wrong path.

Reasonable fixes could include one or more of:

• Detect visible top-level TeamSpeak windows on the managed Xvfb display when ts connect times out and include their titles in the error/hints.
• Add a ts client inspect-windows or similar diagnostic command for managed headless sessions.
• When launching a managed headless client, suppress known nonessential startup popups where safe.
• For dialogs that require user/legal action, do not auto-accept silently, but report something explicit like: TeamSpeak client is blocked by modal dialog: License agreement.

Current workaround

Install X11 inspection/control tooling, inspect the managed Xvfb display, manually accept/close the blocking TeamSpeak dialogs, then rerun ts connect.

That worked, but it is exactly the kind of sharp edge the CLI should expose cleanly.