feat(images): define and verify the devenv BYO image contract

[mogul]

Intent

Define and verify the minimum bring-your-own image contract needed for ADR-0030's devenv-enabled agent-kit architecture.

Parent: #473
ADR: #474

Scope

• Specify required image contents: Nix single-user, devenv at the selected major, direnv/shell hook behavior, agent user assumptions, and /nix store location.
• Specify required workspace expectations such as devenv.nix for auto-activation where applicable.
• Add a verification path that fails clearly when a supplied ACQ_IMAGE or BASE_IMAGE does not meet the contract.
• Preserve existing ACQ_IMAGE override 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 /nix layout, 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.

[mogul]

Implemented the first quickstart-side BYO/devenv image diagnostics increment.

Commit: 0439013 feat(images): add non-enforcing contract doctor

What landed:

• Added acq doctor NAME as a non-enforcing ADR-0030 image-contract diagnostic path for existing sandboxes.
• Preserved existing acq doctor host/config behavior when no sandbox name is supplied.
• Added backend hooks for both backends:
  • SBX: sbx exec NAME -- env HOME=/home/agent sh -c <probe>
  • MSB: msb exec -u agent -e HOME=/home/agent NAME -- sh -c <probe>
• Guest diagnostics check:
  • HOME=/home/agent
  • running as agent user when available
  • /nix
  • nix, devenv, direnv on PATH
  • /home/agent writability
  • best-effort passwordless sudo probe
  • ~/.rc.d
  • shell startup source reference for ~/.rc.d
• Warnings are actionable and non-fatal; backend inspection failures still fail because the sandbox could not be inspected.
• Added direct unit coverage for the generated shell probe so tests exercise the real diagnostic script, not only canned stub output.
• Added argument validation: acq doctor NAME EXTRA is rejected.

Review findings addressed:

• SBX now sets HOME=/home/agent for the probe and the probe warns if it is not running as the expected home/user.
• Sudo check is labeled as a best-effort probe, not a strictly read-only guarantee.
• Tests now execute the generated shell probe under controlled fixtures.
• rc.d detection looks for actual source statements rather than any comment mentioning .rc.d.

Verification:

• PASS: ./scripts/test-acq-bats test/bats/65-doctor-image-contract.bats test/bats/60-help.bats (25/25)
• PASS: 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.bats
• PASS: git diff --check
• PASS: printf %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=warning

Still deferred:

• Exact devenv version floor enforcement, pending the patterns-side devenv 2.x substrate decision.
• Create-time hard enforcement; this increment is intentionally diagnostic/non-enforcing.
• Live backend verification on real SBX/MSB hosts.