[feature] the jump back to the host app is decided at runtime, and can be switched off remotely

[YJack0000]

What

HostReturn refused to run at all on iOS 26.4+, from a compiled-in
#available(iOS 26.4, *) gate. This replaces that gate with a runtime policy
that has a remote kill switch and learns from what actually happens on the
device.

Why

The gate was written when the first reports said Apple closed the host-return
path in 26.4. Keyboards in the same category are observably still returning
users to their host app on iPadOS 26.5, so the gate was switching off
something that works.

The wrong number is the smaller half of the problem. The larger half is that a
compiled-in answer cannot be corrected: for a path built on undocumented
internals, whose ground truth moves with every iOS point update in both
directions, a build-time constant is the wrong shape of answer entirely — and it
takes an App Store release to change.

How

HostReturnPolicy.decide answers "attempt the jump?" from three inputs, none of
which is a prediction:

Input	What it is for
FeatureFlags.HostReturn.enabled	Kill switch. Outranks everything, including a per-OS opt-in.
FeatureFlags.HostReturn.byOSVersion	Turn one iOS off — or back on, which is the only way to re-arm devices that have given up locally.
HostReturnLedger	What this device learned by trying. Two consecutive failures on one OS build and it stops.

Flags are fetched by CloudClient.featureFlags() and cached in the App Group by
FeatureFlagStore, so the keyboard extension reads the same answer the app acts
on. The ledger is stamped with the full OS build string, so an OS update wipes
the count and the device tries again by itself — exactly the moment the answer
might have changed.

HostReturn.attemptAndVerify is where the learning happens: it fires the launch,
polls for up to 1.2 s to see whether the app actually got backgrounded, and
records the verdict.

Optimistic, then honest

returnableHost is set the moment the jump is attempted, so DictationView
shows the hand-off shape immediately; it is cleared again if the app is still
foregrounded when the grace period expires, and the swipe-back guidance takes
over. That 1.2 s is the whole cost of being wrong, it is only paid while the
ledger is undecided, and it buys the one thing a version check never could — a
device that finds out.

Why the kill switch ships in this PR rather than after it

The path this governs is private API. The realistic failure mode is not a bug,
it is App Review objecting under 2.5.1 to a build that is already out. A switch
that requires a release to reach is not a switch. This one is a server-side
field change.

Fail-safe

Nothing here can break dictation:

• every read is synchronous and comes from the local cache; the network only
  ever updates that cache, out of band;
• a 404 from GET /v1/flags is folded into "no opinion", not into an error,
  so until the endpoint is published every device runs on compiled defaults and
  nothing about dictation changes;
• a corrupt cache, a missing App Group, or a flag document that only mentions
  some future feature all decode to the compiled defaults rather than throwing —
  a throw here is indistinguishable from "the server is down", which would
  freeze the fleet on whatever it last saw.

Server-side follow-up

GET /v1/flags does not exist yet. Publishing it is the only remaining step to
gain the switch; no client release is needed. Shape:

{ "hostReturn": { "enabled": true, "byOSVersion": { "26.4": false }, "failureBudget": 2 } }

Testing

• swift build on ParleyKit is clean, no warnings.
• 27 new assertions across HostReturnPolicyTests, HostReturnLedgerTests,
  FeatureFlagsTests, FeatureFlagStoreTests — decision precedence, the budget
  and its clamp, the OS-update reset, and every degradation path.
• bunx tsc --noEmit clean; bunx vitest run 285/285 (no TypeScript touched
  here).

⚠️ swift test and the iOS app target were not run locally. This machine has
Command Line Tools but no Xcode, so XCTest cannot link and the app target cannot
build. The ParleyKit logic was instead verified by compiling the sources into a
standalone harness asserting the same 27 behaviours (all pass), and the five
modified app-target files were checked with swiftc -parse. CI is the first
real build of the app target and of the XCTest suite — worth watching before
merge.

Not verified, and cannot be from here

Whether the jump actually lands, on any given iOS. That is the point of the
ledger: this stops the codebase from guessing and starts it measuring. The first
real signal will be devices on 26.5 either returning or not.

🤖 Generated with Claude Code

[github-actions]

✅ SonarQube Quality Gate passed — pathorsAI_parley

0 open issues on this PR.