v25.11.15 - macOS Interactive Installer Fix

macOS Interactive Installer Fix

This release includes a comprehensive fix for the zenity error that macOS users were encountering during -upgrade operations.

The Problem

Users running -upgrade on macOS were seeing:

The graphical version of this installer cannot run on this system.
Try installing/updating Zenity, and run again.

The Solution

This release implements a bulletproof fix with multiple layers of protection:

1. Early Exit for -upgrade: Prevents any GUI code from running during upgrade operations
2. Capability Caching: Checks message-box properties only once during initialization, only on Linux/BSD
3. Cached Booleans: All subsequent checks use cached values instead of runtime property access
4. Platform Isolation: macOS never evaluates .kdialog or .zenity properties

Key Changes

Fix: Prevent zenity/kdialog checks from ever running on macOS

• Commit: e4212fe
• Added -upgrade flag handler to interactive.js
• Implemented message-box capability caching
• Replaced all direct property accesses with cached booleans
• Added try-catch safety for edge cases

Documentation & Structure Improvements

• Repo structure reorganization
• Module documentation updates
• Build dependency library renames (osx-* → macos-*)

Impact

✅ macOS + -upgrade: Works without errors
✅ macOS + GUI: Works with native osascript dialogs
✅ Linux: Continues to work as before with kdialog/zenity

Files Changed

• modules/interactive.js: Comprehensive zenity check prevention
  • Added: messageBoxCapabilities caching (14 lines)
  • Added: -upgrade flag handler (17 lines)
  • Modified: 3 property access locations → cached booleans

Testing Recommendations

• macOS without zenity: ./meshagent -upgrade
• macOS GUI: Double-click interactive installer
• Linux with kdialog: Test GUI installer
• Linux with zenity: Test GUI installer
• Linux without either: Verify error message shows correctly

Full Commit History

e4212fe Fix: Prevent zenity/kdialog checks from ever running on macOS
0e0187f repo structure changes
3399d41 CleanUP repo structure
2b034e8 Modules Documentation
8aa6f43 Build dependencies: Rename library directories and add documentation
183ddad Cleanup: Remove auto-generated commit info file
71c99f0 Update embedded JavaScript modules (polyfills)
951973d Bug fixes: Database, power monitor, proxy helper, interactive, and zlib
7cfa5ce Build tools: meshagent_code-utils for macOS
2b47ac2 Build tools: macOS signing and notarization workflow

---

Note: This is a draft release. Add build artifacts before publishing.

macOS Build System and KVM Enhancements v25.11.14

macOS Build System and KVM Enhancements

This release introduces comprehensive improvements to the macOS build system, installation workflow, and KVM implementation.

Key Features

ServiceID System and Installer Overhaul

• Support for multiple simultaneous MeshAgent installations
• Enhanced installation workflow with improved bootstrap and unload handling

macOS KVM Reversed Socket Architecture

• LaunchD integration for improved reliability
• Enhanced KVM functionality with better system integration

Build System Enhancements

• Universal binary support for both Intel and Apple Silicon
• Info.plist embedding
• Automated build workflows
• macOS signing and notarization scripts

Build Tools

• meshagent_code-utils binary for macOS
• Comprehensive build documentation

Bug Fixes

• Database module improvements
• Power monitor fixes
• Proxy helper enhancements
• Interactive module updates
• zlib compatibility fix

Build Dependencies

• Renamed library directories from osx-* to macos-*
• Added comprehensive documentation

Testing Completed

• ✅ Multiple MeshAgent installations coexisting using the ServiceID system
• ✅ macOS KVM functionality with reversed socket architecture and LaunchD integration
• ✅ Universal binary builds on both Intel and Apple Silicon Macs
• ✅ Code signing and notarization workflow
• ✅ Installer bootstrap and unload during installation process
• ✅ Bug fixes for database, power monitor, proxy helper, interactive module, and zlib

Files Changed

• 40 files changed, 6,364 insertions(+), 633 deletions(-)
• 10 commits squashed from 168 individual commits

🤖 Generated with Claude Code

v2025-11-10 - Dynamic Service Naming for Multi-Instance Deployments

v2025-11-10: macOS MeshAgent - Dynamic serviceId, -upgrade Function, and Comprehensive Documentation

Tag: v2025-11-10
Commit: 408e85ff1cb56ea64366f64aa84aeaf7ca4b4f88
Date: November 10, 2025
Author: Peet McKinney 68706879+PeetMcK@users.noreply.github.com

This release represents a complete modernization of the macOS MeshAgent installation and service management system, enabling multi-instance deployments, robust server-initiated updates, and dynamic service naming while maintaining 100% backward compatibility.

Development Period: November 6 - November 10, 2025
Commits: 24 commits
Files Changed: ~500 files (+40,000 additions, -10,000 deletions)
Pull Request: #5 - Dynamic serviceId & -upgrade Function

MAJOR FEATURES

1. DYNAMIC SERVICEID SYSTEM

• 4-case serviceId calculation from companyName and meshServiceName
• Enables multiple independent installations on the same system
• Format: meshagent[.serviceName][.companyName]
• Examples:
  • meshagent (default)
  • meshagent.acme (company only)
  • meshagent.tactical (service only)
  • meshagent.tactical.acme (both)
• Input sanitization: lowercase, alphanumeric + hyphen only
• Automatic serviceId propagation through all service components
• Implementation in modules/agent-installer.js:1949-2527

2. AUTOMATIC -UPGRADE FUNCTION

• Automatically called by MeshCentral during agent updates
• Entry point: upgradeAgent() in modules/agent-installer.js:1949
• Recreates LaunchDaemon and LaunchAgent plists with correct serviceId
• Comprehensive safety checks:
  • Service unload verification (prevents launchd restart loops)
  • Process termination verification (ensures clean state)
  • Orphaned plist cleanup (handles service renames)
• 5-tier configuration discovery system:
  • Priority: CLI flags → plist → .msh → .db → path
  • getServiceConfigFromPlist() - Reads authoritative config
  • parseMshFile() - Parses .msh configuration file
  • Auto-migration and auto-sync between sources
• 4 fallback service lookup strategies:
  • Service manager query
  • Self-upgrade detection
  • Plist scan (/Library/LaunchDaemons/)
  • Default path fallback
• Invoked automatically from C code (meshcore/agentcore.c:6613):

  case MeshAgent_Posix_PlatformTypes_LAUNCHD:
      sprintf_s(ILibScratchPad, sizeof(ILibScratchPad), "\"%s\" -upgrade", agentHost->exePath);
      ignore_result(system(ILibScratchPad));
      break;

3. LAUNCHAGENT QUEUEDIRECTORIES

• On-demand KVM helper activation via filesystem monitoring
• Dynamic socket paths: /var/run/{serviceId}/
• QueueDirectories configuration in LaunchAgent plist
• Resource-efficient: only runs when needed
• Proper --serviceId parameter passing to -kvm1
• SessionTypes: ['Aqua', 'LoginWindow']
• Implementation in modules/service-manager.js:1856-1923

4. COMPREHENSIVE DOCUMENTATION

• 4 documentation files totaling ~4,400 lines
• docs/meshagent/architecture.md (~1,400 lines):
  • LaunchDaemon/LaunchAgent dual-service architecture
  • QueueDirectories on-demand activation explained
  • Socket communication and IPC mechanisms
  • Process flows: boot, login, KVM requests, updates
• docs/meshagent/naming-and-configuration.md (~900 lines):
  • Dynamic serviceId calculation with flowcharts
  • Configuration priority chain (5 sources)
  • .msh file format specification
  • Multi-instance deployment examples
• docs/meshagent/installation-functions.md (~1,600 lines):
  • Complete -upgrade function reference
  • All installation function updates
  • Helper function documentation
  • Troubleshooting scenarios with solutions
• docs/meshagent/TLDReadMe.md (~500 lines):
  • "Too Long; Didn't Read" quick reference
  • serviceId calculator with flowchart
  • Copy-paste ready commands
  • Quick fixes and diagnostic one-liners
• 50+ code references with file:line citations
• 100+ practical examples

INSTALLATION FUNCTION UPDATES

1. ENHANCED -INSTALL FUNCTION

• Added serviceId calculation and propagation
• LaunchAgent creation with QueueDirectories
• Proper --serviceId parameter in both plists
• Auto-migration of legacy installations
• modules/agent-installer.js:1206+ lines added

2. ENHANCED -FULLINSTALL FUNCTION

• Added fallback installation discovery for service renames
• Handles multiple installations on same system
• Configuration priority: CLI → .msh → defaults
• Comprehensive validation and error handling

3. ENHANCED -UNINSTALL FUNCTION

• Added comprehensive cleanup for serviceId-based installations
• Orphaned plist removal across all possible serviceIds
• Database cleanup with proper serviceId detection
• Handles partial/failed installation cleanup

4. ENHANCED -FULLUNINSTALL FUNCTION

• Plist search fallback for all meshagent* services
• Removes all traces of any installation variant
• Self-directory cleanup for relocated installations
• Forces service unload before binary removal

CORE FUNCTIONALITY CHANGES

1. MODULES/AGENT-INSTALLER.JS (+1,206 LINES)

New Functions:

• upgradeAgent() - Main -upgrade entry point (lines 1949-2527)
• calculateServiceId() - 4-case calculation logic
• sanitizeIdentifier() - Cleans serviceName/companyName
• checkParameters() - CLI parameter parsing
• verifyServiceUnloaded() - Safety check for launchd
• verifyProcessesTerminated() - Safety check for processes
• forceBootoutService() - Emergency unload
• forceKillProcesses() - Emergency termination
• getServiceConfigFromPlist() - Authoritative config reader
• parseMshFile() - .msh configuration parser
• findInstallation() - 4-strategy service lookup
• createLaunchDaemon() - Updated with --serviceId
• createLaunchAgent() - Updated with QueueDirectories
• cleanupOrphanedPlists() - Removes old plists

2. MODULES/SERVICE-MANAGER.JS (+71 LINES)

LaunchAgent Enhancements:

• QueueDirectories: /var/run/{serviceId}/
• ProgramArguments includes --serviceId parameter
• SessionTypes: ['Aqua', 'LoginWindow']
• Label matches serviceId for consistency

LaunchDaemon Updates:

• ProgramArguments includes --serviceId parameter
• Label matches serviceId
• Proper RunAtLoad and KeepAlive settings

3. MESHCORE/AGENTCORE.C (+38 LINES)

Automatic -upgrade Invocation:

• Called after MeshCommand_AgentUpdate received
• Platform-specific handling for LAUNCHD
• Ensures plists updated with new binary location
• No manual intervention required for updates
• Implementation at meshcore/agentcore.c:6613

BUG FIXES

1. CRITICAL FIXES

• TypeError in upgradeAgent() - Missing JSON.parse() (commit 12320b4)
• Service lookup failure - Added 4 fallback strategies (commit 8752b15)
• Incorrect serviceId calculation in uninstall functions (commit 58a8a7d)
• QueueDirectories path mismatch - Fixed to use serviceId (commit 460a19d)
• .msh key naming - Standardized to PascalCase (commits a5d5711, 2810d94)

2. SAFETY IMPROVEMENTS

• Comprehensive service unload verification (commit 98f8175)
• Process termination verification (commit 98f8175)
• Force bootout on unload failure (commit 98f8175)
• Force kill on termination failure (commit 98f8175)

3. CONFIGURATION FIXES

• Fixed parameter passing in -upgrade command (commit 2a467e6)
• Fixed -import command parameter propagation (commit 55fe737)
• Added .msh persistence for all installation functions
• Fixed auto-sync between .msh and database

REPOSITORY CLEANUP

1. REMOVED FILES (~300 FILES)

• Old RE test files from docs/claude/Pollyfills/
• Duplicate binaries from scripts/meshagent/
• Obsolete scripts from scripts/ directory
• Test backups from tests/ directory

2. MOVED FILES (~200 FILES)

• RE tests → tools/tests/RE_Tests/
• Polyfills RE → tools/tests/RE_Tests/Polyfills_RE/
• Scripts → tools/scripts/macos_build/
• Meshagent binaries → tools/meshagent/{macos,linux}/

3. PATH STANDARDIZATION

• All scripts use relative paths from repo root
• No user-specific absolute paths
• Proper repo root detection in all scripts
• Fixed sign-and-notarize-macos-template.sh paths

4. NEW UTILITIES

• tools/scripts/Polyfills_update/ - Polyfills regeneration demo
• tools/scripts/meshagentDB_dump/ - Database dump utilities
• tools/meshagent/ - Organized binary storage
• Comprehensive README files for all tools

PLATFORM ISOLATION

All changes are macOS-specific and properly guarded:

C Code Guards:

#ifdef _POSIX
#ifdef __APPLE__
// macOS-specific code
#endif
#endif

JavaScript Guards:

if (process.platform == 'darwin') {
    // macOS-specific code
}

Zero impact on:

• Windows implementation
• Linux implementation
• Cross-platform functionality

BACKWARD COMPATIBILITY

100% backward compatible:

• ✅ Default serviceId remains meshagent
• ✅ Default paths unchanged
• ✅ Existing installations work without changes
• ✅ Updates handled automatically via -upgrade
• ✅ No breaking changes to API

New capabilities are opt-in:

• Custom serviceId via --companyName or --meshServiceName
• Multi-instance via different serviceIds
• All existing behavior preserved

MIGRATION GUIDE

FOR EXISTING INSTALLATIONS

No action required! When MeshCentral sends an update:

1. New binary is downloaded
2. Old binary backed up to .meshagent.backup.{timestamp}
3. C code automatically calls -upgrade
4. Plists recreated with correct serviceId
5. Services reloaded
6. Agent running with new functionality

FOR NEW INSTALLATIONS

Standard installation:

sudo ./meshagent -fullinstall --url="https://mesh.example.com/agent.ashx?id=xxxxx"

Custom serviceId:

sudo ./meshagent -fullinstal...

v2025-11-06

production-ready-macos-kvm1: macOS Multi-Session KVM with Code Signing & Notarization

Tag: production-readv-macos-kvm1-2025.11.6
Commit: 6aa5bc0cc15386e45d7507e5d6f68ae011b4d207
Date: November 5, 2025
Tagger: Peet McKinney 68706879+PeetMcK@users.noreply.github.com

This release represents a complete production-ready implementation of macOS remote desktop (KVM)
functionality with full code signing, notarization, and automated build infrastructure.

Development Period: October 28 - November 5, 2025
Commits: 95 commits
Files Changed: 40 files (+4,630 additions, -554 deletions)

MAJOR FEATURES

1. REVERSED ARCHITECTURE FOR MACOS KVM

• Redesigned KVM architecture to work within macOS security model
• Main daemon creates listening socket at /tmp/meshagent-kvm.sock
• LaunchAgent monitors /var/run/meshagent via QueueDirectories
• KVM process (-kvm1) CONNECTS to daemon (not spawned by daemon)
• Works around Apple bootstrap namespace restrictions
• Ensures -kvm1 runs in correct user context (LoginWindow or Aqua)
• Replaced process pipe IPC with domain socket communication
• Added code signature verification for socket connections (mac_kvm_auth.c/h)

2. MULTI-SESSION KVM SUPPORT

• Fixed critical race condition in multi-viewer KVM sessions
• Resolution message now sent IMMEDIATELY before tile data
• Prevents canvas initialization at wrong size for second viewer
• Fixed message ordering issues via direct KVM_SEND() instead of queue
• Supports multiple simultaneous remote desktop viewers
• Fixed CRC tile state bug for session reconnections

3. MACOS CODE SIGNING & NOTARIZATION INFRASTRUCTURE

• Complete automated signing pipeline (scripts/macos/sign-macos.sh)
• Automated notarization with xcrun notarytool (scripts/macos/notarize-macos.sh)
• Notarization ticket stapling support for offline verification
• Signs thin binaries (x86_64, arm64) before universal binary creation
• Proper signature propagation from thin to universal binaries
• Hardened runtime enabled, no entitlements required
• Keychain profile-based credentials (no environment variables)
• Parallel or sequential notarization modes
• Comprehensive error handling and status reporting

4. MACOS APP BUNDLE SUPPORT (EXPERIMENTAL - NOT DEPLOYED)

• App bundle creation during build (scripts/macos/create-app-bundle.sh)
• Bundle ID: com.ylianst.meshagent
• Auto-versioned from git commit date (YY.MMDD.HHMM format)
• Deep signing support for app bundles
• Bundle notarization and stapling
• NOTE: Standalone binary is the current and planned deployment path
• App bundle infrastructure built for future TCC GUI visibility exploration
• Background agent mode (LSUIElement=true, no Dock icon)
• Info.plist with proper metadata and permissions

5. PERMISSION HANDLING IMPROVEMENTS

• Full Disk Access (FDA) check (non-intrusive, no auto-launch)
• Screen Recording permission prompts
• Accessibility permission prompts
• Keyboard/mouse input at macOS loginwindow enabled
• Added -framework ApplicationServices linker flag for CGEventPost
• Disabled automatic System Settings launch for FDA check

BUILD SYSTEM IMPROVEMENTS

1. ORGANIZED BUILD INFRASTRUCTURE

• Centralized scripts into scripts/{macos,linux,windows}/ directories
• Comprehensive build pipeline (scripts/macos/build-pipeline-macos.sh)
• Template scripts for personal use (scripts/templates-for-bin/)
• Test script with git pull and plist refresh (test-macos-meshagent.sh)
• Build output organized: build/{osname}/{arch}/ directories
• Standardized naming: osx → macos throughout codebase

2. BUILD OUTPUTS

• build/macos/universal/meshagent (standalone signed binary - PRIMARY DEPLOYMENT)
• build/macos/universal/DEBUG_meshagent (debug binary)
• build/macos/universal/meshagent.app/ (experimental app bundle - not deployed)
• Proper exclusion of DEBUG binaries from notarization/stapling
• Standalone binary is the production deployment target

3. MAKEFILE ENHANCEMENTS

• App bundle creation integrated into universal binary builds
• Automatic version generation from git commit timestamps
• Renamed macos-arm-64 and macos-x86-64 (from osx-*)
• Updated library paths for consistency
• Added bundle signing and notarization hooks

BUG FIXES

1. MULTI-SESSION KVM FIXES

• Fixed message ordering race condition for multi-viewer KVM
• Fixed multi-session tile state bug (CRC reset on reconnect)
• Fixed multi-viewer resolution issue (MNG_KVM_REFRESH handling)
• Fixed infinite loop caused by zero-size frames in OnData
• Added MNG_JUMBO frame handling to OnData callback
• Fixed frame processing to handle variable-size messages

2. PERMISSION & INPUT FIXES

• Fixed keyboard/mouse input by removing KVM_AGENT_FD checks
• Enabled keyboard/mouse at loginwindow via CGEventPost
• Removed intrusive System Settings auto-launch for FDA

3. MACOS-SPECIFIC FIXES

• Fixed JSON parsing in proxy-helper.js (macos_getProxy)
• Fixed JSON parsing in power-monitor.js (_getBatteryLevel)
• Fixed macOS compilation error in zlib fdopen macro
• Fixed QueueDirectories folder deletion (clear contents vs delete)
• Fixed startup cleanup to preserve /var/run/meshagent directory

4. SIGNING/NOTARIZATION FIXES

• Fixed universal binary signature conflicts
• Fixed notarization ZIP structure for successful stapling
• Fixed duplicate binary detection (exclude .app bundle internals)
• Graceful handling of Error 73 for standalone binary stapling
• Fixed stapling to exclude DEBUG binaries
• Replace app bundle binary with signed universal before bundle signing

CODE QUALITY & CLEANUP

1. REMOVED VESTIGIAL CODE

• Removed old -kvm0 handler (replaced by -kvm1 LaunchAgent)
• Removed kvm_relay_feeddata() stub (unused on macOS)
• Removed KVM_Listener_FD variable (unused in reversed architecture)
• Removed deprecated process-spawning code
• Removed all debug logging from troubleshooting phase
• Removed entitlements infrastructure (not needed with hardened runtime)

2. DOCUMENTATION IMPROVEMENTS

• Comprehensive README.md in scripts/ directory
• Template documentation in scripts/templates-for-bin/
• REVERSED ARCHITECTURE documentation in mac_kvm.c
• Updated terminology: "slave" → "agent" throughout
• Clarified variable naming (restart = socket reconnect, not process)
• Added header documentation explaining architecture decisions

3. CODE ORGANIZATION

• Moved LaunchAgent plists to examples/launchd/mesh_services/
• Added TacticalRMM-compatible plists in examples/launchd/tacticalrmm/
• Updated default plists to match TacticalRMM structure
• Organized templates into dedicated templates-for-bin directory
• Cleaner root directory (moved utilities to scripts/)

LAUNCHD INTEGRATION

1. UPDATED PLIST FILES

• Added Disabled key (set to false) for explicit control
• Added StandardErrorPath and StandardOutPath for logging
• Updated QueueDirectories to /var/run/meshagent
• meshagent.plist: LaunchDaemon for root context
• meshagent-agent.plist: LaunchAgent for user context
• Compatible with both default and TacticalRMM installations

2. LOGGING & MONITORING

• Daemon logs: /tmp/meshagent-daemon.log
• Agent logs: /tmp/meshagent-agent.log (was KVMSlave.log)
• Proper log rotation and cleanup
• Directory watching via QueueDirectories trigger mechanism

CONFIGURATION & DEPLOYMENT

1. SOCKET & FILE PATHS

• KVM socket: /tmp/meshagent-kvm.sock (changed from /usr/local)
• Queue directory: /var/run/meshagent
• Session signal: /var/run/meshagent/session-active
• Installation: /usr/local/mesh_services/meshagent (default)
• Alternative: /opt/tacticalmesh (TacticalRMM)

2. TIMEOUTS & PERFORMANCE

• KVM socket connection timeout: 10s → 30s
• Frame rate throttling removed (caused artifacting)
• Removed 100% CPU usage in KVM loop
• Race condition fixes for socket initialization
• Proper cleanup of stale KVM session files on startup

DEVELOPER EXPERIENCE

1. SCRIPT TEMPLATES

• sign-and-notarize-macos-template.sh (version 0.0.9)
• test-macos-meshagent.sh (version 0.0.9)
• Sanitized templates with placeholder credentials
• Copy to /bin for personal customization (gitignored)
• Comprehensive setup instructions in scripts/templates-for-bin/README.md

2. TESTING & DEBUGGING

• Added startup cleanup for stale session files
• Debug logging infrastructure (disabled by default)
• Comprehensive frame processing debugging available
• Test script with optional git pull and plist refresh
• Clear error messages and status reporting

PLATFORM CONSISTENCY

1. CROSS-PLATFORM IMPROVEMENTS

• Standardized macOS naming (osx → macos everywhere)
• Added .clauderc for Claude Code project
• Updated .gitignore for build artifacts and private files
• Added auto-generated ILibDuktape_Commit.h to .gitignore
• Organized build scripts by platform

2. SCRIPT VERSIONING

• All scripts version 0.0.9
• Consistent version tracking across templates
• Version bumps documented in commit history

SECURITY ENHANCEMENTS

1. CODE SIGNATURE VERIFICATION

• Peer verification for socket connections
• SecCode API integration (mac_kvm_auth.c)
• Ensures only legitimate meshagent binaries connect
• Self-code signature comparison mechanism

2. HARDENED RUNTIME

• All binaries signed with hardened runtime
• No entitlements required (simplified workflow)
• Developer ID signature for all binaries and bundles
• Notarization for malware scanning

ARCHITECTURE NOTES

The reversed architecture (daemon listens, -kvm1 connects) is a fundamental
design decision for macOS. Traditional architectures where the daemon spawns
a child process do not work properly due to:

1. Apple's bootstrap namespace restrictions
2. LaunchAgent/LaunchDaemon security model
3. User session context requirements for Screen Recording/Accessibili...