Commit Graph
2 Commits
Author SHA1 Message Date
ff60d5764c fix(learn): treat an unreadable project memory dir as absent instead of crashing (#3710)
## Description

`headroom learn` aborts with a traceback when `~/.claude/projects/`
contains a project directory the user cannot traverse. Field report
(Headroom desktop 0.9.18, macOS):

```text
File ".../headroom/learn/plugins/claude.py", line 91, in discover_projects
    memory_file = memory_dir / "MEMORY.md" if memory_dir.exists() else None
PermissionError: [Errno 13] Permission denied: '~/.claude/projects/-/memory'
```

The `-` entry is the project dir for `/`, left behind by a session
Claude Code ran as root. The entry itself stats fine (its parent is the
user's own `projects/`), so `entry.is_dir()` passes, but nothing under
it is traversable and the first stat below it raises. #2446 guarded the
decoded project path and `CLAUDE.md` probes with `path_exists` for
exactly this reason; the `memory` probe two lines later was still a bare
`Path.exists()`.

This PR routes the two memory probes through the same `path_exists`
helper, so an unreadable project dir contributes no memory file and
discovery continues, instead of taking the whole scan down.

Closes #

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/learn/plugins/claude.py`: `discover_projects` probes
`<entry>/memory` and `<entry>/memory/MEMORY.md` with `_path_exists`
instead of `Path.exists()`, matching the project-path and `CLAUDE.md`
probes above it.
- `tests/test_learn/test_plugin_permission_errors.py`:
`test_claude_discover_projects_survives_unreadable_memory_dir` builds a
`projects/-/` entry whose `memory` subtree raises `PermissionError` on
stat and asserts discovery still returns the project with
`memory_file=None`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_learn/test_plugin_permission_errors.py -q
collected 6 items
tests/test_learn/test_plugin_permission_errors.py ......                 [100%]
6 passed in 0.75s

# With the fix reverted (git show HEAD~1:headroom/learn/plugins/claude.py), the new test fails:
E   PermissionError: [Errno 13] Permission denied: '.../projects/-/memory'
1 failed, 5 passed in 0.26s

$ uvx ruff check headroom/learn/plugins/claude.py tests/test_learn/test_plugin_permission_errors.py
All checks passed!
$ uvx ruff format --check headroom/learn/plugins/claude.py tests/test_learn/test_plugin_permission_errors.py
2 files already formatted
```

## Real Behavior Proof

- Environment: macOS 15, Python 3.12, worktree of `main` at 94206e26
(0.38.0)
- Exact command / steps: ran the new regression test against the fix and
against the pre-fix `claude.py`; the field traceback above is the
verbatim stderr from a Headroom desktop 0.9.18 install (Sentry RUST-HJ),
where `~/.claude/projects/-/` is a root-owned project directory.
- Observed result: pre-fix the test reproduces the field traceback
(`PermissionError ... /projects/-/memory` from `discover_projects`);
post-fix discovery returns the project with `memory_file=None` and the
remaining 5 permission tests still pass.
- Not tested: a live `headroom learn` run against a real root-owned
project dir on this machine (none present); mypy over the full package.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: no; an unreadable memory dir is now
treated as absent instead of crashing `learn`
- Kill switch / disable path: none needed; the change only widens an
existing `OSError`-to-absent guard to two more probes
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Documentation and mypy items are N/A: no user-facing behavior beyond
"learn no longer crashes", and the touched lines carry no new
annotations. Same class of fix as #2446 (claude project-path probes) and
#2522 (gemini/grok plugins); this is the last bare `Path.exists()` on a
path under a foreign-owned project entry in the claude plugin.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-24 11:12:45 -05:00
Abhay SinghandJerrett Davis 60bfe8be93 fix(learn): guard session-derived path checks against PermissionError in gemini/grok plugins (#2522)
## Description

Issue #2443 fixed a crash where `headroom learn` aborted with a raw
traceback because `Path.exists()` on a decoded candidate path raised
`PermissionError` (`os.stat` on a parent directory the user can't stat)
instead of returning `False`. That fix added a local `_path_exists`
guard to the **claude** plugin only.

The **gemini**, **grok**, and **opencode** plugins have the exact same
shape on paths recorded in session files / the opencode DB:

```python
# gemini: _detect_project_path (outside the json-load try)
if project_path and Path(project_path).exists():   # recorded projectPath / cwd
    ...
# gemini: discovery
if project_path and project_path.exists():
    candidate = project_path / "GEMINI.md"
    if candidate.exists(): ...
# grok: discovery
context_file=grok_md if grok_md.exists() else agents_md if agents_md.exists() else None
# opencode: discovery (worktree recorded in the SQLite DB)
agents_md = Path(worktree) / "AGENTS.md"
context_file=agents_md if agents_md.exists() else None
```

These paths come from session files that may have been written on
another machine or by another user, so a recorded `cwd`/`projectPath`
behind a restricted mount (or a decoded path colliding with another
user's home) makes `.exists()` raise `PermissionError`, which nothing
catches — aborting the whole `learn` run, exactly like #2443.

## Fix

Promote the claude plugin's local `_path_exists` into a shared
`headroom.learn.plugins._paths.path_exists` and use it for every
session-derived existence check across the claude, gemini, grok, and
opencode plugins. `path_exists` treats any `OSError` (including
`PermissionError`) as "does not exist", so discovery skips the path
instead of crashing. The claude plugin keeps its behavior (its
`_path_exists` name is now an import alias of the shared helper, so the
existing `TestDecodePermissionError` still passes).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/learn/plugins/_paths.py` (new): shared `path_exists` helper.
- `headroom/learn/plugins/claude.py`: import `path_exists` as
`_path_exists` and drop the local copy (behavior unchanged).
- `headroom/learn/plugins/gemini.py`: guard the `_detect_project_path`
`projectPath`/`cwd` checks and the discovery `GEMINI.md` probe.
- `headroom/learn/plugins/grok.py`: guard the `GROK.md` / `AGENTS.md`
probes.
- `headroom/learn/plugins/opencode.py`: guard the `AGENTS.md` probe
under the DB-recorded worktree path.
- `tests/test_learn/test_plugin_permission_errors.py` (new): regressions
that `path_exists` swallows `PermissionError`, that gemini
`_detect_project_path` returns `None` instead of raising, that grok
`discover_projects` completes with `context_file=None`, and the same for
opencode `discover_projects` over its SQLite DB.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_learn/test_plugin_permission_errors.py tests/test_learn/test_scanner.py::TestDecodePermissionError -q
7 passed

# with the gemini/grok/opencode source reverted, those plugin tests fail with
# PermissionError: [Errno 13] Permission denied

$ uvx ruff@0.15.17 check headroom/learn/plugins/ tests/test_learn/test_plugin_permission_errors.py
All checks passed!
$ uvx mypy@1.20.2 --ignore-missing-imports headroom/learn/plugins/_paths.py headroom/learn/plugins/gemini.py headroom/learn/plugins/grok.py headroom/learn/plugins/claude.py
Success: no issues found in 4 source files
```

One pre-existing, unrelated failure in
`tests/test_learn/test_scanner.py::TestDecodeProjectPath::test_home_dir_username_stays_single_component`
fails identically on clean `main` on Windows (it decodes a `/home/...`
POSIX path and asserts a non-`None` result); it is not touched by this
change.

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, project venv (`uv sync --extra
proxy`), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv.
- Exact command / steps: monkeypatched `Path.exists` to raise
`PermissionError` and called `path_exists`,
`GeminiPlugin(gemini_dir=tmp)._detect_project_path(session_with_projectPath)`,
`GrokPlugin(grok_dir=tmp).discover_projects()`, and
`OpenCodePlugin(db_path=db).discover_projects()` (each with a real
session tree / DB on disk); then reverted `gemini.py` / `grok.py` /
`opencode.py` and re-ran.
- Observed result: with the fix `path_exists` returns `False`, gemini
`_detect_project_path` returns `None`, and grok/opencode
`discover_projects` return one project with `context_file=None`; with
the fix reverted the gemini, grok, and opencode cases raise
`PermissionError: [Errno 13] Permission denied`. Ran against the actual
modules via `tests/test_learn/test_plugin_permission_errors.py`.
- Not tested: a real cross-user / restricted-mount filesystem end to end
(the PermissionError is injected).

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

---------

Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-09-09 23:13:02 -05:00