Repository navigation
docs: add design spec for background sessions - #15
Merged
Merged
Conversation
Terminal sessions are owned by TerminalActivity, so leaving the screen ends them and the Hermes gateway cannot run in the background. The spec moves sessions into an app-wide SessionManager (one per container) with a thin specialUse foreground service that keeps the process alive and owns the notification, an End session / Keep running / Cancel prompt on Back, a "Keep CPU awake" wake-lock toggle off by default, a "session ended" notification for sessions that end while away, and the error handling and tests. Baseline before this work: tag pre-background-sessions.
Android's Doze ignores wake locks and suspends network access for apps that are not exempt from battery optimization, and a foreground service does not change that (it only keeps the app out of App Standby). The spec implied the "Keep CPU awake" toggle alone keeps a session alive in deep sleep. It now separates screen-off CPU sleep (the wake lock) from Doze (the exemption), says the 24/7 gateway needs both, and the device checks expect the counter to pause in forced Doze without the exemption. Also from the review: each session's emulator runs on its own HandlerThread, since termlib builds a snapshot on its looper after every burst of output (verified early, main looper as fallback; scrollback is capped at 1000 lines); and a session is shown by at most one screen, so opening it again moves it to the new screen.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design for keeping terminal sessions running after leaving their screen, mainly so the Hermes gateway can run 24/7. Docs only; the implementation plan (
docs/plans/background-sessions.md) and the implementation follow in their own PR. Replaces the cancelled #13, now in the neutral layout from #14.Spec:
docs/design/background-sessions.md.android-apk-architecture.md(Follow-up Items, "Background sessions") points to it.Baseline before this work: tag
pre-background-sessions(main86d9e93).Decisions in the spec:
SessionManagerholds one session per container (PTY, emulator with the screen contents, reader thread that keeps draining output). A thin foreground service (specialUse;dataSyncis capped at 6 hours a day on Android 15) only keeps the process alive and owns the notification. Chosen over a bound service owning the sessions: same reliability, no started-and-bound service, session logic testable on the JVM.HandlerThread(termlib builds a snapshot on its looper after every output burst); a session is shown by at most one screen.SessionManagerthrough fake seams, the existing suites, adb lifecycle checks (forced Doze with and without the exemption), and the gateway answering from the host for 30 minutes in forced deep sleep with the exemption granted.The second commit corrects deep sleep after review (checked against Android's Doze and Android 15 behavior-change docs) and adds the emulator thread and one-screen rule.
Out of scope: several sessions per container, start at boot, restoring sessions after process death.