A mistyped path produces a traceback, or a message naming the wrong directory

[royalpinto007]

Problem

The CLI has no error handling for the paths it is given. Every failure surfaces as a Python traceback.

• agentrace --file /does/not/exist list reaches parse_session(Path(args.file)), which calls path.open() in _records and raises FileNotFoundError. The user gets a stack trace through main.
• agentrace --file /some/directory list raises IsADirectoryError the same way.
• agentrace --dir /does/not/exist list behaves differently again: find_sessions returns [] because it checks root.exists(), so the user gets "No subagent runs found. Looked in ~/.claude/projects unless --dir was given", which names the wrong directory and gives no hint that the path they passed does not exist.
• agentrace --dir <path-to-a-file> hits root.glob on a non-directory.

So a mistyped path produces a traceback in one case and a misleading message in another.

Why it matters

This is a tool people point at a directory on their own machine, and getting the path slightly wrong is the single most likely thing to go wrong on first use. A traceback reads as "this tool is broken" rather than "you typed the path wrong", which is a bad first five minutes for a project whose README pitches a copy-paste quickstart.

Suggested approach

1. Validate paths at the top of _load, before any parsing, and raise a single AgentraceError with a clear message: the path does not exist, or it is a directory when a file was expected, or the other way round.
2. Catch that one exception type in main, print it to stderr in red, and return exit code 2. Reserve 1 for "findings were found" so CI can tell a real failure from a usage error.
3. Make the empty-result message honest about where it actually looked: print the resolved root, rather than the current sentence that always says ~/.claude/projects.
4. Handle the per-file failure case in parse_all too. One unreadable transcript in a directory of fifty should produce a warning and let the rest proceed, not abort the run.
5. Related: --file and --dir are not mutually exclusive, so --dir is silently ignored #8 notes that --file and --dir are not mutually exclusive. That belongs in the same validation block, so coordinate with whoever picks it up, or take both.

Done when

• No user-supplied path can produce a traceback.
• Usage errors exit 2 with a one line message on stderr.
• The no-runs message names the directory that was actually searched.
• One bad file in a directory does not abort the whole run.
• Tests cover each bad-path case.

---

If you want to take this on, comment on the issue to claim it and it will be assigned. Please keep to a maximum of 2 open claims per person at a time so other contributors get a chance.