feat: add MCP discovery phase and agent run id to context sync - #29449

Stack context

This stack replaces #29114 after review feedback that a single mcp_settled bool was underdeveloped and the change too large to review. It defines how workspace MCP discovery is communicated from the agent to chats: the agent publishes one discovery report inside the existing context snapshot (PushContextState), coderd persists it atomically with the resources, and chatd, find_tools, the create/start workspace tools, and the chat context UI all consume that same committed report.

The report has three parts. Completeness: MCPDiscovery.phase is PENDING until the agent's initial MCP reload has finished (success, failure, or zero servers all count) and COMPLETE afterwards for the rest of the process; later reloads update outcomes but never move it back. Per-source outcomes stay on the existing ContextResource rows: mcp_config rows carry structural and semantic config errors, mcp_server rows carry discovered servers (including zero tools), failed servers with a sanitized error, and a retained previous connection as OK plus a warning. Freshness: every snapshot carries the agent_run_id of the process that produced it, and the agent reports the same id in Startup, so a snapshot is known to describe the current process when the two ids match. Timestamps are deliberately not used for freshness because ready_at is agent clock and received_at is coderd clock.

Discovery completeness, per-source outcomes, turn eligibility, and the result of an actual tool invocation stay separate facts. Out of scope: continuous health monitoring, reconnect detection, automatic retries, and any retry or reload UI.

Layers, bottom to top: #29448 agent diagnostics, #29449 protocol and persistence, #29450 agent publication, #29451 chat projection, #29452 first-turn gate, #29453 context UI. Each layer builds and passes its tests on its own. The composed stack was validated end to end with remote UAT; the record is on #29453.

Why

coderd had no way to know whether an agent's MCP discovery had finished, and no way to tell whether a stored snapshot described the agent process that is running now. Both are needed before chatd can wait for discovery or withhold a previous process's tool definitions.

Fix

Protocol: PushContextStateRequest gains agent_run_id and a nested MCPDiscovery message with a Phase enum (PHASE_UNSPECIFIED, PENDING, COMPLETE); Startup gains agent_run_id. The run id is a UUID generated once per agent process, stable across RPC reconnects and different after a restart. Legacy agents leave both empty, which means "no guarantee". UpdateStartup rejects a run id above the same 64-byte cap the push path enforces.

Persistence: migration 000596 adds workspace_agents.agent_run_id, workspace_agent_context_snapshots.agent_run_id, and workspace_agent_context_snapshots.mcp_discovery_phase (new enum workspace_agent_mcp_discovery_phase). UpdateStartup always overwrites the agent row's run id (empty for legacy agents). PushContextState persists the run id and phase in the same transaction as the resources, and ignores a push whose run id differs from the agent row's non-empty run id, because within one process UpdateStartup always precedes the first push, so such a push can only come from a previous process. That includes a push with an empty run id: a current legacy process clears the row in UpdateStartup, so a non-empty row means a newer process has registered since. The handler also reports whether the phase or run id changed so the next layer can notify chats on phase-only transitions; this layer only plumbs that flag.

No agent behavior changes here; the agent starts sending these fields in #29450.

Testing

coderd/agentapi tests cover round trips of phase and run id, unspecified phase for requests without the message, stale-run rejection leaving the row untouched, same-run acceptance, empty-run acceptance against an empty row and rejection against a non-empty row, and UpdateStartup overwriting the run id including to empty. Database tests cover the new columns. Remote UAT of the composed stack is recorded on #29453.

Review record

• Codex review 1, requested 2026-09-17 04:29 UTC on 679a4c1d0e: 1 finding. P2 empty request run id skipped the agent row check and accepted a known-stale legacy push: confirmed, fixed; TestPushContextState/MCPDiscovery/LegacyRequestAfterCurrentRunDropped failed on the old code and passes now.
• Codex review 2, requested 2026-09-17 05:37 UTC on 7fd79c77ac: 3 findings. P2 agent row not locked during the run id check: declined with the window analysis (a late push from the previous process is read as stale until the new process's initial push replaces it); the comment is corrected. P2 rolling-deployment invalidation: declined, Coder upgrades happen in scheduled downtime, not rolling. P2 unbounded run id in UpdateStartup: confirmed, fixed (TestUpdateStartup/OversizedRunID).
• Codex review 3, requested 2026-09-17 06:14 UTC on e12f99df94: 1 finding. P2 agent row not locked during the run id check, re-raised via the chat row copy: declined; a push that commits after UpdateStartup leaves the same state as a push committed just before the restart (a lock would only reorder the two), a fresher snapshot cannot be overwritten because both pushes write the same row under repeatable read, and every tool-building reader of the chat rows in this stack goes through feat: project MCP discovery state and freshness into chat context #29451's run id comparison.
• Codex review 4, requested 2026-09-17 06:42 UTC on c1910f133c: no findings on c1910f133c. The UpdateStartup comment on how chatd reads an empty run id was then adjusted to match feat: project MCP discovery state and freshness into chat context #29451.
• Codex review 5, requested 2026-09-17 07:17 UTC on 69b5d2d5cd: 1 finding. P2 a superseded process reconnecting could reclaim the agent row through UpdateStartup: declined, two live processes on one agent token is not a supported configuration (restart ends the previous process, rebuild gives the replacement its own row), and a legacy rollback is the case the run id rule already reads as stale.
• Codex review 6, requested 2026-09-17 07:54 UTC on 1bc859a218: no findings on 1bc859a218.
• Codex review 7, requested 2026-09-17 08:26 UTC on cf21c917d0: no findings on cf21c917d0.
• Codex review 8 requested on c5138256dd: pending.

This PR was authored by Xum on behalf of @ibetitsmike.