Epic: safe kit-bundle update propagation — acq detects stale sandboxes + offers refresh #235

Goal

When USAi adds models (or any built-in kit config changes) a maintainer updates the canonical config in agentic-coding-patterns once, pins it in Quickstart, and existing sandboxes can then be safely refreshed. Today the model-catalog authoring path works, but existing sandboxes silently drift.

Investigation summary (verified against code)

• Model-catalog authoring already works. agentic-coding-patterns ships // BEGIN/END GENERATED USAI MODELS markers in the usai-provider kit's opencode.jsonc, and sync-usai-models.mjs splices only between the markers (replaceBetween()), with bounded timeout + size + shape validation. So "update models easily" is already a npm run sync:usai-models + review + commit workflow.
• Delivery to a sandbox: the kit's merge-global-config.mjs runs at startup — COPY verbatim into an empty global ~/.config/opencode/opencode.jsonc, else DEEP-MERGE the kit's keys in. Audit confirms it preserves unrelated keys and user permission sub-keys (per-leaf override only), and the kit ships no mcp, so user MCP allow-lists are untouched.
• The real gap: for an existing sandbox, acq run → acq_backend_ensure_kits_applied on sbx only injects kits that are absent (feature-probe); it does not detect an installed bundle older than the local PATTERNS_KIT_REF, nor offer a refresh. msb re-applies all four idempotently every run.
• No provenance: nothing inside a sandbox records the installed patterns SHA / bundle version, so "is this sandbox current?" is unanswerable today.
• PATTERNS_KIT_REF is a full 40-char SHA (acq.backends/common.sh); built-in bundle = usai-provider, agentic-coding-playbook, zscaler-ca-certificate, git-ssh-sign. acq runs from a git checkout (symlink-aware).

Design approved 7/7 via multi-model higher-order consensus (architect, security, devex, ai_ml, pm, contrarian, scope_steward).

Phases (2 ordered PRs + deferred follow-up)

• PR1 (Patterns): additive provenance field on the hybrid/v1 kit schema (repo + full SHA + bundle version + kit names) + a permission-preservation regression test (prove a user's permission sub-keys survive a merge — no behavior change; audit showed the current merge is already safe) + a drift-guard test (fail if the acq-kits and sbx-kits opencode.jsonc payloads ever diverge, so a model update to one but not the other is caught). PR1: kit-bundle provenance schema field + permission-preservation & acq/sbx drift-guard tests agentic-coding-patterns#273
• PR2 (Quickstart, pinned to merged PR1 SHA): acq run detects stale / legacy / unknown-provenance sandboxes vs the local PATTERNS_KIT_REF and offers a safe in-place refresh (interactive, default No, EOF=decline, non-interactive never blocks); explicit acq kit check (no mutation) + acq kit update SANDBOX [--yes]; ACQ_UPDATE_CHECK=0 + acq run --no-update-check; write provenance only after successful application; preserve SHA pinning + backend abstraction; whole-bundle reconcile. PR2: acq detects stale sandboxes vs local PATTERNS_KIT_REF + acq kit check|update #236
• PR3 (deferred follow-up): advisory "your Quickstart checkout is behind origin" check (cached 24h, ff-only, fail-open). PR3 (deferred): advisory 'Quickstart checkout is behind origin' update check #237

Source-of-truth discipline

The local Quickstart checkout (its pinned PATTERNS_KIT_REF) is the approved source of truth — never mutable patterns main. Two ordered PRs; Quickstart PR pins to the merged Patterns commit.

Non-goals / guardrails

No eval; bounded timeouts; treat kit/GitHub metadata as untrusted; never print secrets; never destroy sandbox state; fail-open when the check can't run. Do not weaken SHA pinning or backend abstraction.

Related patterns issue: GSA-TTS/agentic-coding-patterns (PR1 provenance/schema).

Co-authored-by: OpenCode Agent [email protected]