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`.

README.md

@@ -241,15 +241,30 @@ BOR_SOURCES_DIR=~/bor-sources   # default; each repo lands in <dir>/<repo-name>/
 ```
 
 - Public repos need no setup: auth is whatever the machine supplies —
-  HTTPS via the OS credential helper, or SSH via your key.
+  HTTPS via the OS credential helper, or SSH via your key. The API
+  accepts `https://`, `http://`, `ssh://`, `git@`, and `file://` URLs
+  (phase 135: a `file://` local-transport repo — e.g. on a mounted
+  volume — is a valid source too).
 - Private repos: the add/edit form on the Git sources page takes an
   optional **masked token** field (phase 121). The token is stored in a
   dedicated DB column and injected into the clone URL only at
   sync/clone time — it is never returned by any API response or shown
   in the UI (legacy rows that already embed `user:token@` in the stored
   URL keep working — the token is sanitized on output).
-- Every run **clones** (first time, shallow `--depth 1`) or **pulls**
-  (`git pull --ff-only`) each repo, then indexes the checkout.
+- A git source can pin the **branch it mirrors** (phase 135): the
+  add/edit form's optional branch field (or the API's `branch`) stores
+  the branch in the `git_sources.branch` column — a fresh clone checks
+  that branch out, an existing checkout tracks it (`git fetch origin
+  <branch>` + `git merge --ff-only FETCH_HEAD`), and a checkout sitting
+  on a *different* branch fails the sync loudly with a remove-and-
+  re-add message (never a silent switch). Rows without a branch —
+  every pre-existing row and the env-fallback rows — keep the default
+  branch with byte-identical clone/pull behavior.
+- Every run **clones** (first time, full history) or **pulls**
+  (`git pull --ff-only`) each repo, then indexes the checkout. A legacy
+  shallow checkout is unshallowed once on its first post-phase-107 sync
+  (`git fetch --unshallow` — the one-time self-heal) so commit dates
+  stay real.
 - A failed sync aborts the run — no partial junk.
 
 ### Archive upload sources