Show agent restart prompt after CLI registration

Author: rodion-m

Sources/App/Services/UISmokeRunner.swift

@@ -167,6 +167,9 @@ enum UISmokeRunner {
         let restartNotice = AgentRestartNotice.afterCLIRegistration(cliName: "hcloud", shimInstalled: true)
         try expect(restartNotice.contains("Restart Codex"), "register success notice names the agent restart action")
         try expect(AgentRestartNotice.requiresManualDismiss(restartNotice), "agent restart notice stays visible until the user dismisses it")
+        let modalMessage = AgentRestartNotice.modalMessageAfterCLIRegistration(cliName: "hcloud")
+        try expect(modalMessage.contains("Codex, Claude Code"), "register modal names common agent apps")
+        try expect(modalMessage.contains("Cmd+Q"), "register modal tells users to fully quit agent apps")
         try expect(
             ExecutablePathSelection.inferredCLIName(from: URL(fileURLWithPath: "/opt/homebrew/bin/hcloud")) == "hcloud",
             "register CLI infers a CLI name from the selected executable path"
@@ -236,6 +239,8 @@ enum UISmokeRunner {
         )
         try expect(registered, "valid direct register submit succeeds")
         try expect(store.successMessage == AgentRestartNotice.afterCLIRegistration(cliName: "hcloud", shimInstalled: false), "successful registration tells the user to restart already-running agent apps")
+        try expect(store.agentRestartPrompt?.title == AgentRestartNotice.restartPromptTitle, "successful registration opens a modal restart prompt")
+        try expect(store.agentRestartPrompt?.message == AgentRestartNotice.modalMessageAfterCLIRegistration(cliName: "hcloud"), "modal restart prompt uses concise Cmd+Q guidance")
     }
 
     private static func testCLIShimInstallerEnvironment() throws {

Sources/App/Stores/ControlPlaneStore.swift

@@ -84,6 +84,19 @@ struct APISessionPresentation: Equatable {
     var token: String
 }
 
+struct AgentRestartPrompt: Identifiable, Equatable {
+    let id = UUID()
+    var cliName: String
+
+    var title: String {
+        AgentRestartNotice.restartPromptTitle
+    }
+
+    var message: String {
+        AgentRestartNotice.modalMessageAfterCLIRegistration(cliName: cliName)
+    }
+}
+
 @Observable
 @MainActor
 final class ControlPlaneStore {
@@ -115,6 +128,7 @@ final class ControlPlaneStore {
     var showingBitwardenBindingEditor = false
     var exportedAudit: String?
     var oneTimeAPISession: APISessionPresentation?
+    var agentRestartPrompt: AgentRestartPrompt?
     var availableUpdate: AppUpdateRelease?
     var isCheckingForUpdates = false
     var lastUpdateCheck: Date?
@@ -555,6 +569,7 @@ final class ControlPlaneStore {
             let summary = try await client.registerCLI(ControlPlaneCommandLineToolRegistrationRequest(name: normalizedName, targetPath: normalizedTargetPath, environmentSecrets: normalizedSecrets))
             selectedCLI = summary.name
             showingRegisterCLI = false
+            agentRestartPrompt = AgentRestartPrompt(cliName: summary.name)
             if installShim {
                 do {
                     _ = try CLIShimInstaller.install(name: summary.name)

Sources/App/Views/ContentView.swift

@@ -19,6 +19,15 @@ struct ContentView: View {
             .sheet(isPresented: $store.showingBitwardenBindingEditor) {
                 BitwardenBindingEditor(store: store)
             }
+            .alert(item: $store.agentRestartPrompt) { prompt in
+                Alert(
+                    title: Text(prompt.title),
+                    message: Text(prompt.message),
+                    dismissButton: .default(Text("OK")) {
+                        store.agentRestartPrompt = nil
+                    }
+                )
+            }
     }
 
     @ViewBuilder

Sources/Broker/AgentRestartNotice.swift

@@ -1,13 +1,19 @@
 import Foundation
 
 public enum AgentRestartNotice {
+    public static let restartPromptTitle = "Restart agent apps"
+
     public static func afterCLIRegistration(cliName: String, shimInstalled: Bool) -> String {
         if shimInstalled {
             return "CLI registered and shim installed. Make sure the shims folder is on PATH. Restart Codex or any other already-running agent app before using normal \(cliName) commands from that app so it reloads shell startup files and current Agentic Secrets state."
         }
         return "CLI registered. Restart Codex or any other already-running agent app before using \(cliName) from that app so it refreshes current Agentic Secrets state."
     }
 
+    public static func modalMessageAfterCLIRegistration(cliName: String) -> String {
+        "CLI registration is saved. Quit and reopen Codex, Claude Code, or the agent app that will use \(cliName). Use Cmd+Q so the app fully reloads PATH and Agentic Secrets state."
+    }
+
     public static func afterShimPathConfiguration(cliName: String) -> String {
         "Shell PATH configured for future sessions. Restart Codex or any other already-running agent app before using \(cliName) from that app so it reloads shell startup files and sees the Agentic Secrets shim."
     }

Sources/ContractTests/main.swift

@@ -109,6 +109,9 @@ func runContracts() throws {
     let restartNotice = AgentRestartNotice.afterCLIRegistration(cliName: "hcloud", shimInstalled: true)
     try expect(restartNotice.contains("Restart Codex"), "CLI registration success notice must tell agent users to restart")
     try expect(AgentRestartNotice.requiresManualDismiss(restartNotice), "agent restart notices must remain visible until dismissed")
+    let restartPromptMessage = AgentRestartNotice.modalMessageAfterCLIRegistration(cliName: "hcloud")
+    try expect(restartPromptMessage.contains("Codex, Claude Code"), "CLI registration modal guidance must name common agent apps")
+    try expect(restartPromptMessage.contains("Cmd+Q"), "CLI registration modal guidance must tell users to fully quit agent apps")
 
     let classifier = CommandClassifier()
     let hcloudRead = classifier.classify(executableName: "hcloud", arguments: ["server", "list"], observedVersion: "1.52.0")