ADR-0003: MCP writes to live-edited pages are rejected

Status: accepted · Date: 2026-08-28

Decision

update_page over MCP refuses to write while the collab service holds an in-memory room for the target page (checked via the collab service’s /rooms/:ws/:page/active probe). The caller gets a clear retryable error; when no room is live, the write replaces current.json, deletes the stale collab.yupdate so the next room seeds from the new JSON, and records an api-source revision.

Context

PLAN Phase 6 required an explicit choice: reject, or apply API writes as Yjs updates through the collab service. A live room’s in-memory Y.Doc is the authority while editors are connected; writing beneath it silently loses whichever side checkpoints last.

Alternatives considered

• Apply as a Yjs transaction through collab: preserves both edits, but replacing a whole document via fragment surgery is error-prone, and “the agent rewrote the page under my cursor” is worse UX than a retry.

Consequences

• Agents see a deterministic, explainable failure and can retry when the session ends; humans never lose live edits to an API write.
• If the collab service is unreachable the guard fails open (no rooms can be live if collab is down).
• Revisit alongside range-anchored comments if partial/append API edits are ever needed — those would go through collab as true Yjs updates.