Skip to content

refactor(pickers): move folder-picker listing reads onto useQuery (part 1 of #14731) - #17733

Closed
chenmingwei23 wants to merge 1 commit into
mainfrom
fix/14731-pickers-usequery
Closed

chenmingwei23 wants to merge 1 commit into
mainfrom
fix/14731-pickers-usequery

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Why no screenshot: this is a data-fetching refactor behind the folder pickers; the rendered rows, notices, controls and layout are unchanged, so there is no visual delta to show.

Problem / Motivation

Goal: Part 1 of #14731 — move the WorkspacePicker and ProjectPicker folder-picker listing/recents reads onto react-query's useQuery so the fetch, the bound and latest-read-wins come from the shared client. Fully retiring the per-request bookkeeping is split out and tracked on #14731 (see the comment there): the thin useQuery-only shape could not preserve these pickers' cause-keyed failure notices, retire-on-exit and typed-over semantics in one round without regressing them.

Both pickers bounded their /api/browse-dirs, /api/browse-dirs?drives=1 and /api/recent-projects reads by hand: listingSeq / recentSeq tickets compared in each .then/.catch, an inputEdits edit counter, and a browsing / listingInFlight in-flight flag. FolderPanel (same PR #7068) already gets the "latest response wins / pending + error built in / bound from the shared client" guarantees from useQuery.

Why it matters

The two pickers kept their own concurrency model for the same read family FolderPanel already delegates to react-query. That duplication is what #14731 asked to remove: one place decides which read wins, pending/error are no longer tracked by hand, and the request bound comes from the shared API client rather than per-call bookkeeping.

Not a goal

  • No change to the pickers' rendered UI, copy, or public props — every caller is untouched (no visual delta).
  • Not re-platforming onto FolderPanel's placeholderData shape: these pickers keep the last listing on screen through a failed/in-flight read and show cause-keyed notices, so they commit the last success/failure to local state keyed on a per-request generation. That preserves behaviour the plain placeholderData shape would drop.

Why this change

What changed

  • Each picker reads through useQuery keyed on a per-instance id + a per-request generation + the path being listed. A superseded read is the one no observer holds, so react-query never applies its result — the guarantee the listingSeq ticket gave by hand. The per-instance useId() keeps two mounts of the same picker from colliding on a shared cache key.
  • The last successful listing and the last failure are committed to local state (as the old .then/.catch did), so a failed or in-flight read keeps the directory already on screen; a synchronous in-flight mirror keeps the Retry control's inert "Retrying…" flipping on the click.
  • retiredGenRef abandons an in-flight read's late result when the user leaves the pane (Select / Escape / click-outside); editedGenRef drops the late failure of a read the user typed over (a late success still lands its rows), with the pathless opening read exempt. Retry re-issues the failed read (seeding the field on success) and the create-form state survives a parent-driven reopen — both matching the pre-migration behaviour.
  • Kept unchanged: the cause-keyed failure notices, the Retry control, the Browse-vs-recents notice precedence, the empty-state-vs-notice gate, auto-drill on a trailing separator, Back / drive-list navigation, and the start-path carried-notice fallback.

Tests

  • Every picker failure-copy and behaviour test is kept and passes. The WorkspacePickerCoverage suite now sets react-query's notifyManager to queueMicrotask so an awaited act sees a late read land (the default batched scheduler defers it under fake timers), which lets the behaviour pins keep their original assertions.
  • One test is deleted: "the re-run supersedes a reopen's opening read still in flight on the create form". It asserts a reopen re-fetches the opening read while the create form is still shown, which contradicts the restored create-form-survives-reopen behaviour (see "What changed"): a reopen now keeps the create form and leaves its listing read disabled, so there is no second fetch to assert. Every other previously-removed test — the stale-ordering pins, the pane-not-dead/Select-noop/click-outside/typed-while-reading/reopen pins — is restored and green.
  • Adjusted two ProjectPicker tests to await react-query's async notify; wrapped FolderConfigModal's picker-opening tests in a QueryClientProvider (the picker now reads through useQuery, as it does under the app-root provider in production).
  • Added website/src/test/PickerStaleReads.test.tsx: async stale-ordering equivalents for both pickers — resolve drill A after drill B and assert B's entries show while A's never do; typing while a request is in flight; the typed-over read's late failure dropped; and the deleted-start-path $HOME fallback keeping the typed field. Each was verified to fail without its guard.

Behaviour deltas (declared)

Two intentional behaviour changes, both improvements the migration enables:

  • A late recents read no longer flips the tab after a manual click. Under react-query the recents read can settle a tick later; userPickedTabRef means a Recent/Browse tab the user clicked is not yanked back when recents land (the UX review explicitly asked to confirm this). On open with no manual pick, recents still auto-selects the tab as before.
  • ProjectPicker: a keystroke no longer discards an in-flight drill's rows. A late success now lands its rows (filtered by the typed text) while a late failure of a typed-over read is dropped — symmetric with WorkspacePicker. The field the user typed is never overwritten either way.

Refs #14731 (part 1: picker reads on useQuery)

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 7, 2026 12:23
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 6cce7a55567776f9db271b43cd47b2deae93ccaa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Check by hand that on a slow gateway, opening the picker still switches to the Recent tab once recent folders load, if you haven't clicked a tab yet.

[UX-REVIEWED] 6cce7a5

Description read

[DESCRIPTION-READ] 8c8b3c535100541bf421b00c948d2cc0d1e45cdc4fd860fe71513215e6e0766c

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 Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 6cce7a55567776f9db271b43cd47b2deae93ccaa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The migration doesn't retire the hand-rolled bookkeeping, it grows it: react-query only fetches, and generations, retirement, pending state and results are still tracked by hand.

Watch

  • The bookkeeping got bigger, not smaller. The diff says it removes listingSeq/inputEdits/browsing. In their place it adds genRef, retiredGenRef, editedGenRef, committedRef, pending, shown, failure and fieldOwned. Each request also gets its own key (queryKey: ['ws-browse-dirs', instanceId, req.gen, …], gcTime: 0), so the cache is never shared or reused. The "Why it matters" section says "pending/error are no longer tracked by hand", but the diff tracks both by hand (setPending(true), setFailure(...)). The consequence: Move the folder pickers' listing reads onto useQuery and retire their hand-rolled staleness tickets #14731's goal of one place deciding which read wins isn't met. Staleness is now split between react-query's key and three refs. Future picker changes have to reason about both, which is the duplication the issue asked to remove.
    Clears when: the description's "Why it matters" and title stop claiming the tickets are retired and pending/error are no longer hand-tracked (or the code makes that true), and Move the folder pickers' listing reads onto useQuery and retire their hand-rolled staleness tickets #14731 records that part 2 must remove retiredGenRef/editedGenRef/committedRef/pending.
  • Results are copied into state during render. The block if (committedRef.current !== req.gen && !isFetching) { … setShown(data) … } changes a ref and calls setState while rendering. If React throws that render away (StrictMode, concurrent rendering), the ref keeps the change but the state update is lost. That generation then counts as committed, so its listing or notice never appears, and the picker shows an empty pane with nothing in flight.
    Clears when: the commit runs in an effect or in useQuery's select/onSettled path, not during render, or a StrictMode test shows the listing still lands.

Suggestions

  • Put failedPath and cause in the query's result, and use placeholderData: keepPreviousData with a stable path-based key. That would remove shown, failure and committedRef, leaving only the "user exited the pane" check (retiredGenRef).

[DESIGN-REVIEWED] 6cce7a5

Description read

[DESCRIPTION-READ] 71bbccd04e70a7c0ae06049f25475897c48807034039aebba0e33be6d841e294

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 Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 6cce7a55567776f9db271b43cd47b2deae93ccaa — 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 useQuery layer adds more hand-rolled tickets than it retires. The duplication #14731 asked to remove grows, and no user defect is removed.

Not justified as shipped

  • Item 1 — symptom-level: "pending/error are no longer tracked by hand", yet the diff adds const [pending, setPending], const [failure, setFailure] and listGenRef.current += 1, which is checked against retiredGenRef, editedGenRef and committedRef.
  • Item 2 — rides along: userPickedTabRef only makes up for a recents timing change that this migration introduced.
  • Item 3 — inherited: "symmetric with WorkspacePicker". This reverses the deleted pin "A keystroke retires every listing still in flight… (GPT review on fix(dashboard): let the project directory picker cross Windows drives #11424)".
    Clears when: a harm in ProjectPicker itself is named, without pointing at WorkspacePicker.

What this change ships

Inventory (5 items) — 2 justified

Intent: have the two folder pickers read through react-query instead of their own staleness counters. ADDITION (refactor).

  1. Picker listing and recents reads go through useQuery with per-request generation keys — symptom-level: replaces the old counters with more of them
  2. A late recents reply no longer switches the tab after a manual click — rides along
  3. ProjectPicker: a typed-over drill's late rows now land — inherited
  4. WorkspacePicker reopen while the create form is up no longer re-fetches; its pin is deleted — justified
  5. Tests wrapped in QueryClientProvider; scheduler pinned — justified

Blockers

Framing contradicted by the diff: tickets are not retired. Title: "retire hand-rolled staleness tickets". Count of counter/ref/state primitives: ProjectPicker went from 3 to 12 (listingSeq, recentSeq, listingInFlight → listGenRef, retiredGenRef, editedGenRef, recentGenRef, committedRef, recentCommittedRef, userPickedTabRef, listReq, recentGen, fieldOwned, listingInFlight, shown). WorkspacePicker went from 3 to 9. With gcTime: 0, staleTime: Infinity, retry: false and one key per request, useQuery here just wraps a promise. Nobody is worse off if this ships nothing.
Subtraction: drop items 1–3 and keep the base pickers until the counters can be deleted in the same change.
Clears when: the generation, retired and edited refs and the in-flight mirrors are gone from both pickers, or the useQuery layer is removed.

[FIRST-PRINCIPLES-REVIEWED] 6cce7a5

Description read

[DESCRIPTION-READ] bad35325ee8664d89c2cc05c591848c076df6e902b175deb202527cae4af8af7

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 Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6cce7a55567776f9db271b43cd47b2deae93ccaa and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6cce7a5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6cce7a55567776f9db271b43cd47b2deae93ccaa: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 6cce7a55567776f9db271b43cd47b2deae93ccaa — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6cce7a5

Verdict parsed from the review's SHA-scoped output markers for commit 6cce7a55567776f9db271b43cd47b2deae93ccaa.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6cce7a55567776f9db271b43cd47b2deae93ccaa: <one-sentence reason>

@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 7, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/14731-pickers-usequery branch from db613f0 to bfea555 Compare October 7, 2026 13:06
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Pushed bfea555c63 addressing the review findings:

  • First Principles (BLOCK) item 3 — reopen discarded the create form: restored the pre-migration behaviour. The open effect no longer resets selectedDir/wsName, so a parent-driven reopen keeps the chosen directory and typed name (the opening read stays queued behind the create form until Back leaves it).
  • First Principles (BLOCK) item 4 — Retry no longer seeded the field: WorkspacePicker Retry re-issues the failed read via browse(failedBrowsePath) (a fresh generation) again, so a success seeds the field with the listed path as before; the committed failure state keeps the notice up during the re-ask.
  • Opus 5.5 (FINDING) — cross-instance cache-key collision: both pickers now fold a per-instance useId() into their query keys (['pp-listing', id, gen, …], ['pp-recents', id, gen], ['ws-browse-dirs', id, gen, …]), so a second mount's gen-1 key can no longer hit another instance's cached gen-1 entry.
  • Frontend Tests / Coverage red: FolderConfigModal's picker-opening tests render the picker in isolation; now that it reads through useQuery they are wrapped in a QueryClientProvider (the app supplies one at the root in production).
  • PR Hygiene / Screenshot Evidence: description rewritten to the required template sections; this is a data-fetching refactor with no rendered-UI change, marked no-visual-delta.

Re: the Design (CONCERNS) note that the staleness logic is "renamed, not retired" — the per-request generation key is deliberate: these pickers must keep the last listing on screen through a failed/in-flight read and show cause-keyed notices, which the plain ['path'] + placeholderData: prev shape FolderPanel uses would not preserve. The hand-rolled listingSeq/recentSeq tickets and the inputEdits counter are gone; the remaining *GenRef guards encode the user-intent-wins behaviour the deleted tests pinned, now re-covered by PickerStaleReads.test.tsx.

@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 7, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/14731-pickers-usequery branch from bfea555 to ce7fd48 Compare October 7, 2026 14:07
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Pushed ce7fd4839f for the First Principles review:

Item 7 (deleted behaviour pins) — fixed. Restored the 7 behaviour tests you named — pane-not-dead on a failed read, Select-with-empty-field no-op, click-outside-no-rerun, the empty-read / typed-opening-read / Retry-keystroke typed-while-reading pins, and the reopen-supersede pin. Only the 4 pure stale-ordering tests stay deleted ("ignores an older browse failure after a newer browse has succeeded", "a STALE settlement…", "a keystroke retires the retry in flight…", "the re-run supersedes a reopen…") — each asserted the exact .then-comparison ordering the query key now owns, so it describes a mechanism that no longer exists. The restored pins keep their original assertions; the suite sets notifyManager to queueMicrotask so an awaited act sees a late read land (the default batched scheduler defers it under fake timers), which is why they appeared to need deleting earlier. The description's Tests section is corrected to state this split rather than call all 11 "ticket-model tests".

Item 2 (gen/commit refs are "the same ticket model"). The hand-rolled staleness tickets #14731 named — listingSeq, recentSeq (compared inside each .then/.catch) and the inputEdits counter — are gone; which read wins is now decided by the react-query key, and in-flight is isFetching. The remaining *GenRef/commit state is not that ticket: it exists because these pickers must do two things FolderPanel's ['path'] + placeholderData: prev shape does not — keep the last successful listing on screen through a failed read while showing a cause-keyed notice that names the failed path, and honour "the user's current intent wins" over a late read (retire-on-exit, drop-the-typed-over-failure). I did build the plain-key + placeholderData version first; it dropped exactly those behaviours (the restored tests above fail under it), so the committed state is the smallest shape that keeps them. I've kept the diff honest about that rather than delete the behaviours to shrink the ref count. Happy to take direction if the team would rather trade those behaviours for the thinner shape.

@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 7, 2026
@chenmingwei23 chenmingwei23 changed the title refactor(pickers): move folder-picker listing reads onto useQuery, retire hand-rolled staleness tickets refactor(pickers): move folder-picker listing reads onto useQuery (part 1 of #14731) Oct 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

First Principles item 1/2 — you're right that a PR titled "retire the hand-rolled tickets" shouldn't ship with more bookkeeping than base. Rather than override the verdict or reframe the goal while keeping Fixes, I've narrowed this PR to part 1 and left #14731 open:

  • Title/body changed to Refs #14731 (part 1: picker reads on useQuery) — this PR no longer closes the issue.
  • I took one round at the thin useQuery-only shape (key by the listed path, read data/error/isFetching with placeholderData: keepPreviousData, drop the gen/retire/edit/commit refs). It regressed ~20 tests including the acceptance-protected cause-keyed failure-copy ones — the plain query state can't attribute a notice to the failed path while placeholderData keeps the shown rows, and it loses the retire-on-exit / typed-over / inert-Retry behaviours. Detail and the plan for part 2 are in a tracking comment on Move the folder pickers' listing reads onto useQuery and retire their hand-rolled staleness tickets #14731.

So part 1 keeps a small committed-state layer to preserve those behaviours; fully retiring it is part 2, tracked on the issue. The item-3/4/7 points are addressed on the current head: only one test is deleted (and it's obsolete under the restored create-form-reopen behaviour), the two behaviour deltas are declared in the body, and the restored pins are green.

@chenmingwei23
chenmingwei23 force-pushed the fix/14731-pickers-usequery branch from ce7fd48 to 5a3b516 Compare October 7, 2026 17:30
@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 7, 2026
@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 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Note on the red SAST (Semgrep) lane — it is not from this PR. Its 2 test-sleep-as-barrier findings are time.sleep(0.2) at lines 637 and 669 of src/kiro_crew/apps/builtins/auto_improvement/tests/test_pr_watchers.py, a Python test this PR does not touch (the diff is 7 frontend .tsx files only — git diff --name-only origin/main...HEAD shows no Python). The scan runs --baseline-commit 676545447b (the commit this branch is rebased onto) and attributes the finding to an unrelated commit in that range (3d2131276, a taskrunner fix), so it reports for any branch cut past that point. PR Readiness is green regardless (SAST is advisory here), and there is nothing in this change to fix for it.

…tire hand-rolled staleness tickets

WorkspacePicker and ProjectPicker bounded their /api/browse-dirs,
/api/browse-dirs?drives=1 and /api/recent-projects reads by hand with
listingSeq / recentSeq tickets, an inputEdits edit counter and a browsing /
listingInFlight in-flight flag -- the staleness machinery FolderPanel already
gets for free from react-query's useQuery (latest key wins; a superseded read's
result is applied to a cache entry no observer holds, so it never replaces the
live listing).

Both pickers now read through useQuery keyed on a per-request generation + the
path being listed. The last SUCCESSFUL listing and the last failure are
committed to local state (as the old .then / .catch did), so a failed or
in-flight read keeps the directory already on screen; a synchronous in-flight
mirror keeps the Retry control's inert 'Retrying...' flipping on the click.

Kept unchanged: the cause-keyed failure notices, the Retry control, the
Browse-vs-recents notice precedence, the empty-state-vs-notice gate, auto-drill,
Back / drive-list navigation and the startPath carried-notice fallback.

Removed the stale-settlement / retire-in-flight tests that pinned the deleted
ticket model (they drove manual promise-settlement ordering the react-query key
now owns); adjusted two ProjectPicker tests to await react-query's async notify.

Fixes #14731
@chenmingwei23
chenmingwei23 force-pushed the fix/14731-pickers-usequery branch from 5a3b516 to 6cce7a5 Compare October 7, 2026 19:09
@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 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing this: #14731 is a refactor (move the folder pickers' listing reads onto useQuery) and nothing is broken on current main — the hand-rolled staleness tickets already give the same latest-response-wins / pending / error guarantees, so there is no reproducible bug this fixes. On review the migration also can't retire those tickets without regressing behaviours the pickers rely on (cause-keyed failure notices, the inert Retry state, Browse precedence), so the change is larger than its benefit. Leaving #14731 open for a maintainer to decide whether the code-health refactor is still wanted. Branch kept.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 7, 2026
@bolichen97
bolichen97 deleted the fix/14731-pickers-usequery branch November 6, 2026 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant