phase: 98_sync_summary_visibility

All verification complete. Final report:

**Phase 98 — Sync summary visibility: final verification pass** (all 5 tasks already complete; implementation verified against the design, no defects found, no code changes needed)

- **Implementation checked:** `SyncStatus` phase machine (4 new keys, terminal-keep counts), `on_progress` hook in `generate_folder_summaries`, `summary_pending` on `KbTreeSource`/`KbTreeFolder` + D3 rule in `build_kb_tree`, phase-aware sync labels + pending UI in `sources.js`, `.kb-summary-pending` CSS — all match decisions D1–D5.
- **Unit + integration:** `uv run pytest` → 2184 tests, 0 failed/errors (exit 0)
- **Coverage:** `uv run pytest --cov=app --cov-report=term-missing` → **99%** on `app/` (criterion >90% ✓; `app/api/sync.py` and `app/rag/folder_summaries.py` at 100%)
- **Lint/types:** `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings
- **Phase E2E (isolation):** `uv run pytest tests/e2e/test_sync_summary_visibility.py -v --no-cov` → **3 passed** (phase machine, live label, pending markers + gap-fill self-heal)
- **Regression suites (each isolated, `--no-cov`):** test_kb_tree ✓, test_ls_tree_drilldown 3 ✓, test_sync_button 3 ✓, test_sync_upload_progress 4 ✓, test_oneshot_llm_retry 2 ✓, test_local_directory_sources 3 ✓
- **Completion criteria:** all 7 verified green — status phase fields + terminal semantics; `Writing KB overview…`/`Summarizing folders… (n/m)` labels (title + aria-live); pending set == `missing_folder_summaries` (integration cross-check pinned at `test_docs_api.py:428`); CLI/`ls` byte-identity (no changes to those paths, pins green); suite/coverage/lint gates; dedicated + regression E2E. Commit left to the harness per protocol (no `git add`/`commit` run).
- **Decisions/deviations:** none — no fixes were required this pass.
- **Next pending phase:** `99_kb_tree_table_and_back_nav`.

tests/unit/test_sync_button.py

@@ -21,6 +21,19 @@ null/0/0); mid-run the status reports the file the (mock) import is
 processing, through the runner's own hook closure (no file yet during
 the clone/pull phase — A4); the terminal states clear
 ``current_file`` while keeping the run's final counts.
+
+Phase 98 (task 01): the status's phase machine joins the pins — the
+four new keys (``phase`` / ``current_summary`` / ``summaries_done`` /
+``summaries_total``) ride along as null/0/0/0 idle, the prelude keeps
+``phase: null``, the import reports ``phase: "import"``, and the
+terminal states clear ``phase`` + ``current_summary`` while keeping
+the run's final summary counts.
+
+Phase 98 (task 02): the running-state title rule is adjusted — the
+FULL untruncated LABEL (the file label, "Writing KB overview…", or
+"Summarizing folders… <folder> (n/m)") rides the button title for
+EVERY running label; the phase-64 "title only when there is a current
+file" (remove-when-null) rule is gone.
 """
 from __future__ import annotations
 
@@ -256,18 +269,29 @@ def test_sources_js_running_state_is_never_stale() -> None:
     fresh run starts clean: the previous failure's title / aria-label /
     .is-error come off NOW, not when the run settles.
 
-    Phase 64 (task 04): the button title carries the FULL untruncated
-    current file (removed when null — no file yet) and #sync-result
-    (the aria-live announcer) carries the same untruncated label."""
+    Phase 64 (task 04): #sync-result (the aria-live announcer) carries
+    the FULL untruncated label. Phase 98 (task 02): the title rule is
+    adjusted — the FULL untruncated LABEL (the file label, the overview
+    label, or the summaries label — whatever the running form is) rides
+    the button title for EVERY running label; the "title only when
+    there is a current file" (remove-when-null) rule is gone."""
     js = _text(SOURCES_JS)
     body = _body(js, "enterSyncRunningState")
     assert "syncBtn.disabled = true" in body
     assert 'syncBtn.setAttribute("aria-busy", "true")' in body
-    assert "syncBtn.title = currentFile" in body, "the full path on hover"
-    assert 'syncBtn.removeAttribute("title")' in body, "removed when no file yet"
-    title_if = body.find("if (currentFile) syncBtn.title = currentFile")
-    title_else = body.find("syncBtn.removeAttribute(\"title\")")
-    assert -1 < title_if < title_else, "title is set, not removed, only when a file exists"
+    assert "syncBtn.title = label" in body, (
+        "the full untruncated label on hover, for every running label"
+    )
+    assert 'syncBtn.removeAttribute("title")' not in body, (
+        "the title is set for EVERY running label (phase 98: the file-only "
+        "rule is adjusted away)"
+    )
+    title_i = body.find("syncBtn.title = label")
+    span_i = body.find("syncLabel.textContent = label")
+    result_i = body.find("syncResult.textContent = label")
+    assert -1 < title_i < span_i < result_i, (
+        "one label: built once, written to title, span AND the announcer"
+    )
     assert 'syncBtn.setAttribute("aria-label", "Sync sources")' in body
     assert "syncBtn.classList.remove(\"is-error\")" in body
     assert "syncIcon.classList.add(\"is-spinning\")" in body
@@ -793,7 +817,12 @@ def _patch_sync_seams(
         *,
         skip: bool = False,
         only_missing: bool = False,
+        on_progress: Callable[[int, int, str, str], None] | None = None,
     ) -> dict[str, int]:
+        # Phase 98 (task 01): the runner wires the progress hook into
+        # the generation branches — the fake accepts it (the state-
+        # machine tests' canned run never fires it: zero summary
+        # counters, like a no-gap skip).
         return {"generated": 0, "failed": 0, "pruned": 0}
 
     monkeypatch.setattr(sync_api, "generate_folder_summaries", fake_folder_summaries)
@@ -835,8 +864,9 @@ def test_idle_status_pins_full_shape_including_progress_keys(
     fresh_sync_status: None,
 ) -> None:
     """Idle: the three phase-64 progress keys ride along as null/0/0,
-    and EVERY pre-existing key is unchanged — the full response dict is
-    pinned, so the current UI and every existing consumer keep working."""
+    the four phase-98 phase keys as null/0/0/0, and EVERY pre-existing
+    key is unchanged — the full response dict is pinned, so the
+    current UI and every existing consumer keep working."""
     assert sync_api.sync_status() == {
         "state": "idle",
         "started_at": None,
@@ -846,6 +876,11 @@ def test_idle_status_pins_full_shape_including_progress_keys(
         "current_file": None,
         "files_done": 0,
         "files_total": 0,
+        # Phase 98 (task 01): the phase-machine keys — null/0/0/0 idle.
+        "phase": None,
+        "current_summary": None,
+        "summaries_done": 0,
+        "summaries_total": 0,
     }
 
 
@@ -869,19 +904,29 @@ def test_mid_run_status_reports_current_file(
     thread, errors = _start_run()
     try:
         assert clone.started.wait(5.0), "the run never reached the clone phase"
-        # Clone/pull phase: running — but no file yet (A4: bare "Syncing…").
+        # Clone/pull prelude: running — but no file yet (A4: bare
+        # "Syncing…") and no phase yet either (D1: the prelude stays
+        # null — the bare label's pin).
         s = sync_api.sync_status()
         assert s["state"] == "running"
+        assert s["phase"] is None
         assert s["current_file"] is None
+        assert s["current_summary"] is None
         assert s["files_done"] == 0 and s["files_total"] == 0
+        assert s["summaries_done"] == 0 and s["summaries_total"] == 0
         clone.release.set()
         assert fake_import.started.wait(5.0), "the run never reached the import"
-        # Import phase: the hook's file is live on the status.
+        # Import phase: the hook's file is live on the status, and the
+        # phase machine names the phase (the summary span has not
+        # started — its counters are still 0/0).
         s = sync_api.sync_status()
         assert s["state"] == "running"
+        assert s["phase"] == "import"
         assert s["current_file"] == "repo/notes/deep.md"
         assert s["files_done"] == 1
         assert s["files_total"] == 3
+        assert s["current_summary"] is None
+        assert s["summaries_done"] == 0 and s["summaries_total"] == 0
         fake_import.release.set()
     finally:
         clone.release.set()
@@ -894,11 +939,17 @@ def test_mid_run_status_reports_current_file(
     # assigned to the status above).
     assert fake_import.prune_flags == [True]
     assert fake_import.hook_calls == [("repo", "notes/deep.md", 1, 3)]
-    # Success terminal: current_file null, final counts retained.
+    # Success terminal: current_file null, final file counts retained;
+    # the phase machine clears phase + current_summary — the fake
+    # folder step never fired the summary hook, so the summary counts
+    # stay 0/0 (the keep-final-counts convention keeps what fired).
     s = sync_api.sync_status()
     assert s["state"] == "success"
+    assert s["phase"] is None
+    assert s["current_summary"] is None
     assert s["current_file"] is None
     assert s["files_done"] == 1 and s["files_total"] == 3
+    assert s["summaries_done"] == 0 and s["summaries_total"] == 0
     assert s["error"] is None
     assert s["started_at"] is not None and s["finished_at"] is not None
 
@@ -942,7 +993,10 @@ def test_failed_terminal_clears_current_file_keeps_counts(
     s = sync_api.sync_status()
     assert s["state"] == "failed"
     assert s["current_file"] is None  # cleared in the terminal state
+    assert s["phase"] is None  # phase 98: cleared in the terminal state
+    assert s["current_summary"] is None
     assert s["files_done"] == 1 and s["files_total"] == 3  # final counts kept
+    assert s["summaries_done"] == 0 and s["summaries_total"] == 0
     assert s["detail"] == {}
     error = s["error"] or ""
     assert "*****@aipi.example.com" in error  # credentials masked