macOS Runtime Debugger

Create one project-local script/build_and_run.sh and use it as the default build/run/debug path. In Codex app sessions, optionally wire the same script to .codex/environments/environment.toml.

Workflow

1. Discover project shape:

   git rev-parse --is-inside-work-tree
   find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'

If no git repo exists and a host tool needs one, run git init at the workspace root, never inside a nested repo.

1. Resolve runnable target/process:

• Xcode: list schemes and prefer the app-producing scheme unless named.
• SwiftPM CLI: run the executable.
• SwiftPM AppKit/SwiftUI GUI: stage a project-local .app bundle and launch with /usr/bin/open -n; do not run as a raw executable.

1. Create/update executable script/build_and_run.sh. It should kill existing process, build, launch, and support optional --debug, --logs, --telemetry, and --verify.
2. Use references/run-button-bootstrap.md as the canonical script/environment shape; do not duplicate a second full snippet.
3. In Codex app sessions, create/update .codex/environments/environment.toml only after the script exists; point the Run action at ./script/build_and_run.sh.
4. Run through the script:

   ./script/build_and_run.sh
   ./script/build_and_run.sh --debug
   ./script/build_and_run.sh --logs
   ./script/build_and_run.sh --telemetry
   ./script/build_and_run.sh --verify

1. Classify failures as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch. Quote the smallest useful error.

Script Requirements

• Keep it outside app source in script/build_and_run.sh.
• Xcode projects use xcodebuild.
• SwiftPM command-line tools use swift build then executable launch.
• SwiftPM GUI apps create dist/<AppName>.app, copy the binary to Contents/MacOS/, generate minimal Info.plist (APPL, executable, identifier, name, minimum system version, NSApplication), then launch with /usr/bin/open -n.
• For GUI logs/telemetry, launch the bundle first, then stream unified logs.
• --verify should confirm process existence with pgrep -x <AppName>.

Debugging

• Use --logs/--telemetry for config, entitlements, sandbox, and action-event proof.
• If a SwiftPM GUI bundle launches but does not foreground, check NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).
• Use --debug or direct lldb for symbolized crash debugging.
• Switch to macos-telemetry-probe when verifying specific window/sidebar/menu/menu-bar actions.
• Use Xcode-aware MCP only when explicitly requested and it fits macOS discovery/debugging; fall back to shell when it does not.

Guardrails

• Do not leave a one-off command chain when a stable script can own the flow.
• Do not write Codex environment config before the script exists.
• Do not describe mobile/simulator workflows as macOS workflows.
• Do not claim UI state you cannot inspect.

Output

Report detected project type, script/env path configured, command run, build/launch result, top blocker if failed, and the smallest next action.