phase: 135_git_source_branch

All verification complete. No edits were needed by this pass — the phase work and docs were already consistent and green.

**Phase 135 final verification pass — report**

- Verified all 5 tasks' work present & correct: migration 0024 (reversible), `GitSource.branch` + 4 schema shapes, `validate_branch_name` (full check order per design), `clone_or_pull(…, branch)` (HEAD guard first, `--branch` clone, fetch+ff merge), both call sites pass `row.branch`, UI (add-form field, editor field, row tag), `file://` URL transport.
- Completion criteria: (1) branch-mirrored through Sync + CLI — **pass** (E2E + integration); (2) `branch=None` byte-identical — **pass** (`test_branch_none_argv_is_byte_identical_pre_phase_sequence` green); (3) fixed 422s / local-row 422 / tri-state — **pass**; (4) mismatch fails loudly with remove-and-re-add — **pass** (E2E); (5) coverage 99% >90%, E2E isolated green — **pass**; (6) no regressions — **pass**.
- Tests: `uv run pytest --cov=app --cov-report=term-missing` → 3223 passed, app/ 99%; `uv run pytest tests/e2e/test_git_source_branch.py -v --no-cov` → 4 passed (16.4 s); `uv run ruff check .` clean; `uv run pyright` → 0 errors, 0 warnings.
- Documentation: README.md reviewed in full — phase-135 branch section accurate; the phase's README diff also correctly fixed a pre-existing stale line (shallow `--depth 1` clone vs full-history, phase 107). Routes, env defaults, feature lists verified against code. AGENTS.md — all 10 rules + quick-reference verified (referenced tests, PLAN.md, phases dirs, commands all accurate). **Verified consistent — no changes needed.**
- No live-infrastructure changes (dev DB already running and healthy; no live steps in this phase).
- Next pending phase: `.agents/phases/todo/136_force_push_reset`.

tests/integration/test_sync_api.py

@@ -91,6 +91,8 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
+import subprocess
 import threading
 import time
 from collections.abc import Callable, Iterator, Sequence
@@ -113,7 +115,7 @@ from app.rag.folder_summaries import affected_folder_keys
 from app.rag.importer import ImportSummary
 from app.rag.llm import EmbeddingError, LLMClient, ModelUnavailableError
 from app.rag.sources_meta import current_sources_version
-from scripts.git_sync import GitSyncError
+from scripts.git_sync import GitSyncError, clone_or_pull
 from tests.conftest import ADMIN_PASSWORD
 from tests.fakes import FakeEmbedder
 
@@ -414,10 +416,12 @@ class FakeFolderSummaries:
 
 
 def _fake_clone() -> tuple[list[tuple[str, Path]], object]:
-    """A ``clone_or_pull`` that materialises a checkout with one .md file."""
+    """A ``clone_or_pull`` that materialises a checkout with one .md
+    file. Phase 135: accepts the row's branch pin (the third argument
+    — ``None`` for every row this file seeds)."""
     calls: list[tuple[str, Path]] = []
 
-    def fake_clone_or_pull(url: str, dest: Path | str) -> Path:
+    def fake_clone_or_pull(url: str, dest: Path | str, branch: str | None = None) -> Path:
         dest = Path(dest)
         dest.mkdir(parents=True, exist_ok=True)
         (dest / "notes.md").write_text(f"# {dest.name}\ncontent for the KB\n", encoding="utf-8")
@@ -1193,7 +1197,7 @@ def test_git_failure_marks_failed_and_skips_import(
         lambda: _settings(sources_dir=str(tmp_path / "bor")),
     )
 
-    def failing_clone(url: str, dest: Path | str) -> Path:
+    def failing_clone(url: str, dest: Path | str, branch: str | None = None) -> Path:
         raise GitSyncError(
             f"git clone {url} failed (exit 128): "
             "fatal: repository not found"
@@ -1993,3 +1997,142 @@ def test_cancel_mid_run_lands_in_cancelled_then_resyncs_clean(
     assert current_sources_version(db) == 1
     assert len(second_import.sources) == 1
     assert second_import.prune_flags == [True]
+
+
+# --- phase 135: the branch pin (real git, two-branch file:// origin) -------
+
+
+def _git_available() -> bool:
+    try:
+        proc = subprocess.run(["git", "--version"], capture_output=True, check=False)
+        return proc.returncode == 0
+    except (FileNotFoundError, OSError):
+        return False
+
+
+#: Real ``git`` in the test environment — skipped cleanly without it
+#: (the ``test_git_file_dates.py`` house pattern).
+GIT = _git_available()
+
+
+def _git(cwd: Path, *argv: str) -> None:
+    """Run one git command for the test harness (fixture setup); a
+    non-zero exit fails the fixture, not the test under test."""
+    env = os.environ.copy()
+    env["GIT_AUTHOR_NAME"] = "T"
+    env["GIT_AUTHOR_EMAIL"] = "t@example.com"
+    env["GIT_COMMITTER_NAME"] = "T"
+    env["GIT_COMMITTER_EMAIL"] = "t@example.com"
+    proc = subprocess.run(
+        ["git", *argv], cwd=cwd, env=env, capture_output=True, text=True, check=False
+    )
+    assert proc.returncode == 0, f"git {' '.join(argv)} failed: {proc.stderr}"
+
+
+def _two_branch_origin(tmp_path: Path) -> Path:
+    """A real-git scratch origin (the phase-135 recipe): ``main`` holds
+    ``a.md``, ``release`` holds ``b.md`` — different content per
+    branch (a branch checkout is the branch's tree, not main's)."""
+    origin = tmp_path / "origin"
+    origin.mkdir()
+    _git(origin, "init", "-q", "-b", "main")
+    _git(origin, "config", "commit.gpgsign", "false")
+    (origin / "a.md").write_text("# A\nmain branch content\n", encoding="utf-8")
+    _git(origin, "add", "a.md")
+    _git(origin, "commit", "-q", "-m", "main: add a.md")
+    _git(origin, "checkout", "-q", "-b", "release")
+    (origin / "a.md").unlink()
+    (origin / "b.md").write_text("# B\nrelease branch content\n", encoding="utf-8")
+    _git(origin, "add", "-A")
+    _git(origin, "commit", "-q", "-m", "release: add b.md")
+    _git(origin, "checkout", "-q", "main")
+    return origin
+
+
+@pytest.mark.skipif(not GIT, reason="git CLI not available")
+def test_git_row_with_branch_button_path_clones_that_branch(
+    sync_client: TestClient,
+    monkeypatch: pytest.MonkeyPatch,
+    db: Session,
+    tmp_path: Path,
+) -> None:
+    """Phase 135: the BUTTON path honors the row's branch pin — a
+    ``git_sources`` row with ``branch='release'`` is cloned with the
+    REAL ``clone_or_pull`` (no fake in this test): the imported root
+    is the RELEASE tree (file B present, file A absent)."""
+    origin = _two_branch_origin(tmp_path)
+    db.add(GitSource(url=f"file://{origin}", kind="git", branch="release"))
+    db.commit()
+    _stub_env(monkeypatch)
+    monkeypatch.setattr(
+        sync_api,
+        "get_settings",
+        lambda: _settings(sources_dir=str(tmp_path / "bor")),
+    )
+    _stub_probe(monkeypatch)
+    fake_import = FakeImportSources(ImportSummary(files=1, added=1))
+    monkeypatch.setattr(sync_api, "import_sources", fake_import)
+    monkeypatch.setattr(sync_api, "regenerate_overview", FakeOverview(ok=True))
+    monkeypatch.setattr(sync_api, "generate_folder_summaries", FakeFolderSummaries())
+
+    _login(sync_client)
+    assert sync_client.post("/api/sync").status_code == 202
+    body = _poll(sync_client, "success")
+    assert body["error"] is None
+
+    root = tmp_path / "bor" / "origin"
+    assert fake_import.sources == [[root]]
+    assert (root / "b.md").is_file()  # the branch's file is what got imported
+    assert not (root / "a.md").exists()
+
+
+@pytest.mark.skipif(not GIT, reason="git CLI not available")
+def test_git_row_branch_mismatch_button_path_fails_loud(
+    sync_client: TestClient,
+    monkeypatch: pytest.MonkeyPatch,
+    db: Session,
+    tmp_path: Path,
+) -> None:
+    """Phase 135 (ASSUMPTION B5): a row pinning a branch the EXISTING
+    checkout does not sit on fails the button sync LOUDLY — the
+    remove-and-re-add message, zero import attempts, and the checkout
+    untouched (still on its branch: no silent switch)."""
+    origin = _two_branch_origin(tmp_path)
+    url = f"file://{origin}"
+    dest = tmp_path / "bor" / "origin"
+    # A pre-existing checkout on the default branch (main) — e.g. a
+    # row that existed before the branch was pinned (the sync's
+    # sources_dir is seeded with it before the run starts).
+    clone_or_pull(url, dest)
+    db.add(GitSource(url=url, kind="git", branch="release"))
+    db.commit()
+    _stub_env(monkeypatch)
+    monkeypatch.setattr(
+        sync_api,
+        "get_settings",
+        lambda: _settings(sources_dir=str(tmp_path / "bor")),
+    )
+    _stub_probe(monkeypatch)
+    fake_import = FakeImportSources(ImportSummary())
+    monkeypatch.setattr(sync_api, "import_sources", fake_import)
+    monkeypatch.setattr(sync_api, "regenerate_overview", FakeOverview(ok=True))
+    monkeypatch.setattr(sync_api, "generate_folder_summaries", FakeFolderSummaries())
+
+    _login(sync_client)
+    assert sync_client.post("/api/sync").status_code == 202
+
+    body = _poll(sync_client, "failed")
+    assert "remove and re-add the source to switch branches" in body["error"]
+    assert "'main'" in body["error"] and "'release'" in body["error"]
+    assert body["detail"] == {}
+    assert fake_import.sources == []  # no partial import
+    # Phase 53: a FAILED sync never bumps.
+    assert current_sources_version(db) == 0
+    # the checkout is untouched: still on main, still main's tree
+    proc = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=dest, capture_output=True, text=True, check=False,
+    )
+    assert proc.returncode == 0 and proc.stdout.strip() == "main"
+    assert (dest / "a.md").is_file()
+    assert not (dest / "b.md").exists()