Merge commit '40623991e8709e5c1ab3e875b51d4de55f0c20a5' into pipelines/run-20261112-0233-phone-bottom-tab-bar-2b54
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user