From 9629643a63c62c8da2c15f96e39a63ea1397e1d2 Mon Sep 17 00:00:00 2001
From: timmy <timmy@stackchain.ai>
Date: Tue, 11 Aug 2026 22:27:53 +0000
Subject: [PATCH] feat: pause Today while handling Attention (Closes #595)

---
 frontend/dashboard.css                    |  3 ++
 frontend/dashboard.js                     | 20 +++++++++
 frontend/index.html                       |  4 ++
 frontend/service-worker.js                |  2 +-
 frontend/today-timer.js                   | 43 +++++++++++++++++++-
 tests/test_comment_next.py                |  2 +-
 tests/test_frontend_bundle.py             |  2 +-
 tests/test_later_sync.py                  |  2 +-
 tests/test_markdown_renderer.py           |  2 +-
 tests/test_mobile_composer_integration.py |  2 +-
 tests/test_mobile_device_setup.py         |  2 +-
 tests/test_mobile_task_dock.py            | 15 +++++++
 tests/test_my_work.py                     | 49 +++++++++++++++++++++++
 tests/test_plan_today.py                  |  2 +-
 tests/test_service_worker.py              | 20 ++++-----
 tests/test_today_readiness.py             |  2 +-
 tests/test_today_sync.py                  |  2 +-
 17 files changed, 153 insertions(+), 21 deletions(-)

diff --git a/frontend/dashboard.css b/frontend/dashboard.css
index 4f14881..1353074 100644
--- a/frontend/dashboard.css
+++ b/frontend/dashboard.css
@@ -506,6 +506,8 @@ textarea { resize: vertical; min-height: 120px; }
 .mobile-task-action { min-width:0; min-height:44px; padding:6px 2px; border:0; border-radius:8px; background:transparent; display:grid; place-items:center; gap:2px; font-size:12px; }
 .mobile-task-action[aria-current="page"] { color:#bfdbfe; background:#17365a; outline:1px solid #31577f; }
 .mobile-task-count { min-width:18px; min-height:18px; padding:1px 5px; border-radius:999px; background:#31577f; font-size:11px; line-height:16px; }
+.attention-interruption:not([hidden]) { max-width:100%; display:flex; align-items:center; justify-content:space-between; gap:10px; margin:0 0 12px; padding:10px 12px; border:1px solid #31577f; border-radius:10px; background:#102641; }
+.attention-interruption button { min-height:44px; flex:0 0 auto; }
 @media (max-width: 600px) {
   body { padding-bottom:calc(66px + env(safe-area-inset-bottom)); }
   header { min-height:56px; max-height:64px; padding:6px 10px; align-items:center; gap:8px; background:rgba(11,21,38,.98); }
@@ -522,6 +524,7 @@ textarea { resize: vertical; min-height: 120px; }
   .device-setup-action { width:100%; }
   .device-readiness-card:not([hidden]) { display:grid; gap:12px; margin-left:max(0px,env(safe-area-inset-left)); margin-right:max(0px,env(safe-area-inset-right)); }
   .my-work { margin:0; }
+  .attention-interruption:not([hidden]) { position:sticky; top:64px; z-index:6; margin-inline:max(0px,env(safe-area-inset-left)) max(0px,env(safe-area-inset-right)); }
   .my-work-header { align-items:flex-start; }
   .my-work-actions { width:100%; flex-wrap:nowrap; }
   .my-work-actions button { min-height:44px; flex:1 1 0; padding-inline:6px; }
diff --git a/frontend/dashboard.js b/frontend/dashboard.js
index 98cf616..e89c158 100644
--- a/frontend/dashboard.js
+++ b/frontend/dashboard.js
@@ -44,12 +44,21 @@
     Array.from(document.querySelectorAll('[data-mobile-task]')).map(button => [button.dataset.mobileTask, button])
   );
   const mobileTaskOverlays = Array.from(document.querySelectorAll('[role="dialog"], #whiteboard-modal, #markdown-modal'));
+  const attentionInterruption = qs('#attention-interruption');
+  function renderAttentionInterruption() {
+    const pending = timer.attentionInterruption();
+    attentionInterruption.hidden = !pending;
+    return pending;
+  }
   function openMobileWorkFallback() {
     qs('[data-work-filter="all"]').click();
     qs('#my-work').scrollIntoView({block:'start'});
     qs('#my-work').focus();
   }
   function openMobileAttention() {
+    if (workSession.checkpointed()) timer.beginAttention();
+    renderAttentionInterruption();
+    timerView.render();
     qs('[data-work-filter="attention"]').click();
     qs('#my-work').scrollIntoView({block:'start'});
     qs('#my-work').focus();
@@ -941,6 +950,17 @@
     queryAll: s => document.querySelectorAll(s),
     formatEstimate: formatPlanMinutes,
   });
+  renderAttentionInterruption();
+  qs('#return-to-today').addEventListener('click', () => {
+    const returned = timer.returnFromAttention();
+    renderAttentionInterruption();
+    if (!returned) return;
+    selectTodayWork();
+    const item = todayMyWork.find(entry => todayWork.identity(entry) === returned.identity);
+    if (item) workSession.reopen(item);
+    else continueTodaySession();
+    timerView.render();
+  });
   const interruptionPrompt = createTodayInterruptionPrompt({
     timer,
     sheet: qs('#today-interruption-sheet'),
diff --git a/frontend/index.html b/frontend/index.html
index 59b9ade..bef97e7 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -147,6 +147,10 @@
         </div>
       </details>
     </div>
+    <aside class="attention-interruption" id="attention-interruption" role="status" aria-live="polite" hidden>
+      <span><strong>Today paused</strong> while handling Attention</span>
+      <button id="return-to-today" type="button">Return to Today</button>
+    </aside>
     <section class="device-readiness-card" id="device-readiness-card" aria-labelledby="device-readiness-heading" hidden>
       <div>
         <strong id="device-readiness-heading">Make this phone work-ready</strong>
diff --git a/frontend/service-worker.js b/frontend/service-worker.js
index 49eb777..886cb45 100644
--- a/frontend/service-worker.js
+++ b/frontend/service-worker.js
@@ -1,6 +1,6 @@
 const BASE = new URL('./', self.location.href).pathname;
 importScripts(BASE + 'static/background-issue-sync.js');
-const CACHE = 'stackchain-dashboard-shell-v90';
+const CACHE = 'stackchain-dashboard-shell-v91';
 const OFFLINE_LEASE_URL = new URL(BASE + '__offline-session-lease', self.location.origin).href;
 const OUTAGE_STATUSES = new Set([500, 502, 503, 504]);
 const NAVIGATION_TIMEOUT_MS = self.__STACKCHAIN_NAVIGATION_TIMEOUT_MS || 4000;
diff --git a/frontend/today-timer.js b/frontend/today-timer.js
index 7384714..faa7a1b 100644
--- a/frontend/today-timer.js
+++ b/frontend/today-timer.js
@@ -3,7 +3,10 @@ function createTodayTimer({ storage, getLogin, now = () => Date.now() }) {
     const login = String(getLogin?.() || '').trim().toLowerCase();
     return login ? 'stackchain.today-timer.v1.' + encodeURIComponent(login) : '';
   };
-  const empty = () => ({ version:1, active_identity:'', entries:{}, away_at:null, pending_interruption:null });
+  const empty = () => ({
+    version:1, active_identity:'', entries:{}, away_at:null,
+    pending_interruption:null, attention_interruption:null,
+  });
   const read = () => {
     const ownerKey = key();
     if (!ownerKey || !storage) return empty();
@@ -32,6 +35,12 @@ function createTodayTimer({ storage, getLogin, now = () => Date.now() }) {
       Number.isFinite(pending.away_ms) && pending.away_ms >= 0 ?
       { identity:pending.identity, away_ms:pending.away_ms } : null;
   };
+  const validAttention = state => {
+    const pending = state.attention_interruption;
+    return pending && typeof pending.identity === 'string' && pending.identity &&
+      typeof pending.resume === 'boolean' ?
+      { identity:pending.identity, resume:pending.resume } : null;
+  };
   const settle = (state, at = now()) => {
     const entry = state.entries[state.active_identity];
     if (!entry?.running) return state;
@@ -63,6 +72,7 @@ function createTodayTimer({ storage, getLogin, now = () => Date.now() }) {
       state.entries[identity] = entry;
       state.away_at = null;
       state.pending_interruption = null;
+      state.attention_interruption = null;
       return write(state);
     },
     pause() {
@@ -86,8 +96,39 @@ function createTodayTimer({ storage, getLogin, now = () => Date.now() }) {
       settle(state);
       state.away_at = null;
       state.pending_interruption = null;
+      state.attention_interruption = null;
       return write(state);
     },
+    beginAttention() {
+      const state = read();
+      const existing = validAttention(state);
+      if (existing) return existing;
+      const identity = state.active_identity;
+      const entry = state.entries[identity];
+      if (!identity || !entry) return null;
+      const resume = Boolean(entry.running);
+      if (resume) settle(state);
+      state.away_at = null;
+      state.attention_interruption = { identity, resume };
+      return write(state) ? { ...state.attention_interruption } : null;
+    },
+    attentionInterruption() {
+      return validAttention(read());
+    },
+    returnFromAttention() {
+      const state = read();
+      const pending = validAttention(state);
+      const entry = pending && state.entries[pending.identity];
+      if (!pending || !entry) return null;
+      state.active_identity = pending.identity;
+      if (pending.resume && !entry.running) {
+        entry.started_at = now();
+        entry.running = true;
+      }
+      state.attention_interruption = null;
+      state.away_at = null;
+      return write(state) ? { identity:pending.identity, resumed:pending.resume } : null;
+    },
     markAway() {
       const state = read();
       const entry = state.entries[state.active_identity];
diff --git a/tests/test_comment_next.py b/tests/test_comment_next.py
index 67a64fb..3abb887 100644
--- a/tests/test_comment_next.py
+++ b/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-v90" in worker
+    assert "stackchain-dashboard-shell-v91" in worker
diff --git a/tests/test_frontend_bundle.py b/tests/test_frontend_bundle.py
index 8e6ba01..cb390a6 100644
--- a/tests/test_frontend_bundle.py
+++ b/tests/test_frontend_bundle.py
@@ -162,7 +162,7 @@ def test_legacy_cache_marker_is_normalized_out_of_build_identity(tmp_path):
     worker = changed_frontend / "service-worker.js"
     worker.write_text(
         worker.read_text().replace(
-            "const CACHE = 'stackchain-dashboard-shell-v90';",
+            "const CACHE = 'stackchain-dashboard-shell-v91';",
             "const CACHE = 'stackchain-dashboard-shell-v999';",
         )
     )
diff --git a/tests/test_later_sync.py b/tests/test_later_sync.py
index dbdf62b..de248e2 100644
--- a/tests/test_later_sync.py
+++ b/tests/test_later_sync.py
@@ -347,5 +347,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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/later-sync.js'" in source
diff --git a/tests/test_markdown_renderer.py b/tests/test_markdown_renderer.py
index 06c8bbc..18fe994 100644
--- a/tests/test_markdown_renderer.py
+++ b/tests/test_markdown_renderer.py
@@ -137,4 +137,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-v90" in worker
+    assert "stackchain-dashboard-shell-v91" in worker
diff --git a/tests/test_mobile_composer_integration.py b/tests/test_mobile_composer_integration.py
index 3bbfe47..7a3c4a1 100644
--- a/tests/test_mobile_composer_integration.py
+++ b/tests/test_mobile_composer_integration.py
@@ -41,7 +41,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-v90" in worker
+    assert "stackchain-dashboard-shell-v91" in worker
 
 
 def test_all_conversation_composers_offer_accessible_mobile_mentions():
diff --git a/tests/test_mobile_device_setup.py b/tests/test_mobile_device_setup.py
index 9de2722..9d55062 100644
--- a/tests/test_mobile_device_setup.py
+++ b/tests/test_mobile_device_setup.py
@@ -186,7 +186,7 @@ def test_mobile_dashboard_mounts_phone_safe_device_setup_flow():
     assert "promptStorage:localStorage" in dashboard
     assert "pushControllerReady.then(ensureDeviceSetup)" in dashboard
     assert "BASE + 'static/mobile-device-setup.js'" in worker
-    assert "stackchain-dashboard-shell-v90" in worker
+    assert "stackchain-dashboard-shell-v91" in worker
     assert ".device-setup-panel" in css
     assert ".device-readiness-card" in css
     assert "overflow-x:hidden" in css
diff --git a/tests/test_mobile_task_dock.py b/tests/test_mobile_task_dock.py
index 0d0b78c..5dc6854 100644
--- a/tests/test_mobile_task_dock.py
+++ b/tests/test_mobile_task_dock.py
@@ -215,3 +215,18 @@ async def test_dashboard_renders_and_wires_phone_safe_task_dock():
     assert "draftCount.textContent = sourceDraftCount.textContent" in html
     assert "mobileTaskDock.updateWork(mobileWorkEntry.mode())" in html
     assert "mobileTaskDock.updateAttention(countMyWork(activeMyWork).attention)" in html
+
+
+@pytest.mark.anyio
+async def test_mobile_attention_pauses_today_and_offers_phone_safe_return():
+    html = await dashboard()
+
+    assert 'class="attention-interruption" id="attention-interruption"' in html
+    assert 'id="return-to-today" type="button">Return to Today</button>' in html
+    assert 'if (workSession.checkpointed()) timer.beginAttention();' in html
+    assert 'timer.returnFromAttention()' in html
+    assert "workSession.reopen(item)" in html
+    assert "attentionInterruption.hidden = !pending" in html
+    assert '.attention-interruption:not([hidden]) {' in html
+    assert '.attention-interruption button { min-height:44px;' in html
+    assert 'max-width:100%;' in html
diff --git a/tests/test_my_work.py b/tests/test_my_work.py
index 119e797..528be53 100644
--- a/tests/test_my_work.py
+++ b/tests/test_my_work.py
@@ -2050,6 +2050,55 @@ process.stdout.write(JSON.stringify({{
     }
 
 
+def test_today_timer_pauses_for_attention_and_restores_only_automatic_running_state():
+    script = f"""
+const createTodayTimer = require({json.dumps(str(TODAY_TIMER))});
+const values = new Map();
+const storage = {{getItem:k=>values.get(k)||null,setItem:(k,v)=>values.set(k,v)}};
+let login = 'timmy';
+let now = 0;
+const timer = createTodayTimer({{storage,getLogin:()=>login,now:()=>now}});
+timer.activate('issue:r:595:');
+now = 60000;
+const entered = timer.beginAttention();
+now = 5 * 60000;
+const duplicate = timer.beginAttention();
+const frozen = timer.snapshot();
+const restored = createTodayTimer({{storage,getLogin:()=>login,now:()=>now}}).attentionInterruption();
+now = 11 * 60000;
+const returned = timer.returnFromAttention();
+now = 12 * 60000;
+const resumed = timer.snapshot();
+timer.pause();
+now = 13 * 60000;
+const enteredPaused = timer.beginAttention();
+now = 20 * 60000;
+const returnedPaused = timer.returnFromAttention();
+const stillPaused = timer.snapshot();
+login = 'alexander';
+const isolated = timer.attentionInterruption();
+process.stdout.write(JSON.stringify({{
+  entered,duplicate,frozen,restored,returned,resumed,
+  enteredPaused,returnedPaused,stillPaused,isolated,
+}}));
+"""
+    result = subprocess.run(["node", "-e", script], capture_output=True, text=True)
+
+    assert result.returncode == 0, result.stderr
+    assert json.loads(result.stdout) == {
+        "entered": {"identity": "issue:r:595:", "resume": True},
+        "duplicate": {"identity": "issue:r:595:", "resume": True},
+        "frozen": {"identity": "issue:r:595:", "elapsed_ms": 60000, "running": False},
+        "restored": {"identity": "issue:r:595:", "resume": True},
+        "returned": {"identity": "issue:r:595:", "resumed": True},
+        "resumed": {"identity": "issue:r:595:", "elapsed_ms": 120000, "running": True},
+        "enteredPaused": {"identity": "issue:r:595:", "resume": False},
+        "returnedPaused": {"identity": "issue:r:595:", "resumed": False},
+        "stillPaused": {"identity": "issue:r:595:", "elapsed_ms": 120000, "running": False},
+        "isolated": None,
+    }
+
+
 def test_today_interruption_prompt_restores_and_resolves_the_pending_mobile_decision():
     script = f"""
 const createTodayTimer = require({json.dumps(str(TODAY_TIMER))});
diff --git a/tests/test_plan_today.py b/tests/test_plan_today.py
index 7549df9..ed85ee3 100644
--- a/tests/test_plan_today.py
+++ b/tests/test_plan_today.py
@@ -332,6 +332,6 @@ async def test_plan_today_wires_cancel_back_and_success_through_overlay_history(
 def test_plan_today_controller_is_available_in_the_offline_shell():
     source = SERVICE_WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/plan-today.js'" in source
     assert "BASE + 'static/plan-today-preview.js'" in source
diff --git a/tests/test_service_worker.py b/tests/test_service_worker.py
index 69d3829..b36a0f3 100644
--- a/tests/test_service_worker.py
+++ b/tests/test_service_worker.py
@@ -135,7 +135,7 @@ async function dispatchPush(payload) {{
 def test_resumable_today_session_ships_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/my-work.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
     assert "BASE + 'static/dashboard.css'" in source
@@ -144,14 +144,14 @@ def test_resumable_today_session_ships_in_a_new_offline_shell():
 def test_ownership_exit_runtime_rolls_the_offline_shell_cache():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v90" in source
+    assert "stackchain-dashboard-shell-v91" 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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/today-completion.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
 
@@ -159,7 +159,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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/create-issue-sheet.js'" in source
     assert "BASE + 'static/dashboard.js'" in source
 
@@ -167,14 +167,14 @@ def test_duplicate_aware_capture_ships_in_a_new_offline_shell():
 def test_exact_later_picker_ships_atomically_in_a_new_offline_shell():
     source = WORKER.read_text()
 
-    assert "stackchain-dashboard-shell-v90" in source
+    assert "stackchain-dashboard-shell-v91" 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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/dashboard.css'" in source
     assert "BASE + 'static/dashboard.js'" in source
     assert "BASE + 'static/install-app.js'" in source
@@ -183,21 +183,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-v90" in source
+    assert "stackchain-dashboard-shell-v91" 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-v90" in source
+    assert "stackchain-dashboard-shell-v91" 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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/update-ownership.js'" in source
 
 
@@ -638,7 +638,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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/queue-today.js'" in source
 
 
diff --git a/tests/test_today_readiness.py b/tests/test_today_readiness.py
index a11fa61..b99d0d7 100644
--- a/tests/test_today_readiness.py
+++ b/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-v90';" in service_worker
+    assert "const CACHE = 'stackchain-dashboard-shell-v91';" in service_worker
     assert "BASE + 'static/today-readiness.js'" in service_worker
 
 
diff --git a/tests/test_today_sync.py b/tests/test_today_sync.py
index 186163c..052dd39 100644
--- a/tests/test_today_sync.py
+++ b/tests/test_today_sync.py
@@ -127,7 +127,7 @@ sync.enqueueConfiguration(120, {{'issue:r:1:':60}});
 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-v90" in source
+    assert "stackchain-dashboard-shell-v91" in source
     assert "BASE + 'static/today-sync.js'" in source