diff --git a/docs/explanations/2026-07-11-explanation-phone-focus-whitelist-foss.html b/docs/explanations/2026-07-11-explanation-phone-focus-whitelist-foss.html new file mode 100644 index 00000000..4dbbeff4 --- /dev/null +++ b/docs/explanations/2026-07-11-explanation-phone-focus-whitelist-foss.html @@ -0,0 +1,405 @@ + + + + + +Explaining: whitelist run-with-music apps + FOSS replacements + + + +
+ +

Run with music, unhide the FOSS apps

+

A change to phone_focus_mode/config.sh — the location-based Android focus enforcer. Commit 7e59abd, 2026-07-11.

+ +
+ On this page + 1 · Background + 2 · Intuition + 3 · The change + ▶ Play + 4 · Quiz +
+ +

1 · Background

+

phone_focus_mode is a set of shell scripts running as root (via Magisk) on a rooted Android phone. A daemon polls your GPS location every few seconds. When you're within ~150 m of home, it enters focus mode and disables distracting apps; when you walk away, it re-enables them. The idea is that home should be low-distraction, but you're not locked out of everything when you're out.

+ +

"Disable" here means pm disable-user — Android's built-in way to make an app vanish from the launcher and stop running, without uninstalling it. The reverse is pm enable.

+ +

What decides if an app is allowed

+

Everything hangs off two plain-text lists in config.sh:

+ +

On startup the daemon flattens each list into a state file (whitelist.txt, night_whitelist.txt) and a function is_allowed(pkg) checks the appropriate one for the current time.

+ +

The one subtlety that drives the whole change

+

The disable sweep only ever looks at third-party packages:

+
pm list packages -3 -e   # -3 = third-party only, -e = currently enabled
+

System apps (anything preinstalled — Gmail, Google Photos, the stock Clock, the dialer) are never touched by the sweep. The only lever that could disable a system app is a separate list, BLOCKED_SYSTEM_APPS — and on this device that list is intentionally empty, with a blunt warning in the file:

+
+ pm disable-user state persists across reboots. A disabled system package across a reboot can trip MediaTek's bootloop protection → recovery → factory wipe (confirmed on the BL9000). So system distraction is handled at the network layer (DNS/iptables), never by disabling the package. +
+

Keep that fact in your pocket — it's why half of this request could not be done in code.

+ +

2 · Intuition

+

The user wanted three things:

+
    +
  1. Go for a run with music — RunnerUp + a music player + the workout app usable even during the night curfew.
  2. +
  3. Unhide a batch of newly-installed FOSS apps (an open-source clock, camera, file manager, weather app, search, email) that replace Google's stock apps.
  4. +
  5. Hide the Google originals they replaced.
  6. +
+ +

Why the FOSS apps were "hidden" in the first place

+

They're third-party apps that weren't on any whitelist. So every time the user got home, the sweep found them via pm list packages -3, saw is_allowed return false, and disabled them. From the user's point of view the app "disappeared." The fix is simply: add them to WHITELIST, and the sweep skips them.

+ +
+

Before

Clock You is third-party, not whitelisted → sweep disables it at home → gone from launcher
+
→
+

Add to WHITELIST

is_allowed now returns true → sweep skips it → stays visible
+
+ +

Why music needed a second entry

+

Metrolist (the music player) was already on the daytime WHITELIST. But a real run might happen at 23:30 — inside the curfew — and the curfew uses the other list. Metrolist wasn't on it, so it got disabled after 23:00. Adding com.metrolist.music to NIGHT_WHITELIST is what actually closes the "run with music" gap.

+ +

Why "hide the Google apps" is not in this diff

+

Gmail, Photos, Keep, the stock Clock, the dialer — all system apps. The sweep can't reach them, and forcing them off means BLOCKED_SYSTEM_APPS, which risks wiping the phone. So that half was declined in code: the safe way to hide a system app is the launcher's own "hide apps" screen, which removes it from view without disabling the package. The diff only does the safe half.

+ +

A latent bug found along the way

+

The night list already had org.fossify.clock for morning alarms — but that package isn't installed. The user's actual clock is com.bnyro.clock. So nothing clock-related actually survived the curfew: a dead entry guarding a real need. The change swaps the dead package for the installed one.

+ +

▶ Play with it

+

The whole system is just: where are you, what time is it, is the app third-party, and which list is it on. Flip the controls and watch each app flip between enabled and disabled. Toggle Before / After to see exactly what this diff changed.

+ +
+
+
+ This change + + + + +
+
+ Location + + + + +
+
+ Time + + + + +
+
+
+

+
+ +

3 · The change

+

All of it lands in two string arrays in config.sh. Grouped by intent:

+ +

a · Unhide the FOSS replacements (daytime WHITELIST)

+

Five open-source apps added, and the dead org.fossify.clock removed from this spot (the installed clock takes its place):

+
 org.mozilla.fenix
+-org.fossify.clock
++# --- FOSS replacements for stock/Google apps (unhidden per request; hide the
++#     Google originals in the launcher, NOT via package-disable — see the
++#     BLOCKED_SYSTEM_APPS note about MTK bootloop/wipe risk on BL9000) ---
++com.bnyro.clock          # Clock You
++com.vayunmathur.camera   # Camera
++com.rama.teyin           # Teyin file manager (replaces Google Files)
++com.yoshi.rain           # Rain weather
++com.jksalcedo.librefind  # LibreFind (replaces Google Search)
+ ws.xsoh.etar
+

(Inline labels shown for clarity; in the file the comments are on their own lines, because the parser only strips whole # lines.)

+ +

b · The email replacement

+
 # --- Email & communication ---
++net.thunderbird.android.beta
+ com.microsoft.office.outlook
+ +

c · The kicktipp app (daytime only)

+

A football-predictions app, wanted during the day but not the night curfew — so it goes on WHITELIST only:

+
 # --- Fitness ---
+ org.runnerup
++
++# --- Sports / football predictions ---
++de.kicktipp.mbookmark
+ +

d · The run-with-music entries (NIGHT_WHITELIST)

+

Music survives the curfew, and the dead alarm-clock entry is replaced with the installed one:

+
 # Calendar
+ com.google.android.calendar
+ ws.xsoh.etar
+-# Alarm clock
+-org.fossify.clock
++# Alarm clock (Clock You — the installed clock; org.fossify.clock is not present)
++com.bnyro.clock
+ ...
+ com.kuhy.workout_app
+ org.runnerup
++# Music player — kept so a night run has music in the background
++com.metrolist.music
+ +
+ How it was verified. Deploying regenerates the on-device state files; the six previously-disabled FOSS apps went from enabled=3 (disabled-by-user) to enabled=1 (enabled), and night_whitelist.txt gained com.metrolist.music and com.bnyro.clock with no org.fossify.clock. Package names (e.g. de.kicktipp.mbookmark, and that "Rain" is a weather app) were confirmed off the device, not guessed. +
+ +

4 · Quiz

+
Score: 0 / 0
+
+ +
Generated by /explain-diff. Grounded in the actual focus_daemon.sh disable sweep and config.sh — behavior verified on device BL9000EEA0000102.
+ +
+ + + + diff --git a/docs/explanations/index.html b/docs/explanations/index.html new file mode 100644 index 00000000..cbd3fc68 --- /dev/null +++ b/docs/explanations/index.html @@ -0,0 +1,43 @@ + + + + + +explanations — change explanations + + + +
+
explanations
+

Change explanations

+

1 explanation · interactive walkthroughs of notable changes, newest first.

+
+ + 2026-07-11 + Explaining: whitelist run-with-music apps + FOSS replacements + +
+ +
+ +