Skip to content

fix(files): route tree-expansion memory through safeStorage - #10678

Closed
leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/tree-expansion-safe-storage
Closed

leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/tree-expansion-safe-storage

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

The Files tree mirrors its expansion state to localStorage so that a page
reload does not start fully collapsed. On an origin whose quota is full, that
mirror silently stops working and never recovers.

website/src/pierre/treeExpansionMemory.ts wrote it raw:

try {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(store))
} catch {
  // Private mode / quota exceeded: the session map above still covers the
  // remount case, only reload persistence is lost.
}

That catch treats a full quota as unrecoverable. It is not.
website/src/utils/safeStorage.ts — used by 91 files — exists precisely for
this write: on a QuotaExceededError it drops one tier of disposable cache
and retries, escalating a tier at a time. Its own header names the condition:

the dashboard accumulates a lot of per-origin localStorage — most notably the
per-session virtualizer height caches (vc_heights_<sid>, up to 2000 entries
each), which pile up across every chat session ever opened and are never
reclaimed. Over time the ~5-10 MB origin quota fills up.

So the bare catch fired in ordinary use, and threw the write away while
megabytes of re-derivable cache sat next to it, reclaimable.

A second dead end, on the read side. readStore() returned null when
storage was unusable, so a doomed write could be skipped — but a value that
merely failed JSON.parse took the same branch:

} catch {
  return null          // ← unreadable storage AND a corrupt value
}

rememberExpandedPaths then returned early without writing, so the corrupt
string stayed put and blocked every later write. One bad value disabled the
mirror permanently, for the life of that browser profile.

This is the residual the First-Principles review of #10366 named when the module
landed: "treeExpansionMemory.ts re-hand-rolls guarded localStorage access that
safeStorage.ts centralizes — and loses its quota reclaim+retry, so on a full
quota the mirror silently dies."
Its stated clearing condition was that the
module read and write through safeGetItem/safeSetItem.

Why it matters

Neither failure is visible at the moment it happens. The module-scope session map
keeps covering the remount case, so the tree behaves correctly for the whole
session; the loss only shows up on the next reload, as a fully collapsed tree and
every file open costing a re-expand from the root. That is the exact cost #10366
set out to remove.

The quota half is not hypothetical: it fires for users with many chat sessions —
the growth safeStorage was written to absorb — and it is self-inflicted,
because the space needed was already there and reclaimable.

The corrupt-value half is worse in one respect: nothing clears it. There is no
expiry, no version check, and no path that rewrites the key, so the feature stays
dead until the user clears site data.

What changed (motivation → approach → change)

Symptom → the expansion mirror stops persisting across reloads and does not
recover.

Root cause → a hand-rolled storage guard that discards the one error class
the shared helper knows how to recover from, plus a read that conflates "storage
is broken" with "this stored value is garbage".

Change → route both ends through the shared helper:

  • rememberExpandedPaths writes with safeSetItem, which reclaims and retries.
  • readStore reads with safeGetItem and returns {} for anything unusable.

Removing the null channel is not a separate decision bolted on — it is what the
first change makes possible. That channel existed only to avoid a write that
could not succeed, and safeSetItem already makes such a write harmless
(it returns false and warns in dev). With its one purpose gone, keeping it would
only preserve the corrupt-value dead end, so it goes, and the next expansion
overwrites the bad value.

Two things deliberately not changed:

  1. The graceful-degradation contract. Storage that is unusable rather than
    full — private mode, storage disabled — still degrades to session-only memory
    and still never throws. safeSetItem only reclaims for genuine quota errors;
    a SecurityError returns false untouched. The third test pins this, because
    it is the behaviour most at risk from a careless "just use safeSetItem" edit.
  2. The other residual from the same review. fix: persist Files tab expansion and filter across remounts (#9653) #10366's review also called
    MAX_SESSION_QUERY_DIRS in FileBrowserRail.tsx oversized (an LRU cap on a
    session-only Map of typed filter strings). That is a different file, a
    different mechanism, and a sizing opinion rather than a defect — nothing is
    lost or stuck. It does not belong in a fix PR.

The module docstring said "private mode or a full quota degrades to session-only
memory". That is now false for the quota half, so it is corrected in the same
commit rather than left describing behaviour the diff removed.

Tests

New website/src/pierre/treeExpansionMemory.test.ts, 3 cases:

  • reclaims disposable cache and retries when the origin quota is full —
    seeds a vc_heights_* key, then makes setItem throw for the mirror key for
    as long as that key exists. Asserts the mirror value actually lands, and that
    only the disposable tier was sacrificed.
  • recovers from a corrupt stored value instead of being stuck on it —
    plants '{not json', then asserts the next expansion overwrites it and that a
    fresh session recalls the value.
  • still degrades to session-only memory when storage is unusable — the
    no-regression control. Makes both getItem and setItem throw a
    SecurityError; asserts no throw and that recall still answers from the
    session map.

One thing worth flagging about the first test, because it nearly shipped wrong:
my initial fixture threw a plain Error subclass named QuotaExceededError.
safeStorage.isQuotaExceededError starts with if (!(err instanceof DOMException)) return false, so that object never reaches the reclaim path at all — the test
failed against the correct fix and would have passed against a fix that did no
reclaiming. It now throws a real DOMException, and the reason is a comment in
the test so the next person does not re-introduce it.

Run:

cd website && npx vitest run src/pierre src/test/PierreWorkspaceTreeImpl.test.tsx src/test/safeStorage.test.ts
  • Red-before on current main (new tests, production file reverted), with the
    corrected fixture:
    • AssertionError: expected null not to be null — the write was discarded
    • SyntaxError: Expected property name or '}' in JSON at position 1 — the
      corrupt value was still in storage, unchanged
    • the degradation control passed on main, as it must
  • Green-after: 3 passed (3) / 85 passed (85), including the existing
    PierreWorkspaceTreeImpl and safeStorage suites.
  • npx tsc --noEmit -p tsconfig.json and npx eslint on both files: clean.

Manual verification

N/A — unit coverage sufficient: both failures are storage-layer error handling
with no rendered surface, and the tests drive the real exported functions against
a real localStorage with the real safeStorage helper, stubbing only the
browser error the quota condition raises.

Related Issues

Follow-up to #10366 (which fixed #9653), closing the storage-layer residual its
First-Principles review recorded. No issue filed for it — the review is the
provenance, quoted above.

Contention was checked against all 300 open PRs on the exact path
website/src/pierre/treeExpansionMemory.ts: zero, verified with a
known-positive control path in the same scan so an empty result could not be a
silently broken query. The two open PRs touching safeStorage.ts (#9724, #8403)
each only add a safeRemoveItem export; neither changes safeGetItem or
safeSetItem, which is all this PR consumes.

Pattern harvest

Rule candidate: lint

Pattern: a bare try { localStorage.setItem(...) } catch {} outside
utils/safeStorage.ts — a guard that looks defensive while discarding the one
error the shared helper can recover from.

What generalizes is narrower and more useful than "use the helper". The
hand-rolled version was not careless: it had a comment, it degraded to a sensible
fallback, and it was written by someone who had clearly thought about private
mode. It was wrong only because quota and unusable are different conditions
with different correct responses, and one catch cannot tell them apart. A
lint rule keyed on a raw setItem in a module that is not safeStorage would
have caught it; a reviewer reading the comment would not, because the comment is
accurate about the case it names.

The read side generalizes the same way: a sentinel that folds "the medium is
broken" together with "this particular value is garbage" will eventually make a
recoverable state permanent, because the caller can only take one branch for both.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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) — the module docstring's now-false quota sentence is corrected in the same commit; no system spec documents this module
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

The Files tree mirrors its expansion to localStorage so a reload does
not start fully collapsed. That mirror wrote with a raw setItem inside
a bare catch, which discards a QuotaExceededError outright.

`utils/safeStorage` exists for exactly this write: on a quota error it
drops one tier of disposable cache -- the per-session virtualizer height
caches, which accumulate across every chat ever opened and are the
documented reason the origin fills up -- and retries. Bypassing it meant
the mirror quietly stopped persisting while megabytes of re-derivable
cache sat next to it, and nothing recovered it.

The read had a second dead end. `readStore` returned null when
localStorage was unusable so a doomed write could be skipped, but a
value that merely failed JSON.parse took the same branch. One corrupt
string therefore blocked every later write and left the bad value in
place, so expansion never persisted again for the life of the profile.
With safeSetItem making a doomed write harmless, that channel has no
remaining purpose: the read now falls back to an empty record, and the
next expansion overwrites the corrupt value.

Storage that is unusable rather than full still degrades to session-only
memory and never throws, which the third test pins.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and dwu96 September 14, 2026 03:12
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 14, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — ✅ PASS

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

The diff touches only treeExpansionMemory.ts (storage error-handling) plus a new test file — no JSX, no user-facing strings, no rendered control added or changed. Reconciliation table is empty: there is nothing a screenshot could show, so no evidence gaps apply and the missing attachments are expected.

UX-Verdict: PASS

Pure storage-layer fix with no rendered surface; the only user-visible effect is the file tree correctly staying expanded across reloads.

[UX-REVIEWED] 58cb985

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

Design-Verdict: PASS

Right fix at the right layer: the shared quota-reclaiming helper replaces the hand-rolled guard that caused both failure modes, with the degradation contract pinned.

The removal of the null "storage broken" channel is sound, not scope creep: its only purpose was avoiding a write safeSetItem now makes harmless, and keeping it would preserve the corrupt-value dead end. Recall semantics are unchanged (corrupt value still yields []), the storage key and record shape are untouched, and the SecurityError regression test covers the one behavior most at risk from this edit. No design-level concerns.

[DESIGN-REVIEWED] 58cb985

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 58cb985

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 58cb985f7eb8c168c379a782e9b1201a99e132f7 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.

Both defects are verifiable directly in the base code (treeExpansionMemory.ts:63-65 catch→null, line 79 early return; the bare-catch write at line 86-91), the shared helper exists and is the repo's recorded mechanism (~90 files import safeStorage), the module's only production consumer is PierreWorkspaceTreeImpl.tsx, and the test-reset export the new test imports already exists in base. The ~25 remaining raw localStorage.setItem files are the incremental migration safeStorage.ts's own header records as the plan, so not a point-patch finding.

First-Principles-Verdict: PASS

Only unrunnable claim is the red-before/green-after test run — CI's vitest job settles it; both defects themselves are verifiable by reading base.

What this change ships

Inventory (5 items) — 5 justified

Intent: keep the file tree's expansion state surviving a page reload when localStorage is full or holds a corrupt value — a FIX (both defects readable in base code; a prior review residual, not a new capability).

  1. A full origin quota now reclaims disposable cache and the expansion write lands, instead of being silently dropped — justified
  2. A corrupt stored value no longer disables reload persistence forever; the next expansion overwrites it — justified
  3. The "storage broken, skip the write" read channel is removed (readStore returns {}) — justified
  4. Module docstring corrected to match the new quota behaviour, same commit — justified
  5. New 3-case test file, including a pin on the surviving private-mode degradation contract — justified

The rewritten docstring pin ("full quota degrades to session-only memory") is retired with evidence: the same catch demonstrably conflated corrupt values with broken storage in base. The declined sibling residual (MAX_SESSION_QUERY_DIRS) is correctly out of scope.

[FIRST-PRINCIPLES-REVIEWED] 58cb985

@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

I've independently reconstructed the post-diff behavior and verified it against the safeStorage helper and the base file.

The candidate list contains no candidates. My own falsification of the change confirms it is a sound defensive refactor:

  • readStore returning {} (not null) on corrupt JSON correctly lets the next write overwrite a poisoned value; safeGetItem returning null on SecurityError still routes to {}, so no crash.
  • The safeSetItem switch preserves the never-throw contract (SecurityError → isQuotaExceededError false → returns false; session map covers remount) and its reclaim tiers (vc_heights_, mc-paste-store-v1, kirocrew:touched-files:) never match the tree's own mc-files-tree-expanded key, so no self-eviction.
  • Dropping ?. in recallExpandedPaths is safe because readStore can no longer return null.

No behavioral defect, security boundary, or blocking AUTOSDE rule is groundable on the changed lines. Nothing survives to Step 2.

No findings.

[OPUS-REVIEWED] 58cb985

@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 Sep 14, 2026
@NicholasRBowers NicholasRBowers added the needs-pr-triage PR scanner: awaiting automated triage label Sep 21, 2026
@chenmingwei23 chenmingwei23 added drive-to-green PR claimed by drive-to-green pipeline and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: chenmingwei23]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author.

Assessment: Frontend-only diff (treeExpansionMemory / safeStorage). Backend Tests + Coverage Gate reds are inherited from main. Fix: rebase onto current main; verify the treeExpansionMemory tests pass.

If you'd prefer I don't touch this PR, add the pr-no-autofix label.

@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this fix, @leonlaiyc! 🙏

This PR had drifted into conflict with main (the treeExpansionMemory module was refactored into a shared createProjectPathMemory factory after you opened it), so to get it landed I ported your change onto current main and opened an in-repo replacement: #16596. It is fully green (all required checks and all reviewer lanes pass).

Your authorship is kept in git: the commit is still authored by you (Leon <leon.lai.yc@gmail.com>) with a Co-authored-by: @leonlaiyc trailer and the original Co-Authored-By: Claude Opus 5 preserved, and you remain in the README contributors list. The replacement PR links back here and credits you in its description.

Closing this one in favour of #16596 (tracked by issue #16595). Thanks again for the contribution!

@iamwhatever iamwhatever closed this Oct 3, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 3, 2026
@mbriones98 mbriones98 removed the drive-to-green PR claimed by drive-to-green pipeline label Oct 13, 2026
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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sidebar Files tab: opening a file collapses the entire tree and clears the filter

5 participants