feat(clients): Explain links a known issue or a pre-filled report

[saphid]

Model: Claude Opus 5.5 and Claude Sonnet 5.5. Rebased onto current main with Claude Opus 5.5 on 2026-10-12.

Draft, depends on #16685. This branch is built on #16685's Explain action; until that merges, this PR's diff also shows its commits. Review the last four commits (from c1ab963c96) for this change.

Problem

Explain (#16685) tells the user what probably went wrong, but not whether it is a problem other people already have. Someone hitting a known bug has no quick way to find its issue, and someone hitting a new one has to work out where and how to report it.

Change

When the user clicks Explain, the server also checks pingdotgg/t3code's issues for a match:

• Known issue: if one matches, the banner shows Known issue: Add Expo mobile client and wire up dev:mobile workflow #123 <title> as a link.
• Otherwise: the banner shows Report this issue, which opens GitHub's bug form in the browser with safe fields pre-filled, and copies the error, What happened and Likely fix to the clipboard for the user to check and paste. T3 posts nothing.

Before (#16685): the explanation, with no issue lookup.

After (this PR): Explain, then Report this issue, which copies the details and opens the form. Real-time recording, cropped to the banner.

How it works:

• The search sends no text from the error. GitHub search is public, so the server recognises the failure against a fixed list of 33 categories (whole-phrase patterns such as "failed to read attachment" or "connection refused") and searches with those categories' fixed terms, at most three, plus a fixed provider keyword, e.g. attachment read turn start claude repo:pingdotgg/t3code is:issue. Only which categories matched leaves the machine. No match means no search.
• The model picks, the server checks. The top five candidates (number, title, state) go into the explanation prompt as an untrusted section; the model names one only if it clearly describes the same failure, and the server accepts the number only if it was a candidate. Links are built from the number, never taken from GitHub's response.
• The report link carries no error text. The URL holds only a title of the same category terms ("[Bug]: Provider failure: attachment read, turn start"), a fixed instruction in the "Actual behavior" field, the provider keyword, runtime mode, OS and T3 version. The error, the explanation and the model name stay out of the URL, since GitHub receives a URL before the user reviews it. Clicking the link copies those details to the clipboard best effort, and the banner confirms only when the copy worked.
• Best effort, never blocking. The search has a 3 s timeout. Failures (network, 403/429, bad response) yield no candidates and the explanation still arrives. After a rate limit, searches pause until GitHub's reset time, measured from when the response arrived. Identical concurrent searches share one request, and results are cached per query for 10 minutes.

Surfaces: web and desktop (desktop opens the link through its existing external-window handler). Mobile has no Explain action. The user guide's activity log page says exactly what the search and the link contain.

Scope and approval

A follow-up to #16685, which is itself a new feature without maintainer approval yet; the same applies here, and I'll follow maintainer direction on both. Kept separate so #16685 stays reviewable on its own.

Verification

• vp test run on KnownIssueSearch.test.ts, ProviderFailureReportLink.test.ts, ProviderFailureExplanationService.test.ts, apps/server/src/textGeneration and apps/web/src/components/chat: all pass. They cover private names made of category words (Failed to read repo billing-migration: permission denied, Connection refused by auth.billing.internal) sending only fixed terms, a property test that every query word is a fixed term or provider keyword, 28 real failure strings mapping to their categories, out-of-list issue numbers ignored, a failed or rate-limited search still returning the explanation, backoff measured from response receipt, 20 concurrent identical searches making one request, emoji at every truncation point, and the report URL carrying none of the error text, explanation or model name.
• tsc --noEmit: 0 errors in apps/server, apps/web, packages/contracts, packages/client-runtime. Lint and format clean, no suppressions.
• Live client (web, headless Chrome, isolated dev server on 8c9fbc8fb5f with fix(server): provider failures say why a turn could not start #16303's ProviderFailure.ts laid over it so the failure names its reason): a real Claude attachment failure. The live search ran and the model matched no issue, so the report path is shown; clicking it opened a new tab with the pre-filled form and the clipboard held the three fields. The known-issue link state is covered by tests, not seen live, because no open upstream issue matches this failure.
• Independent review by GPT-6 Astra (high): two full rounds plus a targeted re-review of the last commit. Round 1 found that words filtered from the error could still leak secrets or private names into the public search (blocker), error text in the report URL, and an emoji truncation crash. Round 2 found that vocabulary words could still spell private names (blocker), backoff measured from the request instead of the response, and uncoalesced concurrent searches. A targeted re-review of the category rewrite confirmed the privacy and timing fixes closed and found one race: an interrupt between registering a shared search and installing its cleanup could strand later identical searches. The last commit holds interruption off across that step and adds a guard test; it was not reviewed again. The same re-review caught a docs line still listing the model name in the link, also fixed.
• Not checked: the GitHub form's rendering of the pre-filled fields (it needs a signed-in browser), and a text generation model other than Codex.

Built with Claude Sonnet 5.5 and Claude Opus 5.5 in Claude Code; cross-vendor review by GPT-6 Astra in T3 Code.

🤖 Generated with Claude Code