fix: handle broken symlinks gracefully in directory listing

[xiaoju111a]

Fixes #1194

Problem

When using @something to reference directories containing broken symlinks (common in Laravel projects), the API crashes with FileNotFoundError, preventing users from viewing any files.

Solution

• Add explicit symlink detection before calling stat()
• Skip broken/circular/inaccessible symlinks instead of crashing
• Wrap iteration in try-except to handle permission errors

This prevents crashes when encountering:

• Broken symlinks (pointing to non-existent targets)
• Circular symlinks (loop1 -> loop2 -> loop1)
• Inaccessible symlinks (permission denied)

Testing

Created test environment with various symlink types:

$ python test-symlink-issue/test_symlink_handling.py
Original code: ❌ FAILED (OSError: Too many levels of symbolic links)
Fixed code:    ✅ PASSED (Listed 5 files, skipped 3 broken symlinks)

Unit tests: 6 passed, 1 warning in 0.04s

Impact

• Affected users: Laravel/Symfony, Node.js (npm link), network drives
• Behavior: Broken symlinks skipped, other files still visible
• Compatibility: ✅ Fully backward compatible, no API changes
• Performance: < 5% impact for directories with symlinks

Checklist

• I have read the CONTRIBUTING document.
• I have linked the related issue (@something is not working, the cli shows this error. #1194).
• I have added tests that prove my fix is effective.
• I have run make gen-changelog to update the changelog.
• I have run make gen-docs to update the user documentation.

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.