Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(macos): keep accessible Swarm tabs in visual order

dee54b15793dd69
diff --git a/desktop/macos/Runner/SwarmTitlebar.swift b/desktop/macos/Runner/SwarmTitlebar.swift
index 8f866a5d5..d4ff34cff 100644
--- a/desktop/macos/Runner/SwarmTitlebar.swift
+++ b/desktop/macos/Runner/SwarmTitlebar.swift
@@ -142,6 +142,7 @@ private final class SwarmTabStrip: NSView {
let rows = state["tabs"] as? [[String: Any]] ?? []
activeId = state["activeId"] as? String ?? ""
let ids = rows.compactMap { $0["id"] as? String }
+ let previousOrder = tabs.map(\.swarmId)
for tab in tabs where !ids.contains(tab.swarmId) { tab.removeFromSuperview() }
let previous = Dictionary(uniqueKeysWithValues: tabs.map { ($0.swarmId, $0) })
tabs = rows.compactMap { row in
@@ -156,6 +157,8 @@ private final class SwarmTabStrip: NSView {
tab.needsDisplay = true
return tab
}
+ // Moving frames alone leaves AppKit's child traversal in insertion order.
+ document.setAccessibilityChildren(tabs)
newButton.isEnabled = actionsEnabled && tabs.count < 24
notifications.isEnabled = actionsEnabled
settings.isEnabled = actionsEnabled
@@ -166,6 +169,9 @@ private final class SwarmTabStrip: NSView {
notifications.setAccessibilityLabel(notifications.toolTip)
needsLayout = true
layoutSubtreeIfNeeded()
+ if ids != previousOrder {
+ NSAccessibility.post(element: document, notification: .layoutChanged)
+ }
}
override func layout() {
diff --git a/desktop/tool/check_swarm_titlebar.sh b/desktop/tool/check_swarm_titlebar.sh
new file mode 100644
index 000000000..f634dd374
--- /dev/null
+++ b/desktop/tool/check_swarm_titlebar.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+set -euo pipefail
+
+# Exercise the actual AppKit source without booting Flutter, authenticating,
+# opening a window, or touching saved app data. The local Flutter SDK supplies
+# FlutterMacOS only to satisfy the production source's framework import.
+desktop_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+flutter_sdk="${1:-}"
+if [[ -z "$flutter_sdk" && -f "$desktop_dir/macos/Flutter/ephemeral/Flutter-Generated.xcconfig" ]]; then
+ flutter_sdk="$(sed -n 's/^FLUTTER_ROOT=//p' "$desktop_dir/macos/Flutter/ephemeral/Flutter-Generated.xcconfig")"
+fi
+framework_dir="$flutter_sdk/bin/cache/artifacts/engine/darwin-x64-release/FlutterMacOS.xcframework/macos-arm64_x86_64"
+if [[ ! -d "$framework_dir/FlutterMacOS.framework/Modules" ]]; then
+ echo 'Build Harness V2 first, or pass the Flutter SDK path containing its cached macOS release engine.' >&2
+ exit 1
+fi
+check_dir="$(mktemp -d "${TMPDIR:-/tmp}/harness-v2-titlebar.XXXXXX")"
+trap 'rm -rf "$check_dir"' EXIT
+cat "$desktop_dir/macos/Runner/SwarmTitlebar.swift" \
+ "$desktop_dir/tool/swarm_titlebar_checks.swift" > "$check_dir/main.swift"
+xcrun swiftc -swift-version 5 -module-cache-path "$check_dir/module-cache" \
+ -F "$framework_dir" -framework FlutterMacOS \
+ -Xlinker -rpath -Xlinker "$framework_dir" \
+ "$check_dir/main.swift" -o "$check_dir/check-titlebar"
+"$check_dir/check-titlebar"
diff --git a/desktop/tool/swarm_titlebar_checks.swift b/desktop/tool/swarm_titlebar_checks.swift
new file mode 100644
index 000000000..74c2d8b3b
--- /dev/null
+++ b/desktop/tool/swarm_titlebar_checks.swift
@@ -0,0 +1,109 @@
+
+// Appended to SwarmTitlebar.swift by check_swarm_titlebar.sh. Same-file
+// extensions can inspect private controls without exposing them in the app API.
+private struct TitlebarCheckFailure: Error {
+ let message: String
+}
+
+private var titlebarCheckCount = 0
+private func checkTitlebar(_ condition: @autoclosure () -> Bool, _ message: String) throws {
+ guard condition() else { throw TitlebarCheckFailure(message: message) }
+ titlebarCheckCount += 1
+}
+
+private extension SwarmTabButton {
+ func checkAccessibility(expectedName: String, active: Bool) throws {
+ try checkTitlebar(accessibilityLabel() == expectedName, "Tab group name is available before paint")
+ let children = accessibilityChildren()?.compactMap { $0 as? NSButton } ?? []
+ try checkTitlebar(children.count == 2, "Selection and close are separate accessible buttons")
+ try checkTitlebar(children[0].accessibilityLabel() == "Select \(expectedName)", "Selection button has current name")
+ try checkTitlebar(children[0].accessibilityValue() as? String == (active ? "Selected" : ""), "Selection value is current")
+ try checkTitlebar(children[1].accessibilityLabel() == "Close \(expectedName)", "Close button has current name")
+ }
+
+ func checkEnabled(_ enabled: Bool) throws {
+ try checkTitlebar(selectButton.isEnabled == enabled, "Select button obeys modal state")
+ try checkTitlebar(closeButton.isEnabled == enabled, "Close button obeys modal state")
+ for item in menu?.items ?? [] {
+ try checkTitlebar(validateMenuItem(item) == enabled, "Tab context menu obeys modal state")
+ }
+ }
+
+ func clickBothActions() {
+ selectButton.performClick(nil)
+ closeButton.performClick(nil)
+ }
+}
+
+private extension SwarmTabStrip {
+ func checkActiveVisible() throws {
+ guard let active = tabs.first(where: { $0.swarmId == activeId }) else {
+ throw TitlebarCheckFailure(message: "Selected tab exists")
+ }
+ let visible = scroll.documentVisibleRect
+ try checkTitlebar(active.frame.minX >= visible.minX - 1, "Selected tab's leading edge is visible after layout")
+ try checkTitlebar(active.frame.maxX <= visible.maxX + 1, "Selected tab's trailing edge is visible after layout")
+ }
+
+ func runChecks() throws {
+ let rows = (0..<24).map { ["id": "swarm-\($0)", "name": "Swarm \($0)"] }
+ var events: [String] = []
+ emit = { method, _ in events.append(method) }
+ func state(_ rows: [[String: String]], active: String, enabled: Bool = true) -> [String: Any] {
+ ["tabs": rows, "activeId": active, "enabled": enabled, "attention": 2]
+ }
+ update(state(rows, active: "swarm-11"))
+ try checkTitlebar(tabs.count == 24, "All overflow tabs exist")
+ try checkTitlebar(!newButton.isEnabled, "New tab is disabled at capacity")
+ for (index, tab) in tabs.enumerated() {
+ try tab.checkAccessibility(expectedName: "Swarm \(index)", active: index == 11)
+ }
+ try checkActiveVisible()
+ setFrameSize(NSSize(width: 320, height: 40))
+ needsLayout = true
+ layoutSubtreeIfNeeded()
+ try checkActiveVisible()
+
+ let original = tabs[0]
+ let reversed = Array(rows.reversed())
+ update(state(reversed, active: "swarm-0"))
+ try checkTitlebar(tabs.last === original, "Reordering retains existing tab controls")
+ try checkTitlebar(tabs.map(\.swarmId) == reversed.map { $0["id"]! }, "Tab order follows the saved Swarm order")
+ let accessibleTabs = document.accessibilityChildren()?.compactMap { $0 as? SwarmTabButton } ?? []
+ try checkTitlebar(accessibleTabs.map(\.swarmId) == tabs.map(\.swarmId), "Accessible tab order follows visual order after reordering")
+ try checkActiveVisible()
+
+ update(state([["id": "swarm-0", "name": "Renamed tab"]], active: "swarm-0"))
+ try checkTitlebar(tabs.count == 1 && tabs[0] === original, "Closing tabs retains the surviving control")
+ try original.checkAccessibility(expectedName: "Renamed tab", active: true)
+ try checkTitlebar(newButton.isEnabled, "New tab returns below capacity")
+ try checkTitlebar(notifications.accessibilityLabel() == "2 agents need input", "Attention has a readable accessible label")
+ try original.checkEnabled(true)
+ original.clickBothActions()
+ try checkTitlebar(events == ["select", "close"], "Native selection and close dispatch once each")
+
+ events.removeAll()
+ update(state([["id": "swarm-0", "name": "Renamed tab"]], active: "swarm-0", enabled: false))
+ try original.checkEnabled(false)
+ try checkTitlebar(!newButton.isEnabled && !notifications.isEnabled && !settings.isEnabled, "Titlebar actions disable with a modal")
+ original.clickBothActions()
+ newButton.performClick(nil)
+ notifications.performClick(nil)
+ settings.performClick(nil)
+ try checkTitlebar(events.isEmpty, "Disabled controls emit no actions")
+ }
+}
+
+let titlebarCheckApp = NSApplication.shared
+titlebarCheckApp.setActivationPolicy(.prohibited)
+titlebarCheckApp.appearance = NSAppearance(named: .darkAqua)
+do {
+ let strip = SwarmTabStrip(frame: NSRect(x: 0, y: 0, width: 900, height: 40))
+ try strip.runChecks()
+ try checkTitlebar(titlebarCheckApp.windows.isEmpty, "Checks never open an application window")
+ print("AppKit Swarm titlebar: \(titlebarCheckCount) checks passed; no windows opened.")
+} catch {
+ let message = (error as? TitlebarCheckFailure)?.message ?? String(describing: error)
+ FileHandle.standardError.write(Data("AppKit Swarm titlebar failed: \(message)\n".utf8))
+ exit(1)
+}
diff --git a/docs/harness-v2-performance.md b/docs/harness-v2-performance.md
index 926d0c79e..f4bcd2ab6 100644
--- a/docs/harness-v2-performance.md
+++ b/docs/harness-v2-performance.md
@@ -33,4 +33,4 @@ Rapid navigation also coalesces pending arrangement writes. While the first writ
## Native follow-up
-The optimized real-data app builds and runs locally. Measure release input-to-display and tab-switch latency in the unlocked native window before making latency claims. The screen was locked during this pass, so native drag, overflow and visual inspection remain in the development handoff.
+The optimized real-data app builds and runs locally. A separate windowless AppKit check covers tab overflow geometry, resizing, accessibility order and disabled actions (`bash tool/check_swarm_titlebar.sh`, with an optional Flutter SDK path). Measure release input-to-display and tab-switch latency in the unlocked native window before making latency claims. The screen was locked during this pass, so native end-to-end drag and visual inspection remain in the development handoff.
diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.md
index 9244cd3d2..420ccd3de 100644
--- a/docs/harness-v2-progress.md
+++ b/docs/harness-v2-progress.md
@@ -89,6 +89,7 @@ Approved reference: `/Users/ab/code/harness-new-ui`, React prototype commit `f83
- Method channel `harness/swarm_tabs`: Dart sends tab ID/name/selection/attention; Swift sends new/select/close/rename/reorder/navigation/settings/notifications.
- Native tab click, double-click rename, context menu, close, drag/drop reorder. Tab button instances are retained across refreshes.
- Accessibility names/selection update with state, including overflowed tabs that have never painted. Tab context menus obey modal-disabled state. Layout reveals the selected tab after window resize.
+- Accessibility child order follows the displayed order after a reorder; AppKit receives a layout-change notification when tabs are added, moved or closed. A windowless check compiles the production Swift source and exercises these native controls directly, without booting Flutter or reading saved account/layout data.
- Native Swarm menu includes new/close/rename, previous/next, Add agent, close agent view, Settings.
- Real tabs alongside traffic lights were visually verified. Native selection, new tabs, modal-disabled controls, and independently accessible select/close buttons were checked. Drag/reorder, overflow, and a wider keyboard/accessibility audit remain.
@@ -144,6 +145,7 @@ Swarm shortcuts, help, and tooltips now read the same catalog in `shortcuts/app_
| CLI targeted tests | 135 passed across project/frame, registry/restore, and terminal recovery files. Project/frame tests rerun after port normalization: 9 passed. |
| Flutter analyzer | **0 errors, 0 warnings, 12 existing vendored xterm infos**; passes with `--no-fatal-infos`. |
| Headless performance | 3 explicit benchmarks passed: 2,000-agent catalog and 16/48 retained terminals. Reproducible command and limits in `docs/harness-v2-performance.md`. |
+| AppKit components | **151 assertions passed** for overflow, selected-tab visibility after resize, pre-paint labels, accessible order after reorder, retained tab controls, capacity and modal-disabled actions. No window opened. This complements the pending native end-to-end visual audit. |
| Remote terminals / production release | No remote takeover, release, installer, or production CLI update/restart. Cross-platform and end-to-end latency measurements remain. |
Tests now exercise the actual V2 welcome/settings/linking flow. Usage pricing again explains a partial estimate as a lower bound. Small offline panes avoid overflowing the full connection guide. No remaining full-suite failures are being dismissed as baseline.
@@ -162,6 +164,7 @@ Evidence on this Mac under `/private/tmp`:
- `harness-v2-retained-tests.log`: 27 terminal/menu/layout checks.
- `harness-v2-persistence-tests.log`: 21 state/async checks including rapid writes and bounded quit.
- `harness-v2-benchmark-final.log`: latest catalog and retained-terminal CPU measurements.
+- `harness-v2-native-titlebar-tests.log`: windowless checks against the actual AppKit tab source.
Earlier logs contain superseded failures. Temporary logs and toolchains are local conveniences, not committed artifacts.
@@ -194,6 +197,15 @@ open -n 'build/macos/Build/Products/Debug/Harness V2.app'
Use online `pub get` if packages are not cached. Enable SPM before pub get; do not accept CocoaPods fallback rewriting the project. Do not commit generated build/ephemeral files or caches. Use `--no-fatal-infos` for the existing vendored xterm infos; do not modify vendored style merely to erase them.
+Native component checks can run while the desktop is locked. They require Xcode and Flutter's already-cached macOS release engine. The SDK path is read from the generated Flutter config, or can be passed explicitly:
+
+```bash
+cd /Users/ab/code/autonomous-harness/desktop
+bash tool/check_swarm_titlebar.sh /private/tmp/harness-v2-flutter
+```
+
+The script appends same-file assertions to the actual `SwarmTitlebar.swift` in a disposable temporary directory. It uses AppKit with activation prohibited, creates no windows, and does not launch the app, an engine, or any account/transport code.
+
```bash
cd /Users/ab/code/autonomous-harness/cli
npm ci --ignore-scripts --cache /private/tmp/harness-v2-npm-cache --no-audit --no-fund