Update to a new build

Agents: claude, codex, opencode · On: phone, desktop

When a newer version of the app is out and your box runs it too, a button appears in the top bar. Tap it and the app reloads onto the new build. Leave it alone and the app reloads by itself the next time it is in the background, or after five minutes without a touch, as long as nothing you typed would be lost. On the dev build it reloads as soon as the box runs the new build.

The app waits for the box: it takes a new build only once the box of the tab in front runs the same release. The app and the box then show the same version. On the login screen, the box list and the pair screen no box is open yet, so the app takes a new build there at once.

Why you would use it

An installed app serves its cached copy of itself. Without this, a deploy would never reach a phone that keeps the app open for days, and swapping scripts under a live session mid-turn would be worse.

How to use it

1. Leave the app open, or bring it back to the foreground. The check runs on every return to the foreground, and every 15 minutes while the app is open (every minute on the dev build).

2. When the new build has finished installing behind the running one, and the box of the tab in front runs the same release, the update button (#update-ready) appears in the top bar, right of the tabs. Until the box updates, the app stays on the build it has.

   

3. Tap it. The app reloads on the newest version, even one released after the button appeared.

4. Or do nothing. The app reloads on its own when you switch away from it, or once it has seen no tap, key or scroll for five minutes. It waits while the composer holds text, a file edit is unsaved, a dictation is running, or a text field has focus, and tries again every 30 seconds. Words in the composer come back after the reload.

5. On the dev build the app does not wait for the background or idle time: it reloads as soon as the box runs the new build, while you use it. Only an unsaved file edit or a running dictation holds it. dev.app.fezu.dev always serves the dev build; app.fezu.dev serves it while any of your boxes runs dev code (see release-channels).

In the app on app.fezu.dev the login, box and pair screens cover the top bar, so the same button shows on that sheet too, as Update ready: reload (#rs-update). Before any box is open, these three screens show it as soon as the new build has installed, whatever release your boxes run. The box list opened over running tabs waits for the box like the top bar does.

What you see

• A circular-arrow button in the top bar. Its label and title are Update ready: reload. It is hidden until a build is waiting.
• It stays until you tap it. It does not cover the transcript and it does not time out.
• After a tap the arrow spins and the button stops answering until the page reloads, which can take a few seconds while a newer build installs.
• Tapping it reloads the page once, on the new build.
• If the new build already took over while the page stayed on the old one (an automatic update in the background, or another window), a tap reloads onto it, and so does the automatic update when it next runs. If nothing newer is left, the button hides at the next check for a new build, or at once on a tap.
• Untapped, the page reloads once on its own, in the background or after five idle minutes. A turn that is running carries on: it runs on the box, and the reloaded page picks it up where it was.

Limits and known gaps

• The app follows the box of the tab in front. With boxes on different releases, switching to a tab on another box can show the button, or hold it back.

• A box that is offline, or does not update, holds new builds back for one day at most, counted from the first one. After that the app takes the newest.

• A box running from a git clone, or on a release from before releases were numbered, does not hold a new build back. Nor does a box that refuses this version of the app.

• The button only appears when an older build is already installed, so a first-ever visit installs silently, with no button and no reload. A page loaded with Ctrl+Shift+R still gets the button.

• The automatic reload drops nothing it can see, but it cannot see a sheet's unsaved choices: a settings sheet half filled in is closed by the reload.

• There is no setting to turn the automatic reload off.

• An operator who ships a shell change without bumping VERSION in public/sw.js never reaches installed phones, restart or not.

Related

• open-the-app-offline: the cache the update replaces
• update-the-install: the operator's half: what puts the new build on the server
• install-on-a-phone: the install that makes the button possible
• update-from-a-tab: /update reloads onto the new build without the button
• release-channels: which build app.fezu.dev serves, and the dev build's faster updates
• floating-chrome: the version row, which shows the box's release