[INSTALL-09] [P2] Add a visible compiler selection and repair flow to the VS Code extension #559

Goal

After installing the editor extension, developers should be guided to a usable Semaprax compiler without needing to find and edit settings JSON.

Priority: P2 · Classification: Verified editor onboarding gap

Reviewed baseline: main 56ad6438653f, 6 October 2026. Published distribution inspected: v0.8.0 (CLI build commit 615e501). Recheck these installation surfaces against the current branch before implementing.

Current behavior and evidence

semaprax.compilerPath defaults to an empty machine-scoped string. extension.js explicitly skips save checks when it is unset and never discovers a compiler automatically.

The extension README and handbook require manually entering an absolute path. Existing status text describes a stopped session rather than explaining the missing compiler configuration.

The CLI catalog marks serve-workspace-mcp public on this reviewed main. Do not infer supported capabilities from a filename or incorrectly declare that command full-only. Inspect the selected executable's actual version/help/capabilities.

• Unset compiler path disables checks
• Save/check behavior without configuration
• Machine-scoped compiler and other settings
• Manual setup instructions
• JSON-based compiler setup
• Current public serve-workspace-mcp declaration

Implementation scope

1. Contribute SEMAPRAX: Configure Compiler and an actionable compiler-status item. Offer Select installed compiler, Open installation guide and a concise explanation of the detected setup state.
2. Use a file picker and optionally list known user installation locations/PATH candidates for the user to select. Resolve and display an absolute path; do not execute discovered candidates automatically or let a workspace file choose the executable.
3. After explicit selection, run bounded direct-process identity/compatibility checks using the existing machine-readable version contract and actual supported command introspection, with shell:false. Persist only the user's machine/global selection using the existing trust model.
4. Distinguish compiler missing, configured/ready for basic checks, executable moved/unusable, incompatible response and advanced-session prerequisites missing. Basic diagnostics must not require a managed session manifest or host policy.
5. Keep existing valid selections; cancelling configuration changes nothing. Provide a repair action after relocation/removal and a clear explanation if PATH points to a different installation than the selected executable.
6. Link to the canonical installation guide and correctly summarize the available editor features in README/handbook. Reuse existing harness/provider setup instead of installing or configuring third-party agent tools here.
7. Keep Marketplace publication with the existing held Publish VS Code Extension (DO NOT DO YET) #253. This ticket neither publishes the extension nor automatically downloads/runs a compiler from an unverified URL.

Acceptance criteria

• A new user selects an installed compiler with a picker, receives a visible ready state and obtains diagnostics on the starter project without editing JSON.
• Missing setup is visible and actionable without repeated modal prompts on every save.
• User/machine settings remain authoritative; workspace/folder settings cannot override executable selection or host policy.
• Identity probes honor time/output limits and paths with spaces/non-ASCII characters on Windows and Unix.
• Cancellation, an untrusted workspace, a removed binary and malformed version output cause no unintended execution or persistent settings change.
• Capability messages reflect the selected binary's actual behavior rather than standalone/full filename assumptions.
• Marketplace state and existing valid harness/client setup are preserved.

Verification

• Reuse authored Node and Extension Host tests for unset path, selected file, cancel, valid current binary, missing/moved binary, bad identity output and untrusted workspace.
• Run one clean editor-profile journey against an installed release and a generated project.
• Check that selecting a compiler enables ordinary diagnostics without requiring advanced session setup.

Existing issues and boundaries

• #253 explicitly holds Marketplace publication; do not duplicate or close it.
• #450 and #430 already implement skill/client integration; this scope is only compiler onboarding and repair.
• INSTALL-01 provides the canonical install guide and INSTALL-02/03 provide useful candidate locations once available.

Delivery notes

Implement in the existing owning modules and test harnesses. Follow AGENTS.md and the relevant release/editor contracts. Keep fixes focused, preserve unrelated behavior, and attach the actual verification results. Do not replace existing signing, publication, project generation or harness setup with a second system.