Repository navigation
feat(images): define and verify the devenv BYO image contract #484
Description
Intent
Define and verify the minimum bring-your-own image contract needed for ADR-0030's devenv-enabled agent-kit architecture.
Scope
- Specify required image contents: Nix single-user, devenv at the selected major, direnv/shell hook behavior, agent user assumptions, and
/nixstore location. - Specify required workspace expectations such as
devenv.nixfor auto-activation where applicable. - Add a verification path that fails clearly when a supplied
ACQ_IMAGEorBASE_IMAGEdoes not meet the contract. - Preserve existing
ACQ_IMAGEoverride behavior while making failures easier to diagnose.
Deferred Decisions
- Exact version floors should be decided after the patterns devenv 2.x update lands and is live-verified.
- Whether the verifier is a new command, a create-time preflight, or both can be decided during implementation.
Acceptance Criteria
- Users bringing their own image get clear diagnostics for missing Nix/devenv/direnv, wrong
/nixlayout, or missing shell hook behavior. - The contract is documented and testable.
- Existing supported images pass the verifier.
- Failure messages do not expose secrets or internal host details.
Orchestration Notes
Implementation should be done by an authoring sub-agent and reviewed by an independent adversarial review sub-agent. Review findings must be addressed before the increment is accepted.
Activity
mogul commentedon Sep 18, 2026
Implemented the first quickstart-side BYO/devenv image diagnostics increment.
Commit:
0439013 feat(images): add non-enforcing contract doctorWhat landed:
acq doctor NAMEas a non-enforcing ADR-0030 image-contract diagnostic path for existing sandboxes.acq doctorhost/config behavior when no sandbox name is supplied.sbx exec NAME -- env HOME=/home/agent sh -c <probe>msb exec -u agent -e HOME=/home/agent NAME -- sh -c <probe>HOME=/home/agentagentuser when available/nixnix,devenv,direnvonPATH/home/agentwritability~/.rc.d~/.rc.dacq doctor NAME EXTRAis rejected.Review findings addressed:
HOME=/home/agentfor the probe and the probe warns if it is not running as the expected home/user..rc.d.Verification:
./scripts/test-acq-bats test/bats/65-doctor-image-contract.bats test/bats/60-help.bats(25/25)bash -n acq acq.backends/common.sh acq.backends/msb.sh acq.backends/sbx.sh scripts/test-acq-lib.sh test/bats/65-doctor-image-contract.batsgit diff --checkprintf %s\\n acq acq.backends/common.sh acq.backends/msb.sh acq.backends/sbx.sh scripts/test-acq-lib.sh test/bats/65-doctor-image-contract.bats | xargs -r -n8 shellcheck --severity=warningStill deferred:
devenvversion floor enforcement, pending the patterns-side devenv 2.x substrate decision.mogul commentedon Oct 6, 2026
Implemented and shipped in v4.0.0 via #474 (with corrective #549). BYO devenv image contract is verified by test/bats/65-doctor-image-contract.bats and doctor diagnostics. The PR's
Closes:footer did not auto-close this because the collapsed-stack squash merge dropped the closing keyword references; closing manually now that the work is onmainand released.