Why Windows discovery finds zero services: one readiness check speaking for seven engines #63

What happens

On Windows, Discover completes and finds zero services, every time. No .vinv/vinv.md is written, no .vinv/services.json follows, and the pipeline dead-ends before a single line is traced. macOS and Linux are unaffected.

Confusingly, the extension reports that the engines installed successfully first.

Why

Two different checks answer "is the engine there?", and they disagree.

The readiness check probes one engine:

// extension/src/engines/resolve.ts
/** True when `uv sync` has been run for the engines root (venv scripts exist). */
export function enginesSynced(enginesRoot: string): boolean {
	return fs.existsSync(pythonEnginePath(enginesRoot, 'tracelens'));
}

But ENGINE_NAMES has seven:

// extension/src/tracelens/bin.ts
export const ENGINE_NAMES: ReadonlyArray<string> = [
	'index',
	'tracelens',
	'handbook',
	'bringup',
	'identification',
	'goal',
	'exerciser',
];

and each stage gates on its own binary:

export function isBinAvailable(context: vscode.ExtensionContext, name: string): boolean {
	return fs.existsSync(getBinPath(context, name));
}

So a uv sync that materialises tracelens but not handbook puts the two in conflict. enginesSynced says ready. Then:

// extension/src/harness/harnessRunner.ts
export function runHandbookViaHarness(...): Promise<boolean> {
	if (isHandbookGenerated(workspaceRoot)) { ... }
	if (!isBinAvailable(context, 'handbook')) {
		showEnginesMissingError('handbook');
		return Promise.resolve(false);        // ← 0 ms, stage over
	}
	...
}

The stage returns false before doing any work. And because the telemetry wrapper classifies a falsy return as an error without distinguishing why:

outcome: token.isCancellationRequested ? 'cancelled' : ok ? 'ok' : 'error'

a missing engine is indistinguishable from an agent that ran for ten minutes and failed.

Why it cascades

Bring-up is gated on the handbook existing, so it never runs at all — the stage that would write services.json is never reached. That is why the symptom presents as "zero services" rather than "missing handbook": the failure surfaces two stages downstream of its cause.

handbook bails (0 ms)
  → no .vinv/vinv.md
    → bring-up never runs
      → no .vinv/services.json
        → services_count = 0

What the field data shows

Aggregate across extension versions 0.2.8 → 0.2.15:

handbook_ok predicts the outcome perfectly — 21/21 runs with a handbook found services, 0/75 without.

It is not the harness: claude-code is 7/18 on darwin and 0/40 on win32.

Stage outcomes on win32 — handbook 32 error / 0 ok, index 61 error / 0 ok, deadcode 10 ok, bringup no rows at all. 19 of the 32 handbook errors finish in under a second, which is the precondition bail above; the other 13 run long (up to 600 s) and still write nothing, which looks like a separate bug.

The clincher: deadcode is the only stage that ever succeeds on Windows, and the only one not in ENGINE_NAMES — it needs no engine binary at all. Every Windows-failing stage requires one.

Ruled out

Checked at v0.2.15 and correct in each case — venv path handling (enginesVenvBinDir returns Scripts on win32, executableFileName appends .exe), PowerShell chaining (; if ($?) { … }, the && parse error was fixed earlier), _resolve_bash (prefers Git-for-Windows bash, skips the WSL launcher), process teardown (taskkill /T /F), and every harness spawn site (shell: true). Missing uv/rust prerequisites appear on darwin at a comparable rate, so they are not the discriminator.

Proposed direction

1. enginesSynced verifies every engine the pipeline will invoke, not just tracelens.
2. The install-settled signal names which engines are missing instead of returning a boolean, so a partial uv sync is visible rather than silent.
3. A stage that bails on a missing engine reports that distinctly from a stage whose agent ran and failed — today both are outcome: 'error'.

Separately, why uv sync yields tracelens but not handbook on Windows still needs a reproduction. But a readiness check should not be able to report ready while a required engine is absent, whatever the cause.

Tracked as #62.