Epic: sbx↔msb backend parity #234

What this tracks

Coordination issue for bringing the acq msb backend to parity with sbx,
so a kit can declare backends: [sbx, msb]. This replaces the branch-only
exploration doc (docs/explorations/acq-backend-parity.md) that the child issues
used to reference; the decision rationale for the biggest piece lives in
ADR-0014.

Scope note: this lists remaining work. Gaps already resolved in earlier PRs
(the sbx port-publish carry #221 /
#223, the msb agent install/launch and
github-via-REST secret binding #230 which closed
#203, and the removal of opencode-web.sh in
favor of the openchamber kit) are done and not re-listed.

Remaining work

• acq: implement neutral port-publish + background kit vocabulary (ADR-0013) and msb consumer #224 — Neutral port-publish + background vocabulary + msb consumer (gap A).
  The largest blocker to backends: [sbx, msb]. Design accepted in ADR-0014; sbx
  half already landed. Implemented on feat/msb-parity: neutral
  publishedPorts + background read neutral-first with a deprecated
  backend_extras.sbx fallback; msb consumer maps entries to -p HOST:GUEST
  and detaches background startup commands. PATTERNS_KIT_REF has now been
  bumped to the released neutral-schema commit (see cross-repo below), so the
  fields light up end-to-end.
• acq(msb): drop unreachable SUPPORTS_SNAPSHOTS flag to 0; wire acq snapshot as follow-up #225 — msb SUPPORTS_SNAPSHOTS flag reconciled (gap B). msb --tree
  (0.6.7) shows msb snapshot does exist as a full CLI verb — so the earlier
  "no CLI verb" reasoning was wrong. Wiring acq snapshot is beyond sbx
  parity, so it stays deferred; implemented: flag set to 0 (matches what
  acq surfaces, not what msb can do) with an honest comment + test assertion.
• acq(msb): bind generic custom-endpoint secrets at provision (not just usai) #226 — Generic custom-endpoint secret binding on msb (gap C).
  Implemented: the msb binding is no longer a fixed usai+github table — any
  stored service with a resolved host/env binds via --secret ENV@HOST. Added a
  non-secret endpoint sidecar (host+env only, 0600, value never on argv/disk)
  so the store persists the pair; multi-host ENV@HOST[,HOST...] supported.
• docs(BACKEND_GUIDE): refresh version banner + msb differences/limitations table (parity gaps B/C/D/I) #227 — BACKEND_GUIDE refresh follow-through (gap J).
  Banner + tables refreshed; the differences table / capability flags now read
  shipped (not "scheduled") for A–C, and reflect the PATTERNS_KIT_REF bump
  and the live-verified post-hoc port publish. Done on feat/msb-parity.
• test-acq: 'msb auto-detect falls back to msb' fails locally when a real sbx is on PATH (PATH-robustness) #217 — test-acq PATH robustness (gap H). Implemented: the
  backend-detection subshells constrain PATH (stub dir + a coreutils dir) so a
  real host sbx on PATH can't leak into _auto_detect_backend; both detect
  cases deterministic. (Reconciled with the host-agnostic variant that later
  landed on main.)
• Post-hoc port publish on msb via ssh serve + ssh -L (gap K) #238 — Post-hoc port publish on msb via ssh serve (gap K). Expose a
  port on a running sandbox without re-create, via msb ssh serve + OpenSSH
  -L, wired behind acq ports --publish. Closes the last port-capability gap
  vs. sbx; flips SUPPORTS_PORT_FORWARD=1. Design in ADR-0015. Implemented and
  live-verified (see Wave 4). Closes on feat/msb-parity merge.

Wave 1 landed (2026-07-29). #224, #225, #226, #217 implemented,
code-reviewed, integrated onto feat/msb-parity (omnibus PR
#233).

Wave 2 landed (2026-07-29). #227 (shipped-state doc pass) and #238 (gap K,
post-hoc ports via ssh serve) integrated.

Wave 3 landed (2026-07-29). Adapter hardening: oversized-function split
(+ a set -e regression fix caught in review), the dotted-service-name
fail-closed fix, and the #239 evaluation (design note + guards). patterns
gap-G validator hardening verified already-resolved on patterns main.

Wave 4 landed (2026-08-01). Second review round on PR #233 addressed
(background-flag / sbx-self-backgrounding accuracy, post-hoc-publish liveness
so a dead tunnel fails closed, ssh IdentitiesOnly/-F none, chown -R -P,
ADR-0015 accepted). Merged main twice (adopting the merged
#241 / #248 / #249). PATTERNS_KIT_REF
bumped to the released neutral-schema commit
(6230faa53ae88e125f04521ab8eee932eeaacdbc) now that the patterns schema and
openchamber kit are on patterns main (below), satisfying ADR-0014's cross-repo
gate. Fixed a LIST-mode set -e hard-fail in acq ports. Added
scripts/verify-ports-live (live harness for the ADR-0015 path). De-referenced
ephemeral tracker refs from code/docs and generalized AGENTS.md from SBX-only to
the sbx/msb sandboxing backend. Live on a macOS + msb 0.6.7 KVM host:
scripts/verify-backends 14/0 (1 skip: playbook fetch w/o gh token) and
scripts/verify-ports-live 15/0 (happy-path publish + host-reaches-guest,
LIST, fail-closed negative, teardown). Offline scripts/test-acq 500/0,
scripts/test-migrate-or-halt 57/0.

Remaining: merge PR #233 (re-review
requested); after which #224/#227/#238 close with it.

Cross-repo (patterns)

• patterns: publishedPorts + background schema/validator (gap A dep).
  Merged — feat(kits): add neutral publishedPorts + background to hybrid/v1 schema agentic-coding-patterns#276 added the neutral fields to
  kit-hybrid-v1.schema.json and enforced them in validate-kits.py with tests.
  On patterns main. quickstart's PATTERNS_KIT_REF is bumped to a main
  commit that includes it, lighting up the acq: implement neutral port-publish + background kit vocabulary (ADR-0013) and msb consumer #224 consumer.

• patterns openchamber msb/ppp parity (feat(openchamber): adopt neutral publishedPorts + background; sbx+msb parity agentic-coding-patterns#283).
  Merged. The openchamber kit adopts the neutral publishedPorts/background
  vocabulary and declares backends: [sbx, msb]; the no-sudo install PATH fix and
  the honest transient-vs-definitive fast-fail landed in the same PR. This is the
  home for the retired opencode-web.sh successor — with the kit on patterns
  main and the quickstart pin bumped, the browser-OpenCode UI is covered on msb,
  not just sbx.

• patterns — harden validate-kits.py (gap G). Reject malformed
  files[].mode / commands[].user / unsafe files[].path at the shared kit
  validator. Verified RESOLVED on patterns main (2026-07-29): schema
  patterns ^0[0-7]{3}$ (mode), ^[0-9]+$ (user), ^/[A-Za-z0-9._/-]+$ (path)
  are enforced per-kit, a code-level _SAFE_PATH_RE adds defense-in-depth, and
  test_validate_kits_injection.py regression-tests reject mode: "0644; id"
  and user: "0; id" (live-confirmed reject vs. accept).

Accepted (no action; recorded for context)

• Gap E — no state-preserving in-place kit heal on msb. msb re-applies kits
  idempotently (never destroys state); revisit if microsandbox ships a
  state-preserving in-place kit-add primitive. Recorded in ADR-0011.
• Gap I — verify-backends msb row can't run in CI. Needs host /dev/kvm
  (no nested sandboxes). Run manually on a KVM host after each release / after ≥3
  behavior-affecting fixes (AGENTS.md §8.3); documented in BACKEND_GUIDE.

Adapter hardening (follow-up, not a parity gap)

• msb adapter: use --script for kit-command injection instead of copy+sh -c #239 — Evaluated msb --script for kit-command injection. Concluded
  NOT a clean win (kit argv already travels as separate positional params, not
  an interpolated sh -c; and kit commands also run mid-life via
  acq_backend_apply_kit/ensure_kits_applied where a create-time --script
  can't apply). Landed as a load-bearing design note + regression guards
  (comment-only) rather than a refactor.
• Split oversized msb functions (§13.3 size limit). Done —
  _acq_msb_exec_command, acq_backend_secret_set, acq_backend_secret_rm
  split into ≤50-line helpers (behavior-preserving; code review also caught &
  fixed a set -e shift-abort regression). acq_backend_provision remains
  over-limit and is a separate future extraction (create-flag assembly /
  mount translation / secret-binding seams).
• acq_secret_meta_list dotted-name mis-scope. Fixed — _acq_secret_key
  now fails closed on dotted service/sandbox names (hosts-with-dots still
  allowed) and meta_list anchors on the sandbox prefix; +regression tests.
• Flaky msb ports tests (ephemeral-port selection). Resolved — the
  gap-K port tests use a deterministic test seam (ACQ_MSB_FORCE_SERVE_PORT) and
  a persisted per-process counter (not $$), with a distinct-port assertion, so
  the stubbed serve+ssh background processes no longer race. scripts/test-acq
  is stable at 500/0 across repeated runs.

Fast-follow (tracked separately, out of this epic's parity scope)

• acq(msb): acq secret ls shows no rows on a Linux secret-tool keychain host #252 — acq secret ls shows no rows on a
  Linux secret-tool keychain host (enumerates the file dir only).
• acq run: acq run --name X -- CMD (no agent positional) silently no-ops instead of failing closed #253 — acq run --name X -- CMD with no
  agent positional silently no-ops instead of failing closed.
• docs(CONTRIBUTING): update stale sbx-kits/ path to acq-kits/ #255 — CONTRIBUTING.md still references
  the legacy sbx-kits/ path (should be acq-kits/).

Sequencing

ADR-0014 (accepted) ──> #224 (neutral fields + msb consumer) ──> patterns openchamber Increment B (merged)
                                     └──> ADR-0015 / #238 (post-hoc publish via ssh serve, gap K)
#225 (snapshot flag reconcile) ── independent, low-risk (beyond-parity; no verb build)
#226 (msb generic secrets)     ── independent
#217 (test PATH robustness)    ── independent, low-risk
#227 (guide follow-through)    ── trails A–C
#239 (--script eval)           ── independent adapter hardening
patterns validator (gap G)     ── parallel, shared security choke point

All parity work is implemented and integrated on feat/msb-parity; the epic
closes when PR #233 merges.

AI-assisted (OpenCode); requires human review.