browser/openspec/changes/allow-forced-server-deletion/design.md

Context

Server deletion is currently a password-confirmed soft delete, but active states (running and installing) are always rejected. That protects against orphaning live runtime work, but it also traps operators when the platform state is stale, the run endpoint is gone, or a lifecycle job cannot complete.

The platform/run boundary matters here: platform can mark metadata deleted, but it must not invent game-specific stop behavior or directly manage host processes outside plugin-owned lifecycle jobs.

Goals / Non-Goals

Goals:

• Let an owner or platform administrator force-delete a running or installing instance when they explicitly accept the operational risk.
• Keep password confirmation mandatory for normal and forced deletion.
• Preserve soft-delete history and current list filtering behavior.
• Make forced deletion visible and deliberate in the UI.

Non-Goals:

• Hard-deleting server metadata or historical records.
• Killing, stopping, or cleaning up a remote process as part of delete.
• Adding run-side force-kill behavior, game-specific cleanup, or deployment target changes.
• Allowing non-owners or non-admins to delete servers.

Decisions

• Extend the existing DELETE /api/v1/server-instances/{id} JSON body with force and confirmation fields. The existing route keeps one destructive API surface, while older clients still get the default safe rejection for running/installing instances.
• Require force: true plus a fixed confirmation phrase for running or installing instances. This separates accidental password-only deletion from intentional cleanup of stuck active instances.
• Keep backend enforcement in DeleteServerInstanceForSession. The frontend can guide the operator, but the service must remain the source of truth.
• Treat forced deletion as metadata-only. The server state becomes deleted; run jobs, logs, artifacts, and audit history remain visible through existing historical paths where supported.
• Show force confirmation only when the selected instance is running or installing, and keep the delete entry in the existing compact server-card action menu.

Risks / Trade-offs

• [Risk] A forced delete can hide a server whose process is still alive. -> Mitigation: confirmation copy states that delete is metadata-only and does not stop the process.
• [Risk] Operators may use force instead of stopping cleanly. -> Mitigation: normal delete remains the default for stopped/ready/failed servers; active states require explicit force confirmation.
• [Risk] Existing clients may omit the new fields. -> Mitigation: the backend keeps the current rejection unless force confirmation is present.