helper: validate external launch agent bridge

[gaelic-ghost]

Summary:

• add an inherited sandbox helper probe matching Apple's embedded CLI recipe
• add an external user LaunchAgent install script for the non-sandboxed helper
• document the Mach lookup requirement and localhost socket fallback

Verification:

• xcodebuild focused helper tests
• scripts/validate-installed-automation-helper.sh
• scripts/manage-external-automation-helper.sh install --check-xpc, then uninstall
• scripts/repo-maintenance/validate-all.sh

Summary by CodeRabbit

Release Notes

• New Features

  • Added diagnostic command for automation helper status validation
  • Introduced external helper management tool for local testing scenarios
  • Enhanced validation probe with improved installer testing support

• Documentation

  • Updated testing guidance with clearer, more detailed procedures
  • Expanded roadmap with comprehensive validation workflows

• Improvements

  • Strengthened automation helper connection validation
  • Enhanced diagnostic error messaging for better troubleshooting

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1c7c8bbf-3630-4f63-8179-e993443890cb

📥 Commits

Reviewing files that changed from the base of the PR and between 0e509c9 and 1166f7b.

📒 Files selected for processing (18)

• Docs/Architecture/RealAppTestingPlan.md
• README.md
• ROADMAP.md
• Sirious.xcodeproj/project.pbxproj
• Sources/App/AutomationHelperCommandRunner.swift
• Sources/App/AutomationHelperDiagnostics.swift
• Sources/AutomationHelper/main.swift
• Sources/AutomationHelperSupport/AutomationHelperXPC.swift
• Sources/InheritedSandboxHelper/main.swift
• Sources/Support/Sirious.entitlements
• Sources/Support/SiriousInheritedSandboxHelper.entitlements
• Sources/Support/com.galewilliams.Sirious.AutomationHelper.plist
• Tests/SiriousTests/AutomationHelperAgentStateTests.swift
• Tests/SiriousTests/AutomationHelperCommandRunnerTests.swift
• Tests/SiriousTests/AutomationHelperDiagnosticsTests.swift
• project.yml
• scripts/manage-external-automation-helper.sh
• scripts/validate-installed-automation-helper.sh

---

📝 Walkthrough

Walkthrough

Adds a SiriousInheritedSandboxHelper embedded tool target (source, entitlements, full pbxproj/XcodeGen wiring) and a --inherited-helper-status diagnostic to probe it. Hardens all XPC connections with code-signing requirements and activate() on both app and helper sides. Realigns the bundled LaunchAgent plist to HelperTools, adds Aqua session type and ProgramArguments. Introduces a new manage-external-automation-helper.sh lifecycle script and expands validate-installed-automation-helper.sh with package-style installer support and inherited-helper signature/entitlement checks. Updates README, ROADMAP, and architecture docs with observed validation results and a localhost-socket fallback plan.

Changes

Automation Helper XPC Hardening & Inherited Sandbox Probe

Layer / File(s)	Summary
XPC signing contracts, entitlements, and LaunchAgent plist Sources/AutomationHelperSupport/AutomationHelperXPC.swift, Sources/Support/Sirious.entitlements, Sources/Support/SiriousInheritedSandboxHelper.entitlements, Sources/Support/com.galewilliams.Sirious.AutomationHelper.plist	AutomationHelperXPC gains team/bundle identifier constants, code-signing requirement strings, and a connection-error formatter. Main app entitlements add the Mach lookup temporary exception. New inherited sandbox helper entitlements file is created. Bundled LaunchAgent plist updated to Contents/Library/HelperTools, Aqua session type, and explicit ProgramArguments.
SiriousInheritedSandboxHelper target wiring and --inherited-helper-status diagnostic Sources/InheritedSandboxHelper/main.swift, project.yml, Sirious.xcodeproj/project.pbxproj, Sources/App/AutomationHelperDiagnostics.swift, Tests/SiriousTests/AutomationHelperDiagnosticsTests.swift	Adds the new tool's Swift source, XcodeGen target definition, and complete pbxproj wiring (build phases, configurations, copy rules, target dependency). AutomationHelperDiagnostics gains --inherited-helper-status handled by InheritedSandboxHelperDiagnostics.run(), which launches the bundled helper via Process and returns output-based results. Test coverage added for the new flag.
XPC activate() and signing requirement enforcement on both sides Sources/AutomationHelper/main.swift, Sources/App/AutomationHelperCommandRunner.swift, Sources/App/AutomationHelperDiagnostics.swift, Tests/SiriousTests/AutomationHelperCommandRunnerTests.swift, Tests/SiriousTests/AutomationHelperAgentStateTests.swift	SiriousAutomationHelper XPC listener switches resume() → activate() and applies appCodeSigningRequirement on accepted connections. App-side NSXPCConnection sets helperCodeSigningRequirement and calls activate(). Proxy errors routed through AutomationHelperXPC.connectionErrorMessage. finishWithConnectionError refactored to delegate to finishWithConnectionErrorMessage. Tests verify signing identifiers, requirement strings, and error message content. LaunchAgent plist shape test updated for new path/session/arguments.
External helper lifecycle management script scripts/manage-external-automation-helper.sh	New script supporting install, status, restart, uninstall actions. Validates --install-root and --launch-agent-dir are HOME-scoped. Implements write_plist(), build_helper(), install_helper() (codesign + launchctl bootstrap/kickstart), print_status() (with optional XPC diagnostic), and uninstall_helper().
Validation script package-style support and inherited helper diagnostics scripts/validate-installed-automation-helper.sh	Adds --package-style mode using pkgbuild/installer, --uninstall early-exit, and --require-service-found flag. Refactors install/cleanup into named functions. Adds inherited sandbox helper executable, signature, and entitlement checks. Expands SMAppService .notFound handling to distinguish registration-requested vs package-style paths.
README, ROADMAP, and architecture doc updates README.md, ROADMAP.md, Docs/Architecture/RealAppTestingPlan.md	README adds package-style probe instructions, external-helper lane, and uninstall guidance. ROADMAP milestone 1 and 4 checklists expanded with full helper validation sequence. Architecture doc updates automation helper recipe, current .notFound results, external LaunchAgent observations, and adds a localhost-socket fallback plan.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 A helper now inherits the sandbox's grace,
XPC wakes with activate() in place,
The plist moves to HelperTools' new home,
Scripts spin up Mach services and roam,
.notFound still lingers—but the plan is clear,
Localhost sockets wait if the Mach path won't appear!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch validation/helper-install-workflow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1166f7be4c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Build the helper by target or share its scheme

In a fresh checkout, git ls-files 'Sirious.xcodeproj/xcshareddata/xcschemes/*' only shows Sirious.xcscheme, but this new install path asks xcodebuild for a SiriousAutomationHelper scheme. The xcodebuild man page distinguishes -scheme (“Build the scheme specified by schemename”) from -target (“Build the target specified by targetname”), so install/--check-xpc fails before installing the external helper unless the developer has a private local helper scheme. Please either generate/share a helper scheme in project.yml or build with -target SiriousAutomationHelper.

Useful? React with 👍 / 👎.