vscode: startup preflight — verify codev CLI installed and version ≥ extension version; guide install/upgrade otherwise

[amrmelsayed]

Problem

Today the extension's only CLI preflight is tower-starter.ts silently calling resolveAfxPath() and logging to the OutputChannel if afx isn't found. There's no version check, no codev-CLI check, and no user-facing guidance — a user with a missing or outdated CLI gets cryptic Tower-startup failures instead of a clear "install this, then retry" path.

Current state

• packages/vscode/src/tower-starter.ts:27-30 — resolves afx binary, logs an error to OutputChannel on failure; no toast, no UX.
• No call to codev --version or afx --version anywhere in the extension.
• No version compatibility matrix; no first-run onboarding.

Proposed behavior

On activate(), run a quick preflight (cached per session — does not re-run on every command):

1. Existence check

• codev --version → must resolve. If missing, this is treated as first-run / setup-required (combination UX, below).
• afx availability is already covered by tower-starter; no duplicate check needed.

2. Version check

• Source-of-truth for the minimum acceptable version is the extension's own package.json version. The CLI must report codev --version ≥ extension.version. No separate compat.json, no manifest field — same-or-higher than the extension is the rule.
• If the CLI version is below the extension version, prompt to upgrade.

3. Guidance UX (combination)

• First-run / missing CLI → trigger a VS Code Walkthrough (Codev: Getting Started) with detect → install → verify steps. Persistent until dismissed or completed; suited to brand-new users.
• Outdated CLI → rich notification with actions: Update via npm (runs npm install -g @cluesmith/codev in an integrated terminal and re-verifies), Open Install Docs, Dismiss. Lightweight, in-context.

4. On dismiss — degrade gracefully

• Codev commands stay registered but become no-ops; invoking one shows a single Codev: CLI not installed / outdated — run setup toast with a Run Setup button that re-opens the install flow.
• Re-prompts on next activation if still unresolved.
• User can use VS Code normally; nothing crashes.

Acceptance criteria

• On activation, the extension runs codev --version exactly once and caches the result.
• If the CLI is missing, the Codev: Getting Started walkthrough is triggered automatically (first activation per workspace).
• If the CLI version is less than the extension's own package.json version, a notification appears with Update via npm and Open Install Docs actions.
• If the user dismisses either prompt, Codev commands remain visible but no-op cleanly with a single toast on first invocation.
• Preflight result is cached per VS Code session; commands don't re-run version checks.
• Preflight completes in under 500ms on a happy path (CLI installed and current); doesn't block activation noticeably.

Out of scope

• Separate compat.json / network-fetched compatibility (intentionally rejected — extension version is the truth).
• afx version checks (handled by existing tower-starter; codev CLI version is the proxy).
• Auto-running the install command without user confirmation.
• Auto-uninstalling outdated CLIs.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).