browser/openspec/changes/fix-server-deployment-trigger/design.md

Context

The Platform already validates and dispatches POST /api/v1/server-instances/{id}/deploy; it accepts a draft or failed server only after its dedicated Run endpoint is registered. The server detail page exposes start, stop, and edit actions, but never calls that deployment API. As a result, a newly registered Run remains correctly idle and a failed server cannot be retried through the console.

Goals / Non-Goals

Goals:

• Make the existing deployment transition available to an authorized operator from the server detail header.
• Use the current server config version and a unique idempotency key, then display ordinary operation feedback and refresh state.
• Make the action unavailable while installation is already active or the state is not deployable.

Non-Goals:

• Do not change the backend API, deployment plan, Run protocol, SCUM install sequence, or automatic-start behavior.
• Do not expose protected directories, commands, tokens, or remote connectivity details.
• Do not change the separate build target / dedicated Run identity boundary.

Decisions

• Add the control beside existing lifecycle controls rather than auto-dispatching when a Run heartbeats. Registration proves connectivity only; automatic installation would make starting a downloaded executable perform a material remote write without a final operator action.
• Reuse platformApiClient.deployServerInstance rather than duplicating request logic. This preserves backend authorization, version fencing, idempotency, and job projection behavior.
• Reuse the existing operation store and refresh() callback so the detail page follows the same feedback pattern as start/stop and immediately shows the job state.

Risks / Trade-offs

• [A stale page submits an outdated version] → The backend's expectedConfigVersion check rejects it; the UI refreshes after the error.
• [Users mistake registration for completed installation] → The action label explicitly distinguishes Deploy from Start, and the queued job result is shown through the standard task feedback.
• [A duplicate click creates duplicate work] → A fresh idempotency key is submitted and the backend enforces its lifecycle idempotency rules.

Migration Plan

1. Deploy the frontend change with the existing Platform API.
2. Open a failed or draft server whose dedicated Run is online and select Deploy / Retry deploy.
3. Confirm the resulting install job is assigned to the dedicated endpoint. Rollback only removes the UI control; no data migration is required.

Open Questions

None.