Skip to content

fix(files): bound the project tree walk and build its body off the loop - #16029

Merged
bolichen97 merged 1 commit into
mainfrom
fix/project-tree-bounded-walk
Oct 4, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/project-tree-bounded-walk

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Opening the workspace tree on a large project no longer stalls the gateway every 10 seconds.

GET /api/project/tree reads a non-git project with os.walk twice, over the whole tree. Only files were capped; every directory row was returned. It then redacted every row and serialized the body ON the event loop. The tree refetches every 10 s while it is open (PierreWorkspaceTreeImpl.tsx), so a big non-git project dir froze every other request the gateway was serving, on every poll. The same walk also answers for a git repository whose ls-files overflows its 8 MiB cap or 15 s timeout, and for a host with no sandbox backend.

Why it matters

Anyone with a large non-git folder (data, logs, a vendored tree) open in the Files tab gets a gateway that pauses every 10 s, for chat, streaming and every other tab, for as long as the tree is open.

Not a goal

  • Lazy per-folder loading of the tree (the long-term alternative to a capped listing).
  • A server-side name search inside the Files rail (FileBrowserRail); its filter stays local, as it already was for files past the cap.

What changed (motivation → approach → change)

Before After
Walk os.walk twice, unbounded one breadth-first scandir pass, at most _PROJECT_TREE_SCAN_LIMIT (200,000) entries, each folder read once
Cap 10,000 files; folder rows uncapped 10,000 rows, files and folders together, on both branches
Redaction + JSON on the event loop in the same worker thread as the listing (_project_tree_body)
Truncation truncated = files were dropped truncated = truncatedDirectories is non-empty; every shown folder whose listing was cut is named

The root cause is that the walk's cost, and the size of the body, grew with the project. Bounding only files left directories free, and the per-row work on the loop made every row block the gateway. So the cost is bounded at three points, all in src/kiro_crew/dashboard/file_api/project_tree.py (the tree route's owner; its two new constants live with the other module state in handlers/files.py). The scan budget is shared fairly without cutting a tree that fits: each folder of a depth, and the depths below as one more claimant, is guaranteed half the even split the depth starts with, and a folder may read whatever the claimants after it do not need for that floor, up to the row cap. So one huge folder cannot starve its siblings wherever it sorts, and a small tree with one large folder is still read whole. The rows are shared fairly (_project_tree_allot): folder rows first, shallowest first, but never past half the cap while files remain, so root files like README.md stay listed; files share their rows round-robin by parent. Nothing is lost silently: a cut folder is named as truncated, never called empty.

The dashboard (website/src/pierre, website/src/pages/chat/FolderPanel.tsx) follows the capped contract. The truncation copy names an item limit (Not shown: limit of 10,000 items reached, in every website/src/i18n catalog). A truncated folder folded into a chain row by flattenEmptyDirectories keeps its badge. A truncated payload with no rows shows the limit, not "No files in this workspace yet". An unreadable-folder dismissal is not forgotten when the cut merely hid the folder. The project-root folder tab sends its search to /api/file-search while the tree is truncated, because the local filter cannot find what was never listed. The tree's own paths that contain the query are merged into those matches (server first, no duplicates), because the server search has its own scan budget and can miss a file the tree shows. A line above the matches says the search also covers items not listed, the tree stays mounted (hidden) behind them so its expanded folders survive clearing the query, and Refresh re-runs that search. Each queued folder is read only if it is still the folder its parent listed (_project_tree_scandir). A link is a symlink or a name-surrogate reparse point (_project_tree_is_link, platform_compat.lstat_is_name_surrogate), so a cloud-files placeholder folder is still walked. A listed folder the walk cannot read, including one whose identity lstat is refused or one swapped after its parent was listed (the root included, as .), is named in unreadableDirectories, never as truncated: truncated means the item limit, and a race on a small project never reached it. Each folder carries its native path so an extended-length Windows root joins correctly. Spec: docs/system-specs/modules/learn-cron-dashboard.md (Project tree).

Overlap: #13580 edits the de-duplication of the same response; this diff moves that loop into _project_tree_body unchanged, so it rebases onto it.

Backwards compatibility

Compatible: the payload keeps every field and shape. directories can now be shorter than the full skeleton on a project over the cap, and those folders are named through truncatedDirectories, which older clients already render.

Tests

  • test/test_project_tree.py: the combined cap on both branches; folder rows first but files keep half; spare rows never evict files that fit; a big tree returns at most the cap; one large folder does not starve its siblings, sorted first or last; a tree inside both limits is read whole beside one large folder, sorted first or last; folders larger than the budget sorted first still leave each small sibling its floor; a folder the budget never reaches is shown and never opened; each folder is read once; a listing that fails part-way is an unreadable row; a listed child whose lstat fails is unreadable and does not make the tree truncated; a folder swapped after its parent was listed is not read and is named unreadable, not truncated (descriptor and by-name branches, rename and symlink swaps); a root swapped for a link is unreadable (.), not truncated; only a name-surrogate reparse tag is a link; the look-ahead is drawn from the scan budget; a root cut by the budget is truncated, not hidden-only; a failed ls-files falls back to the bounded walk; git folder order matches the walk; redaction and serialization run off the event loop thread.
  • PierreWorkspaceTreeImpl.test.tsx / .realWidget.test.tsx: the chain-row badge (against the real @pierre/trees widget), the truncated empty state, dismissal kept and forgotten in truncated payloads.
  • FolderPanel.tree.test.tsx: a truncated tree sends the query to the server search, keeps the tree's own matches when the server search misses them (listed once when both name a file), says so above the matches, stays mounted behind them so the expansion survives clearing the query, and Refresh re-runs that search.

Manual verification

scripts/capture-files-tree-empty-folder.mjs against a fresh build: every frame passes its rendered-surface gates with the new copy. CAPTURE_SCENES=folder-truncated scripts/capture-path-chips.mjs against the dev server: the truncated folder tab hands its query to the search, lists the tree's own match first while the search runs, and hides (does not unmount) the tree behind the results. Local gate: the targeted backend tests pass apart from five that fail identically on a clean origin/main worktree on this host (test_file_grep PDF tests, a platform_compat peak-RSS test and a facade-loading test); the related frontend tests pass.

Screenshots / video

The Files rail with a truncated payload: the workspace notice and the state row under big/ name the item limit and fit the rail.

Files rail, folders expanded, truncation copy

The folder tab on a truncated tree, before a query, while the server search runs (the tree's own match is already listed), and with the server's matches merged in. The line above the matches says the search also covers items not listed:

Folder tab, truncated tree, before a query

Folder tab, truncated tree, query running, the tree's own match listed

Folder tab, truncated tree, merged results

A truncated payload with no rows shows the limit, not an empty workspace:

Files rail, truncated payload with no rows

A truncated folder folded into a chain row (pkg / core) keeps its badge:

Files rail, chain row with truncated badge

Collapsed: the badge on the closed folder

Files rail, big collapsed, badge

Related Issues

None filed; reported in review of the dashboard file handlers.

Pattern harvest

Rule candidate: review-prompt
Pattern: a handler on a polled endpoint whose work grows with user data (a walk, a per-row loop, a json_response of an uncapped list) on the event loop.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Closes #16647

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

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

Folder rows are now capped, so on a project over 10,000 items the Files rail can no longer reach some folders, and its filter is still local only.

Watch

  • The rail loses whole folders. The old contract said "Directory rows are returned separately and uncapped so manual navigation never loses a subtree". The patch counts folder rows against the cap (_PROJECT_TREE_MAX_ENTRIES now covers "files and directory rows together"), so on a large project some folders are simply not returned. The folder tab works around this by sending its query to /api/file-search. FileBrowserRail gets no such fallback, because server search in the rail is listed under "Not a goal". Its filter only searches rows the tree returned, and the user can no longer expand a parent to find a missing folder. The deleted copy "all folders remain available" was that promise. The PR treats the cut folders as a display change, but in the rail they become unreachable. A revert undoes it cleanly.
    Clears when: either the rail gets the same truncated-tree /api/file-search handoff as the folder tab, or the description and the spec (Project tree section) say that a folder past the cap cannot be reached from the rail, with a follow-up issue for lazy per-folder loading.

[DESIGN-REVIEWED] 4232b17

Description read

[DESCRIPTION-READ] 2ca15e29fcceb4a9e6a8c13445f56366838dd9f8f31ae1b3aaab7b087443b2d9

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 4232b171973a709622dca31a34bd938d6af87949 — 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: CONCERNS

Moving the work off the event loop and bounding the walk already end the stall. Capping folder rows at 10,000 removes navigation, and pinning folder identity adds hardening. The Goal needs neither.

Not justified as shipped

  • Item 3 — oversized: this deletes the pin "Directory rows are returned separately and uncapped so manual navigation never loses a subtree" and the copy "all folders remain available". The Goal is the gateway stall, and items 1–2 fix that alone: _PROJECT_TREE_SCAN_LIMIT bounds the walk and _project_tree_body runs in the worker thread.
    Subtraction: keep folder rows uncapped (the scan budget already bounds them) and spend the cap on files only in _project_tree_allot. The parts of item 4 that exist only because folders went missing go with it.
    Clears when: folder rows are uncapped again, or a human amends the Goal to accept losing navigation to folders past the cap.
  • Item 5 — oversized: "Each queued folder is read only if it is still the folder its parent listed" is hardening against a swap race. os.walk on base had no such pin, and no linked defect or failing test on base shows harm. _project_tree_fence already resolves each folder's real path before it fences names.
    Subtraction: delete _ProjectTreeFolderMoved, _project_tree_identity, the descriptor branch of _project_tree_scandir_entries and _PROJECT_TREE_SCANDIR_TAKES_FD. Read each queued folder with os.scandir(native) and keep the existing _project_tree_is_link check at listing time.
    Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 10 — rides along: the chain-row badge fix applies to any truncated folder, not only the new cap.

What this change ships

Inventory (10 items) — 6 justified

Intent: keep the gateway responsive while a large project's Files tree is open — FIX.

  1. Tree listing, redaction and JSON build no longer run on the event loop — justified
  2. Non-git walk reads at most 200,000 entries per poll, shared fairly between folders — justified
  3. Folders past the 10,000-item cap are no longer listed or navigable (both branches) — oversized
  4. Folder-tab search on a truncated tree uses server search, merges in the tree's own matches and shows a note — rides along
  5. A folder swapped between listing and read is shown unreadable, not walked — oversized
  6. Truncation copy says "items", not "files", in every locale — justified
  7. A truncated payload with no rows shows the limit, not "No files" — justified
  8. A dismissed unreadable folder stays dismissed when the cut hid it — justified
  9. Failed ls-files falls back to the bounded walk — justified
  10. A truncated folder folded into a chain row keeps its badge — rides along

[FIRST-PRINCIPLES-REVIEWED] 4232b17

Description read

[DESCRIPTION-READ] aee371c9b6155d0ca48d26fde641b4b160e6f2f75d258b2a5d6f2921b18a456f

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 4232b171973a709622dca31a34bd938d6af87949 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4232b17

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

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The empty truncated workspace says "some not shown" over an empty pane and offers no way forward, and the new search-scope line confused the blind reader.

Watch

  • Empty truncated tree (shot-05). rootTruncated reuses workspace_truncated ("…limit of 10,000 items reached, some not shown") as the whole empty state. The pane shows nothing, so "some" contradicts it. The reader said: "it says 'some not shown' but shows none, and gives me no button to fix it. I can't tell whether it's still loading or has failed." The "Filter files…" box above it filters only locally (the PR leaves the rail's filter local on purpose), so it cannot find anything either. This state is rare, but when it happens the user is stuck. Fix: give it its own string, for example "Too many items to list here. Search to find a file", and point to a search that reaches the server.
  • search_beyond_tree (shot-03). "Too many items to filter here, so the search also covers items not listed" opens with the cause and sounds like an apology. The reader called it "confusingly worded" and could only guess what it meant. The line is the only sign that this box now searches the server instead of filtering the tree, so a newcomer misses that switch. Fix: lead with what the search does, for example "Searching the whole workspace, including items not listed".
  • Search progress (shot-03 → shot-04). The PR describes shot-03 as "while the server search runs", but the screenshot shows no sign of a search in progress. The reader "can't tell whether screen 3 was incomplete or still searching". When three results arrive later, the list looks like it changed on its own. Fix: show the existing "Searching…" text beside "MATCHES" while the request is in flight.

Suggestions

  • The limit now has four wordings: workspace_truncated, row_truncated ("Not shown: limit of 10,000 items reached"), workspace_directory_truncated ("some items not shown") and the empty state. "Not shown" also means something else in search_beyond_tree. Use one phrase for all of them, for example "Not listed: 10,000-item limit", and keep "not listed" out of the search line.
  • row_truncated sits under an expanded big/ and offers nothing to do. The reader said "I see no way to load the rest". Add a "Search this folder" link next to it.

[UX-REVIEWED] 4232b17

Description read

[DESCRIPTION-READ] 184e2931a033afade915983332b6b024c258f4985accae78a63b8ee227126a82

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 4232b171973a709622dca31a34bd938d6af87949 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4232b17

Verdict parsed from the review's SHA-scoped output markers for commit 4232b171973a709622dca31a34bd938d6af87949.

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 2, 2026 00:51
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 2, 2026
@bolichen97
bolichen97 force-pushed the fix/project-tree-bounded-walk branch from 9e366a1 to deb05dc Compare October 2, 2026 19:16
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=0bf67dcbaf49 (queued folder read by name) in deb05dc

Each queued folder now carries the (st_dev, st_ino) its parent's listing recorded.
POSIX opens it O_DIRECTORY|O_NOFOLLOW, compares the fstat identity and lists that descriptor (_project_tree_scandir); Windows compares an lstat just before listing.
A folder that fails the comparison stays a row, is named in unreadableDirectories, and nothing behind it is listed.
Test: test_a_folder_swapped_after_its_parent_was_listed_is_not_read (rename and link cases, descriptor and by-name branches), plus test_a_root_swapped_for_a_link_is_unreadable_not_truncated.
self-added: yes
mechanism: identity-pinned descriptor listing per queued folder

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=f9ca2c4284fc (look-ahead outside the scan budget) in deb05dc

The one look-ahead entry per cut folder is now drawn from the same budget: allowance = min(share + 1, budget), so no more than scan_limit entries are ever read.
The docstring of _project_tree_walk and the Project tree spec say so.
Test: test_the_look_ahead_is_drawn_from_the_scan_budget.
self-added: yes
mechanism: look-ahead counted inside the read budget

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=f34d70cbe647 (same box, two behaviours) in deb05dc

On a truncated tree, a line above the matches (folder-search-beyond-tree) now reads: Too many items to filter here, so the search also covers items not listed. It is in all 13 catalogs.
The tree's own matching paths are merged into the server matches, so a file the tree shows is never missing from the results.
The line is absent on a whole tree, which still filters in place. FolderPanel.tree.test.tsx covers both cases.
Screenshots of before, during and results are in the PR body, along with the truncated empty state and the chain-row badge that the evidence gaps asked for.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=04e2e4daa7dd (Refresh refetch undeclared) in deb05dc

The PR description now declares it: Refresh re-runs the search that stands in for a truncated tree, the same as Refresh already does for a search in listing mode.
It refetches only the active (query, limit) key (searchKey, exact: true), never every cached page.
Test: FolderPanel.tree.test.tsx 'refreshes the search that stands in for a truncated tree', which fails without the refetch. The spec already states it.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

Pushed deb05dc214, one commit rebased onto origin/main 57d71bb54e. It addresses the review round on 9e366a1d0b:

  • GPT F1: a queued folder is listed only if it is still the folder its parent listed, pinned by (st_dev, st_ino). A folder that fails the check, including the root, is named in unreadableDirectories, not truncatedDirectories.
  • GPT F2: the look-ahead entry now comes out of the scan budget.
  • Budget split: every claimant at a depth gets a guaranteed floor, so a small tree beside one large folder is read whole wherever that folder sorts.
  • Links: a link is a symlink or a name-surrogate reparse point (platform_compat.lstat_is_name_surrogate), so cloud-files placeholder and dedup folders are still walked.
  • Unreadable children: a listed child whose identity lstat fails is unreadable, not truncated.
  • UX Watch and evidence gaps: the line above the truncated-tree matches is in place, the tree's own matching paths are merged in, and the tree stays mounted (hidden) behind the results. Screenshots of the takeover, the truncated empty state and the chain-row badge are in the body.
  • First-principles item 6: the Refresh refetch is now declared in the body.
  • Cross-Platform Portability: the / split in the git layout sort now uses posixpath.sep.
  • Backend Lint: the F811 is fixed on main by fix(autonudge): drop shadowing local probes import (F811 on main) #16032, which this push is rebased onto.
  • Simplify pass: comment reflow, plus a dedupe key computed once. No behaviour change.
  • Capture script: capture-path-chips.mjs now checks only for visible tree rows, because the tree stays mounted behind the results.

Rebutted (no code change):

  • Design headline (reversal of the uncapped folder skeleton): deliberate and declared in the spec and the body. Uncapped folder rows made the redaction and serialization on every poll grow with the tree, which is the stall being fixed. Every cut folder is named in truncatedDirectories, and the folder tab hands its search to the server when the tree is truncated.
  • First-principles headline (Files-rail local filter past the cap): listed under Not a goal. Before this PR that filter could not find files past the cap either.

Local gate: static gates pass and the related frontend tests pass. One timing test, MarkdownRenderer 'ampersand flood', failed under a load average of about 180 and passed on rerun. The first backend batch ran: 40,140 passed and 6 failed. All 6 fail the same way on a fresh origin/main worktree on this host: 3 aws_control test_producer CLI tests and 3 test_file_grep PDF tests. I stopped the second backend batch because the host was saturated, after running test/test_project_tree.py directly (56 passed); CI runs the rest.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 2, 2026
@bolichen97
bolichen97 force-pushed the fix/project-tree-bounded-walk branch from deb05dc to fb0a3cc Compare October 4, 2026 07:10
@bolichen97

bolichen97 commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: capability seams replace runtime skips in the swap tests

  • span=97a008dc5c95 New security tests add runtime skips

fixed in fb0a3cc: all three pytest.skip calls in test/test_project_tree.py are gone.
The symlink swap renames the outside folder into place and makes the name answer as a link through seams (ELOOP from the O_NOFOLLOW open, a link lstat by name), so it needs no symlink privilege.
The root-swap test forces the descriptor branch and raises ELOOP from a seam, so it runs on every host.
The descriptor parametrization is collected only where scandir takes a descriptor; the by-name branch runs everywhere.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 4, 2026
@bolichen97
bolichen97 force-pushed the fix/project-tree-bounded-walk branch from fb0a3cc to 056bc3f Compare October 4, 2026 08:33
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Oct 4, 2026
chenmingwei23
chenmingwei23 previously approved these changes Oct 4, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 4, 2026
The non-git fallback of GET /api/project/tree walked the whole project
twice with no bound on directories, then redacted every row and
serialized the body on the event loop. The dashboard refetches the tree
every 10 s while it is open, so a large non-git project, a repository
whose ls-files overflows its cap or timeout, or a host with no sandbox
backend stalled the gateway on every poll.

The walk is now one breadth-first scandir pass under one read budget,
look-ahead included. Each folder of a depth, and the depths below as
one more claimant, is guaranteed half the even split the depth starts
with, and a folder may read what the claimants after it do not need
for that floor, up to the row cap: one large folder cannot starve its
siblings, and a small tree beside one large folder is read whole.
Each queued folder is read only if it is still the folder its parent
listed: POSIX opens it O_DIRECTORY|O_NOFOLLOW and compares the fstat
identity before listing the descriptor, Windows compares an lstat just
before listing. A link is a symlink or a name-surrogate reparse point,
so a cloud-files placeholder folder is still walked. Both branches spend
one combined row cap on folder rows and files together: folders first,
shallowest first, files keeping at least half the cap and sharing it
round-robin by parent. Every shown folder whose listing was cut is named
in truncatedDirectories; a listed folder that cannot be read, its
identity lstat included, or that is no longer the folder its parent
listed, is named in unreadableDirectories. Redaction and JSON
serialization run in the same worker thread as the listing.

The dashboard follows the capped contract: the truncation copy names an
item limit, a folder folded into a chain row keeps its badge, a
truncated payload with no rows shows the limit instead of an empty
workspace, unreadable-folder dismissals survive a cut payload, and the
folder tab sends its search to the server when the tree is truncated,
merges in the tree's own matching paths, says the search also covers
items not listed, and keeps the tree mounted behind the results.
@bolichen97
bolichen97 force-pushed the fix/project-tree-bounded-walk branch from 273b12d to 4232b17 Compare October 4, 2026 18:12
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 4, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: folder rows share the 10,000-row cap with files

  • span=a6e2d7c6c22a The rail loses whole folders

accepted-and-deferred: rail reachability past the cap is tracked in #16819 (rail server-search handoff, lazy per-folder loading).
The cap stays: an uncapped folder skeleton keeps the walk, redaction and render linear in tree size, which is the stall this PR removes.
A folder past the cap is never silent: its parent is named in truncatedDirectories and shows the limit row and badge.
The spec's Project tree section already says folder rows are capped with files and names lazy loading as the long-term alternative.
#16819 carries the deferred-finding label, an owner and a Due date.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: folder rows share the 10,000-row cap with files

  • span=41c46604b9e8 Item 3 — folder rows capped

rebutted: the scan budget bounds what is read, not what is sent; an uncapped folder skeleton is still up to 200,000 rows redacted, serialized and rendered every 10 s.
The worker holds the GIL for that work, so the loop still starves on a large tree; the row cap is what bounds the body and the render.
Same class as the earlier ruling on span=f129a91002ca; folders past the cap are named in truncatedDirectories, and their reach from the rail is tracked in #16819.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: identity-pinned descriptor listing per queued folder

  • span=05e452c28291 Item 5 — identity pin is oversized

rebutted: not a defect and not extra scope; the breadth-first walk itself opens the swap window the pin closes.
os.walk reads a child right after its parent; this walk queues a whole level, up to the 200,000-entry budget, before reading it.
_project_tree_fence resolves names for the sensitive fence only; it does not stop a folder swapped for a link from listing entries outside the project.
Same class as span=460f6ff4607a and span=de1e0add83e9; removing the pin reopens that path escape.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: badge lookup across a folded chain row's segments

  • span=3c4c044bb171 Item 10 — chain-row badge rides along

rebutted: this PR makes truncation the normal state of a large tree, because folder rows now share the cap.
A folder whose files lost their rows and that holds one listed subfolder folds into a chain row; without the lookup its badge vanishes and the cut is silent.
The fix is the lookup over flattenedSegments in the badge path only, which the PR's 'nothing is lost silently' claim needs.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=edc81f6e1f6b Empty truncated tree

accepted-and-deferred: copy and status polish on the capped-tree surfaces, outside this PR's goal (the gateway stall); tracked in #16743.
#16743 carries the deferred-finding label, an owner and a Due date, with this item as a task.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=7b99d062589d search_beyond_tree wording

accepted-and-deferred: copy and status polish on the capped-tree surfaces, outside this PR's goal (the gateway stall); tracked in #16743.
#16743 carries the deferred-finding label, an owner and a Due date, with this item as a task.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=6856b68e5493 Search progress not shown

accepted-and-deferred: copy and status polish on the capped-tree surfaces, outside this PR's goal (the gateway stall); tracked in #16743.
#16743 carries the deferred-finding label, an owner and a Due date, with this item as a task.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=4b41255d06fe One limit, four wordings

accepted-and-deferred: copy and status polish on the capped-tree surfaces, outside this PR's goal (the gateway stall); tracked in #16743.
#16743 carries the deferred-finding label, an owner and a Due date, with this item as a task.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=449fcabe9243 Search this folder under row_truncated

accepted-and-deferred: a new action on the capped-folder row, outside this PR's goal (the gateway stall); tracked as task 3 of #16819.
#16819 carries the deferred-finding label, an owner and a Due date.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 4, 2026

@buluoray buluoray 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.

Reviewed at head 4232b17197. I checked the bound, the work moved off the event loop, the sensitive-path fence and symlink loops. None of them has a defect that should block this PR.

The bound limits the work

  • Every folder read takes at most allowance = min(share + 1, budget) entries, and budget -= pulled runs on both the success path and the error path (project_tree.py _project_tree_walk). I wrapped os.scandir to count the entries actually pulled from a 125k-entry tree. With limit 200,000 it pulled 125,040, and the tree was read in full (that is under the budget). With limit 20,000 it pulled 19,822; with limit 1,000 it pulled 999. Rows returned stayed at or under the row cap each time, and truncated=True named 41 folders. A non-dot root took 0.08 s for the full 125k.
  • Only rows inside the cap are queued, so the number of folders the walk opens is bounded by the cap. _project_tree_allot caps directory rows and files together on both branches. truncated is bool(truncatedDirectories).
  • Fail-closed: when the share is at least the budget, the look-ahead can mark a folder that was actually complete as truncated. That over-reports truncation and never under-reports it.

Work moved off the loop

  • _run and _project_tree_body now run in one asyncio.to_thread call. _sel(), the allow-list match and DashboardState access stay on the loop. The thread touches only the filesystem, _run_git_bounded and the redactors. redact is redact_via_context → current_context(), and to_thread copies the contextvars. I found no loop-only state used from the thread.

Sensitive-path filtering

  • _project_tree_fence is byte-identical to main's _project_tree_entries.fenced. It is still applied to every file entry and every directory entry before it is kept, including the per-folder realpath shortcut. The handler still runs is_sensitive_path(base) on the resolved root before listing anything.

Symlink loops

  • Links are never followed. _project_tree_identity uses lstat, and a link becomes a linkedDirectories row; it is never queued. Each queued folder is re-opened with O_DIRECTORY|O_NOFOLLOW and checked against the (st_dev, st_ino) its parent recorded.
  • I built a tree containing a/b/up -> .., self -> root and a self-referential dangling link x. The walk finished in 2 ms: self and a/b/up came back as linked rows, and x came back as a file. There was no recursion.

Mutation probes (test/test_project_tree.py; each mutation was reverted, and the tree is clean at the end)

Guard removed Test that fails
look-ahead taken outside the budget test_a_folder_the_scan_budget_never_reaches_is_named_and_never_read
if budget <= 0 stop same test
per-folder share uncapped test_one_large_folder_does_not_starve_its_siblings_of_the_scan[data,zz_data], test_a_large_folder_sorted_first_still_leaves_each_sibling_its_floor
descriptor identity compare test_a_folder_swapped_after_its_parent_was_listed_is_not_read[descriptor-rename]
by-name identity/link check ...[by-name-rename], ...[by-name-symlink], ...[descriptor-symlink]
link → linked row test_non_repo_walk_lists_a_junction_as_a_link_and_never_walks_it and 2 others
fence disabled 4 fence/sensitive tests
body built on the loop test_redaction_and_serialization_run_off_the_event_loop[git,walk]

Without any mutation, the related backend files passed 176/176 (test_project_tree.py, test_dashboard_files_composition_contract.py, test_pathres_loop_starvation.py), and the 4 touched frontend test files passed 170/170.

Earlier review: chenmingwei23's review on 273b12d3bb was dismissed. It has an empty body and no inline comments, so there is no point from it to re-check. The bot findings bolichen97 marked fixed were F1 (identity pin), F2 (look-ahead inside the budget) and the runtime-skip finding. I checked them at this head: the code is present, and the first two are covered by the probes above.

CI at 4232b17197: 95 success, 8 skipped, 7 cancelled. The cancelled runs are earlier runs that newer runs replaced. gh pr checks shows no failing check.

Non-blocking follow-ups

  1. Cost under a dot-named root. The PR body and the _PROJECT_TREE_SCAN_LIMIT comment say the walk costs "about half a microsecond an entry" and takes a fraction of a second. That holds only for a root that is not under a dot path. Under a dot root (for example a project under ~/.kiro/... or .worktrees), under_dot holds for every folder, so every entry pays a Python-level os.path.realpath. I measured about 37 µs per entry, which is about 7 s for the full 200k budget on every 10 s poll. That time is spent in a worker thread, and it holds the GIL much of that time. This is not a regression: main paid the same per-entry cost with no bound at all. Consider lowering the budget for dot roots, or correcting the comment.
  2. The early stop on rows past the cap is untested. if len(rows) >= cap: incomplete.add(directory); break can be removed and every test still passes, because _project_tree_allot caps the output anyway. The guard only saves reads; a test that counts pulled entries would pin it.
  3. The test named test_the_look_ahead_is_drawn_from_the_scan_budget does not fail when the look-ahead is moved outside the budget. A different test catches that mutation, so the test name over-claims.

@bolichen97
bolichen97 merged commit a0a90fd into main Oct 4, 2026
103 of 110 checks passed
@bolichen97
bolichen97 deleted the fix/project-tree-bounded-walk branch October 4, 2026 21:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 4, 2026
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.

Files tab: project tree walk on a large non-git project stalls the gateway every 10 s

3 participants