Skip to content

fix(dashboard): name a failed recents read in the project picker - #10842

Closed
rnoack1 wants to merge 1 commit into
kirodotdev:mainfrom
rnoack1:fix/project-picker-listing-failure-ux
Closed

rnoack1 wants to merge 1 commit into
kirodotdev:mainfrom
rnoack1:fix/project-picker-listing-failure-ux

Conversation

@rnoack1

@rnoack1 rnoack1 commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A failed recents read in the project picker was swallowed. api.recentProjects()
ended in .catch(() => setTab('browse')), which acts on the failure but throws the
cause away — so the Recent tab silently held nothing, and reopening the popover
looked like it had lost the list. Nothing named the failure and nothing offered to
re-read it.

Why it matters

A failed read is indistinguishable from an empty one, so the user is told "No recent
projects" about a list that was never fetched. The only recovery was to close and
reopen the popover, which re-runs the same read with no indication that a read is
what failed.

What changed (motivation → approach → change)

The read now reports whether it landed and how many rows it produced, so a single
rule decides the landing tab for both the initial open and a retry, rather than that
rule living twice. When it failed, the picker says so and pairs the notice with a
Retry that re-reads the list and, on recovery, returns focus to the first control
that still exists.

The notice follows the user rather than sitting on one tab. The failure itself is
what selects Browse, so a Recent-only notice would never be seen: it shows on either
tab until she chooses one deliberately, and only on Recent thereafter.

RetryControl is its own component rather than markup at the call site because the
parts that are easy to get wrong are the invisible ones — the aria-busy pair, the
"<label>: <cause>" accessible name, and returning focus to the button after a
failed attempt so a keyboard user does not spend a Tab per retry.

Deliberately not included, both narrowing this unit:

  • No useQuery migration. An earlier revision of this PR converted recents from
    useState to useQuery to obtain refetch. Extracting the existing fetch into a
    callback yields the same handle, so the retry does not require that architectural
    change or the tab-landing bookkeeping that came with it.
  • No controlRef on RetryControl. Nothing in this unit reads it, so it would
    ship as an unused optional prop. The surface that needs it (keyboard nav handing
    Tab and Enter to the control) can add it with its own caller.

This unit does not touch the listing failure notice. That is already on mainline
via #11424, and is left exactly as it is.

Tests

website/src/test/ProjectPicker.recentsRetry.test.tsx, 7 cases: the failure is
named; nothing is said on success; Retry clears the notice and shows the rows; a
failed retry keeps the notice and leaves the control enabled; the notice reaches
Browse, which the failure selected; it stops following once Browse is chosen
deliberately; and it is still there on the Recent tab she opens to look for it.

Break-armed: restoring the old .catch(() => setTab('browse')) swallow fails 6 of
the 7, and the case that survives is "says nothing when the read succeeds" — the one
that should pass without this change. So the suite discriminates rather than
failing wholesale.

Manual verification

Verified locally at this revision: tsc -p tsconfig.app.json clean, eslint src
clean, i18n:check / check-i18n-keys / lint:i18n all pass, and 185 tests green
across the seven affected suites (ProjectPicker.recentsRetry, ProjectPicker,
ProjectPicker.keyboardIsolation, ProjectPicker.pathDelimiter,
FolderConfigModal, WorkspacePickerCoverage, ImeEnterGuardSites).

Two catalog keys across all 13 locales. The English pair is in en.json alongside
every other projectPicker key — not en.manual.json, which carries no such
namespace — and en-XA is regenerated by i18n:pseudo rather than hand-written.

Screenshots

One frame applies, captured by the harness at an earlier revision of this branch
(d55a0105) and showing precisely what this revision renders: the notice on the
Browse tab, which the failed read selected, with Retry beside it.

Notice Frame
Recents unavailable, on the tab the failure selected Recents unavailable with Retry, on the Browse tab

The notice row's markup is unchanged between that revision and this one — same
wrapper classes, same ErrorNotice, same gate shape; only the state variable was
renamed — so the frame is faithful to what ships here.

The harness's other five frames are not cited, because they show behaviour this
unit no longer ships: a recents loading state, and the listing-failure retry.
loading_recent, listCause and listRecoverable all appear 0 times in this
revision.

Pattern harvest

Rule candidate: eslint

Pattern: a rejection from an api.* call discarded by a handler that neither
surfaces nor stores the cause, so the caller renders its empty state as though the
read had succeeded. At this revision's base (upstream/main) the instance this PR
fixes was website/src/components/ProjectPicker.tsx:146 —
.catch(() => setTab('browse')), which acts on the failure but keeps none of it.

The retirable rule is narrow and syntactic: flag a .catch on an api.* promise
whose handler binds no rejection parameter, or binds one and never reads it. A
handler that assigns the cause to state or rethrows is not caught. This belongs in
lint rather than a review prompt because the defect is invisible at the call site by
construction — the code reads as though failure were handled.

One instance remains unfixed and would be caught by that rule:
website/src/components/WorkspacePicker.tsx:35, a body-less .catch(() => {}) on
api.browseDirs, which leaves its list claiming no subdirectories for a directory
that was never read. It is left for the unit that owns that surface.

@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
@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 bolichen97 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) — 🔴 BLOCK

UX-level review of e2d97507f53e9e825ec870dc7eaac6d14fa4dc35 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: BLOCK

cannot evaluate: missing a screenshot of the recents-failure Retry on Browse, in both its idle and its "Retrying…" state; no image reached this review.

Evidence gaps

  • The Retry button on the recents-failure notice (Browse tab). noticeRetry → { busy: retryingRecent, run: retryRecents } adds a new action to the browseNotice row. The image list is empty, and the description's only frame shows up as "[image removed]". That frame was taken at d55a0105, not this HEAD, so it can't close the gap anyway. Fix: attach a still from this revision.
  • The "Retrying…" busy state of that button (noticeRetry.busy ? …retrying). No image shows it. Fix: attach a frame taken while the retry is pending.

Watch

  • The description promises behaviour this diff doesn't have. It says the notice "shows on either tab" and stays on Recent. The diff's own comment says "The recents Retry lives only here, on Browse." The described RetryControl, its focus return and its "two catalog keys" aren't in the patch either. Reviewers and screenshots would be checked against behaviour that doesn't ship. Fix: rewrite the description to match the diff, or ship what it describes.
  • Recent rows go dead with no visible reason. While a failure or retry is active, clicking a recent row hits if (recentFailure || retryingRecent) return. The row stays on screen and clickable-looking, but nothing happens and nothing says why. This is moderate friction, since it only happens after a failed read. Fix: show the rows as disabled, or hide them while the read is failed.

[UX-REVIEWED] e2d9750

Description read

[DESCRIPTION-READ] f6e43083636f9e24261d5e0e5da2de6c82ab47a97e8920a779e08ea55c85f32f

That sha256 names everything this verdict read: the PR description, plus the 3 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) — 🔴 BLOCK (blocking)

Design-level review of e2d97507f53e9e825ec870dc7eaac6d14fa4dc35 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: BLOCK

cannot evaluate: missing a screenshot of the recents-failure Retry on the Browse notice at this revision. The description also describes a different change from the diff.

Blockers

No rendered evidence for a new control
Cause: the diff adds a Retry to the Browse notice for a failed recents read (noticeRetry = listFailure ? … : recentFailure ? { busy: retryingRecent, run: retryRecents }) and a new "Retrying…" state → mechanism: the evidence list shows 0 images and 0 recordings. The one frame the description cites is "[image removed]", taken "at an earlier revision (d55a0105)" → consequence: no one can judge the shape of this surface as it ships.
Fix: attach or commit a capture of this revision showing the Browse notice with Retry, and the same notice in its Retrying… state.
Clears when: a screenshot of the head e2d97507 showing the recents-failure notice with Retry and Retrying… on Browse appears in design-evidence.txt

Watch

The description does not match the diff. The problem it states is already fixed on the base: recentFailure and the named notices exist at ProjectPicker.tsx:216,592,780, and nothing swallows the read any more. Several claims have no code behind them:

  • a RetryControl component;
  • "two catalog keys across all 13 locales";
  • "the notice follows the user … on either tab". The diff does the opposite and puts Retry "only here, on Browse".
  • The 7 tests it lists do not match the 7 in the new test file.

The holdTab landing-tab guard is new behaviour, and the description never mentions it. It is armed by tab clicks, typing, going up a level and drilling into a folder.

Clears when: the description is rewritten to cover this diff's two changes (a recents Retry placed on Browse only, and holdTab keeping the user's tab), with the phantom claims removed

[DESIGN-REVIEWED] e2d9750

Description read

[DESCRIPTION-READ] e80b27a7bf4bf40ab3456a5d870aa9f9e4a075b45fc2db353b7b25c0e6a39d4b

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

First Principles Review (Opus 5.5, fork) — 🔴 BLOCK

Premise-level review of e2d97507f53e9e825ec870dc7eaac6d14fa4dc35 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/CONCERNS are advisory.

First-Principles-Verdict: BLOCK

The description describes a different change: base already names the recents failure, and the RetryControl, focus return and catalog keys it claims are not in the diff.

Not justified as shipped

  • Item 2 — undeclared: the description never mentions it, and no linked issue reports a late read moving the user. Separately, keyboard Enter-drill (ProjectPicker.tsx:878) still lets the tab move: 1 of 5 engagement paths is left unarmed.
    Subtraction: delete holdTab and its 6 assignments; send it as its own unit.
    Clears when: a reported defect is linked, or holdTab is removed.
  • Item 3 — zero consumers: every failure sets setRecentDirs([]) and a retry only starts while that failure stands, so no row is ever there for the guard to block.
    Subtraction: delete both recentFailure || retryingRecent guards.
    Clears when: the guards are removed.

What this change ships

Inventory (3 items) — 1 justified

Intent: let a user re-read a failed recents list without closing and reopening the picker. The title calls it a FIX; it is an ADDITION.

  1. A Retry button on the Browse notice re-reads recents — justified
  2. A late list read no longer moves the tab once the user has done something in the picker — undeclared
  3. Recent rows can't be chosen while the read is failed or retrying — zero consumers

Blockers

  • The description and the diff do not match. The description's problem is ".catch(() => setTab('browse')) … silently held nothing", but base ProjectPicker.tsx:418-422 already sets recentFailure and hides "No recent projects" (:799). The description says "a single rule decides the landing tab for both the initial open and a retry", while the diff says the retry "deliberately never settles the landing tab". "RetryControl is its own component", "returns focus" and "Two catalog keys across all 13 locales" appear nowhere in the patch.
    Subtraction: remove the claims for things the diff does not ship.
    Clears when: the description matches the diff, item 1 alone.

[FIRST-PRINCIPLES-REVIEWED] e2d9750

Description read

[DESCRIPTION-READ] 5f38a62965a5062fa7306abc0f73537b5f382a1775980734bfb23404084fbfee

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

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] e2d9750

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

Pressing Enter to open a folder leaves the user unprotected from the late tab switch that a mouse click on the same folder is now protected from.

FINDING — website/src/components/ProjectPicker.tsx:917 — When the user presses Enter in the path field to open a folder, the code runs browse(filteredBrowse[browseSel].path) but never sets holdTab.current = true. browse fills the field with setInput, which does not trigger onChange, so the hold is never set that way either. If the picker reopens on Browse and the recents read finishes after the user has pressed Enter on a folder, settle reaches setTab('favorites') and moves the user off Browse. A mouse click on the same folder (onClick={() => { holdTab.current = true; browse(d.path) }}) and ArrowLeft (goUp) both keep the user on Browse. → Fix: set holdTab.current = true in the Enter-drill branch before calling browse(...).

[OPUS-REVIEWED] e2d9750

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 17, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from f8fba90 to c75a8b9 Compare September 17, 2026 10:55
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 17, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from c75a8b9 to cb4df84 Compare September 17, 2026 11:59
@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 Sep 17, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch 4 times, most recently from 3b40de0 to 53966bb Compare September 17, 2026 16:58
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 19, 2026
@rnoack1 rnoack1 changed the title fix(chat): name why a project listing failed, persist the retried dir fix(dashboard): name a failed recents read in the project picker Sep 19, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from 81a57ac to e2fb6f3 Compare September 24, 2026 15:23
@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 Sep 24, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from e2fb6f3 to e902d04 Compare September 26, 2026 23:49
@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 Sep 26, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from e902d04 to 85ba53f Compare September 27, 2026 00:35
@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 Sep 27, 2026
@rnoack1
rnoack1 force-pushed the fix/project-picker-listing-failure-ux branch from 85ba53f to 81553ef Compare September 27, 2026 02:30
@dodgeblaster

Copy link
Copy Markdown
Contributor

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

  • UX BLOCK + Design BLOCK: both block solely on missing rendered screenshot evidence of the new "Recent projects unavailable" notice and Retry control. The only cited image is a stale fork URL pinned to a commit outside this PR, so the gate downloaded 0 attachments. Please attach a screenshot of that surface to the PR description (drag it into the editor so it uploads to GitHub's user-attachments CDN). This fork pipeline cannot render that frame on your behalf.
  • PR Hygiene: one required description section is missing — please add it.
  • Opus 5 also raised a non-blocking keyboard-reachability FINDING at ProjectPicker.tsx:369 (the Retry button cannot be reached by keyboard) worth addressing while you're in there.

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

Copy link
Copy Markdown
Contributor

Triage (PR-overlap scan vs origin/main a97659d) — relationship: PARTIALLY_COVERED by merged #7068; overlapping open PR #16611. Not closing.

Already on main via #7068 (18243811d6, merged 2026-09-29, website/src/components/ProjectPicker.tsx):

  • The recents .catch(() => setTab('browse')) this PR targets no longer exists. .catch((err) => { …; setRecentDirs([]); setRecentFailure({ cause: searchErrorCause(err), … }); setTab('browse') }), with a recentSeq ticket that retires stale reads (main ~L291-301).
  • A cause-keyed notice is shown on both tabs (Browse: RECENT_FAILED_KEYS via browseNotice, ~L410; Recent: RECENT_TAB_FAILED_KEYS, pp-recent-tab-error, ~L500).
  • "No recent projects" is hidden after a failed read (~L519).
  • New catalog keys recent_failed*, plus projectPicker.retry / retrying already in en.json.

Not on main, so this is still unique to this PR: a Retry that re-reads recents, the holdTab guard so a slow read can't flip the tab after the user has engaged, and gating row activation while the read is failed or in flight.

Rebase needed: the branch is 2266 commits behind main, and git merge-tree reports conflicts in ProjectPicker.tsx and all 13 locale files. If you rebase as-is, you'd get a second notice (recent_unavailable) next to main's recentFailure notice, and projectPicker.retry would collide with the key that's already there. Suggest cutting this down to "add Retry to main's existing recents notice": reuse recentFailure/recentSeq and the existing retry/retrying keys, and follow the aria-disabled Retry pattern main uses for listings (~L629). The non-blocking Opus finding that the Retry can't be reached by keyboard still applies.

Merge discussion: #16611 (Favorites tab) rewrites the same recents landing-tab and setTab logic (settle('recent', …)). Whichever lands second has to reconcile the tab-landing rule with this PR's holdTabRef.

No breaking change or P0 found, so no change request.

The picker now says the recents list could not be read instead of silently
falling back to Browse, and pairs that notice with a Retry that re-reads it.
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you @rnoack1 for this fix and for the careful write-up and tests.

The naming half of this PR had already landed on main via #7068, so we carried the remaining part, the recents Retry, onto current main in #21148. Your commit is cherry-picked there with your authorship kept, and the follow-up commit credits you as co-author.

One change from your version: the holdTab landing-tab guard was left out, because review asked that #21148 stay scoped to the Retry. It is a separate behaviour on the opening read, and it would be welcome as its own PR.

Closing this in favour of #21148. Your branch is left in place.

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.

6 participants