This map answers two questions: “which program should do this?” and “where should a change live?” It describes current ownership, not a deployment requirement that every component always be present.
The accepted consolidation direction is recorded in
repository-consolidation-and-publication.md.
The platform testbeds listed below have completed their explicit cutovers, so
their public implementation lives under machine-control; private deployment
inventory remains in dotfiles, and any focused external repository is legacy
or generated one-way.
| Component | Current role | Does not own |
|---|---|---|
~/code/yepanywhere |
Agent provider sessions, user supervision, relay transport, peer identity/grants, and proposed cross-host delegation | VM/device implementation details; generic hypervisor or desktop drivers |
~/code/dotfiles/testbeds |
Private concrete testbed inventory, controller availability, portable discovery, and locators for controller-local credential files; link to each current authoritative guide | Credential values, public lifecycle implementation, UI control, recovery, product assertions |
| Consuming application repository | Builds, fixtures, test intent, application-specific assertions, and cross-platform campaign logic | Machine provisioning and generic control transport |
Machine Control owns exact-resource target-use arbitration. A coordinator may supply claimant/session metadata and manage renewal around active work, but the claim contract does not name or require that coordinator. Private inventory selects claim policy and state placement without becoming the live arbiter.
Proposal: access admission and pause extends MC-owned arbitration with waiting, temporary availability and shared controller-desktop reservations. Native/controller UI presents notices and operator controls; YA consumes state for agent supervision. This adds no second VM lease authority and moves no private inventory ownership.
YepAnywhere's delegation direction is documented in
cross-host-delegation.md.
Delegation creates a normal worker session on a YA peer; it does not turn YA
into a raw proxy for every testbed CLI.
Current, unreleased desktop adoption: runtime/
owns ordinary Desktop and Browser surface consent, waiting/task admission,
countdown, pauses, cooldown and ownership. It also owns exact profile selection,
request/reference fencing and CDP stream lifetime. The Windows desktop resident
runs it as a privately bundled Node child through inherited framed pipes. C#
authenticates peers and operator decisions, observes native input/session facts,
executes OS effects, retains protected guards and audit/artifact storage, and
projects those facts into the child. The deterministic reference target executes
the same policy with modeled effects. The unreleased Mac adapter now uses this
policy with bounded ordinary, streamed-CDP and protected packaged acceptance.
The Linux adapter now uses the same policy and passes native handoff/profile
and sealed-package gates, including lock/restart and restored Off/claim release.
Its native read-only activity observer
belongs to Machine Control and exposes active-console-bound health/activity
facts only. It has no input or command API; ordinary desktop effects retain
AT-SPI/portal and never fall back to the appliance root input broker. Integrated
Linux qualification is tracked in Tactical 155.
The Python CLI/client remains the common agent-facing facade; this introduces
no YA coordinator, private inventory owner or public approval endpoint.
Tactical 152 records the accepted original Browser slice. Tactical 153 owns the subsequent unified permission/handoff model, completed broad review and bounded Windows qualification. Ordinary and locked Browser, matching-companion startup and enrolled Desktop acceptance have passed on the bounded unsigned Windows ARM64 candidate. Native provider/credential/cover/relock proof is separate from shared-policy conformance. Each adopted adapter removes its replaced ordinary policy engine and fails closed if the shared child is unavailable. Any separate appliance/protected provider retains its explicit capability and authority boundary; it is not an ordinary desktop fallback.
Decision: Runtime and presentation keeps Machine Control's runtime authority independent of its settings, native notice and tray presentation. Personal, minimal and appliance presentation are modes of one package, not new coordinators or authorization providers. The unreleased Mac, Windows and Linux implementations share this design while retaining their platform-native providers and process placement. Runtime and presentation owns current direction; Tactical 113 records combined-source ARM64 qualification and its release limits.
| Repository | Current role | Does not own |
|---|---|---|
machine-control |
Cross-platform architecture/research, the target-selecting common client and contracts, owned resident facades/provider boundaries, Windows service/session implementation, fixtures, conformance corpus, and post-cutover public platform/testbed implementation | Pre-cutover external testbed implementation, private deployment inventory, YA delegation, or product assertions |
Current: The Windows-first runtime establishes the implementation boundary
between authenticated local/remote callers, a Medium interactive-session
companion, replaceable providers, and a typed LocalSystem protected route. Its
physical x64 evidence covers ordinary system-shell control, UAC secure desktop,
elevated applications, lock, logout, and Windows boot recovery. The dual-boot
testbed must explicitly reselect Windows after one-shot EFI BootNext; a
generic reboot otherwise returns to its default OS.
Current: One common client now selects and validates the Windows, macOS, and Linux testbed adapters, while each adapter retains its own lifecycle, workspace/storage policy, and guest transport. The three residents pass one guarded common semantic, effect, capture, artifact, and local/outside parity workflow. Workspace callers request persistent, isolated, or candidate intent; the owning adapter chooses and reports the actual provider mechanism and binds cleanup to a private exact-identity receipt. This is a shared contract and entry experience, not one universal resident or hypervisor implementation. ChromeOS and device providers remain the next families to receive more common facade coverage. Their target-specific lifecycle and recovery already live in their authoritative platform directories here; broader facade coverage must not flatten their platform semantics into one generic implementation.
Current: the Mac desktop owns an experimental default-off covered locked-use profile. Its existing native executable launches a separate signed cover/input guardian, and its optional root authorization broker owns the deadline, restart marker, and failure relock. The unreleased recovery repair installs a root-owned, signed, non-setuid lock-only copy under PrivilegedHelperTools. The broker enters the original console's GUI bootstrap through fixed launchctl arguments; that copy drops to the console user, re-execs its fixed path and verifies the console again before requesting lock. The broker's own IOKit observation determines completion. This is a Machine Control provider placement detail, not a new delegation or arbitrary privileged-command surface. Permissions owns native SMAppService registration and typed helper preparation; System Settings owns service approval and authentication. Settings only changes the prepared local preference. The calling agent/integration owns a live bounded task connection and explicit completion. This adds no YA coordination or dotfiles inventory ownership and does not reuse exposed appliance unlock as a workstation fallback.
Current: The optional Windows workstation host is another deployment of Machine Control's shared ordinary providers. It runs under the interactive user; the existing appliance broker remains a separate privileged deployment profile. YepAnywhere consumes the installed desktop app's authenticated Python CLI, with default-off eligible session advertisement and media presentation. MC owns installation, updates, native access and resident lifecycle. YA's former workstation installer, grants, deferred tool and private process job are retired; it does not stop the independent desktop on session close or crash. The headless workstation profile and protected appliance remain independently available. The desktop's optional UAC helper is a separate administrator-installed LocalSystem service with a protected payload. The Medium desktop resident owns grants and live admission; the helper verifies that resident and calls back for each request's authority before effects. Permissions owns setup/removal, Settings owns per-run opt-in, and neither surface inherits the appliance's protected authority. The unreleased desktop locked-use integration reuses that protected payload with a separate controller grant. The Medium resident owns consent and task admission; the controller owns key and one-shot credential custody; an independent SYSTEM guardian owns failure relock for the bound console session. That Windows guardian now also owns the opaque single-display cover and physical-input interception. Windows uses its own Win32/DWM presentation mechanism; the Mac guardian remains a separate native implementation. Both profiles bind cleanup to the task's initial lock state. Consumer acceptance and its limits live in YA's topic; historical headless native acceptance remains in Tactical 036.
Current: Optional workstation unlock has an independent privileged service, administrator-owned grants and an elevated consent flow. Machine Control owns that installation and enforcement; YepAnywhere owns controller key/credential custody and product integration. The appliance broker is not its authorization fallback. See Windows protected unlock and Tactical 037.
| Repository | Administration/inner control | Outer control |
|---|---|---|
platforms/windows |
Authoritative UTM/macOS and libvirt/Linux lifecycle/workspace policy, minimized doctor, PowerShell/SSH administration, and bounded access to the Windows resident | UTM or headless QEMU screenshot and input remain explicit recovery routes |
platforms/macos |
Tart lifecycle and COW workspaces, the macOS resident, and the explicit existing-session unlock helper. The Intel KVM profile owns claimed Quickemu and libvirt lifecycle, libvirt workspaces, and pinned guest SSH | Tart for Tart guests. QMP and loopback VNC for Intel KVM bootstrap and recovery |
platforms/linux |
Authoritative UTM/macOS and libvirt/Linux lifecycle/workspace policy, minimized doctor, guest/session execution, and bounded access to the Linux resident | UTM or headless QEMU screenshot and input remain explicit recovery routes |
These repositories implement the right broad ordering: lifecycle and administration, then resident semantic/capture/input control, with outer pixels/input named only for bootstrap and recovery. Their guarded doctor and common conformance paths now enforce that ordinary control does not reach the outer route merely because it is convenient.
The opt-in Windows VirtualBox adapter owns native host identity, claims, lifecycle and pinned SSH for experimental Windows/Linux candidates. Guest residents and credential verifiers remain in their existing platform/runtime owners. Creation/bootstrap is not yet an adopted common factory, and promotion/workspace derivation remains unqualified.
| Repository | Current role | Important boundary |
|---|---|---|
platforms/chromeos |
Root SSH, browser CDP, Chrome desktop accessibility, screenshots, and device-native input on a designated developer-mode Chromebook | Update-sensitive and guest-resident; not an independent physical recovery path |
hardware-kvm-testbed |
Planned HDMI capture and USB HID for externally controlled physical hardware | Pixel/HID only; intended as outer recovery and independent observation, currently in bring-up |
platforms/ios |
Explicit physical-iPhone selection, signing lifetime, typed common iOS operations, CoreDevice lifecycle/crash reports, Agent Device semantic XCTest, libimobiledevice system logs, screenshots, input, leases, and recovery | The agent runs on the Mac; a stock iPhone cannot host a general YA worker |
platforms/android |
Explicit physical-handheld selection, common readiness, ADB administration/deployment/capture/input, and guarded one-shot PIN unlock | Phone keyguard policy is not inherited by Quest or every ADB derivative |
platforms/quest |
Explicit ADB target selection, device state, deployment, leases, and recovery for Quest | Protected headset/account surfaces remain human gates |
platforms/steamdeck |
Direct device administration and session-aware deployment/control | Physical recovery capability depends on available hardware and session state |
| Android-family shared ADB provider | Executable discovery, enumeration, exact transport, shell, battery, and wake parsing reused by Android and Quest | Device-profile lifecycle, protected operations, semantics, and safety policy |
| Component | Use it for | Do not make it |
|---|---|---|
| Research corpus | Provider architecture/license/evidence dossiers and per-platform option comparisons | Exact experiment log, source-pin store, decision topic, or implementation |
machine-control-spike |
Exact Cua pins, conformance evidence, macOS/Windows behavior, and security findings | The current architecture hub or production implementation |
| Cua Driver | Spike-supported provisional normal-user desktop core; exact-window semantics/capture, explicit delivery/effects, sessions, and strong fixtures | Cross-host coordinator, testbed lifecycle owner, protected-control trust foundation, or owner of the common contract |
| Open Computer Use | Compact agent-neutral Computer Use CLI/MCP across Windows, macOS, and Linux; first common-provider comparison candidate | Proven session/result/remote core or exact-window equivalent without conformance evidence |
| WinApp | Adopted WinVM UIA route, Windows comparison provider, and possible gap-filling adapter | Cross-platform core, effect oracle, or protected desktop provider |
| Touchpoint | Small cross-platform AX/UIA/AT-SPI/CDP facade and exact-window identity reference | Proven occlusion-independent capture or Wayland-input solution without target validation |
| Agent Device | Current iOS XCTest provider and a source of compact agent-oriented snapshot/action/recovery behavior | Exact-window macOS control, native Windows control, or the overall desktop/control fabric |
| libimobiledevice | Narrow adopted physical-iOS os_trace_relay provider behind bounded transactional system-log artifacts |
Replacement for CoreDevice/XCTest, general device shell, or duplicate owner of app/crash/file operations |
| Peekaboo | Deep macOS reference for exact-window capture, background action routing, transient system surfaces, and native fixture design | Cross-platform provider or protected-control boundary |
| kwin-mcp | Linux/KWin reference for isolated target-native Wayland sessions, AT-SPI, compositor capture, and libei input | Proven universal Linux desktop or exact-window facade |
| YepAnywhere Device Bridge | Human remote viewing and fast pixel/input backends, especially its iOS Simulator work | Semantic agent control or the cross-platform orchestration contract |
| RustDesk and similar remote desktop projects | AGPL-licensed reference architecture for session services, desktop switching, capture, and input | A wholesale trust boundary imported into the agent-facing system |
Detailed claims and evidence levels live in the
provider index and
platform index. Cross-provider decisions live
in provider-landscape.md. Being listed here
does not mean a provider has passed on every advertised platform.
When adding a capability:
- Put target-specific lifecycle, bootstrap, and recovery in the authoritative platform/testbed source: the external repository before its consolidation cutover and its platform directory here afterward.
- Put reusable resident semantic behavior and provider adapters here; keep a target-specific native runner in its authoritative platform/testbed source when it is not a reusable machine-control component.
- Put cross-provider capability vocabulary and conformance expectations here beside the implementation they govern.
- Put worker creation, peer authorization, observation, and supervision in YepAnywhere coordination.
- Put exact-target usage arbitration in Machine Control; let any coordinator consume that generic claim surface.
- Put product-specific assertions in the consuming application repository.
Do not add the same operation independently to all five layers. Choose one owner and expose it through adapters.
Machine Control owns the optional Tauri desktop operator application, its native resident/providers, grant enforcement, product updater key/configuration, and artifact acceptance. Desktop Release Kit owns the shared update contract and release validation reference; simple-app-update-server owns metadata routing over GitHub Releases. The Machine Control website owns the public desktop download page and resolves versioned installer links from the desktop release family; it does not implement the updater protocol. Dotfiles owns private signing credential locators and service deployment. YepAnywhere connects as a consumer rather than owning a second copy of the desktop application's grant UI or updater.
The Mac desktop embeds the Swift resident in its native process. Windows owns a distinct ordinary-user desktop companion and inherited operator transport, with grants enforced inside that companion. Its process job owns resident/ provider children while explicitly excluding user-launched applications. The headless workstation package and protected appliance remain separate profiles. Windows desktop owns the standalone workstream.
Linux owns an ordinary-user companion, inherited operator channel, native GTK approval process, and a distinct desktop socket. It reuses AT-SPI semantics while portal consent owns capture/input; root appliance input stays separate. Linux desktop owns the workstream, and the shared release family owns its eventual packages.
Current: Machine Control owns the Mac mc-sudo/mc-sudo-askpass pair,
its desktop packaging, local dialog and system-sudo authentication route.
YepAnywhere owns opt-in discovery, publisher verification and agent launch
instructions. This command route does not extend resident grants or the
Windows protected broker. See native sudo.
Current: desktop-app consumers use MC's bundled Python CLI and instructions. MC owns product installation, updates, resident lifecycle and native access; YA owns verified launch discovery, eligibility, optional adaptation and presentation. YA's old Windows component is retired after accepted installed native/browser, model, media and lifecycle checks. Session advertisement grants no access and closing YA does not revoke MC grants; native Stop, expiry and MC restart do. Installed agent CLI and YA Tactical 142 own the implementation and migration gates.