@@ -33,7 +33,15 @@ people actually have is one file.
 Convergence takes back only what it installed. Boxes above was declared
 once and no longer is, so it is on the removal list; Bazaar you installed
 yourself, so it is undeclared but in no danger. Install apps from a store
-if you like — being undeclared costs reproducibility, never survival.
+if you like: being undeclared costs reproducibility, never survival.
+
+Membership and currency are separate questions, and only the first belongs
+to the declaration. It decides what exists. Keeping software current is
+kuma's job regardless of who installed it, so a store-installed app, an
+ad-hoc `brew install`, and a flatpak runtime are updated on the same
+schedule as a declared app. Nothing is left to rot for the crime of not
+being written down. Each ecosystem's own hold still works if you want to
+stay on a version: `flatpak mask` and `brew pin`.
 
 `kuma capture` prints the proposal and writes nothing until `--yes`; naming
 items captures only those. You review a diff of your *declaration*, not of
 
@@ -24,7 +24,8 @@ rpm = ["fish", "git-core", "git-core-doc", "distrobox"]
 
 # Converged on boot and daily, and convergence only takes back what it
 # installed: an app you install through a store stays yours until you
-# decide, and `kuma capture` offers to write it down here.
+# decide, and `kuma capture` offers to write it down here. Updates are
+# not scoped that way: everything installed is kept current.
 flatpak = [
     "org.mozilla.firefox",
     "org.gnome.Loupe",
 
@@ -3,11 +3,11 @@
 schema_version = 1
 
 [system]
-# Unset — the default — kuma composes its own base from Fedora's package
+# Unset (the default) kuma composes its own base from Fedora's package
 # repos: Fedora's minimal bootc core (kernel, systemd, bootc, dnf) plus
 # hardware enablement, and none of the general-purpose weight
 # fedora-bootc carries. Set it to any bootc image reference to build
-# FROM that instead — the escape hatch for debugging against
+# FROM that instead: the escape hatch for debugging against
 # fedora-bootc, a mirror, or a test tag.
 # base = "quay.io/fedora/fedora-bootc:44"
 
@@ -56,7 +56,8 @@ rpm = ["fish", "git-core", "git-core-doc", "distrobox", "tailscale"]
 # Flathub apps, converged on boot and daily: additions install, removals
 # uninstall. Convergence only ever takes back what it installed, so an
 # app you install yourself stays yours, from a store or the command line,
-# and `kuma capture` offers to write it down here.
+# and `kuma capture` offers to write it down here. Updates are not scoped
+# that way: everything installed is kept current, declared or not.
 flatpak = [
     "org.mozilla.firefox",
     "org.gnome.Loupe",
 
@@ -9,7 +9,7 @@ schema_version = 1
 
 [system]
 # Explicit on purpose, twice over: it keeps this the fast compose-free
-# build the smoke tests lean on, and it demonstrates the escape hatch —
+# build the smoke tests lean on, and it demonstrates the escape hatch:
 # any bootc image can be the base when you name one. Omit the key and
 # kuma composes its own base instead (the default everywhere else).
 base = "quay.io/fedora/fedora-bootc:44"
 
@@ -503,6 +503,20 @@ fi
 ///
 /// The uninstall tolerates failure because the state file can name an
 /// app the owner already removed by hand, which is not an error.
+///
+/// Membership and currency are different questions, and only the first
+/// belongs to the declaration. Convergence decides what exists; the
+/// update decides how old it is, and it is deliberately unscoped. An app
+/// the owner installed through the store is theirs to keep, but leaving
+/// it to rot is not respect, it is an unpatched browser. The same call
+/// covers runtimes, which the declared install reaches only when a
+/// declared app happens to demand a newer one.
+///
+/// Ordering is load-bearing. The state file is written before the
+/// update, so a failed update (a flaky network, one broken remote)
+/// cannot leave authority tracking behind and silently strand a removal
+/// until the next successful run. Pruning comes last so the runtimes the
+/// update orphans go in the same pass.
 const FLATPAK_SYNC_SCRIPT: &str = r#"#!/usr/bin/bash
 set -euo pipefail
 declared=/usr/lib/kuma/flatpaks
@@ -514,8 +528,9 @@ while read -r app; do
     grep -qxF "$app" "$declared" \
         || flatpak uninstall --system --assumeyes --noninteractive "$app" || true
 done < "$state"
-flatpak uninstall --system --unused --assumeyes --noninteractive
 cp "$declared" "$state"
+flatpak update --system --assumeyes --noninteractive
+flatpak uninstall --system --unused --assumeyes --noninteractive
 "#;
 
 const FLATHUB_URL: &str = "https://dl.flathub.org/repo/flathub.flatpakrepo";
@@ -1108,6 +1123,15 @@ WantedBy=multi-user.target
 /// and only ever-declared formulae are removal candidates. Ad-hoc `brew
 /// install` is untouched. The flatpak sync learned the same trick after
 /// its scope proxy turned out to be one a store could break.
+///
+/// The upgrade at the end is unscoped on purpose, and it is the one
+/// thing here that reaches past the declaration. Ad-hoc formulae stay
+/// the owner's to keep or remove; they were simply never getting
+/// updated, because the upgrade used to name the declared list. Bare
+/// `brew upgrade` also covers casks, which nothing else in kuma can even
+/// see. It runs after the state file is written so a failure cannot
+/// strand authority tracking, and needs no `brew update` first because
+/// brew auto-updates its taps before upgrading.
 const BREW_SYNC_SCRIPT: &str = r#"#!/usr/bin/bash
 set -euo pipefail
 brew=/home/linuxbrew/.linuxbrew/bin/brew
@@ -1117,14 +1141,14 @@ state=/home/linuxbrew/.linuxbrew/.kuma-brews
 [ -f "$state" ] || : > "$state"
 if [ -s "$declared" ]; then
     xargs -a "$declared" "$brew" install
-    xargs -a "$declared" "$brew" upgrade
 fi
 while read -r formula; do
     grep -qxF "$formula" "$declared" && continue
     "$brew" uninstall "$formula" || true
 done < "$state"
 "$brew" autoremove
 cp "$declared" "$state"
+"$brew" upgrade
 "#;
 
 /// brew refuses to run as root; uid 1000 owns the prefix (brew's
@@ -2119,6 +2143,70 @@ mod tests {
         assert!(dir.path().join("kuma-flatpak-sync").exists());
     }
 
+    /// Both syncs keep software current without claiming it. Scoping the
+    /// upgrade to the declared list is what left 13 outdated formulae,
+    /// every store-installed app, and a stale runtime on a real machine
+    /// whose convergence had been running daily the whole time. So the
+    /// upgrade must name nothing: the moment it takes an argument it has
+    /// a scope again, and everything outside that scope rots.
+    ///
+    /// The ordering assertions are the ones worth keeping. Both scripts
+    /// run under `set -euo pipefail`, so an upgrade placed before the
+    /// state file is written would, on any flaky-network run, abort the
+    /// script with authority tracking still describing the previous
+    /// declaration, stranding a removal until some later run happened to
+    /// have working DNS.
+    #[test]
+    fn both_syncs_update_what_they_do_not_own() {
+        // Match whole lines, not offsets into them. Searching for the
+        // command and slicing from the hit hides everything to its left,
+        // so a re-scoped `xargs -a "$declared" flatpak update ...` reads
+        // as unscoped: the assertion holds exactly when the thing it
+        // guards has been undone.
+        let line_of = |script: &'static str, needle: &str| -> (usize, &'static str) {
+            let mut at = 0;
+            for line in script.lines() {
+                if line.contains(needle) {
+                    return (at, line);
+                }
+                at += line.len() + 1;
+            }
+            panic!("{needle} is gone from the sync script");
+        };
+
+        let (flatpak_update, line) = line_of(FLATPAK_SYNC_SCRIPT, "flatpak update");
+        assert!(
+            !line.contains("declared") && !line.contains("xargs"),
+            "the update must be unscoped, or undeclared apps and runtimes never move: {line}"
+        );
+        let (flatpak_state, _) = line_of(FLATPAK_SYNC_SCRIPT, r#"cp "$declared" "$state""#);
+        assert!(
+            flatpak_state < flatpak_update,
+            "authority must be recorded before the update, so a failed update cannot strand it"
+        );
+        // The prune runs last so runtimes the update orphans go with it.
+        let (flatpak_prune, _) = line_of(FLATPAK_SYNC_SCRIPT, "--unused");
+        assert!(
+            flatpak_prune > flatpak_update,
+            "unused runtimes are pruned after the update, not before"
+        );
+
+        let (brew_upgrade, line) = line_of(BREW_SYNC_SCRIPT, r#""$brew" upgrade"#);
+        assert_eq!(
+            line.trim(),
+            r#""$brew" upgrade"#,
+            "bare upgrade takes formulae and casks alike; an argument list takes neither"
+        );
+        let (brew_state, _) = line_of(BREW_SYNC_SCRIPT, r#"cp "$declared" "$state""#);
+        assert!(brew_state < brew_upgrade, "same ordering rule as the flatpak sync");
+
+        // Membership is still the declaration's alone. Widening the
+        // upgrade must not widen the install: only the declared list is
+        // ever installed, in both scripts.
+        assert!(BREW_SYNC_SCRIPT.contains(r#"xargs -a "$declared" "$brew" install"#));
+        assert!(FLATPAK_SYNC_SCRIPT.contains(r#"xargs -r -a "$declared" flatpak install"#));
+    }
+
     #[test]
     fn user_generates_boot_sync_not_build_time_useradd() {
         let out = generate(&config(
 
@@ -142,7 +142,8 @@ enum Cmd {
         #[arg(long)]
         json: bool,
     },
-    /// Converge flatpaks and brew to the declaration now, not at next boot
+    /// Converge flatpaks and brew to the declaration and update everything
+    /// installed, now rather than at next boot
     Sync {
         /// Report the result as JSON (progress moves to stderr)
         #[arg(long)]