Skip to content

fix(chat): name why an @-mention file search failed - #10838

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
rnoack1:fix/at-menu-search-failure-ux
Nov 4, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
rnoack1:fix/at-menu-search-failure-ux

Conversation

@rnoack1

@rnoack1 rnoack1 commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When an @-mention file search fails, the user can tell which failure it was and take the one action that can actually recover it.

The @-mention file picker rendered a single notice for every failure of /api/file-search: "Couldn't search files. Try again." A timeout, a refusal on a sensitive path, a missing project root and an unknown server error were indistinguishable, so the user could not tell whether waiting, fixing the project setting, or retrying was the right response. There was no Retry control either, and the copy invited a retry even for refusals that answer identically every time.

Why it matters

The menu sits in the composer, so a failure here interrupts typing. Telling the user to "try again" when the folder is off limits sends them into a loop that cannot succeed.

The notice also has to be truthful about the keyboard. It promises which key sends the message, and that promise is wrong if the picker is swallowing that key.

Not a goal

  • Changing the search itself. No endpoint, timeout, query or retry-policy change.
  • Changing how the other surfaces that search files report failure. FolderPanel and FileBrowserRail keep their existing notice copy.
  • Adding or removing a locale. Only the failure copy changes, in the 13 catalogs already present.
  • Changing what a successful search shows. Row rendering, ordering and selection are untouched.

What changed (motivation → approach → change)

Correction to earlier revisions of this description. They said this unit imported RetryControl and the useListKeyboardNav hand-offs from a prerequisite, #10834, and that it would not build until that merged. That was wrong on both counts and is withdrawn. #10834 is closed and was never merged, and this diff adds RetryControl itself, so it is in scope here. Verified against main: website/src/lib/searchErrorCause.ts is present and website/src/components/RetryControl.tsx is absent. This PR no longer changes useListKeyboardNav: keyboard reach comes from the emptyActionRef option main gained in #22662. searchErrorCause is the only piece taken from elsewhere and it is already on main, so nothing here waits on another PR.

Everything this PR ships, and why each piece is here:

  • Cause-specific copy, borrowed where the fact is shared. FilePickerMenu classifies the rejection with searchErrorCause and selects copy per cause: timed out, failed, no access, project folder not found. Without it the four cases are one message. The timeout and generic arms take their copy from lib/searchErrorCause.ts's SEARCH_FAILURE_KEYS, which the map spreads rather than re-spelling, because both surfaces call the same /api/file-search and a timeout there is one fact. Only denied and root_missing stay picker-local: those two NAME a root, and the folder tab's own cwd is a different directory from the chat project this menu searches (FolderPanel.tsx:36), so a shipped test requires the panel's refusal copy not to match /project/i. That drops two picker-local keys from 13 catalogs.
  • The notice carries the cause alone, and the send key moved to the muted hint row. Keyboard guidance printed in the alert colour read as more failure and took weight off the cause. One enter_sends / ctrl_enter_sends pair, picked from the live send-key setting, now sits in the hint row, and is shown only where that key really sends: an empty list with the release gate open. With rows on screen Enter picks the highlighted row, so nothing is claimed there. Ten per-cause suffixed keys collapse into that single pair across 13 catalogs.
  • The cause survives a retry. A retry re-enters pending and drops error, which would rewrite the notice to the generic copy mid-press. lastCauseRef holds the cause so the text does not change under the user.
  • website/src/components/RetryControl.tsx, new in this PR. The notice needs a real button, offered only for causes where retrying can help (RETRYABLE_SEARCH_CAUSES) and withheld for a refusal or a missing root. It is a component rather than inline markup because it owns the busy state and the onMouseDown preventDefault that keeps the composer's caret. It reads its own label from components.filePickerMenu.retry rather than taking one as a prop, so nothing in it is generalized past its single caller.
  • Keyboard reach through the shared hook, unchanged. Retry is passed to useListKeyboardNav as emptyActionRef, the option the skill and slash pickers already use since feat(dashboard): add retry to skill and slash picker load-failure notices #22662, so this PR adds no hook API. The hook owns where focus goes: pressing Retry, leaving it with Tab, or closing with Escape returns focus to the composer, and focus the user moved elsewhere is never taken back.
  • Rows already on screen are kept. Base already kept them — the results memo was never gated on isError — so this PR does not change that behaviour. What it adds is the cause notice above them. The rows stay selectable and Tab still picks one, exactly as in every other list. One exception: while retrying a search that never loaded, rows left over from an earlier, shorter query are hidden, so the notice never sits over another query's results.
  • A hint row under the notice, new in this PR. The cause alone left questions open, so the row carries up to two hints. While a retry is in flight it names the held send key, because the release gate closes during a retry and a fixed promise would be false for as long as the retry takes. When Retry is withheld it names the control that recovers: Click the folder name below the message box to change it, or Pick a different path for a path-scoped refusal. That wording names what is actually on screen: the composer footer shows the project folder's NAME, and nothing there is labelled "project", so an earlier draft pointing at a "project button" named a control the user cannot pick out. Its nouns are lifted from this repo's own gitPanel.not_a_repository_help, which already names that control for this same action in all 12 languages. Tests cover each hint, the case where none should show, and both arms of each conditional, and the capture harness asserts the hint text per scene.
  • A refusal in pathMode blames the path, not the project folder. A @../x token can be refused for one blocked subpath while the project folder itself is fine, so a denied cause in pathMode selects This path is off limits rather than the folder copy, and its hint points at the path instead of the folder control. Outside pathMode the folder copy is unchanged.
  • The hint row is a live region. It stays mounted and empty rather than appearing with the first hint, so a retry starting is a text change inside a region a screen reader is already watching, which is the standard the empty states in this file already follow. It carries aria-live="polite" and not role="status", because this file reserves the status role for the non-failure branch and a shipped test asserts a failure exposes no status role. The margin is applied only when a hint is present, so an empty region has no visual footprint. A test pins the empty case, which is rows surviving a retryable failure: no recovery hint, and no send-key line because Enter picks a row there.
  • Seven screenshots and website/scripts/capture-file-picker-search-failure.mjs. The harness follows the repo's existing website/scripts/capture-<feature>.mjs convention. It runs against the real built SPA and asserts each scene as well as photographing it, because an absent button, surviving rows and a withdrawn promise are not things a photograph can evidence on its own.

Tab keeps its usual meaning

Retry is offered only when the list is empty, so Tab never competes with picking a row. With rows on screen Tab picks one, as in every other useListKeyboardNav list; on an empty list the first Tab reaches Retry, a second returns focus to the composer, and Escape on Retry closes the menu and returns focus there. Enter outside Retry still follows the existing releaseKeysWhenEmpty behaviour.

Earlier revisions offered Retry over surviving rows and took Tab away to reach it. That is withdrawn: three review lanes converged on it, and Design Review named the inconsistency it created, since the second Tab closed the menu to avoid inserting a row the notice called stale while Enter still inserted that same row. Retyping already re-queries while rows are on screen, so nothing is lost.

Backwards compatibility

Removes nothing: useListKeyboardNav is unchanged, so every other consumer keeps its current key handling. No copy key is deleted; the generic failure string is reworded in place.

Tests

website/src/test/FilePickerMenu.timeout.test.tsx and website/src/components/FilePickerMenu.cov80.test.tsx lock in:

  • each of the four cause notices, and the send-key line rendering in the hint row rather than in the alert;
  • Retry appearing for a retryable cause and being withheld for a refusal or a missing root;
  • the cause surviving across a retry, rather than reverting to generic copy;
  • focus returned to the composer when Retry is pressed, when Tab leaves it, and when Escape closes from it, and kept on the composer when a keyboard retry succeeds;
  • an earlier query's rows hidden while retrying a search that never loaded;
  • surviving rows staying selectable, so Enter still picks a row instead of sending the message;
  • the timeout and generic copy coming from the shared map, with no picker-local spelling of either. Controlled on both doors it could return through: re-adding the catalog key (with the panel's own value, so only the key's existence can fail it) and overriding the map arm each redden it.

Manual verification

The seven states below were produced by website/scripts/capture-file-picker-search-failure.mjs, committed here, against the built SPA; each scene is asserted by that script and a mismatch exits non-zero.

All 11 per-language register gates ran as part of the full i18n suite, diff-scoped against this branch's base so the zero-tolerance changed-value arm was armed rather than skipping silently: 1022 tests, 0 violations. That arm was positive-controlled by mutating one of this PR's own new values to the formal address its style doc forbids; bnStyle.test.ts named components.filePickerMenu.check_project_folder by key and failed, so the arm is reading these keys rather than passing blind. Because the latest change DELETES keys from 13 catalogs rather than adding values, the gate that covers it is catalogParity, so that one was positive-controlled too: re-adding the deleted key to de.json alone reddened it with 1 stray key(s), e.g. components.filePickerMenu.search_failed. The full tsc, eslint and vitest runs are CI's on this head.

Screenshots / video

Committed under temp-screenshots/file-picker-search-failure/, pinned to this head.

1. Empty list, retryable cause: the notice names the timeout and offers Retry.

Empty picker showing a timed-out search notice with a Retry button

2. Empty list, refusal: Retry is withheld, because re-asking returns the same answer.

Empty picker showing a no-access notice with no Retry button

3. Rows survived the failure: the cause notice sits above them, Retry is withheld, and they stay selectable.

Picker showing a failure notice above a surviving file row

4. Empty list, generic failure: Retry is offered.

Empty picker showing a generic search-failed notice with a Retry button

5. Empty list, project folder not found: Retry is withheld.

Empty picker showing a project-folder-not-found notice with no Retry button

6. Retry in flight: the cause stays put and the button is busy and disabled.

Picker showing the failure cause with the Retry button in its busy, disabled state

7. Path token refused: the notice blames the path, not the project folder, and Retry is withheld.

Picker showing a path-off-limits notice with a pick-a-different-path hint and no Retry button

Pattern harvest

Rule candidate: review-prompt
Pattern: one generic failure notice standing in for several distinguishable error causes, inviting a retry for causes that answer identically every time.

Open findings

Raised by the review lanes on this head and not fixed by this description. Each needs a code change or a maintainer's decision, not a wording change.

  • UX: the idle Retry icon reserves space. RetryControl keeps the icon invisible when idle, which pushes the label off-centre. Fixing it restales screenshots 1, 3 and 4, so it wants doing together with a capture re-run.
  • FilePickerMenu.tsx:175 names a throttle ladder nothing there sets. The comment sits above placeholderData and staleTime, neither of which configures retry or backoff.
  • FilePickerMenu.timeout.test.tsx:192 waits on real backoff. The 429 test allows 4s of wall clock for the shared ladder's 1s plus jitter. Fake timers would make it fast and deterministic.

@dwu96

dwu96 commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 14, 2026
@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from 90ffc2d to 41c3f5c Compare September 14, 2026 18:57
@dwu96

dwu96 commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@rnoack1
rnoack1 marked this pull request as ready for review September 15, 2026 00:49
@rnoack1
rnoack1 requested review from a team and Zedmor September 15, 2026 00:49
@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 0e5052dfae3eea1aa5fd18ed284ceb84072b566b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

No first-time reader has seen these controls: this fork lane has no blind read. Pushing the branch to this repository would run one.

Notes

  • RetryControl: at rest the RefreshCw icon is invisible but still takes up space, so "Retry" sits off-centre with a blank gap on its left (attachment-01, attachment-04). Collapse the icon's width when it isn't busy, or show it all the time.

[UX-REVIEWED] 0e5052d

Description read

[DESCRIPTION-READ] 8488c748e1e1225fa0f00853dc08c0bf133cfc2ce419aa4c9216f433cd1615d0

That sha256 names everything this verdict read: the PR description, plus the 10 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 0e5052dfae3eea1aa5fd18ed284ceb84072b566b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns: the change reuses the cause classifier, failure-copy map, retryable set and keyboard hand-off already on main, and the only removed key, components.filePickerMenu.search_failed, has no reader outside the file this patch rewrites.

Notes

  • The 368-line capture harness waits on fixed sleeps (waitForTimeout(11000), 2000) as barriers. It is evidence tooling and not in CI, but it will be slow and flaky to re-run. If it is kept, replace the sleeps with waits on actual signals.

[DESIGN-REVIEWED] 0e5052d

Description read

[DESCRIPTION-READ] ccca72ceab5aaa26c502cf2fdfc18e7bdfee7001b4f11e8966dcfe35f07e3387

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 0e5052dfae3eea1aa5fd18ed284ceb84072b566b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0e5052d

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 0e5052dfae3eea1aa5fd18ed284ceb84072b566b via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: every item serves the frozen Goal and no default changes. One new component, RetryControl, is a third spelling of the Retry button that the sibling pickers write inline.

Notes

  • Item 6 — one consumer, generalized: the description says "It is a component rather than inline markup because it owns the busy state and the onMouseDown preventDefault". RetryControl has exactly 1 consumer (FilePickerMenu.tsx). It hard-codes components.filePickerMenu.retry, yet it sits under a generic name in components/. Grepping for ref={retryRef} + onMouseDown={e => e.preventDefault()} finds that same busy and mousedown logic written inline twice: SkillPickerMenu.tsx:360 and SlashCommandMenu.tsx:325. Subtraction: delete website/src/components/RetryControl.tsx and put the <Btn> inline in FilePickerMenu.tsx, as the two siblings do.

What this change ships

Inventory (10 items) — 9 justified

Intent: when an @-mention file search fails, show which failure it was and offer only the action that can recover it. This is a FIX.

  1. The failure notice now names its cause (timed out / failed / no access / project folder not found) — justified
  2. A refused ../ path says "This path is off limits", not the folder copy — justified
  3. A Retry button appears on an empty list, for timeout and generic failure only — justified
  4. When Retry is withheld, a muted hint names the recovery (click the folder name below the message box, or pick a different path) — justified
  5. The send-key line shows on an empty failed list, the one case where Enter really sends — justified
  6. A new shared RetryControl component — one consumer, generalized
  7. While a retry runs, the held send key is named and the earlier query's rows are hidden — justified
  8. The notice keeps its cause text during a retry instead of falling back to generic copy — justified
  9. The picker-local search_failed key is removed from 13 catalogs and the folder panel's shared copy is used instead — justified
  10. A capture script and 7 screenshots — justified

[FIRST-PRINCIPLES-REVIEWED] 0e5052d

Description read

[DESCRIPTION-READ] d89c044f8af1b7ae50f4280e89e5485f078d8f8391411f2de3fe6237bae22f6e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 0e5052dfae3eea1aa5fd18ed284ceb84072b566b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

Notes:

  • In de, fr, ru, hi and bn, the new hint strings use the informal form of "you", while the copy next to them in components.filePickerMenu uses the formal one. This is a wording choice, not a defect.

[OPUS-REVIEWED] 0e5052d

@NicholasRBowers NicholasRBowers added the needs-pr-triage PR scanner: awaiting automated triage label Sep 18, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 18, 2026
@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from 41c3f5c to 714ce12 Compare September 18, 2026 22:21
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 18, 2026
@NicholasRBowers NicholasRBowers added needs-author-decision PR blocked on author input and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 18, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days. I reviewed the blockers but they require your input:

  • The build cannot pass until fix(files): bound the file reads and name why one failed #10834 merges, and fix(files): bound the file reads and name why one failed #10834 is itself conflicting. The type check fails with TS2307: Cannot find module './RetryControl' and TS2307: Cannot find module '../lib/searchErrorCause' at website/src/components/FilePickerMenu.tsx, plus 'onTabToControl' does not exist in type 'UseListKeyboardNavOptions' and four TS7053 index errors downstream of the missing cause type. That is exactly the prerequisite you flagged at the top of the description. #10834 is still open with mergeable: CONFLICTING, so it needs your conflict resolution before this unit can compile. Every other red here — Build Desktop, Build Wheel, Frontend Tests 1-4, E2E, Bundle Size, Coverage — is downstream of that one type-check failure. I will not inline the prerequisite's code to make this build, because the six-unit split is your deliberate structure and collapsing it would change the PR's design direction.

  • Design Review and UX Review both BLOCK on missing rendered evidence, and the surface cannot currently be rendered. Both verdicts are "cannot evaluate": the workflow's evidence file records "attachments downloaded and typed as images: 0 / recordings: 0" with zero transport failures, and on a fork PR a committed image does not count. They each name the specific states they need — the settled-failure notice with the Retry button, the stale_rows_notice above dimmed (opacity-80) surviving rows, a refusal arm (search_denied / search_root_missing) showing the withheld-Retry layout, and the Retry in-flight busy state. Capturing those requires a build, which brings us back to the prerequisite. Attach them via gh pr edit --attach once fix(files): bound the file reads and name why one failed #10834 lands.

  • First Principles CONCERNS disputes a factual claim about your own intent, and only you can settle it. Its item 6 says the description's defect "a failure blanked rows that were still on screen" is contradicted by the base file's own comment ("Rendered above whatever (stale, placeholder) results are still on screen"), that no hunk touches row derivation, and that a failure on a new query key still blanks rows after this diff — so only the annotation is new, not the retention. It clears when the description drops the kept-vs-cleared claim, or links a reproduction of a base path this diff un-blanks. Its item 10 additionally flags that eight tests here pin the prerequisite's timeout bound and retry policy rather than this unit's behaviour. Choosing between "drop the claim" and "prove the repro" is a statement about what you meant to fix.

For the record, the code-level lanes are clean: GPT 5.6 and Opus 4.8 both report no blocking findings, and the branch has no merge conflict of its own. The order of operations is the blocker, not the code.

When you've addressed these, the pipeline will re-assess on its next cycle.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes: this branch still fails to type-check after its prerequisites merge

The red type check on main is already covered above in NicholasRBowers's comment, which blames it on PR #10834 not having merged yet. That no longer explains all of it. At its current head (22b5c95), PR #10834 no longer carries two of the three things this PR imports. Its description says so: "The shared retry affordance (RetryControl) and the two keyboard hand-offs on useListKeyboardNav are not in this PR ... each lands with the surface that calls it." This PR is that surface, and it doesn't add them.

Two problems remain even after every open PR that supplies a piece has merged:

  • website/src/components/FilePickerMenu.tsx:273 and :287 pass onTabToControl and onEnterToControl to useListKeyboardNav. On main and on PR #10834, UseListKeyboardNavOptions has only open, count, wrap, onChoose, onClose, onAltEnter, releaseKeysWhenEmpty. No open PR head adds either option.
  • FilePickerMenu.tsx:376 renders <RetryControl busy={retrying} controlRef={retryRef} ... />. The only RetryControl.tsx in any open PR is in PR #10842. Its signature is RetryControl({ busy, cause, label, onRetry }), and it keeps its button ref private, so there is no controlRef prop.

A reviewer merged main + PR #10834 + PR #10842 + this PR. The only conflict was in error-code-baseline.json, which the website build doesn't read. They then ran tsc -p tsconfig.app.json, the first step of npm run build. It still exits 2:

FilePickerMenu.tsx(273,5): TS2353 'onTabToControl' does not exist in type 'UseListKeyboardNavOptions'
FilePickerMenu.tsx(376,7): TS2322 ... Property 'controlRef' does not exist on type '... { busy; cause; label; onRetry }'

Impact: the red PR Readiness check blocks a merge today, so main is safe for now. But the plan in the description ("imports searchErrorCause, RetryControl and the useListKeyboardNav hand-offs added there") no longer works. No merge order of today's PRs makes this branch green, and merging it would break the frontend, wheel and desktop builds.

Smallest fix:

  • Add onTabToControl / onEnterToControl to UseListKeyboardNavOptions and to the hook's key handling, either here or back in PR #10834.
  • Reconcile with PR #10842's RetryControl: add a controlRef prop there, or adapt this caller to the { busy, cause, label, onRetry } shape.
  • Update the "Prerequisite: #10834" line in the description so it says which PR supplies each piece.

From a full open-PR audit against origin/main c66f95b (2026-09-25); findings were checked by independent reviewers reading the code. Reply here if this is wrong.

Copy link
Copy Markdown
Contributor

Open-PR triage (origin/main 1e38e86565, 2026-10-05): PARTIALLY_COVERED by #7068 + OVERLAPPING with #10844. Recommendation: continue development, plus a merge discussion about who ships RetryControl. Not closing.

This updates bolichen97's CHANGES_REQUESTED from 2026-09-25. The blocker it names still applies, but the prerequisite picture has changed since then:

  • Now on main, from fix(chat): bound the @-menu file-search fetch so a slow gateway fails visibly #7068 (merged 2026-09-29): website/src/lib/searchErrorCause.ts (searchErrorCause, SearchErrorCause), withDeadline / withJournaledDeadline, and FILE_SEARCH_TIMEOUT_MS = 15_000 on api.fileSearch. The import ../lib/searchErrorCause resolves on main now, and the deadline and 429 tests in FilePickerMenu.timeout.test.tsx pin behaviour that main already has. This PR no longer depends on fix(files): bound the file reads and name why one failed #10834 for those.

  • Still not on main, and not in any open PR head:

    • website/src/components/RetryControl.tsx does not exist on main. Two open PRs import it, this one (FilePickerMenu.tsx, with a controlRef prop) and fix(chat): name why a workspace listing failed #10844 (WorkspacePicker.tsx), and neither adds the file.
    • UseListKeyboardNavOptions in website/src/hooks/useListKeyboardNav.ts on main still has no onTabToControl / onEnterToControl.

    So tsc -b still fails at FilePickerMenu.tsx on the ./RetryControl import and the two unknown hook options, whatever order the open PRs merge in.

  • What this PR does that main does not: main's FilePickerMenu.tsx:300-317 still shows only the generic components.filePickerMenu.search_failed notice. The per-cause copy (_enter_sends / _ctrl_enter_sends), the Retry control, keeping the last cause across a retry, and the stale_rows_notice annotation on kept rows are all new. The branch merges cleanly into current main (git merge-tree, 0 conflicts). It is 2323 commits behind, so a rebase is worth doing after the missing pieces land.

Smallest way forward: add RetryControl.tsx (with controlRef) and the two useListKeyboardNav options to this PR, or to one agreed PR that #10844 also builds on. Then rewrite the "Prerequisite: #10834" line to say which PR supplies each piece. Agreeing on one RetryControl signature now saves #10844 from conflicting with this one later.

I found no breaking change and no P0. The only copy change is search_failed ("Couldn't search files. Try again." → "File search failed"), which is behind the same key and test id. Minor: the comment added at FilePickerMenu.tsx (// The one bounded read that keeps the shared throttle ladder: a 429 here must recover.) has no code under it.

Automated open-PR audit; reply here if any of this is wrong.

@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from 714ce12 to 0794b28 Compare October 9, 2026 14:26

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to ship. All three items from my review on 5d547fd are fixed at this head.

Head reviewed: b70b7b1. I compared it with 5d547fd directly: the code change since then is the live region in FilePickerMenu.tsx and one new test.

What changed since 5d547fd:

  1. Open findings: the three UX items this head already fixes are gone from ## Open findings. The list now holds only items that are still open.
  2. Screenshots: all six image URLs now point at this head's SHA, so the body shows the captures that include the hint row. The PNG files did not change, and they don't need to: the new wrapper adds no visible chrome when there are no hints.
  3. Live region: the hint row is now one region that is always mounted, with aria-live="polite". Only its children change, so screen readers announce "won't send yet" when a retry starts. The new test checks that the region exists before the retry, that its text changes during the retry, and that it is the same DOM node afterwards. That is the right way to test this, because a live region that mounts together with its text is often not announced.

Why I am not approving yet: CI on this head is still running. Readiness is checking, two backend test shards are in progress, and PR Readiness is pending. I will approve and enable auto-merge once readiness reports passed on this head and no lane blocks.

Should-fix, not blocking. The description already lists these under Open findings:

  • website/src/hooks/useListKeyboardNav.ts:75 and :84: the JSDoc says EMPTY-list path only, but the hook also calls both options on the non-empty path.
  • website/src/components/FilePickerMenu.tsx:190: the comment above placeholderData describes a throttle ladder that nothing there sets.
  • website/src/test/FilePickerMenu.timeout.test.tsx:191: the 429 test waits on the real backoff. Fake timers would make it faster and deterministic.

My changes-requested review on 714ce12 is out of date. Its two code items were fixed on 442263e and are still fixed here.

@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from b70b7b1 to ddfe477 Compare October 20, 2026 17:16
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 20, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still looks good to ship. Head reviewed: ddfe477.

I compared it with b70b7b1 directly. Both sit on the same base, so this is a content change, not a rebase:

  1. RetryControl no longer takes a label prop. It reads components.filePickerMenu.retry itself, and the @-menu call site drops the prop. The rendered name is unchanged ("Retry: "), and FilePickerMenu is the only caller, so nothing else is affected.
  2. The synonym-drift test now reads both FilePickerMenu.tsx and RetryControl.tsx, so it still guards against the old "Try again" key after the move.

Why I am not approving yet: CI on this head is not green. Readiness is action required, PR Readiness is failing, the required lanes for this push were cancelled and have not rerun, and backend test shards are still queued or running. I will approve and enable auto-merge once readiness reports passed on this head and no lane blocks.

The three should-fix notes from my last review (the JSDoc on useListKeyboardNav.ts, the placeholderData comment, and the real-backoff 429 test) are unchanged and still non-blocking.

@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from ddfe477 to 9e5ebd1 Compare October 20, 2026 18:28
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 20, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed the change since ddfe477 on head 9e5ebd1. This head is a rebase onto current main plus new content:

  • A path-scoped refusal in path mode now names the path instead of the project folder (new search_denied_path* and check_path_inside_project keys).
  • The surviving-rows hint warns that Tab does not pick a row only while an enabled Retry button holds Tab (showing_earlier_results_tab_skips).
  • The folder hint now names the project button beside the composer.

The new keys exist in all 13 locale files, and four new tests cover these branches. No new findings.

Approval is still held: the readiness label is readiness: action required, PR Readiness is failing, UX Review reports BLOCK on this head, and the backend test shards plus one frontend shard are still running.

@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from 9e5ebd1 to c268767 Compare October 20, 2026 19:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 20, 2026
@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from c268767 to c2915fc Compare October 20, 2026 19:27
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 20, 2026
@rnoack1
rnoack1 force-pushed the fix/at-menu-search-failure-ux branch from c2915fc to 50ec3f9 Compare October 20, 2026 20:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 20, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed the change since 9e5ebd1 on head ab54561. This head is a rebase onto current main plus new content:

  • Retry is now withheld whenever rows are still on screen, so Tab keeps picking a row in that case. The rows-retained Tab and Enter hand-off in FilePickerMenu and its four tests are removed, and the showing_earlier_results* hints go with them in all 13 locale files. The empty-list hand-off in useListKeyboardNav is unchanged.
  • The path-mode refusal hint check_path_inside_project now reads "Pick a different path", and the capture script adds a seventh arm that checks this notice does not mention the project folder.

UX Review moved from BLOCK to CONCERNS on this head, so the earlier UX block is cleared. Its remaining notes (the folder hint naming a chip the user cannot pick out, the send-key text in the alert colour) and the First Principles note on the Retry stack are advisory. No new findings from me.

Approval is still held: the readiness label is readiness: checking, PR Readiness is pending, and the frontend shards, type check, desktop builds, integration and E2E lanes are still running on this head. I will re-check once they finish.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed head 4a111f7 against ab54561. This push rebases onto current main and changes content:

  • The send key promise ("Enter sends the message" / "Ctrl+Enter sends the message") moves out of the failure alert into the muted hint row as its own line. It is only shown when no rows are on screen and the keys are released, so it never claims a key that picks a row or that the retry window has swallowed. The eight combined *_enter_sends keys are gone in every locale, replaced by two standalone keys.
  • The path refusal copy no longer needs its own ctrl/enter variants; one search_denied_path key remains.
  • The failure notice is built once and reused for both the empty and surviving rows branches, which removes the duplicated markup.
  • The folder hint now reads "Click the folder name below the message box to change it", and the captures assert the alert carries no send key line.

No new findings on this delta. Approval is still held for maintainer gates, not code: the readiness label is "action required", the PR Readiness status reports one blocking item, and the backend test shards are still running on this head.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed head 29de45c against 4a111f7 (same base). The change since then: the @-menu now spreads the shared SEARCH_FAILURE_KEYS and overrides only denied and root_missing, the menu's own search_timed_out and search_failed keys are removed from all 13 catalogs, tests and the capture script now expect "Search timed out" and "Search failed", and a new test pins that the menu borrows the shared copy. I checked that no reader of the removed keys remains on this head. No new findings.

Approval is still held on maintainer gates: the readiness label is readiness: action required, PR Readiness reports 1 blocking item, SAST (Semgrep) was cancelled and needs a rerun, and backend test shards are still running. The needs-author-decision label is also still set. Sensitive Change Review, Inclusive Language and PR Hygiene are green on this head.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the rebase. Head reviewed: 18291d0d0b7c89ff6587c1a86c7e330075f5c7f5.

What changed since 29de45c: the branch now sits on current main with no conflict, and FilePickerMenu.tsx uses main's OverlayPortal and hoverSelect. The capture script lost a few comments. Range-diff shows no other change to the PR's own hunks. SAST (Semgrep) is green on this head.

Two findings from the GPT and Opus lanes block merge. I read both against the code at this head and agree with each. Both are about where focus goes around Retry, and each fix is a few lines.

  1. Escape during a keyboard retry drops focus off the composer (FilePickerMenu.tsx, closeReturningFocus). RetryControl sets disabled={busy}, and a disabled button cannot keep focus. So while the retry runs, document.activeElement === retryRef.current is false. Escape then closes the menu without returning focus to the anchor, and the next keys go to the page body. Suggestion: keep a local ref that records that Retry took keyboard focus (set it in onTabToControl and on press, clear it on settle), and check that ref instead of activeElement.

  2. A successful retry always moves focus to the composer (onRetry, if (ok) anchorRef.current?.focus()). The menu stays mounted when closed, and a running fetch is not cancelled, so the retry can settle after the user has moved to another field. Focus then jumps back into the chat draft. Suggestion: return focus only when the menu is still open and focus is still on the Retry button or on document.body.

A test for each would help: Tab, Enter, Escape while pending leaves focus on the composer; and a retry that settles after focus moved elsewhere does not move it.

Backend and frontend test shards are still running on this head, and readiness is not passed yet, so I am not approving at this head. Once both are fixed and CI is green, I will re-review the new head.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. Head reviewed: 3bc296e7b0b3389a2cf995012ea8062ea769ad6c.

Both focus points from my last review are fixed. The menu now uses main's emptyActionRef and restoreEmptyFocus from useListKeyboardNav, so Escape during a pending retry no longer drops focus. A retry that settles no longer moves focus to the composer on its own. The PR no longer edits the hook. There is no conflict with main.

One finding from the Opus lane still blocks merge. I read it against this head and agree.

Retry can show rows from an older query. The query keeps placeholderData: prev => prev. If @re returned rows, and then @rele failed with no data of its own, the empty arm shows Retry. Pressing it puts that key back into pending, so react-query serves the @re rows as placeholder data. results.length > 0 then removes the Retry button mid-press. The failure notice renders above rows from the other search, and Enter or Tab during the retry can insert a mention from that stale list.

Suggestion: while retrying (or when isPlaceholderData is true on a key that never succeeded), treat the results as empty, so the failure arm and its Retry stay until the retry settles. A test for this would help: rows for one query, a failure on a longer query, then Retry, and the old rows must not appear.

Test shards are still running and readiness has not passed, so I am not approving at this head. I will review the next head when it lands.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at abe92ab.

This head fixes the last open point, the one the Opus lane raised: a retry on a key that never loaded no longer shows the previous query's placeholder rows. staleRetry = retrying && isPlaceholderData empties the results while that retry runs, so the failure notice and its Retry stay in place until it settles. A new test covers rows for one query, a failure on a longer one, then Retry, and checks that the old rows do not come back.

The two focus points from my earlier review stay fixed through emptyActionRef and restoreEmptyFocus. I read every PR-own hunk across the earlier heads and this delta; the 25 files include tests and locale strings.

No conflict with main. Every AI review lane passes on this head, including the Security Scope rerun, and no check is red. One backend shard and readiness are still running, and auto-merge waits for them.

Replaces the single generic search-failure notice with cause-keyed copy for a timeout, a refusal, a missing root and an unknown error, each spelling the key that actually sends, and keeps stale rows visible rather than blanking them.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) needs-author-decision PR blocked on author input

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants