PR2: acq detects stale sandboxes vs local PATTERNS_KIT_REF + acq kit check|update #236

Part of quickstart#235. Depends on the patterns provenance schema (GSA-TTS/agentic-coding-patterns#273); pin PATTERNS_KIT_REF to that merged commit.

Scope

1. Provenance read/write — after a successful acq_backend_ensure_kits_applied (both backends), record in-sandbox provenance (patterns repo + full PATTERNS_KIT_REF SHA + bundle version + kit names + timestamp + backend), in a backend-neutral location that does not collide with user project files. Write only after success (partial/failed apply must not claim currency). sbx and msb each get a concrete path (documented).
2. Staleness detection in acq run — compare installed provenance vs the local checkout's PATTERNS_KIT_REF:
   • current → nothing;
   • stale (older SHA) or legacy/unknown (no provenance) → offer a safe in-place refresh;
   • interactive only, default No, EOF=decline, and non-interactive acq run never blocks (skip or one concise advisory, then continue). A declined update must not prevent launch.
3. Explicit commands — acq kit check [SANDBOX] (no mutation) and acq kit update SANDBOX [--yes] (updates to the local pinned bundle). --yes only on the explicit command.
4. Opt-out — ACQ_UPDATE_CHECK=0 env + acq run --no-update-check. Keep the interface small (one env + one flag).
5. Whole-bundle reconcile — reapply the built-in bundle (usai/playbook/zscaler/git-ssh-sign) using each backend's existing idempotent path; sbx grows a stale-refresh path (today it only injects absent kits); msb already re-applies idempotently. After a usai refresh, ensure the startup global-merge runs so the new model catalog reaches the config; state (sessions/secrets/unrelated config/project overrides) preserved. If a backend can't safely update in place: explain, preserve the sandbox, give a manual recovery path, never auto-delete.

Security/trust (consensus conditions)

Preserve full 40-char SHA pinning; local checkout is source of truth (never patterns main); validate refs; no eval; quote shell values; bounded timeouts; treat kit metadata as untrusted; never print secrets; preserve backend abstraction (no sbx logic in common.sh); fail-open.

Tests (stub-style)

Provenance: current/older/missing-legacy/malformed; written-only-after-success; idempotent repeats. Detection+prompt: accept/decline/default-No/EOF-decline/non-interactive-never-prompts/declined-doesn't-block; --yes only on explicit command. Backend: sbx in-place refresh; msb idempotent reapply; failure preserves state; no auto-delete; deterministic bundle order; extra user kits not marked built-in. OpenCode: refreshed catalog reaches staged config; global merge preserves unrelated + project-local keys; convergent; parseable; no secret leak.

Docs + ADR

Update QUICKSTART/BACKEND_GUIDE (what acq checks, disable, manual check, explicit update, declined behavior, legacy sandboxes, backend limits, recovery, SHA-trust preserved). New ADR (context; local checkout as source of truth vs mutable main; provenance; interactive vs non-interactive; failure/fail-open; security; rollback; limitations).

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