/research web search fails instantly (web-search-unavailable) with custom GitHub App auth

Trace credential.token from apps/server/src/agent/active-owner.ts through apps/server/src/jobs/research-workspace.ts into the createMCPClient call in apps/server/src/harness/web-search.ts. Reproduce with the provided ghu_ versus gho_ comparison, and confirm whether GitHub's Copilot MCP endpoint supports App user tokens before changing token selection or documentation. Done means the failing path and actual throw site are identified, with either a verified fix and regression coverage or a documented custom-GitHub-App limitation.

Summary

/research web search consistently fails with web-search-unavailable on a fresh self-hosted instance using a custom (non-GitHub-owned) GitHub App for sign-in, even though the signed-in account has an active, working Copilot entitlement. Diagnosis points to the GitHub App user access token (ghu_...) not being accepted by GitHub's Copilot MCP endpoint, while a classic OAuth token (gho_...) for the same account works against that same endpoint.

Environment

• Commit: d9aec4befa397d6da9a1f483e634794a949f821f (2026-10-17)
• HARNESS=copilot-sdk, AGENT=on, BACKGROUND_JOBS=on, WEB_RESEARCH=on
• Local dev setup per README ("Run locally"), Docker Postgres, Bun 1.4.2
• Custom GitHub App created per README's "Register these local URLs" instructions, with the documented repository permissions (Contents RW, PRs RW, Workflows RW, Checks/Commit statuses/Issues RO)
• GitHub account has an active Copilot plan (confirmed at github.com/settings/copilot: included credits in use, "Copilot can search the web" enabled, MCP servers enabled, Copilot CLI enabled)

Steps to reproduce

1. Stand up Chopin locally against a fresh custom GitHub App (not GitHub's own hosted app).
2. Sign in, create a channel on a repository, open a document.
3. Trigger /research with any brief.
4. Observe the research card fail with "Research failed... The public web-search service was unavailable."
5. Retry — fails again, consistently, in ~1–12ms (not the ~60s timeout described in docs/conversation-research.md).

Server-side diagnostics

Background job log for each attempt:

chopin: background job research-evidence <id> attempt 1 progress {"stage":"public-web","phase":"authorizing",...,"elapsedMs":0}
chopin: background job research-evidence <id> attempt 1 progress {"stage":"public-web","phase":"connecting-web",...,"elapsedMs":6}
chopin: background job research-evidence <id> attempt 1 failed - JobExecutionError: Background job execution failed: web-search-unavailable. diagnostic={"stage":"public-web","phase":"connecting-web",...}

The failure happens almost instantly (single-digit to low double-digit ms), every time, at the connecting-web phase — not the slow/variable web-search-timeout failure mode described in docs/conversation-research.md's "Live execution check" note. This looks like a fast rejection, not a hang.

Ruled out

• Copilot entitlement: confirmed active on the GitHub account (github.com/settings/copilot).
• Network reachability: curl to https://api.githubcopilot.com/mcp/ from the same host succeeds and returns the expected 401/WWW-Authenticate response when unauthenticated.
• Debug instrumentation: added console.error to both catch blocks in apps/server/src/harness/web-search.ts (around the createMCPClient call and around the client.tools() call) and restarted the bun --watch dev server. Despite reproducing the failure multiple times afterward, neither log line appeared in server output — so the actual throw site may not be where I expected, and this is worth a maintainer's look at the exact code path under current main.

Working comparison

A manual MCP initialize handshake directly against the same endpoint, using a classic OAuth token (gho_..., obtained via gh auth token for the same GitHub account) succeeded immediately:

curl -X POST https://api.githubcopilot.com/mcp/ \
  -H "Authorization: Bearer $(gh auth token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-MCP-Readonly: true" \
  -H "X-MCP-Toolsets: web_search" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"diag","version":"0.0.1"}}}'

→ 200 OK, full initialize response with tools capability and an mcp-session-id.

Hypothesis

apps/server/src/jobs/research-workspace.ts / apps/server/src/harness/web-search.ts authorize the web_search MCP call using credential.token, which (per apps/server/src/agent/active-owner.ts) is owner.access.token — the GitHub App user access token (ghu_... prefix) issued through the App's own OAuth flow, per docs/authentication.md's description ("It acts as each signed-in user, with their App user access token, so repository-role checks and Copilot entitlement stay theirs").

Given a classic OAuth token for the same account/same Copilot entitlement works against api.githubcopilot.com/mcp/, but the App-issued token path fails instantly and consistently, it looks like GitHub's Copilot MCP endpoint may not accept GitHub App user access tokens (ghu_) the same way it accepts classic OAuth App tokens (gho_) — independent of the underlying user's Copilot entitlement. If so, this would mean /research's web-search step cannot work for any self-hosted deployment using a custom (non-GitHub-owned) GitHub App, regardless of configuration, which seems worth confirming and documenting (or fixing, if there's an alternate token/exchange Chopin should be using instead).

Suggested next steps for a maintainer

1. Confirm whether api.githubcopilot.com/mcp/ is expected to accept ghu_-prefixed GitHub App user access tokens at all.
2. If not, document this as a known limitation for self-hosted instances with custom GitHub Apps (the README's "Run locally" section doesn't currently flag this).
3. If it should work, there may be a bug in token selection/propagation for the webSearchTool call path — happy to help narrow this down further (e.g. by decrypting a real stored session token for a controlled test) if useful.

Happy to provide more diagnostic detail, logs, or test further on request.