fix(install): package provider validator runtime - #619

🤖 Fixed the observed Link Check failure at the latest draft head: timeout troubleshooting now points to the OpenCode kit that owns generated provider configuration instead of the removed provider-owned opencode.jsonc. Local whole-file check confirms that link; it also reports an unrelated existing external microsandbox endpoint as status 0. Fresh CI will verify the changed docs.

Thanks, this fixes the Homebrew and release-install paths from #618. One regression for git checkouts:

The PR removes both the $ACQ_SCRIPT_DIR/.acq-tools/provider-input-validator{,.current} lookup and the python3-on-PATH fallback, and setup-provider-input-validator now requires a release wheelhouse. A checkout of main (or any non-tag ref) has no wheelhouse, so every OpenCode acq create fails closed with "this install lacks its offline bootstrap" or "wheelhouse is missing". install.sh warns about this for development refs, but checkouts are also how contributors and some teams run acq day to day (e.g. install.sh --clone, or running ./acq from a working tree to test a fix), and nothing in that path can be fixed without ACQ_PROVIDER_INPUT_PYTHON.

Suggestion: give checkouts a supported path that stays fail closed. For example, scripts/setup-provider-input-validator --apply --online builds the same runtime from the hash-locked requirements with pip install --require-hashes (network allowed only on that explicit setup call, never during create), and the "runtime unavailable" error names that command when $ACQ_SCRIPT_DIR/.git exists. Documenting ACQ_PROVIDER_INPUT_PYTHON in KNOWN_FAILURE_MODES.md as the manual alternative would also help.

Separately, the failing Link Check isn't from this PR: docs/KNOWN_FAILURE_MODES.md:276 links usai-provider's files/home/usai-config/opencode.jsonc, which agentic-coding-patterns#530 removed. It fails here only because the PR touches that file.

@basiliskus Addressed the checkout regression in the latest draft head:

• scripts/setup-provider-input-validator --apply --online is now the explicit development-checkout path. It uses the same --require-hashes locks and permits network access only during that command, never during acq create.
• Bootstrap Python selection honors ACQ_PROVIDER_INPUT_BOOTSTRAP_PYTHON, then tries python3.14, python3.13, python3.12, and finally python3; the selected interpreter is used for version checks, venv creation, and atomic publication.
• Checkout diagnostics name the online command and document ACQ_PROVIDER_INPUT_PYTHON as the manual alternative.
• Release installs remain offline-wheelhouse-first and fail closed.

Focused setup tests pass 5/5; Bash syntax, ShellCheck, and diff checks pass. The stale OpenCode ownership link was also corrected earlier. Draft CI is the full-suite authority. Please re-review.

@basiliskus Checkout support is complete in the latest draft head:

• --apply --online provides an explicit, hash-verified network setup path only for checkouts; acq create remains offline.
• ACQ_PROVIDER_INPUT_BOOTSTRAP_PYTHON takes precedence and is quoted consistently, including paths containing whitespace.
• Automatic selection tries supported versioned interpreters before generic python3; macOS 3.12–3.14 is supported.
• ACQ_PROVIDER_INPUT_PYTHON is documented as the manual alternative.
• Release installs remain checksum-verified wheelhouse-first.

Focused setup tests pass 5/5; syntax, ShellCheck, and diff checks pass. The stale documentation link is fixed. Please re-review.

One edge case in select_bootstrap_python: it returns the first candidate on PATH, not the first one the host accepts, so a Linux host with both python3.14 and python3.12 stops with "unsupported Python … 3.14" (reproduced with ACQ_PROVIDER_INPUT_HOST_OS=Linux). Checking each candidate's minor version against the host's accepted set before returning would fix it.

@basiliskus Checkout support is now complete in the latest draft head. --apply --online uses the same hash locks and permits network only during explicit setup; acq create remains offline. Bootstrap selection honors the explicit variable, uses macOS 3.14/3.13/3.12 order, and Linux/Windows 3.12-first order; paths are quoted consistently. Manual ACQ_PROVIDER_INPUT_PYTHON guidance is documented. Focused setup tests pass 6/6; static checks pass. Please re-review.

Thanks, both points are fixed at 967858f. I re-ran setup from a scratch checkout of this head on macOS arm64:

• --apply --online builds a working runtime on Python 3.14 with PyYAML 6.0.3 and jsonschema 4.26.0, and without --online the missing-wheelhouse error now points to it.
• With ACQ_PROVIDER_INPUT_HOST_OS=Linux on a host that has both python3.14 and python3.12, setup now picks 3.12.

I didn't run a full acq create against the new runtime.

One note on rollout: release PR #617 currently contains only #608. If it ships before this PR and the tap's current updater picks it up, Homebrew users who upgrade can't create OpenCode sandboxes. Merging GSA-TTS/homebrew-tap#11 first avoids that, since its updater skips any release without the validator wheelhouses, then this PR, then the release.

Review blocker fixes (commit 063cb7c)

Three blockers addressed point by point:

Blocker 1 — Release workflow structural test: tar path ↔ upload-artifact path

Root cause (confirmed): No structural test existed to prove the wheelhouse tar file path and the upload-artifact path were consistent. A divergence would silently upload an empty artifact directory.

Fix: Added four new assertions to test/bats/06-windows-install.bats:

• release workflow: wheelhouse job tar path matches upload-artifact path — verifies tar -C wheelhouse -czf "../…" (runner cwd) and path: provider-input-validator-wheelhouse-${{ matrix.platform }}.tar.gz (bare filename) are consistent
• release workflow: wheelhouse SHA256SUMS never hashes itself — asserts glob('*.whl'), refutes bare glob('*')
• release workflow: wheelhouse tar extracts into platform subdir for non-Windows — asserts Windows extraction uses correct platform subdir
• install-provider-input-wheelhouse: installs into platform subdir + cross-check with setup-provider-input-validator paths

Blocker 2 — SHA256SUMS must never hash itself

Root cause: > SHA256SUMS shell redirect creates the file as a 0-byte file before Python runs. The original glob('*') glob picked it up and emitted e3b0c44... SHA256SUMS (hash of empty string) into the manifest, making every subsequent sha256sum -c run on the extracted wheelhouse fail.

Fix: glob('*.whl') in .github/workflows/release.yml line 83. Confines hashing to wheel files only; SHA256SUMS is never a candidate regardless of creation order.

Regression test: release workflow: wheelhouse SHA256SUMS never hashes itself asserts glob('*.whl') and refutes the bare glob('*') pattern.

Blocker 3 — Wheelhouse extraction path / setup-provider-input-validator discovery

Root cause: install-provider-input-wheelhouse extracted wheels directly to $target (e.g. scripts/provider-input-validator-wheelhouse/), but setup-provider-input-validator expects them one level deeper at $target/$platform (e.g. scripts/provider-input-validator-wheelhouse/linux-x86_64/). The Windows release-assets extraction already used the correct platform subdir path; the POSIX installer did not.

Fix: target="${target}/${platform}" in scripts/install-provider-input-wheelhouse line 42, before stage and backup are derived. All subsequent mkdir/mv/verify operations remain correct; mkdir -p on the stage path automatically creates the new parent directory.

Tests: Structural cross-check verifies all four platform slugs (linux-x86_64, linux-aarch64, macos-arm64, macos-x86_64) appear in both setup-provider-input-validator and install-provider-input-wheelhouse, and that the target=${target}/${platform} assignment is present.

Verification transcript

scripts/test-acq-bats test/bats/05-install.bats:              1..31, 31 pass (was 4 failing — pre-existing git stub gap)
scripts/test-acq-bats test/bats/06-windows-install.bats:      1..23, 23 pass  
scripts/test-acq-bats test/bats/147-provider-input-projection.bats: 1..46, 46 pass
shellcheck --severity=warning (all shell files):              clean
markdownlint:                                                 clean
git diff --check:                                             clean
python3 -c 'import yaml; yaml.safe_load(...)' (all workflows): valid

The four pre-existing failures in 05-install.bats (tests 4, 5, 8, 14) were caused by the git stub's clone case not creating the scripts/install-provider-input-wheelhouse stub that install.sh calls after every release-tag clone; they were not introduced by this PR but masked by --no-msb not being used in those tests. Fixed as part of this commit.

AI-assisted (OpenCode [usai/claude_4_6_sonnet]). Human review required.

@basiliskus Fixed the remaining release archive blocker in the latest draft head. The wheelhouse tar command now writes the bare archive filename in the runner working directory (tar -czf NAME -C wheelhouse .), exactly matching upload-artifact. The previous structural assertion was replaced by an execution regression that runs the command in a job-like directory and asserts the upload path exists. The archive-path, SHA256SUMS, and platform-extraction focused tests pass 3/3; workflow YAML and diff checks pass. Please re-review.

I can't approve because it's a draft, but it's approved

🤖 Merge-queue sequencing check: current queued head 01117db includes the approved checkout/bootstrap and release-artifact fixes. This PR may merge before GSA-TTS/homebrew-tap#11. Hard guard: do not merge/publish the resulting Quickstart release PR until Homebrew updater #11 is merged to tap main; otherwise the published wheelhouse assets cannot be consumed by the generated formula workflow.