Say which conversions come back, rather than that they all do #95

Merged
JMR-dev merged 3 commits from docs/readme-restart-claim into main 2026-08-25 14:02:23 +00:00
JMR-dev commented 2026-08-25 04:15:53 +00:00 (Migrated from github.com)

Closes #44 (R35, filed PLAUSIBLE — verified still live against current code rather than trusted from its date).

README promised, without qualification:

Conversions run as durable background work, so they survive leaving the app and are restored after a restart.

The first half is true and the reattachment work made it truer. The second half has one exception the sentence doesn't admit — and it's the case a user is most likely to hit without understanding it.

The mechanism, still in place

When Android refuses a foreground-service start, FailureOutcome retries — ten attempts on the default exponential backoff (30 s doubling to a five-hour clamp, ≈8 h 30 m total) — then returns FOREGROUND_DENIED on a FAILED job. Reattachment.kt:176 excludes FAILED.

So the job isn't restored, and neither is the message explaining why. The user opens the app to an empty screen.

The code was honest; the README wasn't

FailureOutcome's KDoc already says it plainly:

a user who was not watching when the eleventh attempt ran will find an empty screen rather than the explanation

That's the wrong way round for those two documents — the one users read was the one over-promising.

What replaced it

Says what actually happens, and ends on the thing the user can act on: reopening the app is what grants permission to run, so a conversion stalled this way should be restarted rather than waited on. Same reasoning FOREGROUND_DENIED_MESSAGE is written on — "open the app and start it again" is the fix, not filler.

Deliberately not claimed: that the app tells you. It doesn't, and #16 is the open ticket for giving a present, willing user a way to trigger that retry. Writing "you will be told" here would be this exact defect, one release earlier.

Closes #44 (R35, filed `PLAUSIBLE` — **verified still live** against current code rather than trusted from its date). README promised, without qualification: > Conversions run as durable background work, so they survive leaving the app and are **restored after a restart**. The first half is true and the reattachment work made it truer. The second half has one exception the sentence doesn't admit — and it's the case a user is most likely to hit without understanding it. ## The mechanism, still in place When Android refuses a foreground-service start, `FailureOutcome` retries — **ten attempts** on the default exponential backoff (30 s doubling to a five-hour clamp, **≈8 h 30 m** total) — then returns `FOREGROUND_DENIED` on a **FAILED** job. `Reattachment.kt:176` excludes FAILED. So the job isn't restored, **and neither is the message explaining why.** The user opens the app to an empty screen. ## The code was honest; the README wasn't `FailureOutcome`'s KDoc already says it plainly: > a user who was not watching when the eleventh attempt ran will find an empty screen rather than the explanation That's the wrong way round for those two documents — the one users read was the one over-promising. ## What replaced it Says what actually happens, and ends on the thing the user can act on: **reopening the app is what grants permission to run**, so a conversion stalled this way should be restarted rather than waited on. Same reasoning `FOREGROUND_DENIED_MESSAGE` is written on — *"open the app and start it again"* is the fix, not filler. **Deliberately not claimed: that the app tells you.** It doesn't, and **#16** is the open ticket for giving a present, willing user a way to trigger that retry. Writing *"you will be told"* here would be this exact defect, one release earlier.
Sign in to join this conversation.