perf: bound application point lookup

[steipete]

Summary

• replace AppLocator's synchronous all-application Accessibility scan with one ordered native on-screen window snapshot and direct PID resolution
• add exactApp(at:), which never broadens a miss to the frontmost application, while keeping the historical fallback only in app(at:)
• translate omitted AppKit mouse locations into the matching display's Quartz coordinate space, including multi-display layouts
• bound candidate resolution to unique window-owner PIDs and add deterministic ordering, fallback, performance, and coordinate tests

Performance

• baseline off-screen compatibility miss: 5.008 seconds
• updated focused test: 0.04-0.08 seconds on the same desktop
• source-blind live validation: eight fresh exact, compatibility, on-screen, and mouse runs completed in 39-76 ms

Proof

• swift test --filter AppLocatorTests (7/7)
• PEEKABOO_INCLUDE_AMBIENT_STATE_TESTS=false swift test (116/116 across both test targets)
• swift build -c release
• make check
• source-blind behavior contract: 12 passed, 0 failed, 0 blocked
• final P0-P2 autoreview: clean

Exact-head closeout

• rebased onto AXorcist main at 2f490388e6cb2c1b63092f92d1c2ef0b84d1f177 after the Peekaboo dependency consolidation landed
• reran focused and full tests, Release, strict checks, native-only gates, and P0-P2 autoreview on rebased head 68f4da760c4a951b326b3089d8ede65250b8cd90
• rebuilt the source-blind probe from the rebased head; eight fresh exact, compatibility, on-screen, and live-mouse runs completed in 43-67 ms with every expected PID and coordinate contract satisfied
• exact-head hosted CI passed; Peekaboo's gitlink remains untouched for a separate final pin

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[cursor]

PR Summary

Medium Risk
Changes which app is returned for pointer-based resolution (window stacking vs AX) and adds a public exact API; behavior is heavily tested but affects automation targeting.

Overview
AppLocator no longer walks every running app’s Accessibility windows to resolve which application owns a screen point. It now takes a single ordered CGWindowListCopyWindowInfo on-screen snapshot, matches the point against window bounds, and resolves unique owner PIDs to NSRunningApplication with the same eligibility rules as before.

New exactApp(at:) returns the owning app only when a window hits the point and never substitutes the frontmost app on a miss. app(at:) keeps the legacy frontmost fallback for compatibility. Omitted mouse locations are converted from AppKit to Quartz per display (multi-monitor), and the core locate path is exposed for tests via injectable window lists and application lookup.

Tests cover exact vs compatibility fallback, window ordering and deduplication, zero app queries on off-screen misses with large snapshots, and coordinate conversion.

^{Reviewed by Cursor Bugbot for commit 68f4da7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 13, 2026, 7:02 AM ET / 11:02 UTC.

ClawSweeper review

What this changes

The branch replaces Accessibility-wide application point lookup with native on-screen window-owner lookup, adds an exact-miss API, and tests coordinate, ordering, fallback, and performance behavior.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep open: current main does not contain this lookup redesign, and this collaborator-authored PR explicitly awaits a dependency consolidation before rebase and exact-head validation.

Priority: P2
Reviewed head: 68f4da760c4a951b326b3089d8ede65250b8cd90

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused and well-covered, with final confidence appropriately deferred until the explicitly planned rebase and desktop refresh.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored PR reports post-change desktop and test validation, and the external-contributor proof gate does not apply.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored PR reports post-change desktop and test validation, and the external-contributor proof gate does not apply.
Evidence reviewed	5 items	PR implementation: The PR head adds an exact lookup that returns nil on a miss while preserving the frontmost fallback only in the compatibility API. Bounded lookup and regression coverage: The implementation inspects ordered matching window-owner PIDs once, and the PR adds deterministic fallback, deduplication, large-snapshot, and multi-display tests. Current-main and release status: The lookup change is absent from current main, and no release tag contains the PR head; v0.1.6 contains the prior implementation.
Findings	None	None.
Security	None	None.

How this fits together

AXorcist maps a pointer location to the macOS application that should receive accessibility automation. This lookup feeds application targeting, where a match selects an eligible owner and a legacy compatibility path may instead return the frontmost app.

flowchart LR
A[Pointer request] --> B[Display coordinate conversion]
B --> C[On-screen window snapshot]
C --> D[Eligible window-owner lookup]
D --> E[Selected application]
C --> F[No matching window]
F --> G[Exact miss or legacy frontmost fallback]

Loading

Before merge

• Resolve merge risk (P1) - app(at:) changes point targeting from Accessibility-window traversal to native on-screen window ordering; overlapping-window and multi-display behavior should be re-proven after the planned rebase before merge.
• Complete next step (P2) - The stated merge ordering requires a rebase and exact-head desktop validation after the Peekaboo consolidation; this is not a repair-lane task.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and test delta	production +125/-25, tests +129, changelog +1 across 3 files	The lookup strategy changes substantially, while targeted coverage is slightly larger than the production delta.

Merge-risk options

Maintainer options:

1. Rebase and refresh desktop proof (recommended)
   After the dependency consolidation, rebase this PR and capture exact-head validation for overlapping windows, off-screen fallback, and multi-display mouse lookup before merging.

Technical review

Best possible solution:

Rebase onto the post-consolidation main branch, retain the explicit exact-versus-compatibility split, and land only after fresh desktop validation confirms targeting behavior on the final head.

Do we have a high-confidence way to reproduce the issue?

Unclear for the final merge head: the PR body reports live macOS validation, but it also states that it must be re-proven after its planned rebase.

Is this the best way to solve the issue?

Yes, subject to refreshed exact-head validation: one native on-screen snapshot with explicit exact and legacy-fallback policies is a narrow, maintainable way to bound the expensive lookup.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 2f490388e6cb.

Labels

Label justifications:

• P2: This is a bounded performance and targeting improvement with compatibility-sensitive but limited automation impact.
• merge-risk: 🚨 compatibility: Existing callers of the compatibility lookup may select a different app where native window stacking differs from prior Accessibility traversal.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This collaborator-authored PR reports post-change desktop and test validation, and the external-contributor proof gate does not apply.

Evidence

What I checked:

• PR implementation: The PR head adds an exact lookup that returns nil on a miss while preserving the frontmost fallback only in the compatibility API. (Sources/AXorcist/Core/AppLocator.swift:40, 68f4da760c4a)
• Bounded lookup and regression coverage: The implementation inspects ordered matching window-owner PIDs once, and the PR adds deterministic fallback, deduplication, large-snapshot, and multi-display tests. (Sources/AXorcist/Core/AppLocator.swift:78, 68f4da760c4a)
• Current-main and release status: The lookup change is absent from current main, and no release tag contains the PR head; v0.1.6 contains the prior implementation. (Sources/AXorcist/Core/AppLocator.swift:1, 2f490388e6cb)
• Feature provenance: Current-main AppLocator lines trace to the v0.1.6 release commit authored by Peter Steinberger; the proposed redesign is a later commit by the same area contributor. (Sources/AXorcist/Core/AppLocator.swift:1, dba24f0a2dd4)
• Repository scope policy: The only applicable repository policy asks that AXorcist changes remain minimal and that Peekaboo synchronization be considered when a submodule is bumped; this PR does not change a submodule. (AGENTS.md:1, 2f490388e6cb)

Likely related people:

• Peter Steinberger: Current-main AppLocator provenance is attributed to the v0.1.6 release commit he authored, and he authored the proposed bounded lookup change. (role: current implementation contributor and recent area author; confidence: high; commits: dba24f0a2dd4, 68f4da760c4a; files: Sources/AXorcist/Core/AppLocator.swift, Tests/AXorcistTests/AppLocatorTests.swift)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Rebase after the stated dependency consolidation and rerun the reported desktop validation against that exact head.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)

• reviewed 2026-08-13T10:28:35.217Z sha 8c9a83e :: needs maintainer review before merge. :: none

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: perf: bound application point lookup This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.