Restore remembered Apple sessions automatically without discarding saved access

docs/agents/07-upstream-maintenance.md

@@ -41,7 +41,8 @@ appear everywhere without being forgotten. No recurring schedule is implied.
    Follow the optional launcher-metadata contract; keep game settings delegated to
    the built app unless implementing that contract explicitly.
    Preserve the isideload exact-identifier patch, signed/profile identity checks,
-   Keychain session storage, redacted stdio and RomFS-only transfer capability.
+   Keychain session storage, one queued authentication-only remembered-session
+   recovery per launch, explicit logout and failure preservation, redacted stdio and RomFS-only transfer capability.
    Preserve UDID deduplication (USB preferred), device metadata/search/update
    selection, separate connected/registered inventories and logs without raw
    credential/provider payloads. Full/light packaging must retain the bundled

docs/personal-ios.md

@@ -673,3 +673,23 @@ the modal frame and Close button. No helper, game or save behavior changed.
 Offscreen navigation validates that the open-catalog intent is consumed without
 an attached sheet; catalog fixtures/checks and the production SwiftUI build
 validate the change. No gameplay/device actions were performed.
+
+## Automatic remembered account recovery (1.14.3)
+
+The observed sign-in form was caused by missing normal-startup session recovery:
+only a manual action or a due app refresh invoked the existing Keychain route.
+This fix queues one authentication-only recovery when the remembered-account
+marker exists, waits for the shared helper to be idle and prevents duplicate
+attempts/retry loops. Failure preserves saved data and offers retry/password
+choices without asserting that the token expired. A per-account previous team
+is restored only against fresh team membership and never over an active refresh.
+Explicit logout/cancel prevents queued recovery; cancelled remember-choice intent
+cannot overwrite a prior saved preference during a later recovery.
+
+The native helper, Keychain service/key/format, game files and saves are unchanged.
+No real Keychain value was read, credential printed, Apple login performed or
+running launcher restarted. All 68 script cases completed with one optional JWT
+dependency skip; expanded fake-helper recovery/cancellation fixtures passed again
+after state cleanup. These test restoration orchestration, not the user's actual
+session validity. Production compilation/signature validation and documentation
+checks validate the delivered UI/client patch.

docs/sideloading.md

@@ -366,3 +366,43 @@ inventory even if signing later fails: registering happens before installation
 and can consume the slot independently of install success. The UI explains this
 before confirmation. Apple remains authoritative when registration is attempted.
 Agent validation never logs into a real account or registers a device.
+
+## Remembered session recovery (1.14.3)
+
+Remember session stores the helper's private Apple session data in macOS Keychain,
+under the existing stable service/account key. It does not store the password or
+copy Apple credentials to an iPhone/iPad, game folder or repository. The saved
+email preference is only an opt-in marker, not proof that a Keychain entry exists
+or that Apple still accepts it. No Keychain identifier/format or native helper
+changed in this patch; actual token validity was not inspected by the agent.
+
+Previously a new launcher process started unauthenticated and restored only when
+the player pressed Use Keychain session or a due installation refresh requested
+it. The password form appeared first despite a remembered account. Startup and
+the account view now request one automatic authentication-only recovery. It waits
+for discovery or another helper operation to finish and does not create jobs,
+register devices, sign, install or copy game data. Duplicate view/startup requests
+coalesce; a failure does not cause a retry loop or delete the saved marker/token.
+A visible recovery status offers cancellation outside the account/installer UI.
+
+On failure the account page offers Retry saved session and an explicit password
+fallback. Connection/Keychain failures are not labelled as proven expiration.
+Apple may still require a new authentication; the app cannot promise an indefinite
+session. A manual retry remains possible. Cancelled password-login intent is
+cleared before a later recovery, preventing an abandoned Do not remember choice
+from deleting an earlier remembered account marker. Explicit sign-out remains
+explicit: it removes the saved session through the existing helper and prevents
+an automatic login from undoing the sign-out.
+
+The previously selected team is remembered per account only after successful
+Apple authentication with Remember enabled. Recovery restores it only if that
+exact ID is still in the freshly returned team list and there is no active
+original-team refresh intent. It never chooses an arbitrary team. Existing
+per-app account/team/BundleID bindings remain authoritative for updates.
+
+Compiled fake-helper fixtures simulate cold restart, deferred recovery after
+scoped discovery, duplicate requests, no opt-in, successful prior-team recovery,
+unavailable sessions, explicit retry, logout, helper absence and a cancelled
+non-remembering login followed by recovery. They verify authentication-only
+transport, no retry loop and preservation of saved preference metadata. They do
+not access the user's Keychain or authenticate against Apple.