ci.yml

name: CI

on:
  push:
    branches:
      - main
  pull_request:
    paths:
      - "Sources/**"
      - "CLI/**"
      - "CLI-MCP/**"
      - "programaTests/**"
      - "tests/**"
      - "tests_v2/**"
      - "Resources/**"
      - "Assets.xcassets/**"
      - "vendor/**"
      - "windows/**"
      - "core/**"
      - "scripts/**"
      - ".github/workflows/**"
      - "GhosttyTabs.xcodeproj/**"
      - "programa.entitlements"
      - "programa-Bridging-Header.h"
      - "ghostty.h"
      - "session_escrow_shim.c"
      - "session_escrow_shim.h"
      # The bare "ghostty" entry catches submodule pointer bumps, which
      # "ghostty/**" alone misses.
      - "ghostty"
      - "ghostty/**"
      - ".gitmodules"
  # On-demand runs, so the typing-lag regression can be measured on a branch
  # BEFORE it merges. Without this the lag job only ever ran post-merge on main,
  # which made "measure p95 before and after" impossible to do pre-merge and left
  # perf changes to the keystroke path effectively unverifiable until too late.
  workflow_dispatch:
    inputs:
      notification_ui:
        description: Run the focused multi-window notification UI regression on macOS 26.
        type: boolean
        default: false
      windows_only:
        description: Run shared-core and Windows checks without the macOS test jobs
        type: boolean
        default: false
      lag_combo:
        description: >-
          Key the typing-lag harness repeats. "up" (the default, and what
          scheduled runs use) exercises the per-event hit-test path. A printable
          key such as "a" additionally reaches shouldRefreshAfterTextInput and
          therefore forceRefresh, which the arrow key never does -- the only way
          to measure the text-input half of the keystroke path.
        type: string
        default: up
      glass_surface:
        description: Liquid Glass surface measured as three OFF and three ON lag-harness runs.
        type: choice
        options:
          - window
          - sidebar
          - tabBar
          - browserToolbar
          - overlays
        default: window

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  change-detection:
    runs-on: ubuntu-latest
    outputs:
      run_app_jobs: ${{ steps.detect.outputs.run_app_jobs }}
      run_windows_jobs: ${{ steps.detect.outputs.run_windows_jobs }}
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0

      - name: Validate immutable workflow action pins
        run: ./scripts/validate-workflow-action-pins.py

      - name: Enforce structural lifecycle budgets
        run: ./scripts/check-structural-budgets.py

      - name: Validate deterministic app discovery
        run: ./tests/test_locate_built_app.sh

      - name: Detect changed files
        id: detect
        env:
          WINDOWS_ONLY: ${{ github.event_name == 'workflow_dispatch' && inputs.windows_only }}
        run: |
          set -euo pipefail

          if [[ "$WINDOWS_ONLY" == "true" ]]; then
            echo "run_app_jobs=false" >> "$GITHUB_OUTPUT"
            echo "run_windows_jobs=true" >> "$GITHUB_OUTPUT"
            echo "Manual Windows verification: macOS jobs excluded." >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          # Keep full CI for push events and non-PR runs.
          if [[ "${{ github.event_name }}" != "pull_request" ]]; then
            echo "run_app_jobs=true" >> "$GITHUB_OUTPUT"
            echo "run_windows_jobs=true" >> "$GITHUB_OUTPUT"
            echo "Changed files: full suite (non-PR context)" >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          BASE_SHA="${{ github.event.pull_request.base.sha }}"
          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
          git fetch --no-tags origin "${BASE_SHA}" "${HEAD_SHA}"
          CHANGED_FILES="$(git diff --name-only "${BASE_SHA}...${HEAD_SHA}")"
          CLASSIFICATION="$(printf '%s' "$CHANGED_FILES" | ./scripts/classify_ci_changes.sh)"
          APP_OUTPUT="${CLASSIFICATION%%$'\n'*}"

          if [[ "$APP_OUTPUT" != "$CLASSIFICATION" ]]; then
            echo "CI change classifier returned an invalid output shape" >&2
            exit 1
          fi

          case "$APP_OUTPUT" in
            run_app_jobs=true) RUN_APP_JOBS=true ;;
            run_app_jobs=false) RUN_APP_JOBS=false ;;
            *)
              echo "CI change classifier returned an invalid app result" >&2
              exit 1
              ;;
          esac

          printf '%s\n' "$CLASSIFICATION" >> "$GITHUB_OUTPUT"

          # The Windows build reads only windows/, core/ and its build script, so
          # a PR that touches none of them (or this workflow) skips it. Pushes to
          # main always build it.
          RUN_WINDOWS_JOBS=false
          if grep -qE '^(windows/|core/|scripts/build-windows\.ps1$|\.github/workflows/ci\.yml$)' <<< "$CHANGED_FILES"; then
            RUN_WINDOWS_JOBS=true
          fi
          echo "run_windows_jobs=${RUN_WINDOWS_JOBS}" >> "$GITHUB_OUTPUT"
          {
            echo "### CI scope decision"
            if [[ "$RUN_APP_JOBS" == "true" ]]; then
              echo "Changed file set contains app-relevant changes; running full macOS jobs."
            else
              echo "Pull request appears docs/workflow/localization-only; skipping heavy app jobs."
            fi
            echo ""
            echo "Changed files:"
            if [[ -z "${CHANGED_FILES}" ]]; then
              echo "- <none>"
            else
              printf '%s\n' "${CHANGED_FILES}"
            fi
          } >> "$GITHUB_STEP_SUMMARY"
  workflow-guard-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Validate GhosttyKit lock ownership
        run: ./tests/test_ensure_ghosttykit_locking.sh

      - name: Validate create-dmg version pinning
        run: ./tests/test_ci_create_dmg_pinned.sh

      - name: Validate unit-test runner behavior
        run: ./tests/test_ci_unit_test_runner_behavior.sh

      - name: Validate GhosttyKit checksum verification
        run: ./tests/test_ci_ghosttykit_checksum_verification.sh

      - name: Validate release artifact architecture checks
        run: ./tests/test_ci_universal_release_settings.sh

      - name: Validate rolling release publication
        run: ./tests/test_rolling_release_publication.sh

      - name: Validate rolling release state transitions
        run: node --test scripts/rolling_release_state.test.js

      - name: Validate release build identity
        run: node --test scripts/release_build_identity.test.js

      - name: Validate Sparkle enclosure naming and pruning
        run: node --test scripts/sparkle_enclosure.test.js

      - name: Validate v2 socket API contract has no drift
        run: ./scripts/check-v2-contract.sh

      - name: Validate settings and shortcut docs match the code
        run: python3 scripts/check-settings-docs.py

  shared-core:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - name: Set up Rust
        uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
      - name: Validate shared core
        run: |
          cargo fmt --manifest-path core/Cargo.toml --all -- --check
          # Runs the whole core/ workspace, including programad's unit and
          # integration tests (Unix socket + PTY, both available on
          # ubuntu-latest) now that it lives at core/crates/programad.
          cargo test --manifest-path core/Cargo.toml --workspace --locked
          # max_sendmsg_descriptors_close_without_leak and
          # too_many_descriptors_are_closed_before_the_reject_returns are
          # both #[ignore]d in the run above (see their doc comments in
          # fdpass.rs): the first's EPIPE assertion, and the precision of
          # the second's fd-count assertion, both want nothing else in the
          # process able to fork() while their fixture pipe is alive, which
          # the default parallel run can't guarantee against the
          # Linux-only session::tests that spawn real PTYs. --test-threads=1
          # with no other ignored tests in this binary runs both completely
          # alone.
          cargo test --manifest-path core/Cargo.toml -p programad --locked --lib -- --ignored --test-threads=1
          cargo test --manifest-path core/crates/programa-terminal/Cargo.toml --locked
          cargo test --manifest-path core/vendor/alacritty_terminal/Cargo.toml --locked --lib parses_buffered_bytes_before_returning_a_terminal_read_error

      - name: Smoke test programad
        run: |
          set -euo pipefail
          cargo build --manifest-path core/Cargo.toml -p programad --locked
          socket_dir="$(mktemp -d)"
          export XDG_RUNTIME_DIR="$socket_dir"
          export XDG_STATE_HOME="$socket_dir/state"
          socket_path="$socket_dir/programad.sock"
          ./core/target/debug/programad --socket "$socket_path" &
          daemon_pid=$!
          trap 'kill "$daemon_pid" 2>/dev/null || true' EXIT
          for _ in $(seq 1 50); do
            [ -S "$socket_path" ] && break
            sleep 0.1
          done
          python3 core/crates/programad/tests/smoke.py --socket "$socket_path"

  windows-build:
    needs: change-detection
    if: needs.change-detection.outputs.run_windows_jobs == 'true'
    runs-on: windows-latest
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Set up .NET
        uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
        with:
          dotnet-version: '10.0.x'

      - name: Set up Rust
        uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
        with:
          targets: x86_64-pc-windows-msvc

      - name: Validate and build Windows executable
        shell: pwsh
        env:
          PROGRAMA_CI_BUILD: ${{ github.run_id }}
          PROGRAMA_CI_COMMIT: ${{ github.sha }}
        run: |
          ./scripts/build-windows.ps1 -Version '0.0.0' -Build $env:PROGRAMA_CI_BUILD -Commit $env:PROGRAMA_CI_COMMIT -OutputDirectory "$env:RUNNER_TEMP/programa-windows-ci"

      - name: Run WinUI launch smoke test
        timeout-minutes: 3
        shell: pwsh
        run: |
          $ErrorActionPreference = 'Stop'
          $exe = "$env:RUNNER_TEMP/programa-windows-ci/programa-windows.exe"
          $logPath = "$env:LOCALAPPDATA\Programa\launch.log"
          if (Test-Path -LiteralPath $logPath) { Remove-Item -LiteralPath $logPath -Force }

          # Runs the full WinUI startup path -- Application.Start, MainWindow created and
          # activated, one terminal spawned -- unlike --version/--verify-native-libraries,
          # which both return before Application.Start is ever called. windows-latest
          # runners have an interactive-capable session for UI; if WinUI still refuses to
          # show a window here, this still exercises Application.Start and the exception
          # handlers added for exactly that case report the real error below instead of
          # the process just disappearing.
          #
          # programa.exe --smoke has its own internal watchdog (25s) that force-exits the
          # process even if Application.Start itself never returns. This step-level
          # timeout-minutes plus the explicit kill below is defense in depth on top of
          # that, not a substitute for it -- a first attempt at this smoke test hung for
          # the full 30-minute job timeout because nothing forced the process to exit.
          $proc = Start-Process -FilePath $exe -ArgumentList '--smoke' -PassThru -NoNewWindow
          $finished = $proc.WaitForExit(60000)
          if (-not $finished) {
            Write-Output 'Smoke test process did not exit within 60s; killing it.'
            try { $proc.Kill($true) } catch { Write-Output "Kill failed: $_" }
            $exitCode = -1
          } else {
            $exitCode = $proc.ExitCode
          }

          $logContent = if (Test-Path -LiteralPath $logPath) { Get-Content -LiteralPath $logPath -Raw } else { '' }
          $ok = ($exitCode -eq 0) -and ($logContent -match 'launch ok: window shown')

          if (-not $ok) {
            Write-Output "Smoke test FAILED. Exit code: $exitCode"
            if ($logContent) {
              Write-Output '--- launch.log ---'
              Write-Output $logContent
            } else {
              Write-Output "No launch.log was written at $logPath."
            }
            throw "WinUI launch smoke test failed (exit code $exitCode, log at $logPath)."
          }
          Write-Output "Smoke test passed. Exit code: $exitCode"
          Write-Output '--- launch.log ---'
          Write-Output $logContent

      - name: Upload Windows executable
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: programa-windows-ci
          path: ${{ runner.temp }}/programa-windows-ci/*.exe
          if-no-files-found: error

  # Build the Debug app + UI test bundle once and share it with every job that
  # only needs to *run* it (socket-integration-tests, tests-build-and-lag,
  # ui-regressions). Those three jobs used to each pay their own ~7 min
  # "Build app" step for an identical build; this collapses that to one.
  # unit-tests keeps building its own artifacts: it uses the programa-unit
  # scheme/test host, a different target from the programa app scheme built
  # here, so its output isn't the same product.
  build-app:
    needs: change-detection
    if: needs.change-detection.outputs.run_app_jobs == 'true'
    runs-on: macos-26
    timeout-minutes: 30
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-app
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          submodules: recursive

      - name: Select Xcode
        run: |
          set -euo pipefail
          XCODE_APP="$(ls -d /Applications/Xcode_26*.app 2>/dev/null | sort -V | tail -n 1 || true)"
          if [ -z "$XCODE_APP" ] && [ -d "/Applications/Xcode.app" ]; then
            XCODE_APP="/Applications/Xcode.app"
          fi
          if [ -z "$XCODE_APP" ]; then
            XCODE_APP="$(ls -d /Applications/Xcode*.app 2>/dev/null | sort | tail -n 1 || true)"
          fi
          if [ -z "$XCODE_APP" ]; then
            echo "No Xcode.app found under /Applications" >&2
            exit 1
          fi
          XCODE_DIR="$XCODE_APP/Contents/Developer"
          echo "DEVELOPER_DIR=$XCODE_DIR" >> "$GITHUB_ENV"
          export DEVELOPER_DIR="$XCODE_DIR"
          sudo xcode-select -s "$XCODE_DIR" || true
          xcodebuild -version

      - name: Resolve Ghostty revision
        id: ghostty-revision
        run: |
          set -euo pipefail
          revision="$(./scripts/ghostty_cache_revision.sh)"
          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"

      - name: Cache GhosttyKit.xcframework
        id: cache-ghosttykit-app
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: GhosttyKit.xcframework
          key: ghosttykit-v3-${{ steps.ghostty-revision.outputs.revision }}

      - name: Download pre-built GhosttyKit.xcframework
        if: steps.cache-ghosttykit-app.outputs.cache-hit != 'true'
        run: |
          ./scripts/download-prebuilt-ghosttykit.sh

      - name: Resolve zig version
        id: zig-version
        run: printf 'version=%s\n' "$(./scripts/required-zig-version.sh)" >> "$GITHUB_OUTPUT"

      # install-zig.sh re-checks the tarball against scripts/zig-macos-aarch64.sha256
      # on every run, so a cache hit never skips the checksum.
      - name: Cache zig toolchain tarball
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: ~/.cache/programa-zig-dist
          key: zig-dist-macos-arm64-${{ steps.zig-version.outputs.version }}

      - name: Install zig
        run: ./scripts/install-zig.sh

      - name: Cache Zig packages
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: ~/.cache/zig
          key: zig-packages-${{ hashFiles('ghostty/build.zig.zon', 'ghostty/build.zig.zon.json') }}
          restore-keys: zig-packages-

      # The "Copy Ghostty Resources" build phase compiles the Ghostty CLI helper
      # (Resources/bin/ghostty) with zig. zig's local cache turns that into a
      # no-op while the ghostty revision and zig version stay the same. No
      # restore-keys: an exact key keeps the cache from accumulating old builds.
      - name: Cache Ghostty CLI helper build
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: ghostty/.zig-cache
          key: ghostty-cli-helper-${{ steps.ghostty-revision.outputs.revision }}-zig${{ steps.zig-version.outputs.version }}

      - name: Cache DerivedData
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: ${{ env.PROGRAMA_DERIVED_DATA_DIR }}
          key: deriveddata-build-app-macos26-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}-${{ hashFiles('GhosttyTabs.xcodeproj/project.pbxproj') }}
          restore-keys: |
            deriveddata-build-app-macos26-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}-
            deriveddata-build-app-macos26-

      - name: Cache Swift packages
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: .ci-source-packages
          key: spm-build-app-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}
          restore-keys: spm-build-app-

      - name: Resolve Swift packages
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          mkdir -p "$SOURCE_PACKAGES_DIR"

          for attempt in 1 2 3; do
            if xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
              -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
              -resolvePackageDependencies; then
              exit 0
            fi
            if [ "$attempt" -eq 3 ]; then
              echo "Failed to resolve Swift packages after 3 attempts" >&2
              exit 1
            fi
            echo "Package resolution failed on attempt $attempt, retrying..."
            sleep $((attempt * 5))
          done

      # build-for-testing (not plain build) so the same artifact also covers
      # ui-regressions, which needs the programaUITests bundle + .xctestrun,
      # not just the app binary.
      - name: Build app and UI test bundle
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
            -disableAutomaticPackageResolution \
            -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
            -destination "platform=macOS" \
            build-for-testing

      - name: Package build artifact
        run: |
          set -euo pipefail
          tar -czf app-build.tar.gz -C "$PROGRAMA_DERIVED_DATA_DIR" Build/Products

      - name: Upload build artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: programa-app-build
          path: app-build.tar.gz
          if-no-files-found: error
          retention-days: 1

  # Sharded by test class (see scripts/list-programa-unit-test-classes.sh),
  # weight-balanced halves (scripts/unit-test-shard-weights.txt), so the ~11 min "Run unit tests" step runs as two
  # parallel matrix jobs instead of serially. The stateful class
  # (AppDelegateShortcutRoutingTests) always runs unsharded in shard 1 --
  # splitting it would risk cross-shard focus/window-state interference.
  # `unit-tests` below is the aggregate gate; downstream jobs still depend on
  # that name, not on this one.
  unit-tests-shard:
    needs: change-detection
    if: needs.change-detection.outputs.run_app_jobs == 'true'
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2]
    runs-on: macos-26
    timeout-minutes: 45
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-unit-${{ matrix.shard }}
      PROGRAMA_UNIT_TEST_SHARD: ${{ matrix.shard }}
      PROGRAMA_UNIT_TEST_SHARD_COUNT: 2
      # No unit test runs the Ghostty CLI helper (Resources/bin/ghostty), so the
      # shards take the build script's stub instead of compiling it with zig.
      # build-app still builds the real helper; its artifact feeds the jobs that
      # do run it (theme-picker-helper-regression, socket and UI tests).
      PROGRAMA_SKIP_ZIG_BUILD: "1"
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          submodules: recursive

      - name: Select Xcode
        run: |
          set -euo pipefail
          # Prefer Xcode 26 (macOS 26 SDK) so NSGlassEffectView / Liquid Glass compiles;
          # fall back to the image default when no Xcode 26 install exists.
          XCODE_APP="$(ls -d /Applications/Xcode_26*.app 2>/dev/null | sort -V | tail -n 1 || true)"
          if [ -z "$XCODE_APP" ] && [ -d "/Applications/Xcode.app" ]; then
            XCODE_APP="/Applications/Xcode.app"
          fi
          if [ -z "$XCODE_APP" ]; then
            XCODE_APP="$(ls -d /Applications/Xcode*.app 2>/dev/null | sort | tail -n 1 || true)"
          fi
          if [ -z "$XCODE_APP" ]; then
            echo "No Xcode.app found under /Applications" >&2
            exit 1
          fi
          XCODE_DIR="$XCODE_APP/Contents/Developer"
          echo "DEVELOPER_DIR=$XCODE_DIR" >> "$GITHUB_ENV"
          export DEVELOPER_DIR="$XCODE_DIR"
          sudo xcode-select -s "$XCODE_DIR" || true
          xcodebuild -version

      - name: Run Bonsplit package tests
        if: matrix.shard == 2
        run: swift test --package-path vendor/bonsplit

      - name: Validate Release reload artifact discovery
        run: ./tests/test_reloadp_programa_artifact.sh

      - name: Validate Ghostty cache revision
        run: ./tests/test_ghostty_cache_revision.sh

      - name: Validate CI change classification
        run: ./tests/test_ci_change_classification.sh

      - name: Validate reload entrypoint artifacts and dependency preparation
        run: ./tests/test_reload_entrypoints_artifacts.sh

      - name: Resolve Ghostty revision
        id: ghostty-revision
        run: |
          set -euo pipefail
          revision="$(./scripts/ghostty_cache_revision.sh)"
          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"

      - name: Cache GhosttyKit.xcframework
        id: cache-ghosttykit
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: GhosttyKit.xcframework
          key: ghosttykit-v3-${{ steps.ghostty-revision.outputs.revision }}

      - name: Download pre-built GhosttyKit.xcframework
        if: steps.cache-ghosttykit.outputs.cache-hit != 'true'
        run: |
          ./scripts/download-prebuilt-ghosttykit.sh


      - name: Cache DerivedData
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: ${{ env.PROGRAMA_DERIVED_DATA_DIR }}
          key: deriveddata-tests-macos26-shard${{ matrix.shard }}-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}-${{ hashFiles('GhosttyTabs.xcodeproj/project.pbxproj') }}
          restore-keys: |
            deriveddata-tests-macos26-shard${{ matrix.shard }}-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}-
            deriveddata-tests-macos26-shard${{ matrix.shard }}-

      - name: Cache Swift packages
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: .ci-source-packages
          key: spm-shard${{ matrix.shard }}-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}
          restore-keys: spm-shard${{ matrix.shard }}-

      - name: Resolve Swift packages
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          mkdir -p "$SOURCE_PACKAGES_DIR"

          for attempt in 1 2 3; do
            if xcodebuild -project GhosttyTabs.xcodeproj -scheme programa-unit -configuration Debug \
              -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
              -resolvePackageDependencies; then
              exit 0
            fi
            if [ "$attempt" -eq 3 ]; then
              echo "Failed to resolve Swift packages after 3 attempts" >&2
              exit 1
            fi
            echo "Package resolution failed on attempt $attempt, retrying..."
            sleep $((attempt * 5))
          done

      # Build and exercise the standalone CLI before the long XCTest bundle. This
      # keeps parser/security regressions observable even when an unrelated UI
      # unit test flakes later in the job.
      - name: Build programa CLI regression target
        id: cli-build
        run: |
          CLI_REGRESSION_DIR="$RUNNER_TEMP/programa-cli-regression"
          rm -rf "$CLI_REGRESSION_DIR"
          xcodebuild -project GhosttyTabs.xcodeproj \
            -target programa-cli \
            -configuration Debug \
            SYMROOT="$CLI_REGRESSION_DIR" \
            CODE_SIGNING_ALLOWED=NO \
            build

      - name: Install Fish for shell integration regressions
        run: brew install fish

      - name: Run typed CLI registry behavior regression
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        run: |
          set -euo pipefail

          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          if [ -z "${CLI_BIN:-}" ] || [ ! -x "$CLI_BIN" ]; then
            echo "programa CLI binary not found in DerivedData" >&2
            exit 1
          fi

          PROGRAMA_CLI_BIN="$CLI_BIN" python3 tests/test_cli_registry_behavior.py

      - name: Run CLI argument grammar regression
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        run: |
          set -euo pipefail

          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          if [ -z "${CLI_BIN:-}" ] || [ ! -x "$CLI_BIN" ]; then
            echo "programa CLI binary not found in DerivedData" >&2
            exit 1
          fi

          PROGRAMA_CLI_BIN="$CLI_BIN" python3 tests/test_cli_argument_grammar.py

      - name: Run Codex hook trust regression
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        run: |
          set -euo pipefail

          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          if [ -z "${CLI_BIN:-}" ] || [ ! -x "$CLI_BIN" ]; then
            echo "programa CLI binary not found in DerivedData" >&2
            exit 1
          fi

          PROGRAMA_CLI_BIN="$CLI_BIN" python3 tests/test_cli_codex_hook_trust.py

      - name: Run CLI sweep regressions
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        run: |
          set -euo pipefail
          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          test -x "$CLI_BIN"
          result=0
          for t in \
            tests/test_cli_noninteractive_install_regression.py \
            tests/test_cli_socket_no_autodiscovery_regression.py \
            tests/test_cli_wait_surface_agent_state.py \
            tests/test_cli_claude_settings_preservation.py \
            tests/test_shell_state_report_ordering.py; do
            PROGRAMA_CLI_BIN="$CLI_BIN" python3 "$t" || result=1
          done
          exit "$result"

      - name: Run hook confirmation EOF regressions
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        run: |
          set -euo pipefail
          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          test -x "$CLI_BIN"
          result=0
          for provider in codex claude opencode; do
            PROGRAMA_CLI="$CLI_BIN" python3 "tests_v2/test_${provider}_install_integration.py" --eof-only || result=1
          done
          exit "$result"

      - name: Run unit tests
        if: ${{ !cancelled() && steps.cli-build.outcome == 'success' }}
        env:
          PROGRAMA_UNIT_TEST_SCOPE: split-stateful
        run: ./scripts/ci-run-unit-tests.sh

      - name: Collect ghostty crash reports on failure
        if: failure()
        run: |
          mkdir -p /tmp/programa-unit-xcresults
          cp -R "$HOME/.local/state/ghostty/crash" /tmp/programa-unit-xcresults/ghostty-crash 2>/dev/null || true

      - name: Collect debug symbols for crash symbolication
        if: failure()
        # The crash reports above are sentry-native minidumps, which are useless
        # without the exact binary that produced them: a CI-only Debug build that
        # exists nowhere else. Two separate investigations of the same crash-loop
        # burned hours doing unsymbolicated image-offset matching because this
        # step did not exist. Copy the built products (Debug carries DWARF inside
        # the binaries) plus any dSYMs, so `lldb -o "target create --core <dmp>"`
        # can resolve frames to function names.
        run: |
          set -uo pipefail
          DERIVED="${PROGRAMA_DERIVED_DATA_DIR:-$HOME/Library/Developer/Xcode/DerivedData}"
          OUT=/tmp/programa-unit-xcresults/symbols
          mkdir -p "$OUT"
          find "$DERIVED" -maxdepth 5 -type d \( -name '*.app' -o -name '*.dSYM' \) -print0 2>/dev/null \
            | xargs -0 -I{} cp -R {} "$OUT/" 2>/dev/null || true
          # UUID index so a dump's debug_id can be matched to a file without
          # unpacking every bundle.
          find "$OUT" -type f -perm +111 -print0 2>/dev/null \
            | xargs -0 dwarfdump --uuid 2>/dev/null > "$OUT/uuids.txt" || true
          du -sh "$OUT" || true

      - name: Upload unit-test result bundles on failure
        if: failure()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: unit-test-xcresults-shard${{ matrix.shard }}-${{ github.run_attempt }}
          path: /tmp/programa-unit-xcresults/
          if-no-files-found: ignore
          retention-days: 7

      - name: Run CLI version memory guard regression
        run: |
          set -euo pipefail

          CLI_BIN="$RUNNER_TEMP/programa-cli-regression/Debug/programa"
          if [ -z "${CLI_BIN:-}" ] || [ ! -x "$CLI_BIN" ]; then
            echo "programa CLI binary not found at the job's exact build path" >&2
            exit 1
          fi

          PROGRAMA_CLI_BIN="$CLI_BIN" python3 tests/test_cli_version_memory_guard.py

  # Aggregate gate: downstream jobs and branch protection depend on the name
  # "unit-tests", not on the matrix job above, so sharding stays invisible to
  # everything that isn't ci.yml itself.
  # Shards skipped by change-detection (docs, other workflows) count as a pass;
  # a failed or cancelled shard, or a failed change-detection, does not.
  unit-tests:
    needs:
      - change-detection
      - unit-tests-shard
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Check shard results
        env:
          DETECTION_RESULT: ${{ needs.change-detection.result }}
          RUN_APP_JOBS: ${{ needs.change-detection.outputs.run_app_jobs }}
          SHARD_RESULT: ${{ needs.unit-tests-shard.result }}
        run: |
          if [[ "$SHARD_RESULT" == "success" ]]; then
            exit 0
          fi
          if [[ "$SHARD_RESULT" == "skipped" && "$DETECTION_RESULT" == "success" && "$RUN_APP_JOBS" != "true" ]]; then
            echo "unit-tests-shard skipped: no app-relevant changes"
            exit 0
          fi
          echo "unit-tests-shard: $SHARD_RESULT (change-detection: $DETECTION_RESULT, run_app_jobs: $RUN_APP_JOBS)" >&2
          exit 1

  # Independent of unit-tests: same "programa" scheme app build-app already
  # produces, so this reuses that artifact instead of paying for its own
  # ~3 min build. Split out so it no longer serializes behind the unit-test
  # shards either.
  theme-picker-helper-regression:
    needs:
      - build-app
      - change-detection
    if: needs.change-detection.outputs.run_app_jobs == 'true'
    runs-on: macos-26
    timeout-minutes: 15
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-theme-picker
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Download build artifact
        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
        with:
          name: programa-app-build
          path: .

      - name: Extract build artifact
        run: |
          set -euo pipefail
          mkdir -p "$PROGRAMA_DERIVED_DATA_DIR"
          tar -xzf app-build.tar.gz -C "$PROGRAMA_DERIVED_DATA_DIR"

      - name: Run bundled Ghostty theme picker helper regression
        run: |
          set -euo pipefail
          PROGRAMA_PREBUILT_APP_PATH="$PROGRAMA_DERIVED_DATA_DIR/Build/Products/Debug/Programa DEV.app" \
            ./tests/test_bundled_ghostty_theme_picker_helper.sh

  socket-integration-tests:
    needs:
      - build-app
      - change-detection
    if: needs.change-detection.outputs.run_app_jobs == 'true'
    # Matches build-app's runner OS: the artifact is a Debug binary built
    # against the macOS 26 SDK (Liquid Glass), so it must run on the same
    # OS version it was built for.
    runs-on: macos-26
    timeout-minutes: 40
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-socket-integration
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          submodules: recursive

      - name: Download build artifact
        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
        with:
          name: programa-app-build
          path: .

      - name: Extract build artifact
        run: |
          set -euo pipefail
          mkdir -p "$PROGRAMA_DERIVED_DATA_DIR"
          tar -xzf app-build.tar.gz -C "$PROGRAMA_DERIVED_DATA_DIR"

      - name: Create virtual display
        run: |
          set -euo pipefail
          clang -framework Foundation -framework CoreGraphics \
            -o /tmp/create-virtual-display scripts/create-virtual-display.m
          /tmp/create-virtual-display &
          VDISPLAY_PID=$!
          echo "VDISPLAY_PID=$VDISPLAY_PID" >> "$GITHUB_ENV"
          sleep 3
          kill -0 "$VDISPLAY_PID"

      - name: Run tests_v2 curated CI subset
        run: ./scripts/run-tests-v2-ci.sh

      - name: Verify ordinary-app scrollback privacy and recovery
        run: |
          set -euo pipefail
          APP="$(./scripts/locate-built-app.sh --configuration Debug --primary 'Programa DEV' --derived-data-root "$PROGRAMA_DERIVED_DATA_DIR")"
          python3 tests_v2/test_scrollback_privacy_recovery.py --app "$APP"

      - name: Cleanup virtual display
        if: always()
        run: |
          set -euo pipefail
          if [ -n "${VDISPLAY_PID:-}" ]; then
            kill "$VDISPLAY_PID" >/dev/null 2>&1 || true
          fi
          rm -f /tmp/create-virtual-display

  tests-build-and-lag:
    needs:
      - build-app
      - unit-tests
      - change-detection
    if: (github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')) && needs.change-detection.outputs.run_app_jobs == 'true'
    # Run the lag regression on GitHub-hosted runners, against the app built
    # once in build-app. Keep lag validation separate from UI regressions so
    # functional UI failures and performance regressions stay isolated.
    # Broader interactive UI suites still run via test-e2e.yml on
    # GitHub-hosted runners.
    runs-on: macos-26
    timeout-minutes: 90
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-lag
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          submodules: recursive

      - name: Download build artifact
        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
        with:
          name: programa-app-build
          path: .

      - name: Extract build artifact
        run: |
          set -euo pipefail
          mkdir -p "$PROGRAMA_DERIVED_DATA_DIR"
          tar -xzf app-build.tar.gz -C "$PROGRAMA_DERIVED_DATA_DIR"

      - name: Create virtual display
        run: |
          set -euo pipefail
          clang -framework Foundation -framework CoreGraphics \
            -o /tmp/create-virtual-display scripts/create-virtual-display.m
          /tmp/create-virtual-display &
          VDISPLAY_PID=$!
          echo "VDISPLAY_PID=$VDISPLAY_PID" >> "$GITHUB_ENV"
          sleep 3
          kill -0 "$VDISPLAY_PID"

      - name: Run workspace churn typing-lag regression
        run: |
          set -euo pipefail

          APP="$(./scripts/locate-built-app.sh \
            --configuration Debug \
            --primary "Programa DEV" \
            --derived-data-root "$PROGRAMA_DERIVED_DATA_DIR")"

          TAG="ci-lag"
          SOCK="/tmp/programa-debug-${TAG}.sock"
          BUNDLE_ID="$(
            /usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP/Contents/Info.plist" 2>/dev/null \
              || echo 'com.darkroom.programa.debug'
          )"

          pkill -x "Programa DEV" || true
          rm -f "$SOCK" "/tmp/programa-${TAG}.sock" || true
          defaults write "$BUNDLE_ID" socketControlMode -string full >/dev/null 2>&1 || true

          PROGRAMA_TAG="$TAG" PROGRAMA_SOCKET_PATH="$SOCK" PROGRAMA_UI_TEST_MODE=1 "$APP/Contents/MacOS/Programa DEV" >/tmp/programa-ci-lag.log 2>&1 &
          APP_PID=$!
          trap 'kill "$APP_PID" >/dev/null 2>&1 || true' EXIT

          for _ in {1..240}; do
            [ -S "$SOCK" ] && break
            sleep 0.25
          done
          [ -S "$SOCK" ] || { echo "Socket not ready at $SOCK" >&2; exit 1; }

          PROGRAMA_SOCKET_PATH="$SOCK" \
          PROGRAMA_LAG_MAX_P95_RATIO=1.70 \
          PROGRAMA_LAG_MAX_AVG_RATIO=1.70 \
          PROGRAMA_LAG_MIN_BASELINE_P95_MS_FOR_RATIO=6.0 \
          PROGRAMA_LAG_MIN_BASELINE_AVG_MS_FOR_RATIO=4.0 \
          PROGRAMA_LAG_MAX_P95_DELTA_MS=20.0 \
          PROGRAMA_LAG_MAX_AVG_DELTA_MS=12.0 \
          PROGRAMA_LAG_MAX_CHURN_P95_MS=35 \
          PROGRAMA_LAG_KEY_EVENTS=180 \
          PROGRAMA_LAG_KEY_COMBO="${{ inputs.lag_combo || 'up' }}" \
          python3 tests_v2/test_workspace_churn_up_arrow_lag.py

      - name: Compare Liquid Glass OFF and ON (report only)
        if: github.event_name == 'workflow_dispatch'
        run: |
          set -euo pipefail
          APP="$(./scripts/locate-built-app.sh \
            --configuration Debug \
            --primary "Programa DEV" \
            --derived-data-root "$PROGRAMA_DERIVED_DATA_DIR")"
          PROGRAMA_LAG_KEY_COMBO="${{ inputs.lag_combo || 'up' }}" \
            ./scripts/run-glass-perf-gate.sh "$APP" "${{ inputs.glass_surface || 'window' }}"

      # On-demand only. This measures the refresh call itself with an in-process
      # timer rather than an end-to-end socket round trip, because that round trip
      # is order-milliseconds and cannot resolve a change of this size -- four runs
      # of the forceRefresh change produced completely overlapping ranges (#183).
      #
      # Runs in its own app instance: the sampler only records when
      # PROGRAMA_TYPING_TIMING_LOGS=1, and enabling that for the lag harness above
      # would add logging to the very path that harness measures.
      #
      # Reports numbers, asserts no budget. There is no baseline yet, and a
      # threshold invented before any data would be a number from nowhere.
      - name: Measure text-input refresh cost (dispatch only)
        if: github.event_name == 'workflow_dispatch'
        run: |
          set -euo pipefail

          APP="$(./scripts/locate-built-app.sh \
            --configuration Debug \
            --primary "Programa DEV" \
            --derived-data-root "$PROGRAMA_DERIVED_DATA_DIR")"

          TAG="ci-refresh-cost"
          SOCK="/tmp/programa-debug-${TAG}.sock"
          BUNDLE_ID="$(
            /usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP/Contents/Info.plist" 2>/dev/null \
              || echo 'com.darkroom.programa.debug'
          )"

          pkill -x "Programa DEV" || true
          rm -f "$SOCK" || true
          defaults write "$BUNDLE_ID" socketControlMode -string full >/dev/null 2>&1 || true

          PROGRAMA_TAG="$TAG" PROGRAMA_SOCKET_PATH="$SOCK" PROGRAMA_UI_TEST_MODE=1 \
            PROGRAMA_TYPING_TIMING_LOGS=1 \
            "$APP/Contents/MacOS/Programa DEV" >/tmp/programa-ci-refresh-cost.log 2>&1 &
          APP_PID=$!
          trap 'kill "$APP_PID" >/dev/null 2>&1 || true' EXIT

          for _ in {1..240}; do
            [ -S "$SOCK" ] && break
            sleep 0.25
          done
          [ -S "$SOCK" ] || { echo "Socket not ready at $SOCK" >&2; exit 1; }

          # Surface the app's own log on failure. Without this the step can only say
          # "Socket closed while waiting for response" -- which tells you the app died
          # or refused the connection, but not why, and its log sits on the runner
          # where nobody can read it. That cost a full four-run cycle to learn nothing.
          if ! PROGRAMA_SOCKET_PATH="$SOCK" \
               PROGRAMA_REFRESH_COST_KEY_EVENTS=400 \
               python3 tests_v2/test_text_input_refresh_cost.py | tee -a "$GITHUB_STEP_SUMMARY"; then
            echo "--- app still running? ---"
            pgrep -x "Programa DEV" >/dev/null && echo "yes" || echo "NO - it exited"
            echo "--- socket present at $SOCK? ---"
            [ -S "$SOCK" ] && echo "yes" || echo "NO"
            echo "--- tail of /tmp/programa-ci-refresh-cost.log ---"
            tail -80 /tmp/programa-ci-refresh-cost.log 2>/dev/null || echo "(no log)"
            exit 1
          fi

      - name: Cleanup virtual display
        if: always()
        run: |
          set -euo pipefail
          if [ -n "${VDISPLAY_PID:-}" ]; then
            kill "$VDISPLAY_PID" >/dev/null 2>&1 || true
          fi
          rm -f /tmp/create-virtual-display

  ui-regressions:
    needs:
      - build-app
      - unit-tests
      - change-detection
    if: ((github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'workflow_dispatch' && inputs.notification_ui)) && needs.change-detection.outputs.run_app_jobs == 'true'
    runs-on: macos-26
    timeout-minutes: 60
    env:
      PROGRAMA_DERIVED_DATA_DIR: ${{ github.workspace }}/.ci-derived-data-ui-regressions
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          submodules: recursive

      - name: Select Xcode
        run: |
          set -euo pipefail
          # Prefer Xcode 26 (macOS 26 SDK) so NSGlassEffectView / Liquid Glass compiles;
          # fall back to the image default when no Xcode 26 install exists.
          XCODE_APP="$(ls -d /Applications/Xcode_26*.app 2>/dev/null | sort -V | tail -n 1 || true)"
          if [ -z "$XCODE_APP" ] && [ -d "/Applications/Xcode.app" ]; then
            XCODE_APP="/Applications/Xcode.app"
          fi
          if [ -z "$XCODE_APP" ]; then
            XCODE_APP="$(ls -d /Applications/Xcode*.app 2>/dev/null | sort | tail -n 1 || true)"
          fi
          if [ -z "$XCODE_APP" ]; then
            echo "No Xcode.app found under /Applications" >&2
            exit 1
          fi
          XCODE_DIR="$XCODE_APP/Contents/Developer"
          echo "DEVELOPER_DIR=$XCODE_DIR" >> "$GITHUB_ENV"
          export DEVELOPER_DIR="$XCODE_DIR"
          sudo xcode-select -s "$XCODE_DIR" || true
          xcodebuild -version
          xcrun --sdk macosx --show-sdk-path

      # test-without-building still passes -clonedSourcePackagesDirPath /
      # -disableAutomaticPackageResolution, so it needs the resolved SPM
      # checkouts present even though build-app already compiled everything.
      - name: Cache Swift packages
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4
        with:
          path: .ci-source-packages
          key: spm-ui-regressions-${{ hashFiles('GhosttyTabs.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}
          restore-keys: spm-ui-regressions-

      - name: Resolve Swift packages
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          mkdir -p "$SOURCE_PACKAGES_DIR"

          for attempt in 1 2 3; do
            if xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
              -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
              -resolvePackageDependencies; then
              exit 0
            fi
            if [ "$attempt" -eq 3 ]; then
              echo "Failed to resolve Swift packages after 3 attempts" >&2
              exit 1
            fi
            echo "Package resolution failed on attempt $attempt, retrying..."
            sleep $((attempt * 5))
          done

      - name: Download build artifact
        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
        with:
          name: programa-app-build
          path: .

      - name: Extract build artifact
        run: |
          set -euo pipefail
          mkdir -p "$PROGRAMA_DERIVED_DATA_DIR"
          tar -xzf app-build.tar.gz -C "$PROGRAMA_DERIVED_DATA_DIR"

      - name: Create persistent virtual display
        run: |
          set -euo pipefail
          HELPER_PATH="/tmp/create-virtual-display"
          clang -framework Foundation -framework CoreGraphics \
            -o "$HELPER_PATH" scripts/create-virtual-display.m

          VDISPLAY_READY="/tmp/programa-vdisplay-persistent.ready"
          VDISPLAY_ID_PATH="/tmp/programa-vdisplay-persistent.id"
          rm -f "$VDISPLAY_READY" "$VDISPLAY_ID_PATH"

          # Declare every mode the later display-resolution churn step will
          # switch between (see that step's comment for why it reuses this
          # display instead of creating its own): a CGVirtualDisplay can only
          # be driven to a mode it was created with.
          "$HELPER_PATH" \
            --modes "1920x1080,1728x1117,1600x900,1440x810" \
            --ready-path "$VDISPLAY_READY" \
            --display-id-path "$VDISPLAY_ID_PATH" \
            > /tmp/programa-vdisplay-persistent.log 2>&1 &
          echo "VDISPLAY_PERSISTENT_PID=$!" >> "$GITHUB_ENV"

          echo "Waiting for persistent virtual display..."
          for i in $(seq 1 24); do
            if [ -f "$VDISPLAY_READY" ]; then break; fi
            sleep 0.5
          done
          if [ ! -f "$VDISPLAY_READY" ]; then
            echo "ERROR: Persistent virtual display not ready after 12s" >&2
            cat /tmp/programa-vdisplay-persistent.log 2>/dev/null || true
            exit 1
          fi
          echo "Persistent virtual display ready: ID=$(cat "$VDISPLAY_ID_PATH")"

      # Informational only until it has a track record: this test has never
      # passed on any main run in the project's history (it was masked by a
      # missing exit 1 until 2026-09-16, then blocked every ship for a day).
      # With the window placed, active, and focused on the virtual display,
      # presents still do not advance during mode churn, so the expectation
      # itself is unproven. It keeps running and logging; it does not gate.
      # Promote back to gating once it passes consistently on main.
      - name: Run display resolution churn UI regression
        if: github.event_name != 'workflow_dispatch'
        continue-on-error: true
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          HELPER_PATH="/tmp/create-virtual-display"
          TOKEN="$(uuidgen)"
          DIAG_PATH="/tmp/programa-ui-test-display-churn-${TOKEN}.json"
          DISPLAY_READY="/tmp/programa-ui-test-display-${TOKEN}.ready"
          DISPLAY_ID_PATH="/tmp/programa-ui-test-display-${TOKEN}.id"
          DISPLAY_START="/tmp/programa-ui-test-display-${TOKEN}.start"
          DISPLAY_DONE="/tmp/programa-ui-test-display-${TOKEN}.done"
          HELPER_LOG="/tmp/programa-ui-test-display-${TOKEN}-helper.log"

          # This churn test used to spin up its own second CGVirtualDisplay
          # alongside the persistent one from the previous step. A headless CI
          # session only reliably holds one live CGVirtualDisplay at a time —
          # the second instantiation was reproducibly failing with "Failed to
          # create CGVirtualDisplay" on both retry attempts (a masked bug: an
          # earlier version of this step didn't fail the job when that
          # happened, so it silently never ran the regression test at all).
          # Reuse the persistent display's ID instead of creating a second one.
          PERSISTENT_ID_PATH="/tmp/programa-vdisplay-persistent.id"
          if [ ! -f "$PERSISTENT_ID_PATH" ]; then
            echo "ERROR: Persistent virtual display ID file missing at $PERSISTENT_ID_PATH" >&2
            exit 1
          fi
          PERSISTENT_DISPLAY_ID="$(cat "$PERSISTENT_ID_PATH")"

          cleanup() {
            pkill -x "Programa DEV" 2>/dev/null || true
            rm -f "$DIAG_PATH" "$DISPLAY_READY" "$DISPLAY_ID_PATH" "$DISPLAY_START" "$DISPLAY_DONE" "$HELPER_LOG"
            rm -f /tmp/programa-ui-test-prelaunch.json /tmp/programa-ui-test-display-harness.json
          }
          trap cleanup EXIT

          # Build display helper
          clang -framework Foundation -framework CoreGraphics \
            -o "$HELPER_PATH" scripts/create-virtual-display.m

          APP="$(./scripts/locate-built-app.sh \
            --configuration Debug \
            --primary "Programa DEV" \
            --derived-data-root "$PROGRAMA_DERIVED_DATA_DIR")"
          APP_BINARY="$APP/Contents/MacOS/Programa DEV"
          echo "App binary: $APP_BINARY"

          for attempt in 1 2; do
            cleanup 2>/dev/null || true

            # Attach to the persistent display and churn its modes, rather than
            # creating a second CGVirtualDisplay (see comment above).
            # Use --start-delay-ms instead of --start-path because the XCTest
            # runner is sandboxed and can't write to /tmp/ for the start signal.
            # 10s delay gives the test time to capture baseline render stats.
            "$HELPER_PATH" \
              --attach-id "$PERSISTENT_DISPLAY_ID" \
              --modes "1920x1080,1728x1117,1600x900,1440x810" \
              --ready-path "$DISPLAY_READY" \
              --display-id-path "$DISPLAY_ID_PATH" \
              --done-path "$DISPLAY_DONE" \
              --iterations 40 \
              --interval-ms 40 \
              --start-delay-ms 10000 \
              > "$HELPER_LOG" 2>&1 &
            HELPER_PID=$!

            # Wait for display ready (attaching is effectively instant, but
            # keep the same bounded wait for consistency with the harness
            # manifest contract the UI test reads).
            echo "Waiting for virtual display..."
            for i in $(seq 1 24); do
              if [ -f "$DISPLAY_READY" ]; then break; fi
              sleep 0.5
            done
            if [ ! -f "$DISPLAY_READY" ]; then
              echo "ERROR: Virtual display not ready after 12s" >&2
              cat "$HELPER_LOG" 2>/dev/null || true
              kill "$HELPER_PID" 2>/dev/null || true
              wait "$HELPER_PID" 2>/dev/null || true
              continue
            fi
            DISPLAY_ID=$(cat "$DISPLAY_ID_PATH")
            echo "Virtual display ready: ID=$DISPLAY_ID"

            # Launch app from shell (non-sandboxed, outside XCTest sandbox)
            PROGRAMA_UI_TEST_MODE=1 \
            PROGRAMA_UI_TEST_DIAGNOSTICS_PATH="$DIAG_PATH" \
            PROGRAMA_UI_TEST_DISPLAY_RENDER_STATS=1 \
            PROGRAMA_UI_TEST_TARGET_DISPLAY_ID="$DISPLAY_ID" \
            PROGRAMA_TAG="ui-tests-display-resolution" \
            "$APP_BINARY" > /tmp/programa-ui-test-app.log 2>&1 &
            APP_PID=$!
            echo "App launched: PID=$APP_PID"

            # Wait for app diagnostics
            echo "Waiting for app diagnostics..."
            APP_READY=false
            for i in $(seq 1 30); do
              if [ -f "$DIAG_PATH" ]; then
                if python3 -c "import json; d=json.load(open('$DIAG_PATH')); assert d.get('pid')" 2>/dev/null; then
                  APP_READY=true
                  break
                fi
              fi
              if ! kill -0 "$APP_PID" 2>/dev/null; then
                echo "ERROR: App crashed during startup"
                cat /tmp/programa-ui-test-app.log 2>/dev/null | tail -30 || true
                break
              fi
              sleep 0.5
            done

            if [ "$APP_READY" != "true" ]; then
              echo "Attempt $attempt: App not ready after 15s"
              pkill -x "Programa DEV" 2>/dev/null || true
              kill "$HELPER_PID" 2>/dev/null || true
              if [ "$attempt" -eq 2 ]; then
                echo "Display resolution UI regression failed after 2 attempts" >&2
                echo "--- App log ---"
                cat /tmp/programa-ui-test-app.log 2>/dev/null | tail -50 || true
                echo "--- Helper log ---"
                cat "$HELPER_LOG" 2>/dev/null | tail -20 || true
                echo "--- Diagnostics ---"
                cat "$DIAG_PATH" 2>/dev/null || echo "(not found)"
                exit 1
              fi
              sleep 3
              continue
            fi

            echo "App started. Diagnostics:"
            cat "$DIAG_PATH"

            # This runner cannot reliably place the app's window on the virtual
            # display being churned: on macos-26 AppKit can move the window off
            # it once its mode starts changing. (The churn attaches to the job's
            # persistent display because a headless session holds only one.) When that
            # happens the regression can't be exercised at all: skip rather than
            # fail so a harness limitation doesn't block CI, but only when the
            # placement itself failed — a working harness must still fail on a
            # real regression. The app's own placement logic retries for ~5s
            # after launch (20 attempts, 0.25s apart), so poll rather than
            # reading this once, to avoid skipping on a healthy runner that
            # just hasn't finished its first placement attempt yet.
            echo "Checking whether the window landed on the virtual display..."
            TARGET_DISPLAY_PLACED=false
            for i in $(seq 1 16); do
              if python3 -c "import json; d=json.load(open('$DIAG_PATH')); assert d.get('targetDisplayMoveSucceeded') == '1'" 2>/dev/null; then
                TARGET_DISPLAY_PLACED=true
                break
              fi
              sleep 0.5
            done
            if [ "$TARGET_DISPLAY_PLACED" != "true" ]; then
              echo "SKIPPED: the runner could not place the app window on the virtual display; the display churn regression cannot be exercised here (see docs/testing-layout.md)"
              echo "--- Diagnostics ---"
              cat "$DIAG_PATH" 2>/dev/null || true
              exit 0
            fi

            # Activate the app so ghostty_app_set_focus(true) fires. The app is
            # launched here as a bare Process (not via XCUIApplication.launch(),
            # which blocks ~60s trying to foreground-activate on headless CI), so
            # its own in-process NSRunningApplication.current.activate() call
            # silently fails without a real WindowServer frontmost app. Driving
            # activation externally via System Events, targeted by PID, is a
            # different code path and works even when the in-process call doesn't.
            osascript -e "tell application \"System Events\" to set frontmost of (first process whose unix id is $APP_PID) to true" \
              >/tmp/programa-ui-test-activate.log 2>&1 \
              || echo "WARNING: External activation via System Events failed (see /tmp/programa-ui-test-activate.log)"

            # Wait for render stats (terminal surface initialization)
            echo "Waiting for render stats..."
            RENDER_READY=false
            for i in $(seq 1 40); do
              if python3 -c "import json; d=json.load(open('$DIAG_PATH')); assert d.get('renderStatsAvailable') == '1'" 2>/dev/null; then
                RENDER_READY=true
                echo "Render stats available after $((i / 2))s"
                break
              fi
              sleep 0.5
            done
            if [ "$RENDER_READY" != "true" ]; then
              echo "WARNING: Render stats not available after 20s. Diagnostics:"
              cat "$DIAG_PATH" 2>/dev/null || true
              echo "--- App log ---"
              cat /tmp/programa-ui-test-app.log 2>/dev/null | tail -30 || true
            fi

            # Write manifests so test can find the pre-launched state
            MANIFEST_PATH="/tmp/programa-ui-test-display-harness.json"
            cat >"$MANIFEST_PATH" <<MANIFEST_EOF
          {"readyPath":"$DISPLAY_READY","displayIDPath":"$DISPLAY_ID_PATH","donePath":"$DISPLAY_DONE","logPath":"$HELPER_LOG"}
          MANIFEST_EOF

            PRELAUNCH_PATH="/tmp/programa-ui-test-prelaunch.json"
            cat >"$PRELAUNCH_PATH" <<PRELAUNCH_EOF
          {"diagnosticsPath":"$DIAG_PATH"}
          PRELAUNCH_EOF

            # Run test — app is already launched from shell
            if xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
              -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
              -disableAutomaticPackageResolution \
              -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
              -destination "platform=macOS" \
              -only-testing:programaUITests/DisplayResolutionRegressionUITests \
              test-without-building; then
              exit 0
            fi

            pkill -x "Programa DEV" 2>/dev/null || true
            kill "$HELPER_PID" 2>/dev/null || true

            if [ "$attempt" -eq 2 ]; then
              echo "Display resolution UI regression failed after 2 attempts" >&2
              exit 1
            fi
            echo "Attempt $attempt failed, retrying..."
            sleep 3
          done
          echo "ERROR: Display resolution UI regression exhausted both attempts without a passing test run" >&2
          exit 1

      - name: Run browser find focus UI regression
        if: github.event_name != 'workflow_dispatch'
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
            -disableAutomaticPackageResolution \
            -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
            -destination "platform=macOS" \
            -maximum-test-execution-time-allowance 180 \
            -only-testing:programaUITests/BrowserPaneNavigationKeybindUITests/testCmdFFocusesBrowserFindFieldAfterCmdDCmdLNavigation \
            test-without-building

      # Close confirmations guard against losing running processes; they run
      # on every main push so a regression shows up one merge later at most.
      - name: Run close-confirmation UI regressions
        if: github.event_name != 'workflow_dispatch'
        timeout-minutes: 25
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
            -disableAutomaticPackageResolution \
            -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
            -destination "platform=macOS" \
            -maximum-test-execution-time-allowance 180 \
            -only-testing:programaUITests/CloseWorkspaceConfirmDialogUITests \
            -only-testing:programaUITests/CloseWorkspacesConfirmDialogUITests \
            -only-testing:programaUITests/CloseWorkspaceCmdDUITests \
            test-without-building

      - name: Run multi-window notification focus UI regression
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
            -disableAutomaticPackageResolution \
            -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
            -destination "platform=macOS" \
            -maximum-test-execution-time-allowance 180 \
            -only-testing:programaUITests/MultiWindowNotificationsUITests/testNotifyCLIDoesNotStealFocusAcrossWindows \
            test-without-building

      - name: Run window close Cancel UI regression
        run: |
          set -euo pipefail
          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
          xcodebuild -project GhosttyTabs.xcodeproj -scheme programa -configuration Debug \
            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
            -disableAutomaticPackageResolution \
            -derivedDataPath "$PROGRAMA_DERIVED_DATA_DIR" \
            -destination "platform=macOS" \
            -maximum-test-execution-time-allowance 180 \
            -only-testing:programaUITests/WindowCloseConfirmCancelUITests \
            test-without-building

      - name: Dump notification regression diagnostics
        if: failure()
        run: |
          set +e
          for f in /tmp/programa-ui-test-multi-window-notifs-*.json; do
            [ -f "$f" ] || continue
            echo "== harness data: $f"; cat "$f"; echo
          done
          for f in /tmp/programa-debug-ui-tests-multi-window-notifs-*.log; do
            [ -f "$f" ] || continue
            echo "== app debug log (activation/focus/notification/single_instance): $f"
            grep -E 'app\.activation|notification\.|single_instance|focusMainWindow|window\.key|makeKey|orderFront|surface\.action|notify' "$f" | tail -n 150
            echo "== app debug log tail: $f"; tail -n 80 "$f"
          done

      - name: Cleanup persistent virtual display
        if: always()
        run: |
          if [ -n "${VDISPLAY_PERSISTENT_PID:-}" ]; then
            kill "$VDISPLAY_PERSISTENT_PID" >/dev/null 2>&1 || true
          fi
          rm -f /tmp/programa-vdisplay-persistent.ready /tmp/programa-vdisplay-persistent.id /tmp/programa-vdisplay-persistent.log