🤖 docs: contract for two backends sharing one Xum root

[ThomasK33]

Summary

Documents the cross-backend contract that the multi-backend fencing plan established, in one canonical code comment and one user-docs section. No product code changes.

Background

Last PR of the multi-backend fencing plan (#4727, #4754, #4762, #4772, #4783 merged). Two full backends can share one Xum root: the desktop app beside a xum server that started first (the desktop then skips only its API server), or any pair under XUM_ALLOW_MULTIPLE_INSTANCES=1. The earlier PRs made one rule hold; this PR writes it down where the next change will see it, and tells users what works when they run both apps.

Implementation

• processLiveness.ts: a CONCURRENT BACKENDS block next to the existing DEPLOYMENT CONTRACT. It states the rule, what is serialized across backends (config CAS, the history write lock, the lock kits including the workspace-turn live-owner locks), what stays per process (streams, Stop, owned attempts, busy guards, delegated-turn reservations), the two guarantees under misuse, and which writes the attempt fences cover (and that an already-running execution's own effects are not fenced), and what is not guaranteed (startup recovery of a live backend's active tasks, UIs not observing the other backend's writes, mixed versions 🤖 tests: finish cross-process lock hardening (holder in fileLock errors, macOS/Windows qualification, mixed versions) #4480).
• Pointers to it from the existing scope comments: WorkspaceService context-mutation admission guard, delegatedRootUnavailable (peer admission is a process-local courtesy, 🤖 fix: delegated-turn reservation is process-local, so unrelated admission can race across backend instances #4446), listInstanceWorkspaces (activity and delegated-turn state are this backend's), and the subagentAttemptSettlements.ts header.
• docs/config/server-access.mdx: new section "Running the desktop app and xum server together": what is shared, what stays consistent, what does not work across the two (including that an open chat does not see the other app's writes until reload), "do not drive one workspace or task from both at once", and the startup recovery caveat. That claim was verified in code: recoverInterruptedTasks re-queues starting tasks and re-drives running/awaiting_report tasks, guarded only by process-local isStreaming/isBusyForMessage.

Remaining gaps and the upgrade path (per-attempt live-owner lock, which would also complete #4545) are tracked in #4801, together with the two deferrals from #4772 and the init-status side finding from #4783's dogfood.

Validation

• make static-check-full passes, including mintlify broken-links.
• Rendered with the Mintlify dev preview (desktop and 390 px); screenshots below.

Risks

None at runtime (comments and docs only).

Refs #4446, #4311, #4545, #4801

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high • Cost: $54.64

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Mux	🟢 Ready	View Preview	Sep 27, 2026, 1:36 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T01:38:45.362118Z	90b5479	New commits
🔒 Security Review	✅ Completed 2026-09-27T01:39:20.051436Z	90b5479	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e6d31f130e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cc4a749a45

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

Readiness record for 90b5479:

• Reviews: 3 automatic Codex rounds. R1 3×P2 (doc accuracy: all recovered task states, stale UIs across backends, guarantee scoped to attempt-fenced writes) fixed; R2 1×P2 (stale embedded docs snapshot) regenerated; R3 clean with 👍.
• Checks: make static-check-full (incl. mintlify broken-links) passed locally; required CI green on this head. Page rendered in the Mintlify preview (screenshots in the description).
• Independent clean-context check: every claim verified against code; "ready with tracked follow-ups" (🤖 multi-backend: per-attempt live-owner lock and remaining cross-backend liveness gaps #4801, 🤖 feat: cross-process quiescence for renaming and deleting sub-agent task checkouts #4476, 🤖 tests: finish cross-process lock hardening (holder in fileLock errors, macOS/Windows qualification, mixed versions) #4480).
• Decision: ready.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high