Development

Development notes

CI behavior when working on agent-box itself. Repo conventions — structure, build and test commands, commit style — live in AGENTS.md at the repo root, so this page does not repeat them.

Host-specific setup is deliberately absent. How a given box puts tools on PATH, sets a git identity or stores a gh token is a property of that box, not of the template, so it belongs in that host's own config repo (for the maintainer's box, a private one).

CI

• Watch runs in the FOREGROUND: gh run watch <id> --exit-status. Don't background a streaming watch — it leaves stale "Running" ghost tasks in the UI.
• CI only runs on build-relevant paths (including Nix, payloads, tests, scripts, the lockfile and the CI workflow); doc-only pushes skip it.
• The landing page (docs/) publishes via GitHub Pages branch source, not a workflow — a push to master that touches docs/ deploys on its own.
• modules/agent-box.nix is generated. After you edit modules/agent-box.nix.in or modules/src/, run nix run .#assemble and commit the result, or the module-generated-up-to-date check fails on drift.

Validation scheduling and timing (#519)

Implemented in PR #671, which records baseline measurements, validation runs and the compute tradeoff.

CI runs native checks alongside four VM lanes on standard runners. Each VM lane prepares only its own drivers before executing one test at a time, so at most four VM tests run per workflow run. A test can start multiple guest machines. The extra runners reduce the critical path at the cost of more total runner minutes; do not compare only the fastest job or silently raise VM concurrency.

Validate module & VM is the final gate. It runs even when a dependency fails and succeeds only if native validation and every VM lane succeeded. The matrix keeps running sibling lanes after a failure so their results are not lost. For performance measurements, count from the first validation job's start through the final gate's completion, not the short gate alone. Record initial queue time separately, per-lane preparation and VM execution times, and the sum of job durations to expose the compute tradeoff.

Native check discovery and VM lane inventory checks replace the old manual workflow check list. Add native checks to the flake; register VM tests in vmTestsFor and assign each exactly once in ciVmLanes. The regression check also compares that schedule with the workflow matrix and checks the final gate's handling of failures, cancellations and skipped jobs.

Moving VM tests onto less busy runners exposed races in fixtures that injected state while a real CLI was still starting. The rotation fixture's synthetic SessionStart event could be overwritten by the real startup hook; the notice fixture's synthetic transcript could change during a resume. The quiesce_harness helper in tests/sessions.nix replaces the pane with an idle process and waits for the old process group to disappear before supplying synthetic state. Keeping the session present prevents the supervisor from respawning it early. The test then kills the pane and checks the real supervisor's next command, preserving both rotation hops and all notice cases.

SonarQube static analysis

Introduced by PR #728; activation is pending project and repository credential configuration.

.github/workflows/sonarqube.yml runs separately from the Nix/VM workflow on pushes to master, same-repository pull requests, and manual dispatch. It has no path filter, so changes to analysis settings and any supported source file are analyzed. Fork pull requests and Dependabot runs skip the job because they cannot use the repository scan secret. Do not use pull_request_target to bypass that boundary.

Before enabling the workflow, import this repository into SonarQube Cloud (the default) or create a project on an existing SonarQube Server accessible to GitHub-hosted runners. Set its main branch to master. For Cloud, disable Automatic Analysis in the project's Administration > Analysis Method so CI owns analysis. Use a plan/edition that supports pull-request analysis.

Configure these in the repository's Actions secrets and variables:

• Secret SONAR_TOKEN: a token with Execute Analysis permission for the project.
• Variable SONAR_PROJECT_KEY: the project's actual key from SonarQube.
• Variable SONAR_ORGANIZATION: the organization key, required for Cloud; leave it empty for Server.
• Variable SONAR_HOST_URL: optional; defaults to https://sonarcloud.io. Set this to the existing Server URL when using SonarQube Server.

Run the workflow on master first to establish the baseline before reviewing PR results. Missing configuration fails explicitly. The scan waits up to five minutes for the quality gate; a failed gate, timeout, or scanner error fails SonarQube analysis. This is separate from Validate module & VM; adding a workflow does not change GitHub branch protection. Only require the analysis check after configuration and the baseline scan succeed, accounting for the fork/Dependabot skip policy.

sonar-project.properties separates maintained source from tests and excludes the assembled Nix module, vendored code, generated Azure ARM JSON, and rendered test snapshots. The extensionless bin/agentbox is included as Python. Analysis covers languages supported by the configured SonarQube service; existing Nix checks and VM tests remain necessary. This integration does not generate test coverage reports, so choose the project's quality gate with that in mind rather than treating the scan as coverage validation.

The scanner action is pinned to an immutable release commit. See the official action for its configuration and supported scanners.