phase: 194_sync_pending_count

**Phase 194 — final verification pass: all green.**

**Verified (all 5 tasks already complete; nothing re-implemented needed)**
- `app/rag/importer.py`: `_prescan_pending` + `_pending_hash_stmt` (scalar `documents.file_hash`, own session, ONE `asyncio.to_thread` span, REPLACES the stats pre-walk), `on_scan_progress`, `progress` pair = pending position, `0` branch = byte-identical phase-193 walk.
- `app/config.py`/`settings_catalog.py`/`.env.example`: `sync_pending_count=1` + validator; `app/api/sync.py`: `"scan"` phase, `scan_done`/`scan_total` (additive after `files_total`, kept at every terminal), forced/throttled RSS split; `frontend/assets/sources.js`: `fmtSyncPhaseLabel` scan branch first-arm, `fmtSyncLabel` untouched.

**Tests / lint / coverage (exact commands)**
- `uv run pytest --cov=app --cov-report=term-missing` → **4835 passed**, `app/` 99% (7240 stmts / 16 miss), exit 0
- `uv run pytest tests/e2e/test_sync_pending_count.py -v --no-cov` → **8 passed in 150.81s** (phase suite, isolated)
- 14 sync-lineage E2E suites, one pytest process each (`test_sync_remaining_count`, `…_chunk_progress`, `…_progress_box`, `…_peak_memory_visible`, `…_label_mobile`, `…_upload_progress`, `test_archive_upload_sources`, `…_image_progress`, `…_summary_visibility`, `…_status_freshness`, `test_smoke`, `test_fast_path_deferred_content`, `test_sync_session_reset`, `test_sync_git_freeze`) → **all exit 0**
- `uv run ruff check .` → All checks passed; `uv run pyright` → **0 errors**

**Completion criteria** — all met: `N remaining` = predicted change set (E2E arms 1/2/5, first import counts the walk, no-change → no count part); `scan` phase visible + flips to `import`, scan pair reset/kept at terminals (`test_sync_scan_phase.py`); `BOR_SYNC_PENDING_COUNT=0` walk semantics ("7 remaining" arm) + **negative refuses startup naming the field (verified live by importing `app.main`)**; pre-scan off-loop + cancel lands `cancelled` (integration pins); CLI/upload byte-identical (unedited pins green); payload additive (`_PRE_187_STATUS_KEYS | _MEMORY_KEYS | _SCAN_KEYS`); suite green, coverage >90%, lint/types clean.

**Documentation** — 3 fixes: README sync "States" bullet had an **unclosed parenthesis** (pre-existing, 193/194) and the scan-label "total is 0" clause was ambiguous about a `=0` run (it still counts the walk once the import starts); **AGENTS.md rule 17 had a stray `)`** (pre-existing from phase 191). Also verified consistency both directions for all 87 settings ↔ README ↔ `.env.example` ↔ settings catalog, the pages table ↔ `app/main.py` routes, no stale `BOR_` names, and README/AGENTS claims through phase 194.

**Notes/deviations** — no live-infra changes (prod sync knob ships default-on, no deployment touched); no git index/history commands run (all changes left in the working tree for the harness); commit criterion left to the harness as instructed.

**Next pending phase:** none — `.agents/phases/todo/` holds only `194_sync_pending_count`, which is now ready to move to `complete/`.

tests/unit/test_config.py

@@ -1027,3 +1027,33 @@ def test_sync_prune_batch_rejects_negative(
     monkeypatch.setenv("BOR_SYNC_PRUNE_BATCH", "-1")
     with pytest.raises(ValidationError, match="sync_prune_batch"):
         _settings()
+
+
+# --- Sync pending count (phase 194) ---
+
+
+def test_sync_pending_count_default_and_env_override(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Phase 194 (D2): the pre-scan ships ON (``1``) — the owner's "1216
+    remaining" report means the walk-position count was wrong by default, so
+    the fix is the default and the rollback is the opt-in. ``0`` is accepted
+    and means the exact phase-193 behaviour: count every importable file of
+    the walk and never hash a file before the loop reached it."""
+    monkeypatch.delenv("BOR_SYNC_PENDING_COUNT", raising=False)
+    assert _settings().sync_pending_count == 1
+    monkeypatch.setenv("BOR_SYNC_PENDING_COUNT", "0")
+    assert _settings().sync_pending_count == 0
+    monkeypatch.setenv("BOR_SYNC_PENDING_COUNT", "1")
+    assert _settings().sync_pending_count == 1
+
+
+def test_sync_pending_count_rejects_negative(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A negative switch is a typo — no branch of the importer can mean it,
+    so startup refuses naming the field (the ``agent_max_rounds`` pattern,
+    phase 194). The value is a boolean knob, so ONLY ``0`` is the rollback."""
+    monkeypatch.setenv("BOR_SYNC_PENDING_COUNT", "-1")
+    with pytest.raises(ValidationError, match="sync_pending_count"):
+        _settings()