fix(#89): address review findings in deferred follow-ups

promote_diff checkpoint_step: make catalog_promote_diff checkpoint-exempt (it self-checkpoints, exactly like catalog_recalc) and stamp the recalc sub-report with that single step. Removes the redundant dispatch-decorator commit (the pre-existing empty trailing commit) so the promote + cascade are genuinely ONE revision, and the reported step names it.

Stage C focus guard: recalcTarget takes a focused flag and returns null when the tab is focused, mirroring the #27 NewEntryPill policy — a focused/mid-edit view is never yanked (which would discard unsaved code); a backgrounded view still refreshes. seenRecalc seeds from the mount-time version so a pre-mount recalc isn't replayed.

Plus: pin the companion auto path's by-design None checkpoint_step in test_companion_revise_publishes_recalc_event (assertion-tightening, green today).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: paddymul

packages/app/src/pages/CatalogPage.tsx

@@ -346,15 +346,18 @@ export function CatalogPage() {
   }, [project, version]);
 
   // A recalc re-points aliases to recomputed hashes; if the open entry view is
-  // one of them, navigate to the new hash so the detail pane (keyed on the URL
-  // hash) refetches the fresh result. Process each SSE version at most once
-  // (StrictMode double-fires effects), mirroring NewEntryPill.
-  const seenRecalc = useRef(0);
+  // one of them (and this tab is backgrounded — see recalcTarget), navigate to
+  // the new hash so the detail pane (keyed on the URL hash) refetches the fresh
+  // result. Process each SSE version at most once (StrictMode double-fires
+  // effects), mirroring NewEntryPill. Seed `seen` with the mount-time version so
+  // a recalc that fired before this page mounted isn't replayed on first render.
+  const seenRecalc = useRef(version);
   useEffect(() => {
     if (version === seenRecalc.current) return;
     seenRecalc.current = version;
     if (!project || !lastEvent || lastEvent.kind !== "recalc") return;
-    const target = recalcTarget(hash, lastEvent.remap as Record<string, string> | undefined);
+    const focused = typeof document !== "undefined" && document.hasFocus();
+    const target = recalcTarget(hash, lastEvent.remap as Record<string, string> | undefined, focused);
     if (target && target !== hash) navigate(`/${project}/catalog/${target}`);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [version]);

packages/app/src/recalcRefresh.ts

@@ -1,15 +1,23 @@
 // An auto-recalc (or explicit recalc) re-points an alias from an old content
 // hash to a freshly recomputed one and publishes a `recalc` SSE event carrying
 // the {oldHash: newHash} remap. The open entry view is addressed by content hash
-// in the URL, so a view parked on a head that was just remapped must navigate to
-// the recomputed hash to refresh. Only that view moves: an unrelated or older
-// hash (not a remap key) stays put. The navigation glue lives in CatalogPage.tsx.
+// in the URL, so a backgrounded view parked on a head that was just remapped
+// navigates to the recomputed hash to refresh. Only that view moves: an
+// unrelated or older hash (not a remap key) stays put. The navigation glue lives
+// in CatalogPage.tsx.
+//
+// A *focused* view stays put even when remapped — mirroring the NewEntryPill /
+// #27 policy of never yanking an active user. This also protects an in-progress
+// code edit: navigating remounts the hash-keyed detail pane and would discard
+// unsaved text. The common case (revise via Claude, the browser backgrounded)
+// still refreshes; only an actively-watched tab is left to refresh on its own.
 
 // Returns the hash the open view should navigate to, or null when nothing moves.
 export function recalcTarget(
   currentHash: string | undefined,
   remap: Record<string, string> | undefined,
+  focused: boolean,
 ): string | null {
-  if (!currentHash || !remap) return null;
+  if (focused || !currentHash || !remap) return null;
   return remap[currentHash] ?? null;
 }

src/tallyman_mcp/server.py

@@ -129,6 +129,7 @@ def wrapped(*args, **kwargs):
         "catalog_diff",
         "catalog_scan_staleness",  # read-only staleness scan
         "catalog_recalc",  # self-checkpoints (arg-aware: dry-run takes none, a real run one)
+        "catalog_promote_diff",  # self-checkpoints one tx for the promote + cascade (no double-commit)
         "catalog_list_summary_stats",
         "catalog_list_post_processings",
         "catalog_run_post_processing",  # preview, persists nothing
@@ -909,7 +910,12 @@ def _resolve(v):
     # checkpoint so that one revision sweeps the promote + the cascade together.
     recalc_report = _auto_recalc_after_head_advance(project, target_alias) if repointed else None
 
-    checkpoint_catalog(project, f"tallyman: catalog_promote_diff {name} V{a_idx}→V{b_idx}")
+    # promote_diff is checkpoint-exempt (self-checkpoints): THIS is the single
+    # revision the promote + cascade land in. Stamp its step onto the recalc
+    # sub-report — the checkpoint-free walk built it before this commit existed.
+    step = checkpoint_catalog(project, f"tallyman: catalog_promote_diff {name} V{a_idx}→V{b_idx}")
+    if recalc_report is not None:
+        recalc_report["checkpoint_step"] = step
     _notify("entry_added", content_hash=result.content_hash)
     out = {
         "alias": target_alias,

tests/test_recalc_surfaces.py

@@ -364,5 +364,9 @@ def test_companion_revise_publishes_recalc_event(project, orders_parquet, monkey
     assert r.status_code == 200, r.text
     # The companion publishes the canonical recalc SSE event with the cascade's remap.
     assert captured, "no recalc event published"
-    remap, _step = captured[0]
+    remap, step = captured[0]
     assert remap == {b: get_alias(project, "b")}
+    # checkpoint_step is None by design on the companion auto path: the middleware
+    # commits the revision AFTER the handler returns, and (unlike the MCP decorator)
+    # the response is already serialized, so there's nothing to backfill into.
+    assert step is None