A refused domain change or cluster edit explains why on the page, and Studio checks a domain change before sending it

[dawsontoth]

Refs #1686

Stacked on #1840: #1801 → #1802 → #1840 → this PR. Its base is claude/1800-bind-only-live-selection, so this diff is only the #1686 change. Review and merge the three below it first.

⊙ Problem

PUT /Cluster/{id} is the endpoint behind Bind, Unbind and the cluster edit page. In RUM it was refused 39 times out of 40 in one day, on one cluster, while three sessions retried across three pages (#1686). Studio gave them nothing to go on: each refusal was a toast that faded, and the domain changes sent a whole domainIds list built from whatever the page last cached, unchecked. That list is a replacement, and central manager unbinds every domain it leaves out, so a stale list also silently unbinds a domain another member bound meanwhile.

RUM has no response bodies, so which refusal #1686 hit isn't provable. The central-manager source narrows it. The only 400 that can block both a domain change and an edit is assertClusterMutable (updateCluster.js:69 → sharedHelpers.js:587-606): it refuses every update unless the cluster is RUNNING and no instance is FAILED or transitioning, and transitioning includes STOPPED. The session in #1686 stopped and restarted its containers mid-way, which fits, but it isn't confirmed. Hence Refs, not Closes: the root cause still needs the central-manager logs.

❓ Your call: is the pre-check worth keeping beside the inline reason? With the reason on the page, a user already sees central manager's own sentence. The pre-check stops the doomed request, names the domain rather than its id, and makes a stale-tick retry work at once. The cost is a hand-kept copy of central manager's instance-status list, written so it can only be narrower than central manager's.

💡 Solution

A refused change now says why, on the page, and Studio only sends a domain change central manager will accept, judged by a fresh read:

• Domain changes take intent and build the list fresh. Bind passes add, Unbind passes remove. The mutation re-reads the cluster and the organization's domains, and derives the new list from that read. A domain another tab or member bound meanwhile is kept.
• It refuses what central manager would refuse, before sending. The cluster isn't RUNNING, or an instance is FAILED or transitioning (central manager's TRANSITIONING_INSTANCE_STATES, STOPPED and UPDATED included). The cluster is self-managed. A domain the change touches is missing, unverified, or bound to another cluster, the cluster's existing ones included. It refuses rather than drops: central manager unbinds whatever the new list leaves out without checking which cluster holds it (updateCluster.js:199-205), so dropping a domain bound elsewhere would unbind it there. A refusal over a domain the cluster already lists points at support, because nothing on the page can clear it.
• Failures stay on the page. On the Domains page, a refused bind or unbind (Studio's refusal or central manager's own reason) stays under the toolbar until the next attempt. On the cluster edit page, the edit's failure stays beside the submit button. Both mutations drop the fading toast and report real request failures to RUM themselves; a refusal is not reported.

For example, a bind on a cluster with a stopped member now reads Instance node-1.example.com is STOPPED. This cluster's domains can change once every instance is running. and sends nothing. A refusal Studio can't foresee reads The domain change didn't go through: Cluster has an instance that is not RUNNING (…). Resolve the instance before the update.

⚖️ Alternatives

❓ Your call: the planning review returned better-alternative-exists, and I adopted its alternative. My plan kept #1801's whole-list contract and checked only the ids it sent against a fresh domain list. The reviewer's counterexample beats it: the list still came from the cached cluster, so a domain another member bound meanwhile passes every check and is silently unbound. The cost is a contract change under #1801: its cache write of the accepted list is gone, since every change now re-reads the cluster, and its test "builds the next change … even when re-reading the cluster fails" now asserts the change is refused. A list built on a cluster Studio couldn't read is the thing this PR stops sending.

• Fix it in central manager (validate before patching, compute removals from the domains' own clusterId, accept deltas): that is where the invariant belongs, and it is filed as HarperFast/central-manager#937. This task was Studio-only, and Studio has to show whatever central manager refuses with anyway.
• Only show the server's reason inline, no pre-check: smaller, but it keeps sending requests known to fail, and central manager names a foreign-bound or missing domain by raw id.
• Pre-check the edit page too: the version form deliberately allows a resubmit for a partial upgrade, and its submit gating spans two footers and the billing step. The inline reason covers a refusal there without a second copy of the gate.

🔧 Changes

• describeDomainChangeRefusal.ts (new): describeClusterNotChangeable mirrors assertClusterMutable and its status list, citing the source. describeUnsendableDomainChange checks every held, added and removed domain, plus the self-managed case.
• setDomainIdsOnCluster.ts: takes add / remove, reads the cluster and domains fresh, and writes them into the cache. It reads with the plain fetchers rather than through the query cache, whose error handler would toast a failed read a second time. It then refuses with a DomainChangeRefusedError, or derives the list and sends it. It skips the global toast and console.errors request failures at mutation level. Unbinding one custom domain no longer turns off certificates for the others #1801's cache write is removed.
• getOrganizationDomains.ts: exports the fetcher.
• Management.tsx: one mutation observer for Bind and Unbind. Unbind moves here from the table. The observer's error renders through SubmitErrorMessage, only for the cluster it was about, with Studio's refusals shown as written and anything else prefixed. Bind passes intent; its old cluster-status toast is replaced by the mutation's check. Invalidations use the active query client.
• tableDefinition.tsx: takes onUnbindClick instead of owning a second mutation, and wires it to the button; delete's invalidation uses the active query client.
• useUpdateCluster.ts: the edit mutation skips the global toast and reports its failure at mutation level.
• ClusterForm.tsx passes the edit's failure to the details/version footer in ClusterDetails.tsx and the billing footer in ClusterBilling.tsx, which render it beside the submit button. Create is unchanged.
• src/features/cluster/DESIGN.md, DESIGN.md: why a domain change is built and checked from a fresh read, and the index line.

✅ Verification

End-to-end route: not observable end-to-end here. It needs a central manager and a cluster with a stopped or transitioning member, and a bind changes real infrastructure. Verified at the request boundary against a mocked apiClient, with the test client wired to the app's own error handlers. The copied status list is only proven against central manager's source (cited in the code), not against a running one; a staging pass over Bind, Unbind and edit on such a cluster would close that. After deploy, @type:resource @resource.method:PUT @resource.url:*/Cluster/* 4xx counts should fall, since a refusal no longer sends the request.

• Management.test.tsx, new "a domain change central manager would refuse" block:
  • central manager's reason stays on the page for a refused bind and a refused unbind, with no toast, reported to RUM once;
  • the reason clears when the next change goes through;
  • nothing is sent while an instance is FAILED, STOPPED or UPDATED (the case isRunning gets wrong), or while the cluster isn't running; a change still goes through when every instance is running or gone;
  • a ticked domain the fresh list shows bound elsewhere is refused and stops being offered;
  • a cluster that still lists a missing domain refuses every change and points at support;
  • the list is built from the cluster as central manager has it, so a domain bound meanwhile is kept;
  • one cluster's failure doesn't show on another cluster's page;
  • a fresh read that fails sends nothing, shows once inline, toasts nothing, and reports once.
• Management.test.tsx, #1801's failed re-read test now asserts the change is refused, not sent.
• describeDomainChangeRefusal.test.ts (new): every mirrored status, FAILED, an unknown status passing through, and each domain case (missing, unverified, foreign-bound; held, added and removed; self-managed; adopting a domain bound here that the cluster doesn't list).
• ClusterForm.test.tsx (new): a refused edit's reason stays beside the button with no toast and one RUM report, and clears on resubmit; the billing footer shows it too.
• Fails on base: the 16 new or changed component tests fail against the origin/claude/1800-bind-only-live-selection sources. No inline message is ever rendered, and for the concurrent-writer case the PUT carries ['dom-a', 'dom-c'], dropping the domain bound meanwhile. The negative control (all instances running) passes on both. Every guard was mutation-checked, and its test goes red without it: the fresh cluster read, the mutability check, the domain check, both toast opt-outs, both RUM reports, the same-cluster filter, UPDATED in the list, the edit footer, and reading around the query cache.
• Gates (Node 24.21.0): npx vitest run 399 files / 3,738 passed (exit 0), npx tsc -b exit 0, npx oxlint --format stylish . exit 0, npx dprint check exit 0, and again by the pre-commit hook.

Pre-push review: a planning round (codex; verdict better-alternative-exists, adopted as above) and two full rounds (codex graded, gemini). The Harper-domain adjudicator failed on auth and the Cursor legs failed on the 1Password SSH agent every round, so no round converged. Round 1 found that a failed fresh read went through the query cache's toast handler and was reported twice (fixed: plain fetchers, and the test client now mirrors the app's handler). In round 2 codex ruled every earlier finding resolved and raised only comment nits. I rejected:

• "activeQueryClient is never declared in useDataTableColumns", a blocker (gemini, round 2): it's declared at tableDefinition.tsx:37, added in Bind on the Domains page sends only the domains still offered for binding #1840 and so outside this diff; tsc -b and the tests that render the table pass;
• "unbind invalidates the wrong client and key, so the domain stays bound until reload" (gemini, round 1): in production the module singleton is the provider's client, and [orgId] is a prefix of [orgId, 'domains']. I switched the moved lines to the active client anyway, for testability;
• the remaining comment nits (both legs): the kept comments state constraints the code can't (why the reads bypass the query cache, why the toast is off but RUM is not, why a queued click is refused, why the test router mock keeps one object).

Also filed: HarperFast/central-manager#937 (P2, Bug): updateCluster's domain branch can unbind another cluster's domain, strand a half-bound one, or throw on a deleted id. #1843 (P3, Bug): the Domains table's Remove tooltip never opens, because TooltipTrigger asChild wraps a fragment. It's pre-existing, and it's the React warning in these test runs.

_{🤖 Generated with Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: #1801 overlaps (stack base; this PR replaces its whole-list cache write), #1802 overlaps (stack base), #1840 overlaps (this PR's base), #1842 overlaps (both add ClusterForm.test.tsx; whichever lands second merges the file)
Complexity: complicated

_{Review-Coverage: authored=claude; ran=codex,gemini; blocked=cursor-grok(no-receipt),cursor-composer(no-receipt),domain(auth),cursor-muse(no-receipt); declined=cursor-kimi; rounds=2; full=1 @ ee2b5ba}

_{Review-Attention: study ~9m (raised: degraded review) @ ee2b5ba}

[gemini-code-assist]

Code Review

This pull request refactors the custom domain management flow to build and validate domain changes from a fresh read of the cluster and organization domains rather than relying on stale page state. It introduces client-side pre-validation (describeDomainChangeRefusal) to replicate central manager's mutability and domain checks, allowing Studio to present clear, actionable inline error messages (via SubmitErrorMessage) instead of generic 400 errors or fading toasts. Additionally, it updates the edit cluster forms and billing screens to display inline submission errors and adds comprehensive unit tests covering these refusal scenarios. I have no feedback to provide as there are no review comments to evaluate.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	68.93%	10364 / 15034
🔵	Statements	69.07%	11054 / 16004
🔵	Functions	62.46%	2686 / 4300
🔵	Branches	63.86%	7893 / 12359

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/cluster/domains/Management.tsx	81.05%	88.13%	85%	82.41%	99, 126, 234-260, 268, 274-275
src/features/cluster/domains/constants/tableDefinition.tsx	92.3%	86.2%	91.66%	94.59%	123, 156, 169
src/features/clusters/hooks/useUpdateCluster.ts	83.33%	100%	100%	83.33%	18
src/features/clusters/mutations/describeDomainChangeRefusal.ts	100%	90.9%	100%	100%
src/features/clusters/mutations/setDomainIdsOnCluster.ts	100%	90.9%	100%	100%
src/features/clusters/upsert/ClusterBilling.tsx	78.57%	52%	100%	78.57%	92-106
src/features/clusters/upsert/ClusterDetails.tsx	84.84%	56.36%	100%	83.87%	74-79, 83-88, 123-124, 195-264
src/features/clusters/upsert/ClusterForm.tsx	52.53%	30.72%	60.86%	53.33%	109-118, 123-127, 134-166, 210, 213-226, 230, 233, 262-271, 280-283, 294-297, 339-372, 382-389, 393-398, 411-441, 461-462, 468, 472
src/features/organization/queries/getOrganizationDomains.ts	100%	100%	100%	100%

Generated in workflow #2139 for commit ee2b5ba by the Vitest Coverage Report Action