[Abhishek-B-R]

Summary

hflow doctor now reports a file it cannot open (permission denied) in place as [error] unreadable: ... and keeps going, instead of exiting with a traceback.

Why

_command_doctor caught ValueError and FileNotFoundError per file. Opening a file the user has no read permission for raises PermissionError, which is an OSError but not a FileNotFoundError, so it escaped the loop. The run stopped and every report after that file was lost, which is the thing docs/FORMAT.md says doctor avoids ("An unreadable or unparseable path is reported in place ... and the run continues with the remaining files").

Repro on main:

$ cp episode.mcap locked.mcap && chmod 000 locked.mcap
$ uv run hflow doctor locked.mcap episode.mcap
Traceback (most recent call last):
  ...
PermissionError: [Errno 13] Permission denied: 'locked.mcap'

After: locked.mcap gets [error] unreadable: [Errno 13] Permission denied: ... and NOT CONFORMING, episode.mcap still gets its report, and the exit code is 1 (or 2 if nothing could be diagnosed), per the existing exit code rules.

The fix is to catch OSError in the CLI loop. diagnose() itself is unchanged, so library callers still get the exception. CLI only, no stored bytes change, so no behavior version bump.

Validation

• uv run pytest -q tests/test_doctor.py -k permission on main: fails with the PermissionError above. With the fix: passes.
• uv run pytest -q -n 4: 2571 passed, 49 skipped.
• uv run ruff check --fix, uv run ruff format, uv run ty check: clean.

The new test is skipped when running as root, since root can open a mode 000 file.

Checklist

• I added or updated outcome-focused tests for changed business logic.
• I updated documentation for changed behavior, flags, formats, or requirements. (No change needed: docs/FORMAT.md already describes this behavior.)
• I ran uv run ruff check --fix, uv run ruff format, and uv run ty check.
• I ran the relevant pytest suite.
• I did not add recordings, generated media, credentials, private URLs, or runtime artifacts.
• I preserved stored-data compatibility or documented an explicit version change.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge.

Summary

hflow doctor now reports files it cannot open instead of stopping the batch.

• The doctor command reports unreadable files and continues through the list.

_{Reviews (1) · Last reviewed commit: "fix(doctor): report files without read p..." · Reviewed by Greptile}

[kstonekuan]

Thanks for the fix. Ruff, ty, the permission regression test, and both Python CI jobs pass. Merging.