Bgclick Rev

---
name: bgclick-rev
description: Reverse-engineer a macOS GUI automation app's background-click path and produce a Swift reproduction. Use only when the user provides a target .app and explicitly asks for IDA-backed background-click reverse engineering. Requires IDA Pro with IDA MCP attached.
---

# Background-Click Reverse Engineering

Use this skill only for research on a user-provided macOS `.app`. If IDA Pro or IDA MCP is unavailable, stop early and explain the blocker. Do not modify Uni-CLI source code from this skill; write research artifacts and reproduction code only after the binary evidence is gathered.

## Outputs

Create a research bundle under `<workspace>/research/`:

- `SHARED-CONTEXT.md` with target paths, bundle IDs, signing status, IDA MCP instance mapping, and priors to verify.
- `findings/<phase-or-question>.md` for call-site maps and open questions.
- `sub_<addr>-<label>.md` for every decompiled function used as evidence.
- `frame-map.md` for Swift async task-frame offsets.
- `FINAL-REPORT.md` with behavior spec, evidence table, reproduction diff, and VM test plan.

If asked to build a reproduction, add:

- `Sources/<Module>/BackgroundClicker.swift`
- `EchoApp/main.swift`
- `impl-research.md` with empirical VM runs.

## Priors To Verify

Treat these as hypotheses until confirmed in the target binary:

- Events are posted with `CGEvent.postToPid(_:)`.
- The synthetic event starts as `NSEvent.mouseEvent(...)`, then uses `event.cgEvent`.
- Explicit integer fields are `3` button, `7` subtype value `3`, `91` window under pointer, and `92` window that can handle the event.
- Screen location is set, read back, translated by the target window origin, and written with `CGEventSetWindowLocation` resolved by `dlsym`.
- Background targets receive `CGEventFlags.maskCommand` (`0x00100000`), not the non-coalesced flag.
- `CGWindowID` comes from `CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID)` filtered by owner PID.
- Do not double-write fields already populated by `NSEvent.cgEvent`.
- The click path should not activate the target app through AppKit, AX frontmost setters, or SLS/CGS private activation APIs.

## Workflow

1. Triage the `.app`: locate main executable and helper apps, record `codesign -d --entitlements -`, `nm -u`, and relevant Mach-O paths.
2. Confirm IDA MCP instances and map each instance to a binary in `SHARED-CONTEXT.md`.
3. Audit service binary call sites upward from `CGWindowListCopyWindowInfo`, `CGWindowListCreateDescriptionFromArray`, AX APIs, screen-capture APIs, `dlsym`, and `dlopen`.
4. Identify the dispatch function that logs or formats the click dispatch message, then trace the Swift async continuation chain into the synthesizer.
5. For each decompiled function used, write `research/sub_<addr>-<label>.md` with a one-line verdict, trimmed evidence, frame writes, and Swift equivalent.
6. Resolve dyld-hash wrappers to concrete CoreGraphics symbols. Verify with `dlsym` on a comparable macOS host when possible.
7. Produce `findings/cgevent-fields.md` mapping every explicit `setIntegerValueField` write to SDK constants and source expressions.
8. Hunt open questions independently. Each finding file starts with a one-sentence verdict and includes evidence addresses.
9. Build `BackgroundClicker.swift` only from verified behavior. Use public AppKit/CoreGraphics APIs plus `dlsym` for `CGEventSetWindowLocation`.
10. Validate in a VM with an EchoApp counter window. Record window number, screen point, window-local point, activation state, and pass/fail in `impl-research.md`.

## Guardrails

- Keep all reverse-engineered evidence in `research/`; do not paste large decompiler output into chat.
- Mark unknowns as open questions instead of guessing.
- Never label `0x100000` as non-coalesced; it is the Command flag.
- Activation selectors found elsewhere in the binary are not evidence unless they are on the verified click path.