feat(workspace): log workspace and agent state changes

[aqandrew]

What

Add info-level logging of workspace, agent, and lifecycle status transitions so connection debugging has a record of state changes — correlated by the session ID from #1073.

This is Phase 3 of 3 for DEVEX-661 (RFC req 7). It builds on #1074.

Changes

State handling is split into three layers, one job each:

• detect — WorkspaceStateObserver / WorkspaceAgentObserver (src/instrumentation/workspace.ts) each detect a transition once and report a transition object. Stateful but effect-free (no logger/telemetry imports). The agent observer tracks every agent by ID and reports agents that disappear.
• record — recordWorkspaceState / recordAgentState emit the workspace.state_transitioned / workspace.agent.state_transitioned telemetry events.
• log — inline in WorkspaceMonitor.update(), with flat scalar payloads matching the repo's other log sites. Logs state observed on first sight, state changed afterward, and agent <name> removed when an agent disappears.

WorkspaceMonitor is now the single agent-observation site, so WorkspaceStateMachine no longer tracks agent telemetry.

Important

Telemetry data change. workspace.agent.state_transitioned now covers every agent for the whole monitored session (deduped per agent), rather than only the connected agent during connection setup. In practice most workspaces have one agent, so volume is unchanged; multi-agent workspaces and flaky connections emit more. There is no sampling in src/telemetry/, so this lands as-is. EVENTS.md is updated; heads-up to whoever owns the funnel queries.

Testing

• pnpm typecheck, targeted pnpm lint, full pnpm test (2456 passing).
• Unit tests cover observer detection (first observation, dedup, per-agent independence, removal, reset), the record* event shapes, and the monitor's inline logging (observed vs changed, agent transitions across all agents, agent removal).

Refactor design (reviewer's three-layer shape)

Per the review, the goal was to remove the duplication between the telemetry observers and the state loggers by making transition detection happen once:

• detect: pure-detection observers report a transition object; no logger or telemetry imports.
• record: recordWorkspaceState / recordAgentState in src/instrumentation/, telemetry only.
• log: inline in the monitor, same as every other logging call site.

This deletes both src/workspace/*Logger.ts files and leaves one tracker per concern.

Observer API decision: observers return a transition object (workspace → WorkspaceStateTransition | undefined; agents → { transitions, removed }) and WorkspaceMonitor.update() logs inline and calls record*. This was chosen over a constructor callback because observe() has a single synchronous caller, so a callback would only hide the side effects and complicate tests.

---

🤖 Generated by Coder Agents.

[linear-code]

DEVEX-661

DEVEX-666

[EhabY]

Should we include an entry in the changelog for the past 2 PRs + this? We only mention user-visible changes and these are worthy of it since it means sharing the logs or browsing them would give them an easy way to correlate logs to sessions. (also more logs so they can easily debug more)

[EhabY]

Nice cleanup, the split into two loggers resolves my second comment. My first one about duplication is only half done, and fixing it properly is the one structural change I'm after, left inline on workspaceMonitor.ts:145.

Shape I have in mind, three layers with one job each:

• detect: the observers, pure, no logger or telemetry imports, report a transition object
• record: recordWorkspaceState / recordAgentState in src/instrumentation/, telemetry only
• log: inline in the monitor, same as every other logging call site here

Sorry this got a bit out of hand, I saw an opportunity for some refactoring and unifying :)