fix(llm): use Windows WSA errnos instead of string matching (#953)

## Summary

- Follow-up to #951. The Windows CI failure resolved there with a
string-matching fallback has a deeper, fully typed fix.
- `syscall.ECONNREFUSED` on Windows is defined as \`APPLICATION_ERROR |
iota\` (an invented value, not the real WSA error code), so
\`errors.Is(err, syscall.ECONNREFUSED)\` *always* returns false on
Windows for real network errors. Same for \`ENETUNREACH\` and
\`EHOSTUNREACH\`.
- Split \`connectionErrnos\` across build-tagged files: POSIX uses the
standard \`syscall.*\` constants; Windows uses
\`golang.org/x/sys/windows.WSAECONNREFUSED\` / \`WSAENETUNREACH\` /
\`WSAEHOSTUNREACH\` (already a direct dep, exposed as \`syscall.Errno\`
so \`errors.Is\` works).
- \`isNetworkError\` collapses to a simple loop over the
platform-specific list; the substring fallback comes out. Zero string
matching on either platform.
- \`AGENTS.md\`: codify "no \`err.Error()\` substring classification"
with the Windows errno caveat documented inline so the next agent
doesn't fall into the same trap.

Author: cpcloud

AGENTS.md

@@ -344,6 +344,19 @@ details; do not duplicate that detail here.
   (e.g. `delete(m, "id"); delete(m, "ID")`) -- that papers over an
   inconsistency instead of fixing it. If you see ambiguity, fix the
   source struct's tags.
+- **No string matching to classify errors**: Never inspect `err.Error()`
+  substrings to decide whether an error is e.g. a network failure or a
+  syntax error. Substring checks break silently when an upstream wrapper
+  changes its message format. Use `errors.Is` against typed sentinels or
+  `errors.As` against typed error structs. **Windows socket gotcha**:
+  `syscall.ECONNREFUSED`/`ENETUNREACH`/`EHOSTUNREACH` are NOT portable.
+  On Windows they are `APPLICATION_ERROR | iota` invented constants that
+  never match the WSA error codes (10061/10051/10065) `net/http` actually
+  returns -- so `errors.Is(err, syscall.ECONNREFUSED)` always fails on
+  Windows. Define platform-specific sentinel lists in build-tagged files
+  using `golang.org/x/sys/windows.WSA*` (already typed as `syscall.Errno`)
+  for the Windows variant. See `internal/llm/network_errors_{windows,other}.go`
+  for the pattern.
 - **Deterministic ordering requires tiebreakers**: Every `ORDER BY` that
   could tie MUST include a tiebreaker (typically `id DESC`).
 - **Audit new deps before adding**: Review source for security issues

internal/llm/client.go

@@ -10,7 +10,6 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
-	"syscall"
 	"time"
 
 	anyllm "github.com/mozilla-ai/any-llm-go"
@@ -456,23 +455,18 @@ func (c *Client) wrapError(err error) error {
 
 // isNetworkError reports whether err represents a connection-level failure
 // (connection refused, unreachable host) as opposed to an application-level
-// error from a server that was reachable. Tries syscall sentinels first,
-// then falls back to message matching: net/http on Windows wraps
-// "connectex" errors in a way that drops the syscall.Errno layer, so
-// errors.Is(err, syscall.ECONNREFUSED) returns false even for a refused
-// connection (CI proved this on the windows-latest runner). The string
-// fallback is the only way to recognize those cases.
+// error from a server that was reachable. The set of errno sentinels is
+// platform-specific because Windows' net stack returns WSA error codes
+// (e.g., WSAECONNREFUSED = 10061) and syscall.ECONNREFUSED on Windows is
+// an invented APPLICATION_ERROR value that never matches them. See
+// connectionErrnos in network_errors_{windows,other}.go.
 func isNetworkError(err error) bool {
-	if errors.Is(err, syscall.ECONNREFUSED) ||
-		errors.Is(err, syscall.ENETUNREACH) ||
-		errors.Is(err, syscall.EHOSTUNREACH) {
-		return true
+	for _, errno := range connectionErrnos {
+		if errors.Is(err, errno) {
+			return true
+		}
 	}
-	msg := err.Error()
-	return strings.Contains(msg, "connection refused") ||
-		strings.Contains(msg, "actively refused") ||
-		strings.Contains(msg, "host is unreachable") ||
-		strings.Contains(msg, "network is unreachable")
+	return false
 }
 
 // isLoopbackURL returns true if the URL points to a loopback address.

internal/llm/client_test.go

@@ -14,7 +14,6 @@ import (
 	"net/http/httptest"
 	"os"
 	"strings"
-	"syscall"
 	"testing"
 	"testing/synctest"
 	"time"
@@ -417,7 +416,7 @@ func TestPingServerDownCloud(t *testing.T) {
 	// Use wrapError directly: a ECONNREFUSED wrapped in ProviderError
 	// from a cloud provider should say "cannot reach ... check your
 	// base_url" and NOT mention ollama.
-	inner := fmt.Errorf("dial tcp: %w", syscall.ECONNREFUSED)
+	inner := fmt.Errorf("dial tcp: %w", connectionErrnos[0])
 	c := &Client{providerName: "openai"}
 	err := c.wrapError(anyllmerrors.NewProviderError("openai", inner))
 	require.Error(t, err)
@@ -478,7 +477,7 @@ func TestCreateProviderAllSupported(t *testing.T) {
 // TestWrapErrorProviderError exercises the wrapError path for ProviderError.
 func TestWrapErrorProviderError(t *testing.T) {
 	t.Parallel()
-	connErr := fmt.Errorf("dial tcp: %w", syscall.ECONNREFUSED)
+	connErr := fmt.Errorf("dial tcp: %w", connectionErrnos[0])
 	tests := []struct {
 		provider string
 		wantMsg  string
@@ -501,49 +500,43 @@ func TestWrapErrorProviderError(t *testing.T) {
 	}
 }
 
-// TestIsNetworkError verifies that wrapped syscall sentinels are
-// recognized via errors.Is, regardless of how deeply they are wrapped.
+// TestIsNetworkError verifies that wrapped platform-correct syscall
+// sentinels are recognized via errors.Is, regardless of how deeply
+// they are wrapped. Uses connectionErrnos to stay correct across
+// Linux/macOS (POSIX errnos) and Windows (WSA errnos), since
+// syscall.ECONNREFUSED on Windows is an invented APPLICATION_ERROR
+// constant that doesn't match the WSA value.
 func TestIsNetworkError(t *testing.T) {
 	t.Parallel()
+	refused := connectionErrnos[0]
 	cases := []struct {
 		name string
 		err  error
 		want bool
 	}{
-		{"bare ECONNREFUSED", syscall.ECONNREFUSED, true},
-		{"bare ENETUNREACH", syscall.ENETUNREACH, true},
-		{"bare EHOSTUNREACH", syscall.EHOSTUNREACH, true},
+		{"bare connection-refused errno", refused, true},
 		{
-			"net.OpError wrapping ECONNREFUSED",
+			"net.OpError wrapping connection-refused errno",
 			&net.OpError{
 				Op: "dial", Net: "tcp",
-				Err: &os.SyscallError{Syscall: "connect", Err: syscall.ECONNREFUSED},
+				Err: &os.SyscallError{Syscall: "connect", Err: refused},
 			},
 			true,
 		},
 		{
-			"fmt.Errorf wrapping EHOSTUNREACH",
-			fmt.Errorf("dial tcp: %w", syscall.EHOSTUNREACH),
+			"fmt.Errorf wrapping connection-refused errno",
+			fmt.Errorf("dial tcp: %w", refused),
 			true,
 		},
 		{"unrelated error", errors.New("something else broke"), false},
 		{"context.Canceled", context.Canceled, false},
-		// Windows: net/http wraps connectex errors without preserving
-		// the syscall.Errno layer, so the string fallback is the only
-		// way to recognize them. Verbatim error captured from CI.
+		// Bare strings without a wrapped syscall sentinel must NOT be
+		// classified as network errors. Pin this so we don't slide back
+		// into substring matching.
 		{
-			"windows connectex actively refused",
-			errors.New(
-				"Get \"http://127.0.0.1:1/v1/models\": dial tcp 127.0.0.1:1: " +
-					"connectex: No connection could be made because the target " +
-					"machine actively refused it.",
-			),
-			true,
-		},
-		{
-			"plain connection refused string",
+			"bare string says connection refused",
 			errors.New("dial tcp: connection refused"),
-			true,
+			false,
 		},
 	}
 	for _, tt := range cases {

internal/llm/network_errors_other.go

@@ -0,0 +1,18 @@
+// Copyright 2026 Phillip Cloud
+// Licensed under the Apache License, Version 2.0
+
+//go:build !windows
+
+package llm
+
+import "syscall"
+
+// connectionErrnos lists the syscall errors that mean "I could not reach
+// the server" on POSIX platforms. errors.Is unwraps net.OpError ->
+// os.SyscallError -> syscall.Errno, so these match the values net/http
+// surfaces when a connect(2) fails.
+var connectionErrnos = []syscall.Errno{
+	syscall.ECONNREFUSED,
+	syscall.ENETUNREACH,
+	syscall.EHOSTUNREACH,
+}

internal/llm/network_errors_windows.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Phillip Cloud
+// Licensed under the Apache License, Version 2.0
+
+package llm
+
+import (
+	"syscall"
+
+	"golang.org/x/sys/windows"
+)
+
+// connectionErrnos lists the WSA error values that mean "I could not
+// reach the server" on Windows. The standard syscall.ECONNREFUSED on
+// Windows is an APPLICATION_ERROR-prefixed invented constant that
+// never matches what ConnectEx returns; the real values come from
+// winsock and are exposed via golang.org/x/sys/windows. errors.Is
+// unwraps net.OpError -> os.SyscallError{Syscall: "connectex"} ->
+// syscall.Errno, so these match what net/http surfaces.
+var connectionErrnos = []syscall.Errno{
+	windows.WSAECONNREFUSED,
+	windows.WSAENETUNREACH,
+	windows.WSAEHOSTUNREACH,
+}