DispatchOptions.upgrade accepts boolean in types but runtime rejects it

Summary

DispatchOptions.upgrade currently accepts boolean in the public TypeScript type, but the runtime request validator rejects any truthy non-string value with InvalidArgumentError: upgrade must be a string. A TypeScript-valid call such as client.dispatch({ path: '/', method: 'GET', upgrade: true }, handler) therefore fails before any connector/network dispatch.

Code path

Producer / validator / feedback anchors:

• types/dispatcher.d.ts:116-117: upgrade?: boolean | string | null;
• lib/core/request.js:134-136: truthy upgrade values are rejected unless typeof upgrade === 'string'.
• lib/dispatcher/dispatcher-base.js:172-180: the validator failure is surfaced through handler.onResponseError(null, err) and dispatch() returns false when the handler has an error hook.

Steps to reproduce

Validation level: dynamic reproduction plus source-control-flow validation.

const { Client } = require('undici')

const client = new Client('http://127.0.0.1:9', {
  connect () {
    throw new Error('connector should not be reached when option validation fails')
  },
})

const handler = {
  onRequestStart () {},
  onResponseStart () {},
  onResponseData () {},
  onResponseEnd () {},
  onResponseError (_controller, err) {
    console.log(`handler.error.name=${err.name}`)
    console.log(`handler.error.message=${err.message}`)
  },
}

console.log(client.dispatch({ path: '/', method: 'GET', upgrade: true }, handler))

Observed output from the local repro:

handler.error.name=InvalidArgumentError
handler.error.message=upgrade must be a string
dispatch_return=false

Expected behavior

The public type and runtime validator should agree on the upgrade option contract. Either boolean should be rejected by TypeScript, or true should be normalized to a well-defined upgrade token.

Actual behavior

The TypeScript surface permits upgrade: true, but runtime rejects it before dispatch and reports upgrade must be a string.

Existing coverage

I searched current open/closed issues and PRs for upgrade must be a string, DispatchOptions upgrade boolean, and related types/dispatcher.d.ts upgrade terms. I did not find exact coverage. Nearby upgrade/WebSocket issues and PRs appear to cover protocol behavior, not this type/runtime option drift.

Suggested fix

The lower-risk fix is to narrow DispatchOptions.upgrade to string | null, matching the current runtime validator. If boolean support is intended, the runtime should define and test what true means.

Suggested tests

• Add a type-level negative assertion for upgrade: true on DispatchOptions if narrowing the type.
• Keep or add a runtime test that upgrade: 'websocket' remains accepted.
• Keep invalid non-string runtime values flowing to onResponseError.

Submitted with Codex.

Start with types/dispatcher.d.ts:116-117 and lib/core/request.js:134-136, then trace the error path in lib/dispatcher/dispatcher-base.js:172-180. Check the existing type-level and runtime test conventions for DispatchOptions and request validation. Done means the public upgrade contract matches runtime behavior, valid string upgrades remain accepted, and invalid values are covered through the handler error path.