Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Stage agent validation and verify combined merges in CI (#966)

Deeefcc553e68a6
diff --git a/.github/workflows/authoring-browser-checks.yml b/.github/workflows/authoring-browser-checks.yml
index e1c441542..76498ad15 100644
--- a/.github/workflows/authoring-browser-checks.yml
+++ b/.github/workflows/authoring-browser-checks.yml
@@ -1,50 +1,22 @@
name: Authoring browser checks
# Only changes used by this suite start the expensive browser/native checks.
+# Automatic invocations are selected by ci.yml; standalone runs remain available.
on:
workflow_dispatch:
- pull_request:
- paths:
- - 'store/agents/generative-art/**'
- - 'store/agents/music-studio/**'
- - 'store/agents/creative-direction/**'
- - 'store/agents/voxel-worlds/**'
- - 'store/agents/drone-pilot/**'
- - 'store/agents/game-master/**'
- - 'store/agents/lab-bench/**'
- - 'store/agents/data-studio/**'
- - 'store/viewers/web-viewer/**'
- - 'store/tools/**'
- - '.github/workflows/authoring-browser-checks.yml'
- push:
- branches: [main]
- paths:
- - 'store/agents/generative-art/**'
- - 'store/agents/music-studio/**'
- - 'store/agents/creative-direction/**'
- - 'store/agents/voxel-worlds/**'
- - 'store/agents/drone-pilot/**'
- - 'store/agents/game-master/**'
- - 'store/agents/lab-bench/**'
- - 'store/agents/data-studio/**'
- - 'store/viewers/web-viewer/**'
- - 'store/tools/**'
- - '.github/workflows/authoring-browser-checks.yml'
+ workflow_call:
permissions:
contents: read
-# New commits replace obsolete checks for the same PR or branch.
-concurrency:
- group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
- cancel-in-progress: true
-
jobs:
authoring-browser:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
with:
node-version: '22.23.2'
diff --git a/.github/workflows/ci-health.yml b/.github/workflows/ci-health.yml
new file mode 100644
index 000000000..60e343f7b
--- /dev/null
+++ b/.github/workflows/ci-health.yml
@@ -0,0 +1,34 @@
+name: CI health
+
+on:
+ schedule:
+ - cron: '43 * * * *'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ actions: read
+
+concurrency:
+ group: ci-health
+ cancel-in-progress: false
+
+jobs:
+ report:
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ sparse-checkout: scripts/ci-health.py
+ sparse-checkout-cone-mode: false
+ - name: Measure completed validation and cancelled execution
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: python3 scripts/ci-health.py
+ - uses: actions/upload-artifact@v4
+ with:
+ name: ci-health
+ path: ${{ runner.temp }}/ci-health.json
+ if-no-files-found: error
+ retention-days: 30
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e2b1fea11..f90995ddb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,25 +1,19 @@
name: CI
-# Modelled on autonomous-harness-desktop's ci.yml. Like that one, this runs ON DEMAND only.
-#
-# It used to run on every pull request as well (2026-09-10 → 2026-09-16). That was switched off
-# deliberately: the suite is timing-sensitive on the shared ubuntu runner (real tmux server, shell
-# scripts, sqlite3 polls), so a red check on a PR said more about the runner than about the change,
-# and every contributor had to read the log to find out which. The verdict on a branch is still one
-# click away — Actions -> CI -> Run workflow, pick the branch — which is what a reviewer does when
-# they want it. If per-PR CI comes back, use `pull_request`, never `pull_request_target`: a fork's PR
-# must run with a read-only token and no secrets, since this job executes the contributor's code.
-#
-# There is no `push` trigger either. Nobody pushes to main directly (CONTRIBUTING.md step 2) and
-# merges are squashed, so a push run would re-test a commit somebody already ran by hand.
+# Automatic PR and merge-candidate validation use the same coarse suite planner.
+# Contributor code runs with a read-only token and no release credentials.
on:
- # The only way this runs on its own: Actions -> CI -> Run workflow, on any branch.
+ pull_request:
+ branches: [main, 'ci-rollout/**']
+ types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]
+ merge_group:
+ types: [checks_requested]
workflow_dispatch:
inputs:
scope:
- description: 'Affected components (full for shared protocols or uncertain impact)'
+ description: 'Affected component; full for core suites, all for every component'
type: choice
- options: [full, cli, tui, backend, desktop, process]
+ options: [full, cli, tui, backend, desktop, process, all, companions, website, experience, authoring, home-assistant, desktop-logging, os, provider, firmware, mobile, daemons]
default: full
# Callable as a reusable workflow. release.yml used to gate on this and take the Node pin from
# its output; it no longer does (see the note above `publish` there) and pins the same version
@@ -41,21 +35,74 @@ permissions:
# The managed runtime shipped by the CLI; keep release.yml's pin in sync.
env:
CLI_NODE_VERSION: 22.23.2
+ CI_SOURCE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
-concurrency:
- group: cli-ci-${{ github.workflow }}-${{ github.ref }}-${{ inputs.scope || 'full' }}
- # Every run here was started by a person or by a release, and is the record of whether that commit
- # was green — never killed to make room for a newer one.
- cancel-in-progress: false
+# Supersede individual PR jobs, not the whole workflow: an always-running final
+# gate on an obsolete revision must not hold the next revision's scheduling lock.
+# Every matrix row has its own group. Explicit runs and merge candidates use run
+# IDs, so their requested validation is preserved. Summaries and the final gate
+# have no lock: an older aggregate can finish after newer work without cancelling it.
jobs:
+ plan:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-plan
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ outputs:
+ plan: ${{ steps.select.outputs.plan }}
+ ready: ${{ steps.select.outputs.ready }}
+ cli: ${{ steps.select.outputs.cli }}
+ desktop: ${{ steps.select.outputs.desktop }}
+ tui: ${{ steps.select.outputs.tui }}
+ backend: ${{ steps.select.outputs.backend }}
+ companions: ${{ steps.select.outputs.companions }}
+ website: ${{ steps.select.outputs.website }}
+ experience: ${{ steps.select.outputs.experience }}
+ authoring: ${{ steps.select.outputs.authoring }}
+ home-assistant: ${{ steps.select.outputs.home-assistant }}
+ desktop-logging: ${{ steps.select.outputs.desktop-logging }}
+ os: ${{ steps.select.outputs.os }}
+ provider: ${{ steps.select.outputs.provider }}
+ firmware: ${{ steps.select.outputs.firmware }}
+ mobile: ${{ steps.select.outputs.mobile }}
+ daemons: ${{ steps.select.outputs.daemons }}
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ fetch-depth: 0
+ - name: Validate the integration workflows
+ run: >-
+ go run github.com/rhysd/actionlint/cmd/[email protected]
+ .github/workflows/ci.yml .github/workflows/cli-e2e.yml .github/workflows/ci-health.yml
+ .github/workflows/website-checks.yml .github/workflows/experience-checks.yml
+ .github/workflows/authoring-browser-checks.yml .github/workflows/home-assistant-checks.yml
+ .github/workflows/desktop-logging-checks.yml
+ - id: select
+ env:
+ CI_SCOPE: ${{ inputs.scope || 'full' }}
+ run: python3 scripts/ci-plan.py --scope "$CI_SCOPE" --output "$RUNNER_TEMP/ci-plan.json"
+ - uses: actions/upload-artifact@v4
+ with:
+ name: ci-plan
+ path: ${{ runner.temp }}/ci-plan.json
+ if-no-files-found: error
+ overwrite: true
+ retention-days: 14
+
process-checks:
- if: ${{ contains(fromJSON('["full","cli","tui","backend","desktop","process"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-process-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
- uses: actions/checkout@v7
with:
+ ref: ${{ env.CI_SOURCE_SHA }}
sparse-checkout: |
/.github/
/scripts/
@@ -79,16 +126,12 @@ jobs:
overwrite: true
retention-days: 7
- # workflow_dispatch restricts the choice; reusable callers can pass any string.
- # Fail invalid calls rather than reporting success after skipping every check.
- invalid-scope:
- if: ${{ !contains(fromJSON('["full","cli","tui","backend","desktop","process"]'), inputs.scope || 'full') }}
- runs-on: ubuntu-latest
- steps:
- - run: echo '::error::scope must be full, cli, tui, backend, desktop, or process'; exit 1
-
desktop-tests:
- if: ${{ contains(fromJSON('["full","desktop"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-desktop-tests-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.desktop == 'true'
name: desktop-tests (${{ matrix.os }}, ${{ matrix.shard }})
runs-on: ${{ matrix.os }}
timeout-minutes: 15
@@ -100,6 +143,7 @@ jobs:
steps:
- uses: actions/checkout@v7
with:
+ ref: ${{ env.CI_SOURCE_SHA }}
sparse-checkout: |
/.github/
/scripts/
@@ -141,13 +185,14 @@ jobs:
retention-days: 7
desktop-test-summary:
- needs: desktop-tests
- if: ${{ !cancelled() && contains(fromJSON('["full","desktop"]'), inputs.scope || 'full') }}
+ needs: [plan, desktop-tests]
+ if: ${{ !cancelled() && needs.plan.outputs.ready == 'true' && needs.plan.outputs.desktop == 'true' }}
runs-on: ubuntu-22.04
timeout-minutes: 3
steps:
- uses: actions/checkout@v7
with:
+ ref: ${{ env.CI_SOURCE_SHA }}
sparse-checkout: |
/desktop/test/
/scripts/
@@ -178,7 +223,11 @@ jobs:
# binary backpressure and unplug behavior on both supported OSes and runtimes.
# These are disposable PTYs; no USB device or existing daemon is touched.
serial-native:
- if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-serial-native-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true'
strategy:
fail-fast: false
matrix:
@@ -191,6 +240,8 @@ jobs:
working-directory: cli
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node }}
@@ -207,7 +258,11 @@ jobs:
# Build both slices and execute each host architecture. All process/tmux
# fixtures are private; no installed agent or running session is controlled.
process-images-native:
- if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-process-images-native-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true'
strategy:
fail-fast: false
matrix:
@@ -219,6 +274,8 @@ jobs:
working-directory: cli
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: 22.23.2
@@ -241,7 +298,11 @@ jobs:
# The optional product has its own dependencies, bundle and suites. CLI-only CI
# deliberately checks core without installing or building this package.
companion-subsystems:
- if: ${{ (inputs.scope || 'full') == 'full' }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-companion-subsystems
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.companions == 'true'
runs-on: ubuntu-latest
timeout-minutes: 10
defaults:
@@ -249,6 +310,8 @@ jobs:
working-directory: companions
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: ${{ env.CLI_NODE_VERSION }}
@@ -268,7 +331,11 @@ jobs:
# Typecheck and contract checks run alongside the default suite's four shards.
cli-contracts:
- if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-cli-contracts
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
outputs:
@@ -278,6 +345,8 @@ jobs:
working-directory: cli
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
# THE runtime pin — release.yml's `publish` job carries the same value; bump them together.
#
@@ -356,7 +425,11 @@ jobs:
# remembered: test:resume had slipped to 93% of stoppedAgents.ts and test:orchestrator below 100% by
# 5 October 2026 without anyone noticing. One step per gate, so a red run names the gate.
cli-coverage-gates:
- if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-cli-coverage-gates
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true'
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
@@ -364,6 +437,8 @@ jobs:
working-directory: cli
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: ${{ env.CLI_NODE_VERSION }}
@@ -392,7 +467,11 @@ jobs:
retention-days: 7
cli-tests:
- if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-cli-tests-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true'
strategy:
fail-fast: false
matrix:
@@ -404,6 +483,8 @@ jobs:
working-directory: cli
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: ${{ env.CLI_NODE_VERSION }}
@@ -432,8 +513,8 @@ jobs:
# Preserve the original aggregate check/output for callers. A missing, failed
# or skipped shard/contract job cannot turn into a green aggregate check.
typecheck-test:
- needs: [cli-contracts, cli-tests]
- if: ${{ !cancelled() && contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ needs: [plan, cli-contracts, cli-tests]
+ if: ${{ !cancelled() && needs.plan.outputs.ready == 'true' && needs.plan.outputs.cli == 'true' }}
runs-on: ubuntu-latest
timeout-minutes: 3
outputs:
@@ -441,6 +522,7 @@ jobs:
steps:
- uses: actions/checkout@v7
with:
+ ref: ${{ env.CI_SOURCE_SHA }}
# This job reads only the shard reports and this stdlib-only verifier.
# Avoid fetching/materializing the app, fixtures and performance assets again.
sparse-checkout: scripts/verify-cli-test-shards.py
@@ -470,7 +552,11 @@ jobs:
# Native shell lifecycle checks on the Linux platforms used over SSH. This workflow
# remains on demand; it builds and tests without publishing or installing a release.
tui-test:
- if: ${{ contains(fromJSON('["full","tui"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-tui-test-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.tui == 'true'
strategy:
fail-fast: false
matrix:
@@ -484,6 +570,8 @@ jobs:
working-directory: tui
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: dtolnay/rust-toolchain@stable
with:
targets: ${{ matrix.target }}
@@ -569,7 +657,11 @@ jobs:
retention-days: 14
backend-desk:
- if: ${{ contains(fromJSON('["full","backend"]'), inputs.scope || 'full') }}
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-backend-desk
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.backend == 'true'
runs-on: ubuntu-latest
timeout-minutes: 10
defaults:
@@ -577,6 +669,8 @@ jobs:
working-directory: backend
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
- uses: actions/setup-node@v7
with:
node-version: 22.23.2
@@ -585,3 +679,206 @@ jobs:
- run: npm ci --no-audit --no-fund
- name: Shared desk layout compatibility
run: npm test -- src/routes/desk.test.ts
+
+ website-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-website-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.website == 'true'
+ uses: ./.github/workflows/website-checks.yml
+
+ experience-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-experience-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.experience == 'true'
+ uses: ./.github/workflows/experience-checks.yml
+
+ authoring-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-authoring-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.authoring == 'true'
+ uses: ./.github/workflows/authoring-browser-checks.yml
+
+ home-assistant-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-home-assistant-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.home-assistant == 'true'
+ uses: ./.github/workflows/home-assistant-checks.yml
+
+ desktop-logging-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-desktop-logging-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.desktop-logging == 'true'
+ uses: ./.github/workflows/desktop-logging-checks.yml
+
+ os-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-os-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.os == 'true'
+ runs-on: ubuntu-24.04
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ - name: OS source, installer and update contracts
+ run: make -C os check
+
+ provider-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-provider-checks-${{ strategy.job-index }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.provider == 'true'
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ strategy:
+ fail-fast: false
+ matrix:
+ package: [reference-provider, example-provider]
+ defaults:
+ run:
+ working-directory: provider/${{ matrix.package }}
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ - uses: actions/setup-node@v7
+ with:
+ node-version: ${{ env.CLI_NODE_VERSION }}
+ cache: npm
+ cache-dependency-path: provider/${{ matrix.package }}/package-lock.json
+ - run: npm ci --no-audit --no-fund
+ - run: npm run typecheck
+ - run: npm test
+
+ firmware-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-firmware-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.firmware == 'true'
+ runs-on: ubuntu-24.04
+ timeout-minutes: 15
+ env:
+ IDF_PATH: ${{ github.workspace }}/.ci-esp-idf
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ - uses: actions/checkout@v7
+ with:
+ repository: espressif/esp-idf
+ ref: 8c750b088c7cd857d079c0eeb495da199b359461 # v5.5
+ path: .ci-esp-idf
+ sparse-checkout: |
+ components/json
+ components/esp_rom
+ - name: Prepare the SDK's pinned cJSON source
+ run: git -C "$IDF_PATH" submodule update --init --depth 1 components/json/cJSON
+ - name: Use Clang for the host fixture warning and sanitizer contracts
+ run: |
+ clang-18 --version
+ mkdir -p "$RUNNER_TEMP/firmware-bin"
+ ln -s "$(command -v clang-18)" "$RUNNER_TEMP/firmware-bin/cc"
+ echo "$RUNNER_TEMP/firmware-bin" >> "$GITHUB_PATH"
+ - name: Run every host firmware contract (physical acceptance remains separate)
+ run: |
+ python3 - <<'PY'
+ from pathlib import Path
+ import subprocess
+ files = sorted(Path('devices/harness-device/firmware/test').glob('test_*.py'))
+ assert files, 'firmware test inventory is empty'
+ failures = []
+ for path in files:
+ print(path, flush=True)
+ try:
+ subprocess.run(['python3', str(path)], check=True, timeout=120)
+ except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+ failures.append(str(path))
+ if failures:
+ raise SystemExit('Failed firmware contracts: ' + ', '.join(failures))
+ print(f'Passed all {len(files)} firmware host contracts')
+ PY
+
+ mobile-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-mobile-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.mobile == 'true'
+ runs-on: ubuntu-22.04
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ - id: toolchain
+ run: |
+ version="$(sed -n "s/^ FLUTTER_VERSION: '\([^']*\)'.*/\1/p" .github/workflows/release-desktop.yml)"
+ test -n "$version"
+ echo "version=$version" >> "$GITHUB_OUTPUT"
+ - uses: subosito/flutter-action@v2
+ with:
+ flutter-version: ${{ steps.toolchain.outputs.version }}
+ channel: stable
+ cache: true
+ - run: flutter pub get
+ working-directory: mobile
+ - run: flutter test --no-pub --concurrency 4 --reporter expanded
+ working-directory: mobile
+
+ daemons-checks:
+ concurrency:
+ group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}-daemons-checks
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+ needs: plan
+ if: needs.plan.outputs.ready == 'true' && needs.plan.outputs.daemons == 'true'
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ - uses: actions/setup-node@v7
+ with:
+ node-version: ${{ env.CLI_NODE_VERSION }}
+ - run: node --test daemons/tools/card.test.mjs
+
+ required:
+ name: ci/required
+ needs: [plan, process-checks, desktop-tests, desktop-test-summary, serial-native, process-images-native,
+ companion-subsystems, cli-contracts, cli-coverage-gates, cli-tests, typecheck-test, tui-test,
+ backend-desk, website-checks, experience-checks, authoring-checks, home-assistant-checks,
+ desktop-logging-checks, os-checks, provider-checks, firmware-checks, mobile-checks, daemons-checks]
+ if: always()
+ runs-on: ubuntu-latest
+ timeout-minutes: 3
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ env.CI_SOURCE_SHA }}
+ sparse-checkout: scripts/
+ - name: Require every selected job and complete coverage summaries
+ env:
+ CI_PLAN: ${{ needs.plan.outputs.plan }}
+ CI_NEEDS: ${{ toJSON(needs) }}
+ run: python3 scripts/ci-plan.py --verify --output "$RUNNER_TEMP/ci-required.json"
+ - uses: actions/upload-artifact@v4
+ with:
+ name: ci-required
+ path: ${{ runner.temp }}/ci-required.json
+ if-no-files-found: error
+ overwrite: true
+ retention-days: 14
diff --git a/.github/workflows/cli-e2e.yml b/.github/workflows/cli-e2e.yml
index 499a88ae4..5199c57cb 100644
--- a/.github/workflows/cli-e2e.yml
+++ b/.github/workflows/cli-e2e.yml
@@ -27,11 +27,11 @@ on:
permissions:
contents: read
-# A newer merge to main replaces the run of an older one; a nightly or dispatched run is somebody's
-# record and is left to finish.
+# Let active main validation finish; retain only the newest pending main snapshot.
+# Explicit/nightly runs have independent identities and are never superseded.
concurrency:
- group: cli-e2e-${{ github.ref }}-${{ github.event_name }}
- cancel-in-progress: ${{ github.event_name == 'push' }}
+ group: cli-e2e-${{ github.event_name }}-${{ github.event_name == 'push' && github.ref || github.run_id }}
+ cancel-in-progress: false
# The managed runtime the CLI ships on; keep ci.yml's and release.yml's pins in sync.
env:
diff --git a/.github/workflows/desktop-logging-checks.yml b/.github/workflows/desktop-logging-checks.yml
index 58794236c..6472acdb9 100644
--- a/.github/workflows/desktop-logging-checks.yml
+++ b/.github/workflows/desktop-logging-checks.yml
@@ -1,19 +1,9 @@
name: Desktop logging checks
+# Automatic invocations are selected by ci.yml; standalone runs remain available.
on:
- pull_request:
- paths:
- - 'desktop/lib/logging/**'
- - 'desktop/test/app_log_test.dart'
- - 'desktop/test/buffered_log_test.dart'
- - 'desktop/test/crash_log_test.dart'
- - 'desktop/test/dial_log_tail_test.dart'
- - 'desktop/test/log_*_test.dart'
- - 'desktop/test/export_logs_dialog_test.dart'
- - 'desktop/test/cli_transcript_test.dart'
- - 'desktop/tool/log_append_probe.dart'
- - '.github/workflows/desktop-logging-checks.yml'
workflow_dispatch:
+ workflow_call:
permissions:
contents: read
@@ -31,6 +21,8 @@ jobs:
working-directory: desktop
steps:
- uses: actions/checkout@v7
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
- id: toolchain
run: |
version="$(sed -n "s/^ FLUTTER_VERSION: '\([^']*\)'.*/\1/p" ../.github/workflows/release-desktop.yml)"
diff --git a/.github/workflows/experience-checks.yml b/.github/workflows/experience-checks.yml
index 61c4c2730..ea675357b 100644
--- a/.github/workflows/experience-checks.yml
+++ b/.github/workflows/experience-checks.yml
@@ -1,27 +1,21 @@
name: Experience checks
+# Automatic invocations are selected by ci.yml; standalone runs remain available.
on:
workflow_dispatch:
- pull_request:
- paths: ['store/**', 'desktop/assets/engine-icons/**', '.github/workflows/experience-checks.yml']
- push:
- branches: [main]
- paths: ['store/**', 'desktop/assets/engine-icons/**', '.github/workflows/experience-checks.yml']
+ workflow_call:
permissions:
contents: read
-# New commits replace obsolete checks for the same PR or branch.
-concurrency:
- group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
- cancel-in-progress: true
-
jobs:
models-and-viewer:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
with:
node-version: '22.23.2'
diff --git a/.github/workflows/home-assistant-checks.yml b/.github/workflows/home-assistant-checks.yml
index 6f97d8e4c..51ddb6831 100644
--- a/.github/workflows/home-assistant-checks.yml
+++ b/.github/workflows/home-assistant-checks.yml
@@ -1,36 +1,22 @@
name: Home Assistant checks
# Only changes used by this suite start the expensive browser/native checks.
+# Automatic invocations are selected by ci.yml; standalone runs remain available.
on:
workflow_dispatch:
- pull_request:
- paths:
- - 'store/agents/home-assistant/**'
- - 'store/tools/runtimes.sh'
- - 'store/tools/sync-runtimes.mjs'
- - '.github/workflows/home-assistant-checks.yml'
- push:
- branches: [main]
- paths:
- - 'store/agents/home-assistant/**'
- - 'store/tools/runtimes.sh'
- - 'store/tools/sync-runtimes.mjs'
- - '.github/workflows/home-assistant-checks.yml'
+ workflow_call:
permissions:
contents: read
-# New commits replace obsolete checks for the same PR or branch.
-concurrency:
- group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
- cancel-in-progress: true
-
jobs:
home-assistant-native:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
with:
node-version: '22.23.2'
@@ -38,9 +24,11 @@ jobs:
run: |
bash store/agents/home-assistant/toolchain/setup.sh
node store/agents/home-assistant/node_modules/playwright-core/cli.js install --with-deps chromium
- echo "HA_PYTHON=$GITHUB_WORKSPACE/store/agents/home-assistant/.runtime/core/bin/python" >> "$GITHUB_ENV"
- echo "HA_DSH_DIR=$GITHUB_WORKSPACE/store/agents/home-assistant" >> "$GITHUB_ENV"
- echo "PLAYWRIGHT_MODULE=$GITHUB_WORKSPACE/store/agents/home-assistant/node_modules/playwright-core/index.mjs" >> "$GITHUB_ENV"
+ {
+ echo "HA_PYTHON=$GITHUB_WORKSPACE/store/agents/home-assistant/.runtime/core/bin/python"
+ echo "HA_DSH_DIR=$GITHUB_WORKSPACE/store/agents/home-assistant"
+ echo "PLAYWRIGHT_MODULE=$GITHUB_WORKSPACE/store/agents/home-assistant/node_modules/playwright-core/index.mjs"
+ } >> "$GITHUB_ENV"
- name: Test native timers, fixtures, isolation, drafts and failure preservation
run: node --test store/agents/home-assistant/test/*.test.mjs
- name: Edit, revise, export and reopen distinct automation workflows in Chromium
diff --git a/.github/workflows/website-checks.yml b/.github/workflows/website-checks.yml
index ab74e9a96..d99fe0aaa 100644
--- a/.github/workflows/website-checks.yml
+++ b/.github/workflows/website-checks.yml
@@ -10,22 +10,14 @@ name: Website checks
# bundle harness-web-release.json pins, the same path a local build takes; release-web.yml builds the
# real image from a freshly built bundle instead.
+# Automatic invocations are selected by ci.yml; standalone runs remain available.
on:
workflow_dispatch:
- pull_request:
- paths: ['website/**', '.github/workflows/website-checks.yml']
- push:
- branches: [main]
- paths: ['website/**', '.github/workflows/website-checks.yml']
+ workflow_call:
permissions:
contents: read
-# New commits replace obsolete checks for the same PR or branch.
-concurrency:
- group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
- cancel-in-progress: true
-
jobs:
website:
runs-on: ubuntu-latest
@@ -35,6 +27,8 @@ jobs:
working-directory: website
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
with:
# The major Dockerfile.k8s runs on (node:22-bookworm-slim), at the repo's usual pin.
@@ -62,7 +56,7 @@ jobs:
server_pid=$!
trap 'kill "$server_pid" 2>/dev/null || true' EXIT
ready=false
- for attempt in $(seq 1 30); do
+ for ((attempt=1; attempt<=30; attempt++)); do
if curl --fail --silent http://127.0.0.1:3000/os > /dev/null; then
ready=true
break
diff --git a/AGENTS.md b/AGENTS.md
index 23954154d..ece9cf45e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,18 +25,23 @@ For product names, terminology, and visible copy, follow the
validation cycle. Verify published versions and checksums, then report completion.
Desktop's `--wait` follows the exact tag/SHA through the workflow's six-artifact
verification; reuse that receipt instead of repeating the downloads manually.
-- Prepare the PR and review while checks run. For an authorized merge after review
- and required non-CI checks, use `make merge-pr` with the reviewed head/main SHAs,
- CI run/scope, and `--merge` (see the validation guide). It collects CI evidence,
- rechecks the source, merges, and verifies the resulting tree. For evidence only,
- use `scripts/record-ci-validation.py RUN_ID --scope SCOPE --pr PR_NUMBER --wait`.
- Retain routine results in the ignored receipt and PR body instead of another
- documentation commit. Resolve source differences explicitly before reusing evidence.
- Process and Desktop VM CI can retain the original run across unrelated changes
- when their verified source-input contracts match; pass that run to the same
- collector/merge helper. Check its changed-path list and validate other affected
- scopes separately. Changes to included tests, dependencies or workflows require
- new evidence; see the validation guide for the complete input boundaries.
+- Prepare the PR and complete code/native review while automatic CI runs. For an
+ agent implementation in progress, push to a draft PR: CI runs cheap workflow
+ and process checks. Mark ready after targeted local checks to start complete
+ affected suites, and keep the revision stable while CI and review finish.
+ The integration gate remains blocked on drafts. For an authorized merge, use
+ `make merge-pr` with the reviewed head/base SHAs and
+ `--queue --merge`; it enqueues the exact reviewed head, follows the queue and
+ verifies the merged tree against successful merge-group CI. Main advancing
+ does not invalidate the review base; the queue checks the combined candidate.
+ GitHub approval requirements remain as configured; this does not introduce
+ an additional human approval count. Keep review independent of implementation.
+ Existing `--run/--scope` commands automatically select queue mode when the
+ target's merge-queue rule is enabled; direct mode remains for rollout only.
+ For evidence outside the queue, use `scripts/record-ci-validation.py` and the
+ existing verified Process/Desktop source-input contracts. Other affected
+ native, browser, engine and hardware checks remain explicit review requirements.
+ Never replay an uncertain enqueue/merge mutation; inspect the same PR first.
- For an authorized Desktop release, start `make release-desktop ARGS="--prepare"`
from the final pushed PR branch alongside validation and review. It prepares
verified packages without publishing; merge and release only after checks pass.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7a5738412..33645c624 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -173,12 +173,13 @@ Security reports go through [SECURITY.md](SECURITY.md).
to select checks, bound their runtime, and reuse results. Say exactly what ran and what did not.
3. **Make it reproducible.** Use the PR template to describe the result, how to try it, and the
validation. Remove credentials and private project content from logs and recordings.
-4. **Review together.** A maintainer checks the change and may ask you to refine it. CI is
- currently run manually through **Actions → CI → Run workflow**; a PR does not automatically
- exercise the app, real engines, or hardware. Report those checks separately.
-5. **Merge and release.** PRs are squash-merged. Rebase on the latest `main` when needed to keep
- the diff readable. Harness catalog changes publish automatically after merge. App, CLI, and
- firmware releases have their own schedules.
+4. **Review together.** A maintainer checks the change while automatic CI selects complete
+ component suites from its Git diff. Native, browser, real-engine and hardware acceptance
+ still need the checks relevant to the change; report those separately.
+5. **Merge and release.** Reviewed PRs enter the merge queue, which validates them with current
+ `main` and changes ahead in the queue before squash merging. Rebase to resolve conflicts;
+ ordinary main movement does not require another manual validation/rebase cycle. Harness
+ catalog changes publish after merge; app, CLI and firmware releases keep their schedules.
## Conventions across this repository
diff --git a/cli/src/lib/localModels.spec.ts b/cli/src/lib/localModels.spec.ts
index c78dec1fa..20f297388 100644
--- a/cli/src/lib/localModels.spec.ts
+++ b/cli/src/lib/localModels.spec.ts
@@ -2011,6 +2011,8 @@ describe('Jev models: Get brings Grid\'s llama.cpp up to a build that serves the
})
it('offers none it cannot size, but keeps listing the ones already here, at the quant that is here', async () => {
+ // Sparse weight fixtures declare their disk budget, independent of the developer's free space.
+ vi.mocked(statfs).mockResolvedValue({ bavail: 100 * GiB, bsize: 1 } as Awaited<ReturnType<typeof statfs>>)
await writeFile(join(home, 'models', 'Kev-9B-Q8_0.gguf'), '')
await (await import('node:fs/promises')).truncate(join(home, 'models', 'Kev-9B-Q8_0.gguf'), 9_529_735_648)
await writeFile(join(home, 'models', 'Clef-Q4_K_M.gguf.part'), 'half')
@@ -2040,6 +2042,8 @@ describe('Jev models: Get brings Grid\'s llama.cpp up to a build that serves the
})
it('updates an engine new enough for Jev models but not for Clef, whose architecture came later', async () => {
+ // Sparse weight fixtures declare their disk budget, independent of the developer's free space.
+ vi.mocked(statfs).mockResolvedValue({ bavail: 100 * GiB, bsize: 1 } as Awaited<ReturnType<typeof statfs>>)
await engine('0.5.0-dev (build 11365, commit 1a2b3c4d5)')
const models = jevService({}, {}, { ...card10, usable_bytes: 48 * GiB })
await models.act('home', LAYA, 'start'); await models.settled()
diff --git a/desktop/test/device_viewer_notices_test.dart b/desktop/test/device_viewer_notices_test.dart
index b8d43f15b..48fef5346 100644
--- a/desktop/test/device_viewer_notices_test.dart
+++ b/desktop/test/device_viewer_notices_test.dart
@@ -341,15 +341,16 @@ void main() {
test('signing in by hand as another account starts that account\'s list over', () async {
// Account A: this browser joined its log.
await backend.add(box2, 'machine', 'b' * 32, 'box2');
- await openAs(backend, 'user-a', byHand: true);
+ await openAs(backend, backend.acct, byHand: true);
final me = b64e((await keys.identity()).pub);
expect(backend.state.active[me]?.kind, 'viewer');
// Signed in as B in the same browser, by hand: B's log is another account's, and this sign-in is
- // new — a new list, not a backend that lies. The profile is not waited for.
+ // new — a new list, not a backend that lies. A fresh sign-in's profile names the same account
+ // as its signed log; restored-session profile mismatches are exercised below.
final other = _Backend('acct-2');
await other.add(phone, 'viewer', '', 'Phone');
- final b = await openAs(other, 'user-b', byHand: true);
+ final b = await openAs(other, other.acct, byHand: true);
final listing = await logOf(b).list();
expect(
listing.frozen,
@@ -366,7 +367,7 @@ void main() {
test('a restored session whose /me id differs does not reset the list', () async {
await backend.add(box2, 'machine', 'b' * 32, 'box2');
- await openAs(backend, 'user-a', byHand: true);
+ await openAs(backend, backend.acct, byHand: true);
await backend.add(phone, 'viewer', '', 'Phone');
final first = await openAs(backend, 'user-a');
expect(first.newDevices.map((d) => d.label), ['Phone']);
@@ -956,7 +957,7 @@ void main() {
test('the sign-in is known to the log before the boot reads anything else (a pane restore reads it first)', () async {
// Account A: this browser joined its log by hand.
await backend.add(box2, 'machine', 'b' * 32, 'box2');
- await openAs(backend, 'user-a', byHand: true);
+ await openAs(backend, backend.acct, byHand: true);
final me = b64e((await keys.identity()).pub);
// A's sign-in is long past: only a sign-in made just now may start another account's list.
const old = 'a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0@1000';
diff --git a/desktop/test/e2ee/encrypted_down_types_test.dart b/desktop/test/e2ee/encrypted_down_types_test.dart
index d94353db5..79ff2e323 100644
--- a/desktop/test/e2ee/encrypted_down_types_test.dart
+++ b/desktop/test/e2ee/encrypted_down_types_test.dart
@@ -24,44 +24,45 @@ void main() {
return file.readAsStringSync();
}
- /// The quoted names in the set literal that follows [start], `//` comments stripped first — the
- /// CLI's comments quote type names too.
- Set<String> namesIn(String source, String start) {
- final from = source.indexOf(start);
- if (from < 0) throw StateError('could not find $start');
- final body = source.substring(from, source.indexOf('])', from));
- final code = body
+ /// Quoted names in a declared set/array literal, including typed declarations.
+ /// Comments also quote frame names, so exclude them from the contract.
+ Set<String> namesIn(String source, String name) {
+ final code = source
.split('\n')
.map((line) => line.split('//').first)
.join('\n');
+ final declaration = RegExp(
+ r'\b' +
+ RegExp.escape(name) +
+ r'(?:\s*:[^=]+)?\s*=\s*(?:new Set(?:<[^>]+>)?\(\s*)?\[([\s\S]*?)\]',
+ ).firstMatch(code);
+ if (declaration == null) throw StateError('could not find $name literal');
return {
- for (final match in RegExp(r"'([a-z0-9_]+)'").allMatches(code)) match[1]!,
+ for (final match in RegExp(r"'([a-z0-9_]+)'").allMatches(declaration[1]!))
+ match[1]!,
};
}
late Set<String> core, machineRequests, unwrapped;
setUpAll(() {
- core = namesIn(
- cli('lib/e2ee/core.ts'),
- 'ENCRYPTED_DOWN_TYPES = new Set<string>([',
- );
+ core = namesIn(cli('lib/e2ee/core.ts'), 'ENCRYPTED_DOWN_TYPES');
final frames = cli('lib/e2ee/applicationFrames.ts');
final relay = cli('lib/relayFrames.ts');
// `MACHINE_REQUESTS` also spreads the owner commands in; those are read where they are declared.
machineRequests = {
- ...namesIn(frames, 'MACHINE_REQUESTS = new Set(['),
- ...namesIn(relay, 'OWNER_COMMAND_TYPES = new Set(['),
- // ...which spread the route commands in from their own set.
- ...namesIn(relay, 'ROUTE_COMMAND_TYPES: ReadonlySet<string> = new Set(['),
+ ...namesIn(frames, 'MACHINE_REQUESTS'),
+ ...namesIn(cli('lib/shellProtocol.ts'), 'SHELL_REQUESTS'),
+ ...namesIn(relay, 'OWNER_COMMAND_TYPES'),
+ ...namesIn(relay, 'ROUTE_COMMAND_TYPES'),
};
unwrapped = {
...core,
...machineRequests,
- ...namesIn(frames, 'FLEET_REQUESTS = new Set(['),
- ...namesIn(relay, 'PAIR_REQUESTS = new Set(['),
- ...namesIn(cli('sharing/protocol.ts'), 'SHARE_REQUEST_TYPES = new Set(['),
- ...namesIn(cli('teams/wire.ts'), 'TEAM_REQUEST_TYPES = new Set(['),
- ...namesIn(cli('lib/viewerFrames.ts'), 'VIEWER_DOWN_TYPES = new Set(['),
+ ...namesIn(frames, 'FLEET_REQUESTS'),
+ ...namesIn(relay, 'PAIR_REQUESTS'),
+ ...namesIn(cli('sharing/protocol.ts'), 'SHARE_REQUEST_TYPES'),
+ ...namesIn(cli('teams/wire.ts'), 'TEAM_REQUEST_TYPES'),
+ ...namesIn(cli('lib/viewerFrames.ts'), 'VIEWER_DOWN_TYPES'),
};
});
diff --git a/desktop/test/local_cli_discovery_test.dart b/desktop/test/local_cli_discovery_test.dart
index 92be014ee..4aa4380d7 100644
--- a/desktop/test/local_cli_discovery_test.dart
+++ b/desktop/test/local_cli_discovery_test.dart
@@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:convert';
import 'dart:io';
+import 'package:fake_async/fake_async.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/config.dart';
import 'package:harness/core/harness_cli_runner.dart';
@@ -764,48 +765,72 @@ void main() {
},
);
- test('startSupervising waits for more than one quiet tick before spawning into an update gap', () async {
- const computerId = '0123456789abcdef0123456789abcdef';
- final identityFile = File('${scratch.path}/computer-id')
- ..writeAsStringSync(computerId);
- // The port goes quiet — the old daemon closed it, the new one is about to bind — then answers
- // again. That is a handoff, not a crash, and must not cost a spawn. `spawnAfter: 3` against a
- // gap of ~1.5 ticks: however the gap lands on the tick phase, at most two ticks can see it.
- final port = await freePort();
- server = await serveStatus(port, () => readyStatus(computerId));
- var spawnCount = 0;
- final discovery = discoveryFor(
- port,
- identityFile,
- spawnCommand: () async {
- spawnCount++;
- },
- );
-
- final timer = discovery.startSupervising(
- checkInterval: const Duration(milliseconds: 20),
- graceStep: const Duration(milliseconds: 10),
- graceWindow: const Duration(milliseconds: 50),
- initialBackoff: const Duration(milliseconds: 20),
- maxBackoff: const Duration(milliseconds: 20),
- spawnAfter: 3,
- stillSignedIn: () async => true,
- );
- addTearDown(timer.cancel);
-
- await Future.delayed(const Duration(milliseconds: 60));
- await server!.close(force: true);
- server = null;
- await Future.delayed(const Duration(milliseconds: 30)); // the gap
- server = await serveStatus(port, () => readyStatus(computerId));
- await Future.delayed(const Duration(milliseconds: 150));
- expect(spawnCount, 0, reason: 'a short gap is a handoff, not a crash');
-
- // Quiet for good: now it is down, and the spawn is the fix.
- await server!.close(force: true);
- server = null;
- await Future.delayed(const Duration(milliseconds: 250));
- expect(spawnCount, greaterThan(0));
+ test('startSupervising waits for more than one quiet tick before spawning into an update gap', () {
+ fakeAsync((clock) {
+ final ready = LocalCliProbe.ready(
+ LocalCliEndpoint(
+ computerId: '0123456789abcdef0123456789abcdef',
+ wsUri: Uri.parse('ws://127.0.0.1/api/local-ws'),
+ protocolVersion: localWsProtocolVersion,
+ terminalProtocolVersion: localTerminalProtocolVersion,
+ ),
+ );
+ const down = LocalCliProbe.down('handoff gap');
+ var seen = ready;
+ var spawnCount = 0;
+ final discovery = _SupervisionProbe(
+ readProbe: () async => seen,
+ spawnCommand: () async {
+ spawnCount++;
+ },
+ );
+ const interval = Duration(milliseconds: 20);
+ final timer = discovery.startSupervising(
+ checkInterval: interval,
+ // This fixture tests consecutive probes, not grace/backoff durations.
+ graceWindow: Duration.zero,
+ initialBackoff: Duration.zero,
+ maxBackoff: Duration.zero,
+ spawnAfter: 3,
+ stillSignedIn: () async => true,
+ );
+ void tick() {
+ clock.elapse(interval);
+ clock.flushMicrotasks();
+ }
+
+ try {
+ tick();
+ // Real socket/timer delays can stretch a nominal 30 ms gap on busy
+ // runners. Specify the observations: two quiet ticks, then recovery.
+ seen = down;
+ tick();
+ tick();
+ expect(spawnCount, 0, reason: 'a short gap is a handoff, not a crash');
+ seen = ready;
+ tick();
+ expect(spawnCount, 0);
+
+ // Recovery must reset the count. Only three NEW consecutive quiet
+ // probes may start a replacement daemon.
+ seen = down;
+ tick();
+ tick();
+ expect(
+ spawnCount,
+ 0,
+ reason: 'quiet ticks before recovery do not accumulate',
+ );
+ tick();
+ expect(
+ spawnCount,
+ 1,
+ reason: 'confirmed failure starts one replacement',
+ );
+ } finally {
+ timer.cancel();
+ }
+ });
});
test('startSupervising backs off between failed spawn attempts instead of spawning every tick', () async {
@@ -1040,3 +1065,16 @@ void main() {
expect(signedOutCalls, 1, reason: 'a late answer is still told');
});
}
+
+/// Control probe results while exercising the real supervisor and its timers.
+class _SupervisionProbe extends LocalCliDiscovery {
+ _SupervisionProbe({
+ required this.readProbe,
+ required Future<void> Function() spawnCommand,
+ }) : super(config: AppConfig.dev, spawnCommand: spawnCommand);
+
+ final Future<LocalCliProbe> Function() readProbe;
+
+ @override
+ Future<LocalCliProbe> probe({String? expectedComputerId}) => readProbe();
+}
diff --git a/devices/harness-device/firmware/test/test_cable_identity.py b/devices/harness-device/firmware/test/test_cable_identity.py
index cae10d8e5..14b61d5e0 100644
--- a/devices/harness-device/firmware/test/test_cable_identity.py
+++ b/devices/harness-device/firmware/test/test_cable_identity.py
@@ -20,6 +20,7 @@ def function(name):
code = r'''
+#define _POSIX_C_SOURCE 200809L
#include <limits.h>
enum { native_name_max = NAME_MAX };
#include "cable_client.h"
diff --git a/devices/harness-device/firmware/test/test_character_preferences.py b/devices/harness-device/firmware/test/test_character_preferences.py
index 77c6d5ce2..666ece77c 100644
--- a/devices/harness-device/firmware/test/test_character_preferences.py
+++ b/devices/harness-device/firmware/test/test_character_preferences.py
@@ -119,7 +119,7 @@ with tempfile.TemporaryDirectory(prefix='harness-character-pref-') as directory:
sources = ['character.c', 'illustrated.c', 'character_motion.c', 'character_layout.c', 'tux.c', 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c',
'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c']
for flags in ([], ['-DDEVICE_DEFAULT_CHARACTER_TUX=1']):
- subprocess.run(['cc', '-std=c11', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
+ subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'), *flags,
'-I', str(native), str(out / 'test.c'), *(str(native / f) for f in sources),
'-o', str(out / 'test')], check=True)
diff --git a/devices/harness-device/firmware/test/test_companions.py b/devices/harness-device/firmware/test/test_companions.py
index 20f3d5510..a598cc719 100644
--- a/devices/harness-device/firmware/test/test_companions.py
+++ b/devices/harness-device/firmware/test/test_companions.py
@@ -21,7 +21,7 @@ _binary_companion_art_pack_end:
sources = ['character.c', 'illustrated.c', 'illustrated_cache.c', 'character_motion.c',
'character_layout.c', 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'tux.c',
'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c', 'terminal.c', 'fonts.c']
- subprocess.run(['cc', '-std=c11', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
+ subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'), '-I', str(NATIVE),
str(HERE / 'test_companions.c'), *(str(NATIVE / name) for name in sources),
str(out / 'pack.S'), '-lz', '-o', str(out / 'test')], check=True)
diff --git a/devices/harness-device/firmware/test/test_device_settings.py b/devices/harness-device/firmware/test/test_device_settings.py
index 4e8efd882..7a213359e 100644
--- a/devices/harness-device/firmware/test/test_device_settings.py
+++ b/devices/harness-device/firmware/test/test_device_settings.py
@@ -245,7 +245,7 @@ with tempfile.TemporaryDirectory(prefix='harness-device-settings-') as directory
(out / 'test.c').write_text(code)
sources = ['character.c', 'illustrated.c', 'character_motion.c', 'character_layout.c', 'tux.c', 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c',
'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c']
- subprocess.run(['cc', '-std=c11', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
+ subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'),
'-I', str(native), str(out / 'test.c'), *(str(native / f) for f in sources),
'-o', str(out / 'test')], check=True)
diff --git a/devices/harness-device/firmware/test/test_draft_ui.py b/devices/harness-device/firmware/test/test_draft_ui.py
index 3530f2aec..a55be93a7 100644
--- a/devices/harness-device/firmware/test/test_draft_ui.py
+++ b/devices/harness-device/firmware/test/test_draft_ui.py
@@ -98,6 +98,6 @@ int main(void){
'''
with tempfile.TemporaryDirectory(prefix='harness-draft-ui-') as d:
root=Path(d);(root/'test.c').write_text(code)
- subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-O1','-g','-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),
+ subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g','-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),
'-I',str(native),str(root/'test.c'),str(native/'draft.c'),str(native/'carry.c'),str(native/'terminal.c'),str(native/'fonts.c'),'-o',str(root/'test')],check=True)
subprocess.run([str(root/'test')],check=True)
diff --git a/devices/harness-device/firmware/test/test_fw_update.py b/devices/harness-device/firmware/test/test_fw_update.py
index f01655df1..decd9ff55 100644
--- a/devices/harness-device/firmware/test/test_fw_update.py
+++ b/devices/harness-device/firmware/test/test_fw_update.py
@@ -196,7 +196,7 @@ int main(void) {
with tempfile.TemporaryDirectory(prefix='harness-ota-') as d:
out = Path(d)
(out / 'ota.c').write_text(code)
- subprocess.run(['cc', '-std=c11', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
+ subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize='+os.environ.get('SANITIZERS', 'undefined,bounds'),
str(out/'ota.c'), '-o', str(out/'ota')], check=True)
subprocess.run([str(out/'ota')], check=True)
diff --git a/devices/harness-device/firmware/test/test_layout_bench.py b/devices/harness-device/firmware/test/test_layout_bench.py
index 3ffe0c22b..cb28c6d96 100644
--- a/devices/harness-device/firmware/test/test_layout_bench.py
+++ b/devices/harness-device/firmware/test/test_layout_bench.py
@@ -75,7 +75,7 @@ with tempfile.TemporaryDirectory(prefix='harness-layout-bench-') as d:
defines=[f'-DDEVICE_LAYOUT_BASELINE{baseline}=1'] if baseline!=48 else []
sources=[f'reference{baseline}/terminal_ref.c'] if baseline!=82 else []
if baseline==48: sources+=['reference48/octopus_ref.c']
- subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-O1','-g','-DDEVICE_LAYOUT_BENCH=1',*defines,
+ subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g','-DDEVICE_LAYOUT_BENCH=1',*defines,
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),'-I',str(native),'-I',str(Path(__file__).resolve().parent),
str(out/'bench.c'),*[str(native/f) for f in ['octopus.c','ascii_clip.c','octopus_font.c','tim.c','character_motion.c','character_layout.c','terminal.c','fonts.c']],
*[str(Path(__file__).resolve().parent/f) for f in sources],
diff --git a/devices/harness-device/firmware/test/test_machine_ui.py b/devices/harness-device/firmware/test/test_machine_ui.py
index d3e9f065f..8d69c9ec3 100644
--- a/devices/harness-device/firmware/test/test_machine_ui.py
+++ b/devices/harness-device/firmware/test/test_machine_ui.py
@@ -94,7 +94,7 @@ int main(void) {
with tempfile.TemporaryDirectory(prefix='harness-machine-ui-') as folder:
folder = Path(folder)
(folder/'machine.c').write_text(code)
- subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-O1','-g',
+ subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g',
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),str(folder/'machine.c'),
'-o',str(folder/'machine')],check=True)
subprocess.run([str(folder/'machine')],check=True)
diff --git a/devices/harness-device/firmware/test/test_question_ui.py b/devices/harness-device/firmware/test/test_question_ui.py
index 2cf898b8c..e06d1d2ec 100644
--- a/devices/harness-device/firmware/test/test_question_ui.py
+++ b/devices/harness-device/firmware/test/test_question_ui.py
@@ -270,7 +270,7 @@ int main(int argc,char **argv) {
'''
with tempfile.TemporaryDirectory(prefix='harness-question-ui-') as tmp:
out=Path(tmp);(out/'question_ui.c').write_text(code)
- subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-O1','-g',
+ subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g',
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),'-I',str(native),
str(out/'question_ui.c'),str(native/'terminal.c'),str(native/'fonts.c'),'-o',str(out/'test')],check=True)
args=[str(out/'test')]
diff --git a/devices/harness-device/firmware/test/test_touch_ui.py b/devices/harness-device/firmware/test/test_touch_ui.py
index 5e336e9be..211fa7772 100644
--- a/devices/harness-device/firmware/test/test_touch_ui.py
+++ b/devices/harness-device/firmware/test/test_touch_ui.py
@@ -2784,7 +2784,7 @@ if os.environ.get('HABITAT_BRIDGE_TRACE'):
with tempfile.TemporaryDirectory(prefix='harness-touch-ui-') as d:
out = Path(d)
(out / 'touch_ui.c').write_text(code)
- subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-O1','-g',
+ subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g',
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),
*extra_includes, '-I',str(native),str(out/'touch_ui.c'), *extra_sources, str(native/'gestures.c'),
str(native/'form.c'),str(native/'visit.c'),str(native/'draft.c'), str(native/'scroll.c'),str(native/'selection.c'),str(native/'carry.c'),str(native/'tim.c'),str(native/'character_motion.c'),str(native/'character_layout.c'),str(native/'character.c'),str(native/'illustrated.c'),str(native/'tux.c'),str(native/'focus.c'),str(native/'lvgl_fonts.c'),str(native/'lvgl_icons.c'),str(native/'focus_marks.c'),str(native/'focus_faces.c'),str(native/'pets.c'),str(native/'terminal.c'),
diff --git a/devices/harness-device/firmware/test/test_voice_ui.py b/devices/harness-device/firmware/test/test_voice_ui.py
index 31e766e5e..331dda286 100644
--- a/devices/harness-device/firmware/test/test_voice_ui.py
+++ b/devices/harness-device/firmware/test/test_voice_ui.py
@@ -292,7 +292,7 @@ int main(void) {
with tempfile.TemporaryDirectory(prefix='harness-voice-ui-') as directory:
root = Path(directory)
(root / 'voice_ui.c').write_text(harness)
- subprocess.run(['cc', '-std=c11', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
+ subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'),
'-I', str(native), str(root / 'voice_ui.c'), str(native / 'selection.c'), str(native / 'carry.c'), str(native / 'visit.c'), str(native / 'form.c'), str(native / 'draft.c'), str(native / 'workspace.c'),
'-o', str(root / 'voice_ui')], check=True)
diff --git a/docs/validation-and-release.md b/docs/validation-and-release.md
index c594f92a2..1e888ce6d 100644
--- a/docs/validation-and-release.md
+++ b/docs/validation-and-release.md
@@ -31,7 +31,7 @@ bundle checks, the serial/login-shell OS/Node matrix, and the per-file 100% cove
gates (`test:core`, `test:harnessd`, `test:resume`, `test:orchestrator`, `test:sharing`,
`test:remote-viewers`, `test:portability`). `tui` includes its native
CLI integration tests. Select `full` for cross-component changes or uncertain impact.
-The workflow remains on demand; this change does not introduce new required gates.
+Automatic PR and merge-group runs select all affected component scopes; manual scopes remain available.
`desktop` runs all Desktop VM files on both macOS and Linux, split into four
isolated runners per platform. It uses the release's pinned Flutter SDK and shared
@@ -417,103 +417,112 @@ until they disappear.
## Merge an already-reviewed PR
-Once code review and required non-CI checks are complete and merging is authorized,
-start this command while the selected CI run is still running:
+After independent code review, required non-CI acceptance and merge authorization:
```bash
-make merge-pr ARGS="PR_NUMBER --run RUN_ID --scope SCOPE --reviewed-head HEAD_SHA --reviewed-base MAIN_SHA --merge"
+make merge-pr ARGS="PR_NUMBER --queue --reviewed-head HEAD_SHA --reviewed-base REVIEW_BASE_SHA --merge --wait-timeout 1800"
```
-Use full commit SHAs. The clean local checkout must be the reviewed head and include
-that reviewed `main` commit. Prepare the PR description with its check scope and CI
-run link first. The command waits for that attempt, verifies the same jobs/artifacts
-as the evidence collector, then rechecks the PR and the live `main` ref before one
-squash-merge request. GitHub must report the PR ready; the request includes the exact
-reviewed head and does not bypass branch rules or enable auto-merge/queueing.
-
-Omit `--merge` for a read-only preview. Logs, CI evidence, per-phase timings and the
-merge outcome are saved under `.harness/validation/*-merge-*/`. `--wait-timeout`
-defaults to 900s; `--timeout` gives preflight and post-CI operations 90s each. The
-command records its intended mutation before sending it. If a response is lost, it
-inspects the same PR without replaying the merge request.
-
-A changed head, dirty checkout, moved main, failed CI or blocked merge stops the
-command. Review new source differences and reuse only applicable evidence, as above;
-the command does not decide that impact or replace native checks and code review.
-After a merge, it verifies the actual Git tree against the reviewed target tree.
-The receipt separately reports whether the full tested tree matches; scoped CI
-reuse may preserve test inputs while other reviewed files differ. A merge tree
-different from the reviewed target is recorded as `merged_source_review_required`
-(exit 3), so resolve that source review before release. An unconfirmed write is
-recorded as `merge_not_confirmed`; inspect the same PR before further action. This
-command does not create release tags or dispatch release workflows.
-
-## Complete the authorized release
-
-Once required checks pass, merge, verify the resulting source, and tag that source
-using the existing release scripts. Do not introduce an additional full-suite phase.
-For a client/server change, publish required server support before exposing clients
-that need it. Independent product releases may build concurrently; preserve their
-source/version compatibility and manifest publication safeguards.
-
-Check the live version and artifact checksum, and give the user the release link
-promptly. Broader maintenance testing must not silently turn into another release
-gate after shipping. Record these UTC timestamps in the PR or release task:
-
-- Request received; implementation ready; required validation started/completed.
-- Merge; each product's release trigger and live publication; completion reported.
-- Pauses and waiting, with their known reason. Mark missing data unknown.
-
-For Desktop, use the existing release command with `--wait` to follow the exact
-tag and source through completion:
-
-```bash
-make release-desktop ARGS="--notes-file /path/to/reviewed-notes.md --wait"
-```
-
-The workflow's `publish` job downloads all six public artifacts three at a time,
-using the updater's Dart user agent, and checks every version, full SHA-256, and
-size. It starts immediately after publication on the same runner.
-Each transfer has a total deadline; any failure makes the workflow fail and keeps
-the JSON receipt in the `desktop-release-verification` artifact. A successful
-verification satisfies that release's download checks: report completion instead
-of downloading everything again locally. The watcher requires this job to pass
-and checks the tag's full SHA, so another release's success cannot satisfy it.
-
-Different Desktop versions may build concurrently. The shared release lock covers
-publication and its public verification, so a second workflow cannot change the
-live version midway through that check. Versions are checked before building and
-again immediately before publication. A late older version fails as superseded;
-do not retry it over a newer live release. All four platform manifests must contain
-exactly the six expected entries for one version. Artifact writes are create-only,
-and the final manifest write requires the GCS generation read by the publisher.
-Concurrent external changes therefore cause a failure instead of being lost.
-
-For publication changes, run the local process suite and the disposable GCS
-contract check on the candidate branch:
-
-```bash
-gh workflow run release-desktop.yml --ref BRANCH -f version=0.0.0 -f test_publication=true
+The checkout must be clean at the exact reviewed head and include the review-base
+commit. Main may advance after that review. The helper verifies successful automatic
+PR CI, enqueues with GitHub's `expectedHeadOid`, follows the same PR and verifies
+that its merged full tree matches successful `merge_group` CI and its immutable gate
+receipt. It retains source, run, attempt, artifact digest and phase timings under
+`.harness/validation/*-merge-*/`. Omit `--merge` for a read-only queue preview.
+
+Queue rejection, a changed head/target, missing coverage, failed/skipped required
+jobs or a lost response cannot report success. An uncertain enqueue is inspected
+without replaying the mutation. If the wait budget expires, follow that same queued
+PR; do not start another validation or merge request. GitHub enforces the required
+check and queue after rollout. Existing `--run/--scope` commands automatically use
+queue mode when the branch has that rule; legacy direct mode is retained for the
+bootstrap merge only and requires unchanged reviewed main.
+
+## Automatic CI and rollout
+
+`ci.yml` runs on every PR revision and on `merge_group: checks_requested`.
+`scripts/ci-plan.py` reads the complete immutable Git diff, including both sides
+of renames, rather than GitHub's limited file list. PR runs check out the exact
+head; queue runs check out the combined candidate. Unknown paths fail planning
+until their checks are registered. CI uses read-only repository permissions and
+executes no contributor code with release credentials.
+
+Agents should open a draft PR while implementing and run targeted local checks
+before marking it ready. Draft pushes run workflow lint and repository process
+checks; expensive component suites wait for `ready_for_review`. The plan still
+records all affected suites, and `ci/required` stays blocked while the PR is a
+draft. Marking ready runs complete affected validation for that exact head;
+returning to draft defers component checks on later pushes. Keep a ready PR stable while CI and
+independent review finish. Push again when a correction is needed, rather than
+repeatedly dispatching the same full suite. Merge candidates and explicit runs
+always execute their complete selected scopes.
+
+Coarse component selection retains the existing complete CLI coverage/native
+matrix and Desktop inventory on both platforms. Shared CLI and process/workflow
+inputs conservatively select all core suites; source boundaries are not narrowed
+as part of rollout. CLI changes also select Mobile's protocol contracts; changes to
+the shared planner or CI job graph select every component. Website, Store
+experiences/browser, logging, OS source contracts,
+provider, firmware host tests, Mobile VM tests and daemon contracts are selected
+for their declared inputs. Physical devices, full OS images/VM journeys, real engines,
+visual inspection and other acceptance selected by review remain separate required
+validation; automatic host tests do not substitute for those.
+
+The dependency map determines test coverage, not workflow cancellation groups:
+
+```mermaid
+flowchart LR
+ CLI[CLI protocols and runtime APIs] --> Desktop[Desktop contracts]
+ CLI --> Phone[Mobile protocol contracts]
+ CLI --> Companions[Companion cross-imports]
+ CLI --> TUI[TUI protocol and daemon integration]
+ Fixtures[Shared desk and daemon fixtures] --> Core[Core and Mobile checks]
+ Store[Store runtimes and viewers] --> Desktop
+ Store --> Browser[Experience and authoring browser checks]
+ Planner[Shared CI planner and job graph] --> All[Every component]
```
-This mode skips all product build/release jobs. It uses tiny public fixture objects
-under `harness/desktop/.publication-check/<run>-<attempt>/`, checks actual GCS
-preconditions and downloads, and removes only that run's prefix. It exercises
-normal publication, duplicate/older versions, incomplete platform sets, concurrent
-manifest writes, and immutable artifact collisions. It cannot publish an app.
-
-For a release made before that job existed, or to investigate a download failure:
-
-```bash
-python3 scripts/verify-desktop-release.py 1.2.51
-```
-
-This is read-only. A failed verification after publication means the release may
-already be live; inspect the receipt and fix the cause rather than blindly
-retagging or retrying immutable artifact uploads.
-
-Report both total elapsed time and its stages. For small changes, aim to return to
-the team's previous 10–15 minute merge/release overhead; publishing duration alone
-does not demonstrate that target. At ten minutes without progress, identify the
-blocked phase and its next action instead of silently extending testing. Compare
-the next ten tasks using request-to-completion data before claiming an improvement.
+Separate PR groups prevent cross-cancellation, but still share available runner
+capacity. Related branches validate independently; the merge queue validates
+their combined source before integration. Keep PRs small and coordinate edits to
+shared interfaces and frequently changed files. Main background validation may
+coalesce pending snapshots; distinct merge candidates must not share that group.
+
+The stable `ci/required` job runs even after an upstream failure. It accepts only
+successful selected jobs and complete shard summaries. Deliberately inapplicable
+jobs may be skipped; a required skip, cancellation, failure or missing result fails
+integration. Manual `full` retains its prior core-suite meaning; `all` selects every
+automatic suite. Manual dispatch is extra evidence and cannot substitute for the
+automatic PR/merge-group gate.
+
+Enable main's queue only after passing automatic CI and a disposable-branch queue
+trial. Start with three candidate builds, squash, ALLGREEN, a minimum of one PR and
+no batch accumulation delay. Check timeout is 60 minutes to permit required slower
+component work. Required checks are non-strict on the PR branch because the queue
+validates current main. Require PRs and resolved discussions, preserving the existing
+approval count instead of inventing a new human-review bottleneck. Preserve main's
+delete/force-push guards. Queue jumping invalidates work and is reserved for urgent
+integration. The queue's merge limits do not batch its CI builds.
+
+New revisions replace active checks for the same PR, job and matrix row. Cancellation
+locks belong to work jobs, leaving summaries and the always-running final gate independent: an obsolete
+gate waiting for a runner cannot block the next revision. Checks no longer selected
+by the new plan may finish, including when a ready PR returns to draft; they cannot
+validate a newer head. Explicit runs and distinct candidates have independent
+concurrency identities. Broad main E2E
+finishes its active snapshot and retains the newest pending snapshot; nightly and
+explicit E2E requests are separate and preserved. A passing older snapshot does
+not validate newer source. Broad E2E remains advisory until reliable, and missing
+required acceptance still prevents an authorized release.
+
+Hourly **CI health** retains a bounded latest-100-run workload sample, execution
+observed in cancelled runs and the age/source of completed main E2E. These are job
+timestamps, not billed cost or a guarantee that current main passed. Use a week of
+traffic to tune candidate concurrency from runner waiting, rebuilds and ready-to-merge
+time. Investigate/revert confirmed main regressions promptly. Preserve explicit retry
+and incomplete-suite reporting; do not retry assertions until they disappear.
+
+Release publication and Desktop prepared-package reuse retain their existing
+source/evidence, signing and artifact contracts. Release admission based on automatic
+candidate receipts is a subsequent rollout step after the queue is stable; no release
+workflow is bypassed by this integration change.
diff --git a/mobile/test/encrypted_down_types_test.dart b/mobile/test/encrypted_down_types_test.dart
index a7aa0606c..fb7b2abae 100644
--- a/mobile/test/encrypted_down_types_test.dart
+++ b/mobile/test/encrypted_down_types_test.dart
@@ -23,18 +23,22 @@ void main() {
return file.readAsStringSync();
}
- /// The quoted names in the set literal that follows [start], `//` comments stripped first — the
- /// CLI's comments quote type names too.
- Set<String> namesIn(String source, String start) {
- final from = source.indexOf(start);
- if (from < 0) throw StateError('could not find $start');
- final body = source.substring(from, source.indexOf('])', from));
- final code = body
+ /// Quoted names in a declared set/array literal, including typed declarations.
+ /// Comments also quote frame names, so exclude them from the contract.
+ Set<String> namesIn(String source, String name) {
+ final code = source
.split('\n')
.map((line) => line.split('//').first)
.join('\n');
+ final declaration = RegExp(
+ r'\b' +
+ RegExp.escape(name) +
+ r'(?:\s*:[^=]+)?\s*=\s*(?:new Set(?:<[^>]+>)?\(\s*)?\[([\s\S]*?)\]',
+ ).firstMatch(code);
+ if (declaration == null) throw StateError('could not find $name literal');
return {
- for (final match in RegExp(r"'([a-z0-9_]+)'").allMatches(code)) match[1]!,
+ for (final match in RegExp(r"'([a-z0-9_]+)'").allMatches(declaration[1]!))
+ match[1]!,
};
}
@@ -46,29 +50,24 @@ void main() {
late Set<String> core, machineRequests, pairRequests, unwrapped;
setUpAll(() {
- core = namesIn(
- cli('lib/e2ee/core.ts'),
- 'ENCRYPTED_DOWN_TYPES = new Set<string>([',
- );
+ core = namesIn(cli('lib/e2ee/core.ts'), 'ENCRYPTED_DOWN_TYPES');
final frames = cli('lib/e2ee/applicationFrames.ts');
final relay = cli('lib/relayFrames.ts');
- // `MACHINE_REQUESTS` also spreads the owner commands in; those are read where they are declared,
- // as are the pair frames.
machineRequests = {
- ...namesIn(frames, 'MACHINE_REQUESTS = new Set(['),
- ...namesIn(relay, 'OWNER_COMMAND_TYPES = new Set(['),
- // ...which spread the route commands in from their own set.
- ...namesIn(relay, 'ROUTE_COMMAND_TYPES: ReadonlySet<string> = new Set(['),
+ ...namesIn(frames, 'MACHINE_REQUESTS'),
+ ...namesIn(cli('lib/shellProtocol.ts'), 'SHELL_REQUESTS'),
+ ...namesIn(relay, 'OWNER_COMMAND_TYPES'),
+ ...namesIn(relay, 'ROUTE_COMMAND_TYPES'),
};
- pairRequests = namesIn(relay, 'PAIR_REQUESTS = new Set([');
+ pairRequests = namesIn(relay, 'PAIR_REQUESTS');
unwrapped = {
...pairRequests,
...core,
...machineRequests,
- ...namesIn(frames, 'FLEET_REQUESTS = new Set(['),
- ...namesIn(cli('sharing/protocol.ts'), 'SHARE_REQUEST_TYPES = new Set(['),
- ...namesIn(cli('teams/wire.ts'), 'TEAM_REQUEST_TYPES = new Set(['),
- ...namesIn(cli('lib/viewerFrames.ts'), 'VIEWER_DOWN_TYPES = new Set(['),
+ ...namesIn(frames, 'FLEET_REQUESTS'),
+ ...namesIn(cli('sharing/protocol.ts'), 'SHARE_REQUEST_TYPES'),
+ ...namesIn(cli('teams/wire.ts'), 'TEAM_REQUEST_TYPES'),
+ ...namesIn(cli('lib/viewerFrames.ts'), 'VIEWER_DOWN_TYPES'),
};
});
diff --git a/scripts/ci-health.py b/scripts/ci-health.py
new file mode 100644
index 000000000..9a29ccc3b
--- /dev/null
+++ b/scripts/ci-health.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Publish bounded, read-only CI workload and freshness measurements."""
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import subprocess
+import time
+
+
+def api(path):
+ repository = os.environ["GITHUB_REPOSITORY"]
+ # These are read-only GETs. A transient API failure must not discard the
+ # entire workload report; retry within the workflow's bounded deadline.
+ for attempt in range(3):
+ try:
+ result = subprocess.run(["gh", "api", f"repos/{repository}/{path}"], check=True,
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=30, text=True)
+ return json.loads(result.stdout)
+ except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+ if attempt == 2:
+ raise
+ time.sleep(2 ** attempt)
+
+
+def stamp(value):
+ return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def main():
+ now = datetime.now(timezone.utc)
+ runs = api("actions/runs?per_page=100")["workflow_runs"]
+ measured = [r for r in runs if r["path"] in {".github/workflows/ci.yml", ".github/workflows/cli-e2e.yml"}]
+ cancelled = [r for r in measured if r["conclusion"] == "cancelled"]
+
+ def cancelled_work(run):
+ data = api(f"actions/runs/{run['id']}/jobs?per_page=100")
+ if data["total_count"] > len(data["jobs"]):
+ raise ValueError("job inventory exceeds health-report bound; extend pagination")
+ minutes = sum(max(0, (stamp(j["completed_at"]) - stamp(j["started_at"])).total_seconds()) / 60
+ for j in data["jobs"] if j.get("started_at") and j.get("completed_at") and j["conclusion"] != "skipped")
+ return dict(run_id=run["id"], event=run["event"], branch=run["head_branch"], observed_job_minutes=round(minutes, 2))
+
+ with ThreadPoolExecutor(max_workers=4) as pool:
+ work = list(pool.map(cancelled_work, cancelled))
+ # Search main successes independently: heavy traffic can push the last
+ # passing broad validation out of the 100-run overall sample.
+ passed = api("actions/workflows/cli-e2e.yml/runs?branch=main&status=success&per_page=100")["workflow_runs"]
+ passed = [r for r in passed if r["event"] in {"push", "schedule", "workflow_dispatch"}]
+ last = max(passed, key=lambda r: r["updated_at"], default=None)
+ report = dict(schema=1, measured_at=now.isoformat(), sample_runs=len(runs), validation_runs=len(measured),
+ sample_oldest=min((r["created_at"] for r in runs), default=None),
+ outcomes=dict(Counter(r["conclusion"] or r["status"] for r in measured)),
+ events=dict(Counter(r["event"] for r in measured)), cancelled_runs=work,
+ cancelled_run_job_minutes=round(sum(r["observed_job_minutes"] for r in work), 2),
+ last_completed_main_e2e=dict(url=last["html_url"], sha=last["head_sha"],
+ completed_at=last["updated_at"], age_minutes=round((now-stamp(last["updated_at"])).total_seconds()/60, 1)) if last else None,
+ note="Bounded latest-100-run sample. Job timestamps are execution observations, not billed minutes. A completed old snapshot does not cover newer main inputs.")
+ Path(os.environ["RUNNER_TEMP"], "ci-health.json").write_text(json.dumps(report, indent=2) + "\n")
+ with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary:
+ summary.write(f"CI sample: {len(measured)} validation runs since {report['sample_oldest']}.\n\n")
+ summary.write(f"Outcomes: `{report['outcomes']}`.\n\n")
+ summary.write(f"Execution in cancelled runs: **{report['cancelled_run_job_minutes']:g} combined job-minutes**.\n\n")
+ if last:
+ summary.write(f"Last completed [main E2E]({last['html_url']}): **{report['last_completed_main_e2e']['age_minutes']:g} minutes ago**, source `{last['head_sha']}`.\n\n")
+ else:
+ summary.write("No completed passing main E2E found.\n\n")
+ summary.write(report["note"] + "\n")
+ print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/ci-plan.py b/scripts/ci-plan.py
new file mode 100644
index 000000000..f59c56851
--- /dev/null
+++ b/scripts/ci-plan.py
@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Select coarse CI suites from a complete Git diff and verify their final results.
+
+PRs test their exact head; merge groups test their exact combined candidate.
+Manual scopes retain their existing meaning. Native/engine/hardware acceptance
+selected during review remains additional to these automatic checks.
+"""
+import argparse
+import fnmatch
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+
+
+CORE = {"cli", "desktop", "tui", "backend", "companions"}
+EXTRA = {"website", "experience", "authoring", "home-assistant", "desktop-logging",
+ "os", "provider", "firmware", "mobile", "daemons"}
+SUITES = CORE | EXTRA
+JOBS = {
+ "cli": {"serial-native", "process-images-native", "cli-contracts", "cli-coverage-gates", "cli-tests", "typecheck-test"},
+ "desktop": {"desktop-tests", "desktop-test-summary"},
+ "tui": {"tui-test"}, "backend": {"backend-desk"}, "companions": {"companion-subsystems"},
+ **{name: {name + "-checks"} for name in EXTRA},
+}
+MANUAL = {"full": CORE, "all": SUITES, "process": set(), **{name: {name} for name in SUITES}}
+AUTHORING = {"generative-art", "music-studio", "creative-direction", "voxel-worlds",
+ "drone-pilot", "game-master", "lab-bench", "data-studio"}
+LOGGING = ["desktop/lib/logging/*", "desktop/test/app_log_test.dart", "desktop/test/buffered_log_test.dart",
+ "desktop/test/crash_log_test.dart", "desktop/test/dial_log_tail_test.dart", "desktop/test/log_*_test.dart",
+ "desktop/test/export_logs_dialog_test.dart", "desktop/test/cli_transcript_test.dart", "desktop/tool/log_append_probe.dart"]
+SPECIAL_WORKFLOWS = {"website-checks.yml": "website", "experience-checks.yml": "experience",
+ "authoring-browser-checks.yml": "authoring", "home-assistant-checks.yml": "home-assistant",
+ "desktop-logging-checks.yml": "desktop-logging"}
+ROOT_DOCS = {"AGENTS.md", "CHANGELOG.md", "CLAUDE.md", "CONTEXT.md", "CONTRIBUTING.md", "HANDOFF.md",
+ "LICENSE", "README.md", "SECURITY.md", "claude_research.md"}
+
+
+def git(root, *args):
+ return subprocess.check_output(["git", *args], cwd=root, stderr=subprocess.PIPE, timeout=120).decode().strip()
+
+
+def sha(value):
+ if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{40}", value):
+ raise ValueError("CI requires a full immutable Git SHA")
+ return value
+
+
+def select(paths):
+ selected, reasons, unknown = set(), {}, []
+ for path in paths:
+ if not isinstance(path, str) or not path or path.startswith("/") or ".." in path.split("/"):
+ raise ValueError("invalid changed path")
+ scopes = set()
+ root = path.split("/", 1)[0]
+ if path in ROOT_DOCS or (root == "docs" and not path.startswith("docs/images/")):
+ pass
+ elif root in {".github", "scripts"} or path in {"Makefile", ".gitattributes", ".gitignore", ".gitmodules"}:
+ # Keep existing source-input contracts conservative. Workflow/helper
+ # changes invalidate all core suites until narrower contracts exist.
+ scopes |= CORE
+ if path in {".github/workflows/ci.yml", "scripts/ci-plan.py"}:
+ scopes |= SUITES # The shared planner/job graph controls every component.
+ workflow = path.removeprefix(".github/workflows/")
+ if workflow in SPECIAL_WORKFLOWS:
+ scopes.add(SPECIAL_WORKFLOWS[workflow])
+ if workflow.startswith("os-") or workflow == "os.yml":
+ scopes.add("os")
+ elif root == "cli":
+ scopes |= CORE # Desktop/TUI/companions consume CLI inputs.
+ scopes.add("mobile") # Phone protocol contracts read the CLI's frame definitions.
+ elif root == "desktop":
+ scopes.add("desktop")
+ if path.startswith("desktop/assets/engine-icons/"):
+ scopes.add("experience")
+ if any(fnmatch.fnmatchcase(path, pattern) for pattern in LOGGING):
+ scopes.add("desktop-logging")
+ elif root in {"tui", "backend", "companions", "website", "os", "provider"}:
+ scopes.add(root)
+ elif root == "devices":
+ scopes |= {"firmware", "cli", "desktop"}
+ elif root == "mobile":
+ scopes.add("mobile")
+ if path == "mobile/pubspec.lock":
+ scopes.add("desktop")
+ elif root in {"tests", "daemons"}:
+ scopes |= CORE | {"mobile", "daemons"}
+ elif root == "store":
+ scopes |= {"desktop", "experience"}
+ if (path.startswith(("store/tools/", "store/viewers/web-viewer/"))
+ or any(path.startswith(f"store/agents/{name}/") for name in AUTHORING)):
+ scopes.add("authoring")
+ if path.startswith("store/agents/home-assistant/") or path in {"store/tools/runtimes.sh", "store/tools/sync-runtimes.mjs"}:
+ scopes.add("home-assistant")
+ elif path.startswith("docs/images/"):
+ scopes.add("desktop")
+ elif root in {"artifacts", "output", "work"}:
+ scopes |= CORE
+ else:
+ unknown.append(path)
+ selected |= scopes
+ reasons[path] = sorted(scopes)
+ if unknown:
+ raise ValueError("register CI coverage for these paths before merging: " + ", ".join(unknown))
+ return selected, reasons
+
+
+def make_plan(root, event_name, event, scope="full", source=None):
+ head = sha(source or git(root, "rev-parse", "HEAD"))
+ if git(root, "rev-parse", "HEAD") != head:
+ raise ValueError("checkout differs from the requested source")
+ base = None
+ draft = False
+ paths, reasons = [], {}
+ if event_name == "pull_request":
+ pr = event["pull_request"]
+ draft = pr.get("draft", False)
+ if not isinstance(draft, bool):
+ raise ValueError("invalid PR draft state")
+ if sha(pr["head"]["sha"]) != head:
+ raise ValueError("PR head differs from the checkout")
+ # Use Git, not the event's truncated paths or GitHub's limited file API.
+ base = sha(git(root, "merge-base", sha(pr["base"]["sha"]), head))
+ elif event_name == "merge_group":
+ group = event["merge_group"]
+ if event.get("action") != "checks_requested" or sha(group["head_sha"]) != head:
+ raise ValueError("merge group differs from the checkout")
+ base = sha(group["base_sha"])
+ git(root, "merge-base", "--is-ancestor", base, head)
+ elif event_name not in {"workflow_dispatch", "workflow_call"}:
+ raise ValueError("unsupported CI event")
+ if base:
+ # Treat renames as deletion + addition so both input boundaries apply.
+ changed = subprocess.check_output(["git", "diff", "--no-renames", "--name-only", "-z", base, head], cwd=root, timeout=120)
+ paths = sorted(p.decode() for p in changed.split(b"\0") if p)
+ suites, reasons = select(paths)
+ else:
+ if scope not in MANUAL:
+ raise ValueError("invalid manual CI scope")
+ suites = MANUAL[scope]
+ required = {"process-checks"} | set().union(*(JOBS[name] for name in suites))
+ return dict(schema=1, kind="ci-plan", event=event_name, head=head, base=base, draft=draft,
+ tree=git(root, "rev-parse", "HEAD^{tree}"), paths=paths, reasons=reasons,
+ suites=sorted(suites), required_jobs=sorted(required),
+ manual_acceptance="Review still selects relevant native, real-engine, hardware and visual acceptance.")
+
+
+def verify(plan, needs, source):
+ if plan.get("schema") != 1 or plan.get("kind") != "ci-plan" or plan.get("head") != sha(source):
+ raise ValueError("CI plan identity does not match this source")
+ sha(plan.get("tree"))
+ if plan.get("draft") is not False:
+ raise ValueError("Draft PR: complete component validation is deferred until ready_for_review")
+ suites = plan.get("suites")
+ if not isinstance(suites, list) or len(set(suites)) != len(suites) or not set(suites) <= SUITES:
+ raise ValueError("invalid planned suites")
+ expected = {"process-checks"} | set().union(*(JOBS[name] for name in suites))
+ if plan.get("required_jobs") != sorted(expected):
+ raise ValueError("CI plan has incomplete job coverage")
+ if needs.get("plan", {}).get("result") != "success":
+ raise ValueError("CI planning did not pass")
+ for job in expected:
+ if needs.get(job, {}).get("result") != "success":
+ raise ValueError(f"required CI job did not pass: {job}")
+ for job, result in needs.items():
+ if result.get("result") not in {"success", "skipped"}:
+ raise ValueError(f"CI job did not complete successfully: {job}")
+ return dict(schema=1, kind="ci-required", status="passed", source_sha=plan["head"],
+ source_tree=plan["tree"], event=plan["event"], base=plan["base"],
+ suites=suites, required_jobs=sorted(expected), results={k: v["result"] for k, v in needs.items()},
+ run_id=int(os.environ.get("GITHUB_RUN_ID", "0")), run_attempt=int(os.environ.get("GITHUB_RUN_ATTEMPT", "0")))
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--verify", action="store_true")
+ parser.add_argument("--scope", default="full")
+ parser.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ if args.verify:
+ plan = json.loads(os.environ["CI_PLAN"])
+ if (git(Path.cwd(), "rev-parse", "HEAD") != os.environ["CI_SOURCE_SHA"]
+ or git(Path.cwd(), "rev-parse", "HEAD^{tree}") != plan.get("tree")):
+ raise ValueError("CI gate checkout differs from the planned source")
+ record = verify(plan, json.loads(os.environ["CI_NEEDS"]), os.environ["CI_SOURCE_SHA"])
+ else:
+ record = make_plan(Path.cwd(), os.environ["GITHUB_EVENT_NAME"],
+ json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text()), args.scope, os.environ["CI_SOURCE_SHA"])
+ with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+ output.write("plan=" + json.dumps(record, separators=(",", ":")) + "\n")
+ output.write(f"ready={'false' if record['draft'] else 'true'}\n")
+ for suite in sorted(SUITES):
+ output.write(f"{suite}={'true' if suite in record['suites'] else 'false'}\n")
+ args.output.write_text(json.dumps(record, indent=2) + "\n")
+ with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary:
+ summary.write(f"Source: `{record.get('head', record.get('source_sha'))}`\n\n")
+ summary.write("Automatic suites: " + ", ".join(record["suites"] or ["repository process checks"]) + ".\n")
+ if record.get("draft"):
+ summary.write("Draft PR: only workflow/process checks run; mark ready for review to run the complete affected suites. The integration gate remains blocked.\n")
+ summary.write("Native, real-engine, hardware and visual acceptance remain explicit review requirements.\n")
+ print(json.dumps(record, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/ci-source-inputs.py b/scripts/ci-source-inputs.py
index 7130a643e..51abd023a 100644
--- a/scripts/ci-source-inputs.py
+++ b/scripts/ci-source-inputs.py
@@ -46,7 +46,7 @@ def verify_checkout(root, scope, subset=False):
def capture(root):
verify_checkout(root, "process")
sha = git(root, "rev-parse", "HEAD")
- if os.environ.get("GITHUB_SHA") != sha:
+ if os.environ.get("CI_SOURCE_SHA", os.environ.get("GITHUB_SHA")) != sha:
raise ValueError("checkout differs from the CI source")
run, attempt = (int(os.environ[key]) for key in ("GITHUB_RUN_ID", "GITHUB_RUN_ATTEMPT"))
if run < 1 or attempt < 1:
diff --git a/scripts/merge-validated-pr.py b/scripts/merge-validated-pr.py
index b78845fa6..52cc86f2b 100644
--- a/scripts/merge-validated-pr.py
+++ b/scripts/merge-validated-pr.py
@@ -152,8 +152,10 @@ def finish(client, root, number, run_id, scope, head, base, output, *, merge=Fal
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("pr", type=int)
- parser.add_argument("--run", type=int, required=True)
- parser.add_argument("--scope", choices=ci.SCOPES, required=True)
+ parser.add_argument("--run", type=int, help="required for legacy direct merging; queue mode follows automatic CI")
+ parser.add_argument("--scope", choices=ci.SCOPES, help="required for legacy direct merging")
+ parser.add_argument("--queue", action="store_true", help="enqueue and verify the tested merge candidate")
+ parser.add_argument("--base-branch", default="main", help="queue target; use a disposable branch for rollout trials")
parser.add_argument("--reviewed-head", required=True, help="full commit SHA already reviewed, including required non-CI checks")
parser.add_argument("--reviewed-base", required=True, help="full main SHA included in the reviewed head")
parser.add_argument("--repo", default="autonomous-ai/openharness")
@@ -162,19 +164,34 @@ def main():
parser.add_argument("--timeout", type=float, default=90, help="budget for preflight and, separately, post-CI operations")
parser.add_argument("--output", type=Path)
args = parser.parse_args()
- if (args.pr < 1 or args.run < 1
+ if (args.pr < 1 or (args.run is not None and args.run < 1)
or any(not re.fullmatch(r"[0-9a-f]{40}", sha) for sha in [args.reviewed_head, args.reviewed_base])
or any(not 0 < value < float("inf") for value in [args.wait_timeout, args.timeout])
- or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_.-]*", args.repo)):
+ or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_.-]*", args.repo)
+ or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_/-]*", args.base_branch)):
parser.error("supply positive IDs/budgets, full reviewed SHAs, and a valid repository")
root = Path(git(Path.cwd(), "rev-parse", "--show-toplevel")).resolve()
output = args.output or root / ".harness/validation" / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ") + f"-merge-{args.pr}")
- record = finish(ci.Client(args.repo, 0), root, args.pr, args.run, args.scope, args.reviewed_head,
- args.reviewed_base, output, merge=args.merge, wait_timeout=args.wait_timeout, timeout=args.timeout)
+ client = ci.Client(args.repo, time.monotonic() + args.timeout)
+ # Existing commands transparently use the queue once the target's rule is
+ # active. An explicit --queue supports testing before main is enforced.
+ rules = client.api(f"rules/branches/{args.base_branch}")
+ queued = args.queue or any(rule.get("type") == "merge_queue" for rule in rules)
+ if queued:
+ queue_spec = importlib.util.spec_from_file_location("queue_merge", Path(__file__).with_name("queue-validated-pr.py"))
+ queue = importlib.util.module_from_spec(queue_spec)
+ queue_spec.loader.exec_module(queue)
+ record = queue.finish(client, root, args.pr, args.reviewed_head, args.reviewed_base, output,
+ merge=args.merge, wait_timeout=args.wait_timeout, timeout=args.timeout, branch=args.base_branch)
+ else:
+ if args.run is None or args.scope is None or args.base_branch != "main":
+ parser.error("direct merging requires --run, --scope and main; use --queue for queued integration")
+ record = finish(client, root, args.pr, args.run, args.scope, args.reviewed_head,
+ args.reviewed_base, output, merge=args.merge, wait_timeout=args.wait_timeout, timeout=args.timeout)
print(f"{record['status']}: {output / 'merge.md'}")
if "error" in record:
print(record["error"], file=sys.stderr)
- return {"merged": 0, "ready": 0, "merged_source_review_required": 3}.get(record["status"], 1)
+ return {"merged": 0, "ready": 0, "ready_for_queue": 0, "merged_source_review_required": 3}.get(record["status"], 1)
if __name__ == "__main__":
diff --git a/scripts/queue-validated-pr.py b/scripts/queue-validated-pr.py
new file mode 100644
index 000000000..747d04685
--- /dev/null
+++ b/scripts/queue-validated-pr.py
@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Enqueue an already-reviewed PR and retain evidence for its actual merged tree.
+
+The exact reviewed head is bound to GitHub's enqueue mutation. Main may advance;
+the required merge-group CI tests that combined candidate. No mutation is retried
+after an uncertain response, and this command never publishes a release.
+"""
+import importlib.util
+import json
+from pathlib import Path
+import re
+import subprocess
+import time
+
+spec = importlib.util.spec_from_file_location("queue_ci_evidence", Path(__file__).with_name("record-ci-validation.py"))
+ci = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(ci)
+
+STATE_QUERY = """query($owner:String!,$name:String!,$number:Int!) {
+ repository(owner:$owner,name:$name) { pullRequest(number:$number) {
+ id number state isDraft headRefOid baseRefName mergedAt
+ mergeCommit { oid tree { oid } }
+ mergeQueueEntry { id state position enqueuedAt headCommit { oid tree { oid } } }
+ } }
+}"""
+ENQUEUE = """mutation($id:ID!,$head:GitObjectID!) {
+ enqueuePullRequest(input:{pullRequestId:$id,expectedHeadOid:$head,jump:false}) {
+ mergeQueueEntry { id }
+ }
+}"""
+
+
+def graphql(client, query, **variables):
+ args = ["api", "graphql", "-f", "query=" + query]
+ for key, value in variables.items():
+ args += ["-F" if isinstance(value, int) else "-f", f"{key}={value}"]
+ result = client.command(*args)
+ if result.get("errors") or not isinstance(result.get("data"), dict):
+ raise ValueError("GitHub queue lookup failed: " + json.dumps(result.get("errors", [])))
+ return result["data"]
+
+
+def state(client, number, head, branch):
+ owner, name = client.repository.split("/")
+ pr = graphql(client, STATE_QUERY, owner=owner, name=name, number=number)["repository"]["pullRequest"]
+ if (pr.get("number") != number or pr.get("headRefOid") != head or pr.get("baseRefName") != branch
+ or pr.get("isDraft") is not False):
+ raise ValueError("PR head, target or draft state differs from the reviewed source")
+ return pr
+
+
+def gate_evidence(client, run, output):
+ ci.check_run(run, client.repository, run["id"])
+ if run.get("event") not in {"pull_request", "merge_group"}:
+ raise ValueError("only automatic PR or merge-group CI can authorize queued integration")
+ jobs = client.pages(f"actions/runs/{run['id']}/jobs?filter=latest", "jobs")
+ gates = [j for j in jobs if j["name"] == "ci/required"]
+ if (len(gates) != 1 or gates[0].get("head_sha") != run["head_sha"]
+ or gates[0].get("status") != "completed" or gates[0].get("conclusion") != "success"):
+ raise ValueError("automatic required CI gate did not pass")
+ artifacts = client.pages(f"actions/runs/{run['id']}/artifacts", "artifacts")
+ matches = [a for a in artifacts if a.get("name") == "ci-required"]
+ if len(matches) != 1 or matches[0].get("size_in_bytes", 65537) > 65536:
+ raise ValueError("expected one bounded required-gate receipt")
+ artifact = matches[0]
+ archive = client.command("api", f"repos/{client.repository}/actions/artifacts/{artifact['id']}/zip", binary=True)
+ receipt = ci.summary_contents(artifact, archive, run, "ci-required")
+ commit = client.api(f"git/commits/{run['head_sha']}")
+ if (commit.get("sha") != run["head_sha"] or receipt.get("schema") != 1
+ or receipt.get("kind") != "ci-required" or receipt.get("status") != "passed"
+ or receipt.get("source_sha") != run["head_sha"] or receipt.get("event") != run["event"]
+ or receipt.get("source_tree") != commit.get("tree", {}).get("sha")
+ or receipt.get("run_id") != run["id"] or receipt.get("run_attempt") != gates[0].get("run_attempt")
+ or not receipt.get("required_jobs")
+ or any(receipt.get("results", {}).get(job) != "success" for job in receipt["required_jobs"])
+ or receipt.get("results", {}).get("plan") != "success"):
+ raise ValueError("required-gate receipt has inconsistent source, coverage or run identity")
+ after = client.api(f"actions/runs/{run['id']}")
+ ci.check_run(after, client.repository, run["id"])
+ if any(after[key] != run[key] for key in ["head_sha", "run_attempt", "updated_at"]):
+ raise ValueError("CI changed during queue evidence collection")
+ output.mkdir(parents=True, exist_ok=True)
+ (output / "ci-required.zip").write_bytes(archive)
+ (output / "receipt.json").write_text(json.dumps(receipt, indent=2) + "\n")
+ return dict(run_id=run["id"], run_attempt=run["run_attempt"], url=run["html_url"],
+ source_sha=receipt["source_sha"], source_tree=receipt["source_tree"],
+ suites=receipt["suites"], artifact_id=artifact["id"], artifact_digest=artifact["digest"])
+
+
+def pr_gate(client, head, output):
+ runs = client.pages("actions/workflows/ci.yml/runs?event=pull_request&head_sha=" + head, "workflow_runs")
+ candidates = sorted((r for r in runs if r.get("head_sha") == head), key=lambda r: r["id"], reverse=True)
+ if not candidates:
+ raise ValueError("automatic CI has not run for the reviewed PR head")
+ return gate_evidence(client, candidates[0], output)
+
+
+def merged_gate(client, tree, branch, started_at, output):
+ # A merge may finish between polls, so don't depend on having seen its queue
+ # ref. Search the automatic candidate runs and verify the immutable tree.
+ path = "actions/workflows/ci.yml/runs?event=merge_group&created=%3E%3D" + started_at[:19] + "Z"
+ runs = client.pages(path, "workflow_runs")
+ candidates = sorted(runs, key=lambda r: r["id"], reverse=True)
+ for run in candidates:
+ if (run.get("status") != "completed" or run.get("conclusion") != "success"
+ or not run.get("head_branch", "").startswith(f"gh-readonly-queue/{branch}/")):
+ continue
+ commit = client.api(f"git/commits/{run['head_sha']}")
+ if commit.get("sha") == run["head_sha"] and commit.get("tree", {}).get("sha") == tree:
+ return gate_evidence(client, run, output)
+ raise ValueError("merged tree lacks verified successful merge-group CI; inspect this same PR")
+
+
+def finish(client, root, number, head, base, output, *, merge=False, wait_timeout=1800, timeout=90, branch="main"):
+ output.mkdir(parents=True, exist_ok=False)
+ record = dict(schema=1, kind="queued-pr-merge", repository=client.repository, pr=number,
+ reviewed_head=head, reviewed_base=base, target_branch=branch, merge_authorized=merge,
+ started_at=ci.utc_now(), status="not_queued", phases={})
+
+ def save():
+ temporary = output / "receipt.tmp"
+ temporary.write_text(json.dumps(record, indent=2) + "\n")
+ temporary.replace(output / "receipt.json")
+
+ def phase(name, action):
+ started = time.monotonic()
+ detail = record["phases"][name] = dict(started_at=ci.utc_now())
+ save()
+ try:
+ return action()
+ finally:
+ detail.update(finished_at=ci.utc_now(), duration_seconds=round(time.monotonic() - started, 3))
+ save()
+
+ try:
+ client.deadline = time.monotonic() + timeout
+ local = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True, timeout=15).strip()
+ dirty = subprocess.check_output(["git", "status", "--porcelain", "--untracked-files=normal"], cwd=root, text=True, timeout=15).strip()
+ if local != head or dirty:
+ raise ValueError("the local checkout must remain clean at the reviewed head")
+ subprocess.run(["git", "merge-base", "--is-ancestor", base, head], cwd=root, check=True, timeout=15)
+ pr = phase("preflight", lambda: state(client, number, head, branch))
+ if pr["state"] != "OPEN":
+ raise ValueError("PR is not open")
+ record["pr_evidence"] = phase("pr_validation", lambda: pr_gate(client, head, output / "pr-ci"))
+ pr = state(client, number, head, branch)
+ if pr["state"] != "OPEN":
+ raise ValueError("PR state changed before enqueueing")
+ entry = pr.get("mergeQueueEntry")
+ # Resuming a queued PR must include the candidate created by its earlier
+ # enqueue. A fresh command's start time would exclude that valid run.
+ record["candidate_search_since"] = entry["enqueuedAt"] if entry else record["started_at"]
+ if entry:
+ record["queue_entry"] = entry
+ record["status"] = "ready_for_queue"
+ save()
+ if merge:
+ if not pr["mergeQueueEntry"]:
+ record.update(status="enqueue_requested", enqueue_requested_at=ci.utc_now())
+ save()
+ try:
+ record["enqueue_response"] = phase("enqueue", lambda: graphql(client, ENQUEUE, id=pr["id"], head=head))
+ except (OSError, RuntimeError, subprocess.SubprocessError, ValueError) as error:
+ record["enqueue_error"] = str(error)
+ # Observe the same PR even after a lost enqueue response. Never
+ # silently issue a second mutation or substitute a newer PR head.
+ client.deadline = time.monotonic() + wait_timeout
+
+ def follow():
+ announced = None
+ while time.monotonic() < client.deadline:
+ current = state(client, number, head, branch)
+ if current["state"] == "MERGED":
+ merged = current["mergeCommit"]
+ ci_sha = merged["oid"]
+ tree = merged["tree"]["oid"]
+ if not all(re.fullmatch(r"[0-9a-f]{40}", v or "") for v in [ci_sha, tree]):
+ raise ValueError("merged PR has an invalid commit/tree")
+ client.deadline = time.monotonic() + timeout
+ evidence = merged_gate(client, tree, branch, record["candidate_search_since"], output / "candidate-ci")
+ return dict(commit=ci_sha, tree=tree, merged_at=current["mergedAt"], evidence=evidence)
+ entry = current["mergeQueueEntry"]
+ if current["state"] != "OPEN" or not entry:
+ raise ValueError("PR left the merge queue or enqueue was not confirmed; inspect this same PR")
+ summary = (entry["id"], entry["state"], entry["position"])
+ if summary != announced:
+ print(f"PR #{number}: queue position {entry['position']}, {entry['state']}", flush=True)
+ announced = summary
+ record.update(status="queued", queue_entry=entry)
+ save()
+ time.sleep(min(10, max(0, client.deadline - time.monotonic())))
+ raise TimeoutError("queue wait deadline exceeded; PR remains queued, follow the same PR")
+
+ record["merge"] = phase("queue_wait_and_verification", follow)
+ record["status"] = "merged"
+ except (OSError, RuntimeError, ValueError, KeyError, TypeError, subprocess.SubprocessError, ci.zipfile.BadZipFile) as error:
+ record["error"] = str(error)
+ if "enqueue_requested_at" in record or record.get("queue_entry"):
+ record["status"] = "queue_outcome_not_confirmed"
+ record["finished_at"] = ci.utc_now()
+ save()
+ text = f"PR #{number}: **{record['status']}**.\nReviewed head `{head}`; review base `{base}`.\n"
+ if "merge" in record:
+ evidence = record["merge"]["evidence"]
+ text += f"Merged `{record['merge']['commit']}`; its full tree matches verified [candidate CI]({evidence['url']}).\n"
+ if "error" in record:
+ text += record["error"] + "\n"
+ (output / "merge.md").write_text(text)
+ return record
diff --git a/scripts/tests/test_ci_plan.py b/scripts/tests/test_ci_plan.py
new file mode 100644
index 000000000..9e9a8141d
--- /dev/null
+++ b/scripts/tests/test_ci_plan.py
@@ -0,0 +1,201 @@
+import copy
+import importlib.util
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+spec = importlib.util.spec_from_file_location("ci_plan", Path(__file__).resolve().parents[1] / "ci-plan.py")
+planner = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(planner)
+
+
+class SelectionTests(unittest.TestCase):
+ def test_docs_still_require_process_checks_and_assets_are_inputs(self):
+ self.assertEqual(planner.select(["docs/guide.md", "README.md"])[0], set())
+ self.assertEqual(planner.select(["docs/images/poster.png"])[0], {"desktop"})
+
+ def test_cli_and_process_changes_keep_conservative_core_coverage(self):
+ for path in ["scripts/merge-validated-pr.py", "Makefile"]:
+ with self.subTest(path=path):
+ self.assertEqual(planner.select([path])[0], planner.CORE)
+
+ def test_cli_changes_include_phone_protocol_contracts(self):
+ self.assertEqual(planner.select(["cli/src/lib/relayFrames.ts"])[0], planner.CORE | {"mobile"})
+
+ def test_shared_planner_or_job_graph_changes_validate_every_component(self):
+ for path in ["scripts/ci-plan.py", ".github/workflows/ci.yml"]:
+ self.assertEqual(planner.select([path])[0], planner.SUITES)
+
+ def test_known_component_and_browser_inputs(self):
+ for path, expected in {
+ "website/app/page.tsx": {"website"}, "os/root/usr/lib/session": {"os"},
+ "mobile/pubspec.lock": {"mobile", "desktop"}, "tui/src/main.rs": {"tui"},
+ "provider/spec.md": {"provider"}, "devices/harness-device/firmware/main/main.c": {"firmware", "cli", "desktop"},
+ "store/agents/home-assistant/src/a.py": {"desktop", "experience", "home-assistant"},
+ "store/tools/runtimes.sh": {"desktop", "experience", "home-assistant", "authoring"},
+ "desktop/test/log_redact_test.dart": {"desktop", "desktop-logging"},
+ }.items():
+ with self.subTest(path=path):
+ self.assertEqual(planner.select([path])[0], expected)
+
+ def test_unknown_paths_fail_instead_of_getting_an_empty_green_plan(self):
+ for path in ["new-component/code.ts", "surprise.py", "../cli/code.ts", "/absolute"]:
+ with self.subTest(path=path), self.assertRaises(ValueError):
+ planner.select([path])
+
+
+class GitPlanTests(unittest.TestCase):
+ def setUp(self):
+ tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(tmp.cleanup)
+ self.root = Path(tmp.name)
+ self.git("init", "-q")
+ self.git("config", "user.email", "[email protected]")
+ self.git("config", "user.name", "Fixture")
+ self.write("README.md", "base")
+ self.base = self.commit()
+
+ def git(self, *args):
+ return subprocess.check_output(["git", *args], cwd=self.root, stderr=subprocess.PIPE, text=True).strip()
+
+ def write(self, path, value="content"):
+ target = self.root / path
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(value)
+
+ def commit(self):
+ self.git("add", ".")
+ self.git("commit", "-qm", "fixture")
+ return self.git("rev-parse", "HEAD")
+
+ def plan(self, event="pull_request", base=None, draft=False):
+ head = self.git("rev-parse", "HEAD")
+ base = base or self.base
+ payload = ({"pull_request": {"head": {"sha": head}, "base": {"sha": base}, "draft": draft}} if event == "pull_request" else
+ {"action": "checks_requested", "merge_group": {"head_sha": head, "base_sha": base}})
+ return planner.make_plan(self.root, event, payload, source=head)
+
+ def test_draft_preserves_required_coverage_for_ready_event(self):
+ self.write("cli/src/lib/relayFrames.ts")
+ self.commit()
+ draft = self.plan(draft=True)
+ ready = self.plan()
+ self.assertTrue(draft["draft"])
+ self.assertFalse(ready["draft"])
+ self.assertEqual(draft["suites"], ready["suites"])
+ self.assertEqual(draft["required_jobs"], ready["required_jobs"])
+ self.assertIn("mobile-checks", draft["required_jobs"])
+ with self.assertRaisesRegex(ValueError, "invalid PR draft state"):
+ self.plan(draft="false")
+
+ def test_manual_and_merge_candidates_always_require_full_selected_validation(self):
+ self.assertFalse(self.plan("merge_group")["draft"])
+ self.assertFalse(planner.make_plan(self.root, "workflow_dispatch", {}, "all")["draft"])
+
+ def test_all_paths_are_read_even_above_github_file_limits(self):
+ for index in range(350):
+ self.write(f"docs/page-{index}.md")
+ self.write("website/changed.ts")
+ self.commit()
+ plan = self.plan()
+ self.assertEqual(len(plan["paths"]), 351)
+ self.assertEqual(plan["suites"], ["website"])
+
+ def test_rename_selects_old_and_new_components(self):
+ self.write("website/source.txt")
+ self.base = self.commit()
+ self.write("os/moved.txt")
+ (self.root / "website/source.txt").unlink()
+ self.commit()
+ self.assertEqual(set(self.plan()["suites"]), {"os", "website"})
+
+ def test_pr_uses_merge_base_without_claiming_unrelated_main_changes(self):
+ self.write("os/new.txt")
+ main = self.commit()
+ self.git("checkout", "--detach", self.base)
+ self.write("website/new.txt")
+ self.commit()
+ self.assertEqual(self.plan(base=main)["suites"], ["website"])
+
+ def test_group_includes_every_change_ahead_of_this_pr(self):
+ self.write("website/new.txt")
+ self.commit()
+ self.write("os/new.txt")
+ self.commit()
+ plan = self.plan("merge_group")
+ self.assertEqual(set(plan["suites"]), {"os", "website"})
+ self.assertEqual(plan["base"], self.base)
+
+ def test_wrong_head_event_or_nonancestor_group_fails(self):
+ head = self.git("rev-parse", "HEAD")
+ for event, payload in [
+ ("pull_request", {"pull_request": {"head": {"sha": "f" * 40}, "base": {"sha": self.base}}}),
+ ("merge_group", {"action": "destroyed", "merge_group": {"head_sha": head, "base_sha": self.base}}),
+ ("push", {}),
+ ]:
+ with self.subTest(event=event), self.assertRaises(ValueError):
+ planner.make_plan(self.root, event, payload, source=head)
+ self.write("os/later.txt")
+ future = self.commit()
+ self.git("checkout", "--detach", self.base)
+ with self.assertRaises(subprocess.CalledProcessError):
+ self.plan("merge_group", base=future)
+
+ def test_manual_scopes_remain_explicit_and_invalid_scopes_fail(self):
+ self.assertEqual(planner.make_plan(self.root, "workflow_dispatch", {}, "process")["required_jobs"], ["process-checks"])
+ self.assertEqual(set(planner.make_plan(self.root, "workflow_dispatch", {}, "all")["suites"]), planner.SUITES)
+ with self.assertRaises(ValueError):
+ planner.make_plan(self.root, "workflow_dispatch", {}, "typo")
+
+
+class GateTests(unittest.TestCase):
+ def setUp(self):
+ self.head = "a" * 40
+ self.plan = dict(schema=1, kind="ci-plan", head=self.head, tree="b" * 40, event="merge_group", base="c" * 40,
+ draft=False,
+ suites=["desktop"], required_jobs=sorted({"process-checks"} | planner.JOBS["desktop"]))
+ self.needs = {name: {"result": "success"} for name in self.plan["required_jobs"] + ["plan"]}
+ self.needs["cli-tests"] = {"result": "skipped"}
+
+ def test_gate_accepts_only_explicit_nonapplicable_skips(self):
+ result = planner.verify(self.plan, self.needs, self.head)
+ self.assertEqual(result["status"], "passed")
+ self.assertEqual(result["source_sha"], self.head)
+
+ def test_draft_or_missing_state_never_claims_passing_full_validation(self):
+ for state in [True, None, "false", 0]:
+ with self.subTest(state=state), self.assertRaisesRegex(ValueError, "deferred"):
+ planner.verify(dict(self.plan, draft=state), self.needs, self.head)
+ plan = copy.deepcopy(self.plan)
+ del plan["draft"]
+ with self.assertRaises(ValueError):
+ planner.verify(plan, self.needs, self.head)
+
+ def test_missing_skipped_cancelled_or_failed_required_job_blocks(self):
+ for status in [None, "skipped", "cancelled", "failure", "in_progress"]:
+ needs = copy.deepcopy(self.needs)
+ if status is None:
+ del needs["desktop-tests"]
+ else:
+ needs["desktop-tests"]["result"] = status
+ with self.subTest(status=status), self.assertRaises(ValueError):
+ planner.verify(self.plan, needs, self.head)
+
+ def test_unplanned_failure_or_failed_planning_cannot_be_hidden(self):
+ for job in ["cli-tests", "plan"]:
+ needs = copy.deepcopy(self.needs)
+ needs[job]["result"] = "failure"
+ with self.assertRaises(ValueError):
+ planner.verify(self.plan, needs, self.head)
+
+ def test_malformed_incomplete_or_wrong_source_plan_is_rejected(self):
+ for patch in [{"head": "d" * 40}, {"tree": "bad"}, {"required_jobs": ["process-checks"]},
+ {"suites": ["unknown"]}, {"suites": ["desktop", "desktop"]}]:
+ with self.subTest(patch=patch), self.assertRaises(ValueError):
+ planner.verify(dict(self.plan, **patch), self.needs, self.head)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_ci_source_inputs.py b/scripts/tests/test_ci_source_inputs.py
index 3e6d18ce3..a5e16ebe5 100644
--- a/scripts/tests/test_ci_source_inputs.py
+++ b/scripts/tests/test_ci_source_inputs.py
@@ -84,15 +84,18 @@ class SourceInputTests(unittest.TestCase):
def test_capture_binds_git_objects_to_the_real_source_run_and_attempt(self):
self.sparse(inputs.ci.SOURCE_INPUTS["process"])
- with mock.patch.dict(os.environ, GITHUB_SHA=self.sha, GITHUB_RUN_ID="123", GITHUB_RUN_ATTEMPT="2"):
+ with mock.patch.dict(os.environ, GITHUB_SHA=self.sha, CI_SOURCE_SHA=self.sha,
+ GITHUB_RUN_ID="123", GITHUB_RUN_ATTEMPT="2"):
result = inputs.capture(self.root)
self.assertEqual(result["source_sha"], self.sha)
self.assertEqual(result["run_attempt"], 2)
self.assertEqual(set(result["scopes"]), {"process", "desktop"})
self.assertEqual(result["scopes"]["desktop"], inputs.ci.input_snapshot(self.root, self.sha, "desktop"))
- with mock.patch.dict(os.environ, GITHUB_SHA="b" * 40):
+ with mock.patch.dict(os.environ, CI_SOURCE_SHA="b" * 40):
with self.assertRaisesRegex(ValueError, "differs from the CI source"):
inputs.capture(self.root)
+ with mock.patch.dict(os.environ, GITHUB_SHA="b" * 40, CI_SOURCE_SHA=self.sha):
+ self.assertEqual(inputs.capture(self.root)["source_sha"], self.sha)
if __name__ == "__main__":
diff --git a/scripts/tests/test_queue_validated_pr.py b/scripts/tests/test_queue_validated_pr.py
new file mode 100644
index 000000000..4f9470792
--- /dev/null
+++ b/scripts/tests/test_queue_validated_pr.py
@@ -0,0 +1,201 @@
+import copy
+import hashlib
+import importlib.util
+import io
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+import zipfile
+
+spec = importlib.util.spec_from_file_location("queue_merge", Path(__file__).resolve().parents[1] / "queue-validated-pr.py")
+queue = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(queue)
+
+
+class QueueTests(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.root = Path(self.tmp.name) / "source"
+ self.root.mkdir()
+ self.git("init", "-q")
+ self.git("config", "user.email", "[email protected]")
+ self.git("config", "user.name", "Fixture")
+ (self.root / "README.md").write_text("base")
+ self.git("add", ".")
+ self.git("commit", "-qm", "base")
+ self.base = self.git("rev-parse", "HEAD")
+ (self.root / "README.md").write_text("reviewed")
+ self.git("commit", "-qam", "reviewed")
+ self.head = self.git("rev-parse", "HEAD")
+ self.output = Path(self.tmp.name) / "result"
+ self.client = FakeClient(self)
+ p = mock.patch.object(queue.time, "sleep")
+ p.start()
+ self.addCleanup(p.stop)
+ p = mock.patch("builtins.print")
+ p.start()
+ self.addCleanup(p.stop)
+
+ def git(self, *args):
+ return subprocess.check_output(["git", *args], cwd=self.root, stderr=subprocess.PIPE, text=True).strip()
+
+ def finish(self, merge=True):
+ result = queue.finish(self.client, self.root, 5, self.head, self.base, self.output, merge=merge)
+ self.assertEqual(json.loads((self.output / "receipt.json").read_text()), result)
+ return result
+
+ def test_preview_collects_automatic_evidence_without_writes(self):
+ self.assertEqual(self.finish(False)["status"], "ready_for_queue")
+ self.assertEqual(self.client.writes, [])
+
+ def test_enqueue_is_bound_to_reviewed_head_and_combined_tree_verified(self):
+ result = self.finish()
+ self.assertEqual(result["status"], "merged")
+ self.assertEqual(result["merge"]["tree"], self.client.candidate_tree)
+ self.assertNotEqual(result["merge"]["tree"], self.git("rev-parse", "HEAD^{tree}"))
+ self.assertEqual(len(self.client.writes), 1)
+ self.assertIn("head=" + self.head, self.client.writes[0])
+ self.assertEqual(result["merge"]["evidence"]["run_id"], 124)
+
+ def test_lost_enqueue_response_is_observed_without_retrying_mutation(self):
+ self.client.lost_response = True
+ result = self.finish()
+ self.assertEqual(result["status"], "merged")
+ self.assertIn("enqueue_error", result)
+ self.assertEqual(len(self.client.writes), 1)
+
+ def test_resuming_existing_queue_entry_verifies_earlier_candidate_without_reenqueue(self):
+ entry = dict(id="entry", state="AWAITING_CHECKS", position=1, enqueuedAt="2026-10-06T20:00:00Z")
+ opened = dict(state="OPEN", mergeQueueEntry=entry)
+ merged = dict(state="MERGED", mergeCommit={"oid": self.client.merged,
+ "tree": {"oid": self.client.candidate_tree}}, mergedAt="2026-10-07T03:00:00Z")
+ with mock.patch.object(queue, "state", side_effect=[opened, opened, merged]):
+ result = self.finish()
+ self.assertEqual(result["status"], "merged")
+ self.assertEqual(self.client.writes, [])
+ self.assertEqual(result["candidate_search_since"], entry["enqueuedAt"])
+ self.assertTrue(any("created=%3E%3D2026-10-06T20:00:00Z" in path for path in self.client.read_paths))
+
+ def test_unconfirmed_enqueue_or_queue_removal_cannot_report_success(self):
+ self.client.drop = True
+ result = self.finish()
+ self.assertEqual(result["status"], "queue_outcome_not_confirmed")
+ self.assertEqual(len(self.client.writes), 1)
+
+ def test_failed_pr_ci_cannot_enqueue(self):
+ self.client.runs[123]["conclusion"] = "failure"
+ self.assertEqual(self.finish()["status"], "not_queued")
+ self.assertEqual(self.client.writes, [])
+
+ def test_head_change_after_write_is_detected(self):
+ self.client.change_head = True
+ result = self.finish()
+ self.assertEqual(result["status"], "queue_outcome_not_confirmed")
+ self.assertEqual(len(self.client.writes), 1)
+
+ def test_failed_or_wrong_tree_candidate_cannot_verify_merge(self):
+ for patch in [{"conclusion": "failure"}, {"head_branch": "another-branch"}, {"head_sha": "e" * 40}]:
+ self.client = FakeClient(self)
+ self.output = Path(self.tmp.name) / ("case-" + list(patch)[0])
+ self.client.runs[124].update(patch)
+ with self.subTest(patch=patch):
+ result = self.finish()
+ self.assertEqual(result["status"], "queue_outcome_not_confirmed")
+ self.assertEqual(len(self.client.writes), 1)
+
+ def test_receipt_tampering_wrong_attempt_or_incomplete_jobs_blocks_enqueue(self):
+ for patch in [{"source_sha": "f" * 40}, {"run_attempt": 2}, {"source_tree": "e" * 40},
+ {"results": {"process-checks": "skipped", "plan": "success"}}, {"event": "workflow_dispatch"}]:
+ self.client = FakeClient(self)
+ self.client.receipt_patch = patch
+ self.output = Path(self.tmp.name) / ("receipt-" + list(patch)[0])
+ with self.subTest(patch=patch):
+ self.assertEqual(self.finish()["status"], "not_queued")
+ self.assertEqual(self.client.writes, [])
+
+ def test_dirty_or_unreviewed_checkout_cannot_enqueue(self):
+ (self.root / "unreviewed.txt").write_text("change")
+ self.assertEqual(self.finish()["status"], "not_queued")
+ self.assertEqual(self.client.writes, [])
+
+
+class FakeClient:
+ repository = "owner/repo"
+
+ def __init__(self, fixture):
+ self.fixture = fixture
+ self.writes, self.enqueued, self.polls = [], False, 0
+ self.read_paths = []
+ self.drop = self.change_head = self.lost_response = False
+ self.receipt_patch = {}
+ self.candidate, self.candidate_tree, self.merged = "c" * 40, "d" * 40, "b" * 40
+ self.runs = {run_id: dict(id=run_id, repository={"full_name": self.repository}, path=".github/workflows/ci.yml",
+ status="completed", conclusion="success", run_attempt=1, updated_at="2026-10-07T03:00:00Z",
+ head_sha=fixture.head if run_id == 123 else self.candidate,
+ event="pull_request" if run_id == 123 else "merge_group", head_branch="topic" if run_id == 123 else "gh-readonly-queue/main/pr-5-head",
+ html_url=f"https://github.com/owner/repo/actions/runs/{run_id}") for run_id in [123, 124]}
+
+ def archive(self, run):
+ receipt = dict(schema=1, kind="ci-required", status="passed", source_sha=run["head_sha"],
+ source_tree=self.fixture.git("rev-parse", "HEAD^{tree}") if run["id"] == 123 else self.candidate_tree,
+ event=run["event"], run_id=run["id"], run_attempt=1, suites=[], required_jobs=["process-checks"],
+ results={"process-checks": "success", "plan": "success"})
+ if run["id"] == 123:
+ receipt.update(self.receipt_patch)
+ stream = io.BytesIO()
+ with zipfile.ZipFile(stream, "w") as bundle:
+ bundle.writestr(zipfile.ZipInfo("ci-required.json", (2026, 10, 7, 0, 0, 0)), json.dumps(receipt))
+ return stream.getvalue()
+
+ def api(self, path):
+ if path.startswith("actions/runs/"):
+ return copy.deepcopy(self.runs[int(path.split("/")[2])])
+ if path.startswith("git/commits/"):
+ head = path.split("/")[-1]
+ tree = self.fixture.git("rev-parse", "HEAD^{tree}") if head == self.fixture.head else self.candidate_tree
+ if head == "e" * 40:
+ tree = "f" * 40
+ return dict(sha=head, tree={"sha": tree})
+ raise AssertionError(path)
+
+ def pages(self, path, key):
+ self.read_paths.append(path)
+ if key == "workflow_runs":
+ return [copy.deepcopy(self.runs[123 if "event=pull_request" in path else 124])]
+ run = self.runs[int(path.split("/")[2])]
+ if key == "jobs":
+ return [dict(name="ci/required", status="completed", conclusion="success", head_sha=run["head_sha"], run_attempt=1)]
+ if key == "artifacts":
+ archive = self.archive(run)
+ return [dict(id=run["id"], name="ci-required", expired=False, size_in_bytes=len(archive),
+ digest="sha256:" + hashlib.sha256(archive).hexdigest(), workflow_run={"id":run["id"], "head_sha":run["head_sha"]})]
+ raise AssertionError(path)
+
+ def command(self, *args, binary=False):
+ if binary:
+ return self.archive(self.runs[int(args[-1].split("/")[-2])])
+ query = next(v for v in args if v.startswith("query="))
+ if "enqueuePullRequest" in query:
+ self.writes.append(args)
+ receipt = json.loads((self.fixture.output / "receipt.json").read_text())
+ assert receipt["status"] == "enqueue_requested"
+ self.enqueued = True
+ if self.lost_response:
+ raise subprocess.TimeoutExpired("gh", 30)
+ return {"data":{"enqueuePullRequest":{"mergeQueueEntry":{"id":"entry"}}}}
+ self.polls += int(self.enqueued)
+ merged = self.enqueued and not self.drop
+ pr = dict(id="pr", number=5, state="MERGED" if merged else "OPEN", isDraft=False,
+ headRefOid="f" * 40 if self.enqueued and self.change_head else self.fixture.head,
+ baseRefName="main", mergedAt="2026-10-07T03:00:00Z" if merged else None,
+ mergeCommit={"oid":self.merged,"tree":{"oid":self.candidate_tree}} if merged else None,
+ mergeQueueEntry=None)
+ return {"data":{"repository":{"pullRequest":pr}}}
+
+
+if __name__ == "__main__":
+ unittest.main()