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 :)

[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]

Both reset() methods are dead, this one and :177. Nothing in src/ calls either; the only callers are test/unit/workspace/observers.test.ts:106 and :211. Delete both methods and their two tests, since buildStartedAtMs and the maps now live and die with the monitor.

[EhabY]

previous and names (:132) always hold the same keys: a first sight always reports a transition, so both get set together, and the removal loop deletes from both. Fold the name into the state and drop names:

interface ObservedAgentState {
	readonly name: string;
	readonly status: WorkspaceAgentStatus;
	readonly lifecycleState: WorkspaceAgentLifecycle;
	readonly observedAtMs: number;
}

The removal loop then iterates previous. One caveat: a rename with no state change keeps the old name, which can't happen without a rebuild handing out new IDs.

[EhabY]

RemovedAgent wraps a single name. Make it readonly removed: string[], so the monitor reads for (const name of removed) and the test asserts ["second"]. Also no need to export if this is only used internally

[EhabY]

AgentStateTransition is the last nested payload left. Both consumers flatten it on arrival. Put statusFrom, statusTo, lifecycleFrom, and lifecycleTo on the transition itself.

[EhabY]

buildStartedAtMs is set only while provisioning and cleared as soon as it isn't, so wasProvisioning is exactly buildStartedAtMs !== undefined and both locals can go:

let buildDurationMs: number | undefined;
if (PROVISIONING_STATUSES.has(status)) {
	this.buildStartedAtMs ??= now;
} else if (this.buildStartedAtMs !== undefined) {
	buildDurationMs = now - this.buildStartedAtMs;
	this.buildStartedAtMs = undefined;
}

[EhabY]

Same ternary at :170. One module-level helper covers both and reads better at the call site:

const stateVerb = (from: string | undefined) =>
	from === undefined ? "state observed" : "state changed";

[EhabY]

This block now re-tests the observers. Dedup on reason (:132), build-duration resolution (:173), and the duration measurements (:96) are all observer behavior, and observers.test.ts:56, :75, and :90 cover each of them directly. Now that detection lives in one place, keep the monitor tests on wiring only: the first update logs and records once, a later change logs and records again. That drops roughly 100 lines of triple coverage.

[EhabY]

WorkspaceStateObserver has "reports a change when only transition or reason changes" (:75), but the agent side never changes lifecycle on its own. Add the symmetric case: same status, new lifecycle_state, one transition reported.

[EhabY]

agentWorkspace here and workspaceWith at observers.test.ts:21 are the same builder, and this one types its agents as Array<Parameters<typeof createAgent>[0]>. Move one into the shared test mocks and have it take WorkspaceAgent[].

[EhabY]

Also at :330. These hand-roll { type: "data", data } instead of using the file's own workspaceEvent helper (:34). Let that helper take a Workspace as well.