flake: coderd TestWorkspaceWatcher

[spikecurtis]

copied from #550 (comment) because it's a separate issue.

CI run: https://github.com/coder/coder/actions/runs/20114690657

• Failing job: test-go-race-pg (run_attempt: 1)
• Job completed at: 2025-12-10T22:32:39Z; Slack alert at 2025-12-10T22:32:58Z (same minute)
• Commit: 8ed1c1d3720b40a5dcc41c8a17debf93b36d3537 (author: Callum Styan)

Failure evidence (excerpt):

=== Failed
=== FAIL: coderd TestWorkspaceWatcher (26.09s)
...
Error Trace: /home/runner/work/coder/coder/coderd/workspaces_test.go:3420
             /home/runner/work/coder/coder/coderd/workspaces_test.go:3458
Error:       timed out waiting for event
Test:        TestWorkspaceWatcher
Messages:    agent disconnected
...
DONE 13271 tests, 63 skipped, 1 failure in 431.105s

Classification: Flaky test (timeout)

• No data race signatures found (no "WARNING: DATA RACE" or "race detected during execution of test").
• No process crashes or OOM indicators in logs.

Ownership analysis:

• Failing test function: TestWorkspaceWatcher in coderd/workspaces_test.go (approx. lines 3372–3519 on main).
• Attempted to identify last modifier of the function; could not reliably establish function-level blame via API. Recent file contributors include multiple authors across unrelated areas.
• Leaving unassigned for now; tagging area: coderd/workspace events/agent lifecycle.

[spikecurtis]

Root cause here is that if we shut down the agent before the Tailnet is created, the routine can exit with an "agent is closing" error, which triggers preemptively tearing down the RPC connection to Coderd.