@bman654/clodex 2.13.0 → 2.14.0

package/docs/background-agents.md

@@ -11,6 +11,7 @@ This page explains how to bridge **every** Claude Code process on your machine
   - endpoint-mode server: `ANTHROPIC_BASE_URL` pointing at the gateway;
   - **no live server: env untouched** — `claude` always launches normally, a stopped server never breaks anything.
 - Setting **`CLAUDE_CODE_PROCESS_WRAPPER`** to `clodex-claude` makes Claude Code invoke it as `clodex-claude <claude-binary-path> <args...>` for every process it spawns — agents view sessions and background agents are bridged automatically.
+- That ordinary process-wrapper route keeps the handed-in binary. A separate VS Code-only path (`CLAUDE_CODE_ENTRYPOINT=claude-vscode`, explicit bundled executable, live proxy server; on Windows reached through the launcher from `clodex install-vscode-launcher`) may run the clodex-patched install instead, but only when the patch manifest proves by full SHA-256 that it is the patched output of those exact pristine bytes. Missing or mismatched proof keeps the bundled binary. When the manifest identifies the other install, a refused chat spawn emits one stderr line; refused helper commands stay silent, and the inspected extension source sends chat stderr to VS Code's **Claude VSCode** output channel. Tool, hook, and agent children carry child-session markers, while background pty wrappers lose the `claude-vscode` entrypoint; neither shape substitutes. Endpoint, no-server, and direct launches do not substitute either.
 - For your own terminal sessions, run **`clodex-claude`** instead of `claude` — same auto-discovery, no port or CA path to hardcode anywhere.
 - Set **`CLODEX_REQUIRE_SERVER=1`** in an isolated routed profile when bypassing Clodex must be impossible. `clodex-claude` then exits with an error if no advertised server passes its process and TCP checks. The default remains fail-open for ordinary installations.
 - A live standalone server has already snapshotted its credentials and account selection. If a wrapper launch sets `CLODEX_OAUTH_ACCOUNT` or a nonblank `CLODEX_KEY_*`, `clodex-claude` warns that the variable is ignored and still launches through that server. Restart the server with the selector, or save the provider credential and refresh its models, before launching without the process-only variable. With no live server these variables pass through unchanged.
@@ -20,6 +21,39 @@ This page explains how to bridge **every** Claude Code process on your machine
   `clodex-claude` invocation does not reconfigure the running server.
 - Proxy-mode wrapper launches remove Anthropic entries from the union of `NO_PROXY` and `no_proxy`, while preserving unrelated bypasses. The manual server output prints the same adjusted values for users who export the proxy settings themselves.
 
+## VS Code model picker
+
+After installing clodex, patch a compatible local Claude Code install and keep
+`clodex server --proxy` running. On macOS and Linux, find the absolute, extensionless wrapper path:
+
+```bash
+command -v clodex-claude
+```
+
+Put that exact path in VS Code's user `settings.json` (do not use the underlying `.js` file), then
+reload the window. If a Node version manager owns that path, use the stable launcher described in
+step 3 below instead of an ephemeral or version-specific path:
+
+```json
+"claudeCode.claudeProcessWrapper": "/absolute/path/to/clodex-claude"
+```
+
+On Windows the extension cannot spawn npm's script shims; run `clodex install-vscode-launcher` and
+paste the `.exe` path it prints instead — the same substitution then applies. Full walkthrough in
+[windows-setup.md](windows-setup.md).
+
+The extension and local Claude install update independently. If their pristine bytes no longer
+match, the wrapper keeps the extension's bundled executable; align compatible builds and run
+`clodex patch` again. A fallback notice appears in VS Code's **Claude VSCode** output channel, not
+as a toast; main-chat lines use the `From claude: ...` prefix.
+
+At least two extension behaviors relevant to this setup change when `claudeProcessWrapper` is set;
+these were verified from source rather than in a running editor: it skips a post-update activation health/telemetry probe (not the VS Code
+marketplace updater), and the SDK supplies `--permission-mode default` when no explicit permission
+mode is configured. An explicit mode still wins. Process-level tests cover the wrapper selection;
+the picker was not exercised in a running editor, and the Linux host path was not run for this
+change.
+
 ## Setup steps
 
 1. **Install clodex globally** (puts both `clodex` and `clodex-claude` on your PATH):
@@ -113,6 +147,7 @@ The check does not launch Claude.
 ## Troubleshooting
 
 - **Is my session bridged?** In a session started via `clodex-claude` (or spawned by Claude Code with the wrapper set), `/model` accepts your `clodex:` model names and aliases (run `clodex models --list` to see them). If those models are rejected and you haven't run `clodex patch`, that's expected for unpatched binaries — but a bridged session still routes them; an unbridged one errors at the API instead.
+- **VS Code routes models but omits picker entries:** open the **Claude VSCode** channel in the Output panel and look for a one-line `From claude: clodex-claude: running ...` fallback notice. Missing or unreadable state that cannot identify another install is deliberately silent, so the absence of a notice is not proof of selection. The extension and installed CLI update separately, and equal version labels do not prove equal artifacts. Align their builds and run `clodex patch` again. On Windows the wrapper setting must be the `.exe` from `clodex install-vscode-launcher` (npm's `.cmd` shim cannot be configured directly — see [windows-setup.md](windows-setup.md)); the notice appears in the same output channel.
 - **Server not running:** `clodex-claude` launches plain `claude` by default. With `CLODEX_REQUIRE_SERVER=1`, it exits instead. Check `cat ~/.clodex/server-runtime.json` — a missing file (or records whose `pid` is no longer alive) means no server is advertised; start `clodex server --proxy`. If a server is running but absent from the file, make sure it was not started with `--no-discovery` / `CLODEX_NO_DISCOVERY=1`.
 - **Wrapper variable empty or stale:** run `echo "$CLAUDE_CODE_PROCESS_WRAPPER"` in a **new login shell**. If it is empty, a `$(command -v ...)` in your profile ran before your Node version manager initialized (see the warning in step 3) — switch to a literal path. If it points at a path that no longer exists (a Node upgrade moved the global bin, an fnm/nvm shim directory expired, or it still names an old hand-written script), spawned processes fail to start or silently skip bridging. Verify with `[ -x "$CLAUDE_CODE_PROCESS_WRAPPER" ] && echo OK`.
 - **Agents fail to spawn / `env: node: No such file or directory`:** the wrapper's `#!/usr/bin/env node` shebang could not find Node, typically because Claude Code was launched from a GUI (Spotlight, Raycast, an IDE) with a minimal PATH. Use the launcher script from step 3, which resolves Node by absolute path, and test it with `env -i HOME="$HOME" PATH=/usr/bin:/bin "$CLAUDE_CODE_PROCESS_WRAPPER" --version`.

package/docs/windows-setup.md

@@ -9,10 +9,15 @@ There are two levels of setup, and they solve different problems:
 | Setup | What you get |
 | --- | --- |
 | [Proxy env vars](#1-route-the-extension-through-clodex) | clodex models **work** in the extension |
-| [+ process wrapper](#2-make-clodex-models-appear-in-the-model-picker) | clodex models also **appear in the model picker** |
+| [Launcher](#2-launch-the-extensions-claude-code-through-clodex) | the extension launches Claude Code **through `clodex-claude`**, which follows your running server on its own — no proxy values to copy into VS Code settings — and runs your **clodex-patched install** in place of the bundled binary, so clodex models appear in the extension's **model picker** |
 
-The first is enough if you are happy selecting a model once and leaving it. Add the second if you
-want to switch between clodex models from the extension's UI.
+Only the launcher level changes the picker. `clodex-claude` replaces the extension's bundled,
+unpatched Claude Code with your verified clodex-patched install exactly as it does on macOS and
+Linux (see the [VS Code setup in
+background-agents.md](background-agents.md#vs-code-model-picker)): the bundled file's full SHA-256
+must match the pristine hash `clodex patch` recorded, and the patched install must still match its
+recorded output. With the step 1 settings alone the extension launches its own bundled binary and
+the picker stays as it was.
 
 ## 1. Route the extension through clodex
 
@@ -53,14 +58,15 @@ running; stop it and the port goes dead, so every request fails until you start
 
 > [!NOTE]
 > Do not set `claudeCode.claudeProcessWrapper` to `clodex-claude` here. On Windows npm installs that
-> bin as `clodex-claude`, `clodex-claude.cmd` and `clodex-claude.ps1` — there is no `.exe`. The
-> extension spawns the wrapper without a shell, so pointing it at the `.cmd` fails with
-> `spawn EINVAL`. The environment-variable approach above is the one that works.
+> bin as three script shims — `clodex-claude` (a POSIX shell script), `clodex-claude.cmd` and
+> `clodex-claude.ps1` — and no `.exe`. The extension spawns the wrapper without a shell, so pointing
+> it at any of them fails with `spawn EINVAL`.
+> [Step 2](#2-launch-the-extensions-claude-code-through-clodex) builds the `.exe` that setting needs.
 
 ### Selecting a clodex model
 
 At this level the extension's model picker will **not** list clodex models (see
-[why](#why-the-picker-is-empty-without-a-wrapper)). Set one as your default from a terminal instead:
+[why](#why-the-picker-is-empty-without-a-launcher)). Set one as your default from a terminal instead:
 
 ```powershell
 clodex claude
@@ -72,9 +78,9 @@ launch — Claude Code reports it as `Using <model> (from .claude\settings.json)
 
 Existing chat tabs keep whatever model they launched with; open a new chat to pick up the change.
 
-## 2. Make clodex models appear in the model picker
+## 2. Launch the extension's Claude Code through clodex
 
-### Why the picker is empty without a wrapper
+### Why the picker is empty without a launcher
 
 `clodex patch` patches the Claude Code binary that npm installed. The VS Code extension does not
 launch that binary — it ships and launches its own copy:
@@ -83,218 +89,247 @@ launch that binary — it ships and launches its own copy:
 %USERPROFILE%\.vscode\extensions\anthropic.claude-code-<version>-win32-x64\resources\native-binary\claude.exe
 ```
 
-On the machine this was written from, that bundled copy was byte-identical (SHA-256) to the pristine
-backup clodex took before patching, confirming it was unpatched. The model picker's entries live
-inside the binary, so the dropdown shows whatever the *launched* binary offers — which is why models
-routed correctly while remaining invisible in the picker.
+On the machine this was first written from, that bundled copy was byte-identical (SHA-256) to the
+pristine backup clodex took before patching, confirming it was unpatched. The model picker's entries
+live inside the binary, so the dropdown shows whatever the *launched* binary offers — which is why
+models routed correctly while remaining invisible in the picker.
 
 Routing does not depend on the patch. Claude Code sends the model name it was given, and the proxy
 maps it. The patch is what makes the binary itself aware of clodex models — listing them in the
 picker, accepting them as known aliases, and reporting their context windows.
 
-### Point the extension at the patched binary
+`clodex-claude` solves this itself: when the extension hands it the bundled binary, it substitutes
+the install recorded in `patch-state.json` — only when the extension's full binary hash matches
+that manifest's pristine hash and the install's full hash still matches the recorded patched
+output (equal version labels or sizes are not enough); a mismatch runs the extension's own binary
+and writes one line to its output channel. On Windows the only missing piece was an executable the
+extension could spawn; the launcher below is that piece.
 
-`claudeCode.claudeProcessWrapper` takes an executable path. Claude Code invokes it as:
+### What the launcher is
+
+`claudeCode.claudeProcessWrapper` takes a single executable path. Claude Code invokes it as:
 
 ```
 <wrapper> <path-to-claude-binary> <args...>
 ```
 
-passing the binary it *would* have run as the first argument. A wrapper that drops that argument and
-runs the clodex-patched binary instead gives the extension a patched Claude Code.
-
-It must be a real `.exe`, for the `spawn EINVAL` reason above. Any language that produces one works;
-this is a Go reference implementation. It asks clodex which binary it patched, so the same compiled
-exe works on any machine without editing a path:
-
-```go
-// The extension invokes a claudeProcessWrapper as:
-//     wrapper.exe <path-to-claude-binary> <args...>
-// so the first argument is the binary it would otherwise have run.
-//
-// Target resolution, in order:
-//  1. CLODEX_WRAPPER_TARGET, if set
-//  2. binaryPath from clodex's patch manifest (patch-state.json)
-//  3. the path the caller handed us — so claude always launches, just unpatched
-package main
-
-import (
-	"encoding/json"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-)
-
-// clodexHome mirrors getAppHome() in clodex's src/paths.ts: CLODEX_HOME is the
-// app directory itself when set, otherwise <home>/.clodex.
-func clodexHome() string {
-	if override := strings.TrimSpace(os.Getenv("CLODEX_HOME")); override != "" {
-		return override
-	}
-	for _, key := range []string{"HOME", "USERPROFILE"} {
-		if value := os.Getenv(key); value != "" {
-			return filepath.Join(value, ".clodex")
-		}
-	}
-	if home, err := os.UserHomeDir(); err == nil {
-		return filepath.Join(home, ".clodex")
-	}
-	return ""
-}
-
-// patchedBinary reads the binary clodex last patched, or "" if unavailable.
-func patchedBinary() string {
-	home := clodexHome()
-	if home == "" {
-		return ""
-	}
-	data, err := os.ReadFile(filepath.Join(home, "patch-state.json"))
-	if err != nil {
-		return ""
-	}
-	var manifest struct {
-		BinaryPath string `json:"binaryPath"`
-	}
-	if err := json.Unmarshal(data, &manifest); err != nil {
-		return ""
-	}
-	return manifest.BinaryPath
-}
-
-func isFile(path string) bool {
-	if path == "" {
-		return false
-	}
-	info, err := os.Stat(path)
-	return err == nil && !info.IsDir()
-}
-
-func main() {
-	args := os.Args[1:]
-
-	// The caller passes the binary it would have run; hold it as the fallback.
-	handedIn := ""
-	if len(args) > 0 {
-		if base := strings.ToLower(filepath.Base(args[0])); base == "claude.exe" || base == "claude" {
-			handedIn = args[0]
-			args = args[1:]
-		}
-	}
-
-	target := ""
-	for _, candidate := range []string{
-		strings.TrimSpace(os.Getenv("CLODEX_WRAPPER_TARGET")),
-		patchedBinary(),
-		handedIn,
-	} {
-		if isFile(candidate) {
-			target = candidate
-			break
-		}
-	}
-	if target == "" {
-		os.Stderr.WriteString("claude-wrapper: no Claude Code binary found\n")
-		os.Exit(1)
-	}
-
-	cmd := exec.Command(target, args...)
-	cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
-	cmd.Env = os.Environ()
-
-	if err := cmd.Run(); err != nil {
-		if exitErr, ok := err.(*exec.ExitError); ok {
-			os.Exit(exitErr.ExitCode())
-		}
-		os.Stderr.WriteString("claude-wrapper: " + err.Error() + "\n")
-		os.Exit(1)
-	}
-}
+passing the binary it *would* have run as the first argument. clodex already ships a wrapper for
+exactly this contract — `clodex-claude`, the one [background agents](background-agents.md) use —
+but on Windows npm installs it as three script shims (extensionless, `.cmd`, `.ps1`) and no
+executable, and the extension refuses those with `spawn EINVAL`.
+
+`clodex install-vscode-launcher` builds the missing `.exe` on your machine. It compiles a small C#
+program (`launcher\clodex-claude-launcher.cs` in the clodex package — a short, commented file you
+can read) with the C# compiler that ships inside the .NET Framework on every Windows 10/11 install,
+so there is nothing to download and no prebuilt binary to trust. The resulting
+`clodex-claude.exe`:
+
+- runs `node.exe` with clodex's `claude-wrapper.js`, passing the extension's arguments through
+  with their **values preserved, Unicode included** (it forwards the raw command line rather than
+  re-quoting each argument, and the wrapper spawns a native `claude.exe` directly rather than
+  through `cmd.exe`, so JSON arguments, empty strings, `%NAMES%` and paths with spaces reach Claude
+  Code as sent);
+- ties Node and the Claude Code it launches to its own lifetime with a Windows job object, so that
+  when the extension cancels a chat or the window reloads, no `node.exe` or `claude.exe` is left
+  behind. If Windows refuses the job object the launcher prints one warning line and runs anyway;
+- lets Ctrl+C reach Claude Code rather than swallowing it, waits, and exits with Claude Code's own
+  exit code.
+
+`clodex-claude` then does what it does for any Claude process: finds your running
+`clodex server --proxy` and bridges the session to it. **The launcher does not choose the Claude
+Code binary.** It hands `clodex-claude` the bundled `claude.exe` the extension named, exactly as the
+extension would, and `clodex-claude` applies its usual rule: when that file's full SHA-256 equals
+the pristine hash in `patch-state.json` and your patched `claude.exe` still hashes to the recorded
+patched output, it runs the patched install; otherwise it runs the bundled `claude.exe` and, for
+the chat itself, writes one line to the **Claude VSCode** output channel (helper commands the
+extension runs fall back silently). On Windows both files must be `.exe` programs (a
+`.cmd` launcher is never substituted for or into), and the bundled file (about 200 MB) is hashed on
+every launch — `tests/wrapper-substitution.windows.test.ts` prints the measured time on the CI
+runner; see that job's log for the current number.
+
+### Build it
+
+Run once, from any terminal, with the Node you normally use:
+
+```powershell
+clodex install-vscode-launcher
 ```
 
-Build it:
+It prints where the launcher went and the setting to paste:
 
-```powershell
-go build -ldflags="-s -w" -o claude-wrapper.exe .
 ```
+Built C:\Users\<you>\.clodex\bin\clodex-claude.exe
+  compiler: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe
+  runs:     C:\nvm4w\nodejs\node.exe C:\nvm4w\nodejs\node_modules\@bman654\clodex\dist\claude-wrapper.js
+
+Add this to your VS Code settings (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):
+
+  "claudeCode.claudeProcessWrapper": "C:\\Users\\<you>\\.clodex\\bin\\clodex-claude.exe"
+```
+
+The two paths on the `runs:` line are compiled into the executable. **Re-run the command after
+switching Node versions or moving the clodex install** — it is idempotent and replaces the launcher.
+If the wrapper script it was built against disappears, the launcher exits with code 127 and a
+one-line message naming the command to re-run, which shows up in the extension's **Claude VSCode**
+output channel.
+
+If the command reports that it cannot find `csc.exe`, your Windows install is missing the .NET
+Framework 4.x runtime it normally ships with; install .NET Framework 4.8 from Microsoft and re-run.
 
-Then add the setting, keeping the environment variables from step 1 — they do the routing, the
-wrapper only chooses the binary:
+### Add the setting
+
+Paste the printed line into your user settings and **remove** the `HTTPS_PROXY`, `HTTP_PROXY` and
+`NODE_EXTRA_CA_CERTS` entries from step 1: `clodex-claude` injects the equivalent values itself
+from the server it discovers, and static entries pointing at a fixed port would keep failing while
+the server is down, whereas the wrapper leaves the environment alone and lets Claude Code start
+unbridged.
 
 ```json
-"claudeCode.claudeProcessWrapper": "C:\\path\\to\\claude-wrapper.exe"
+"claudeCode.claudeProcessWrapper": "C:\\Users\\<you>\\.clodex\\bin\\clodex-claude.exe"
 ```
 
-Reload the window. The picker should now list your clodex models alongside the built-in ones.
+Reload the window. `clodex server --proxy` still has to be running — the launcher does not start it.
+Open a new chat: the model picker now lists your clodex favorites and aliases, provided the CLI you
+patched and the extension ship the same Claude Code build. When they drift apart (the extension and
+the CLI update separately), the picker falls back to the bundled list and the **Claude VSCode**
+output channel shows a `From claude: clodex-claude: running ...` line; update the CLI to the
+extension's version and re-run `clodex patch`.
 
 If Claude fails to start, remove the `claudeCode.claudeProcessWrapper` line, save, and reload — that
-returns you to the step 1 setup.
+returns you to the step 1 setup. The **Claude VSCode** output channel (View → Output) shows the
+launcher's and wrapper's messages, prefixed `From claude:`.
 
 > [!TIP]
-> If you use a Node version manager, prefer a path that survives version switches. With NVM for
-> Windows, `C:\nvm4w\nodejs` is a symlink to the active version, so a path through it stays valid
-> across both Node upgrades and Claude Code updates.
+> `clodex-claude` looks for the server in `%USERPROFILE%\.clodex`. If you set `CLODEX_HOME` in your
+> shell only, VS Code will not see it; add it under `claudeCode.environmentVariables` as well.
 
 ### Consequences of setting a process wrapper
 
-Claude Code changes two behaviors when `claudeProcessWrapper` is set. Both were read from the
-extension's own code rather than observed failing:
+At least two extension behaviors relevant to this setup change when `claudeProcessWrapper` is set.
+These were read from the extension's own code rather than observed in a running editor:
 
-- **Its update check is skipped.** Keeping Claude Code current becomes your job:
+- **A post-update activation health/telemetry probe is skipped.** This is not the VS Code
+  marketplace updater and does not show that extension auto-updates stop. The extension can still
+  update separately from the CLI, so keep the CLI you patch aligned with the extension you run:
 
   ```powershell
   npm install -g @anthropic-ai/claude-code@latest
   clodex patch
   ```
 
-- **Permission-mode resolution moves out of the CLI.** If permission prompts behave unexpectedly
-  under a wrapper, this is the setting to remove first when narrowing it down.
+- **The SDK supplies a permission mode.** With no explicit mode, wrapper launches add
+  `--permission-mode default` instead of leaving default-mode resolution to the CLI. An explicitly
+  configured mode still wins. If permission prompts behave unexpectedly under a wrapper, remove the
+  wrapper setting while narrowing it down.
 
-Re-running `clodex patch` after each Claude Code update is required regardless of the wrapper — the
-patch applies to a specific version of the binary.
+Re-running `clodex patch` after each Claude Code CLI update is required regardless of the wrapper —
+the patch applies to specific bytes.
 
-Keep the two versions aligned as well. With a wrapper set, the binary the extension launches is no
-longer the one it ships with, while the extension itself can still update from the marketplace — so
-the two can drift apart. Compare them if something starts behaving unexpectedly:
+### Previous manual workaround
 
-```powershell
-(Get-ChildItem "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-*" -Directory |
-   Sort-Object Name | Select-Object -Last 1).Name
-claude --version
-```
+Earlier versions of this page carried a hand-built Go program to compile yourself. It ran the
+patched npm `claude.exe` directly, bypassing `clodex-claude` entirely: it needed the step 1
+environment variables, got no server discovery, and had none of `clodex-claude`'s full-hash
+verification, so its target had to be kept aligned and re-patched by hand. It still works if you
+built one, but `clodex install-vscode-launcher` is the supported path and the only one that verifies
+what it runs.
 
 ## Troubleshooting
 
-**`spawn EINVAL`** — `claudeProcessWrapper` points at a `.cmd`, `.ps1`, or `.bat`. It must be an
-`.exe`.
+**`spawn EINVAL`** — `claudeProcessWrapper` points at a `.cmd`, `.ps1`, or `.bat`. It must be the
+`.exe` from `clodex install-vscode-launcher`.
 
-**Every request fails** — check `clodex server --proxy` is still running. The extension's
-`HTTPS_PROXY` points at a fixed port; nothing falls back when the server is gone.
+**`clodex-claude.exe: clodex's claude-wrapper.js is no longer at ...`** (output channel, exit 127)
+— clodex moved or was reinstalled under a different Node. Re-run `clodex install-vscode-launcher`.
 
-**Certificate errors** — `NODE_EXTRA_CA_CERTS` must match the path the server printed, with
-backslashes escaped in JSON.
+**`could not find the .NET Framework C# compiler`** — install .NET Framework 4.8 from Microsoft; the
+command looks under `%WINDIR%\Microsoft.NET\Framework64\v4.*` and `Framework\v4.*`.
 
-**Models route but the picker is empty** — expected without the wrapper; see
-[step 2](#2-make-clodex-models-appear-in-the-model-picker).
+**Windows Defender or SmartScreen flags the launcher** — it is a freshly compiled unsigned
+executable, so reputation-based checks have never seen it. The source is in the clodex package
+(`launcher\clodex-claude-launcher.cs`); allow the file, or build it again after clearing the
+warning.
+
+**Every request fails** — check `clodex server --proxy` is still running. With the step 1 env vars
+the extension's `HTTPS_PROXY` points at a fixed port and nothing falls back when the server is gone;
+with the launcher, sessions started while the server is down run unbridged.
+
+**Certificate errors** (step 1 setup) — `NODE_EXTRA_CA_CERTS` must match the path the server
+printed, with backslashes escaped in JSON.
+
+**Models route but the picker is empty** — with the step 1 settings alone that is expected: the
+extension launches its own bundled binary. With the launcher, open View → Output → **Claude VSCode**
+and look for a `From claude: clodex-claude: running ...` line: it names the reason (usually the
+extension and the installed CLI are different Claude Code builds). Align them —
+`npm install -g @anthropic-ai/claude-code@<extension version>` — and re-run `clodex patch`. No
+line at all is not proof either way: a missing or unreadable patch manifest is deliberately silent.
+Run `clodex patch`, and check that `CLODEX_HOME`, if you set it, is also set under
+`claudeCode.environmentVariables` so the wrapper reads the same manifest.
+
+**`CLODEX_CLAUDE_PATH` points at `clodex-claude` or `claude` without an extension, or at a `.ps1`** —
+Node cannot spawn those on Windows at all. Point it at the `.cmd` or at the program's `.exe`.
 
 **`clodex patch` reports it cannot detect the installation** — upgrade clodex; resolving npm
 launchers to the underlying binary on Windows was fixed in 2.11.5.
 
 ## What was verified, and where
 
-Verified on Windows 11, NVM for Windows (node v22.19.0), clodex 2.11.6, Claude Code 2.1.267, Claude
-Code VS Code extension 2.1.267, against the ChatGPT/Codex-plan OAuth provider:
+Step 1, and the *previous* Go workaround, were verified on Windows 11, NVM for Windows
+(node v22.19.0), clodex 2.11.6, Claude Code 2.1.267, Claude Code VS Code extension 2.1.267, against
+the ChatGPT/Codex-plan OAuth provider:
 
 - Step 1 routes extension traffic through clodex, and a model set as default from `clodex claude` is
   used by the extension.
-- Step 2 makes clodex models appear in the extension's model picker and selectable from it.
+- A process wrapper that launches a patched binary makes clodex models appear in the extension's
+  model picker and selectable from it.
 - The extension's bundled binary was unpatched, matching clodex's pristine backup by SHA-256.
-- The wrapper's target resolution, exercised in all four states: `patch-state.json` present (runs the
-  recorded binary), manifest absent (falls back to the handed-in binary), manifest absent with an
-  unreadable handed-in path (exits 1 with a message rather than hanging), and the normal case on this
-  machine. The listing above was extracted from this page and compiled to confirm it builds as
-  printed.
 
-Not verified: any Node version manager other than NVM for Windows, any provider other than
+Not verified there: any Node version manager other than NVM for Windows, any provider other than
 ChatGPT/Codex-plan OAuth, and the two wrapper consequences above, which were read from the
 extension's code rather than reproduced.
+
+`clodex install-vscode-launcher` is verified on every pull request by a Windows CI job
+(`windows-latest`, `tests/vscode-launcher.windows.test.ts`): the command builds the launcher with the
+runner's own .NET Framework `csc.exe`; the resulting `.exe` is spawned the way the extension spawns
+it (no shell, arguments as a list) with `node.exe` plus a probe script standing in for the bundled
+Claude Code; argument values with spaces, quotes, JSON, empty strings, `%PATH%`, `&|<>^` and
+non-ASCII text arrive at the probe unchanged through Node and `clodex-claude`; stdin, stdout and the
+exit code pass through; killing the launcher takes Node, the probe and the probe's own child process
+down; re-running the install over a running launcher ends in a one-line message; and a launcher
+whose baked wrapper script was removed exits 127 with the re-run hint. Off Windows the command's
+compiler discovery, source rendering, scratch compile and install are exercised against a fake
+`csc.exe`.
+
+The patched-install substitution behind the launcher is verified on the same job by
+`tests/wrapper-substitution.windows.test.ts`: a fake `claude.exe` compiled with the runner's
+`csc.exe` is patched by the real `clodex patch` command, the launcher is handed a pristine copy of
+it and runs the patched one (its output names which copy ran, and the proxy settings and arguments
+reach it intact); a same-size copy with different bytes runs as handed in with exactly one line on
+stderr, written before anything the binary prints; helper spawns (`auth status`,
+`--no-session-persistence` queries) fall back silently; and a dead server disables substitution.
+The same file records what Node reports about files on the runner's NTFS volume (file ids, volume
+serial, change time on an in-place rewrite, the read-only attribute) and prints the time to hash a
+200 MB file.
+
+**Not covered by CI, please report on #245 if you can try it:** the real VS Code extension spawning
+the launcher and showing clodex models in its picker (it is spawned by a test harness in CI, which
+cannot open an editor), Windows Defender/SmartScreen behaviour on the freshly compiled `.exe`, and
+Windows on ARM.
+
+```powershell
+# 1. Build, and note the three paths it prints.
+clodex install-vscode-launcher
+
+# 2. Paste the printed "claudeCode.claudeProcessWrapper" line into user settings, remove the
+#    HTTPS_PROXY/HTTP_PROXY/NODE_EXTRA_CA_CERTS entries, keep `clodex server --proxy` running,
+#    Developer: Reload Window. Then, with a chat open and a reply streaming:
+Get-Process node, claude -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, StartTime
+# Press the stop button in the chat, wait five seconds, run the same line again: the node/claude
+# processes started when the chat began (their StartTime) must be gone. Paste both listings.
+
+# 3. Output channel: View > Output > "Claude VSCode". Paste any line starting with
+#    "From claude: clodex-claude.exe:" (job-object warnings) — there should be none.
+
+# 4. Defender/SmartScreen: paste any prompt or quarantine notice about
+#    $env:USERPROFILE\.clodex\bin\clodex-claude.exe, or say there was none.
+```