feat(kits)!: make oci-engine an opt-in catalog kit and retire the adapter auto-install

[mogul]

Context

This PR implements GSA-TTS/agentic-coding-quickstart#505 and is stacked on GSA-TTS/agentic-coding-quickstart#474. It must merge after GSA-TTS/agentic-coding-quickstart#474 because the base branch carries the patterns v1.10.0 pin (2dd2ad6ad5f63b842d732424bed5ba9aebeed676), where the oci-engine kit exists.

What Changed

• Added oci-engine to the generic opt-in kit catalog used by acq configure.
• Removed the msb adapter's default podman auto-install path, including adapter-owned podman package knobs, short-name-mode plumbing, OCI device grants, and the provision/start call sites.
• Repointed live OCI verification to provision a dedicated msb sandbox with the oci-engine kit selected.
• Added offline coverage that:
  • oci-engine appears in the configure catalog.
  • Selecting it writes extra_kits: oci-engine.
  • The configured catalog name expands to the pinned patterns ref.
  • A configured catalog kit survives acq start in a fresh shell through the persisted kit record path.
  • msb provisioning without oci-engine performs no adapter podman install and grants no OCI devices.
• Superseded ADR-0020 and updated backend/concepts/failure-mode docs for the catalog migration.

BREAKING CHANGE

New msb sandboxes no longer install podman automatically. Users who need docker run or docker compose inside the sandbox must opt into the oci-engine kit.

Migration options:

1. Run acq configure and select oci-engine for future sandboxes.
2. Pass the pinned kit ref with --kit for a one-off sandbox.
3. Export the pinned kit ref in ACQ_EXTRA_KITS.

Pinned kit ref for GSA-TTS/agentic-coding-quickstart#474 / patterns v1.10.0:

git+https://github.com/GSA-TTS/agentic-coding-patterns.git#ref=2dd2ad6ad5f63b842d732424bed5ba9aebeed676&dir=integrations/isolation/acq-kits/oci-engine

Verification Transcript

$ gh issue view 505 --repo GSA-TTS/agentic-coding-quickstart --json title,body,url,state,number
PASS - issue read without projectCards field.

$ test/vendor/bats-core/bin/bats test/bats/50-kit-list-completeness.bats test/bats/72-msb-agent-user.bats test/bats/95-kit-ref-persistence.bats test/bats/135-configure.bats
1..90
PASS - 90 tests, 0 failures.

$ bash -n acq acq.backends/*.sh scripts/test-acq-lib.sh scripts/test-acq-bats test/bats/helper.bash scripts/verify-backends
PASS - no output.

$ printf '%s\n' acq acq.backends/*.sh scripts/test-acq-lib.sh scripts/test-acq-bats test/bats/*.bats test/bats/helper.bash scripts/verify-backends | xargs -r -n8 shellcheck --severity=warning
PASS - no output.

$ npm run lint:md
markdownlint-cli2 v0.23.3 (markdownlint v0.41.1)
Finding: **/*.md !node_modules !.github/linters/node_modules !deleteme !tmp !CHANGELOG.md !test/vendor
Linting: 52 files
Summary: 0 issues in 0 files

CI note: the PR's Markdown Lint check is red before markdownlint runs because `.github/workflows/markdown-quality.yml:47` runs `npm audit --audit-level=high`, which now flags the pre-existing `.github/linters` chain `markdownlint-cli2@0.23.3` -> `globby` -> `micromatch` -> `braces@3.0.3` (GHSA-vfj7-8cjw-p6xm / CVE-2026-93687). `main`'s own run 37129103656 (2026-10-03T14:17:50Z) fails identically, while GSA-TTS/agentic-coding-quickstart#474's 00:55 run passed; this is a vulnerability-database update, not an OCI change. `npx markdownlint-cli2` itself passes locally. The advisory has no patched version, so the fix is a CI-policy decision deferred to GSA-TTS/agentic-coding-quickstart#540, not a dependency change in this PR.

$ git diff --check
PASS - no output.

$ ACQ_BATS_JOBS=4 ./scripts/test-acq-bats
BLOCKED/ENV - /tmp is a 512 MB tmpfs and filled during parallel bats:
No space left on device; executed 544 instead of expected 670 tests.

$ TMPDIR="$PWD/.tmp" GIT_CEILING_DIRECTORIES="$PWD/.tmp" ACQ_BATS_JOBS=4 ./scripts/test-acq-bats
1..670
PASS - all tests ok; sbx grammar tests skipped because sbx is not on PATH.

$ PATH="$PWD/.verify-tmp/bin:$PATH" ACQ_BACKEND=msb GIT_ALLOW_PROTOCOL=none ./acq ls
PASS - stubbed backend on PATH exits 0.

$ ACQ_SOURCE_ONLY=1 bash -c '. ./acq >/dev/null 2>&1; _acq_optin_kit_ref oci-engine'
git+https://github.com/GSA-TTS/agentic-coding-patterns.git#ref=2dd2ad6ad5f63b842d732424bed5ba9aebeed676&dir=integrations/isolation/acq-kits/oci-engine
PASS - oci-engine resolves to the v1.10.0 pinned ref.

$ grep for acq_oci_|ACQ_ENABLE_OCI_KIT|_acq_oci_engine_kit_ref
PASS - no files found.

$ grep for ACQ_MSB_ENSURE_OCI|ACQ_MSB_PODMAN_PKGS|ACQ_MSB_SHORT_NAME_MODE|_acq_msb_ensure_oci|_acq_msb_grant_oci_devs
PASS - no files found.

$ ./scripts/verify-backends --only msb --oci-only
verify-backends
  workspace: /home/agent/.cache/acq/verify/ws.cI2wkd

== backend: msb (oci-engine kit) ==
  skip  msb: oci-engine kit skipped (msb not installed)

  passed: 0   failed: 0   skipped: 1   warnings: 0

$ adversarial review sub-agent over git diff refactor/acq-devenv-base-image...HEAD
PASS - no findings. Residual risk: real podman install/run path requires live msb host; offline tests split configure/create/start semantics.

Rollback

Revert this PR to restore the msb adapter-owned podman auto-install path and remove oci-engine from the opt-in catalog. Existing sandboxes are not migrated by rollback; recreate affected sandboxes if their provisioned state needs to match the restored adapter behavior.

Security Impact

Positive security impact. The msb adapter no longer grants /dev/net/tun and /dev/fuse unconditionally during provision/start. The oci-engine kit owns OCI-specific setup and gates/revokes device exposure based on engine presence. This narrows default device exposure and also removes the prior sbx/msb asymmetry: both backends now use the same explicit opt-in kit for in-sandbox OCI support.

Stack

Stacked on GSA-TTS/agentic-coding-quickstart#474; base branch is refactor/acq-devenv-base-image, not main.

Closes: #505

[basiliskus]

Reviewed at d2ec9dc.

This change adds oci-engine to the pinned opt-in kit catalog, removes the msb adapter's automatic podman installation and device grants, and moves live OCI verification to a dedicated kit-enabled sandbox. It also documents the breaking migration and advances the patterns bundle to v1.11.0.

Intent: The catalog registration and new-sandbox opt-in path match the stated intent, but the migration does not preserve the documented OCI behavior of existing msb sandboxes across their next restart.

Findings (1)

1. Blocking: Preserve or explicitly migrate the restart-time device grant for legacy msb sandboxes. This hunk removes _acq_msb_grant_oci_devs from acq_backend_start, but sandboxes created before this release have podman on disk without a persisted oci-engine kit ref; after msb stop/start, devtmpfs recreates /dev/net/tun and /dev/fuse with root-only permissions, so rootless docker run/docker build stops working even though the new docs say existing sandboxes keep their installed engine. The normal reattach heal reloads only persisted extra/CLI kits and therefore cannot run the new kit for those legacy sandboxes, and no warning tells the user to add it or recreate. I confirmed the removed call is in git diff 191d501a d2ec9dc; the base comment immediately above it states the regrant is required after every restart because devtmpfs is recreated.
   acq.backends/msb.sh:1002

Verdict: needs changes

Assisted-by: OpenCode [gpt-5.6-sol-latest-guardrails-defaultv2] team-code-review

[mogul]

Thanks. I agree this needs a migration decision rather than silently breaking restart behavior for legacy msb sandboxes.

I also split the unrelated markdownlint work out to #548 so this stack does not keep carrying a local markdownlint fix in every branch. After #548 lands and #474 is rebased, I’ll rebase #541 and address the legacy OCI restart/device-grant finding here.

Current intended direction: either preserve the restart-time grant only for legacy sandboxes with adapter-installed podman and no persisted kit, or make the migration explicitly fail/warn with a concrete remediation ( / add / recreate). I’ll implement the minimal behavior that keeps the docs honest and fails closed rather than silently regressing existing sandboxes.

[mogul]

Landed on main via the collapsed stack: #474 plus corrective #549, released in v4.0.0. This branch is now absorbed and is being deleted.