Files
headroom/tests/test_learn/test_worktree_merge.py
d2fb350a34 fix(learn): only fold real linked worktrees into their main checkout (#4839)
## Description

`headroom learn` folds a linked git worktree's sessions into its main
checkout's project via `_main_worktree_root()`
(`headroom/learn/plugins/claude.py`). It read the checkout's `.git` file
(`gitdir: ...`) and that dir's `commondir`, and returned the parent of
whatever directory they named. Both files come from the checkout itself,
so a checkout whose pointers named an unrelated directory made learn use
that directory as the project root, and `learn --apply` wrote
`CLAUDE.local.md` there.

The function now accepts only git's own linked-worktree layout:
- the admin dir (the `gitdir:` target) must be
`<common>/worktrees/<name>`, and
- its `gitdir` file must point back at this checkout's `.git` (git
writes this for every `git worktree add`).

Anything else returns `None`, so the session folder stays its own
project at its own path (the existing fallback).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/learn/plugins/claude.py`: layout and back-pointer checks in
`_main_worktree_root()`.
- `tests/test_learn/test_worktree_merge.py`: the worktree fixture now
writes the `gitdir` back-pointer like real git; new tests for pointers
outside the `worktrees/<name>` layout and for an admin dir that does not
point back at the checkout.

## Testing

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

### Test Output

```text
# new tests on origin/main (fix stashed)
$ pytest -q tests/test_learn/test_worktree_merge.py
FAILED tests/test_learn/test_worktree_merge.py::test_main_worktree_root_ignores_pointers_outside_gits_worktree_layout
FAILED tests/test_learn/test_worktree_merge.py::test_main_worktree_root_needs_the_admin_dir_to_point_back
========================= 2 failed, 7 passed in 0.96s ==========================

# with the fix
$ pytest -q tests/test_learn
======================= 402 passed, 4 skipped in 32.06s ========================

$ ruff check / ruff format --check (0.17.3) on changed files
All checks passed!
2 files already formatted
$ mypy headroom/learn/plugins/claude.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, git 2.x, Python 3.12 venv.
- Exact command / steps: `git init m && git -C m commit --allow-empty -m
x && git -C m worktree add ../w`; separately a directory `scanned/`
whose `.git` file is `gitdir: <abs>/elsewhere/.git` with
`elsewhere/.git/commondir` = `.`. Then `_main_worktree_root(Path(...))`
for both.
- Observed result:
  - main: `w -> .../gwt/m`, `scanned -> .../gwt/elsewhere`
- this branch: `w -> .../gwt/m` (real worktree still folds), `scanned ->
None`
- Not tested: a full `learn --apply` run against live Claude Code
session folders.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: worktrees created by `git worktree
add` fold exactly as before. A worktree whose admin dir was moved or
whose back-pointer is stale (git would report it as prunable) is no
longer folded and stays its own project.
- Kill switch / disable path: n/a
- 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`

## Additional Notes

No docs change needed. Fix adapted from a proposal by HetCreep (this
version adds the back-pointer check, since the `worktrees/<name>` shape
alone can be reproduced inside a checkout).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4839"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-14 10:45:37 +05:30

179 lines
6.5 KiB
Python

"""A linked git worktree's sessions belong to its repo's learn project.
Claude Code files each working directory's sessions under its own
``~/.claude/projects`` folder, so a worktree (a Conductor workspace,
``.claude/worktrees/*``) used to surface as its own project.
"""
from __future__ import annotations
import json
import re
from pathlib import Path
from headroom.learn.plugins.claude import ClaudeCodePlugin, _main_worktree_root
from headroom.memory.traffic_learner import (
ExtractedPattern,
PatternCategory,
_project_for_pattern,
)
def _repo_with_worktree(base: Path) -> tuple[Path, Path]:
main, worktree = base / "repo", base / "workspaces" / "san-salvador"
gitdir = main / ".git" / "worktrees" / "san-salvador"
gitdir.mkdir(parents=True)
(gitdir / "commondir").write_text("../..\n")
(gitdir / "gitdir").write_text(f"{worktree / '.git'}\n")
worktree.mkdir(parents=True)
(worktree / ".git").write_text(f"gitdir: {gitdir}\n")
return main, worktree
def _folder(claude_dir: Path, cwd: Path) -> Path:
return claude_dir / "projects" / re.sub(r"[^A-Za-z0-9]", "-", str(cwd))
def _write_session(claude_dir: Path, cwd: Path, name: str) -> None:
call = {"type": "tool_use", "id": "u1", "name": "Bash", "input": {"command": "ls"}}
result = {"type": "tool_result", "tool_use_id": "u1", "content": "ok"}
lines = [
{"type": "assistant", "cwd": str(cwd), "message": {"content": [call]}},
{"type": "user", "cwd": str(cwd), "message": {"content": [result]}},
]
folder = _folder(claude_dir, cwd)
folder.mkdir(parents=True, exist_ok=True)
(folder / f"{name}.jsonl").write_text("\n".join(json.dumps(x) for x in lines) + "\n")
def test_main_worktree_root_resolves_linked_worktrees_only(tmp_path: Path) -> None:
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
(worktree / "src").mkdir()
submodule, sub_gitdir = main / "vendor" / "lib", main / ".git" / "modules" / "lib"
submodule.mkdir(parents=True)
sub_gitdir.mkdir(parents=True)
(submodule / ".git").write_text("gitdir: ../../.git/modules/lib\n")
assert _main_worktree_root(worktree) == main
assert _main_worktree_root(worktree / "src") == main
assert _main_worktree_root(main) is None
assert _main_worktree_root(submodule) is None
assert _main_worktree_root(base) is None
def test_relative_path_never_resolves_through_the_working_directory(
tmp_path: Path, monkeypatch
) -> None:
_, worktree = _repo_with_worktree(tmp_path.resolve())
monkeypatch.chdir(worktree)
assert _main_worktree_root(Path("C:\\Users\\dev\\work")) is None
assert _main_worktree_root(Path("src")) is None
def test_worktree_sessions_merge_into_the_main_checkout(tmp_path: Path) -> None:
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
claude_dir = base / "claude"
_write_session(claude_dir, main, "a")
_write_session(claude_dir, worktree, "b")
plugin = ClaudeCodePlugin(claude_dir=claude_dir)
[project] = plugin.discover_projects()
assert project.project_path == main
assert project.data_path == _folder(claude_dir, main)
assert project.worktree_paths == [worktree]
assert project.extra_data_paths == [_folder(claude_dir, worktree)]
assert len(plugin.scan_project(project)) == 2
def test_worktree_only_repo_gets_the_main_checkouts_memory_folder(tmp_path: Path) -> None:
# Conductor shape: every session runs in a workspace, none in the repo.
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
claude_dir = base / "claude"
_write_session(claude_dir, worktree, "a")
plugin = ClaudeCodePlugin(claude_dir=claude_dir)
[project] = plugin.discover_projects()
assert project.project_path == main
assert project.name == "repo"
assert project.data_path == _folder(claude_dir, main)
assert project.extra_data_paths == [_folder(claude_dir, worktree)]
assert len(plugin.scan_project(project)) == 1
def test_projects_outside_worktrees_are_untouched(tmp_path: Path) -> None:
base = tmp_path.resolve()
one, two = base / "one", base / "two"
one.mkdir()
two.mkdir()
claude_dir = base / "claude"
_write_session(claude_dir, one, "a")
_write_session(claude_dir, two, "b")
projects = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()
assert sorted(p.project_path for p in projects) == [one, two]
assert all(not p.worktree_paths and not p.extra_data_paths for p in projects)
def test_traffic_pattern_in_a_worktree_routes_to_its_repo(tmp_path: Path) -> None:
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
claude_dir = base / "claude"
_write_session(claude_dir, main, "a")
_write_session(claude_dir, worktree, "b")
[project] = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()
pattern = ExtractedPattern(
category=PatternCategory.PREFERENCE,
content=f"Edit `{worktree}/src/app.py` rather than the generated copy.",
importance=0.5,
)
assert _project_for_pattern(pattern, [project]) is project
def test_a_session_started_in_a_worktree_subfolder_records_the_checkout(tmp_path: Path) -> None:
"""Selecting the worktree itself must find a project whose only session
started in one of its subfolders."""
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
(worktree / "src").mkdir()
claude_dir = base / "claude"
_write_session(claude_dir, worktree / "src", "a")
[project] = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()
assert project.project_path == main
assert project.worktree_paths == [worktree / "src", worktree]
def test_main_worktree_root_ignores_pointers_outside_gits_worktree_layout(
tmp_path: Path,
) -> None:
base = tmp_path.resolve()
elsewhere = base / "elsewhere" / ".git"
elsewhere.mkdir(parents=True)
(elsewhere / "commondir").write_text(".\n")
(elsewhere / "gitdir").write_text(f"{base / 'checkout' / '.git'}\n")
checkout = base / "checkout"
checkout.mkdir()
(checkout / ".git").write_text(f"gitdir: {elsewhere}\n")
assert _main_worktree_root(checkout) is None
def test_main_worktree_root_needs_the_admin_dir_to_point_back(tmp_path: Path) -> None:
base = tmp_path.resolve()
main, worktree = _repo_with_worktree(base)
other = base / "other"
other.mkdir()
(other / ".git").write_text(f"gitdir: {main / '.git' / 'worktrees' / 'san-salvador'}\n")
assert _main_worktree_root(worktree) == main
assert _main_worktree_root(other) is None