Add graceful SCUM stop, restart, and version update flow

SCUM 停止/重启/更新以前只有“结束进程”这一条路，插件没有声明任何优雅关闭方式，平台也没有把停止后重新启动串起来。现在插件声明自己的关闭脚本，run 先执行它，平台在停止或更新成功后再自动拉起服务。 run: - lifecycle stop 支持插件声明的 gracefulStop（可执行文件、参数、环境、超时、 fallback=report|terminate）；关闭命令超时且声明 report 时任务失败，不再默默杀进程。 - 新增 steam.update 依赖探针：调用 steamcmd +app_info_print 获取公开分支 buildid，与本地 steamapps/appmanifest_<appid>.acf 的 buildid 比较，输出 installed/latest/update=yes|no|unknown。 platform: - 新增 POST /api/v1/server-instances/{id}/restart 与 /update。 - restart 派发插件 stop 动作（走优雅关闭），终态成功后入队 start 作业。 - update 派发插件 install 动作；插件在更新前必须先优雅关闭 SCUM，关闭失败直接拒绝 SteamCMD 更新，成功后平台再拉起服务。 - 依赖检查输入带上插件声明的服务器安装根目录，供 steam.update 读取 appmanifest。 plugin (SCUM server plugin 0.1.16): - bin/scum-stop.cmd：解析已声明的可执行文件路径，定位同路径正在运行的 SCUMServer.exe，通过本地 RCON 公告并发送关闭命令，等待进程自行退出；不再使用 taskkill。 - bin/scum-rcon.ps1：插件自有的 Source RCON 客户端，从 UE4SS mod config.ini 读取密码/端口，密钥不离开本机。 - actions/stop.json 声明 gracefulStop；actions/install.json 更新前先执行同一关闭脚本。 platform_web: - 服务器详情新增“重启”按钮和“SCUM 版本更新”面板；点“检查更新”查询公开分支版本，只有检测到更新时“更新版本”按钮才会置为可用并高亮，点击后先确认再派发更新任务。
2026-09-15 13:30:15 +08:00
parent 4ea27bda6a
commit 05f5a97ba9
39 changed files with 1197 additions and 56 deletions
@@ -172,7 +172,7 @@ func (svc *CoreService) GetDependencyExecutionInput(request domain.DependencyExe
 	if err != nil {
 		return domain.DependencyExecutionInput{}, err
 	}
-	return domain.CopyDependencyExecutionInput(domain.DependencyExecutionInput{JobID: job.ID, ServerInstanceID: job.ServerInstanceID, RunEndpointID: job.RunEndpointID, PluginID: resolution.plugin.ID, PluginVersion: resolution.plugin.Version, ProfileKey: resolution.binding.ProfileKey, TargetOS: resolution.endpoint.Platform, TargetArch: resolution.endpoint.Architecture, PlanDigest: digest, Probe: probe, Plan: plan, Bindings: bindings}), nil
+	return domain.CopyDependencyExecutionInput(domain.DependencyExecutionInput{JobID: job.ID, ServerInstanceID: job.ServerInstanceID, RunEndpointID: job.RunEndpointID, PluginID: resolution.plugin.ID, PluginVersion: resolution.plugin.Version, ProfileKey: resolution.binding.ProfileKey, TargetOS: resolution.endpoint.Platform, TargetArch: resolution.endpoint.Architecture, PlanDigest: digest, ServerRoot: strings.TrimSpace(resolution.instance.Deployment.ServerRoot), Probe: probe, Plan: plan, Bindings: bindings}), nil
 }

 func (svc *CoreService) GetRunUpdateInput(request domain.RunUpdateInputRequest) (domain.RunUpdateInput, error) {
@@ -304,3 +304,31 @@ func dependencyUpdateHello(instance domain.ServerInstance) domain.RunControlHell
 		Capacity:          domain.RunCapacity{MaxJobs: 2},
 	}
 }
+
+func TestDependencyInputCarriesDeclaredServerInstallRoot(t *testing.T) {
+	svc, session, instance := newDistributionTestFixture(t)
+	instance.Deployment.ServerRoot = "C:/scumserver"
+	if err := svc.store.ServerInstances().Update(instance); err != nil {
+		t.Fatalf("set deployment server root: %v", err)
+	}
+	catalog, err := svc.GetDependencyCatalogForSession(session, instance.ID)
+	if err != nil {
+		t.Fatalf("dependency catalog: %v", err)
+	}
+	job, err := svc.QueueDependencyJobForSession(session, domain.DependencyJobRequest{ServerInstanceID: instance.ID, ProbeKey: catalog.Probes[0].Key, IdempotencyKey: "dependency-install-root"})
+	if err != nil {
+		t.Fatalf("queue dependency check: %v", err)
+	}
+	runSession := registerDependencyUpdateRun(t, svc, instance)
+	claim, err := svc.ClaimRunJob(domain.RunJobClaim{RunEndpointID: instance.RunEndpointID, SessionToken: runSession, Capabilities: []string{domain.JobCapabilityDependenciesCheck}, Capacity: domain.RunCapacity{MaxJobs: 1}})
+	if err != nil || !claim.HasJob || claim.Job.JobID != job.ID {
+		t.Fatalf("claim dependency check: claim=%+v err=%v", claim, err)
+	}
+	input, err := svc.GetDependencyExecutionInput(domain.DependencyExecutionInputRequest{RunEndpointID: instance.RunEndpointID, SessionToken: runSession, JobID: claim.Job.JobID, LeaseToken: claim.Job.LeaseToken, Attempt: claim.Job.Attempt})
+	if err != nil {
+		t.Fatalf("dependency input: %v", err)
+	}
+	if input.ServerRoot != "C:/scumserver" {
+		t.Fatalf("expected dependency input to carry the declared server install root, got %q", input.ServerRoot)
+	}
+}
@@ -323,7 +323,7 @@ func autonomousBootstrapLifecycleAction(plugin domain.GamePlugin, profile domain
 }

 func autonomousDependencyProbe(probe domain.RuntimeDependencyProbe) domain.RunAutonomousDependencyProbe {
-	return domain.RunAutonomousDependencyProbe{Key: probe.Key, Kind: probe.Kind, TargetKey: probe.TargetKey, Required: probe.Required, MinimumVersion: probe.MinimumVersion, Platforms: domain.CopyStringSlice(probe.Platforms)}
+	return domain.RunAutonomousDependencyProbe{Key: probe.Key, Kind: probe.Kind, TargetKey: probe.TargetKey, Required: probe.Required, MinimumVersion: probe.MinimumVersion, SteamAppID: probe.SteamAppID, Platforms: domain.CopyStringSlice(probe.Platforms)}
 }

 func autonomousInstallPlan(plan domain.RuntimeInstallPlan) domain.RunAutonomousInstallPlan {
@@ -100,6 +100,8 @@ type Core interface {
 	StartServerInstanceForSession(string, domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
 	StopServerInstance(domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
 	StopServerInstanceForSession(string, domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
+	RestartServerInstanceForSession(string, domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
+	UpdateServerGameForSession(string, domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
 	QueryServerInstanceProcessForSession(string, domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error)
 	GetServerInstance(string) (domain.ServerInstance, error)
 	GetServerInstanceForSession(string, string) (domain.ServerInstance, error)
@@ -1194,7 +1196,7 @@ func (svc *CoreService) executeBridgeJobDispatch(sessionID string, base domain.P
 		return base
 	}
 	lifecycleAction := domain.ServerLifecycleAction(strings.TrimSpace(payload["lifecycleAction"]))
-	if lifecycleAction == domain.ServerLifecycleActionStart || lifecycleAction == domain.ServerLifecycleActionStop {
+	if lifecycleAction == domain.ServerLifecycleActionStart || lifecycleAction == domain.ServerLifecycleActionStop || lifecycleAction == domain.ServerLifecycleActionRestart || lifecycleAction == domain.ServerLifecycleActionUpdate {
 		expectedVersion, _ := strconv.Atoi(payload["expectedConfigVersion"])
 		command := domain.ServerLifecycleCommand{
 			ServerInstanceID:      instance.ID,
@@ -1218,6 +1220,20 @@ func (svc *CoreService) executeBridgeJobDispatch(sessionID string, base domain.P
 				return base
 			}
 			result, err = svc.StopServerInstanceForSession(sessionID, command)
+		case domain.ServerLifecycleActionRestart:
+			if capability != domain.LifecycleCapabilityStop {
+				base.Status = "denied"
+				base.Error = &domain.PluginBridgeSafeError{Code: "capability_denied", Message: "lifecycle action must match requested capability"}
+				return base
+			}
+			result, err = svc.RestartServerInstanceForSession(sessionID, command)
+		case domain.ServerLifecycleActionUpdate:
+			if capability != domain.LifecycleCapabilityInstall {
+				base.Status = "denied"
+				base.Error = &domain.PluginBridgeSafeError{Code: "capability_denied", Message: "lifecycle action must match requested capability"}
+				return base
+			}
+			result, err = svc.UpdateServerGameForSession(sessionID, command)
 		}
 		if err != nil {
 			return bridgeExecutionError(base, err)
@@ -212,6 +212,34 @@ func (svc *CoreService) StopServerInstanceForSession(sessionID string, command d
 	return svc.StopServerInstance(command)
 }

+// RestartServerInstanceForSession queues the plugin-declared graceful stop and
+// records restart intent. Run executes the stop action; the terminal stop
+// result dispatches the plugin-declared start action for the same instance.
+func (svc *CoreService) RestartServerInstanceForSession(sessionID string, command domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error) {
+	if err := svc.authorizeServerLifecycle(sessionID, command.ServerInstanceID); err != nil {
+		return domain.ServerLifecycleResult{}, err
+	}
+	return svc.dispatchExistingServerLifecycle(command, domain.ServerLifecycleActionRestart, []domain.ServerInstanceState{
+		domain.ServerInstanceStateRunning,
+		domain.ServerInstanceStateStopped,
+	})
+}
+
+// UpdateServerGameForSession queues the plugin-declared install/update action.
+// The plugin script stops the running server gracefully before SteamCMD touches
+// server files, and the terminal update result starts the server again.
+func (svc *CoreService) UpdateServerGameForSession(sessionID string, command domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error) {
+	if err := svc.authorizeServerLifecycle(sessionID, command.ServerInstanceID); err != nil {
+		return domain.ServerLifecycleResult{}, err
+	}
+	return svc.dispatchExistingServerLifecycle(command, domain.ServerLifecycleActionUpdate, []domain.ServerInstanceState{
+		domain.ServerInstanceStateRunning,
+		domain.ServerInstanceStateStopped,
+		domain.ServerInstanceStateReady,
+		domain.ServerInstanceStateFailed,
+	})
+}
+
 func (svc *CoreService) QueryServerInstanceProcessForSession(sessionID string, command domain.ServerLifecycleCommand) (domain.ServerLifecycleResult, error) {
 	if err := svc.authorizeServerLifecycle(sessionID, command.ServerInstanceID); err != nil {
 		return domain.ServerLifecycleResult{}, err
@@ -418,6 +446,10 @@ func lifecycleExecutionOperation(action domain.ServerLifecycleAction) string {
 		return "start"
 	case domain.ServerLifecycleActionStop:
 		return "stop"
+	case domain.ServerLifecycleActionRestart:
+		return "restart"
+	case domain.ServerLifecycleActionUpdate:
+		return "update"
 	case domain.ServerLifecycleActionStatus:
 		return "status"
 	default:
@@ -431,8 +463,10 @@ func runtimeProfileActionRef(actions domain.PluginLifecycleActions, action domai
 		return actions.Install
 	case domain.ServerLifecycleActionStart:
 		return actions.Start
-	case domain.ServerLifecycleActionStop:
+	case domain.ServerLifecycleActionStop, domain.ServerLifecycleActionRestart:
 		return actions.Stop
+	case domain.ServerLifecycleActionUpdate:
+		return actions.Install
 	case domain.ServerLifecycleActionStatus:
 		return actions.Status
 	default:
@@ -502,8 +536,10 @@ func lifecycleActionRef(plugin domain.GamePlugin, action domain.ServerLifecycleA
 		return plugin.LifecycleActions.Install
 	case domain.ServerLifecycleActionStart:
 		return plugin.LifecycleActions.Start
-	case domain.ServerLifecycleActionStop:
+	case domain.ServerLifecycleActionStop, domain.ServerLifecycleActionRestart:
 		return plugin.LifecycleActions.Stop
+	case domain.ServerLifecycleActionUpdate:
+		return plugin.LifecycleActions.Install
 	case domain.ServerLifecycleActionStatus:
 		return plugin.LifecycleActions.Status
 	default:
@@ -1,6 +1,7 @@
 package service

 import (
+	"log"
 	"strings"
 	"time"

@@ -113,9 +114,39 @@ func (svc *CoreService) projectLifecycleJobResult(job domain.Job, stamp time.Tim
 		return err
 	}
 	svc.publishLogProcessState(instance)
+	svc.dispatchFollowUpLifecycle(job, instance)
 	return nil
 }

+// dispatchFollowUpLifecycle starts the server again after a declared graceful
+// stop or a completed game update. A failed or cancelled stop/update leaves the
+// instance in its projected state so the operator sees the failure before any
+// start is attempted.
+func (svc *CoreService) dispatchFollowUpLifecycle(job domain.Job, instance domain.ServerInstance) {
+	if job.State != domain.JobStateSucceeded {
+		return
+	}
+	operation := job.ExecutionInput.LifecycleOperation
+	if operation != string(domain.ServerLifecycleActionRestart) && operation != string(domain.ServerLifecycleActionUpdate) {
+		return
+	}
+	command := domain.ServerLifecycleCommand{
+		ServerInstanceID:      instance.ID,
+		ExpectedConfigVersion: instance.ConfigVersion,
+		IdempotencyKey:        job.IdempotencyKey + ":start",
+	}
+	result, err := svc.dispatchExistingServerLifecycle(command, domain.ServerLifecycleActionStart, []domain.ServerInstanceState{
+		domain.ServerInstanceStateReady,
+		domain.ServerInstanceStateStopped,
+		domain.ServerInstanceStateFailed,
+	})
+	if err != nil {
+		log.Printf("PLATFORM phase=lifecycle status=follow_up_failed operation=%s server=%s error=%s", safeLogValue(operation), safeLogValue(instance.ID), safeLogValue(err.Error()))
+		return
+	}
+	log.Printf("PLATFORM phase=lifecycle status=follow_up_queued operation=%s server=%s job=%s", safeLogValue(operation), safeLogValue(instance.ID), safeLogValue(result.Job.ID))
+}
+
 func (svc *CoreService) projectServerDeploymentProgress(job domain.Job, stamp time.Time) error {
 	if job.ExecutionInput.Deployment == nil || job.ServerInstanceID == "" {
 		return nil
@@ -534,3 +534,214 @@ func claimAndCompleteLifecycleJobForServer(t *testing.T, svc *CoreService, sessi
 		t.Fatalf("complete lifecycle job %s: %v", capability, err)
 	}
 }
+
+func TestCoreServiceRestartLifecycleQueuesDeclaredStopThenStart(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "lifecycle-operator", DisplayName: "Lifecycle Operator", Email: "lifecycle-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-restart")
+
+	restarted, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{
+		ServerInstanceID:      instance.ID,
+		ExpectedConfigVersion: instance.ConfigVersion,
+		IdempotencyKey:        "idem-restart",
+	})
+	if err != nil {
+		t.Fatalf("restart lifecycle workflow: %v", err)
+	}
+	if restarted.Action != domain.ServerLifecycleActionRestart || restarted.Job.Capability != domain.LifecycleCapabilityStop || restarted.Job.TargetKey != "actions/stop.json" {
+		t.Fatalf("expected restart to queue the plugin-declared stop action, got %+v", restarted)
+	}
+	if restarted.Job.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionRestart) {
+		t.Fatalf("expected restart intent on the queued job, got %+v", restarted.Job.ExecutionInput)
+	}
+	if _, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart); ok {
+		t.Fatal("restart must not queue a start job before the declared stop result lands")
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStop, domain.JobStateSucceeded)
+	stopped, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get stopped instance: %v", err)
+	}
+	if stopped.State != domain.ServerInstanceStateStopped {
+		t.Fatalf("expected graceful stop result to project stopped, got %+v", stopped)
+	}
+
+	startJob, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart)
+	if !ok {
+		t.Fatal("expected a follow-up start job after the graceful stop succeeded")
+	}
+	if startJob.TargetKey != "actions/start.json" || startJob.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionStart) || startJob.IdempotencyKey != "idem-restart:start" {
+		t.Fatalf("unexpected follow-up start job: %+v", startJob)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get restarted instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected restart to return the server to running, got %+v", running)
+	}
+}
+
+func TestCoreServiceUpdateLifecycleQueuesInstallThenStart(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "update-operator", DisplayName: "Update Operator", Email: "update-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-update")
+
+	updated, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{
+		ServerInstanceID:      instance.ID,
+		ExpectedConfigVersion: instance.ConfigVersion,
+		IdempotencyKey:        "idem-update",
+	})
+	if err != nil {
+		t.Fatalf("update lifecycle workflow: %v", err)
+	}
+	if updated.Action != domain.ServerLifecycleActionUpdate || updated.Job.Capability != domain.LifecycleCapabilityInstall || updated.Job.TargetKey != "actions/install.json" {
+		t.Fatalf("expected update to queue the plugin-declared install action, got %+v", updated)
+	}
+	if updated.Job.ExecutionInput.LifecycleOperation != string(domain.ServerLifecycleActionUpdate) {
+		t.Fatalf("expected update intent on the queued job, got %+v", updated.Job.ExecutionInput)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	startJob, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart)
+	if !ok {
+		t.Fatal("expected a follow-up start job after the game update succeeded")
+	}
+	if startJob.IdempotencyKey != "idem-update:start" {
+		t.Fatalf("unexpected follow-up start job: %+v", startJob)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get updated instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected update to start the server again, got %+v", running)
+	}
+}
+
+func TestCoreServiceRestartAndUpdateRespectLifecycleState(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "state-operator", DisplayName: "State Operator", Email: "state-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	if _, err := svc.CreateServerInstanceWorkflow(domain.ServerLifecycleCreate{ID: "server-installing", PluginID: "server.scum", RunEndpointID: "run-local", Name: "SCUM installing", IdempotencyKey: "installing-create", ProfileKey: "local"}); err != nil {
+		t.Fatalf("create installing instance: %v", err)
+	}
+	installing, err := svc.GetServerInstance("server-installing")
+	if err != nil {
+		t.Fatalf("get installing instance: %v", err)
+	}
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: installing.ID, ExpectedConfigVersion: installing.ConfigVersion, IdempotencyKey: "idem-restart-installing"}); err == nil || !strings.Contains(err.Error(), "cannot restart") {
+		t.Fatalf("expected restart state rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: installing.ID, ExpectedConfigVersion: installing.ConfigVersion, IdempotencyKey: "idem-update-installing"}); err == nil || !strings.Contains(err.Error(), "cannot update") {
+		t.Fatalf("expected update state rejection, got %v", err)
+	}
+
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, installing.ID, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	ready, err := svc.GetServerInstance(installing.ID)
+	if err != nil {
+		t.Fatalf("get ready instance: %v", err)
+	}
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: ready.ID, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: "idem-restart-ready"}); err == nil || !strings.Contains(err.Error(), "cannot restart") {
+		t.Fatalf("expected ready state restart rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: ready.ID, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: "idem-update-ready"}); err != nil {
+		t.Fatalf("ready server should accept a game update dispatch: %v", err)
+	}
+}
+
+func TestCoreServiceFailedGracefulStopDoesNotStartServer(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "failure-operator", DisplayName: "Failure Operator", Email: "failure-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-restart-failure")
+
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-restart-failure"}); err != nil {
+		t.Fatalf("restart lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, instance.ID, domain.LifecycleCapabilityStop, domain.JobStateFailed)
+	if _, ok := queuedLifecycleJob(t, svc, instance.ID, domain.LifecycleCapabilityStart); ok {
+		t.Fatal("a failed graceful stop must not queue a start job")
+	}
+	failed, err := svc.GetServerInstance(instance.ID)
+	if err != nil {
+		t.Fatalf("get failed instance: %v", err)
+	}
+	if failed.State != domain.ServerInstanceStateFailed {
+		t.Fatalf("expected failed stop to project failed, got %+v", failed)
+	}
+}
+
+func TestCoreServiceRestartAndUpdateRequireEndpointCapabilities(t *testing.T) {
+	svc, runSession := newLifecycleRunService(t)
+	createLifecyclePlugin(t, svc)
+	operator := createServiceUserAndLogin(t, svc, domain.User{ID: "capability-operator", DisplayName: "Capability Operator", Email: "capability-operator@example.test", Roles: []string{"platform-admin"}, PasswordHash: "secret-password"})
+	instance := runningLifecycleInstanceForTest(t, svc, runSession, "server-capability")
+
+	endpoint, err := svc.store.RunEndpoints().Get("run-local")
+	if err != nil {
+		t.Fatalf("get lifecycle endpoint: %v", err)
+	}
+	remaining := make([]string, 0, len(endpoint.Capabilities))
+	for _, capability := range endpoint.Capabilities {
+		if capability != domain.LifecycleCapabilityStop && capability != domain.LifecycleCapabilityInstall {
+			remaining = append(remaining, capability)
+		}
+	}
+	endpoint.Capabilities = remaining
+	if err := svc.store.RunEndpoints().Update(endpoint); err != nil {
+		t.Fatalf("remove lifecycle capabilities: %v", err)
+	}
+
+	if _, err := svc.RestartServerInstanceForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-restart-capability"}); err == nil || !strings.Contains(err.Error(), domain.LifecycleCapabilityStop) {
+		t.Fatalf("expected missing stop capability rejection, got %v", err)
+	}
+	if _, err := svc.UpdateServerGameForSession(operator, domain.ServerLifecycleCommand{ServerInstanceID: instance.ID, ExpectedConfigVersion: instance.ConfigVersion, IdempotencyKey: "idem-update-capability"}); err == nil || !strings.Contains(err.Error(), domain.LifecycleCapabilityInstall) {
+		t.Fatalf("expected missing install capability rejection, got %v", err)
+	}
+}
+
+func runningLifecycleInstanceForTest(t *testing.T, svc *CoreService, runSession string, id string) domain.ServerInstance {
+	t.Helper()
+	if _, err := svc.CreateServerInstanceWorkflow(domain.ServerLifecycleCreate{ID: id, PluginID: "server.scum", RunEndpointID: "run-local", Name: "SCUM " + id, IdempotencyKey: id + "-create", ProfileKey: "local"}); err != nil {
+		t.Fatalf("create lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, id, domain.LifecycleCapabilityInstall, domain.JobStateSucceeded)
+	ready, err := svc.GetServerInstance(id)
+	if err != nil {
+		t.Fatalf("get ready instance: %v", err)
+	}
+	if _, err := svc.StartServerInstance(domain.ServerLifecycleCommand{ServerInstanceID: id, ExpectedConfigVersion: ready.ConfigVersion, IdempotencyKey: id + "-start"}); err != nil {
+		t.Fatalf("start lifecycle workflow: %v", err)
+	}
+	claimAndCompleteLifecycleJobForServer(t, svc, runSession, id, domain.LifecycleCapabilityStart, domain.JobStateSucceeded)
+	running, err := svc.GetServerInstance(id)
+	if err != nil {
+		t.Fatalf("get running instance: %v", err)
+	}
+	if running.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected running instance, got %+v", running)
+	}
+	return running
+}
+
+func queuedLifecycleJob(t *testing.T, svc *CoreService, serverInstanceID string, capability string) (domain.Job, bool) {
+	t.Helper()
+	jobs, err := svc.store.Jobs().List(domain.JobFilter{ServerInstanceID: serverInstanceID, State: domain.JobStateQueued})
+	if err != nil {
+		t.Fatalf("list jobs: %v", err)
+	}
+	for _, job := range jobs {
+		if job.Capability == capability {
+			return job, true
+		}
+	}
+	return domain.Job{}, false
+}