Windows: managed ONNX setup creates conflicting Path/PATH entries and breaks child-process resolution

[beh87]

Description

On Windows 11 with OpenCode and @cortexkit/aft-opencode 0.55.1, enabling
semantic search with AFT-managed ONNX can break executable resolution in the
AFT worker. Git, PowerShell, and Git Bash are available in the parent
environment but cannot be found by AFT.

Observed symptoms include:

artifact cache key probe failed ... spawn failed: program not found

The bridge inherits a Windows environment whose path key is spelled Path,
then adds uppercase PATH while prepending the managed ONNX directory.
These are distinct JavaScript object keys but represent the same Windows
environment variable. The suspected failure mechanism is that lookup or
serialization under the host runtime loses the original executable search
path. The exact Bun lookup/serialization behavior has not been independently
established in the embedded runtime.

Normalizing the child environment to a single case-insensitive path entry,
while preserving the full inherited value, fixes executable resolution in
our local test. Git, PowerShell, and Git Bash resolve successfully afterward,
and semantic indexing and retrieval work.

The installed plugin is already locally patched. Current doctor results
therefore describe the patched installation, not a clean upstream package.
The failure excerpts below precede recovery; the shell-resolution excerpts
show the later working state. Reinstalling or upgrading the plugin removes
the local workaround.

Environment

Component	Version / configuration
OS	Windows 11, x64
AFT CLI, binary, and OpenCode plugin	0.55.1
OpenCode at doctor collection	1.18.29
Node running doctor	24.20.0; not OpenCode's embedded runtime
AFT-managed ONNX Runtime	1.24.4
Plugin registration	@cortexkit/aft-opencode@latest, resolved to 0.55.1
Custom ONNX override	No custom ORT_DYLIB_PATH required
Report collected	2026-09-07

Minimal AFT configuration:

{
  "search_index": true,
  "semantic_search": true
}

Doctor reports the host installed, plugin registered, AFT enabled, no AFT
configuration parse error, and a compatible cached ONNX Runtime. It ignores
the Windows System32 ONNX copy because its version is unreadable.

Reproduction

1. Use the unpatched AFT 0.55.1 OpenCode plugin on Windows with Git and
   PowerShell available on the parent's executable search path.
2. Use an inherited environment with the path key spelled Path.
3. Enable lexical and semantic search with the configuration above, allowing
   AFT to select its managed ONNX runtime.
4. Restart OpenCode and invoke an AFT tool that initializes the native worker.
5. Inspect Git root-commit probing and shell candidate discovery in AFT logs.

Expected: prepending the managed ONNX directory preserves the full inherited
search path and passes only one case-insensitive PATH entry to the child.

Actual on the affected installation: AFT starts through its absolute binary
path but cannot resolve Git or the usual shells by name.

Cached artifact keys can mask the Git-probe failure, and path-identity
fallback can allow configuration to proceed. Successful configuration alone
does not demonstrate healthy executable resolution. No cache deletion is
required to inspect the probe warnings and shell discovery results.

Relevant Logs

These are shortened historical excerpts, not a new unpatched reproduction.
Workspace paths and session identifiers have been replaced consistently.
The word git, over-redacted by doctor, is restored from the previously
inspected failure logs. Unrelated task-replay and indexing logs are omitted.

Before recovery:

[2026-09-07T05:47:08Z] artifact cache key: git root-commit probe failed after retries (spawn failed: program not found); falling back to path identity for \\?\C:\repos\example
[2026-09-07T05:47:55Z] artifact cache key: git root-commit probe failed after retries (spawn failed: program not found); falling back to path identity for \\?\C:\repos\example-other
[2026-09-07T05:48:15Z] artifact cache key: git root-commit probe failed after retries (spawn failed: program not found); falling back to path identity for C:\repos\example

Working shell discovery after recovery with the local patch present:

[2026-09-07T05:52:57Z] bash candidate: pwsh.exe (PowerShell 7+; supports && pipeline operator)
[2026-09-07T05:52:57Z] bash candidate: powershell.exe (Windows PowerShell 5.1; && in pipelines unsupported, will surface as parse error)
[2026-09-07T05:52:57Z] bash candidate: git-bash auto-detected at <HOME>\scoop\apps\git\current\bin\bash.exe (POSIX, invoked as -c)

Workaround And Proposed Patch

The affected source is the bridge's child-environment construction in
packages/aft-bridge/src/bridge.ts. OpenCode loads a bundled copy in
@cortexkit/aft-opencode/dist/index.js, around line 9214 in version 0.55.1.
Patching only the separately installed bridge dependency does not update
that bundled copy.

The validated local workaround finds the inherited path key
case-insensitively, preserves its complete value, removes all path-key
variants, and supplies one path entry with the ONNX directory prepended.

The proposed patch below implements the same Windows normalization strategy
but is not byte-identical to the validated local edit: it chooses uppercase
PATH rather than retaining the inherited spelling and normalizes Windows
keys even without an ONNX directory. Treat it as a proposed 0.55.1 workaround,
not as a separately runtime-tested upstream fix. An upstream fix should also
preserve case-sensitive non-Windows PATH behavior.

Proposed patch against the published 0.55.1 package

diff --git a/dist/index.js b/dist/index.js
--- a/dist/index.js
+++ b/dist/index.js
@@ -9211,9 +9211,16 @@
     const useFastembedBackend = semanticBackend === undefined || semanticBackend === "fastembed" || semanticBackend === "";
     const ortDir = typeof this.configOverrides._ort_dylib_dir === "string" && useFastembedBackend ? this.configOverrides._ort_dylib_dir : null;
     const ortLibraryPath = ortDir == null ? null : join4(ortDir, process.platform === "win32" ? "onnxruntime.dll" : process.platform === "darwin" ? "libonnxruntime.dylib" : "libonnxruntime.so");
-    const envPath = process.platform === "win32" && ortDir ? `${ortDir};${process.env.PATH ?? ""}` : process.env.PATH;
-    const env = {
-      ...process.env,
-      ...envPath ? { PATH: envPath } : {}
-    };
+    const parentPathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path");
+    const parentPath = parentPathKey ? process.env[parentPathKey] : undefined;
+    const envPath = process.platform === "win32" && ortDir ? `${ortDir};${parentPath ?? ""}` : parentPath;
+    const env = { ...process.env };
+    if (process.platform === "win32") {
+      for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === "path")
+          delete env[key];
+      }
+    }
+    if (envPath)
+      env.PATH = envPath;
     this.logVia(`bridge.spawnProcess: useFastembedBackend=${useFastembedBackend}, ` + `parentORT=${process.env.ORT_DYLIB_PATH ?? "(unset)"}, ` + `ortLibraryPath=${ortLibraryPath ?? "(none)"}`);

Suggested upstream regression coverage: inherited Path, inherited PATH,
duplicate variants, missing PATH, ONNX enabled/disabled, and unchanged
case-sensitive non-Windows behavior.

Scope

Related symptom: #174, which concerns
extended-path working directories. This report concerns child-environment
PATH handling; failures were observed with both normal and extended paths.

An intermittent first-keystroke Bun crash was also observed, but the PATH
workaround did not resolve it. This report does not claim to diagnose that
separate crash.

This report was manually minimized after doctor collection. It contains no
conversation transcript; only selected diagnostics, log excerpts, and the
proposed patch are included.

[aft-alfonso]

Confirmed at the source: packages/aft-bridge/src/bridge.ts builds the worker env as { ...process.env, PATH: envPath } — the spread keeps the inherited Path key and the assignment adds a second PATH key, so the child gets two case-variants of one Windows variable and which one survives is undefined. npmSpawnEnv in the bridge's npm resolver has the same shape. Fix in progress on main: one shared helper that collapses every case-variant into a single key that keeps the inherited spelling and full value (ONNX dir prepended when managed ONNX is active), used at every spawn site; non-Windows keeps case-sensitive PATH only. Your coverage list (inherited Path, inherited PATH, both, missing, ONNX on/off, non-Windows untouched) is the test matrix, with the exactly-one-path-key assertion as the one that fails on 0.55.1. Thank you for the precise report and the validated workaround — the upstream fix keeps the inherited spelling rather than forcing PATH, as you suggested.