AI Agent Gateway Deadlock On Docker Desktop Bind Mounts

When an AI coding agent runs inside Docker Desktop on Windows, a bind-mounted config directory can make the gateway look ready while HTTP, WebSocket, plugin startup, or Docker calls hang behind permissions, lock files, or a frozen Docker backend.

Common Failure Buckets

• Bind-mount permission drift: the config root or generated files are owned by root while the gateway runs as an app user.
• Stale runtime locks: plugin dependency installs, mirrors, package managers, or session locks survive a failed startup.
• Docker daemon timeout: Docker Desktop accepts a client call but the daemon, WSL2 backend, or storage layer never answers.
• Dispatcher deadlock: the process is alive and listening, but HTTP/WS handlers never complete and connections pile up.
• Storage pressure: Docker VM disk, Windows host free space, logs, or agent session files fill the path used by the bind mount.

Read-Only Evidence Order

1. Bound every external call with a timeout: Docker, compose, git, package managers, plugin installers, and health probes.
2. Capture process state, recent logs, TCP socket state, and the exact command that hangs.
3. Check ownership and mode on the bind-mount root, config file, workspace mount, plugin runtime directory, and lock directories.
4. Measure host and Docker storage before pruning or resetting anything.
5. Only remove stale lock directories after the owning process is stopped and the lock path is known to be rebuildable.

User-Facing Recovery Copy

A good error message should say which probe timed out, what evidence to collect, and which local state is at risk. Avoid one-line guidance like "reset Docker Desktop" or "delete the config folder" when sessions, plugin state, credentials, workspaces, or named volumes may be involved.