@@ -533,12 +533,16 @@ private func actionWindow(app: NSRunningApplication, hit: AXUIElement?) -> AXUIE
   }
   guard let front = try? frontWindowFrame(pid: app.processIdentifier) else { return nil }
   return windows(of: AXUIElementCreateApplication(app.processIdentifier)).first { window in
-    guard let rect = rectAttribute(window) else { return false }
-    return abs(rect.x - front.minX) < 1 && abs(rect.y - front.minY) < 1
-      && abs(rect.width - front.width) < 1 && abs(rect.height - front.height) < 1
+    rectAttribute(window).map { isSameFrame($0, front) } ?? false
   }
 }
 
+/// Whether an accessibility window frame is the frame of a WindowServer window.
+private func isSameFrame(_ rect: RectResponse, _ frame: CGRect) -> Bool {
+  abs(rect.x - frame.minX) < 1 && abs(rect.y - frame.minY) < 1
+    && abs(rect.width - frame.width) < 1 && abs(rect.height - frame.height) < 1
+}
+
 private func windowTitle(of element: AXUIElement) -> String? {
   let window = role(of: element) == "AXWindow"
     ? element : elementAttribute(element, attribute: kAXWindowAttribute as String)
@@ -683,7 +687,21 @@ func appWindowInfo() -> [[String: Any]]? {
 /// none. A window list that cannot be read is a refusal, not an empty list: the caller must not
 /// report "no window" for a WindowServer it could not ask.
 func frontWindow(pid: pid_t, windowInfo: [[String: Any]]? = appWindowInfo()) throws -> OnScreenWindow? {
-  onScreenWindows(pid: pid, windowInfo: try requireWindowInfo(windowInfo)).first
+  let windowInfo = try requireWindowInfo(windowInfo)
+  return frontWindow(
+    among: onScreenWindows(pid: pid, windowInfo: windowInfo),
+    isSharingIndicator: { isWindowSharingIndicator(pid: pid, frame: $0.bounds) }
+  )
+}
+
+/// The frontmost candidate that is not a window-sharing indicator. A lone window is never one: an
+/// indicator only appears in front of the window it belongs to.
+func frontWindow(
+  among candidates: [OnScreenWindow],
+  isSharingIndicator: (OnScreenWindow) -> Bool
+) -> OnScreenWindow? {
+  guard candidates.count > 1 else { return candidates.first }
+  return candidates.first { !isSharingIndicator($0) }
 }
 
 func requireWindowInfo(_ windowInfo: [[String: Any]]? = appWindowInfo()) throws -> [[String: Any]] {
@@ -699,6 +717,45 @@ func requireWindowInfo(_ windowInfo: [[String: Any]]? = appWindowInfo()) throws
   return windowInfo
 }
 
+/// While a ScreenCaptureKit stream shares one of an app's windows, macOS 27 adds a 66 x 20
+/// normal-layer window titled "Window" in front of it. Its only child is a button titled
+/// `WindowSharingSessionButton`. That window is a system indicator, not the app's front window.
+private let windowSharingIndicatorButtonTitle = "WindowSharingSessionButton"
+
+/// Whether a child of a window, by its accessibility role and title, marks the window as the
+/// indicator. The title is read only for a button.
+func isWindowSharingIndicatorButton(role: String, title: @autoclosure () -> String?) -> Bool {
+  role == "AXButton" && title() == windowSharingIndicatorButtonTitle
+}
+
+/// `AXUIElementSetMessagingTimeout` applies only to the element it is set on, so every element the
+/// probe reads gets it, and the probe stops at its own deadline.
+private let sharingIndicatorReplyTimeoutSeconds: Float = 0.1
+private let sharingIndicatorProbeSeconds = 0.5
+
+/// An accessibility tree that cannot be read in time, from a hung app or without Accessibility
+/// access, reads as no indicator, so the frontmost window stays the choice as before the indicator
+/// check. Refusing instead would fail screenshots, which need no accessibility read today.
+private func isWindowSharingIndicator(pid: pid_t, frame: CGRect) -> Bool {
+  let deadline = Date().addingTimeInterval(sharingIndicatorProbeSeconds)
+  func bounded(_ element: AXUIElement) -> AXUIElement? {
+    guard Date() < deadline else { return nil }
+    AXUIElementSetMessagingTimeout(element, sharingIndicatorReplyTimeoutSeconds)
+    return element
+  }
+  guard let appElement = bounded(AXUIElementCreateApplication(pid)) else { return false }
+  let window = windows(of: appElement).first { window in
+    guard let window = bounded(window), let rect = rectAttribute(window) else { return false }
+    return isSameFrame(rect, frame)
+  }
+  guard let window else { return false }
+  return children(of: window).contains { child in
+    guard let child = bounded(child) else { return false }
+    return isWindowSharingIndicatorButton(
+      role: role(of: child), title: stringAttribute(child, attribute: kAXTitleAttribute as String))
+  }
+}
+
 func frontWindowFrame(pid: pid_t, windowInfo: [[String: Any]]? = appWindowInfo()) throws -> CGRect? {
   try frontWindow(pid: pid, windowInfo: windowInfo)?.bounds
 }
 
@@ -43,6 +43,48 @@ final class AppWindowScreenshotTests: XCTestCase {
     XCTAssertEqual(try frontWindowFrame(pid: 42, windowInfo: windows), front?.bounds)
   }
 
+  func testFrontWindowSkipsASharingIndicatorInFrontOfAnotherWindow() {
+    let indicator = OnScreenWindow(
+      number: 9, bounds: CGRect(x: 10, y: 10, width: 66, height: 20), sharingState: 1)
+    let shared = OnScreenWindow(
+      number: 8, bounds: CGRect(x: 0, y: 0, width: 900, height: 700), sharingState: 1)
+
+    XCTAssertEqual(
+      frontWindow(among: [indicator, shared], isSharingIndicator: { $0.number == 9 })?.number, 8)
+    XCTAssertEqual(frontWindow(among: [indicator, shared], isSharingIndicator: { _ in false })?.number, 9)
+  }
+
+  func testRecognizesTheSharingIndicatorOnlyByItsSessionButton() {
+    XCTAssertTrue(isWindowSharingIndicatorButton(role: "AXButton", title: "WindowSharingSessionButton"))
+
+    // A small ordinary window: title-bar buttons, or the session title on a non-button.
+    XCTAssertFalse(isWindowSharingIndicatorButton(role: "AXButton", title: nil))
+    XCTAssertFalse(isWindowSharingIndicatorButton(role: "AXButton", title: "Close"))
+    XCTAssertFalse(
+      isWindowSharingIndicatorButton(role: "AXStaticText", title: "WindowSharingSessionButton"))
+  }
+
+  /// A child's title is read only once its role is a button.
+  func testReadsNoTitleForAChildThatIsNotAButton() {
+    var readTitle = false
+    let isIndicator = isWindowSharingIndicatorButton(
+      role: "AXGroup", title: { readTitle = true; return "WindowSharingSessionButton" }())
+
+    XCTAssertFalse(isIndicator)
+    XCTAssertFalse(readTitle)
+  }
+
+  /// The indicator check reads the app's accessibility tree; a lone window never needs it.
+  func testFrontWindowAsksNothingAboutALoneWindow() {
+    let lone = OnScreenWindow(
+      number: 8, bounds: CGRect(x: 0, y: 0, width: 900, height: 700), sharingState: 1)
+    var asked = false
+    let front = frontWindow(among: [lone], isSharingIndicator: { _ in asked = true; return true })
+
+    XCTAssertEqual(front?.number, 8)
+    XCTAssertFalse(asked)
+  }
+
   func testRefusesWhenOnlyInvisibleOrEmptyWindowsRemain() throws {
     let windows = [
       windowInfo(id: 1, onScreen: false),
 
@@ -84,7 +84,7 @@ export const screenshotCommandFacet = defineCommandFacet({
   text: {
     summary: 'Capture a screenshot',
     cliDetail:
-      "Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
+      "Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
   },
   metadata: screenshotCommandMetadata,
   run: (client, input) => client.capture.screenshot(input),
 
@@ -363,7 +363,7 @@ With the native backend, each app you open on the `app` surface is a device of i
 
 Copies of one app need distinct bundle ids. Screenshots run one at a time across the Mac. Use one agent-device version per claims directory.
 
-- `click`, `press`, and `fill` use accessibility actions on the element at the target point, which must be inside one of the app's on-screen windows, not its menu bar. `click --button secondary` opens the context menu of the nearest element at the point that offers one (`AXShowMenu`); the open menu shows in the next `snapshot`, and `click` on one of its items picks it. It fails with `UNSUPPORTED_OPERATION` (`helperReason: no-context-menu`) when no element there offers a menu (`no-accessible-target` when no element is at the point). It fails with `COMMAND_FAILED` and `reason: context-menu-not-observed` when the app's window list was readable but showed no new menu window, and with `reason: window-list-unreadable` when the window list could not be read before the action or by any read during the wait for the menu. `type` inserts at the focused control or falls back to key events. `scroll` moves the scroll bar under the front window's center. Electron and other Chromium-based desktop apps expose their web content in the snapshot: the first `snapshot` turns the app's Chromium accessibility tree on, and a snapshot warns when that tree did not populate. `screenshot` captures only the app's front window, even when it is covered. The front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, and a sheet is captured as its own window. If that window cannot be captured, `screenshot` fails; it never captures another window.
+- `click`, `press`, and `fill` use accessibility actions on the element at the target point, which must be inside one of the app's on-screen windows, not its menu bar. `click --button secondary` opens the context menu of the nearest element at the point that offers one (`AXShowMenu`); the open menu shows in the next `snapshot`, and `click` on one of its items picks it. It fails with `UNSUPPORTED_OPERATION` (`helperReason: no-context-menu`) when no element there offers a menu (`no-accessible-target` when no element is at the point). It fails with `COMMAND_FAILED` and `reason: context-menu-not-observed` when the app's window list was readable but showed no new menu window, and with `reason: window-list-unreadable` when the window list could not be read before the action or by any read during the wait for the menu. `type` inserts at the focused control or falls back to key events. `scroll` moves the scroll bar under the front window's center. Electron and other Chromium-based desktop apps expose their web content in the snapshot: the first `snapshot` turns the app's Chromium accessibility tree on, and a snapshot warns when that tree did not populate. `screenshot` captures only the app's front window, even when it is covered. The front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. If that window cannot be captured, `screenshot` fails; it never captures another window.
 - `record`, `prepare`, `back`, `longpress`, `--hold-ms`, `--double-tap`, gestures, and clicks on an element with no accessibility action fail with `UNSUPPORTED_OPERATION` (`reason: unsupported-device-backend`). Use the default XCTest backend for those.
 
 ```bash