Keep settings and delivery updates together

Preserve the reviewed grouped Settings page while fixing its embedded phone safe area, and land the accompanying notification, walkthrough, terminal, and documentation updates captured by this run.
This commit is contained in:
2026-11-12 03:27:37 +00:00
88 changed files with 3633 additions and 639 deletions
@@ -0,0 +1,91 @@
# Android background delivery: survive Doze, sign-in, battery, diagnosis
Stage 01-implement, run 20261112-0157. Source only; not committed, not installed.
## What changed
- **Reconnects are alarms, not handler delays.** `ReconnectAlarms` schedules
`setExactAndAllowWhileIdle` when `canScheduleExactAlarms()`, otherwise
`setAndAllowWhileIdle`. The alarm PendingIntent is a foreground-service intent
to `NotificationService` (`ACTION_RECONNECT`). The `Handler.postDelayed`
reconnect is gone.
- **Watchdog.** `NotificationWatchdog` (JobScheduler, periodic 15 min,
persisted) restarts the service when delivery is enabled and the socket is
down with no reconnect pending. It does not restart while signed out or
waiting for a network. Also scheduled by `NotificationService.start`.
- **Connect wake lock.** `ConnectWakeLock` holds a partial wake lock for 30 s
from `connect()` until the socket opens or fails.
- **Swipe away.** `onTaskRemoved` logs and queues a watchdog check 2 s later.
- **Battery exemption.** `SettingsDeviceDeliverySection` shows a persistent
warning row while delivery is on and the exemption is missing, with the
Samsung "Never sleeping apps" note. `setEnabled(true)` requests the
exemption before starting the service. Opening Settings with delivery already
on and the exemption missing asks once per open (`NotificationServiceController.open`);
resume refreshes never ask again.
- **HTTP 401/403.** The retry loop stops, status becomes `sign_in_required`,
and a "Sign in to Pipelines again to keep notifications" notice is posted
(channel `pipelines.account`, id 2). `configure` with a fresh cookie restarts
the service.
- **Connection log.** `ConnectionLog` keeps the last 50 events (time, event,
error, HTTP code) in the service preferences. The channel method
`connectionEvents` returns them. Settings shows them in an expandable
"Connection log" row.
## Files
- Kotlin (new): `ReconnectPolicy.kt`, `ReconnectAlarms.kt`,
`NotificationWatchdog.kt`, `ConnectWakeLock.kt`, `ConnectionLog.kt`
- Kotlin (changed): `NotificationService.kt`, `NotificationPresenter.kt`,
`NotificationServiceChannel.kt`, `ServiceSettings.kt`, `AndroidManifest.xml`
(WAKE_LOCK, SCHEDULE_EXACT_ALARM, watchdog service)
- Kotlin tests (new): `ConnectionLogTest.kt` (5), `ReconnectPolicyTest.kt` (3)
- Dart (new): `lib/features/notification_service/notification_service_events.dart`
- Dart (changed): `notification_service_bridge.dart`,
`notification_service_controller.dart`, `notification_service_status.dart`,
`lib/features/settings/settings_device_delivery_section.dart`
- Dart tests (changed): `test/features/settings/settings_device_delivery_section_test.dart`
(+8 cases), `test/features/notification_service/notification_service_bridge_test.dart`
(+3 cases), `test/features/notification_service/fake_notification_service.dart`
## Focused results
- Kotlin: `gradle :app:testDebugUnitTest --tests 'net.awan.pipelines_app.notify.*'`
BUILD SUCCESSFUL. 28 of 28 pass: ConnectionLogTest 5, ReconnectPolicyTest 3,
DeliveryLedgerTest 8, NotificationProtocolTest 12. Includes main-source compile.
- Flutter: `tool/memwatch/full.sh` on the four files below, PASS 35 passed,
0 failed (run twice, once after formatting):
- test/features/settings/settings_device_delivery_section_test.dart
- test/features/notification_service/notification_service_bridge_test.dart
- test/features/notification_service/notification_service_handoff_test.dart
- test/features/attention/notify/notification_delivery_test.dart
- `tool/analyze.sh`: clean (run twice).
## Affected UI states (for ui-review, not captured here)
- Delivery on, exemption missing: warning row visible with Samsung note.
- Delivery on, exemption granted: warning row gone; battery row says "Allowed".
- Delivery off: no battery row, no warning row.
- Status "Sign in to Pipelines again to keep notifications".
- Connection log collapsed, expanded with events, expanded empty
("No connection events yet"). Expansion needs an interactive check.
## Limitations and decisions
- **Not verified on a device.** Doze timing, alarm delivery, the
foreground-start exemption from alarms and the watchdog job, the swipe
restart, and the sign-in notice were not run. The Fold was not touched.
- **Exact alarms.** SCHEDULE_EXACT_ALARM is declared, but the app does not
send the user to grant it. Without the grant, reconnects use
idle-tolerant alarms.
- **Upgrade users are prompted when Settings opens, not at app start.** The
exemption is requested on switch-on, and on opening Settings while delivery
is on and the exemption is missing. The prompt is not fired from app start
because the section is the only place with the request context. A user who
declines is prompted again the next time Settings opens, then sees the
warning row. Users who never open Settings are not prompted.
- **JobScheduler is deferred in Doze**, so the watchdog is a backstop; the
alarms are the primary path.
- NotificationService.kt is 387 lines (aim is under 250; it was 293 before).
The reconnect alarms, watchdog, wake lock and log are in separate files,
but the socket state machine remains in the service; splitting it further is
a follow-up.
+49 -19
View File
@@ -30,14 +30,25 @@ every destination and come back at app start without Chat being opened.
terminal). On macOS Ctrl+Y in a terminal always goes to the shell.
- **Focus**: a window that shows or comes to the top puts the keyboard in its
composer; hiding the last window gives it back to what had it.
- **Cycle**: while a floating chat window's content holds the keyboard (a
composer, a Files page inside it), Ctrl+Tab brings the next visible chat
window to the top and Ctrl+Shift+Tab the previous one, wrapping round. The
order is the stacking order, bottom to top, and the window's composer takes
the keyboard. Command+Tab stays with the system. With the tiling focused,
Ctrl+Tab still cycles its panes; while the terminal claims tab keys (shown)
it switches terminal tabs. Alt+` (`windowCycleShortcut`) still cycles every
kind of window, not only chats.
- **Cycle**: Ctrl+Tab and Ctrl+Shift+Tab move between the chats the user can
see, and never bring up one that is not shown.
- **While any chat window is shown** (not minimised, its group shown), the
keys cycle those windows only, from wherever the keyboard is in Chat: a
window's composer, a Files page inside it, or the tiling (the chat list
included). From a window, the next (previous) shown window in open order
comes to the top, wrapping round. From the tiling, Ctrl+Tab takes the
top-most shown window to the top first. Either way the window's composer
takes the keyboard. Open order is the order the windows were opened (a
restored window keeps its saved place), so a raise does not change the
cycle; the stacking order does change on a raise.
- **With no chat window shown**, Ctrl+Tab cycles the tiled panes only and
the keys focus the chosen pane's composer. With one tiled pane it does
nothing. A chat shown before, or a minimised or floating chat, is never
swapped in.
- Command+Tab stays with the system. While the terminal claims tab keys
(shown) Ctrl+Tab switches terminal tabs. A keyboard held by another window
(a run, terminal) is left to that window. Alt+` (`windowCycleShortcut`)
still cycles every kind of window, not only chats.
- **Popups**: sheets, dialogs, menus and tooltips opened from a floating chat
are above every window. Files opens as a page inside the window, and a file
opened from it stays in the window. Because the window's own title bar names
@@ -69,17 +80,36 @@ every destination and come back at app start without Chat being opened.
## Checks
- Focused, 2026-11-12, `tool/memwatch/full.sh` with
`test/features/chat/chat_floating_pane_test.dart` and
`test/features/terminal/terminal_chat_tab_test.dart`: 16 passed, 0 failed.
New in the first: Ctrl+Tab and Ctrl+Shift+Tab over three floating chats
(order, wrap, composer focus, Command+Tab ignored); with the tiling focused
Ctrl+Tab moves the active pane and leaves the windows alone, and with one
window focused it does nothing; a terminal that claims tab keys keeps
Ctrl+Tab over a focused chat window.
- `tool/analyze.sh` on the changed paths: clean.
- Affected states: two or more floating chats; one floating chat; tiling
focused; a window focused with the terminal shown (claimed); Command+Tab.
- Focused, 2026-11-12, `tool/memwatch/full.sh` over
`test/features/chat/chat_floating_pane_test.dart`,
`test/features/chat/chat_keyboard_focus_test.dart`,
`test/features/chat/chat_control_tab_test.dart`,
`test/features/chat/windows/chat_windows_test.dart` and
`test/features/terminal/terminal_chat_tab_test.dart`: 38 passed, 0 failed.
Related Ctrl+Tab users, `tool/memwatch/full.sh` over
`test/shell/destination_shortcuts_test.dart`,
`test/shell/tab_history_back_test.dart`, `test/shell/search_escape_test.dart`
and `test/features/chat/shell/chat_shell_terminal_test.dart`: 26 passed,
0 failed.
- New in the first file: Ctrl+Tab and Ctrl+Shift+Tab over three floating chats
cycle in open order, not stacking order (order, wrap, composer focus,
Command+Tab ignored). With the tiling focused Ctrl+Tab goes to the top-most
shown window and leaves the panes alone; with one shown window it does
nothing; with the window minimised the panes cycle and the window stays
hidden. With one tiled pane and a minimised chat, Ctrl+Tab does nothing and
shows nothing. A terminal that claims tab keys keeps Ctrl+Tab over a focused
chat window.
- Removed: the single-pane recent-chat swap (the chat shown before, opened
back into the pane), with its tests in `chat_keyboard_focus_test.dart`. A
single pane with no shown window now does nothing on Ctrl+Tab, so
`chat_control_tab_test.dart` no longer expects the composer to take focus
from the sidebar.
- `tool/analyze.sh` on `lib/features/chat` and the three chat test files:
clean.
- Affected states: two or more floating chats; one floating chat shown;
floating chat minimised with one tiled pane; tiling focused with windows
shown and with none; a window focused; the terminal shown (claimed);
Command+Tab.
- Not covered: the terminal's own tab switching (the test app has no terminal
surface), real browser or device keys, and captures (ui-review's).
- Observed, not changed: in the widget harness, floating from a pane's More
+76
View File
@@ -0,0 +1,76 @@
# Chat terminal buttons (narrow duplicate, bar styling)
## Findings (from the code and the ui-review captures)
- The terminal toggle is the shell's bar action, passed as `barActions` from
`application/pipelines_app.dart` on the Chat tab. The shell draws that bar
only where it is not covered:
- Wide (>= 600, `kListDetailMinWidth`): the shell bar sits over the list
column while a chat is open, so the terminal shows there beside New chat
and Refresh (capture: `Terminal (Option+T)` at x 287). The chat's own bar
holds only Files and More.
- Narrow (< 600): the open chat is a pushed page with its own bar
(`ShellBar(barless: true)`), which covers the shell bar. A shell-bar
terminal button therefore never shows on a phone chat, even though it was
listed in `barActions`. This is why the first attempt (keeping it in
`barActions` for an open chat) rendered nothing on phone.
- Narrow chat list: the shell bar shows the toggle beside New chat and
Refresh (the duplicate this change removes).
- The styling difference: `TerminalToggleButton` passed `isSelected: shown`,
which tints the icon while the terminal is shown. Files and More
(`ChatBarAction`, `SegmentedMoreButton`) are plain IconButtons with no
selected state.
## Changes
- `lib/application/app_terminals.dart`: `barToggle(context)` returns the shell
toggle only on a wide layout; null on narrow (chat list and open chat).
- `lib/application/pipelines_app.dart`: the Chat tab's `barActions` uses
`?_terminals.barToggle(context)`.
- `lib/features/terminal/terminal_open_action.dart`: new
`terminalChatBarAction(context)`: on narrow, with a terminal surface, a
`ChatBarAction` (the same widget as Files) that toggles the terminal
(identifier `chat-terminal-toggle`). Null on wide or without a surface.
- `lib/features/chat/conversation/chat_thread_view.dart`: the chat header's
actions are Files followed by `?terminalChatBarAction(context)`, so a
narrow open chat shows the terminal beside Files.
- `lib/features/terminal/terminal_toggle_button.dart`: drops `isSelected`; the
shown state is exposed as `Semantics(toggled:)` only.
## Tests
- `test/application/app_terminals_test.dart`: wide 1000 px offers the shell
toggle; narrow 390 px offers none.
- `test/features/terminal/terminal_chat_bar_action_test.dart`, light and dark:
phone 390 px: the chat bar's terminal button is present, the same size as
Files, the same icon colour, not selected, and tapping it toggles the
terminal; wide 1000 px and no terminal surface: no chat-bar terminal button.
- `test/features/terminal/terminal_toggle_button_test.dart`, light and dark:
the shell's terminal button has no `isSelected`, its icon colour equals
Files' in hidden and shown states, both are 48 px, and the shown state is
announced as toggled.
- Affected users re-run: `terminal_first_open_test.dart`,
`terminal_surface_test.dart`, `chat_floating_chrome_test.dart`,
`chat_floating_pane_test.dart`.
## Focused results
`tool/memwatch/full.sh` with the seven paths above as one argument:
57 passed, 0 failed (peak 1877 MB, 53 s; verdict names only those paths).
`tool/analyze.sh`: clean.
## Expected states (from the code; not captured here)
- Phone chat list: no terminal in the bar; the shortcut bubble remains.
- Phone open chat: the chat bar reads Files, terminal, More; the terminal is
the same 48 px plain IconButton style as Files.
- Wide chat list and wide open chat: placement unchanged; the shell bar's
terminal button is plain (no selected tint).
## Not verified here
- Rendered states at phone and desktop sizes, light and dark, and hover and
pressed states: not captured (ui-review owns captures).
- `pipelines_app.dart` wiring has no direct test.
`test/application/pipelines_app_test.dart` fails on untouched main (pending
launch-update timer), so it was not run.
+117
View File
@@ -0,0 +1,117 @@
# First-run walkthrough
A short, skippable four-page walkthrough for new users of the Flutter app.
## What it does
- Shows once per device on first launch, from the Pipelines page.
- Is also offered once per server when the device has already seen it and the
connected server has no pipelines, runs or chats yet (the server is checked
with `list_pipelines`, `list_runs` and `chat_sessions`; an unreadable server
never triggers it).
- Pages: 1) what Pipelines is and how to connect to the server; 2) set up an
agent harness, with an agent picker and one copy button for
`pipelines harness setup <agent>` (`claude`, `codex`, `opencode`, `pi`);
3) the Pipelines and Runs tabs and how to start a run; 4) the Chat tab, float
and terminal.
- Every page has Skip; Back and Next move between pages; Done ends on the last.
- Closing by any route (Skip, Done, the close gesture, a tap outside) records the
device as seen.
- Settings reopens it from Tools → Help → "Show the walkthrough". Reopening
does not change the seen record.
## Where it lives
- `lib/features/walkthrough/`
- `walkthrough_store.dart`: the seen/offered records (`pipelines.next.*` keys;
a store that cannot be read reports "seen", so it never nags).
- `walkthrough_steps.dart`: the page copy and agent list (pure data).
- `first_run_walkthrough.dart`: the stepper and `showFirstRunWalkthrough`
(a Material bottom sheet on phones, a dialog on wide windows, via
`showAppDetails`).
- `walkthrough_harness_command.dart`: agent chips, the command and copy.
- `walkthrough_gate.dart`: the first-launch and empty-server check.
- `lib/application/pipelines_app.dart`: wraps the Pipelines destination body in
the gate (the Pipelines tab is the first screen).
- `lib/features/settings/settings_walkthrough_section.dart`: one row in the
Tools → Help group, plus `SettingsKeys.walkthrough`.
## Focused tests
- `test/features/walkthrough/walkthrough_gate_test.dart`: first launch shows
once; Done and Skip persist; a seen device on an empty server is offered once;
a seen device that starts disconnected makes no server call and is offered
after it connects; an unreadable check is retried on the next connection (and
a repeated notification while connected does not re-query); a server with
work, an unreadable server, a hidden Pipelines page, and an unavailable store
all stay quiet; hiding the Pipelines page while the first-launch read is
still pending keeps the walkthrough closed, and showing it again offers it
once.
- `test/features/walkthrough/first_run_walkthrough_test.dart`: phone bottom
sheet and wide dialog; Back disabled on page 1; four pages with Done on the
last and Skip throughout; the harness picker and copy; large text (2x) and
dark mode without overflow.
- `test/features/settings/settings_walkthrough_test.dart`: the Settings row
reopens the walkthrough on page 1.
## Results
- Focused run: `tool/memwatch/full.sh 'test/features/walkthrough/first_run_walkthrough_test.dart test/features/walkthrough/walkthrough_gate_test.dart test/features/settings/settings_walkthrough_test.dart'`
→ PASS, 20 passed, 0 failed, peak 1031 MB, 16 s. The verdict named only these
three paths.
- Visibility fix (review must-fix, visit 2): the gate offered without checking
`enabled`, so a walkthrough could open over another destination if Pipelines
was hidden before the post-frame callback or during a pending read. The gate
now checks `mounted && enabled` in the callback, after each await, and before
each show. A skipped callback clears the in-flight flag, so re-enabling
Pipelines reschedules the offer. Covered by the new gate test
"hiding Pipelines while an offer is pending keeps the walkthrough closed".
That test was not run against the pre-fix code, so the failing-before claim
is by reasoning only.
- Lifecycle fix (review must-fix): the empty-server check used to run once
right after the first frame, before the session connected. A seen device
then got a `NotConnectedError`, and the check was never retried. The gate now
takes the session as its connection source (`connection` + `connected`), waits
while disconnected, re-runs on each new connection until the server answers,
and stays quiet on a repeated notification while connected. A connection that
arrives between frames requests a visual update, so the post-frame callback
runs. The fix is covered by the two new gate tests above.
- Two earlier runs failed and were fixed in the test code, not by weakening
expectations: the large-text test tapped Next before scrolling it into view,
and the "unavailable store" test awaited the real preferences plugin inside
`testWidgets` and hung. The store now takes an injectable opener, so that case
is a plain test with a null opener.
- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos).
- Not run here: `pipelines_app_test`, the Settings screen suites and the other
Pipelines suites. They belong to the land gate.
## Affected states (checked by focused tests only; nothing captured)
- Phone (390×844): bottom sheet; page 1 with Back disabled; all four pages;
Skip mid-walkthrough.
- Wide (1280×900): dialog; Next reaches page 2.
- Harness page: four agent chips; the command follows the selected agent; copy
copies the selected command and the button shows a check.
- Large text (2×) on a 360×740 phone and dark mode: every page builds with no
exception.
- Gate: first launch once; Done and Skip persist; a seen device on an empty
server is offered once per server; a server with runs, an unreadable server,
a hidden Pipelines page and an unavailable store stay quiet.
- Settings: "Show the walkthrough" reopens page 1 and does not change the seen
record.
Nothing was built, run on a device or captured. `ui-review` owns the rendered
review.
## Limitations
- The gate is tested in isolation with fake stores and gateways. The Pipelines
wiring in `pipelines_app.dart` is not covered by a focused test.
- Narrow window: the empty-server offer marks the server as offered before it
shows. If Pipelines is hidden during that one store write, the server is
consumed without the walkthrough appearing. Fixing it needs the store write
to move to the dialog's close, which changes when the offer is recorded.
- On phones the walkthrough is a Material bottom sheet, not a full page.
- The harness command is shown as a picker with one copy button for the
selected agent, not four separate copy buttons.
- The "Show the walkthrough" test covers the row, not the whole Settings tree.
+74
View File
@@ -96,3 +96,77 @@ section with error and Retry.
- Not on-device verified.
- The "Check for updates" action walks the servers sequentially when pressed. That
is a user action, not the page load, and was left unchanged.
## Re-entry after land: main moved (merge of main)
Main changed the Settings files this branch rewrote, so the merge conflicted in
`settings_keys.dart`, `settings_screen.dart` and `settings_topic_pages.dart`.
Resolution (merge staged, not committed):
- `settings_topic_pages.dart` stays deleted. Its main-side change added a
walkthrough row to the old tab layout; this page already has the row.
- `settings_keys.dart` keeps `SettingsKeys.showWalkthrough` only; main's
`SettingsKeys.walkthrough` is dropped.
- `settings_screen.dart` keeps this branch's imports; main's
`settings_walkthrough_section.dart` import is dropped.
- `settings_walkthrough_section.dart` and its test
`test/features/settings/settings_walkthrough_test.dart` (main's, for the removed
tab row) are deleted. The reopen behaviour stays covered by the Help and about
row test in `settings_screen_test.dart`.
- `pipelines_app.dart` now passes `onShowWalkthrough` to Settings, calling
`showFirstRunWalkthrough(context)`. Before this, the row was disabled in the
app because nothing supplied the handler. The settings route builder now names
its parameter `context`.
- Main's device-delivery changes (warning, connection log, `open()`) merged
cleanly and are kept.
Focused results (memwatch, from app/):
- Passing: settings_screen_test, settings_device_delivery_section_test,
settings_search_page_test, settings_layout_test, settings_library_test,
settings_server_load_test, first_run_walkthrough_test, walkthrough_gate_test.
- Failing: `test/application/settings_page_test.dart` (2 tests: the bar gear
case and the rail case) and `test/application/settings_registration_test.dart`
(1 test). The same tests fail on untouched main, and the pre-merge branch
commit passes them. Likely cause: main's Pipelines bar now includes the
terminal toggle (`pipelines_app.dart` `_shellFor`), which pushes out the
`pipelines-open-settings` gear. Not fixed here; these tests need a decision on
the gear.
- `settings_tabs_test.dart` and `settings_topic_restore_test.dart` do not exist
on this branch; they are stale names in the change list.
`tool/analyze.sh`: clean.
Not on-device verified; no UI captured in this stage.
## Re-entry after ui-review: phone bar over the page
ui-review (visit 2) captured the phone page panned under the shell's floating tab
bar. The bar's glass let the Terminal help text and its controls show through the
bar, so they could not be read.
Cause: the shell's `Scaffold` uses `extendBody`, so the page's body reads the bar's
height as its bottom padding. The page padded only its scroll end, so rows scrolled
under the bar.
Fix (`settings_screen.dart`, embedded branch): the page's viewport now ends at the
bar's top edge. It reserves the body's bottom padding (the bar's height, or the
system inset when no bar shows) and removes that padding from its subtree, so the
page's own end padding is not counted twice. The non-embedded (own Scaffold) branch
is unchanged. On a wide window the bar is in the rail, so the reserved space is zero.
New regression test: `settings_screen_test.dart`, "phone: the page scrolls to rest
above the floating tab bar". It pumps the page in a `Scaffold(extendBody: true)` with
an 80 px bottom bar at 390×844, scrolls to the end, and asserts the list viewport and
the last row (the walkthrough row) end above the bar. It was confirmed to fail on the
previous embedded layout and to pass with this fix.
Focused results (memwatch, from app/, same path list as above, plus the new test):
- 49 passed, 3 failed. The 3 failures are the known application tests from the
land stage: `settings_page_test.dart` (390 and 1200 cases) and
`settings_registration_test.dart`. They fail at a tap on `segmented.more` and a
route check before reaching this layout. Not changed here.
- `tool/analyze.sh` on the settings lib/test paths and the two application tests: clean.
Affected states to re-capture (ui-review owns this): phone light and dark, panned to
the end of the page (the walkthrough row and Terminal help text must sit above the
bar); desktop, where the bar is in the rail and nothing changes.
Not on-device verified; no UI was built or captured in this stage.