Xcode Sync

Synchronize exact Xcode builds across Peter's supported Macs. Use $remote-mac for fleet topology and SSH rules.

Inventory

1. Read ~/Projects/manager/computers.yaml; use live tailscale status --json for reachability/IPs.
2. Exclude handed-off and unknown hosts. Verify hostname, user, macOS, architecture, and hardware UUID before writes.
3. Deduplicate Tailscale nodes by hardware UUID; one Mac may have multiple live node records.
4. Run scripts/xcode-host-inventory.sh locally or remotely:

skills/xcode-sync/scripts/xcode-host-inventory.sh
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s' \
  < skills/xcode-sync/scripts/xcode-host-inventory.sh

Treat unreachable hosts as pending, not synchronized. Try live Tailscale IP, Tailscale SSH, then mDNS/LAN only when network topology permits.

Simulator hygiene

Every fleet Mac must pass the simulator-hygiene audit, including worker Macs where the correct result is not-applicable because Xcode and simctl are absent. Apple CoreSimulator's own classifications are authoritative: remove runtime images reported by simctl runtime delete --outdated --dry-run or --unusable --dry-run, plus simulator devices attached to unavailable runtimes. Do not classify a runtime as stale from its version number alone; stable and beta Xcodes can legitimately need different runtime generations on the same Mac.

Run the dependency-light audit locally or stream it to a remote Mac:

skills/xcode-sync/scripts/xcode-simulator-hygiene.sh
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s' \
  < skills/xcode-sync/scripts/xcode-simulator-hygiene.sh

The audit exits 1 for drift. After verifying the host identity and current Xcode work, repair with --repair; the action deletes unavailable devices and Apple's outdated/unusable runtime candidates, then re-audits. It refuses repair while a simulator device is booted. Do not use age-based runtime deletion, --notUsedSinceDays, or all for routine fleet maintenance.

Inspect source

Prefer the user's downloaded .xip; do not redownload it.

pkgutil --check-signature "$archive"
shasum -a 256 "$archive"
stage=$(mktemp -d /tmp/xcode.XXXXXX)
cleanup() { rm -rf "$stage"; }
trap cleanup EXIT
(cd "$stage" && xip --expand "$archive")
set -- "$stage"/Xcode*.app
[[ $# == 1 && -d "$1" ]]
app=$1
plutil -extract CFBundleShortVersionString raw -o - "$app/Contents/Info.plist"
plutil -extract ProductBuildVersion raw -o - "$app/Contents/version.plist"
plutil -extract LSMinimumSystemVersion raw -o - "$app/Contents/Info.plist"
DEVELOPER_DIR="$app/Contents/Developer" xcodebuild -version
cleanup
trap - EXIT

Require Apple Software signature. Compare ProductBuildVersion, not version label alone: two archives named Xcode 26.6 may contain different builds. Do not use DTXcodeBuild as the sync key; it can differ from the build reported by xcodebuild -version.

Compatibility

• Require Apple silicon for an Apple-silicon-only archive.
• Require host macOS >= LSMinimumSystemVersion.
• Fleet rule: install Xcode 26.6 only on macOS 26 Tahoe, version 26.2 or newer. Skip macOS 27 Golden Gate even if the bundle launches.
• Apply explicit user exclusions after technical checks.

Never change a host OS to make an Xcode build eligible unless explicitly requested.

Transfer and install

1. Transfer the signed archive, not an expanded app; preserve resumability:

rsync -a --partial --progress -e 'ssh -o RequestTTY=no -o RemoteCommand=none' \
  "$archive" HOST:Downloads/

2. Verify the remote SHA-256 and signature before expansion.
3. Expand on the destination. Use a single-quoted remote script or ssh HOST 'bash -s'; never let the local shell expand remote $variables or $(commands).
4. Keep this app policy:
   • current stable: /Applications/Xcode.app
   • newest prerelease, beta or RC: /Applications/Xcode-beta.app
   • previous-major stable: /Applications/Xcode-previous.app, only for three months after a new stable major ships unless the user sets another window
5. Replace same-major point releases and same-channel prereleases; do not preserve them. An RC replaces the beta slot. Validate the staged app, move the old app to a temporary rollback path, install and verify the new app, then delete the rollback copy. Run the CLI smoke gate below before deleting any rollback copy. Restore the old app on other failures; the smoke gate retains a failing unselected app for diagnosis.
6. When stable advances to a new major, rotate transactionally: move any existing Xcode-previous.app to a temporary rollback path, move the former stable to Xcode-previous.app, install and verify the new stable, then delete the older rollback copy. Pass the former stable's new path as the smoke gate's rollback. If it restores stable, also restore the older previous-major rollback to Xcode-previous.app. Restore both channel paths on other failures; retain both rollback copies on an unselected smoke failure. Record the new previous-major removal date in the task report.
7. Stop on unexpected destination collisions. Never delete an app outside these known channels without explicit confirmation.
8. Preserve xcode-select unless the user requests a switch. Replacing the app at the already-selected path preserves selection.

Use writable /Applications directly. Otherwise use passwordless sudo -n; if admin approval is required, show a local macOS authorization prompt or report the exact pending step. Do not bypass receipts or license state.

First launch and verification

Keep the rollback copy through first-launch setup and the CLI smoke gate. Confirm GNU timeout (or gtimeout, from coreutils) is available before replacing a bundle. For every installed app:

DEVELOPER_DIR="$app/Contents/Developer" xcodebuild -version
codesign --verify --deep --strict "$app"
DEVELOPER_DIR="$app/Contents/Developer" xcodebuild -checkFirstLaunchStatus

If first-launch status is nonzero:

sudo env DEVELOPER_DIR="$app/Contents/Developer" xcodebuild -license accept
sudo env DEVELOPER_DIR="$app/Contents/Developer" xcodebuild -runFirstLaunch

Recheck until status 0. If sudo/admin UI is unavailable, the app is installed but not ready; report that distinction.

After every installation or replacement, once license/first-launch setup is complete and before rollback cleanup, run the CLI smoke gate. xcrun may reject a healthy bundle until its license is accepted:

skills/xcode-sync/scripts/xcode-post-install-smoke.sh "$app" "$rollback"
# For a fresh install without an old bundle, omit the rollback argument.

One 20-second deadline covers the installed bundle's Contents/Developer/usr/bin/git --version and Contents/Developer/usr/bin/python3 -V, plus xcrun --find git when the bundle is the persistent xcode-select target. Selection lookup ignores the caller's DEVELOPER_DIR workaround. On failure, the helper exits nonzero and restores the supplied rollback at a selected path; it moves the failed app aside and prints its location. An unselected failure keeps the installed app and rollback, records failed-kept, and prints the workaround. A selected fresh install has no rollback: treat failed-no-rollback as immediate operator recovery. Use the same /Applications write privileges as the installation, and recheck the restored bundle. Never change xcode-select without the user's request.

Observed failure signature: Git and Python sleep forever at dyld start (sample shows _dyld_start), near-zero CPU, no children. Diagnose with timeout 8 /usr/bin/git --version; when a broken Xcode-beta is selected, use export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer in the affected session and every work order. Check the persistent target separately with env -u DEVELOPER_DIR xcode-select -p.

Finish with a host matrix: macOS, desired version/build, installed path, selected path, signature, CLI smoke status (including rollback/failed-bundle paths), first-launch state, simulator-hygiene state, previous-major removal date, and skip/failure reason. Keep source archives unless deletion is explicitly requested.