fix(useFiles): stop warning on expected evicted-media reads

[Pasumarthi Rutwik (rutwik2001)]

Summary

• readFile() logged a warn for every encrypted read that returned no local bytes, conflating two distinct cases: the file simply isn't on this device (evicted off-device, or synced as metadata but never pulled) vs. a genuine decrypt/IO failure.
• Case 1 is an expected state once media eviction + backup restore is in play, so it spammed [useFiles] Encrypted read failed ... trying legacy storage on each render of restorable media.
• Split the outcomes: a null result (clean not-found) now logs at debug and falls through quietly; only a thrown error (decrypt/IO) keeps the warn.
• No behavior change — callers still resolve missing bytes via backup-first restore (EvictedMediaTile / downloadEvictedMedia).

Integration

None required. Console noise drops automatically. Apps that route the SDK debug level to a no-op logger will see the evicted-read line disappear entirely; real decrypt/IO failures still surface at warn.

Breaking Changes

None.

Test plan

• pnpm typecheck — clean
• pnpm exec eslint src/react/useFiles.ts — clean
• pnpm vitest run storage/opfs suites — 48 passed
• Open a conversation with evicted media: confirm no warn spam, EvictedMediaTile/tap-to-download still restores

---

Note

Low Risk
Logging-only refinement in encrypted read handling; file resolution and error throwing after legacy fallback are unchanged.

Overview
readFile in useFiles now treats a null from readEncryptedFile (no local encrypted bytes—evicted or metadata-only) as an expected path: it logs at debug and continues to legacy OPFS instead of throwing and hitting the warn path labeled “encrypted read failed.”

Real decrypt/IO failures still warn and fall back the same way. Restore/backup behavior is unchanged—callers still resolve missing bytes via evicted-media restore after legacy lookup fails.

^{Reviewed by Cursor Bugbot for commit 7cab74d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

Splits the log-level handling inside readFile's encrypted path in useFiles.ts to distinguish a clean "no local bytes" result (null) from a hard decrypt/IO failure (thrown error). The null branch now logs at debug and falls through to legacy OPFS storage quietly; the catch branch keeps its warn.

• The behavior seen by callers is unchanged: both the null path and the error path still fall through to the legacy unencrypted OPFS read, which throws File could not be found if also absent there.
• The original warn message "Encrypted read failed" was misleading for the eviction case — the new debug message "No local encrypted bytes … (likely evicted)" is more precise.

Confidence Score: 5/5

Safe to merge — the change only adjusts log verbosity and does not alter how callers receive file data.

The encrypted-read path's null/throw split is correctly handled: the null branch falls through to legacy storage the same way the old throw→catch path did, so no user-visible behavior changes. The warn message for real failures is preserved, and the new debug message is accurate. The single-file diff is minimal and easy to reason about end-to-end.

No files require special attention.

Important Files Changed

Filename	Overview
src/react/useFiles.ts	Refactors null vs exception handling in the encrypted-read path to use debug vs warn respectively; no functional behavior change for callers.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[readFile called] --> B{hasEncryptionKey?}
    B -- No --> F
    B -- Yes --> C[readEncryptedFile]
    C -- result is non-null --> D[return File]
    C -- result === null\nnot found / evicted --> E[log.debug\n'No local encrypted bytes'\nfall through]
    C -- throws\ndecrypt / IO error --> G[log.warn\n'Encrypted read failed'\nfall through]
    E --> F[Try legacy OPFS]
    G --> F
    F -- success --> H[return File from OPFS]
    F -- not found --> I[throw 'File could not be found']

Loading

_{Reviews (1): Last reviewed commit: "fix(useFiles): stop warning on expected ..." | Re-trigger Greptile}

[github-actions]

Dependency graph

Changed files are highlighted in green.

flowchart LR

subgraph 0["src"]
subgraph 1["react"]
2["index.ts"]
3["useFiles.ts"]
end
end
2-->3
2-->3

style 3 fill:lime,color:black

Loading

[github-actions]

Import Impact

App	Symbols used	Impacted
starter-next	81 across 3 entry points	⚠️ Yes
starter-mini	4 across 3 entry points	✅ No
starter-telegram	3 across 2 entry points	✅ No
starter-agent	17 across 2 entry points	✅ No
dashboard	26 across 3 entry points	✅ No
text	48 across 2 entry points	✅ No
cli	0 across 1 entry points	✅ No
ai-memoryless-client	310 across 6 entry points	⚠️ Yes

Impact details

starter-next

• @anuma/sdk/react: useFiles

ai-memoryless-client

• @anuma/sdk/react: UseFilesOptions, UseFilesResult, useFiles

Changed SDK files (1)

• src/react/useFiles.ts

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	64.85%	7575 / 11680
🔵	Statements	63.53%	8185 / 12883
🔵	Functions	61.27%	1272 / 2076
🔵	Branches	52.24%	4881 / 9342

File Coverage

No changed files found.

Generated in workflow #1138 for commit 7cab74d by the Vitest Coverage Report Action

[github-actions]

Integration Check ✅ (baseline matches)

Failures also occur on main — not caused by this PR.

	main	PR
starter-next build	❌	❌
starter-next e2e	❌	❌
starter-mini build	❌	❌
starter-telegram build	✅	✅
starter-agent build	❌	❌
dashboard build	✅	✅
text build	✅	✅
cli build	✅	✅
ai-memoryless-client build	✅	✅