Continuity Hardening: stabilize cross-platform session continuity, background flows, and responsive runtime behavior

[insign]

Summary

Audit and harden the parts of CodeWalk that most directly affect continuity across mobile/desktop usage: background permission handling, session restore/reconnect behavior, terminal/composer coexistence on compact layouts, desktop tray continuity, cellular saver signaling, and web/runtime limitations.

This issue is about resilience and predictability, not new protocol surface area.

Why this exists

CodeWalk's value depends heavily on being able to move between active sessions, device states, and layout breakpoints without losing the thread. The repo already contains many specialized runtime surfaces, which is good, but it also means regressions can hide in platform-specific glue.

High-sensitivity areas include:

• permission auto-approve context on Android/background
• reconnect/restore/scroll ownership
• composer visibility while terminal is open on compact layouts
• desktop tray unread/attention behavior
• cellular data saver badge chain
• web SSE/cache limitations

Required references

• Resulting matrix from Contract Matrix: build OpenCode source-of-truth and capability inventory for CodeWalk #26
• Contract protections from Contract Tests: enforce ADR-023 and ADR-019 invariants in CI #27
• Relevant ADRs for scroll, PTY, continuity, permission auto-approve, and related behavior

Current repo evidence to inspect

• lib/presentation/services/permission_auto_approve_runtime.dart
• lib/presentation/services/android_background_alert_worker.dart
• lib/presentation/pages/chat_page/chat_page_scroll_coordinator.dart
• lib/presentation/pages/chat_page/chat_page_terminal_runtime.dart
• lib/presentation/widgets/codewalk_terminal_panel.dart
• lib/presentation/services/desktop_tray_service.dart
• lib/presentation/services/cellular_data_saver_service.dart
• lib/core/network/dio_sse_adapter.dart
• lib/core/network/dio_sse_adapter_stub.dart
• lib/data/cache/chat_cache_payload_store.dart
• lib/data/cache/chat_cache_payload_store_stub.dart

Scope

Part A — Android/background continuity

• Verify permission auto-approve context is correctly scoped and cleared
• Verify lifecycle transitions do not approve actions for the wrong session/thread
• Verify fallback behavior is explicit when background execution cannot complete safely

Part B — session restore / reconnect / scroll behavior

• Ensure reconnect and restore remain server-authoritative
• Add regression coverage where restore and scroll ownership are fragile

Part C — terminal/composer responsive behavior

• Audit compact/mobile behavior when terminal is opened, minimized, or closed
• Preserve draft state while avoiding UI collisions

Part D — desktop and web continuity helpers

• Audit tray behavior for unread/attention continuity
• Audit web limitations and make them explicit if reduced functionality is unavoidable

Part E — cellular saver coherence

• Ensure the badge/notice chain is consistent wherever the feature is surfaced

Deliverables

• Hardened lifecycle and continuity behavior across platforms
• Additional tests for high-risk transitions
• Any necessary explicit user-facing limitations for web/runtime edge cases
• Cleaner, more predictable runtime behavior on mobile and desktop

Acceptance criteria

• No cross-session permission approval leakage during lifecycle transitions.
• Restore/reconnect behavior remains stable and server-authoritative.
• Terminal/composer behavior on compact layouts is predictable and preserves drafts.
• Desktop tray behavior is coherent with unread/attention state.
• Cellular saver signals remain in sync across the documented surfaces.
• Any known web limitations are explicit rather than silent.

Non-goals

• No new protocol features.
• No large-scale visual redesign.
• No platform expansion.

Testing / validation

• Provider and service tests for lifecycle-sensitive logic
• Widget tests for compact layout terminal/composer behavior and saver indicators
• Manual validation on Android + desktop
• Run make check

Dependencies

• Depends on Contract Matrix: build OpenCode source-of-truth and capability inventory for CodeWalk #26.
• Strongly benefits from Contract Tests: enforce ADR-023 and ADR-019 invariants in CI #27.
• Coordinate with UX: replace aggressive offline state and streamline OpenCode onboarding/connection #28 where offline/recovery behavior overlaps.

Notes for the implementer

Do not rely on happy-path manual testing. Most of the value here comes from making awkward transitions boring and predictable.

[insign]

Implemented the continuity hardening pass for background permission scoping.

Delivered:

• explicit clearing of Android background auto-approve context before project-scope transitions
• explicit clearing of the previous server context during active server switches
• best-effort teardown clearing plus guarded server-switch flow so local scope changes continue even if the background clear call fails
• pure transition helper coverage and BEHAVIOR.md sync for the new scoping rule

Validation:

• make check
• reviewer loop completed; accepted fixes were applied until only non-actionable residual warnings remained

Audit note:

• terminal/composer compact behavior, reconnect/restore scroll ownership, and cellular saver surfaces were rechecked against existing ADR-backed behavior and current coverage during this pass; the remaining concrete hardening gap addressed here was the background permission-scope purge path.