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]

Shape looks right now, the three layers each do one job and the earlier duplication is gone. Just some small clean up left 🙏

Changelog. Still missing. The Unreleased section has no entry for the session ID or the state logs.

src/instrumentation/CONVENTIONS.md:9. The checklist says one instrumentation class per domain wrapping TelemetryService, and this PR replaces two such classes with the stateless recordWorkspaceState and recordAgentState functions. Either keep the methods but update the conventions or convert them into a class if there's some shared state that is useful.

[EhabY]

Looks great, thanks!