Add sidebar active agent indicator

.github/swift-file-length-budget.tsv

@@ -5,7 +5,7 @@
 17862	Sources/AppDelegate.swift
 16424	Sources/ContentView.swift
 15098	Sources/TerminalController.swift
-13228	Sources/Workspace.swift
+13164	Sources/Workspace.swift
 12501	Sources/GhosttyTerminalView.swift
 12348	cmuxTests/AppDelegateShortcutRoutingTests.swift
 11388	Sources/Panels/BrowserPanel.swift
@@ -178,10 +178,10 @@
 637	Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/MobileShellRenderGridLivenessTestSupport.swift
 635	cmuxUITests/RightSidebarChromeHeightUITests.swift
 630	Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/ShortcutWhenClause.swift
+624	Sources/SettingsNavigation.swift
 623	Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Surface/ControlCommandCoordinator+Surface.swift
 620	Sources/Panels/BrowserNavigationDelegate.swift
 620	cmuxTests/FinderFileDropRegressionTests.swift
-618	Sources/SettingsNavigation.swift
 608	cmuxUITests/FeedSidebarUITests.swift
 607	Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface.swift
 607	Sources/SessionIndexModels.swift

CLI/WorkspaceLoadingArguments.swift

@@ -0,0 +1,201 @@
+import Foundation
+
+struct WorkspaceLoadingArguments {
+    let turnOn: Bool
+    let id: String?
+    let workspace: String?
+    let window: String?
+}
+
+extension CMUXCLI {
+    func validateWorkspaceLoadingCommandBeforeSocket(
+        command: String,
+        commandArgs: [String]
+    ) throws {
+        guard command == "workspace",
+              commandArgs.first?.lowercased() == "loading" else {
+            return
+        }
+        _ = try parseWorkspaceLoadingArguments(Array(commandArgs.dropFirst()))
+    }
+
+    func workspaceLoadingUsage() -> String {
+        String(
+            localized: "cli.workspaceLoading.usage",
+            defaultValue: "Usage: cmux workspace loading <on|off> [--id <name>] [--workspace <id>] [--window <id>] [--json]"
+        )
+    }
+
+    func parseWorkspaceLoadingArguments(_ commandArgs: [String]) throws -> WorkspaceLoadingArguments {
+        let usage = workspaceLoadingUsage()
+        var idArg: String?
+        var wsArg: String?
+        var winArg: String?
+        var positional: [String] = []
+        var index = 0
+        var pastTerminator = false
+
+        func requireValue() throws -> String {
+            let valueIndex = index + 1
+            guard valueIndex < commandArgs.count, !commandArgs[valueIndex].hasPrefix("--") else {
+                throw CLIError(message: usage)
+            }
+            return commandArgs[valueIndex]
+        }
+
+        while index < commandArgs.count {
+            let arg = commandArgs[index]
+            if !pastTerminator, arg == "--" {
+                pastTerminator = true
+                index += 1
+                continue
+            }
+            if !pastTerminator, arg == "--json" {
+                index += 1
+                continue
+            }
+            if !pastTerminator, arg == "--id" {
+                idArg = try requireValue()
+                index += 2
+                continue
+            }
+            if !pastTerminator, arg == "--workspace" {
+                wsArg = try requireValue()
+                index += 2
+                continue
+            }
+            if !pastTerminator, arg == "--window" {
+                winArg = try requireValue()
+                index += 2
+                continue
+            }
+            if !pastTerminator, arg.hasPrefix("--id=") {
+                let value = String(arg.dropFirst("--id=".count))
+                guard !value.isEmpty else { throw CLIError(message: usage) }
+                idArg = value
+                index += 1
+                continue
+            }
+            if !pastTerminator, arg.hasPrefix("--workspace=") {
+                let value = String(arg.dropFirst("--workspace=".count))
+                guard !value.isEmpty else { throw CLIError(message: usage) }
+                wsArg = value
+                index += 1
+                continue
+            }
+            if !pastTerminator, arg.hasPrefix("--window=") {
+                let value = String(arg.dropFirst("--window=".count))
+                guard !value.isEmpty else { throw CLIError(message: usage) }
+                winArg = value
+                index += 1
+                continue
+            }
+            if !pastTerminator, arg.hasPrefix("--") {
+                throw CLIError(message: usage)
+            }
+            positional.append(arg)
+            index += 1
+        }
+
+        guard positional.count <= 1 else {
+            throw CLIError(message: usage)
+        }
+        guard let sub = positional.first?.lowercased() else {
+            throw CLIError(message: usage)
+        }
+        let turnOn: Bool
+        switch sub {
+        case "on", "start", "show", "running", "busy":
+            turnOn = true
+        case "off", "stop", "hide", "done", "idle", "finished":
+            turnOn = false
+        default:
+            throw CLIError(message: String(
+                format: String(
+                    localized: "cli.error.workspaceLoadingInvalidState",
+                    defaultValue: "Invalid state '%@'. Expected on or off. %@"
+                ),
+                locale: .current,
+                sub,
+                usage
+            ))
+        }
+
+        return WorkspaceLoadingArguments(
+            turnOn: turnOn,
+            id: idArg,
+            workspace: wsArg,
+            window: winArg
+        )
+    }
+
+    /// `cmux workspace loading <on|off> [--id <name>]` toggles the workspace's
+    /// loading spinner via the reserved `manual` lifecycle namespace.
+    func runWorkspaceLoading(
+        commandArgs: [String],
+        client: SocketClient,
+        windowId: String?,
+        jsonOutput: Bool
+    ) throws {
+        let parsed = try parseWorkspaceLoadingArguments(commandArgs)
+        let usage = workspaceLoadingUsage()
+
+        let manual = AgentHibernationLifecycleStatusKeys.manualKey
+        let key: String
+        if let rawId = parsed.id?.trimmingCharacters(in: .whitespacesAndNewlines) {
+            guard !rawId.isEmpty else {
+                throw CLIError(message: usage)
+            }
+            let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")
+            guard rawId.unicodeScalars.allSatisfy(allowed.contains) else {
+                throw CLIError(message: String(
+                    format: String(
+                        localized: "cli.error.workspaceLoadingInvalidId",
+                        defaultValue: "Invalid --id '%@'. Use letters, digits, '.', '_', or '-' (no spaces)."
+                    ),
+                    locale: .current,
+                    rawId
+                ))
+            }
+            key = "\(manual):\(rawId)"
+        } else {
+            key = manual
+        }
+
+        let windowRaw = parsed.window ?? windowId
+        let workspaceArg = parsed.workspace ?? Self.callerWorkspaceForSurfaceHandle(nil, windowRaw: windowRaw)
+        let winId = try normalizeWindowHandle(windowRaw, client: client)
+        let wsId = try resolveWorkspaceId(
+            workspaceArg,
+            client: client,
+            windowHandle: winId
+        )
+
+        let response = try sendV1Command(
+            "workspace_loading \(key) \(parsed.turnOn ? "on" : "off") --tab=\(wsId)",
+            client: client
+        )
+
+        if jsonOutput {
+            var before = false
+            var after = false
+            for part in response.split(separator: ";") {
+                let kv = part.split(separator: "=", maxSplits: 1)
+                guard kv.count == 2 else { continue }
+                let isOn = kv[1].trimmingCharacters(in: .whitespaces).uppercased() == "ON"
+                if kv[0] == "before" { before = isOn }
+                if kv[0] == "after" { after = isOn }
+            }
+            print(jsonString([
+                "ok": true,
+                "id": parsed.id ?? "",
+                "workspace_id": wsId,
+                "before": before,
+                "after": after,
+                "loading": after,
+            ]))
+        } else {
+            print(response)
+        }
+    }
+}

CLI/cmux.swift

@@ -3499,7 +3499,6 @@ struct CMUXCLI {
                 throw CLIError(message: "Unknown feed subcommand: \(sub)")
             }
         }
-
         if command == "events" {
             try runEventsCommand(
                 commandArgs: commandArgs,
@@ -3527,7 +3526,7 @@ struct CMUXCLI {
             command: command,
             commandArgs: commandArgs
         )
-
+        try validateWorkspaceLoadingCommandBeforeSocket(command: command, commandArgs: commandArgs)
         let client = SocketClient(path: resolvedSocketPath)
         if resolvedSocketPath != socketPath {
             cliTelemetry.breadcrumb(
@@ -6356,7 +6355,7 @@ struct CMUXCLI {
         }
         throw CLIError(message: "Surface index not found")
     }
-    private static func callerWorkspaceForSurfaceHandle(_ raw: String?, windowRaw: String?) -> String? {
+    static func callerWorkspaceForSurfaceHandle(_ raw: String?, windowRaw: String?) -> String? {
         let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         return windowRaw == nil && (trimmed.isEmpty || Int(trimmed) != nil) ? ProcessInfo.processInfo.environment["CMUX_WORKSPACE_ID"] : nil
     }
@@ -8112,7 +8111,7 @@ struct CMUXCLI {
         guard let sub = commandArgs.first?.lowercased() else {
             throw CLIError(message: String(
                 localized: "cli.error.workspaceSubcommandRequired",
-                defaultValue: "workspace requires a subcommand. Try: list, create, env, close, rename, select, reconnect, disconnect, group"
+                defaultValue: "workspace requires a subcommand. Try: list, create, env, close, rename, select, reconnect, disconnect, loading, group"
             ))
         }
         let rest = Array(commandArgs.dropFirst())
@@ -8201,11 +8200,13 @@ struct CMUXCLI {
                 idFormat: idFormat,
                 windowOverride: windowOverride
             )
+        case "loading":
+            try runWorkspaceLoading(commandArgs: rest, client: client, windowId: windowOverride, jsonOutput: jsonOutput)
         default:
             throw CLIError(message: String(
                 format: String(
                     localized: "cli.error.workspaceSubcommandUnknown",
-                    defaultValue: "Unknown workspace subcommand: %@. Try: list, create, env, close, rename, select, reconnect, disconnect, group"
+                    defaultValue: "Unknown workspace subcommand: %@. Try: list, create, env, close, rename, select, reconnect, disconnect, loading, group"
                 ),
                 locale: .current,
                 sub
@@ -15881,12 +15882,11 @@ struct CMUXCLI {
                                       whose automatic reconnect paused because the host
                                       was unreachable
               disconnect [workspace]  Stop a remote (SSH) workspace's connection
+              loading <on|off> [--id <name>] Toggle the workspace loading spinner.
               group <subcommand>      Workspace group operations (see cmux workspace-group --help)
-
             env/reconnect/disconnect accept a positional handle or --workspace
             <id|ref|index>, defaulting to the caller's workspace, then the
             selected one (of --window's window when given).
-
             Examples:
               cmux workspace list --json
               cmux workspace create --name Build --cwd ~/projects/myapp

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Sidebar/ControlCommandCoordinator+SidebarV1.swift

@@ -99,6 +99,7 @@ extension ControlCommandCoordinator {
         case "list_meta_blocks": return sidebarListMetaBlocks(args, context: context)
         case "set_agent_pid": return sidebarSetAgentPID(args, context: context)
         case "set_agent_lifecycle": return sidebarSetAgentLifecycle(args, context: context)
+        case "workspace_loading": return sidebarWorkspaceLoading(args, context: context)
         case "agent_hibernation": return sidebarAgentHibernation(args, context: context)
         case "clear_agent_pid": return sidebarClearAgentPID(args, context: context)
         case "log": return sidebarAppendLog(args, context: context)

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Sidebar/ControlCommandCoordinator+SidebarWorkspaceLoadingV1.swift

@@ -0,0 +1,52 @@
+internal import Foundation
+
+extension ControlCommandCoordinator {
+    /// `workspace_loading <key> <on|off> [--tab=<id>]` toggles a workspace-scoped
+    /// manual loading state and replies `before=ON;after=OFF`.
+    nonisolated func sidebarWorkspaceLoading(_ args: String, context: (any ControlCommandContext)?) -> String {
+        let parsed = sidebarParseOptions(args)
+        let usage = "workspace_loading <key> <on|off> [--tab=<id>]"
+        guard parsed.positional.count >= 2 else {
+            return "ERROR: Usage: \(usage)"
+        }
+        let key = parsed.positional[0]
+        guard key == "manual" || key.hasPrefix("manual:") else {
+            return "ERROR: workspace_loading only accepts manual loader keys (manual or manual:<id>); use set_agent_lifecycle for agent keys"
+        }
+        if key != "manual" {
+            let id = key.dropFirst("manual:".count)
+            let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")
+            guard !id.isEmpty, id.count <= 64, id.unicodeScalars.allSatisfy(allowed.contains) else {
+                return "ERROR: Invalid manual loader id; use 1-64 characters from letters, digits, '.', '_', '-'"
+            }
+        }
+        let on: Bool
+        switch parsed.positional[1].lowercased() {
+        case "on", "running", "start", "show":
+            on = true
+        case "off", "idle", "stop", "hide":
+            on = false
+        default:
+            return "ERROR: Usage: \(usage)"
+        }
+        let tabArg = parsed.options["tab"]
+        if let tabArg, tabArg.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return "ERROR: Invalid --tab; expected a workspace id, ref, or index"
+        }
+        let result = context?.controlSidebarOnMain {
+            $0.controlSidebarSetWorkspaceLoading(
+                tabArg: tabArg,
+                key: key,
+                on: on
+            )
+        }
+        guard let result = result ?? nil else {
+            return "ERROR: Workspace not found"
+        }
+        if let failureReason = result.failureReason {
+            return "ERROR: \(failureReason)"
+        }
+        func label(_ value: Bool) -> String { value ? "ON" : "OFF" }
+        return "before=\(label(result.before));after=\(label(result.after))"
+    }
+}

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Sidebar/ControlSidebarContext.swift

@@ -93,6 +93,18 @@ public protocol ControlSidebarContext: AnyObject {
         panelID: UUID?
     )
 
+    /// Workspace-scoped manual loading toggle for `workspace_loading`. `on`
+    /// marks the manual loader `key` running on the workspace; `off` clears it
+    /// from every panel so it turns off regardless of which surface invoked it.
+    /// Returns this manual loader key's state before and after the change, or
+    /// `nil` if the workspace was not found. Other active agent lifecycles may
+    /// still keep the aggregate sidebar spinner visible.
+    func controlSidebarSetWorkspaceLoading(
+        tabArg: String?,
+        key: String,
+        on: Bool
+    ) -> ControlSidebarWorkspaceLoadingState?
+
     /// Applies the `agent_hibernation` global toggle.
     nonisolated func controlSidebarSetAgentHibernation(enabled: Bool)
 

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Sidebar/ControlSidebarWorkspaceLoadingState.swift

@@ -0,0 +1,25 @@
+/// The manual loader key state before and after a `workspace_loading` toggle,
+/// reported back to the caller (e.g. `before=ON;after=OFF`).
+public struct ControlSidebarWorkspaceLoadingState: Sendable, Equatable {
+    /// Whether this manual loader key was running before the toggle.
+    public let before: Bool
+
+    /// Whether this manual loader key is running after the toggle.
+    public let after: Bool
+
+    /// A human-readable failure reason when the requested toggle could not be
+    /// applied. The v1 line protocol maps this to `ERROR: <reason>`.
+    public let failureReason: String?
+
+    /// Creates a before/after pair for one `workspace_loading` toggle.
+    ///
+    /// - Parameters:
+    ///   - before: Spinner state before the change.
+    ///   - after: Spinner state after the change.
+    ///   - failureReason: A failure reason when no state change was possible.
+    public init(before: Bool, after: Bool, failureReason: String? = nil) {
+        self.before = before
+        self.after = after
+        self.failureReason = failureReason
+    }
+}