Let the phone replace itself, and give CI a channel it may sign

The Android head had no updater and no release path, and the two are one problem:
Android refuses an update signed by a different key, and CI generates a fresh debug
key in every container. An APK released from a workflow could be installed once and
never updated again — each new one an uninstall, which on this product means losing
the cache, the outbox and the device key.

So there are two channels, and they are two applications because the platform gives
no third option. dev.dodotech.dodossh is cut from a v* tag by a person running
scripts/release-android.ps1 with the key ADR 0011 rule 1 keeps off runners.
dev.dodotech.dodossh.nightly is cut from main by CI and signed with a keystore
committed here in the open — a key everybody has cannot be stolen and grants nothing
by being held, which is why putting it in CI does not touch the rule. Neither can
update the other, by construction. See ADR 0014.

The android job assumed an image with a JDK and an Android SDK on it, which is what
a GitHub runner is and what this project's is not. It now installs a JDK, fetches
Google's command-line tools, accepts the licences and installs API 36 — each a no-op
where it is already satisfied, and each cached by the persistent runner's own disk
rather than by an action that would move a quarter of a gigabyte to rebuild a
directory that never left.

The client reads a small JSON manifest beside the APK, the counterpart of
releases.win.json, and compares Android's versionCode rather than a version name:
that integer is what the platform itself uses to accept or refuse an install, so
comparing anything else would offer updates the phone then rejects. It fetches, and
then asks Android to ask — the system draws its own confirmation, and from API 26
will not draw even that until unknown sources is on for this application.

IUpdateChannel gained ApplyingEndsTheProcess. On Windows applying replaces the files
and restarts, so the shell disposes the vault first and that is what zeroes the keys.
On the phone the install is a request and the answer may be no, so disposing first
would answer "not now" with a locked keychain and every shell closed — a punishment
for declining an update.

Two measured bugs found on the way, both older than this work and both invisible to
a -getProperty check. ApplicationDisplayVersion is read by the Android targets in a
top-level PropertyGroup, so the target setting it from MinVer ran after the only
thing that reads it: every APK ever built here said versionName 1.0.0. And nothing
found so far varies the launcher name per channel — four mechanisms tried, all of
them recorded in platform-flags, none of them reaching the label the launcher shows.
The two channels share an icon name for now and are told apart by package name,
version, and what the preferences screen says.

docs/adr/0014-android-updates.md

@@ -0,0 +1,119 @@
+# ADR 0014 — Updating the Android client, and the two channels that makes necessary
+
+- Status: accepted
+- Date: 2026-08-04
+- Builds on: [ADR 0011](0011-android-distribution.md), [ADR 0013](0013-desktop-distribution-and-updates.md)
+- Amends: ADR 0011's consequence that there is "no automatic update"
+
+## Context
+
+[ADR 0011](0011-android-distribution.md) settled who holds the Android release key and listed the price
+of shipping outside a store: *"There is no discovery, no automatic update, and no Play channel."* It
+also left the door open in rule 2 — *"If an update check is ever added it points at the project's
+domain"* — and named the missing update path as **the sharpest edge of the decision** for a product sold
+to teams.
+
+[ADR 0013](0013-desktop-distribution-and-updates.md) then built exactly that for Windows, and the
+argument it turns on applies here word for word: an SSH client holding a team's infrastructure
+credentials is precisely the software where *"the fix shipped and the user never got it"* is a security
+outcome rather than an inconvenience.
+
+So the question is not whether the phone should update itself. It is how, given one Android fact that
+decides everything else:
+
+**An installed app can only be updated by a package signed with the same key.** Not "should not" —
+Android refuses, with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`. A key is an app's identity for its whole
+life.
+
+That collides with ADR 0011 rule 1, which puts the release key on a machine that is not a runner. CI can
+build an APK; what it cannot do is sign one that any installed copy will accept, because the debug key it
+falls back to is generated fresh in every container. An APK released from CI today could be installed
+once and never updated again — and each "update" would require an uninstall, which on this product means
+losing the local cache, the outbox and the device key.
+
+## Decision
+
+**Two channels, which are two applications, because Android has no third option.**
+
+1. **`release` — `dev.dodotech.dodossh`, signed by the key ADR 0011 rule 1 describes.** Cut from a `v*`
+   tag by a person running `scripts/release-android.ps1` on a machine that is not a runner. No workflow
+   touches it, no secret exists for it, and CI has no job that could. ADR 0011 rule 1 is unchanged, and
+   its "Rejected" entry — *a release key held by CI so tagging cuts a release* — still stands.
+
+2. **`nightly` — `dev.dodotech.dodossh.nightly`, signed by a keystore committed to this repository in the
+   open.** Cut from `main` by CI on every push, published as a pre-release on the project's own forge.
+
+   **The key is public on purpose, and that is what makes it safe to put in CI.** ADR 0011 rule 1 exists
+   because a key a workflow can reach is a key held by everyone who can change a workflow file. A key
+   everybody already has cannot be stolen, needs no secret to configure, and grants nothing by being
+   held — so the rule has nothing to protect. It also means this channel works on a fresh runner with no
+   setup, which is the practical reason it was reachable at all.
+
+3. **Neither channel can update the other, by construction rather than by care.** Different package ids
+   and different keys, so a mistake is an install Android refuses rather than a nightly quietly replacing
+   somebody's real client. Both can be installed at once, which is the useful half: testing a nightly
+   costs nobody the build they rely on.
+
+4. **The update check reads the project's forge and never the deployment**, which is ADR 0011 rule 2
+   applied unchanged. The feed address is a `const` in `AndroidUpdateChannel` and there is deliberately
+   no setting for it — a configurable update URL is exactly the knob that would let an operator, or a
+   stray edit to a plaintext file, point the update path at the party ADR 0001 models as the adversary.
+
+5. **The comparison is Android's `versionCode` and not the version name.** That integer is what the
+   platform itself uses to accept or refuse an install, so comparing anything else would let the client
+   offer an update the platform then rejects. The feed publishes it in a small JSON manifest beside the
+   APK — the counterpart of `releases.win.json` — so a check costs a few hundred bytes rather than a
+   download.
+
+6. **Nothing is installed by the application.** It fetches, then asks Android to ask. The platform draws
+   its own confirmation naming the package, and from API 26 will not draw even that until the user has
+   turned this application on in the unknown-sources screen. Two deliberate answers, neither to a screen
+   DodoSSH controls.
+
+7. **Applying does not end the process, and the shell had to learn that.** On Windows, applying replaces
+   the files and restarts, so the shell disposes the vault first — that is what zeroes the identity keys,
+   the vault keys and the cache key. On Android the install is a *request* and the answer may be no, so
+   disposing first would answer "not now" with a locked keychain and every shell closed. `IUpdateChannel`
+   gained `ApplyingEndsTheProcess`; where it is false the session is left alone, and the keys go when
+   Android kills the process on the install it agreed to.
+
+## Consequences
+
+**The nightly channel is a real attack surface and should be described as one.** Anyone can build an APK
+a nightly phone will accept, because the key is public. Reaching one still means being what it fetches
+from — a release on `git.dodotech.cloud` over TLS — so the practical set is *whoever can write a release
+on this repository*, which is the same set ADR 0013 names for the desktop. That is acceptable for a
+channel whose users are testing it and is not acceptable for the one holding people's credentials, which
+is the entire reason there are two.
+
+**A nightly is not a beta of the release channel; it is a different application.** Moving from one to the
+other is an uninstall and a fresh enrolment. There is no migration and there will not be one — the two
+caches are encrypted under keys held by two package identities the platform keeps apart.
+
+**ADR 0011's "no automatic update" consequence is now wrong for the release channel and remains true for
+reach.** Discovery, MDM deployment and the sideloading permission are all unchanged. What changed is only
+that an installed copy can now learn a newer one exists.
+
+**The release channel's `versionCode` stays a hand-bumped literal**, and forgetting to bump it is caught
+rather than shipped: the release script reads what is already published and refuses to build a package
+that does not beat it.
+
+**Two identical launcher icons.** A nightly installed beside a release shows the same name under both.
+Four ways to vary it per channel were tried and none reached the launcher label; the findings are in
+`docs/platform-flags.md`. What tells them apart today is the package name in Android's app info, the
+version, and the channel the application names on its own preferences screen.
+
+## Rejected
+
+- **A release keystore in CI so tagging cuts the real release.** The convenience is the point of CI and
+  the key is the point of ADR 0011; where they collide the key wins. This ADR is what makes that refusal
+  survivable rather than merely principled — the nightly channel is where the convenience went.
+- **One channel, released from CI, signed with a stable key held as a secret.** This is the arrangement
+  most projects land on and it is ADR 0011's rejected entry with an extra step: the secret is reachable
+  by whoever can change a workflow file, and what it signs is the client holding the credentials.
+- **Opening the release page in a browser instead of installing.** It would work, and it moves the same
+  APK through the same unknown-sources gate with one more step and no less trust. What it gives up is any
+  way of knowing a fix has been fetched, which is the property this ADR exists to buy.
+- **A version-name comparison, so the feed could be a directory listing.** SemVer with prerelease heights
+  needs a parser, and the parser would disagree with the platform sooner or later. The number Android
+  uses is the number to compare.

docs/manual-checks.md

@@ -1811,3 +1811,95 @@ is wrong. Reinstalling then asks for the passphrase rather than for a server.
 **Failure means:** the cache going with the application is the pack-id collision, and whoever ran this has
 lost their offline unlock and any change that was still in the outbox. That is the failure ADR 0013
 decision 2 exists to prevent, and it is why 16.1 checks the same thing from the other end.
+
+---
+
+## Phase 17 — Installing and updating the phone
+
+Every check here needs a real Android device or emulator. Nothing about this is automated and structurally
+cannot be for the reason phase 8 gives, with one more on top: the install is another application's screen.
+
+Two channels, and they are two applications — see [ADR 0014](adr/0014-android-updates.md). The nightly is
+what CI publishes on every push to main and is signed with a key that is in this repository; the release
+channel is cut by `scripts/release-android.ps1` on a machine holding the real key. Most of these checks can
+be walked on the nightly, which is the point of having one.
+
+### 17.1 The unknown-sources gate is asked for and not assumed
+
+On a phone that has never installed a DodoSSH APK, download one from the release page and open it.
+
+**Pass:** Android says the browser is not allowed to install unknown apps and offers the settings screen.
+Granting it there and returning completes the install.
+
+**Failure means:** nothing — this is the platform working, and it is the cost ADR 0011 names. It is a check
+because the *next* one depends on somebody having been through it.
+
+### 17.2 Both channels install side by side
+
+Install a nightly on a phone that already has a release build, or the other way round.
+
+**Pass:** two applications, two icons, both openable, each with its own keychain. Android's app info shows
+`dev.dodotech.dodossh` for one and `dev.dodotech.dodossh.nightly` for the other.
+
+**Failure means:** if the second install replaces the first, the two channels are sharing a package id and
+the separation ADR 0014 rests on is not there. If it is *refused*, they share an id and differ in key,
+which is the same fault seen from the other side.
+
+Both icons say DodoSSH, which is a known defect rather than a surprise — see `docs/platform-flags.md`.
+
+### 17.3 The version on screen is the version that was built
+
+Settings → Preferences → UPDATES.
+
+**Pass:** a version matching the tag it was built from, or on a nightly the full MinVer string with its
+height. Never `1.0.0`.
+
+**Failure means:** `1.0.0` is the `_AndroidVersionName` fix having come undone; see platform-flags.
+
+### 17.4 A check that finds nothing says so, and one on a timer does not
+
+Press CHECK NOW on the newest build there is.
+
+**Pass:** it answers — "DodoSSH x.y.z is the latest build." Then leave the app open and do nothing for
+several minutes.
+
+**Pass:** no message appears on its own. A background pass that found nothing is silent, which is what makes
+the feature tolerable.
+
+### 17.5 An update is found, fetched without being asked, and installed only when asked · **the whole point**
+
+With an older build installed, publish or wait for a newer one on the same channel, then press CHECK NOW.
+
+**Pass:** the bar moves, then an INSTALL button and a line saying what it costs. **Nothing is installed
+yet.** Leave it sitting there and confirm the application still works normally.
+
+Press INSTALL.
+
+**Pass:** Android's own installer appears naming the package. Agreeing replaces the app and it reopens as
+the new version, still enrolled, with the vault and its hosts intact.
+
+**Failure means:** an install that happens without INSTALL being pressed is the policy this feature is built
+around being broken. An `INSTALL_FAILED_UPDATE_INCOMPATIBLE` means the two builds were signed by different
+keys — on the nightly channel that means the committed keystore changed, and on the release channel it means
+the wrong keystore was used.
+
+### 17.6 Declining leaves a working session · **the one that would be missed**
+
+Repeat 17.5 to the point where Android's installer is on screen, with a terminal open and the vault
+unlocked. Press back or cancel.
+
+**Pass:** DodoSSH is still running, still unlocked, and the shell is still connected.
+
+**Failure means:** a locked keychain or a dead session is the shell having disposed itself before asking —
+`IUpdateChannel.ApplyingEndsTheProcess` not being read, or answering true on this head. It punishes somebody
+for declining an update, and nothing in an automated suite would notice.
+
+### 17.7 A nightly cannot update a release build
+
+With a release build installed, download the nightly APK and try to install it *over* it — rename it if the
+package manager will not offer to.
+
+**Pass:** refused, or installed as a second application. Never a replacement.
+
+**Failure means:** the channels are not separate, and a public key is signing the application people keep
+their credentials in.

docs/platform-flags.md

@@ -616,3 +616,29 @@ surface — but it is still an unmetered write path.
 **`/api/v1/me` does not update `last_seen_at_utc`.** Deliberate: a GET that writes on every call is
 a smell, and nothing depends on the value yet. Revisit when device management lands, since that is
 the first feature that needs it.
+
+**`ApplicationDisplayVersion` cannot be set from a target, so the Android head shipped `1.0.0`.**
+`Xamarin.Android.Common.targets` reads it in a plain top-level `PropertyGroup` —
+`<_AndroidVersionName>$(ApplicationDisplayVersion)</_AndroidVersionName>` — which is *evaluation*, not a
+target. Every project property is already final before any target runs, so the MinVer-derived value set in
+`UseTheDerivedVersionForAndroid` was assigned after the only thing that reads it had finished. MinVer cannot
+run at evaluation time, so no arrangement of the public property works. The tell is that
+`-getProperty:ApplicationDisplayVersion` answers correctly while `aapt2 dump badging` on the packaged APK
+says `versionName='1.0.0'` — measured, and the reason a `-getProperty` check cannot catch this class of bug.
+The fix is to assign `_AndroidVersionName` from a target hooked `BeforeTargets="_GenerateJavaStubs"`; an
+internal name, taken deliberately over passing `-p:ApplicationDisplayVersion` from every caller and leaving
+an ordinary `dotnet build` lying about its version.
+
+**Nothing found so far varies the Android launcher name per build.** Four mechanisms were tried and all
+four produce the same label. `AndroidManifestPlaceholders` is wired to the manifest task and does not reach
+`android:label` — measured on a build whose placeholder property evaluated to `appLabel=DodoSSH nightly`
+and whose APK reported `DodoSSH`. `ApplicationTitle`, the documented property, feeds an `ApplicationLabel`
+task parameter that the label already on the application element wins against. A second resource directory
+under `Resources/` is picked up by the SDK's own glob as a *qualifier* and fails the build outright with
+`APT2142: invalid configuration 'nightly'`. And an `AndroidResource` `Remove`/`Include` swap does nothing
+from the project body — the SDK's glob is added by `Sdk.targets`, imported below it, so the removal runs
+before the item exists — while the same swap inside a target that runs before `UpdateAndroidResources` also
+had no effect. Underneath all of it: the launcher shows the *activity's* label, and that one is a string in
+a C# attribute. The two channels ADR 0014 defines therefore share a launcher name, and are told apart by
+the package name in Android's app info, by the version, and by the channel the application names on its own
+preferences screen.