feat: keep Following changes for later (Closes #1320)

tests/e2e/test_mobile_following_release.py

@@ -77,6 +77,15 @@ def test_following_queue_is_phone_usable_at_narrow_viewport(viewport):
           {status:'ready'}, document.querySelector('#watch-search-result'))""")
         expect(retire).to_have_text("Watch pull request")
         assert retire.bounding_box()["height"] >= 44
+        keep = page.locator("#keep-following-for-later")
+        page.evaluate("document.querySelector('#keep-following-for-later').hidden = false")
+        expect(keep).to_be_visible()
+        expect(keep).to_have_text("Keep for later & next")
+        assert keep.bounding_box()["height"] >= 44
+        assert page.locator("#keep-following-status").evaluate(
+            "node => getComputedStyle(node).overflowWrap"
+        ) == "anywhere"
+        assert page.locator("#keep-following-status").bounding_box()["height"] >= 20
         overflow = page.evaluate("document.documentElement.scrollWidth > document.documentElement.clientWidth")
         assert overflow is False
         browser.close()

tests/test_comment_next.py

@@ -303,4 +303,4 @@ async def test_unread_update_offers_reply_mark_read_and_next_independent_of_toda
     assert '.update-reply-actions { display:grid; grid-template-columns:repeat(2,minmax(0,1fr));' in html
     assert '.update-reply-actions button { min-height:44px;' in html
     worker = (Path(__file__).parents[1] / "frontend" / "service-worker.js").read_text()
-    assert "stackchain-dashboard-shell-v135" in worker
+    assert "stackchain-dashboard-shell-v136" in worker

tests/test_following_api.py

@@ -293,6 +293,35 @@ async def test_following_acknowledges_only_the_exact_loaded_revision(monkeypatch
     assert response.json()["items"][0]["has_unseen_change"] is False
 
 
+@pytest.mark.anyio
+async def test_following_keep_restores_only_the_loaded_revision(monkeypatch, tmp_path):
+    store = FollowingStore(tmp_path / "following.sqlite3", encryption_key=b"f" * 32)
+    item = {
+        "repository": "stackchain/api", "kind": "pull", "number": 42, "title": "Changed",
+        "state": "open", "updated_at": "2026-08-23T03:00:00Z",
+        "url": "https://forge.example/stackchain/api/pulls/42",
+    }
+    store.set_watching("timmy", item, True)
+    changed = {**item, "updated_at": "2026-08-23T04:00:00Z"}
+    store.refresh("timmy", [changed])
+    store.acknowledge("timmy", item["repository"], item["number"], changed["updated_at"], kind="pull")
+
+    async def user():
+        return {"login": "timmy"}
+
+    monkeypatch.setattr(main, "_following_store", lambda: store)
+    monkeypatch.setattr(main, "current_user", user)
+    transport = httpx.ASGITransport(app=main.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.put(
+            "/api/v1/following/stackchain/api/issues/42/keep?kind=pull",
+            json={"updated_at": changed["updated_at"]},
+        )
+
+    assert response.status_code == 200
+    assert response.json()["items"][0]["has_unseen_change"] is True
+
+
 @pytest.mark.anyio
 async def test_closed_following_issue_can_be_unwatched_but_not_newly_watched(monkeypatch, tmp_path):
     store = FollowingStore(tmp_path / "following.sqlite3", encryption_key=b"g" * 32)

tests/test_following_frontend.py

@@ -96,6 +96,23 @@ def test_dashboard_dispatches_following_route_to_changed_first_review():
     assert route_handler.index("followingQueue.route") < route_handler.index("selectWorkQueue")
 
 
+def test_following_preview_wires_keep_for_later_action_and_retryable_failure():
+    html = (ROOT / "frontend" / "index.html").read_text()
+    dashboard = (ROOT / "frontend" / "dashboard.js").read_text()
+    following = MODULE.read_text()
+
+    assert 'id="keep-following-for-later"' in html
+    assert 'id="keep-following-status"' in html
+    assert "followingQueue.preview(state)" in dashboard
+    assert "query('#close-search-preview').click()" in following
+    assert "state?.item?.following !== true" in following
+    assert "feature.keepForLater(activeReviewItem)" in following
+    assert "Kept for later" in following
+    assert "Could not keep this change for later" in following
+    assert "changeRevision(item, 'keep')" in following
+    assert "keepForLater:feature.keepForLater" in following
+
+
 def test_following_typed_identity_prevents_issue_pull_collisions():
     script = f"""
 const createFollowing = require({json.dumps(str(MODULE))});
@@ -243,6 +260,42 @@ const feature = createFollowing({{
     assert result["renders"][-1]["reviewSummary"] == {"reviewed": 2, "remaining": 0}
 
 
+def test_following_keep_for_later_preserves_revision_and_advances_without_looping():
+    script = f"""
+const createFollowing = require({json.dumps(str(MODULE))});
+const state = {{opened:[], acknowledged:[], kept:[], counts:[]}};
+const items=[
+  {{repository:'stackchain/api',number:42,title:'First',updated_at:'2026-08-23T06:00:00Z',has_unseen_change:true}},
+  {{repository:'stackchain/web',number:9,title:'Second',updated_at:'2026-08-23T05:00:00Z',has_unseen_change:true}}
+];
+const feature = createFollowing({{
+  fetchJson:async () => ({{revision:7,items}}),
+  onOpen:async item => state.opened.push(item.number),
+  onAcknowledge:async item => state.acknowledged.push(item.number),
+  onKeep:async item => state.kept.push(item.number),
+  onCount:value => state.counts.push(value),
+}});
+(async () => {{
+  await feature.load();
+  await feature.startReview();
+  const kept = await feature.keepForLater(feature.session().items[0]);
+  process.stdout.write(JSON.stringify({{
+    kept, session:feature.session(), items:feature.items(), state
+  }}));
+}})().catch(error => {{ console.error(error); process.exit(1); }});
+"""
+    result = json.loads(subprocess.run(
+        ["node", "-e", script], text=True, capture_output=True, check=True
+    ).stdout)
+
+    assert result["kept"]["number"] == 9
+    assert [item["number"] for item in result["session"]["items"]] == [9]
+    assert result["items"][0]["has_unseen_change"] is True
+    assert result["state"] == {
+        "opened": [42, 9], "acknowledged": [42, 9], "kept": [42], "counts": [2, 1, 2, 1]
+    }
+
+
 def test_following_review_notifies_prepare_today_when_final_revision_is_loaded():
     script = f"""
 const createFollowing = require({json.dumps(str(MODULE))});
@@ -367,13 +420,13 @@ def test_following_review_controls_are_wired_into_the_phone_preview_flow():
     assert "query('#review-following').addEventListener('click'" in following
     assert "getSession:() => followingQueue.session() || commandSearchState" in dashboard
     assert "onOpened:item => followingQueue.previewLoaded(item)" in dashboard
-    assert "'/seen?kind=' + encodeURIComponent(item.kind)" in following
+    assert "changeRevision(item, 'seen')" in following
     assert "afterUnwatch:item => followingQueue.retire(item)" in dashboard
     assert "followingQueue.returnToFollowing()" in dashboard
     assert "'Back to Following'" in dashboard
     assert "if (searchPreviewReturnKind === 'following')" in dashboard
     assert "e.key === 'Escape' && searchPreviewReturnKind === 'following'" in dashboard
-    assert "stackchain-dashboard-shell-v135" in service_worker
+    assert "stackchain-dashboard-shell-v136" in service_worker
 
 
 def test_prepare_today_lazily_refreshes_and_directly_reviews_following():

tests/test_following_store.py

@@ -66,6 +66,36 @@ def test_acknowledgement_is_revision_conditional_and_later_change_is_unseen(tmp_
     assert store.get("timmy")["items"][0]["has_unseen_change"] is True
 
 
+def test_keep_for_later_restores_the_exact_seen_revision_as_unseen(tmp_path):
+    store = FollowingStore(tmp_path / "following.sqlite3", encryption_key=KEY)
+    store.set_watching("timmy", ITEM, True)
+    changed = {**ITEM, "updated_at": "2026-08-23T04:00:00Z"}
+    store.refresh("timmy", [changed])
+    store.acknowledge("timmy", ITEM["repository"], ITEM["number"], changed["updated_at"])
+
+    snapshot = store.keep_unseen(
+        "timmy", ITEM["repository"], ITEM["number"], changed["updated_at"]
+    )
+
+    assert snapshot["items"][0]["has_unseen_change"] is True
+    assert store.get("timmy")["items"][0]["has_unseen_change"] is True
+
+
+def test_reopening_a_kept_revision_acknowledges_it_again(tmp_path):
+    store = FollowingStore(tmp_path / "following.sqlite3", encryption_key=KEY)
+    store.set_watching("timmy", ITEM, True)
+    changed = {**ITEM, "updated_at": "2026-08-23T04:00:00Z"}
+    store.refresh("timmy", [changed])
+    store.acknowledge("timmy", ITEM["repository"], ITEM["number"], changed["updated_at"])
+    store.keep_unseen("timmy", ITEM["repository"], ITEM["number"], changed["updated_at"])
+
+    snapshot = store.acknowledge(
+        "timmy", ITEM["repository"], ITEM["number"], changed["updated_at"]
+    )
+
+    assert snapshot["items"][0]["has_unseen_change"] is False
+
+
 def test_reconfirmed_watch_does_not_mark_an_unseen_change_as_seen(tmp_path):
     store = FollowingStore(tmp_path / "following.sqlite3", encryption_key=KEY)
     store.set_watching("timmy", ITEM, True)

tests/test_frontend_bundle.py

@@ -72,6 +72,8 @@ def test_product_workflows_are_stable_lazy_feature_chunks(tmp_path):
     assert b"function createQueueToday" not in first.runtime_bytes
     assert b"function createQueueToday" in first.feature_bundles["today-timer"].runtime_bytes
     assert b"function createPlanToday" in first.feature_bundles["planning"].runtime_bytes
+    assert b"function createFollowing" in first.feature_bundles["planning"].runtime_bytes
+    assert b"function createFollowing" not in first.feature_bundles["today-timer"].runtime_bytes
     assert b"function createTomorrowPlan" in first.feature_bundles["planning"].runtime_bytes
     assert b"function createPlanToday" not in first.runtime_bytes
     assert b"function createConversationPager" in first.feature_bundles["today-timer"].runtime_bytes

tests/test_later_sync.py

@@ -435,5 +435,5 @@ async def test_dashboard_syncs_every_later_change_and_exposes_account_status():
 def test_later_sync_ships_atomically_in_the_offline_shell():
     source = (Path(__file__).parents[1] / "frontend" / "service-worker.js").read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/later-sync.js'" in source

tests/test_markdown_renderer.py

@@ -256,4 +256,4 @@ def test_markdown_work_bodies_are_mobile_safe_block_containers():
     assert ".markdown-content { min-width:0; max-width:100%; overflow-wrap:anywhere;" in css
     assert ".markdown-content pre { max-width:100%; overflow-x:auto;" in css
     assert ".markdown-content a { min-height:44px;" in css
-    assert "stackchain-dashboard-shell-v135" in worker
+    assert "stackchain-dashboard-shell-v136" in worker

tests/test_mobile_composer_integration.py

@@ -45,7 +45,7 @@ def test_offline_shell_contains_every_local_dashboard_runtime_asset():
     shell_assets = set(re.findall(r"BASE \+ '([^']+)'", worker.split("async function sessionCsrf", 1)[0]))
 
     assert local_assets <= shell_assets, f"Offline shell is missing: {sorted(local_assets - shell_assets)}"
-    assert "stackchain-dashboard-shell-v135" in worker
+    assert "stackchain-dashboard-shell-v136" in worker
 
 
 def test_all_conversation_composers_offer_accessible_mobile_mentions():

tests/test_mobile_device_setup.py

@@ -383,7 +383,7 @@ def test_mobile_dashboard_mounts_phone_safe_device_setup_flow():
     assert "controller.recoverPermission('deadline')" in dashboard
     assert "pushControllerReady.then(ensureDeviceSetup)" in dashboard
     assert "BASE + 'static/mobile-device-setup.js'" in worker
-    assert "stackchain-dashboard-shell-v135" in worker
+    assert "stackchain-dashboard-shell-v136" in worker
     assert ".device-setup-panel" in css
     assert ".device-readiness-card" in css
     assert "overflow-x:hidden" in css

tests/test_mobile_insights.py

@@ -243,5 +243,5 @@ async def test_mobile_home_progressively_discloses_secondary_panels_as_insights(
 def test_mobile_insights_rolls_into_the_offline_shell():
     worker = (CONTROLLER.parent / "service-worker.js").read_text()
 
-    assert "stackchain-dashboard-shell-v135" in worker
+    assert "stackchain-dashboard-shell-v136" in worker
     assert "BASE + 'static/mobile-insights.js'" in worker

tests/test_mobile_start_day.py

@@ -414,7 +414,7 @@ async def test_dashboard_wires_thumb_safe_start_day_briefing_into_offline_mobile
     assert ".mobile-start-day-finish { min-height:44px;" in html
     assert "max-width:100%; overflow-wrap:anywhere;" in html
     assert "BASE + 'static/mobile-start-day.js'" in service_worker
-    assert "stackchain-dashboard-shell-v135" in service_worker
+    assert "stackchain-dashboard-shell-v136" in service_worker
 
 
 @pytest.mark.anyio

tests/test_plan_today.py

@@ -418,7 +418,7 @@ async def test_starting_saved_today_work_closes_a_concurrent_rollover_planner():
 def test_plan_today_controller_is_available_in_the_offline_shell():
     source = SERVICE_WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/plan-today.js'" in source
     assert "BASE + 'static/plan-today-readiness.js'" in source
     assert "BASE + 'static/plan-today-preview.js'" in source

tests/test_service_worker.py

@@ -186,7 +186,7 @@ async function dispatchPush(payload) {{
 def test_week_unplan_undo_rolls_the_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/week-plan.js'" in source
     assert "BASE + 'static/dashboard.css'" in source
 
@@ -194,20 +194,20 @@ def test_week_unplan_undo_rolls_the_offline_shell():
 def test_private_today_action_mailbox_rolls_the_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
 
 
 def test_per_day_week_conflict_ui_rolls_the_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/week-plan.js'" in source
 
 
 def test_resumable_today_session_ships_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/my-work.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
     assert "BASE + 'static/dashboard.css'" in source
@@ -216,7 +216,7 @@ def test_resumable_today_session_ships_in_a_new_offline_shell():
 def test_mobile_conversation_photo_bundles_roll_the_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/dashboard.js'" in source
     assert "BASE + 'static/authored-outbox.js'" in source
     assert "BASE + 'static/background-issue-sync.js'" in source
@@ -225,7 +225,7 @@ def test_mobile_conversation_photo_bundles_roll_the_offline_shell():
 def test_photo_metadata_sanitizer_rolls_the_cached_optimizer_atomically():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/issue-evidence-review.js'" in source
     assert "BASE + 'static/issue-attachment.js'" in source
 
@@ -233,14 +233,14 @@ def test_photo_metadata_sanitizer_rolls_the_cached_optimizer_atomically():
 def test_ownership_exit_runtime_rolls_the_offline_shell_cache():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/dashboard.js'" in source
 
 
 def test_offline_review_next_ships_today_completion_atomically():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/today-completion.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
 
@@ -248,7 +248,7 @@ def test_offline_review_next_ships_today_completion_atomically():
 def test_duplicate_aware_capture_ships_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/create-issue-sheet.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
 
@@ -256,7 +256,7 @@ def test_duplicate_aware_capture_ships_in_a_new_offline_shell():
 def test_inline_checklist_step_flow_rolls_the_offline_shell_atomically():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/issue-sheet.js'" in source
     assert "BASE + 'static/checklist-conflict.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
@@ -266,14 +266,14 @@ def test_inline_checklist_step_flow_rolls_the_offline_shell_atomically():
 def test_exact_later_picker_ships_atomically_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/later-picker.js'" in source
 
 
 def test_navigation_deadline_ships_in_a_new_shell_cache():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/dashboard.css'" in source
     assert "BASE + 'static/dashboard.js'" in source
     assert "BASE + 'static/install-app.js'" in source
@@ -282,21 +282,21 @@ def test_navigation_deadline_ships_in_a_new_shell_cache():
 def test_today_convergence_ships_in_a_new_shell_cache():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/today-sync.js'" in source
 
 
 def test_mobile_search_viewport_ships_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/mobile-search-viewport.js'" in source
 
 
 def test_update_ownership_flow_ships_atomically_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/update-ownership.js'" in source
 
 
@@ -1302,7 +1302,7 @@ def test_one_session_bound_csrf_proof_is_reused_for_a_background_drain():
 def test_queue_today_ships_atomically_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/queue-today.js'" in source
 
 

tests/test_today_readiness.py

@@ -221,7 +221,7 @@ async def test_today_blocker_opens_existing_preview_and_preserves_readiness_gate
 def test_readiness_runtime_is_available_in_offline_shell():
     service_worker = SERVICE_WORKER.read_text()
 
-    assert "const CACHE = 'stackchain-dashboard-shell-v135';" in service_worker
+    assert "const CACHE = 'stackchain-dashboard-shell-v136';" in service_worker
     assert "BASE + 'static/today-readiness.js'" in service_worker
 
 

tests/test_today_sync.py

@@ -343,7 +343,7 @@ listeners['stackchain:first-task-complete']();
 def test_inflight_today_drain_ships_in_a_new_offline_shell():
     source = (Path(__file__).parents[1] / "frontend" / "service-worker.js").read_text()
 
-    assert "stackchain-dashboard-shell-v135" in source
+    assert "stackchain-dashboard-shell-v136" in source
     assert "BASE + 'static/today-sync.js'" in source