App Update Notifications (auto-update banner + error self-recovery)
How Omniscio updates itself: the silent background download, the Ready, Error and Duplicate-copy banners, manual update checks, rolling back to a previous version, selective rollout, and the What's New card that lands in your inbox after an update.
On this page
What it is
Omniscio auto-updates itself silently when a new release is published. Every 4 hours (and 30 seconds after each launch) the packaged app polls the Cloudflare R2 releases feed (with GitHub as a single-shot fallback if R2 is unreachable), downloads the new installer in the background, and surfaces a small banner near the top of the window so the user can either restart immediately ("Restart Now") or defer ("Later" — the install runs on next quit). When the check itself fails — private-repo authentication problems, a network outage, a draft-release glitch in the publish pipeline, an expired GitHub Personal Access Token — the banner now flips to a visible error notice instead of silently disappearing, with a link to the public releases page so the user can self-recover by downloading a fresh installer manually.
The banner has five user-visible states (in addition to the hidden "idle" state):
- Downloading — hidden for an ordinary automatic update: the new installer downloads silently in the background (it still installs on the next quit), so a routine update never interrupts you with a progress bar. The small accent-colored bar with "Updating to vX.X.X..." now appears only for a user-initiated rollback (Version History → "Roll back to this version") — a deliberate, awaited restore you're actively waiting on, so its progress stays visible right up to the restart it triggers.
- Ready — accent-colored "vX.X.X ready" plus a "Restart Now" button and a muted "Later" button. Clicking "Restart Now" quits the app and opens a small branded install window with a REAL progress bar (live percentage + megabytes as the new version unpacks, each step logged) and then relaunches Omniscio by itself — zero clicks, no wizard pages (2026-08-14 installer re-engineering; see windows-installer.md). Clicking "Later" hides the banner until the next update; the install still runs the next time you quit Omniscio (that quit-time install is silent — no window).
- Error — a red recovery banner with the "Download latest from releases" link (…/releases/latest,
target="_blank"+rel="noopener noreferrer") and a Dismiss button. The message is now HONEST about the cause: when the failure is a network/DNS block that can't reach the update server — the class where the feed host is DNS-blocked wholesale (bug f9d5e07b, e.g.*.r2.devblocked by an ISP/national resolver) — it reads "Can't reach the update server — your network or DNS may be blocking it. A different DNS or a VPN can help." instead of the dead-end "Update check failed."; any other (reachable-server) failure keeps the plain "Update check failed." The store carries anerrorReason('network-blocked' | 'generic', classified byclassifyUpdateErrorReasoninapp-update-error-classify.ts) that the banner branches on. This state was previously hidden — its arrival is the fix described in this page. - Duplicate copy — amber text "A newer version of Omniscio (vX.X.X) is already installed on this computer — this copy can't update itself," plus a "Switch to it" button when the newer copy is verified-safe to launch (or the folder path to open it manually when it isn't), and a "Later" button. This appears when a machine has more than one Omniscio install and the copy that was launched is out of date. See "When you have more than one copy installed" below.
- Hidden — when status is
idle,checking, ordismissed, nothing renders. The banner returns automatically on the next successful check that finds a new version, or on the next failure if the user dismissed an earlier error.
The auto-update system only runs in NSIS-installed packaged builds. Three conditions must all hold: app.isPackaged === true (dev builds skip), the launched binary is NOT a portable EXE (electron-builder sets process.env.PORTABLE_EXECUTABLE_FILE only on the portable target — its presence disables the updater), and <resourcesPath>/app-update.yml exists (manually-unpacked builds without it are skipped). During npm run dev, the service is inert — the developer updates by pulling git, not by downloading a binary. Portable EXE users (small-team distribution via Google Drive) never see the update banner: portable builds bundle app-update.yml like NSIS, but the GitHub-Releases credential path isn't available outside the installer flow, so polling would surface a recurring red "Update check failed" banner every 4 hours. Portable distribution replaces itself by re-downloading the new EXE from Google Drive, not by in-place update.
Safe Mode still updates. The update checker is core recovery, not automation, so it runs in Safe Mode (the idle "apply while I'm away" installer does not). An install that booted Safe Mode to escape a broken release can still receive the fixed one.
A build that can't update itself is no longer silent. On top of the manual "Check for updates" toast, a lightweight behind signal runs every 4 hours (and 30 seconds after launch) and reads the platform's latest*.yml from https://releases.omniscio.com/ (falling back to GitHub's hosted copy of the same file). When the feed holds a newer RELEASED version (a staged one does not count) and this build is one electron-updater refuses to run in — a portable EXE, a build with no app-update.yml, an AppImage whose APPIMAGE env is unset, or a macOS app outside /Applications — it raises ONE inbox card, "A newer version of Omniscio is available", with a "Download the latest version" button. It is deduped per version, never installs anything, and does not run in dev builds.
A prerelease install can always reach stable. An rc / exp / beta build follows the rc feed. If that feed offers nothing (it stops moving between soaks — rc.yml sat at 0.1.102-rc.5 from 2 Sep), the same check makes ONE extra check against the stable feed with prereleases off. A stable release newer than the running prerelease is then offered normally; it can never be a downgrade (allowDowngrade stays false and only a strictly-newer result is used), and nightly builds are left alone. The build's own feed is restored straight afterwards, so the next tick is unchanged.
Where to find it
Checking manually ("Check for updates")
The Check for updates item — in the header's overflow ("More") menu, or as a pinned toolbar button — runs the same check on demand. It always tells you how it turned out. A spinner toast ("Checking for updates…") goes up the moment you click, and is replaced by exactly one of:
- "You're up to date." — the feed offered this copy nothing newer. (A feed with no published release yet counts as up to date, and so does a release still rolling out to other copies: who gets which release is the team's choice and is never shown to a user — see below.)
- Nothing at all — the banner takes over — an update was found. The download starts and the banner shows it, so no toast talks over it.
- "This build doesn't update itself. Download the latest to upgrade." with a Download button — this copy of Omniscio can't update in place (a dev build, a portable EXE, or a manually-unpacked build with no
app-update.yml). No check was performed. The button opens the download page. - "Couldn't check for updates. Check your connection and try again." — the check genuinely failed. The raw network/HTTP cause is written to the log, never to the toast.
The "doesn't update itself" case is worth knowing about: because a portable build can never update in place, upgrading means downloading a fresh copy yourself. Since 2026-11-09 it is no longer the ONLY signal — the background behind signal raises an inbox card once per newer version on exactly these builds, so a user who never clicks "Check for updates" still learns they are behind.
A release this copy was not offered never reaches its user. A release published at a stagingPercentage below 100 is refused by electron-updater for installs outside the ring without any error, and the copy simply stays where it is: no banner, no toast, no inbox card. The same rule holds everywhere the app answers "which release exists": the behind signal and Version History's "Newest on the stable feed" treat a staged manifest as not out yet (the GitHub fallback reads GitHub's hosted copy of the same manifest under the same rule, never the latest tag), and the Version History list and GET /changelog show no release newer than the version this copy runs. The team still sees a withheld install: the routine tick writes ONE [app-update] v… is on the feed but was NOT offered to this install line per offered version, and the install heartbeat reports withheld.
An assigned release always arrives. A copy targeted by email or test group (see Selective rollout below), and a user-started rollback, skip the rollout ring, so a canary gets its version even while that release is staged at 25%.
You can take a release yourself. Settings → Diagnostics → Version History carries a Get updates right away switch (off by default). Turned on, this copy stops waiting to be picked by the gradual rollout and takes the newest release as soon as it is published — the switch checks immediately, so you do not wait for the next four-hour check. It changes nothing about what you are shown: the update arrives through the normal banner like any other. A release the team needs to stop is still stopped by pulling or replacing it on the update feed, so leaving the switch on never strands you on a release nobody can fix.
A failed background download retries once before you hear of it. The first failed download of a version is logged and retried quietly 15 minutes later; only a second failure of the same version shows the red banner. A download you started yourself with Check for updates is the exception: its failure shows the banner straight away.
Rescue when the feed host is blocked (bug f9d5e07b). The normal feed is served from a first-party Cloudflare R2 domain (https://releases.omniscio.com/), which replaced the shared *.r2.dev host after some ISP/national resolvers were found to DNS-block *.r2.dev wholesale (Indonesia's aduankonten.id), stranding every install behind such a resolver on ERR_CONNECTION_REFUSED. If the feed host is unreachable, a user-initiated "Check for updates" now runs the single-shot GitHub emergency fallback before surfacing the error (previously only the 4-h background tick fell back), so a user whose feed host is blocked but who can reach GitHub is rescued instead of stranded — that rescue is also what carries an already-blocked install onto the new address. When the BACKGROUND check keeps failing on that class AND the fallback can't reach a feed either — the install is genuinely stranded — one deduped, actionable inbox card ("Updates aren't getting through" → "Download the latest version") is raised so the silent failure is detectable, not only via a user complaint (alert-actions/app-update.ts).
How to use it
- Default behavior — nothing to configure. Once you've installed Omniscio from a real installer (
.exeon Windows,.dmgon macOS,.AppImageon Linux), the periodic checker is on by default. New releases arrive within 4 hours of being published. - Restart immediately when ready. When the banner shows "vX.X.X ready", click Restart Now. If a plugin job (such as a deck build) is still running, Omniscio first asks: Wait keeps everything as it is, Restart anyway stops the job and installs. Otherwise Omniscio quits, a small install window shows real progress (live percentage + MB unpacked, each step logged) while the new version installs, and the new version launches itself — zero clicks. Your sessions, accounts, and settings are preserved (the SQLite database lives outside the app bundle).
- Defer the install. Click Later to hide the banner. The downloaded installer auto-runs on the next quit — no second prompt, no extra step.
- Recover from a stuck binary. If the banner shows "Update check failed.", click Download latest from releases. That opens the releases page in your default browser; download the matching installer for your platform, run it, and the next launch will be on the new version. The error banner stays visible until you click Dismiss so you don't miss the recovery path.
- If the banner says nothing but you suspect updates aren't reaching you, open Settings → Diagnostics, click Export diagnostic bundle, and send the ZIP it saves to support@omniscio.com with what you expected to happen and roughly when.
Messages you might see
| The message you see | What to do |
|---|---|
| vX.X.X ready | The update has downloaded. Click Restart Now to apply it, or Later to install it the next time you quit. |
| Couldn't restart to install the update. | Restart Now could not restart the app. Click it again; if it keeps failing, use Download latest from releases. |
| Still couldn't check for updates. | The retried check failed too. Check your connection and try Check for updates again; if it repeats, send the diagnostic bundle to support. |
| Update check failed. | The update check failed. Click Try again, or Download latest from releases. |
| Can't reach the update server — your network or DNS may be blocking it. A different DNS or a VPN can help. | Your network or DNS is blocking the update server. Try a different DNS or a VPN, then Try again. |
| An update to Omniscio downloaded but couldn't install itself. Download the latest version to update. | The download could not install itself. Use the download link and run the fresh installer. |
| A newer version of Omniscio (vX.X.X) is already installed on this computer — this copy can't update itself. | Another, newer copy is on this computer. Click Switch to it. |
| A job is still running (a dialog after Restart Now) | A plugin job such as a deck build is running. Click Wait to leave it alone, or Restart anyway to stop it and install now. |
| The app update is waiting for your current job (inbox card) | Nothing to do. The update installs when the job ends and the computer is idle, or after 6 hours at the latest. |
| An update has been waiting N days. Restart to finish installing it. | A downloaded update is waiting because the app was never quit. Click Restart Now. |
Rolling back to a previous version
Settings → Diagnostics → Version History lists every release. Next to any older version you still have a data snapshot for, a "Roll back to this version" link appears. Clicking it shows a plain-English confirmation ("This restarts Omniscio and returns it to version X, including your data from just before that update. Your current data is saved first, so you can move forward again."), then: saves a fresh snapshot of your current data (so you can move forward again), downloads that older version's installer, restarts onto it, and restores that version's data on the way up.
Why a data snapshot, not just the old .exe: Omniscio's database only migrates forward, so an older app can misread a newer database. Right after every update finishes downloading, Omniscio quietly snapshots the outgoing version's data (tagged with that version) and keeps the last 3. Rollback restores the matching snapshot — which is why the list is empty until future updates have laid snapshots down; the screen says so rather than looking broken. If the older installer is no longer on the releases feed, the rollback fails cleanly with "Your data was not changed" — nothing is touched.
Backend: rollbackToVersion / listRollbackTargets in
app-update-service.ts (transient
allowDowngrade + a generic feed pointed at the target release), the 'pre-update'
snapshot ring in backup-service.ts,
and the targetVersion-gated restore in
backup-mirror-restore-service.ts.
Full invariants: app-update-rollback-contract.md.
You can always see where you stand. At the top of Version History a summary card shows
the version you are running, the newest version on the stable feed, and when this
install last successfully checked (as relative time — "12m ago"). It renders even when the
release list is empty or could not be loaded, which is exactly the stranded-install case; a
build whose updater never ran shows the behind signal's own last successful read instead of a
blank. Backend: the app-update:feed-status IPC
(app-update-handlers.ts → getUpdateBehindStatus() + getAutoUpdateLastSuccessfulCheckAt()).
Gentle nudge + "apply while I'm away"
Because Omniscio is left running all day (and close-to-tray means ✕ doesn't quit), a ready update can sit unapplied for days — measured, an install reporting 24 h of uptime every single day for 25 straight days that never took an update it had already downloaded. Two things help, neither ever yanks the rug:
- Apply while I'm away — ON by default since 2026-10-06. Omniscio installs a waiting update
on its own once the computer has been idle for 5 minutes, no tool update is installing and
the helper is not recording (
auto-install-idle.ts— any uncertainty means it waits). Running agents do not hold it (owner decision 2026-11-16): an agent mid-turn is cut off and picks up again after the restart, so a busy always-on computer still updates within hours. This is the one path that restarts Omniscio on its own.- A running plugin job does hold it (owner decision 2026-11-19): a paid deck build, for
example, cannot resume after a restart, so while an app screen has a job registered as running
the update waits. One inbox card, "The app update is waiting for your current job", names the
job and clears itself when the update installs or the job ends. It waits at most 6 hours,
then installs anyway (
app-update-run-gate.ts). - To turn it off: Settings → Diagnostics → Version History, and switch off "Apply updates automatically when away". Updates then wait until you click Restart (or until the gentle nudge below reminds you), exactly as before. Turning it off sticks — Omniscio will not switch it back on for you.
- A running plugin job does hold it (owner decision 2026-11-19): a paid deck build, for
example, cannot resume after a restart, so while an app screen has a job registered as running
the update waits. One inbox card, "The app update is waiting for your current job", names the
job and clears itself when the update installs or the job ends. It waits at most 6 hours,
then installs anyway (
- Gentle nudge — the store carries
readySince; once an update has been ready for more than 24 hours the "Restart Now / Later" banner strengthens into a calmer reminder. Still dismissible, and it never restarts. With the auto-install on by default this is the backstop for a machine that never goes idle: a computer that goes quiet installs itself long before the nudge would fire.
An update that has been downloaded and waiting for more than three days keeps its Restart Now banner, which says how many days it has waited; the long wait is logged once and rides the install heartbeat. It is never turned into the "download it manually" card, which is reserved for a copy that actually tried to install and kept booting the old version.
The store now holds { status, version, downloadPercent, releaseNotes, error, readySince, duplicate, rollbackInFlight }.
How it behaves
When the app cannot start (the startup rescue)
A release that fails during startup used to be a dead end: the app said "Copy details / Close", closed itself, and the update checker (which starts 30 seconds in, after the database) never got a turn. The migration path was worse — restoring the pre-migration backup clears the failure marker, so the same build re-ran the same broken migration on every launch.
The app now rescues itself from that state without needing the database:
- It reads the same update feed the install already uses — the release manifest for this platform, and the channel's own file for an rc or nightly build, with the public GitHub releases repo as a fallback — and gives up after a few seconds if the network will not answer.
- If a strictly newer version exists, the dialog offers Install the fix (vX.X.X): it downloads with a small progress window and then opens the same branded installer a normal update uses, so the user watches real progress and the new version relaunches itself. Choosing it never leaves the app running broken — the installer takes over.
- If nothing newer can be found, it offers Download the latest version, which opens the releases page, together with a plain statement that the details have been sent to the team automatically.
- The existing escape hatches stay: Copy details, and Close.
- A shared, all-users install it cannot write to is detected up front and explained — download the latest installer and run it as an administrator — instead of failing silently.
- Every other boot dead end offers it too, not just a crash: a database this copy is too old to open (after its own explain-and-quit notice), a database that will not open at all (the offer is merged into the existing Open Data Folder / Quit dialog, so neither escape hatch is lost), and a cancelled database-password unlock all lead to the same Install the fix / Download the latest version dialog instead of a bare Close.
The same rescue also fires when the app keeps dying before any window appears. A small file in the user-data folder counts starts that never reached a window (a healthy start clears it), so two failed starts of the same version raise the dialog on the next launch even when the failure never passed through the fatal-startup handler — a native crash or a killed process included. That launch offers Download the latest version but never an in-place install, because the app it is talking about may simply still be starting, and quitting it out from under a slow boot would be worse than the problem.
This counter is separate from the "update won't stick" attempt counter above: that one counts failed installs, this one counts failed starts.
This exists for installed builds only. A dev build or a portable EXE cannot update itself, so it
keeps exactly the old behaviour. Invariants, and the early-exit paths still to adopt it, are in
app-update-apply-contract.md (I15).
When you have more than one copy installed
A machine can end up with more than one copy of Omniscio in different folders — the Windows installer lets you choose the install location (so running it twice can land two installs), and there is also a portable build people download separately. When that happens, one copy auto-updates fine while the other copy stays on an old version. If the shortcut you click opens the old copy, it keeps noticing the new release, downloading it, and showing "Restart Now" — but restarting only updates/relaunches the other copy, so the one you open never changes. From the user's side it looks like "it says it updated but it still says restart now," forever. (autoUpdater.quitAndInstall() never downgrades, so a running version that drops from new back to old is proof of a second, separate binary — not a botched update.)
Omniscio now detects this and tells the truth instead of nagging. On startup (Windows installed builds only) it records each copy it runs — the executable's path and the version — in a small file in its user-data folder, then checks whether a strictly newer, INSTALLED copy exists at another path that is still on disk. "Installed" means the NSIS install directory carries its uninstaller (Uninstall <product>.exe); a portable or zip copy extracted from Downloads can never update anything in place, so it is never treated as the canonical newer copy (before 2026-11-09 one run of a newer zip copy was enough to make a real install stop checking for 30 days). If a newer installed copy exists, this copy is a stale duplicate: Omniscio stops the false download → "Restart Now" loop and shows the amber "Duplicate copy" banner. The banner offers a one-click "Switch to it" that:
- Verifies the newer copy is genuinely ours — it must exist, share our program's exe filename, and carry the same code-signing publisher as the running copy. If any check fails, Omniscio refuses to launch it and just shows the folder path so the user can open it manually. (It never launches an arbitrary path from that file.)
- Relaunches into the newer copy using
app.relaunch({ execPath }), which starts the new binary only after this one exits — so there's no window where nothing is running. - Repoints your shortcuts (best-effort) so the next time you open Omniscio from the Start Menu / desktop, you get the up-to-date copy — a permanent fix, not a one-time hop. Only the shortcut's target changes; its icon is left alone.
Why the record is keyed by install path (not a single global "did the update stick?" flag): both copies share the same user-data folder, so a global flag would be cleared by whichever copy launched last — masking the stale one. Keying by path is what lets Omniscio see "this copy is behind that copy."
Scope for v1: Windows installed builds. macOS/Linux and the "the portable copy is the stale one" case are documented gaps. Backend: install-registry-decision.ts (pure detection + validation, including the installed-copy predicate), install-registry.ts (the on-disk record and the uninstaller probe), switch-to-canonical.ts (the verified relaunch + shortcut repoint), and applyInstallLocationOnStartup + the sticky 'duplicate' status in app-update-service.ts. Full invariants: app-update-apply-contract.md.
Selective rollout (deliver to selected users, not the whole fleet)
By default a published stable release reaches every install within ~4 hours. Three controls deliver an update to a SUBSET instead (added 2026-06-29 — full invariants in targeted-update-contract.md):
- Staged % rollout. The
staging_percentage: <N>input injectsstagingPercentageinto the publishedlatest*.yml(inject-staging-percentage.mjs); electron-updater self-buckets each install on a stable per-machine id so only ~N% update. N must be one of the rule's steps — 25, 50 or 100 — and every entry point that writes it (therelease.ymlandrelease-promote.ymlinputs,release-cut,release:promoteand the injector) refuses anything else, because the automatic widener only knows how to advance those steps: a release parked at 20% is one it can never move. A percentage the feeds ALREADY carry off the ladder is still advanced to the next step above it (20 → 25, 30 → 50), and a hold that outlives 24 h at one step raises an inbox card naming every reason and the exact promote command, withdrawn once the step moves on (by the widener, by hand, or through a newer cut). - Per-user targeting by login email. A super-admin assigns a specific published version to a specific signed-in user in the admin dashboard's Targeted Updates tab; only that person's install picks it up.
runTargetedUpdateCheckinapp-update-service.tsasks theglobalAuthProfileCloud Function — keyed on the VERIFIED token email, so a user can never claim another's targeting — whether this install is targeted, and if so points the updater at that release's feed via the samesetFeedURLmechanism rollback uses (app-targeted-update.tsholds the pure decision logic). It is fail-safe (any error or signed-out state → normal updates continue), forward-only (never downgrades), admin-gated, and inert behindAMC_DISABLE_TARGETED_UPDATE. Reach is limited to users signed in to the account gate — the admin tab shows per-email reachability so that limit is visible. The server side (the shares Firebase project: the new globalAuth actions + thetargeted_updatescollection deny-rule + the dashboard tab) needs a one-time, gatedfirebase deploy. - Test groups. The same idea for a NAMED LIST of people: a super-admin creates a group in the admin dashboard's Test Groups tab (a name + a pasted set of emails + a version), and everyone in the group gets that version. It is resolved entirely SERVER-SIDE —
checkTargetedUpdatefolds the caller's per-user target with the target of every enabled group they're in and returns the HIGHEST version (update-groups.ts+ the sharedtargeting-shared.ts), so NO app change is needed — groups work for any app build that already has the targeting check. Groups are a dedicatedupdate_groupscollection (NOT the heavyweightorganizations/tenancy structure), admin-SDK-only, and the admin list shows member counts with per-member reachability on expand. Full invariants:targeted-update-contract.md.
Release notes in your inbox after an update
After Omniscio updates itself and relaunches into a new version, it drops a one-time card into your Inbox — "What's new in Omniscio vX.Y.Z" — showing that release's full "What's New" highlights right in the card (shown in full, no truncation and no extra button to click). It appears once per version, only on a real upgrade: a fresh install, the first launch after this feature ships, a rollback to an older version, and ordinary restarts all post nothing. It is inbox-only (no toast) and always on (no toggle to disable it), gated only by the master "agent alerts" inbox switch.
The card's text is whatever is written in that release's ## What's New section on GitHub — editing that section (even after the release is published) flows through to users' cards the next time their app fetches the notes, so the content is fully author-controlled per release. No release-workflow change is needed; the card reuses the same release-notes fetch the banner uses, plus the inbox-alert primitive. A release published without a ## What's New header falls back to a short title-only card (the technical "Details" section never lands in the card).
Only published releases are ever shown. The release ritual deliberately writes each set of notes as a draft for a human to review before publishing, and the in-app "New release" dialog defaults to draft too — so at any moment the top of the releases feed is usually a stack of unpublished stubs. GitHub hands those drafts back only to a caller signed in with access to the repo, which is why this misfired for signed-in users only: to everyone else the same request already returned the right release. The effect was a "What's New" that named an older version than the app you were running, reading as though the current release's notes were never written. The fetch now drops drafts outright, and also drops a published release whose notes are empty, so the newest thing you see is always the newest thing the team actually shipped.
Backend: release-notes-inbox.ts (a launch-time version-marker compare → fetch the new version's notes → post one deduped card), wired as the 'Release notes inbox' startup task (packaged builds only, fire-and-forget so it never blocks startup). The full "What's New" is rendered inline in the card body, so the card has no action button of its own — but, like every alert, it now offers the universal "Start session" button (the old renderer carve-out in AlertInboxViewer.tsx that suppressed it was removed — see inbox-alert-contract.md I8). When a release carries no ## What's New section (or the notes can't be fetched — an offline launch, a release not yet in the feed), the card does NOT stop at a bare "has been updated to vX": its body appends that version's release-notes URL (releaseNotesReleaseUrl), so an update always comes with a way to read what changed. That URL sits outside the translated sentence, and the English sentence itself lives in the en catalog shard (resources/locales/en/common.*.json) — a code defaultValue only applies when the key is missing, so changing the default alone would ship the old text. Full invariants: release-notes-inbox-contract.md.
Dismissal expires, and a stuck install can't be silenced (audit F064 / F171)
- "Later" is a deferral, not a mute. A ready update's dismissal is version-scoped, persisted in
localStorage(amc-app-update-dismissed-version) with the epoch ms it was recorded, and expires after 24 hours — the same window as the banner's "an update has been ready for a while" nudge. Without the expiry a single Later click made that nudge unreachable, which left a machine that never goes idle (so the idle auto-install never fires) permanently on an old build. - The two terminal stranding cards are session-only.
duplicate("a newer copy exists elsewhere") andwont-stick("it installed but the old binary keeps booting") are the only surfaces that tell a user their copy can never update itself, so a Later on either one now hides it for the current run and no longer. They are never written to storage, and a dismissal recorded on thereadybanner can never suppress them —app-update-store.tskeys the dismissal by the state it was made in. - The attempt is captured for support (RT-F035).
collectDiagnostics()now carries anupdateblock: the live status, the version that was offered, how far the download got, the classifiederrorReason, the durablelastAttemptVersion/lastAttemptAt/failedBootCountfrom the install registry (which survives the restart a user does before reporting), pluslastSuccessfulCheckAtandwithheldVersion. The raw error text is never carried. - A machine that never quits its app still gets told. An install that keeps the app running
only ever installs an update by quitting, so a downloaded update can wait indefinitely. After
three days of waiting the banner says so plainly — "An update has been waiting N days.
Restart to finish installing it." — and keeps Restart Now. This is the normal tray-resident
path, not a failed install:
wont-stickis reserved for a copy that actually tried and kept booting the old binary. The wait is measured from the moment the update FIRST became ready, not from the latest check, so a re-check every four hours cannot restart the clock; the same number rides the install heartbeat asupdateWaitingHours, so the fleet sees a multi-day stall instead of a permanent "2 hours". - A check never demotes a ready update, and
wont-sticknever stops the check. A background check while an update is ready leaves thereadystatus and its clock alone (a failed check cannot hide the update or stop the idle auto-install).wont-stickblocks only the release that would not stick (and anything older) — the 4-hourly tick keeps running, and a strictly NEWER release clears the flag and is offered normally, so a copy that missed a restart can still recover on its own. Suppressing the check instead would leave that install out of auto-update for good. The same rule applies to a stale duplicate: it never stops the check either — it only suppresses the false "Restart now" for a copy whose updates land on the other binary, and turnsautoDownload/autoInstallOnAppQuitoff so the copy does not fetch and run an installer it cannot use. The duplicate decision is re-read every tick, so uninstalling the newer copy restores normal updates (and re-arms both flags) without a restart. - The stuck card never stops the check.
wont-stickblocks only the release that would not stick (and anything older) — the 4-hourly tick keeps running, and a strictly NEWER release clears the flag and is offered normally, so a copy that missed a restart can still recover on its own. Suppressing the check instead would leave that install out of auto-update for good. - The fleet sees a stranded install without anyone complaining. Every install heartbeat
carries its live update health —
updateState(check-failed,wont-stick,duplicate,withheld,waiting,check-stale), how long it has held that state,lastSuccessfulCheckAt, the release channel, whether the build can auto-update at all, and the classifiederrorReason— and re-sends within a minute of the state changing. An install with more than 24 hours of uptime and no successful check in the last 24 hours reportscheck-staleinstead of the old "healthy", andcheck-staleis reported like any other bad state. The daily fleet pulse compares against the published release for each platform's own feed —latest.yml,latest-mac.yml,latest-linux.yml— so a release that skipped a platform's build never strands that platform (a release still below 100 % staged is not yet the baseline), and any install stranded for more than 7 days — two releases behind, more than 14 days behind, or stuck in a bad update state — is alerted on every digest, not once-on-a-surge. The 7- and 14-day legs measure how long the install has been BEHIND — from the later of its own version change and the first day that newer release was seen published — so a brand-new release never reads as a week of stranding. A build that cannot auto-update at all (a portable EXE, an updater that declined to run) is counted on its own line rather than as stranded, and awithheldinstall only counts once its platform's release is fully published — during a staged rollout being withheld is the rollout working, not a fault. The same counts appear in the digest card's "Update health" block, the admin FleetVersions panel, andnpm run fleet:installs.
Related
- logs-and-debugging.md — where
main.loglives and how to read[app-update]lifecycle entries - toolchain-update-v3.md — different system: updates the bundled CLIs (Claude Code, gh, git) at the OS level, not the Omniscio binary itself
- notifications-and-silence.md — the update banner is purely visual and does not route through the OS notification stack
- The never-restart v2 map (
.claude/memory/never-restart-v2-map.md, in the repository) — the planned design for applying new backend code without restarting the app at all, and optionally keeping agents running through it
Last verified 2026-11-19