ci.yml

# .github/workflows/ci.yml

name: 'LLxprt Code CI'

on:
  push:
    branches:
      - 'main'
      - 'release/**'
  pull_request:
    branches:
      - 'main'
      - 'release/**'
      - 'dev/**'
  merge_group:
  workflow_dispatch:
    inputs:
      prereview_pr:
        description: 'Optional PR number for runner-local prereview validation'
        type: string
        default: ''
      prereview_head:
        description: 'Expected immutable head SHA for prereview validation'
        type: string
        default: ''

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  checks: 'write'
  contents: 'read'
  statuses: 'write'

defaults:
  run:
    shell: 'bash'

env:
  ACTIONLINT_VERSION: '1.7.7'
  SHELLCHECK_VERSION: '0.11.0'
  YAMLLINT_VERSION: '1.35.1'
jobs:
  prereview_validation:
    if: github.event_name == 'workflow_dispatch' && inputs.prereview_pr != ''
    uses: './.github/workflows/pr-review.yml'
    permissions:
      contents: read
      pull-requests: write
      issues: read
      actions: read
    with:
      pull_request_number: '${{ inputs.prereview_pr }}'
      expected_head_sha: '${{ inputs.prereview_head }}'
  skip_check:
    name: 'Skip Duplicate Check'
    runs-on: 'ubuntu-latest'
    outputs:
      should_skip: ${{ steps.skip_check.outputs.should_skip }}
      paths_result: ${{ steps.skip_check.outputs.paths_result }}
    steps:
      - id: skip_check
        # ratchet:fkirc/skip-duplicate-actions@v5.3.2
        uses: 'fkirc/skip-duplicate-actions@b974a9395958c231af965b70070979a577efa578'
        with:
          concurrent_skipping: 'same_content'
          skip_after_successful_duplicate: 'true'
          do_not_skip: '["workflow_dispatch", "merge_group"]'
  doc_change_filter:
    name: 'Detect doc-only changes'
    runs-on: 'ubuntu-latest'
    # Every heavy job declares `needs: doc_change_filter`, so a stalled `gh api`
    # call here would block the whole tier for the 6-hour Actions default. Cap
    # it like shard_selector does; two API calls need nowhere near this.
    timeout-minutes: 5
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    env:
      GH_TOKEN: '${{ github.token }}'
    # Reads PR file metadata (issue #342); be explicit rather than relying on
    # the repo being public. Matches how shard_selector declares permissions.
    permissions:
      contents: 'read'
      pull-requests: 'read'
    outputs:
      docs_only: '${{ steps.detect.outputs.docs_only }}'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 1

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'

      - name: 'Determine documentation-only PR'
        id: 'detect'
        env:
          PR_NUMBER: >-
            ${{ github.event_name == 'pull_request' && github.event.pull_request.number || '' }}
        run: |
          set -euo pipefail
          # Non-PR events (push, merge_group, workflow_dispatch) always run full CI.
          if [[ -z "${PR_NUMBER:-}" ]]; then
            echo "docs_only=false" >>"$GITHUB_OUTPUT"
            exit 0
          fi

          # Fetch the full structured PR file list as NDJSON (one entry per line
          # across all pages, including status/previous_filename/patch so renames
          # and the .gitignore carve-out are handled) and the authoritative
          # changed_files count. `|| true` keeps an API blip from failing this
          # job: the detector script then resolves to docs_only=false (run full
          # CI) rather than skipping the six heavy jobs and wedging the PR.
          files_json="${RUNNER_TEMP}/pr-files.ndjson"
          : >"$files_json"
          gh api \
            --paginate \
            -H "Accept: application/vnd.github+json" \
            "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \
            --jq '.[]' >"$files_json" || true

          changed_files="$(gh api \
            -H "Accept: application/vnd.github+json" \
            "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
            --jq '.changed_files' || true)"

          # The classifier (scripts/docs-only-filter.ts) is a conservative
          # allowlist (issue #342): runtime .md/.txt inputs under packages/ are
          # CODE, renames require both sides to be docs, and the changed_files
          # count guards against the 3000-file API ceiling. It writes docs_only
          # to GITHUB_OUTPUT and a summary to GITHUB_STEP_SUMMARY, always
          # exiting 0 so a detector blip never wedges a PR.
          node scripts/docs-only-filter.ts \
            --files-json "$files_json" \
            --changed-files "$changed_files" \
            --output github-actions || true
  #
  # Lint: GitHub Actions
  #
  # Shard selection (issue #2709)
  #
  # A cheap Node script reads the PR's changed paths and a checked-in package
  # import graph to select only the test shards that can observe the changes.
  # Non-PR events (push, merge_group, workflow_dispatch) select all shards.
  # Unknown paths or selector failure run all six shards (fail-closed). The
  # selector is path-only (no AST scan, no install) and completes in
  # milliseconds; the import-graph drift guard
  # (scripts/check-affected-test-shards.ts) runs in the lint_javascript job.
  shard_selector:
    name: 'Select test shards'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 5
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
      pull-requests: 'read'
    outputs:
      matrix: '${{ steps.select.outputs.matrix }}'
      selected_shards: '${{ steps.select.outputs.selected_shards }}'
      has_tests: '${{ steps.select.outputs.has_tests }}'
      coverage_complete: '${{ steps.select.outputs.coverage_complete }}'
      full_run_reason: '${{ steps.select.outputs.full_run_reason }}'
      lint_targets: '${{ steps.lint_select.outputs.lint_targets }}'
      lint_full_run: '${{ steps.lint_select.outputs.lint_full_run }}'
      lint_full_run_reason: '${{ steps.lint_select.outputs.lint_full_run_reason }}'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'

      - name: 'Determine changed files'
        id: 'changed'
        env:
          GH_TOKEN: '${{ github.token }}'
          PR_NUMBER: >-
            ${{ github.event_name == 'pull_request' && github.event.pull_request.number || '' }}
        run: |
          set -euo pipefail
          # Non-PR events select all shards, so we only need the file list for
          # pull_request events. An empty file list makes the selector fail
          # closed (all shards), which is the safe default.
          files_file="${RUNNER_TEMP}/changed-files.txt"
          : >"$files_file"
          if [[ -n "${PR_NUMBER:-}" ]]; then
            gh api \
              --paginate \
              -H "Accept: application/vnd.github+json" \
              "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \
              --jq '.[].filename' >"$files_file"
          fi
          echo "count=$(wc -l <"$files_file" | tr -d ' ')" >>"$GITHUB_OUTPUT"

      - name: 'Select affected shards'
        id: 'select'
        run: |
          set -euo pipefail
          event='${{ github.event_name }}'
          files_arg=()
          if [[ "$event" == "pull_request" ]]; then
            files_arg=(--files-from "${RUNNER_TEMP}/changed-files.txt")
          fi

          # The selector writes selected_shards, matrix, has_tests,
          # coverage_complete, and full_run_reason directly to GITHUB_OUTPUT,
          # and a human-readable summary to GITHUB_STEP_SUMMARY. The matrix is
          # a JSON array of {shard, os, node-version} objects, one per
          # selected shard per OS (Linux + macOS).
          node scripts/affected-test-shards.ts \
            --event "$event" \
            "${files_arg[@]}" \
            --output github-actions

      - name: 'Select affected lint targets'
        id: 'lint_select'
        run: |
          set +e
          event='${{ github.event_name }}'
          files_arg=()
          if [[ "$event" == "pull_request" ]]; then
            files_arg=(--files-from "${RUNNER_TEMP}/changed-files.txt")
          fi
          # The lint selector reuses the same import graph as the test-shard
          # selector and writes lint_targets (JSON array of package dirs +
          # integration-tests) and lint_full_run (true when fail-closed to a
          # full root lint) directly to GITHUB_OUTPUT. The selector must NOT
          # fail this job — on crash it writes a full-run fallback so that
          # lint_javascript's step-level fail-closed logic lints the whole
          # root tree.
          node scripts/affected-lint-targets.ts \
            --event "$event" \
            "${files_arg[@]}" \
            --output github-actions
          select_rc=$?
          if [[ "$select_rc" -ne 0 ]]; then
            echo "lint_targets=[\".\"]" >> "$GITHUB_OUTPUT"
            echo "lint_full_run=true" >> "$GITHUB_OUTPUT"
            echo "lint_full_run_reason=lint selector failed (exit $select_rc)" >> "$GITHUB_OUTPUT"
            echo "::warning::affected-lint-targets failed (exit $select_rc); falling back to full lint"
          fi
  #
  lint_github_actions:
    name: 'Lint (GitHub Actions)'
    runs-on: 'ubuntu-latest'
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 1

      - name: 'Install shellcheck' # Actionlint uses shellcheck
        run: |-
          mkdir -p "${RUNNER_TEMP}/shellcheck"
          curl -sSLo "${RUNNER_TEMP}/.shellcheck.txz" "https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz"
          tar -xf "${RUNNER_TEMP}/.shellcheck.txz" -C "${RUNNER_TEMP}/shellcheck" --strip-components=1
          echo "${RUNNER_TEMP}/shellcheck" >> "${GITHUB_PATH}"

      - name: 'Install actionlint'
        run: |-
          mkdir -p "${RUNNER_TEMP}/actionlint"
          curl -sSLo "${RUNNER_TEMP}/.actionlint.tgz" "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
          tar -xzf "${RUNNER_TEMP}/.actionlint.tgz" -C "${RUNNER_TEMP}/actionlint"
          echo "${RUNNER_TEMP}/actionlint" >> "${GITHUB_PATH}"

      # For actionlint, we specifically ignore shellcheck rules that are
      # annoying or unhelpful. See the shellcheck action for a description.
      - name: 'Run actionlint'
        run: |-
          actionlint \
            -color \
            -format "{{range \$err := .}}::error file={{\$err.Filepath}},line={{\$err.Line}},col={{\$err.Column}}::{{\$err.Filepath}}@{{\$err.Line}} {{\$err.Message}}%0A\`\`\`%0A{{replace \$err.Snippet \"\\\\n\" \"%0A\"}}%0A\`\`\`\\n{{end}}" \
            -ignore 'SC2002:' \
            -ignore 'SC2016:info' \
            -ignore 'SC2129:' \
            -ignore 'label ".+" is unknown'

      - name: 'Run ratchet'
        uses: 'sethvargo/ratchet@9ca118155b0f79464185703a50da367e111107cd' # ratchet:sethvargo/ratchet@v0.12.0
        with:
          files: |-
            .github/workflows/*.yml
            .github/actions/**/*.yml

  #
  # Lint: Javascript
  #
  # S6 (#2243): installs dependencies with `bun install`. The root postinstall
  # script (scripts/postinstall.cjs) replaces Bun's hoisted static workspace
  # copies with symlinks to the real workspace dirs, so esbuild/tsserver
  # resolve workspace `dist/` correctly (see dev-docs/bun.md). Lint/typecheck/
  # format/build run under Node via `npm run …` (the workspace-fanout scripts
  # `npm run typecheck --workspaces` / `npm run test --workspaces` recurse under
  # `bun run`, so execution stays on npm; only the install moved to Bun.
  lint_javascript:
    name: 'Lint (Javascript)'
    runs-on: 'ubuntu-latest'
    needs:
      - 'skip_check'
      - 'shard_selector'
    # Fail closed: run this required lint job even when shard_selector fails or
    # is skipped, so the step-level fail-closed logic (full lint on non-success)
    # is reachable. Without `!cancelled()`, GitHub Actions skips dependent jobs
    # before evaluating `if` when a needed job fails, which would silently skip
    # lint and allow un-linted code to merge.
    if: ${{ !cancelled() && needs.skip_check.outputs.should_skip != 'true' }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'

      # S6 (#2243): Bun is the package manager for this job. Node remains
      # required because the lint/typecheck/format/build scripts execute under
      # it. Several npm scripts invoked below (check:lockfile,
      # lint:eslint-guard, build, bundle) are backed by bun scripts/*.ts and
      # require the Bun runtime to be on PATH.
      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Cache Bun dependencies'
        uses: 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' # ratchet:actions/cache@v6
        with:
          path: |
            ~/.bun/install/cache
          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}

      - name: 'Run lockfile check'
        run: |-
          npm run check:lockfile

      - name: 'Install dependencies'
        # `bun install` drives dependency resolution; the root postinstall
        # (scripts/postinstall.cjs) then replaces Bun's static workspace copies
        # with symlinks so esbuild/tsserver resolve workspace `dist/` (see
        # dev-docs/bun.md). Bun re-normalizes `bun.lock` on every install
        # (dev-docs/bun.md), so restore the committed lockfile or the
        # formatter's `git diff --exit-code` below would flag the re-write.
        # Likewise, the vscode-ide-companion `prepare` script regenerates
        # NOTICES.txt from live npm metadata, so restore the committed copy.
        run: |-
          bun install
          git checkout -- bun.lock
          git checkout -- packages/vscode-ide-companion/NOTICES.txt

      - name: 'Run formatter check'
        run: |-
          npm run format
          # Check for changes, excluding project-plans directory
          git diff --exit-code -- . ':!project-plans/'

      - name: 'Run ESLint policy guard'
        env:
          ESLINT_GUARD_BASE: >-
            ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha
              || github.event_name == 'merge_group' && github.event.merge_group.base_sha
              || github.event_name == 'push' && github.event.before
              || 'origin/main' }}
          ESLINT_GUARD_HEAD: ${{ github.sha }}
        run: |-
          npm run lint:eslint-guard

      - name: 'Run CLI import-boundary guard'
        run: |-
          npm run lint:cli-boundary
          npm run lint:a2a-boundary

      - name: 'Run Gemini containment guard'
        run: |-
          npm run lint:gemini-containment

      - name: 'Run runtime-dependency declaration guard (#3305)'
        # Fails if any published workspace package imports, at runtime, a
        # package it does not declare in dependencies/peerDependencies/
        # optionalDependencies. A devDependencies-only declaration is a
        # failure: that section is never installed for a consumer, which is
        # how the published mcp tarball shipped unable to resolve core.
        run: |-
          npm run lint:runtime-deps

      - name: 'Run legacy-global-path guard (#2606)'
        run: |-
          npm run lint:legacy-paths

      - name: 'Run no-vitest guard (#2970)'
        run: |-
          npm run lint:no-vitest

      - name: 'Check for new JS files (#2745)'
        run: |-
          npm run lint:no-new-js

      - name: 'Run CLI test-discovery guard (#2923)'
        run: |-
          npm run lint:cli-test-discovery

      - name: 'Run copyright-year guard (#2820)'
        env:
          COPYRIGHT_GUARD_BASE: >-
            ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha
              || github.event_name == 'merge_group' && github.event.merge_group.base_sha
              || github.event_name == 'push' && github.event.before
              || 'origin/main' }}
          COPYRIGHT_GUARD_HEAD: ${{ github.sha }}
        run: |-
          npm run lint:copyright-year

      - name: 'Run doc-links guard (#2654)'
        run: |-
          npm run lint:doc-links

      - name: 'Run doc-placement guard (#2654)'
        run: |-
          npm run lint:doc-placement

      - name: 'Run affected-test-shards graph drift guard (#2709)'
        # Verifies the checked-in import graph matches the real AST-derived
        # edges. Runs here (after build) because it needs the TypeScript
        # compiler API available.
        run: |-
          npm run lint:affected-shards

      - name: 'Run E2E real-model budget guard (#2278)'
        # Validates integration-tests/real-model-budget.ts: no duplicate or
        # malformed entries, a ceiling that is at least a 50% cut from the
        # measured baseline, and no entry naming a rig.setup() call that no
        # longer exists. The per-leg ledger check runs in e2e.yml.
        run: |-
          npm run lint:e2e-model-budget

      # Runs independently of test shard selection. Path observers only reduce
      # test work; this guard provides the settings synchronization guarantee.
      # It must run before build:types, whose declaration-only output cannot be
      # executed when the schema follows runtime imports across workspaces.
      - name: 'Run settings docs/schema sync guard (#3212)'
        run: |-
          npm run lint:settings-sync

      # Build must run BEFORE the type-aware lint: three workspace tsconfigs
      # map cross-workspace imports to `dist/*.d.ts` — cli -> tools, core -> mcp,
      # and a2a-server -> settings/storage/tools — so tsserver (projectService)
      # needs the compiled declarations on disk to resolve types. Under npm
      # `npm ci`'s postinstall builds implicitly; under `bun install` (whose
      # postinstall only symlinks, see scripts/postinstall.cjs) it does not, so
      # the build is explicit here.
      #
      # `build:types` emits declarations only (issue #2983). Every later step in
      # this job reads types and none executes application code, so the
      # transpiled `.js` was pure cost here. Do not reuse `build:types` in a job
      # that runs the CLI or a Bun test suite: Bun honors tsconfig `paths`, so a
      # declaration-only `dist` makes cross-package imports resolve to a `.d.ts`
      # with no JavaScript behind it. The release path (release.yml -> `npm run
      # build:packages`) still does a full emit, because every published library
      # workspace declares `main: dist/index.js` and ships `dist`, so npm
      # consumers resolving without the `bun` export condition load that
      # JavaScript.
      - name: 'Build declarations for type-aware lint'
        run: |-
          npm run build:types

      - name: 'Run agents API-surface guard'
        run: |-
          npm run lint:agents-api-surface

      # The audit type-checks the non-workspace runtime plugins (see
      # productionPlugins in scripts/runtime-entry-manifest.ts). The
      # google-gemini plugin imports @ai-sdk/google from its own
      # node_modules, which the root `bun install` does not populate, so the
      # compiler reports TS2307/TS7006 and blocks the service-shape scanner.
      # Plugin installs need bun >= 1.4.2 for the same reason as the
      # runtime_plugins job (the repo pin re-resolves the plugin lockfile and
      # stalls on hosted runners).
      - name: 'Install runtime plugin dependencies for the audit'
        run: |-
          curl -fsSL https://bun.sh/install | BUN_INSTALL="$RUNNER_TEMP/bun-plugin" bash -s "bun-v1.4.2"
          for plugin in plugins/*/; do
            if [ -f "${plugin}package.json" ]; then
              (cd "$plugin" && "$RUNNER_TEMP/bun-plugin/bin/bun" install --omit=peer)
            fi
          done
          git checkout -- bun.lock

      - name: 'Run runtime-boundary production audit (#2616)'
        # TypeScript-aware audit of production sources: fails on any
        # mutable-state, ALS, ambient-delegation, Config-locator or compiler
        # finding. runtime-service-bundle and runtime-service-bag-parameter
        # are a tracked residual held by the committed ratchet baseline
        # (scripts/runtime-service-shape-baseline.json): per-owner counts may
        # fall but never rise. Needs the declarations from build:types above.
        run: |-
          npm run check:runtime-boundary

      # ESLint cache is CI opt-in only (issue #2710). The exact key hashes
      # every linted source/config/type input so a changed cross-file type
      # producer invalidates the cache of its consumers. There are no
      # restore-keys: a partial match across a stale type input would be
      # unsound.
      - name: 'Restore ESLint cache'
        id: 'eslint_cache'
        if: ${{ needs.shard_selector.result == 'success' }}
        uses: 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' # ratchet:actions/cache@v6
        with:
          path: 'node_modules/.cache/eslint'
          key: ${{ runner.os }}-eslint-${{ hashFiles('packages/*/src/**', 'packages/*/package.json', 'packages/*/tsconfig.json', 'scripts/**', 'evals/**', 'integration-tests/**', 'eslint.config.js', 'eslint-rules/**', 'package.json', 'package-lock.json', 'bun.lock', 'tsconfig.json', 'tsconfig.scripts.json', '*.js', 'test-setup/**', '.github/workflows/**', '.github/scripts/**') }}

      - name: 'Run linter'
        run: |
          set -euo pipefail
          # Fail closed: if the selector did not succeed, or reported a full
          # run, lint the whole root tree. Otherwise lint only the selected
          # package targets (the runner always includes integration-tests).
          selector_result='${{ needs.shard_selector.result }}'
          lint_full_run='${{ needs.shard_selector.outputs.lint_full_run }}'
          lint_targets='${{ needs.shard_selector.outputs.lint_targets }}'
          lint_full_run_reason='${{ needs.shard_selector.outputs.lint_full_run_reason }}'
          if [[ -n "$lint_full_run_reason" ]]; then
            echo "::notice::Lint running full: $lint_full_run_reason"
          fi
          if [[ "$selector_result" == "success" && "$lint_full_run" != "true" && -n "$lint_targets" && "$lint_targets" != "null" ]]; then
            # Scoped run: the runner derives --cache args centrally from the
            # LLXPRT_LINT_CACHE env (it also reads the target list from env),
            # so no cache flags are passed on the CLI.
            LLXPRT_LINT_CACHE=true LLXPRT_LINT_TARGETS="$lint_targets" \
              npm run lint:runner
          else
            # Full run: the partitioned runner covers the whole tree,
            # integration-tests included, one ESLint process per package
            # plus a root slice (#3387). Both branches rely on the runner's
            # own per-child heap, so no NODE_OPTIONS is set here.
            npm run lint:ci
          fi

      - name: 'Run LSP package linter'
        run: |-
          cd packages/lsp && npx eslint .

      - name: 'Run formatter on integration tests'
        run: |-
          npx prettier --check integration-tests
          git diff --exit-code

      - name: 'Run type check'
        run: |-
          npm run typecheck

      - name: 'Run sensitive keyword linter'
        run: 'bun scripts/lint.ts --sensitive-keywords'

  #
  # Lint: Shell
  #
  lint_shell:
    name: 'Lint (Shell)'
    runs-on: 'ubuntu-latest'
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 1

      - name: 'Install shellcheck'
        run: |-
          mkdir -p "${RUNNER_TEMP}/shellcheck"
          curl -sSLo "${RUNNER_TEMP}/.shellcheck.txz" "https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz"
          tar -xf "${RUNNER_TEMP}/.shellcheck.txz" -C "${RUNNER_TEMP}/shellcheck" --strip-components=1
          echo "${RUNNER_TEMP}/shellcheck" >> "${GITHUB_PATH}"

      - name: 'Install shellcheck problem matcher'
        run: |-
          cat > "${RUNNER_TEMP}/shellcheck/problem-matcher-lint-shell.json" <<"EOF"
          {
            "problemMatcher": [
              {
                "owner": "lint_shell",
                "pattern": [
                  {
                    "regexp": "^(.*):(\\\\d+):(\\\\d+):\\\\s+(?:fatal\\\\s+)?(warning|error):\\\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                  }
                ]
              }
            ]
          }
          EOF
          echo "::add-matcher::${RUNNER_TEMP}/shellcheck/problem-matcher-lint-shell.json"

      # Note that only warning and error severity show up in the github files
      # page. So we replace 'style' and 'note' with 'warning' to make it show
      # up.
      #
      # We also try and find all bash scripts even if they don't have an
      # explicit extension.
      #
      # We explicitly ignore the following rules:
      #
      # - SC2002: This rule suggests using "cmd < file" instead of "cat | cmd".
      #   While < is more efficient, pipes are much more readable and expected.
      #
      # - SC2129: This rule suggests grouping multiple writes to a file in
      #   braces like "{ cmd1; cmd2; } >> file". This is unexpected and less
      #   readable.
      #
      # - SC2310: This is an optional warning that only appears with "set -e"
      #   and when a command is used as a conditional.
      - name: 'Run shellcheck'
        run: |-
          git ls-files | grep -E '^([^.]+|.*\.(sh|zsh|bash))$' | xargs file --mime-type \
            | grep "text/x-shellscript" | awk '{ print substr($1, 1, length($1)-1) }' \
            | xargs shellcheck \
              --check-sourced \
              --enable=all \
              --exclude=SC2002,SC2129,SC2310,SC2311,SC2312 \
              --severity=style \
              --format=gcc \
              --color=never | sed -e 's/note:/warning:/g' -e 's/style:/warning:/g'

  #
  # Lint: YAML
  #
  lint_yaml:
    name: 'Lint (YAML)'
    runs-on: 'ubuntu-latest'
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 1

      - name: 'Setup Python'
        uses: 'actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97' # ratchet:actions/setup-python@v7
        with:
          python-version: '3'

      - name: 'Install yamllint'
        run: |-
          pip install --user "yamllint==${YAMLLINT_VERSION}"

      - name: 'Run yamllint'
        run: |-
          git ls-files | grep -E '\.(yaml|yml)' | xargs yamllint --format github

  #
  # Lint: All
  #
  # This is a virtual job that other jobs depend on to wait for all linters to
  # finish. It's also used to ensure linting happens on CI via required
  # workflows.
  lint:
    name: 'Lint'
    needs:
      - 'lint_github_actions'
      - 'lint_javascript'
      - 'lint_shell'
      - 'lint_yaml'
      # node_consumer_smoke provides a cheap package install/invocation gate.
      # test_shard depends directly on it (issue #2877); lint retains the
      # dependency here to preserve smoke coverage when the matrix is skipped.
      - 'node_consumer_smoke'
      # doc_change_filter (issue #342) makes node_consumer_smoke skippable on
      # docs-only PRs. skip_check makes every job skippable on duplicate runs.
      # Both are read below so this required aggregator stays honest instead of
      # being skipped by GitHub when a needed job is skipped.
      - 'doc_change_filter'
      - 'skip_check'
    if: ${{ always() }}
    runs-on: 'ubuntu-latest'
    steps:
      - name: 'Check lint results'
        run: |-
          should_skip='${{ needs.skip_check.outputs.should_skip }}'
          docs_only='${{ needs.doc_change_filter.outputs.docs_only }}'
          lint_github_actions_result='${{ needs.lint_github_actions.result }}'
          lint_javascript_result='${{ needs.lint_javascript.result }}'
          lint_shell_result='${{ needs.lint_shell.result }}'
          lint_yaml_result='${{ needs.lint_yaml.result }}'
          node_consumer_smoke_result='${{ needs.node_consumer_smoke.result }}'

          # Explicit duplicate-skip: skip_check said this run duplicates a
          # passing one, so every downstream job was intentionally skipped.
          # The required Lint check is green by design.
          if [ "$should_skip" == "true" ]; then
            echo "skip_check reported a duplicate passing run (should_skip=true). Lint check is green by design."
            exit 0
          fi

          # Every linter must succeed regardless of PR type.
          if [ "$lint_github_actions_result" != "success" ]; then
            echo "::error::GitHub Actions lint did not succeed (result: $lint_github_actions_result)"
            exit 1
          fi
          if [ "$lint_javascript_result" != "success" ]; then
            echo "::error::JavaScript lint did not succeed (result: $lint_javascript_result)"
            exit 1
          fi
          if [ "$lint_shell_result" != "success" ]; then
            echo "::error::Shell lint did not succeed (result: $lint_shell_result)"
            exit 1
          fi
          if [ "$lint_yaml_result" != "success" ]; then
            echo "::error::YAML lint did not succeed (result: $lint_yaml_result)"
            exit 1
          fi

          # node_consumer_smoke must succeed on code PRs. On docs-only PRs
          # (issue #342) it is intentionally skipped, which is accepted here.
          if [ "$node_consumer_smoke_result" != "success" ]; then
            if [ "$docs_only" == "true" ] && [ "$node_consumer_smoke_result" == "skipped" ]; then
              echo "docs-only PR: node_consumer_smoke intentionally skipped (issue #342)."
            else
              echo "::error::Node Consumer Smoke did not succeed (result: $node_consumer_smoke_result)"
              exit 1
            fi
          fi

          echo 'All linters finished!'

  #
  # Bun: Workspace install smoke
  #
  # Verifies the S1 acceptance criterion that `bun install` succeeds from a
  # clean checkout and wires up every workspace package. Uses a plain
  # `bun install` rather than `--frozen-lockfile`: Bun re-normalizes this
  # monorepo's lockfile on every pass (see dev-docs/bun.md), so a frozen check
  # would be perpetually red despite a valid, deterministically generated
  # lockfile. Pinning via .bun-version keeps the toolchain reproducible.
  bun_install_smoke:
    name: 'Bun Install Smoke'
    runs-on: 'ubuntu-latest'
    # A monorepo smoke install completes in well under a minute; cap the job so a
    # hung `bun install` (registry stall or workspace-resolution deadlock) fails
    # fast instead of occupying a runner up to the 6-hour GitHub Actions default.
    timeout-minutes: 15
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    # Skip on docs-only PRs (issue #342): a doc edit cannot change whether
    # `bun install` resolves and links the workspaces.
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          # This job runs `bun install`, which executes the lifecycle scripts of
          # trusted native dependencies. It performs no authenticated git
          # operation after checkout, so the default credential persistence only
          # widens the token's exposure to those install-time scripts. Drop it.
          persist-credentials: false

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Install workspaces with Bun'
        run: |-
          bun install

      - name: 'Verify Bun linked every declared local workspace package'
        # Runs the committed verifier (also runnable locally via
        # `bun install && bun scripts/verify-bun-workspace-links.ts`) so the
        # link-check logic lives in one tested place instead of an inline
        # heredoc. Executed with `bun` — already set up for this job — to avoid
        # relying on an implicitly-provided Node on the runner.
        run: |-
          bun scripts/verify-bun-workspace-links.ts

  #
  # Bun: Native-module smoke (issue 2239, S2)
  #
  # Verifies that the native modules the CLI depends on load and operate under
  # the Bun runtime on POSIX: @ast-grep/napi, @napi-rs/keyring (construct-only),
  # web-tree-sitter + tree-sitter-bash WASM, and the Bun.Terminal PTY adapter
  # (the bun-pty seam). Does NOT weaken existing checks — it is an additive job.
  bun_native_modules_smoke:
    name: 'Bun Native Modules Smoke'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 15
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    # Skip on docs-only PRs (issue #342): a doc edit cannot change native
    # module load/operate behaviour under the Bun runtime.
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      # `npm install`, not `npm ci`: packages/cli declares the os-gated launcher
      # packages (issue #2978) as optionalDependencies. They cannot be root
      # workspaces -- npm enforces a workspace's `os` field and fails
      # EBADPLATFORM on every platform -- so before their first publish they are
      # unresolvable and absent from the lockfile. `npm ci` rejects that as a
      # manifest/lock desync; `npm install` correctly omits an unresolvable
      # OPTIONAL dependency, exits 0, and leaves the lockfile untouched. This
      # job only needs node_modules for the harness below, so it does not
      # depend on `npm ci`'s stricter guarantees.
      - name: 'Install dependencies'
        run: |-
          npm install --no-audit --no-fund

      - name: 'Run Bun native-module smoke harness'
        run: |-
          bun scripts/bun-native-modules-smoke.ts

  #
  # Node consumer smoke (issue 2243, S6 / issue 2603)
  #
  # Guards npm install/invocation compatibility: install with npm, then run the
  # installed bin directly. The bin is a POSIX sh launcher (issue #2603) that
  # execs the package-local Bun against packages/cli/index.ts — no Node process
  # is started on the installed command path. A direct dependency of test_shard
  # (issue #2877) and of the lint aggregator, so broken package installs or CLI
  # invocation fail before matrix fanout.
  node_consumer_smoke:
    name: 'Node Consumer Smoke'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 15
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    # Skip on docs-only PRs (issue #342): a doc edit cannot change npm
    # package install/invocation compatibility.
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    # This job installs the packed package with npm (executing third-party
    # install scripts) and only needs to read the repo, so scope permissions to
    # contents:read and drop credential persistence. It validates the published
    # npm entry path by running the installed launcher directly after install;
    # the launcher execs Bun on TypeScript source.
    permissions:
      contents: 'read'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          fetch-depth: 1
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'

      - name: 'Setup Bun'
        # The installed launcher executes Bun against the package's TypeScript
        # sources even though the package itself is installed with npm.
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Pack source-runtime package'
        run: |-
          mkdir -p "$RUNNER_TEMP/llxprt-pack"
          npm pack --pack-destination "$RUNNER_TEMP/llxprt-pack"

      - name: 'Install packed package with npm'
        run: |-
          mkdir -p "$RUNNER_TEMP/llxprt-consumer"
          cd "$RUNNER_TEMP/llxprt-consumer"
          npm init -y
          npm install "$RUNNER_TEMP/llxprt-pack"/*.tgz

      - name: 'Smoke test installed CLI entry (launcher -> Bun, no Node in chain)'
        run: '"$RUNNER_TEMP/llxprt-consumer/node_modules/.bin/llxprt" --version'

  #
  # Bun-backed test orchestration smoke (issue #2463)
  #
  # Verifies that `bun scripts/test.ts` (the `test:bun` entry point) can
  # discover all workspaces, parse their test/pretest scripts, and produce
  # a summary — using a dry-run mode that does not actually execute the
  # workspace test suites. This catches regressions in the orchestrator itself
  # without the cost of a full test matrix. The actual workspace tests still
  # run under Bun's native runner via the existing `test` job; this job only
  # validates the Bun-backed orchestration script.
  bun_test_orchestrator_smoke:
    name: 'Bun Test Orchestrator Smoke'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 10
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    # Skip on docs-only PRs (issue #342): a doc edit cannot change test
    # orchestrator discovery/parsing/routing behaviour.
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Install dependencies'
        run: |-
          bun install
          git checkout -- bun.lock

      - name: 'Run test orchestrator on a single workspace'
        # Runs the orchestrator against one workspace. --skip-pretest skips
        # pretest hooks (like the agents API-surface guard) to keep the smoke
        # fast. The workspace's test phase still runs, but test-utils has a
        # tiny test suite. --skip-scripts skips the root script harness tests.
        # The only failure modes that matter here are bugs in the orchestrator
        # itself (discovery, parsing, routing).
        run: |-
          bun scripts/test.ts --workspace test-utils --skip-scripts

      - name: 'Run script harness tests for the orchestrator'
        run: |-
          bun test --preload ./scripts/tests/test-setup.ts scripts/tests/test-orchestrator.test.ts

      - name: 'Verify every test file is covered by some executor'
        # Fails when a test file exists on disk that no executor runs (uncovered)
        # or when two executors both run the same file (doubly-executed). This
        # runs on every non-docs-only PR regardless of which shard it touches,
        # so a package-only change cannot introduce an uncovered file.
        run: |-
          bun scripts/check-test-file-coverage.ts

  #
  # Windows test-infra gate (issue #3439)
  #
  # The full Windows matrix lives in the nightly (issue #3153), which meant
  # Windows-incompatible test code merged green and was first exercised by
  # the next day's nightly — the recurring "Nightly workflow failed" issues.
  # This gate runs the Windows-sensitive test infrastructure (the per-package
  # bun test runners, the CLI launcher shims, and the test orchestrator) on
  # windows-latest for every push to main, and for PRs that touch that
  # surface, so the same class of failure is caught within minutes of the
  # offending change instead of the next night. It deliberately does NOT run
  # the six-shard corpus (issue #3249 keeps Windows runner cost bounded);
  # only the suites whose subjects are process launching and path handling,
  # which is exactly the Windows-divergent surface.
  windows_test_infra:
    name: 'Windows Test-Infra Gate'
    runs-on: 'windows-latest'
    timeout-minutes: 20
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
      pull-requests: 'read'
    outputs:
      affected: '${{ steps.filter.outputs.affected }}'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Detect Windows-sensitive changes'
        id: 'filter'
        env:
          GH_TOKEN: '${{ github.token }}'
          PR_NUMBER: >-
            ${{ github.event_name == 'pull_request' && github.event.pull_request.number || '' }}
        run: |
          set -euo pipefail
          # Non-PR events (push to main, merge_group, workflow_dispatch)
          # always run the gate: the post-merge signal is the other half of
          # the fix — a slip past the path filter still fails within minutes.
          if [[ -z "${PR_NUMBER:-}" ]]; then
            echo "affected=true" >>"${GITHUB_OUTPUT}"
            exit 0
          fi

          # Path allowlist for the Windows-sensitive surface. Anything else
          # (package internals, docs) cannot change Windows behavior of the
          # suites this gate runs.
          files_json="${RUNNER_TEMP}/pr-files.ndjson"
          : >"${files_json}"
          gh api --paginate -H 'Accept: application/vnd.github+json' \
            "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \
            --jq '.[].filename' >"${files_json}" || true
          # An empty list means the API call failed, not that the PR changed
          # nothing: fail open and run the gate (mirrors doc_change_filter).
          if [[ ! -s "${files_json}" ]] || grep -Eq \
            '^(scripts/|packages/[^/]+/run-bun-tests\.ts$|packages/[^/]+/bun-preload\.ts$|packages/auth/src/__tests__/|packages/cli/bin/|packages/(cli|core)/test/.*run-bun-tests|packages/agents/test-bun/|\.github/workflows/(ci|nightly)\.yml$|bun\.lock$|package(-lock)?\.json$|tsconfig[^/]*)' \
            "${files_json}"; then
            echo "affected=true" >>"${GITHUB_OUTPUT}"
          else
            echo "affected=false" >>"${GITHUB_OUTPUT}"
          fi

      - name: 'Configure Windows Defender exclusions'
        if: steps.filter.outputs.affected == 'true'
        run: |
          Add-MpPreference -ExclusionPath $env:GITHUB_WORKSPACE -Force
          Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE\node_modules" -Force
          Add-MpPreference -ExclusionPath $env:TEMP -Force
        shell: 'pwsh'

      - name: 'Configure npm for Windows performance'
        if: steps.filter.outputs.affected == 'true'
        run: |
          npm config set progress false
          npm config set audit false
          npm config set fund false
          npm config set loglevel error
          npm config set maxsockets 32
          npm config set registry https://registry.npmjs.org/
        shell: 'pwsh'

      - name: 'Install dependencies for testing'
        if: steps.filter.outputs.affected == 'true'
        run: |-
          npm ci

      - name: 'Fix rollup platform dependency'
        if: steps.filter.outputs.affected == 'true'
        run: |-
          npm install @rollup/rollup-win32-x64-msvc --no-save || true
        shell: 'bash'

      - name: 'Run launcher shim and output-generator tests'
        if: steps.filter.outputs.affected == 'true'
        run: |-
          bun test --preload ./scripts/tests/test-setup.ts scripts/tests/issue-2978-node-shim.bun.test.ts scripts/tests/issue-2978-oven-fallback.bun.test.ts scripts/tests/memory/output-generator.test.ts

      - name: 'Run test-runner and orchestrator meta-tests'
        if: steps.filter.outputs.affected == 'true'
        run: |-
          bun test --preload ./scripts/tests/test-setup.ts scripts/tests/run_bun_tests.test.ts scripts/tests/bun-test-reaper.bun.test.ts scripts/tests/test-orchestrator.test.ts scripts/tests/test-shard-orchestrator.test.ts
          cd packages/cli && bun test test/run-bun-tests.test.ts
          cd ../core && bun test test/run-bun-tests.test.ts
          cd ../agents && bun test ./test-bun/run-bun-tests.issue3253.bun.ts
          cd ../auth && bun test src/__tests__/run-bun-tests.behavior.test.ts

      - name: 'Smoke test CLI entry (launcher -> Bun, no Node in chain)'
        if: steps.filter.outputs.affected == 'true'
        run: './packages/cli/bin/llxprt --version'

  #
  # Test: Node (Linux only — issue #2876)
  #
  # Stays on npm (not Bun) for S6 (#2243): Bun's hoisted linker non-
  # deterministically materializes incomplete copies of third-party packages
  # (e.g. uuid, yargs, ajv) whose package.json entry points at files that the
  # copy is missing, breaking the test runner's import resolution. Revisit once Bun's
  # hoisted linker materializes complete packages.
  #
  # setup-bun is still installed here (pinned via .bun-version) because the LSP
  # service client resolves `bun` through `which` and disables the LSP/MCP
  # service when bun is absent from PATH. Pinning to .bun-version reconciles
  # the CI toolchain with dev-docs/bun.md and avoids a floating Bun version.
  #
  # Issue #2707: the workspace test suite is sharded into parallel jobs so the
  # critical path is max(shard) rather than sum(all workspaces). The shard map
  # lives in scripts/test-shards.ts and is enforced by
  # scripts/check-test-shards.ts (run below and via `lint:test-shards`). Each
  # logical shard expands into one or more physical matrix rows (issue #3185:
  # cli splits into 1of3/2of3/3of3; other shards carry 1of1); the `scripts`
  # shard runs the root script harness instead of workspace tests. All physical
  # rows are ubuntu-only (issue #2876); macOS coverage moved to the nightly
  # workflow.
  #
  # Issue #2709: the matrix is now dynamic — shard_selector outputs a JSON
  # matrix of physical partition rows expanded from only the logical shards
  # that can observe the PR's changed files (issue #3185 expands cli into
  # 1of3/2of3/3of3). When shard_selector fails or is skipped, the `if`
  # condition prevents test_shard from running entirely, and the `test`
  # aggregator converts that into a failure (see test job). When the selector
  # succeeds but selects zero shards (has_tests=false), the matrix is empty
  # and no legs run; the `test` aggregator treats that as success (the
  # selector explicitly said there are no tests to run).
  test_shard:
    name: 'Test (${{ matrix.os }}) [${{ matrix.shard }} ${{ matrix.partition }}]'
    runs-on: '${{ matrix.os }}'
    # The cli shard is the longest (~12 min pre-cost-reduction); cap so a
    # hung shard fails instead of occupying a runner for the 6h default.
    timeout-minutes: 45
    needs:
      - 'node_consumer_smoke'
      - 'doc_change_filter'
      - 'shard_selector'
      - 'skip_check'
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' && needs.shard_selector.result == 'success' && needs.shard_selector.outputs.has_tests == 'true' }}
    permissions:
      contents: 'read'
      checks: 'write'
      pull-requests: 'write'
    strategy:
      fail-fast: false # So we can see all test failures
      # Dynamic matrix from shard_selector (issue #2709): only shards that can
      # observe the changed files. The selector emits ubuntu-only rows (issue
      # #2876); macOS test coverage moved to the nightly workflow. An empty
      # matrix (no tests selected) combined with the has_tests gate above
      # skips all legs without making the required `Test` check red.
      matrix:
        include: ${{ fromJSON(needs.shard_selector.outputs.matrix) }}
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js ${{ matrix.node-version }}'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version: '${{ matrix.node-version }}'

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Cache Bun dependencies'
        uses: 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' # ratchet:actions/cache@v6
        with:
          path: |
            ~/.bun/install/cache
          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}

      # S6 (#2243): `bun install` resolves dependencies; the root postinstall
      # (scripts/postinstall.cjs) then symlinks Bun's static workspace copies to
      # the real workspace dirs so build/test resolve workspace `dist/` (see
      # dev-docs/bun.md). Per-shard tests run via `bun scripts/test.ts --shard`
      # which invokes each workspace's `test` script. The tools, mcp, and storage
      # workspaces use native Bun; all other packages use their configured runner.
      - name: 'Install dependencies for testing'
        # Bun re-normalizes `bun.lock` on every install (dev-docs/bun.md);
        # restore the committed lockfile so no downstream step sees a dirty one.
        # The plugin installs give the gemini integration suites their
        # runtime-plugin dependency: the CLI discovers the checkout's
        # plugins/ directory (#2759), and the google-gemini plugin imports
        # @ai-sdk/google from its own node_modules at load time. Plugin
        # installs need bun >= 1.4.2 for the same reason as the
        # runtime_plugins job: the repo pin rejects the plugin lockfile's
        # unresolved root peers, discards the lock, and re-resolves, which
        # stalls indefinitely on hosted runners.
        run: |-
          bun install
          git checkout -- bun.lock
          curl -fsSL https://bun.sh/install | BUN_INSTALL="$RUNNER_TEMP/bun-plugin" bash -s "bun-v1.4.2"
          for plugin in plugins/*/; do
            if [ -f "${plugin}package.json" ]; then
              (cd "$plugin" && "$RUNNER_TEMP/bun-plugin/bin/bun" install --omit=peer)
            fi
          done
          git checkout -- bun.lock
      # Issue #2983: tests never read compiled output. Every workspace declares
      # a `bun` export condition resolving to TypeScript source, and Bun's
      # native test runner resolves cross-workspace imports straight
      # at source, so a full build here produced JavaScript nothing loaded.
      #
      # Two shards are the exception. Both run the agents API-surface guard
      # (`scripts/check-agents-api-surface.ts`) — the `agents` shard through its
      # package `pretest` hook, the `scripts` shard through
      # scripts/tests/check-agents-api-surface.test.ts. That guard's temp
      # tsconfig resolves `@vybestack/llxprt-code-{telemetry,mcp}` and several
      # `storage/*` subpaths through node_modules to `dist/*.d.ts`, because
      # packages/agents/tsconfig.json has no source mapping for them. Issue
      # #2618 (tsconfig bypasses) owns repointing those mappings at source;
      # until it lands, these two legs need a built workspace.
      #
      # These legs must run the FULL build, not `build:types`. Bun applies
      # tsconfig `paths` at runtime, so `packages/core/tsconfig.json`'s
      # `@vybestack/llxprt-code-mcp -> ../mcp/dist/mcp/index.d.ts` mapping wins
      # over the package's `bun` export condition whenever that file exists. A
      # declaration-only `dist` therefore resolves to a `.d.ts` whose relative
      # re-export has no emitted JavaScript behind it, and every test importing
      # core through mcp dies at import time. Either a complete `dist` or no
      # `dist` at all works; a partial one does not. `build:types` is confined
      # to `lint_javascript`, which runs no application code.
      #
      # The standalone `Run agents API-surface guard` step is gone: the
      # `lint_javascript` job already runs it after its own declaration build,
      # and the `agents` shard runs it through the agents package `pretest`
      # hook.
      - name: 'Build project (agents API-surface guard prerequisite)'
        if: matrix.shard == 'agents' || matrix.shard == 'scripts'
        run: |-
          npm run build

      - name: 'Verify test shard completeness (issue #2707)'
        # Fails if any workspace declared in package.json is missing from the
        # shard map, so adding a package can never silently go untested.
        run: |-
          npm run lint:test-shards

      - name: 'Run shard tests (issue #2707)'
        env:
          # Provider configuration from repository secrets/variables
          OPENAI_API_KEY: ${{ secrets[vars.KEY_VAR_NAME] }}
          OPENAI_API_KEY_2: ${{ secrets[vars.KEY_VAR_NAME_2] }}
          KEY_VAR_NAME: ${{ vars.KEY_VAR_NAME }}
          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
          LLXPRT_DEFAULT_MODEL: ${{ vars.LLXPRT_DEFAULT_MODEL }}
          LLXPRT_DEFAULT_PROVIDER: ${{ vars.LLXPRT_DEFAULT_PROVIDER }}
          # Set auth type to provider for API key authentication
          LLXPRT_AUTH_TYPE: provider
          NO_COLOR: true
          # Ensure OAuth tests are skipped in CI (they require browser interaction)
          CI: true
          # Issue #3185: partition identity consumed by the CLI runner
          # (packages/cli/run-bun-tests.ts). The selector expands cli into
          # 1of3/2of3/3of3; other shards carry 1of1 and are unaffected.
          LLXPRT_CLI_TEST_PARTITION: ${{ matrix.partition }}
        # The orchestrator expands --shard to the shard's workspaces (or runs
        # npm run test:scripts for the scripts shard). Each workspace's tests
        # run under whichever runner its own `test` script selects — Bun-native
        # for all workspaces (issue #2578, #2970).
        run: 'bun scripts/test.ts --shard "${{ matrix.shard }}"'

      - name: 'Report harness toolchain versions'
        # The assign harness shells out to jq, python3 and bash. Those differ
        # between runner images, which is exactly the class of difference that
        # made the nightly ubuntu-22.04 failure hard to attribute (#2688).
        # Record them so a platform-specific failure can be diagnosed from the
        # log alone. Only needed on the scripts shard (the harness leg).
        if: matrix.shard == 'scripts'
        run: |-
          echo "bash:    $(bash --version | head -1)"
          echo "jq:      $(jq --version)"
          echo "python3: $(python3 --version)"

      - name: 'Run shell-script behavioral tests (#2606)'
        # Shell-script tests are not workspace-scoped; run them once on the
        # scripts shard to avoid duplicating across every leg.
        if: matrix.shard == 'scripts'
        env:
          CI: true
        run: npm run test:shell

      - name: 'Smoke test CLI entry (launcher -> Bun -> TypeScript, no Node)'
        # The CLI entry is exercised by the cli shard's tests. This step
        # retains the logical-shard condition (matrix.shard == 'cli'), so it
        # runs once in each CLI partition leg (1of3, 2of3, 3of3).
        if: matrix.shard == 'cli'
        run: './packages/cli/bin/llxprt --version'

      - name: 'Wait for file system sync'
        run: 'sleep 2'

      - name: 'Publish Test Report (for non-forks)'
        # The scripts shard runs the root script harness, which produces no
        # per-workspace junit.xml. Skip it to avoid a "no test report files
        # found" error.
        if: |-
          ${{ always() && matrix.shard != 'scripts' && (github.event.pull_request.head.repo.full_name == github.repository) }}
        uses: 'dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2' # ratchet:dorny/test-reporter@v3
        with:
          name: 'Test Results [${{ matrix.shard }} ${{ matrix.partition }}] (Node ${{ matrix.node-version }}, ${{ matrix.os }})'
          path: 'packages/*/junit.xml'
          reporter: 'java-junit'
          fail-on-error: 'false'

      - name: 'Upload Test Results Artifact (for forks)'
        if: |-
          ${{ always() && matrix.shard != 'scripts' && (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
        uses: 'actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' # ratchet:actions/upload-artifact@v7
        with:
          name: 'test-results-fork-${{ matrix.shard }}-${{ matrix.partition }}-${{ matrix.node-version }}-${{ matrix.os }}'
          path: 'packages/*/junit.xml'

  #
  # Test: virtual aggregator (issue #2707)
  #
  # Mirrors the existing `lint` virtual job: it depends on every shard leg and
  # only succeeds when all of them do. Keeping the required-check name as
  # `Test` means branch-protection rules do not need to change — downstream
  # jobs and required checks keep gating on a single
  # name while the real work fans out across the matrix.
  #
  # `if: always()` is essential: when a `test_shard` leg fails or is skipped
  # (e.g. because an upstream `node_consumer_smoke` dependency failed), GitHub
  # would otherwise **skip** this job, and branch protection treats skipped
  # checks as passing — a silent bypass. The explicit result check converts
  # any non-success outcome (failure, skipped, cancelled) into a `failure`
  # conclusion on this required check.
  #
  # Issue #2709: the `test` job now also depends on `shard_selector`. When the
  # selector succeeds and explicitly reports has_tests=false (the PR touches
  # no testable code), test_shard is intentionally skipped (empty matrix). In
  # that case `test` is green: the selector said there is nothing to test and
  # it succeeded. Any other selector outcome (failed, skipped) makes `test`
  # red, because a skipped/failed selector means we cannot trust the skip and
  # must fail closed.
  #
  # ACP Conformance (issue #2564)
  #
  # Runs the pinned acplint v0.2.0 selected-category gate (initialization,
  # session_lifecycle, schema_validation) against the real LLxprt ACP stdio
  # launcher. The non-secret placeholder key initializes the provider without
  # prompting a model or performing network inference. Captures raw status,
  # log, and JSON report, validates the report with the committed single-purpose
  # validator, and uploads diagnostics as an always-run artifact.
  acp_conformance:
    name: 'ACP Conformance'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 20
    needs:
      - 'doc_change_filter'
      - 'skip_check'
    # Skip on docs-only PRs (issue #342): a doc edit cannot change the
    # built CLI's agent conformance behaviour.
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
    steps:
      - name: 'Initialize diagnostics and LLXPRT homes'
        run: |-
          set -euo pipefail
          diag_dir="${RUNNER_TEMP}/acplint/diagnostics"
          log_dir="${diag_dir}/llxprt-logs"
          config_home="${RUNNER_TEMP}/acplint/llxprt-config"
          data_home="${RUNNER_TEMP}/acplint/llxprt-data"
          mkdir -p "${diag_dir}" "${log_dir}" "${config_home}" "${data_home}"
          printf 'not-run\n' > "${diag_dir}/status.txt"
          printf 'acplint gate has not run yet (setup not complete)\n' \
            > "${diag_dir}/acplint.log"
          {
            echo "ACPLINT_DIAG_DIR=${diag_dir}"
            echo "LLXPRT_CONFIG_HOME=${config_home}"
            echo "LLXPRT_DATA_HOME=${data_home}"
            echo "LLXPRT_LOG_HOME=${log_dir}"
          } >> "${GITHUB_ENV}"

      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Set up Python'
        uses: 'actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97' # ratchet:actions/setup-python@v7
        with:
          python-version: '3.11'

      - name: 'Install dependencies'
        run: |-
          bun install

      - name: 'Install acplint'
        run: |-
          python -m pip install "acplint @ git+https://github.com/rinadelph/acplint.git@e2f4e49b3ba825869a4ecab7e10076d4460f4dcd"

      - name: 'Verify acplint version'
        run: |-
          [ "$(acplint --version)" = "acplint 0.2.0" ]

      - name: 'Build project'
        run: |-
          npm run build

      # Reuse this full JS build on Node 24/Linux, independently of shard
      # selection. All non-doc changes run here, including MCP's transitive
      # workspace dependencies and the distribution runner. No extra install.
      # POSIX fixture coverage only; this does not claim Windows coverage.
      - name: 'Verify standalone MCP distribution'
        run: |-
          npm run test:mcp:distribution -- tmp/mcp-distribution-ci

      - name: 'Upload standalone MCP distribution diagnostics'
        if: ${{ always() }}
        uses: 'actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' # ratchet:actions/upload-artifact@v7
        with:
          name: 'mcp-distribution-diagnostics'
          path: |-
            tmp/mcp-distribution-ci/
            !tmp/mcp-distribution-ci/packed/
          if-no-files-found: 'warn'

      - name: 'Run acplint'
        run: |-
          set +e
          acplint \
            --agent "./packages/cli/bin/llxprt" \
            --agent-args "--experimental-acp --provider openai --model gpt-4o --key acplint-ci" \
            --categories initialization session_lifecycle schema_validation \
            --output json \
            --output-file "${ACPLINT_DIAG_DIR}/report.json" \
            --cwd "${GITHUB_WORKSPACE}" \
            > "${ACPLINT_DIAG_DIR}/acplint.log" 2>&1
          EXIT_CODE=$?
          echo "$EXIT_CODE" > "${ACPLINT_DIAG_DIR}/status.txt"
          echo "acplint raw exit status: $EXIT_CODE"
          echo '::group::acplint log tail'
          tail -n 200 "${ACPLINT_DIAG_DIR}/acplint.log"
          echo '::endgroup::'
          exit 0

      - name: 'Validate acplint report'
        run: |-
          STATUS="$(cat "${ACPLINT_DIAG_DIR}/status.txt")"
          node scripts/validate-acplint-report.ts "${ACPLINT_DIAG_DIR}/report.json" "$STATUS"

      - name: 'Upload acplint diagnostics'
        if: ${{ always() }}
        uses: 'actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' # ratchet:actions/upload-artifact@v7
        with:
          name: 'acplint-diagnostics'
          path: ${{ runner.temp }}/acplint/diagnostics/
          if-no-files-found: 'error'

  test:
    name: 'Test'
    needs:
      - 'test_shard'
      - 'shard_selector'
      - 'skip_check'
      - 'node_consumer_smoke'
      - 'acp_conformance'
      - 'doc_change_filter'
      - 'windows_test_infra'
    if: ${{ always() }}
    runs-on: 'ubuntu-latest'
    steps:
      - name: 'Check shard results'
        run: |-
          should_skip='${{ needs.skip_check.outputs.should_skip }}'
          docs_only='${{ needs.doc_change_filter.outputs.docs_only }}'
          selector_result='${{ needs.shard_selector.result }}'
          has_tests='${{ needs.shard_selector.outputs.has_tests }}'
          shard_result='${{ needs.test_shard.result }}'
          node_consumer_smoke_result='${{ needs.node_consumer_smoke.result }}'
          acp_result='${{ needs.acp_conformance.result }}'
          windows_infra_result='${{ needs.windows_test_infra.result }}'
          windows_infra_affected='${{ needs.windows_test_infra.outputs.affected }}'

          # Explicit duplicate-skip: skip_check said this run duplicates a
          # passing one, so every downstream job was intentionally skipped.
          # The required Test check is green by design.
          if [ "$should_skip" == "true" ]; then
            echo "skip_check reported a duplicate passing run (should_skip=true). Test check is green by design."
            exit 0
          fi

          # There is intentionally NO unconditional docs-only early return here
          # (issue #342). shard_selector is an independent, stricter classifier
          # than doc_change_filter; requiring it to succeed (and, when it reports
          # tests, requiring the selected shards to succeed) means a
          # misclassification by doc_change_filter fails closed instead of
          # greening the required Test check. Only the docs-only-skippable jobs
          # (node_consumer_smoke, acp_conformance) accept a `skipped` result when
          # docs_only == 'true'; the selector/has_tests/test_shard logic below is
          # unchanged.

          # Fail closed if the selector itself did not succeed.
          if [ "$selector_result" != "success" ]; then
            echo "::error::Shard selector did not succeed (result: $selector_result); cannot trust test selection."
            exit 1
          fi

          # node_consumer_smoke must succeed on code PRs. On docs-only PRs
          # (issue #342) it is intentionally skipped, which is accepted here.
          if [ "$node_consumer_smoke_result" != "success" ]; then
            if [ "$docs_only" == "true" ] && [ "$node_consumer_smoke_result" == "skipped" ]; then
              echo "docs-only PR: node_consumer_smoke intentionally skipped (issue #342)."
            else
              echo "::error::Node Consumer Smoke did not succeed (result: $node_consumer_smoke_result)"
              exit 1
            fi
          fi

          # Intentional no-test PR: selector succeeded and said has_tests=false.
          if [ "$has_tests" != "true" ]; then
            echo "Shard selector reported no tests to run (has_tests=false)."
          else
            # Normal case: all selected shards must succeed.
            if [ "$shard_result" != "success" ]; then
              echo "::error::Test shards did not all succeed (result: $shard_result)"
              exit 1
            fi
          fi

          # ACP conformance must succeed on code PRs. On docs-only PRs it is
          # intentionally skipped (issue #342), which is accepted here.
          if [ "$acp_result" != "success" ]; then
            if [ "$docs_only" == "true" ] && [ "$acp_result" == "skipped" ]; then
              echo "docs-only PR: acp_conformance intentionally skipped (issue #342)."
            else
              echo "::error::ACP conformance job did not succeed (result: $acp_result)"
              exit 1
            fi
          fi

          # Windows test-infra gate (issue #3439) must succeed when it ran.
          # It reports skipped in two intentional cases: docs-only PRs (its
          # job-level if mirrors the other smoke jobs) and path-filtered PRs
          # whose changes cannot affect the Windows-sensitive suites
          # (affected=false). Anything else — including a failure — fails the
          # required Test check.
          if [ "$windows_infra_result" != "success" ]; then
            if [ "$windows_infra_result" == "skipped" ] && { [ "$docs_only" == "true" ] || [ "$windows_infra_affected" == "false" ]; }; then
              echo "Windows test-infra gate intentionally skipped (docs_only=$docs_only, affected=$windows_infra_affected)."
            else
              echo "::error::Windows test-infra gate did not succeed (result: $windows_infra_result)"
              exit 1
            fi
          fi

          echo 'All test shards finished!'

  secure_store_backend:
    name: 'SecureStore Backend (${{ matrix.os }}, ${{ matrix.secure-store-mode }})'
    runs-on: '${{ matrix.os }}'
    timeout-minutes: 15
    needs:
      - 'lint'
      - 'doc_change_filter'
      - 'skip_check'
    if: ${{ needs.doc_change_filter.outputs.docs_only != 'true' && needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
      checks: 'write'
      pull-requests: 'write'
    strategy:
      fail-fast: false
      matrix:
        # Issue #2876: macOS keyring coverage moved to the nightly workflow.
        # The PR matrix is ubuntu-only to reduce macOS runner contention.
        include:
          - os: 'ubuntu-latest'
            node-version: '24.x'
            secure-store-mode: 'keyring'
            test-script: 'test:secure-store:keyring'
          - os: 'ubuntu-latest'
            node-version: '24.x'
            secure-store-mode: 'fallback'
            test-script: 'test:secure-store:fallback'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js ${{ matrix.node-version }}'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version: '${{ matrix.node-version }}'

      - name: 'Setup Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          bun-version-file: '.bun-version'

      - name: 'Cache Bun dependencies'
        uses: 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' # ratchet:actions/cache@v6
        with:
          path: |
            ~/.bun/install/cache
          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}

      - name: 'Install dependencies for SecureStore tests'
        run: |-
          bun install
          git checkout -- bun.lock

      - name: 'Install Linux Secret Service dependencies'
        if: matrix.os == 'ubuntu-latest' && matrix.secure-store-mode == 'keyring'
        run: |-
          sudo apt-get update
          sudo apt-get install --no-install-recommends -y dbus-x11 gnome-keyring libglib2.0-bin libsecret-1-0

      - name: 'Run SecureStore backend tests'
        env:
          CI: true
          NO_COLOR: true
          SECURE_STORE_MODE: '${{ matrix.secure-store-mode }}'
          TEST_SCRIPT: '${{ matrix.test-script }}'
          KEYRING_PASSWORD: 'llxprt-ci-keyring'
        run: |-
          if [[ "$RUNNER_OS" == 'Linux' && "$SECURE_STORE_MODE" == 'keyring' ]]; then
            export XDG_RUNTIME_DIR
            XDG_RUNTIME_DIR="$(mktemp -d "$RUNNER_TEMP/secure-store-runtime.XXXXXX")"
            chmod 700 "$XDG_RUNTIME_DIR"
            trap 'rm -rf "$XDG_RUNTIME_DIR"' EXIT
            dbus-run-session -- bash -euo pipefail -c '
              export XDG_DATA_HOME="$XDG_RUNTIME_DIR/data"
              install -d -m 700 "$XDG_DATA_HOME"

              import_keyring_environment() {
                local assignment export_suffix variable_name variable_value
                while IFS= read -r assignment; do
                  [[ -z "$assignment" ]] && continue
                  case "$assignment" in
                    GNOME_KEYRING_CONTROL=*|GNOME_KEYRING_PID=*|GPG_AGENT_INFO=*|SSH_AUTH_SOCK=*)
                      variable_name="${assignment%%=*}"
                      variable_value="${assignment#*=}"
                      export_suffix="; export $variable_name;"
                      if [[ "$variable_value" == *"$export_suffix" ]]; then
                        variable_value="${variable_value%"$export_suffix"}"
                      elif [[ "$variable_value" == *";"* ]]; then
                        printf "Unsafe gnome-keyring-daemon assignment: %s\n" "$assignment" >&2
                        exit 1
                      fi
                      export "$variable_name=$variable_value"
                      ;;
                    *)
                      printf "Unexpected gnome-keyring-daemon output: %s\n" "$assignment" >&2
                      exit 1
                      ;;
                  esac
                done <<<"$1"
              }

              login_env="$(printf "%s" "$KEYRING_PASSWORD" | gnome-keyring-daemon --login)"
              import_keyring_environment "$login_env"
              daemon_env="$(gnome-keyring-daemon --start --components=secrets)"
              import_keyring_environment "$daemon_env"

              if [[ -z "$DBUS_SESSION_BUS_ADDRESS" ]]; then
                printf "dbus-run-session did not provide a session bus address\n" >&2
                exit 1
              fi
              secret_service_owner="$(gdbus call --session \
                --dest org.freedesktop.DBus \
                --object-path /org/freedesktop/DBus \
                --method org.freedesktop.DBus.NameHasOwner \
                org.freedesktop.secrets)"
              if [[ "$secret_service_owner" != "(true,)" ]]; then
                printf "org.freedesktop.secrets has no owner: %s\n" "$secret_service_owner" >&2
                exit 1
              fi
              login_collection_locked="$(gdbus call --session \
                --dest org.freedesktop.secrets \
                --object-path /org/freedesktop/secrets/collection/login \
                --method org.freedesktop.DBus.Properties.Get \
                org.freedesktop.Secret.Collection Locked)"
              if [[ "$login_collection_locked" != "(<false>,)" ]]; then
                printf "GNOME login collection is not unlocked: %s\n" "$login_collection_locked" >&2
                exit 1
              fi
              npm run "$TEST_SCRIPT" --workspace @vybestack/llxprt-code-storage
            '
          else
            npm run "$TEST_SCRIPT" --workspace @vybestack/llxprt-code-storage
          fi

      - name: 'Publish SecureStore Test Report'
        if: |-
          ${{ always() && (github.event.pull_request.head.repo.full_name == github.repository) }}
        uses: 'dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2' # ratchet:dorny/test-reporter@v3
        with:
          name: 'SecureStore Backend Results (Node ${{ matrix.node-version }}, ${{ matrix.os }}, ${{ matrix.secure-store-mode }})'
          path: 'packages/storage/junit.secure-store.xml'
          reporter: 'java-junit'
          fail-on-error: 'false'

      - name: 'Upload SecureStore Test Results Artifact (for forks)'
        if: |-
          ${{ always() && (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
        uses: 'actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' # ratchet:actions/upload-artifact@v7
        with:
          name: 'secure-store-results-fork-${{ matrix.node-version }}-${{ matrix.os }}-${{ matrix.secure-store-mode }}'
          path: 'packages/storage/junit.secure-store.xml'

  codeql:
    name: 'CodeQL'
    runs-on: 'ubuntu-latest'
    # Issue #3187: bound CodeQL's pull-request runner time so candidate runs can
    # satisfy the umbrella's under-ten-minute verdict target (#2702). Measured
    # full push scans routinely take 70–79 minutes, so all non-PR events retain
    # the 360-minute allowance. A timeout remains a non-success conclusion;
    # candidate CI measures the end-to-end verdict.
    timeout-minutes: ${{ github.event_name == 'pull_request' && 15 || 360 }}
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      actions: 'read'
      contents: 'read'
      security-events: 'write'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Initialize CodeQL'
        uses: 'github/codeql-action/init@bce182f857edf1feab116e9795a3393d21977282' # ratchet:github/codeql-action/init@v4
        with:
          languages: 'javascript'
          # Issue #3567: route non-PR events (push, workflow_dispatch) to the
          # security-and-quality suite plus the local mechanism-class query
          # pack, while pull_request and merge_group keep the default security
          # suite until #3495/#3187 settle the PR-path budgets (#2702).
          config-file: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && './.github/codeql/codeql-config.yml' || './.github/codeql/codeql-config-pr.yml' }}

      - name: 'Perform CodeQL Analysis'
        uses: 'github/codeql-action/analyze@bce182f857edf1feab116e9795a3393d21977282' # ratchet:github/codeql-action/analyze@v4

  runtime_plugins:
    name: 'Runtime Plugins (build, typecheck, test)'
    runs-on: 'ubuntu-latest'
    timeout-minutes: 30
    needs:
      - 'skip_check'
    if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
    permissions:
      contents: 'read'
    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' # ratchet:actions/checkout@v7
        with:
          persist-credentials: false

      - name: 'Set up Node.js'
        uses: 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' # ratchet:actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'

      - name: 'Set up Bun'
        uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' # ratchet:oven-sh/setup-bun@v2
        with:
          # Plugin-local flows need bun >= 1.4.2: earlier releases reject the
          # plugin lockfile's unresolved root peers on re-install and hang.
          # The repo-wide pin (.bun-version) stays older on purpose so the
          # root bun.lock format is never migrated.
          bun-version: '1.4.2'

      # The plugin contexts sit outside the root workspaces (issue #2759), so
      # each one installs, typechecks, tests, builds, and pack-smokes from its
      # own directory with its own lockfile. The directory list is explicit;
      # it mirrors FIRST_PARTY_RUNTIME_PLUGIN_RELEASES and is never derived by
      # scanning. Full plugin CI coverage (artifact suites, affected
      # selection) lands with issue #2762.
      #
      # The root install runs FIRST: plugin tsconfig paths resolve host source
      # under ../../packages/*, and that source imports other workspace
      # packages (@vybestack/llxprt-code-ide-integration, -auth, -tools,
      # -mcp) resolvable only through root node_modules.
      - name: 'Install root dependencies'
        # Bun re-normalizes `bun.lock` on every install (dev-docs/bun.md);
        # restore the committed lockfile so no downstream step sees a dirty
        # one (mirrors the smoke and test-shard jobs).
        run: |-
          bun install
          git checkout -- bun.lock

      # Plugin build programs resolve host types via root node_modules links
      # into packages/*/dist (tsconfig.build.json paths only externalize the
      # composition contract), so the host must be built first, exactly like
      # release.yml's plugin phase runs after the base-CLI build.
      - name: 'Build host packages'
        run: 'npm run build'

      - name: 'Install, typecheck, test, build, and pack-smoke each plugin'
        run: |
          set -euo pipefail
          for plugin in plugins/google-gemini plugins/google-mcp-auth; do
            echo "::group::${plugin}"
            (
              cd "$plugin" &&
                bun install --omit=peer &&
                bun run typecheck &&
                bun test &&
                bun run build &&
                bun run pack:smoke
            )
            echo "::endgroup::"
          done