Use kits to install agents on a devenv-enabled base image

Context

A Slack discussion on 2026-09-15 converged on a possible architecture simplification for acq: stop relying on base images that already contain specific coding agents, and instead use a generic devenv-enabled base image plus agent kits.

The relevant base-image work is in GSA-TTS/agentic-coding-patterns: GSA-TTS/agentic-coding-patterns#395. That pattern is not necessarily NixOS. It layers Nix single-user, devenv, and direnv onto a parametrized BASE_IMAGE, which keeps Ubuntu-like images viable while still giving us Nix/devenv/direnv behavior.

Proposed direction

Have acq depend on a generic devenv-enabled, agent-less base image contract.
Move agent install, config, and startup knowledge into agent kits.
Treat OpenCode, Pi, Goose, Prime Agent, and future harnesses as tools supplied by kits rather than baked into base images or core acq logic.
Keep acq responsible for backend lifecycle, credentials, mounts, network, and kit orchestration.
Let acq run <agent> <workspace> infer the corresponding agent kit when one is not explicitly supplied.
Treat shell as the likely special case because it is not an agent harness.
Consider extracting podman setup into a default OCI engine kit, rather than keeping OCI engine installation embedded in an adapter.

Layering model

User / control plane
  CLI, Agor-like UI, future Factory UI

Normalized session API
  acq today, possibly split later

Harness adapter layer
  OpenCode, Pi, Goose, Prime Agent, future agents

Environment / capability layer
  kits + devenv

Sandbox control layer
  acq lifecycle, credentials, network, mounts

Backends
  msb, sbx

Generic devenv-enabled base
  parametrized BASE_IMAGE + Nix single-user + devenv + direnv

Open questions for discussion

Does acq run devenv up, devenv shell, direnv allow, or a combination?
Which declarations belong at create time versus run or attach time?
What exact neutral schema should agent kits use for entrypoints, startup steps, files, env, volumes, and egress?
How should security-sensitive merge conflicts work when built-in, team, and personal kits overlap?
Should usai-provider remain one agent-aware kit, or should provider-format translation live inside each agent kit?
Should rootless podman setup move into an OCI engine kit that is part of the default kit set?
What minimum contract should acq require from a bring-your-own BASE_IMAGE or ACQ_IMAGE?
How should personal dotfiles be represented: devenv config, a personal kit, a mounted volume, or explicit copy-in?
What current acq run opencode . behavior must remain stable during migration?

Discussion goal

Use this issue and the proposed ADR draft to align before implementation. The immediate goal is not to implement the refactor, but to agree on the architecture, vocabulary, and migration path.

The architecture-level feedback (install pinning, activation contract, create-time vs run-time and a resources: field, supervision models, usai-provider, BYO image contract, egress merge) is on the ADR PR: #474 (comment). Four of the open questions here are not covered there, and the login.gov data team runs a concrete answer to the first one.

Personal dotfiles: a personal kit, and the drop-in hook belongs in the base contract. We already run this shape: a personal kit under ACQ_EXTRA_KITS that ships config files (files[]), installs the user's tools with a pinned nix profile install startup step, and drops shell snippets into ~/.rc.d/ that the team kit wires into bash and zsh. Weighing the alternatives from that experience: devenv config is per-project, so it is the wrong layer for per-user preferences; a mounted host dotfiles directory assumes host paths and host-installed tools that the guest does not have; explicit copy-in is what a kit's files[] already is. The one gap: the ~/.rc.d wiring lives in our team kit today, so a personal kit only works when that team kit is present. That hook should move into the base-image contract or a built-in neutral kit.

Agent kit inference: built-in bundle only, visible, and overridable. acq run opencode . should resolve the agent kit by name match against the built-in bundle, never against extra kits (otherwise a team or personal kit named opencode silently becomes the agent). acq kit ls or the create output should print which kit was selected, and an explicit --kit wins. shell selects nothing.

OCI engine kit: yes, but optional and not in the default bundle. Moving rootless podman out of the msb adapter is right. Keeping it out of the default set matters: it is a create-time install plus egress for every sandbox, and kits like ours never need it.

Behavior that must stay stable during migration. From the team kit's side the load-bearing contract is: --clone semantics with the ACQ_CLONE/ACQ_WORKSPACE guest markers (ADR-0027); startup steps re-applied on every run on msb; ACQ_EXTRA_KITS local paths applied after the built-in bundle; acq exec/acq shell landing in the primary repo with a login shell; ACQ_IMAGE as the image override; and volumes: mounted at boot before any exec. Our scripts/verify asserts each of these against a real --clone sandbox on the active backend, so it can serve as a regression check while the refactor lands.

docs(adr): incorporate review feedback on agent-kit/devenv layering

Status: moving from ADR discussion into incremental implementation

Radiating intent: we are going to start moving the engineering work forward from ADR-0030 with the understanding that the cost of rework is relatively low if later comments materially change the ADR. Comments are still welcome, but comments that affect sequencing or architecture are most useful sooner rather than later.

The implementation will proceed as small deliverables. Unresolved questions stay deferred until the last responsible moment before a concrete increment needs the answer.

Increment Roadmap

Baseline substrate update in patterns

Track the devenv 2.x image/substrate work in devenv image: adopt devenv 2.x and revisit size, startup, and generation agentic-coding-patterns#418. Quickstart implementation should consume that output rather than duplicate it.
Agent-kit metadata and inference

feat(agent-kits): add built-in agent kit metadata and inference #479 defines the first acq-side increment: built-in-bundle-only agent kit inference, visible selected kit, explicit override, and shell as no-agent-kit.
Migration gate for OpenCode stability

test(migration): gate the OpenCode agent-kit migration #480 defines the regression gate and sequencing needed to preserve current acq run opencode . behavior while behavior moves into kits.
Provider facts versus agent rendering

feat(provider): split USAi provider facts from agent config rendering #481 splits usai-provider into neutral provider facts while each agent kit renders its native config.
Neutral shell drop-in hook for personal kits

feat(kits): add neutral shell rc.d hook for personal kits #482 moves the ~/.rc.d hook out of team-specific behavior and into the base contract or a built-in neutral kit.
Human-owned devenv/direnv activation

feat(devenv): implement human-owned activation contract #478 implements the activation contract: surface trust/activation actions, do not auto-approve by default, and allow only explicit ACQ_ opt-in for non-interactive use.
OpenCode agent kit

feat(opencode): move OpenCode install and entrypoint into an agent kit #485 moves OpenCode install and entrypoint ownership into a content-pinned agent kit.
Optional OCI engine kit

feat(oci): extract rootless podman into optional OCI engine kit #483 extracts rootless podman into an explicit optional OCI engine kit, preserving ADR-0020 security decisions.
Bring-your-own image contract

feat(images): define and verify the devenv BYO image contract #484 defines and verifies the minimum image contract, including /nix, devenv major, direnv/shell hook behavior, and diagnostics.
Guest sizing follow-up

#475 remains separate from the devenv adoption story and tracks neutral CPU/memory resource vocabulary.

Deferred to Last Responsible Moment

Non-egress merge semantics for volumes and startup steps are deferred until an increment needs to translate or merge those fields.
Exact BYO image version floors are deferred until the patterns devenv 2.x substrate is available and live-verified.
The detailed acq run opencode . cutover sequence is deferred to the migration-gate increment.
Whether the ~/.rc.d hook belongs in the base image or a built-in neutral kit is deferred until implementation can compare the blast radius.

Orchestration Protocol

Each implementation increment should be assigned to an authoring sub-agent session when feasible.
Each authoring output must be reviewed by a separate adversarial review sub-agent before acceptance.
Review findings must be returned to the authoring sub-agent and addressed before the orchestrator accepts or advances the increment.
Verification transcripts belong in the increment PRs, with live backend verification where the increment changes backend behavior.

Implementation status after sandbox recovery

The earlier sandbox was torn down, so the previous “review queue” state should be treated as stale. I reconstructed the durable state from Git/worktrees and rebased the local work on current origin/main before continuing.

Current durable state:

refactor/acq-devenv-base-image is the integration branch for Use kits to install agents on a devenv-enabled base image #473.
ADR-0030 is present on that branch and remains the architecture reference for the migration.
The first completed implementation increment is still local on that branch: test(migration): gate opencode agent-kit migration.
That increment covers test(migration): gate the OpenCode agent-kit migration #480 by adding test/bats/140-opencode-migration-gate.bats, documenting the migration-sensitive contract in docs/BACKEND_GUIDE.md, and updating scripts/verify-backends as the live sequencing gate.
The prior dirty exploratory worktrees for feat(agent-kits): add built-in agent kit metadata and inference #479 and feat(devenv): implement human-owned activation contract #478 still exist, but they are now treated as spikes to inspect and selectively port, not as active review-in-flight work.

Verification known from the pre-teardown session for the migration-gate increment:

PASS: ./scripts/test-acq-bats test/bats/140-opencode-migration-gate.bats
PASS: ./scripts/test-acq-bats test/bats/35-image-override.bats test/bats/116-clone-option.bats test/bats/110-volumes.bats test/bats/30-dispatch-routing.bats test/bats/70-msb-backend.bats test/bats/140-opencode-migration-gate.bats
PASS: npm run lint:md
PASS: git diff --check

Residual risk / re-verification needed:

Those checks need to be rerun after the rebase and before opening or updating a PR.
Live ./scripts/verify-backends --only sbx and --only msb still require a sandbox-capable host and real backend setup.
The full offline suite previously had an unrelated pre-existing failure in test/bats/90-sbx-startup-kit.bats; if it still reproduces, it should stay out of scope for this increment unless it blocks the migration work.

Next implementation step:

Continue with feat(agent-kits): add built-in agent kit metadata and inference #479: built-in-bundle-only agent-kit inference, visible selected kit, explicit --kit override, and shell selecting no agent kit.
Use the orchestration protocol from this issue: authoring sub-agent when feasible, separate adversarial review sub-agent, feed review findings back before acceptance, and keep at most three sub-agent sessions in flight.

Implementation update

Rebased the local #473 work on current origin/main, refreshed the stale status comment after sandbox recovery, and continued the next increment using the orchestration protocol from this issue.

Current integration branch: refactor/acq-devenv-base-image

New commits on top of the migration gate:

e61520b feat(agent-kits): infer built-in agent kit metadata
a3f3437 test(agent-kits): cover enabled built-in kit selection
f58b04c fix(agent-kits): preserve recorded agent for kit refresh

Implemented for #479:

Added built-in agent-kit metadata for opencode while keeping application deferred until the pinned built-in bundle actually ships an enabled agent kit.
Kept shell as the no-agent-kit case.
Kept explicit --kit higher precedence than implicit inference.
Kept ACQ_EXTRA_KITS out of inference; extras are still appended after selected built-ins and before CLI kits.
Preserved support-kit ordering and existing acq run opencode . behavior.
Added host-side recorded-agent provenance so future enabled agent kits can participate in heal/refresh paths instead of being applied only at create time.
Addressed the adversarial review finding that enabled agent kits could otherwise be omitted from reattach/start/restart/bundle-refresh and still get current provenance.

Verification:

PASS: bash -n acq acq.backends/agents.sh acq.backends/common.sh acq.backends/msb.sh acq.backends/sbx.sh
PASS: git diff --check
PASS: ./scripts/test-acq-bats test/bats/30-dispatch-routing.bats test/bats/36-agent-catalog.bats test/bats/50-kit-list-completeness.bats test/bats/74-msb-restart-durability.bats test/bats/85-kit-provenance.bats test/bats/95-kit-ref-persistence.bats test/bats/140-opencode-migration-gate.bats (106/106)
PASS: npm run lint:md

Known residual:

./scripts/test-acq-bats test/bats/90-sbx-startup-kit.bats still has the pre-existing unrelated failure in heal(sbx): the playbook stale-probe uses the AGENTS.md footprint, not .git; the new agent-kit-heal(sbx): forced refresh includes recorded agent kit case in that file passes.
Live backend verification (./scripts/verify-backends) was not run in this session because it requires a sandbox-capable host/backend setup.

Cleanup:

Removed inactive clean worktrees: agent-kit-scout, neutral-rcd-hook, robust-vampirebat, and review-opencode-migration-gate.
Left active Paseo workspaces and dirty exploratory branches in place.
opencode-migration-gate could not be removed via git worktree remove because initialized submodules are present; left it untouched rather than forcing removal.

Epic Status: ADR-0030 Implementation

Current integration branch: refactor/acq-devenv-base-image

Latest pushed commit: 0f6a6b8 chore(shellcheck): document optional kit-list argument

Summary

Group	Issues	Status
Landed on branch	#480, #479, #478, #481	Implemented on `refactor/acq-devenv-base-image`; sub-issues remain open until the PR/branch lands
Backlog	#482, #485, #483, #484	Not implemented yet
Separate track	#475	Intentionally factored out of this epic branch

Landed on Branch

Issue	What landed	Next	Deferred / Notes
#480 — migration gate for OpenCode stability	Added `test/bats/140-opencode-migration-gate.bats`; updated `docs/BACKEND_GUIDE.md`; updated `scripts/verify-backends` so migration behavior is explicitly gated	Keep the gate green through the OpenCode agent-kit cutover; run live backend verification when available	Actual OpenCode install/entrypoint migration belongs to #485
#479 — built-in agent-kit metadata and inference	Added built-in agent-kit metadata for `opencode`; `shell` selects no agent kit; explicit `--kit` suppresses inference; `ACQ_EXTRA_KITS` cannot drive inference; recorded-agent provenance supports future heal/refresh	Enable application only once the pinned built-in bundle ships a valid `opencode` kit	OpenCode kit application remains intentionally deferred; MSB fallback install behavior remains for now
#478 — human-owned devenv/direnv activation	Detects `.envrc` and devenv markers; default behavior advises only; `ACQ_ACTIVATE_PROJECT_ENV=1` opts into already-approved `direnv export`; internal helper/probe execs are protected; SBX/MSB review fixes landed	Ensure future shell hook/base-image work composes with this instead of duplicating it	No automatic `devenv shell`; current opt-in only uses `direnv export` when `.envrc` exists
#481 — provider facts vs. agent rendering	Added transitional `USAI_PROVIDER_*` fallback defaults; routed SBX/MSB default USAi binding through them; preserved explicit `--host/--env` precedence; ADR-0030 now defines provider-facts artifact contract	Consume the authoritative patterns-side `usai-provider` artifact once available at the pinned ref	Quickstart does not implement the patterns-side artifact; agent-specific provider config rendering remains future agent-kit work

Backlog

Issue	Current state	Next	Deferred / Notes
#482 — neutral shell rc.d hook for personal kits	ADR-0030 records expected hook shape and guardrails; no code landed	Decide base-image contract vs. built-in neutral capability kit; implement deterministic shell drop-in sourcing	Must be non-secret-bearing and must not duplicate devenv behavior
#485 — OpenCode agent kit	#479 scaffolding and #480 migration gate are in place	Consume patterns-side OpenCode agent kit once available; enable only when artifact is present and valid	Removing/demoting fallback install/start behavior waits until kit exists and gates pass
#483 — optional OCI engine kit	ADR-0030 records direction; no code landed	Define optional OCI capability role and kit behavior; preserve ADR-0020 security decisions	Must remain opt-in, not part of the default bundle
#484 — devenv BYO image contract	ADR-0030 records `/nix`, devenv major, direnv/shell hook, and workspace `devenv.nix` concerns; no checks landed	Add diagnostics/checks for `ACQ_IMAGE` / `BASE_IMAGE` once substrate details are stable	Exact version floors and live checks wait for patterns-side substrate availability
#475 — neutral guest resources field	Separate backlog item; ADR-0030 explicitly factors guest sizing out of this story	Define `resources:` CPU/memory vocabulary independently	No implementation belongs to the current #473 branch

Commit Map

Area	Commits
ADR / architecture	`0791da3`, `5ca2efc`, `5f07235`, `f7ce258`, `52a17c7`, `77ee43d` after rebase
#480	`c62f24d` after rebase
#479	`2ec7810`, `4fc7b26`, `b61916f` after rebase
#478	`823de9a`, `97d00a5` after rebase
#481	`31d0588`, `77ee43d` after rebase
Pre-commit/ShellCheck cleanup	`e21779d`, `0f6a6b8`

Verification

Check	Latest local result
Shell syntax	PASS: `bash -n acq acq.backends/agents.sh acq.backends/common.sh acq.backends/msb.sh acq.backends/sbx.sh`
ShellCheck	PASS: `printf %s\\n acq acq.backends/.sh scripts/test-acq-lib.sh scripts/test-acq-bats test/bats/.bats test/bats/helper.bash \| xargs -r -n8 shellcheck --severity=warning`
Markdown lint	PASS: `npm run lint:md`
Diff hygiene	PASS: `git diff --check HEAD`
Focused Bats	PASS: `./scripts/test-acq-bats test/bats/50-kit-list-completeness.bats test/bats/30-dispatch-routing.bats test/bats/72-msb-agent-user.bats test/bats/140-opencode-migration-gate.bats` (`99/99`)

Known Residuals

Residual	Notes
Live backend verification	`./scripts/verify-backends` has not been run in this session because it requires a sandbox-capable backend host
Known unrelated test failure	`test/bats/90-sbx-startup-kit.bats` still has the pre-existing failure in `heal(sbx): the playbook stale-probe uses the AGENTS.md footprint, not .git`

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`c8150e3 feat(provider): load usai facts artifact`	#481	Adds the quickstart-side parser/validator for `provider-facts/usai.env`-style metadata, with fallback behavior preserved

Updated #481 Status

Area	Status
Parser	Landed: `acq_provider_facts_load FILE` parses static `KEY=VALUE` data; it does not source or eval the file
Validation	Landed: validates schema, provider id, host/bind hosts, HTTPS URLs, and env var names
Fallback	Landed: missing artifact leaves current fallback defaults intact; invalid artifact fails closed without partial override
Backend binding	Landed: SBX/MSB default USAi binding now uses `USAI_PROVIDER_BIND_HOSTS` while preserving explicit `--host/--env` sidecar precedence
Tests	Landed: valid, missing, invalid, and fallback artifact cases
Still deferred	Automatic fetch/load from the pinned `usai-provider` kit ref; removing/demoting fallback defaults once the patterns-side artifact exists

Verification

Check	Result
`bash -n acq.backends/common.sh acq.backends/sbx.sh acq.backends/msb.sh`	PASS
`git diff --check`	PASS
focused ShellCheck	PASS
`./scripts/test-acq-bats test/bats/50-kit-list-completeness.bats test/bats/40-secret-set.bats test/bats/71-msb-provision-secrets.bats test/bats/77-usai-rotate.bats test/bats/30-dispatch-routing.bats`	PASS (`98/98`)

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`08a00b4 feat(provider): load facts from usai kit`	#481	Automatically attempts to load `provider-facts/usai.env` from the pinned `usai-provider` kit, preserving fallback defaults when absent and failing closed when present-but-invalid

Updated #481 Status

Area	Status
Static parser	Landed in `c8150e3`: parses `KEY=VALUE` facts as data, not shell
Validation	Landed in `c8150e3`: validates schema, provider id, host/bind hosts, HTTPS URLs, and env var names
Automatic kit consumption	Landed in `08a00b4`: `acq` tries the pinned `USAI_KIT` artifact after backend resolution
Missing artifact fallback	Landed: current pinned kit can lack the artifact without changing behavior
Invalid artifact handling	Landed: present-but-invalid artifact stops execution instead of partially overriding provider facts
Still deferred	Removing fallback defaults after patterns publishes the artifact; agent-specific config rendering remains agent-kit work

Verification

Check	Result
`bash -n acq.backends/common.sh acq.backends/sbx.sh acq.backends/msb.sh`	PASS
`git diff --check`	PASS
focused ShellCheck on changed shell/test files	PASS
`./scripts/test-acq-bats test/bats/50-kit-list-completeness.bats test/bats/40-secret-set.bats test/bats/71-msb-provision-secrets.bats test/bats/77-usai-rotate.bats test/bats/30-dispatch-routing.bats`	PASS (`101/101`)

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`2982ba5 feat(kits): source neutral rc snippets`	#482	Adds MSB support for the neutral `~/.rc.d/*.sh` hook contract in the acq-owned login profile bridge

Updated #482 Status

Area	Status
Hook location	Landed for MSB: `~/.rc.d/*.sh`
Shell coverage	Landed for bash/zsh login shells through the `.profile` bridge
Ordering	Landed: deterministic lexical shell glob order
Idempotency	Landed: bridge remains acq-owned and rewrite-guarded
Guardrails	Landed: no `direnv allow`; does not duplicate `ACQ_ACTIVATE_PROJECT_ENV` behavior
Still deferred	Built-in neutral capability kit artifact; SBX/base-image parity if needed; fish/nushell native conf.d behavior

Verification

Check	Result
`bash -n acq.backends/msb.sh test/bats/72-msb-agent-user.bats`	PASS
`git diff --check`	PASS
focused ShellCheck	PASS
`./scripts/test-acq-bats test/bats/72-msb-agent-user.bats test/bats/140-opencode-migration-gate.bats`	PASS (`50/50`)

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`932a8b7 test(kits): cover neutral rc snippet delivery`	#482	Adds SBX/MSB fixture coverage that neutral kit `files:` payloads can deliver `~/.rc.d/*.sh` snippets

Updated #482 Status

Area	Status
MSB shell bridge	Landed in `2982ba5`: sources `~/.rc.d/*.sh` for bash/zsh login shells
SBX neutral delivery	Covered in `932a8b7`: neutral kit `files/home/agent/.rc.d/*.sh` materializes into sbx-v2 kit payloads
MSB neutral delivery	Covered in `932a8b7`: neutral kit files copy to `/home/agent/.rc.d/*.sh` and the rc.d tree is chowned to agent
Ordering	Covered by the shell glob contract and tests for bridge loop behavior
Still deferred	Publishing a built-in neutral capability kit artifact; fish/nushell native conf.d behavior; any additional SBX base-image shell hook if needed beyond file delivery

Verification

Check	Result
syntax / diff	PASS
focused ShellCheck	PASS
filtered rc.d + migration Bats	PASS (`9/9`)

Known residual: full test/bats/90-sbx-startup-kit.bats still has the unrelated stale-probe/git-identity failure; the new SBX rc.d case passes.

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`0439013 feat(images): add non-enforcing contract doctor`	#484	Adds `acq doctor NAME` diagnostics for ADR-0030 BYO/devenv image contract checks on existing sandboxes

Updated #484 Status

Area	Status
Diagnostic entrypoint	Landed: `acq doctor NAME` inspects an existing sandbox; bare `acq doctor` behavior is preserved
Backend support	Landed for SBX and MSB via `acq_backend_doctor_sandbox` hooks
Checks	Landed: `HOME`, agent user, `/nix`, `nix`, `devenv`, `direnv`, `/home/agent` writability, best-effort passwordless sudo probe, `~/.rc.d`, shell startup hook reference
Enforcement	Non-enforcing by design: missing capabilities warn and return success; inability to inspect the sandbox still fails
Review fixes	Addressed SBX HOME/user context, sudo wording, direct shell-script test coverage, extra-argument rejection, and stricter rc.d source detection
Still deferred	Exact `devenv` version floors; create-time hard enforcement; live backend validation

Verification

Check	Result
`./scripts/test-acq-bats test/bats/65-doctor-image-contract.bats test/bats/60-help.bats`	PASS (`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.bats`	PASS
`git diff --check`	PASS
focused ShellCheck on changed files	PASS

Quickstart-side progress update

New pushed commit on refactor/acq-devenv-base-image:

Commit	Issue	Summary
`9be74d3 feat(agent-kits): validate built-in agent artifacts`	#485	Adds static validation/gating for future built-in agent-kit artifacts without enabling OpenCode yet

Updated #485 Status

Area	Status
Artifact validation	Landed: validates neutral `spec.yaml`, expected kit name, and direct `agent.name` / `agent.entrypoint` metadata
Fail-closed behavior	Landed: missing/wrong-schema/wrong-name/wrong-agent metadata keeps inference deferred
Current behavior	Preserved: `opencode` remains disabled by default; current migration gate stays stable
Fetch/cache behavior	Landed: readiness checks are cached per agent/ref during an invocation to avoid repeated fetch/validation
Explicit override	Preserved: explicit `--kit` still suppresses implicit built-in agent-kit inference
Still deferred	Real patterns-side OpenCode agent kit; enabling the OpenCode built-in kit; removing/demoting MSB npm fallback install

Verification

Check	Result
`./test/vendor/bats-core/bin/bats test/bats/140-opencode-migration-gate.bats test/bats/85-kit-provenance.bats test/bats/50-kit-list-completeness.bats test/bats/30-dispatch-routing.bats`	PASS (`93/93`)
`bash -n acq acq.backends/common.sh acq.backends/agents.sh acq.backends/kit-translate.sh`	PASS
focused ShellCheck	PASS
`git diff --check`	PASS

Quickstart-side progress update

Continued the ADR-0030 work on refactor/acq-devenv-base-image (draft PR #474), focused on the quickstart-side work that has no patterns-substrate dependency while the devenv 2.x image, USAi facts artifact, and OpenCode agent kit are still unpublished.

CI is green again on the epic branch

The draft PR was red on Pre-commit and bash 3.2 compat (the offline bats suite). Fixed and merged current main:

Commit	Summary
`4bcca99 test(agent-kits): fix sbx heal test flake and agent-kit refresh gate`	Fixes the two offline-suite failures
`d946f27 feat(oci): add opt-in OCI-engine capability kit selection`	First, conservative slice of #483
`c889723 Merge origin/main`	Resolves the `acq.backends/msb.sh` conflict (Windows path-form/`_acq_msb_cli` wrapping from #463/#464 vs. the epic's `ACQ_ACTIVATE_PROJECT_ENV` activation logic — both preserved)

Root causes fixed:

agent-kit-heal(sbx): forced refresh includes recorded agent kit broke when the selection gate tightened from acq_agent_builtin_kit_enabled to acq_agent_builtin_kit_ready (validated artifact). OpenCode enablement is deferred until the pinned patterns bundle ships a valid opencode agent kit, so the test now stubs readiness offline to exercise the refresh path without falsely enabling OpenCode.
heal(sbx): the playbook stale-probe uses the AGENTS.md footprint, not .git passed in CI but failed on hosts with a configured git identity (which injects a git-identity kit-add). Neutralized the git identity in the probe subshell, matching the same fix on fix(acq): use sandbox workspace for github scoping #476.

All four PR checks (Pre-commit, bash 3.2 compat, PR Lint, Markdown Quality) are now green at c889723.

#483 (OCI engine kit) — first increment landed

Implemented the quickstart-side, opt-in selection + allowlisting + tests for an oci-engine capability kit, off by default (ACQ_ENABLE_OCI_KIT) and gated on a readiness probe of the pinned patterns ref. Because the patterns kit body is unpublished, opting in currently no-ops with a single notice; the msb adapter's _acq_msb_ensure_oci provisioning is untouched and remains the active OCI mechanism. Details, verification, and the deferred/sequenced follow-ups are tracked on #483.

Decisions confirmed this session

The OCI-engine kit body lives in agentic-coding-patterns, not quickstart. This quickstart increment only wires selection/allowlisting/tests; the patterns kit is a separate PR (the trigger that flips readiness to true).
Safer sequencing: land the neutral opt-in selection + contract + tests now, and defer the msb-adapter podman removal + sbx forced-heal wiring until the kit path is live-verified (per feat(oci): extract rootless podman into optional OCI engine kit #483's own acceptance criteria). Those deferred items are recorded on feat(oci): extract rootless podman into optional OCI engine kit #483 with their trigger condition.

Still blocked on patterns substrate (unchanged)

#481 fallback-removal, #484 version floors, and #485 OpenCode enablement remain deferred pending the patterns-side devenv 2.x image, provider-facts/usai.env artifact, and OpenCode agent kit.

Quickstart-side progress update

Continued the ADR-0030 work on refactor/acq-devenv-base-image / draft PR #474.

Latest pushed commits:

Commit	Summary
`59d10f0 feat(kits): wire neutral rc snippets`	Completes the quickstart-side neutral rc.d bridge work across msb and sbx, preserving/reconciling the rc-snippet docs from #511
`892a183`	Merges current `origin/main` into the integration branch and resolves the verifier header conflict, keeping the ADR-0030 gate language and the current sbx `>= 0.39.0` floor
`9a82061 feat(kits): harden pending kit gates`	Adds quickstart-side hardening that is useful before the remaining patterns artifacts land

Updated scope tracking

#474 now has a fully qualified Closes: line for #478, #479, #480, #481, #482, #483, #484, and #485.

#475 has been removed from the PR closure scope and remains a separate resource-sizing track.

What landed since the prior #473 update

Area	Status
#482 rc.d hook	The shared `acq_login_profile_rc_block` now drives both msb and sbx; sbx installs the bridge through post-create `sbx exec` after an exec-readiness wait; tests now execute the generated block and verify deterministic byte-order sourcing
#483 OCI kit prep	Quickstart now tracks the selected support-kit boundary separately from total built-in kits, so the optional `oci-engine` capability kit is not misclassified as an agent kit during sbx forced refresh; msb suppresses adapter-owned podman provisioning only when the OCI kit is actually selected and fetched for that provision
#484 image diagnostics	`acq doctor NAME` diagnostics now report available tool versions and separate the missing `~/.rc.d` directory warning from the missing shell-startup-hook warning, while remaining non-enforcing
#485 OpenCode gate	Added coverage that a valid future OpenCode kit artifact remains deferred while built-in OpenCode kit enablement is disabled, preserving current `acq run opencode .` behavior

Current patterns dependencies

Dependency	State	Quickstart impact
GSA-TTS/agentic-coding-patterns#395	Merged	Generic devenv image exists as the baseline artifact
GSA-TTS/agentic-coding-patterns#418	Open issue	Exact devenv 2.x image/version floors remain pending
GSA-TTS/agentic-coding-patterns#437	Open PR, review required	OCI-engine kit readiness remains pending until merge plus quickstart pin bump
OpenCode agent kit artifact	Still pending patterns-side publication	#485 enablement remains gated

Verification

Check	Result
`./scripts/test-acq-bats`	PASS (`597/597`)
`./scripts/test-acq-bats test/bats/66-oci-engine-kit.bats test/bats/71-msb-provision-secrets.bats test/bats/65-doctor-image-contract.bats test/bats/140-opencode-migration-gate.bats test/bats/90-sbx-startup-kit.bats`	PASS (`70/70`)
`bash -n acq acq.backends/agents.sh acq.backends/common.sh acq.backends/msb.sh acq.backends/sbx.sh scripts/test-acq-lib.sh scripts/test-acq-bats test/bats/helper.bash test/bats/65-doctor-image-contract.bats test/bats/66-oci-engine-kit.bats test/bats/71-msb-provision-secrets.bats test/bats/140-opencode-migration-gate.bats test/bats/90-sbx-startup-kit.bats scripts/verify-backends`	PASS
`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
`git diff --check`	PASS
`npm run lint:md`	PASS (`0` issues)
Adversarial AI code review	PASS after fixes; findings addressed before push

Residual risk: live ./scripts/verify-backends was not run in this session because it requires a sandbox-capable host/backend setup.

feat(schema): add optional agent block to hybrid/v1 kit schema (#454)

feat(acq-kits): add opencode agent-harness kit (SHA-pinned release bi…

Shipped in v4.0.0

The devenv-base / agent-kit migration tracked by this issue is implemented, released, and verified end-to-end on both backends.

Release: https://github.com/GSA-TTS/agentic-coding-quickstart/releases/tag/v4.0.0
Patterns pin: agentic-coding-patterns v1.12.0 (56d1f5f49ef928f50e61aa64a93d618b3d21c415)

What landed

Core migration arrived in #474, with the capability/agent-kit layer completed by #549 and the shared markdownlint fix factored out to #548.

Agent-less, devenv-enabled base image contract (ADR-0030), with a non-enforcing BYO image doctor.
Built-in agent-kit metadata + inference; OpenCode install/entrypoint moved into the pinned opencode agent kit.
Native MSB OpenCode npm fallback removed — acq now fails closed if the kit is unavailable rather than installing opencode-ai from npm.
Rootless podman moved into the opt-in oci-engine catalog kit; adapter-owned MSB OCI auto-install and unconditional device grants retired.
USAi provider facts split from agent config rendering (provider-facts/usai.env), with a transitional fallback.
Neutral ~/.rc.d/*.sh shell-snippet contract, bridged on both msb and sbx.

Breaking changes (see v4.0.0 notes)

No default podman/OCI tooling — opt into oci-engine via acq configure, --kit, or ACQ_EXTRA_KITS.
No native OpenCode npm fallback — OpenCode comes from the pinned agent kit.
Existing MSB sandboxes with adapter-installed podman are not migrated in place; recreate them or add oci-engine.

Verification

Full offline bats suite green in CI; targeted suites (agent catalog, kit-list completeness, opencode migration gate, BYO doctor, provenance, verify-capture, exec-bits) pass locally.
Live scripts/verify-backends on the release branch: msb 15/0/1, sbx 10/0/1 (the single skips are the no-GitHub-token playbook fetch).

Closed by this work

#478, #479, #480, #481, #482, #483, #484, #485, #505.

Deliberately out of scope / tracked separately

Add a neutral resources: kit field for guest CPU and memory #475 — resource sizing — being chased up separately.
devenv image: adopt devenv 2.x and revisit size, startup, and generation agentic-coding-patterns#418 — likewise handled separately.
Open ADR-0030 follow-ups: stacked-kit merge semantics (Track ADR-0030 stacked-kit merge semantics beyond egress #533) and the BYO image contract hardening.

Closing this umbrella issue as the migration is shipped in v4.0.0.

Use kits to install agents on a devenv-enabled base image #473

Description

Context

Proposed direction

Layering model

Open questions for discussion

Discussion goal

Activity

basiliskus commented on Sep 15, 2026

mogul commented on Sep 16, 2026

Status: moving from ADR discussion into incremental implementation

Increment Roadmap

Deferred to Last Responsible Moment

Orchestration Protocol

mogul commented on Sep 17, 2026

Implementation status after sandbox recovery

mogul commented on Sep 17, 2026

Implementation update

1 remaining item

mogul commented on Sep 17, 2026

Epic Status: ADR-0030 Implementation

Summary

Landed on Branch

Backlog

Commit Map

Verification

Known Residuals

mogul commented on Sep 17, 2026

Quickstart-side progress update

Updated #481 Status

Verification

mogul commented on Sep 17, 2026

Quickstart-side progress update

Updated #481 Status

Verification

mogul commented on Sep 17, 2026

Quickstart-side progress update

Updated #482 Status

Verification

mogul commented on Sep 18, 2026

Quickstart-side progress update

Updated #482 Status

Verification

mogul commented on Sep 18, 2026

Quickstart-side progress update

Updated #484 Status

Verification

mogul commented on Sep 18, 2026

Quickstart-side progress update

Updated #485 Status

Verification

mogul commented on Sep 21, 2026

Quickstart-side progress update

CI is green again on the epic branch

#483 (OCI engine kit) — first increment landed

Decisions confirmed this session

Still blocked on patterns substrate (unchanged)

mogul commented on Sep 24, 2026

Quickstart-side progress update

Updated scope tracking

What landed since the prior #473 update

Current patterns dependencies

Verification

mogul commented on Oct 6, 2026

Shipped in v4.0.0

What landed

Breaking changes (see v4.0.0 notes)

Verification

Closed by this work

Deliberately out of scope / tracked separately

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions