Fix agent shim PATH ordering

Author: rodion-m

Docs/INSTALLATION.md

@@ -60,7 +60,7 @@ The default prefix is `~/Library/Application Support/AgenticSecrets/LocalInstall
 ./scripts/install_local.sh --load --configure-shell
 ```
 
-This recommended command installs the app at `~/Applications/AgenticSecrets.app`, keeps runtime files under the local install prefix, loads the LaunchAgent, waits for the broker daemon IPC health check, opens the installed app copy, and appends a guarded PATH block to your user shell config so future shell sessions can run `agentic-secrets` directly. Open a new terminal after installation, or run `source "$HOME/.zshrc"` in the current one.
+This recommended command installs the app at `~/Applications/AgenticSecrets.app`, keeps runtime files under the local install prefix, loads the LaunchAgent, waits for the broker daemon IPC health check, opens the installed app copy, and appends guarded PATH blocks to your user shell startup files so future shell sessions can run `agentic-secrets` directly. For zsh, the installer updates `.zshenv` for non-interactive tool runners, `.zprofile` for login shells, and `.zshrc` for interactive shells. Open a new terminal after installation, or source the relevant startup file in the current one.
 
 For automation or CI where shell startup files must not be touched and the UI should not open, omit `--configure-shell` and pass `--no-open`:
 
@@ -82,17 +82,17 @@ To add the installed commands to your current shell:
 export PATH="$HOME/Library/Application Support/AgenticSecrets/LocalInstall/bin:$PATH"
 ```
 
-To make the command available in future zsh sessions, add the same directory to your user shell config:
+To make the command available in future zsh sessions, add the same directory to your user shell startup files. Non-interactive tool runners read `.zshenv`; login shells read `.zprofile`; interactive terminal shells read `.zshrc`:
 
 ```sh
-cat >> "$HOME/.zshrc" <<'EOF'
+for file in "$HOME/.zshenv" "$HOME/.zprofile" "$HOME/.zshrc"; do
+  cat >> "$file" <<EOF
 
 # Agentic Secrets PATH
-case ":$PATH:" in
-  *":$HOME/Library/Application Support/AgenticSecrets/LocalInstall/bin:"*) ;;
-  *) export PATH="$HOME/Library/Application Support/AgenticSecrets/LocalInstall/bin:$PATH" ;;
-esac
+agentic_secrets_path_dir="$HOME/Library/Application Support/AgenticSecrets/LocalInstall/bin"
+export PATH="\$agentic_secrets_path_dir:\$PATH"
 EOF
+done
 ```
 
 The installer prints these next steps after every install. It opens the installed app by default for the standard user-local prefix; pass `--no-open` to suppress that, or `--open` to force opening when installing to an explicit custom prefix. It only edits shell startup files when `--configure-shell` is passed, and it appends without reading existing shell rc contents. It does not write to `/etc/paths.d`; this keeps the self-build installer user-local, reviewable, and reversible.
@@ -221,7 +221,7 @@ If you want the normal `hcloud ...` command to route through Agentic Secrets, in
 agentic-secrets cli shim install hcloud --configure-shell
 ```
 
-Open a new terminal so the shell picks up the shim PATH block, then verify command resolution:
+Open a new terminal or restart the tool runner so the shell picks up the shim PATH block, then verify command resolution. If Codex, Claude Code, or another agent app was already running during registration, restart that agent app before using `hcloud` from it.
 
 ```sh
 command -v hcloud

Sources/App/Services/BrokerStatusController.swift

@@ -598,8 +598,7 @@ struct LocalBrokerStatusController: BrokerStatusControlling {
     }
 
     private static func managedShellConfigPaths() -> [URL] {
-        let home = FileManager.default.homeDirectoryForCurrentUser
-        return [".zshrc", ".bashrc", ".profile"].map { home.appendingPathComponent($0) }
+        ShellStartupFilePolicy.managedConfigurationFiles()
     }
 
     private static let installExecutables = [
@@ -683,7 +682,11 @@ enum ShellConfigurationCleaner {
             caseIndex = index + 1
         }
         guard caseIndex < lines.count,
-              lines[caseIndex].trimmingCharacters(in: .whitespaces) == #"case ":$PATH:" in"# else { return nil }
+              lines[caseIndex].trimmingCharacters(in: .whitespaces) == #"case ":$PATH:" in"# ||
+              lines[caseIndex].trimmingCharacters(in: .whitespaces).hasPrefix("export PATH=") else { return nil }
+        if lines[caseIndex].trimmingCharacters(in: .whitespaces).hasPrefix("export PATH=") {
+            return caseIndex
+        }
         var cursor = caseIndex + 1
         while cursor < lines.count {
             if lines[cursor].trimmingCharacters(in: .whitespaces) == "esac" {

Sources/App/Services/UISmokeRunner.swift

@@ -26,7 +26,9 @@ enum UISmokeRunner {
         try await testEmptyState()
         try await testSettingsLayout()
         try await testRegisterWizardValidation()
+        try await testSuccessfulCLIRegistrationGuidance()
         try testCLIShimInstallerEnvironment()
+        try testShellStartupFilePolicy()
         try testCLIShimStatusPresentation()
         try testManagementEditorValidation()
         try testPasteboardCopy()
@@ -49,6 +51,20 @@ enum UISmokeRunner {
         try await testMenuBarStatusReflectsDaemonHealth()
     }
 
+    private static func testShellStartupFilePolicy() throws {
+        let home = URL(fileURLWithPath: "/tmp/agentic-secrets-ui-shell-policy", isDirectory: true)
+        let zshFiles = ShellStartupFilePolicy.defaultConfigurationFiles(
+            homeDirectory: home,
+            shellPath: "/bin/zsh"
+        ).map(\.lastPathComponent)
+        try expect(zshFiles == [".zshenv", ".zprofile", ".zshrc"], "zsh shell configuration includes non-interactive, login, and interactive startup files")
+
+        let managedFiles = ShellStartupFilePolicy.managedConfigurationFiles(homeDirectory: home).map(\.lastPathComponent)
+        try expect(managedFiles.contains(".zshenv"), "managed shell cleanup includes zsh non-interactive startup file")
+        try expect(managedFiles.contains(".zprofile"), "managed shell cleanup includes zsh login startup file")
+        try expect(managedFiles.contains(".bash_profile"), "managed shell cleanup includes bash login startup file")
+    }
+
     @MainActor
     private static func testSettingsLayout() async throws {
         let store = ControlPlaneStore(
@@ -148,6 +164,9 @@ enum UISmokeRunner {
 
     private static func testRegisterWizardValidation() async throws {
         try expect(RegisterCLIFormDefaults.installShim, "register CLI defaults to installing a command shim")
+        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")
         try expect(
             ExecutablePathSelection.inferredCLIName(from: URL(fileURLWithPath: "/opt/homebrew/bin/hcloud")) == "hcloud",
             "register CLI infers a CLI name from the selected executable path"
@@ -202,6 +221,23 @@ enum UISmokeRunner {
         ]).isEmpty, "whitespace-only secret values are omitted from registration payload")
     }
 
+    @MainActor
+    private static func testSuccessfulCLIRegistrationGuidance() async throws {
+        let store = ControlPlaneStore(
+            client: SequenceControlPlaneClient(snapshots: [snapshot(cliNames: ["hcloud"])]),
+            brokerController: StubBrokerStatusController(statusValue: healthyBrokerStatus())
+        )
+        await store.refresh()
+        let registered = await store.registerCLI(
+            name: "hcloud",
+            targetPath: "/bin/echo",
+            environmentSecrets: ["HCLOUD_TOKEN": "synthetic-secret"],
+            installShim: false
+        )
+        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")
+    }
+
     private static func testCLIShimInstallerEnvironment() throws {
         let prefix = URL(fileURLWithPath: "/tmp/agentic-secrets-custom-prefix", isDirectory: true)
         let environment = CLIShimInstaller.subprocessEnvironment(
@@ -785,6 +821,14 @@ enum UISmokeRunner {
           *) export PATH="$agentic_secrets_path_dir:$PATH" ;;
         esac
 
+        # Agentic Secrets PATH
+        agentic_secrets_path_dir='\(binDir)'
+        export PATH="$agentic_secrets_path_dir:$PATH"
+
+        # AgenticSecrets CLI shims
+        agentic_secrets_path_dir='\(shimDir)'
+        export PATH="$agentic_secrets_path_dir:$PATH"
+
         # AgenticSecrets CLI shims
         case ":$PATH:" in
           *":\(shimDir):"*) ;;

Sources/App/Stores/ControlPlaneStore.swift

@@ -558,14 +558,14 @@ final class ControlPlaneStore {
             if installShim {
                 do {
                     _ = try CLIShimInstaller.install(name: summary.name)
-                    successMessage = "CLI registered and shim installed"
+                    successMessage = AgentRestartNotice.afterCLIRegistration(cliName: summary.name, shimInstalled: true)
                     errorMessage = nil
                 } catch {
                     successMessage = nil
                     errorMessage = "CLI registered, but the command shim could not be installed: \(userFacingError(error))"
                 }
             } else {
-                successMessage = "CLI registered"
+                successMessage = AgentRestartNotice.afterCLIRegistration(cliName: summary.name, shimInstalled: false)
                 errorMessage = nil
             }
             do {

Sources/App/Views/ContentView.swift

@@ -497,7 +497,7 @@ private struct FeedbackBanner: View {
             Image(systemName: store.errorMessage == nil ? "checkmark.circle" : "exclamationmark.triangle")
                 .foregroundStyle(store.errorMessage == nil ? .green : .orange)
             Text(store.errorMessage ?? store.successMessage ?? "")
-                .lineLimit(2)
+                .lineLimit(4)
             Button {
                 store.clearFeedback()
             } label: {
@@ -514,6 +514,7 @@ private struct FeedbackBanner: View {
         .accessibilityElement(children: .contain)
         .task(id: store.successMessage) {
             guard let message = store.successMessage, store.errorMessage == nil else { return }
+            guard !AgentRestartNotice.requiresManualDismiss(message) else { return }
             try? await Task.sleep(nanoseconds: 3_500_000_000)
             await MainActor.run {
                 store.clearSuccessIfCurrent(message)

Sources/App/Views/EditorViews.swift

@@ -109,6 +109,8 @@ struct RegisterCLIView: View {
                         Text("The shim is installed in the local Agentic Secrets shims folder. Shell PATH configuration remains a separate explicit install action.")
                             .foregroundStyle(.secondary)
                     }
+                    Label("After registration and shim PATH setup, restart Codex or any other already-running agent app before using this CLI from that app.", systemImage: "arrow.clockwise")
+                        .foregroundStyle(.secondary)
                 }
             }
         }

Sources/Broker/AgentRestartNotice.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+public enum AgentRestartNotice {
+    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 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."
+    }
+
+    public static func afterManualPathChange(cliName: String) -> String {
+        "After changing PATH, restart Codex or any other already-running agent app before using \(cliName) from that app."
+    }
+
+    public static func requiresManualDismiss(_ successMessage: String) -> Bool {
+        successMessage.contains("Restart Codex")
+            || successMessage.contains("already-running agent app")
+    }
+}

Sources/Broker/ShellStartupFilePolicy.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+public enum ShellStartupFilePolicy {
+    public static func defaultConfigurationFiles(
+        homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser,
+        shellPath: String? = ProcessInfo.processInfo.environment["SHELL"]
+    ) -> [URL] {
+        let shellName = URL(fileURLWithPath: shellPath ?? "zsh").lastPathComponent
+        switch shellName {
+        case "zsh":
+            return [".zshenv", ".zprofile", ".zshrc"].map { homeDirectory.appendingPathComponent($0) }
+        case "bash":
+            return [".bash_profile", ".bashrc"].map { homeDirectory.appendingPathComponent($0) }
+        default:
+            return [homeDirectory.appendingPathComponent(".profile")]
+        }
+    }
+
+    public static func managedConfigurationFiles(
+        homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser
+    ) -> [URL] {
+        [".zshenv", ".zprofile", ".zshrc", ".bash_profile", ".bashrc", ".profile"].map {
+            homeDirectory.appendingPathComponent($0)
+        }
+    }
+}

Sources/CLI/main.swift

@@ -307,7 +307,7 @@ struct AgenticSecretsCLI {
           \(name) version
         """)
         if configureShell {
-            print("Shell PATH configured for future sessions.")
+            print(AgentRestartNotice.afterShimPathConfiguration(cliName: name))
         } else {
             print("""
 
@@ -316,6 +316,8 @@ struct AgenticSecretsCLI {
 
             For future sessions:
               agentic-secrets cli shim install \(name) --configure-shell
+
+            \(AgentRestartNotice.afterManualPathChange(cliName: name))
             """)
         }
     }
@@ -496,40 +498,32 @@ struct AgenticSecretsCLI {
         return value
     }
 
-    private static func defaultShellConfig() -> URL {
-        let shell = URL(fileURLWithPath: ProcessInfo.processInfo.environment["SHELL"] ?? "zsh").lastPathComponent
-        switch shell {
-        case "bash":
-            return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".bashrc")
-        case "zsh":
-            return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".zshrc")
-        default:
-            return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".profile")
-        }
+    private static func defaultShellConfigs() -> [URL] {
+        ShellStartupFilePolicy.defaultConfigurationFiles()
     }
 
     private static func configureShellPath(directory: URL, label: String) throws {
-        let target = defaultShellConfig()
         let quotedDirectory = try shellSingleQuotedPath(directory.path)
-        try FileManager.default.createDirectory(at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
-        if !FileManager.default.fileExists(atPath: target.path) {
-            FileManager.default.createFile(atPath: target.path, contents: nil)
-        }
         let block = """
 
         # \(label)
         agentic_secrets_path_dir=\(quotedDirectory)
-        case ":$PATH:" in
-          *":$agentic_secrets_path_dir:"*) ;;
-          *) export PATH="$agentic_secrets_path_dir:$PATH" ;;
-        esac
+        export PATH="$agentic_secrets_path_dir:$PATH"
         """
-        let handle = try FileHandle(forWritingTo: target)
-        defer { try? handle.close() }
-        try handle.seekToEnd()
-        try handle.write(contentsOf: Data(block.utf8))
-        try handle.write(contentsOf: Data([10]))
-        print("Configured shell PATH in \(target.path)")
+        for target in defaultShellConfigs() {
+            try FileManager.default.createDirectory(at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
+            if !FileManager.default.fileExists(atPath: target.path) {
+                _ = FileManager.default.createFile(atPath: target.path, contents: nil)
+            }
+            do {
+                let handle = try FileHandle(forWritingTo: target)
+                defer { try? handle.close() }
+                try handle.seekToEnd()
+                try handle.write(contentsOf: Data(block.utf8))
+                try handle.write(contentsOf: Data([10]))
+            }
+            print("Configured shell PATH in \(target.path)")
+        }
     }
 
     private static func shellSingleQuotedPath(_ path: String) throws -> String {

Sources/ContractTests/main.swift

@@ -92,6 +92,24 @@ func signedPack(payload: CommandPolicyPackPayload, key: P256.Signing.PrivateKey,
 }
 
 func runContracts() throws {
+    let shellPolicyHome = URL(fileURLWithPath: "/tmp/agentic-secrets-shell-policy", isDirectory: true)
+    let zshStartupFiles = ShellStartupFilePolicy.defaultConfigurationFiles(
+        homeDirectory: shellPolicyHome,
+        shellPath: "/bin/zsh"
+    ).map(\.lastPathComponent)
+    try expect(zshStartupFiles == [".zshenv", ".zprofile", ".zshrc"], "zsh configuration must cover non-interactive Codex shells, login shells, and interactive terminals")
+    let bashStartupFiles = ShellStartupFilePolicy.defaultConfigurationFiles(
+        homeDirectory: shellPolicyHome,
+        shellPath: "/bin/bash"
+    ).map(\.lastPathComponent)
+    try expect(bashStartupFiles == [".bash_profile", ".bashrc"], "bash configuration must cover login and interactive shells")
+    let managedStartupFiles = ShellStartupFilePolicy.managedConfigurationFiles(homeDirectory: shellPolicyHome).map(\.lastPathComponent)
+    try expect(managedStartupFiles.contains(".zshenv"), "cleanup must remove managed zsh non-interactive shell PATH blocks")
+    try expect(managedStartupFiles.contains(".zprofile"), "cleanup must remove managed zsh login shell PATH blocks")
+    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 classifier = CommandClassifier()
     let hcloudRead = classifier.classify(executableName: "hcloud", arguments: ["server", "list"], observedVersion: "1.52.0")
     try expect(hcloudRead.risk == .unknown, "hcloud server list has no built-in policy pack by default")