chore: bump version to 0.1.12

Whole-project review pass over the entire crate. No new features.
All function definitions preserved; layout and visibility reorganised.

Bug fixes:
- bubble: ExtractIconExW HICON pair was leaked per bubble toggle.
  Extract once into a process-wide OnceLock, reuse forever (bounded).
- usage/anthropic: parse_iso8601 was stripping the UTC offset without
  applying it — negative-offset users saw countdowns up to 14h wrong.
  Now parses signed minutes and computes utc_secs = local - off*60.
  Also rejects y<1970, mo∉[1,12], d∉[1,max_day(mo,y)] up front so
  malformed API responses can't index DAYS_IN_MONTH out of bounds.
- usage: clamp utilization to [0,100] at all four Window construction
  sites so a misbehaving server can't render "121%".
- bubble: GetDC and CreateCompatibleDC results weren't checked. Guard
  both; release the screen DC on the CreateCompatibleDC failure path.

Refactor:
- Drop type TrayIconKind = ProviderId aliases (5 sites); use ProviderId
  directly everywhere. Inline the identity-function kind_to_provider.
- Delete panel::bar_color_for shim (was just argument-reorder glue).
- Replace local scale_to_dpi fns in bubble.rs and panel.rs with
  use crate::os::dpi::scale as scale_to_dpi (brings os::dpi into the
  live import graph; was unused before).
- Delete dead PCWSTR import + #[allow(dead_code)] sentinel in
  tray/badge.rs; fold the trailing `use BOOL` into the top imports.
- Inline app::primary_dpi() to crate::os::dpi::for_system().

app.rs:
- Add update_settings(|s: &mut AppState|) helper that locks state,
  runs the closure, snapshots Settings, drops the lock, then saves
  to disk. Convert four pure-mutate-then-save callsites.

Layering: bubble.rs no longer reaches upward into crate::app::.
Introduce bubble::Callbacks (fn-pointers), OnceLock<Callbacks>, and
bubble::install_callbacks(). The wnd_proc dispatches the six prior
upward calls via a private dispatch() helper. app::run installs
callbacks once at startup; the six on_bubble_* / recheck_theme fns
are demoted from pub fn to fn.

Resource-warning logs added: dispatch() warns on uninstalled
callbacks; app_icons() warns when ExtractIconExW returns nulls.

Build: cargo build --release clean; cargo clippy reports zero new
warnings (11 pre-existing, all in untouched code).

.github/workflows/release.yml

@@ -14,10 +14,7 @@ permissions:
 
 jobs:
   build:
-    # Pinned explicitly: `windows-latest` is being redirected to a newer image
-    # by GitHub in mid-2026 — pin the current Windows Server 2025 image so
-    # release behavior is deterministic across that transition.
-    runs-on: windows-2025
+    runs-on: windows-latest
     steps:
       - uses: actions/checkout@v6
         with:

Cargo.lock

@@ -59,7 +59,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "claude-code-usage-bubble"
-version = "0.1.9"
+version = "0.1.12"
 dependencies = [
  "dirs",
  "embed-resource",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "claude-code-usage-bubble"
-version = "0.1.9"
+version = "0.1.12"
 edition = "2021"
 license = "Apache-2.0"
 description = "Floating bubble showing Claude Code and Codex usage on Windows"
@@ -23,12 +23,14 @@ version = "0.58"
 features = [
     "Win32_Foundation",
     "Win32_Globalization",
+    "Win32_Graphics_Dwm",
     "Win32_Graphics_Gdi",
     "Win32_System_LibraryLoader",
     "Win32_UI_Shell",
     "Win32_UI_WindowsAndMessaging",
     "Win32_System_Registry",
     "Win32_System_Threading",
+    "Win32_Storage_FileSystem",
     "Win32_Security",
     "Win32_UI_HiDpi",
     "Win32_UI_Input_KeyboardAndMouse",

plans/260521-1530-silent-update-no-cmd/phase-01-foundation-cli-flags-native-spawn-helper-mutex-retry.md

@@ -0,0 +1,104 @@
+---
+phase: 1
+title: "Foundation: CLI flags + native spawn helper + mutex retry"
+status: complete
+priority: P1
+effort: "3h"
+dependencies: []
+---
+
+# Phase 1: Foundation: CLI flags + native spawn helper + mutex retry
+
+## Overview
+
+Build the primitives that phases 2-4 reuse: a CLI argument parser for `--wait-pid <pid>` and `--updated-to <version>`, a `spawn_detached_self` helper that calls `CreateProcessW` directly (no cmd.exe), and mutex-acquisition retry logic that activates only when `--wait-pid` was passed.
+
+## Requirements
+
+**Functional**
+- Parse `--wait-pid <u32>` and `--updated-to <version-string>` from `std::env::args` without breaking existing flags (`--diagnose`, `--apply-update`).
+- Expose `spawn_detached(exe: &Path, args: &[OsString]) -> io::Result<()>` that uses `CreateProcessW` with `CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`.
+- Expose `wait_for_parent_exit(pid: u32, timeout_ms: u32)` that uses `OpenProcess(SYNCHRONIZE)` + `WaitForSingleObject`. Returns silently on timeout (best-effort).
+- Mutex acquisition in `app::run` retries `CreateMutexW` for ~3 seconds (200ms backoff) ONLY when `--wait-pid` was present; preserves today's immediate-fail behavior for normal startup.
+
+**Non-functional**
+- No new external dependencies. All Win32 calls via the existing `windows = "0.58"` crate features.
+- Helper module ≤ ~120 lines total.
+
+## Architecture
+
+```
+src/
+├── update/
+│   └── handoff.rs   ← NEW: spawn_detached, wait_for_parent_exit, cleanup_stale_old_exes
+├── main.rs          ← parse --wait-pid early, call wait_for_parent_exit BEFORE app::run
+└── app.rs           ← run() reads a static "wait_pid_was_passed" flag, retries mutex if set
+```
+
+Rationale for `src/update/handoff.rs`: keeps low-level Win32 process/file ops alongside the update module that uses them most. `app.rs` and `main.rs` import it for restart + post-update bootstrap.
+
+## Related Code Files
+
+- **Create**: `src/update/handoff.rs`
+- **Modify**: `src/main.rs` (early arg parse + wait + flag handoff to app)
+- **Modify**: `src/update/mod.rs` (declare `pub mod handoff`)
+- **Modify**: `src/app.rs` (mutex retry loop, gated on flag from main)
+- **Modify**: `Cargo.toml` if a new `windows` feature is needed (likely `Win32_System_Threading` already covers `OpenProcess`/`WaitForSingleObject`/`CreateProcessW`)
+
+## Implementation Steps
+
+1. **Audit `windows` crate features.** Confirm `Win32_System_Threading` is in `Cargo.toml` (it is — line 31). Verify `CreateProcessW`, `STARTUPINFOW`, `PROCESS_INFORMATION` are accessible. Add `Win32_Storage_FileSystem` if not already present (needed for phase 3's `MoveFileExW`).
+
+2. **Create `src/update/handoff.rs`** with three pub fns:
+   - `pub fn spawn_detached(exe: &Path, args: &[OsString]) -> io::Result<()>`
+     - Build a wide-char command line: quoted exe path + space-joined args, NUL-terminated.
+     - `STARTUPINFOW` zero-initialized, `cb` set.
+     - `CreateProcessW(NULL, cmdline_wide.as_mut_ptr(), NULL, NULL, FALSE, CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP, NULL, NULL, &si, &pi)`.
+     - Close `pi.hProcess` and `pi.hThread` immediately (fire-and-forget).
+   - `pub fn wait_for_parent_exit(pid: u32, timeout_ms: u32)`
+     - `OpenProcess(SYNCHRONIZE, FALSE, pid)`. If it fails (parent already gone), return immediately.
+     - `WaitForSingleObject(h, timeout_ms)`. Ignore return value.
+     - `CloseHandle(h)`.
+   - `pub fn cleanup_stale_old_exes(current_exe: &Path)` (used by phase 4; stub here, fill in phase 4)
+     - Stub: returns `Ok(())`.
+
+3. **Modify `src/update/mod.rs`** to add `pub mod handoff;`.
+
+4. **Modify `src/main.rs`** — insert BEFORE `app::run()`:
+   ```rust
+   let wait_pid = args.iter()
+       .position(|a| a == "--wait-pid")
+       .and_then(|i| args.get(i + 1))
+       .and_then(|s| s.parse::<u32>().ok());
+   if let Some(pid) = wait_pid {
+       update::handoff::wait_for_parent_exit(pid, 5_000);
+   }
+   ```
+   Note: keep this AFTER `update::run_cli` so the legacy `--apply-update` path still short-circuits cleanly.
+
+5. **Modify `src/app.rs::run`** — gate mutex retry on whether `--wait-pid` appeared. Cheapest implementation: re-parse `std::env::args` once at the top of `run()`. Then around line 156:
+   ```rust
+   let retry_mutex = std::env::args().any(|a| a == "--wait-pid");
+   let _mutex = acquire_singleton_mutex(retry_mutex)?;  // new helper
+   ```
+   New helper `acquire_singleton_mutex(retry: bool)`:
+   - If `!retry`: today's behavior (fail immediately on `ERROR_ALREADY_EXISTS`).
+   - If `retry`: loop CreateMutexW → on `ALREADY_EXISTS`, `Sleep(200)` and retry. Budget 15 iterations = ~3 seconds. Log every retry. After budget exhausted, return error and exit cleanly.
+
+6. **Compile check.** `cargo build --release`. Fix any feature gaps. No behavior should change yet — `--wait-pid` arg is parsed but no caller passes it yet.
+
+## Success Criteria
+
+- [ ] `cargo build --release` succeeds with zero warnings beyond the existing `dead_code` allow.
+- [ ] Running the binary normally (no flags) behaves identically to today (mutex check is immediate, no retry).
+- [ ] Running the binary with `--wait-pid <pid-of-running-instance>` against a live instance: the new process waits ≤5s for old one to exit, then acquires the mutex within ~200ms of its release. Verifiable by killing the original after 2s and watching the new one continue.
+- [ ] `update::handoff::spawn_detached` smoke test: from a small one-off snippet in `main` (gated behind a never-used flag) verify CreateProcessW returns success and pid increments. Remove before commit.
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|---|---|
+| Wide-char cmdline construction has off-by-one / missing NUL | Hand-test with a path containing spaces; assert `OsStringExt::encode_wide` produces expected bytes |
+| `CREATE_NO_WINDOW | DETACHED_PROCESS` combination misbehaves on GUI subsystem binaries | Documented Windows behavior: for a GUI subsystem child, both flags are effectively no-ops (no console requested), but combining them is harmless. Tested by phase 5 |
+| Mutex retry loop hangs forever if budget logic wrong | Hard cap = 15 iterations × 200ms = 3.0s. After that, exit. Add log line per retry so a stuck loop is visible in `--diagnose` |
+| `OpenProcess(SYNCHRONIZE, ...)` returns access-denied for cross-session | Fallback: `WaitForSingleObject` simply isn't called; mutex retry compensates |

plans/260521-1530-silent-update-no-cmd/phase-02-restart-path-replace-restart-app-with-native-createprocessw.md

@@ -0,0 +1,113 @@
+---
+phase: 2
+title: "Restart path: replace restart_app with native CreateProcessW"
+status: complete
+priority: P1
+effort: "1h"
+dependencies: [1]
+---
+
+# Phase 2: Restart path: replace restart_app with native CreateProcessW
+
+## Overview
+
+Replace `src/app.rs::restart_app`'s `cmd.exe /c "timeout & start ..."` handoff with a direct `spawn_detached(current_exe, ["--wait-pid", our_pid])` call. The new instance handles the parent-exit wait itself using phase 1's helper; no timer needed.
+
+## Requirements
+
+**Functional**
+- Restart triggered from the tray menu produces zero console flash.
+- New instance acquires `Global\ClaudeCodeUsageBubble` mutex successfully every time.
+- Settings still flushed to disk before exit (preserve current `snap + save` defensive write).
+- Path-with-`%` defense becomes unnecessary (no cmd.exe); the check is removed.
+
+**Non-functional**
+- `restart_app` function shrinks from ~40 lines to ~25 lines.
+
+## Architecture
+
+```
+restart_app():
+  1. settings::save(snap)                          (unchanged)
+  2. exe = current_exe()                           (unchanged)
+  3. our_pid = GetCurrentProcessId()
+  4. handoff::spawn_detached(exe, [--wait-pid, our_pid])
+  5. on success: PostQuitMessage(0)
+  6. on failure: log error, do NOT quit
+```
+
+Mutex release is implicit on process exit — no explicit `ReleaseMutex` needed because the `_mutex` handle in `app::run` is dropped when `run()` returns after `PostQuitMessage`. `Drop` closes the handle, which releases the mutex.
+
+## Related Code Files
+
+- **Modify**: `src/app.rs::restart_app` (lines ~1378-1432)
+- **Remove**: the `RESTART_CREATE_NO_WINDOW` / `RESTART_DETACHED_PROCESS` constants (now in handoff.rs)
+- **Remove**: the `%`-rejection defense (no cmd.exe to exploit)
+- **Remove**: the `replace('"', "")` quote-stripping (handoff.rs handles quoting)
+
+## Implementation Steps
+
+1. **Read current `restart_app`** at `src/app.rs:1378-1432` to confirm exact bounds.
+
+2. **Rewrite `restart_app`** to:
+   ```rust
+   fn restart_app() {
+       // Defensive settings flush (unchanged)
+       let snap = lock_state().as_ref().map(|s| s.settings.clone());
+       if let Some(s) = snap {
+           settings::save(&s);
+       }
+
+       let exe = match std::env::current_exe() {
+           Ok(p) => p,
+           Err(e) => {
+               log::error!("restart: current_exe failed: {e}");
+               return;
+           }
+       };
+
+       let pid = unsafe { GetCurrentProcessId() };
+       let args = vec![
+           OsString::from("--wait-pid"),
+           OsString::from(pid.to_string()),
+       ];
+
+       match update::handoff::spawn_detached(&exe, &args) {
+           Ok(()) => {
+               log::info!("restart: spawned detached child, posting quit");
+               unsafe { PostQuitMessage(0) };
+           }
+           Err(e) => log::error!("restart: spawn failed: {e}"),
+       }
+   }
+   ```
+
+3. **Drop the two `RESTART_*` const declarations** above the function — they were specific to the old cmd.exe path. Phase 1's helper has its own.
+
+4. **Drop the `%`-rejection block** in the new `restart_app`. The brainstorm doc keeps the equivalent check in `install.rs` for defense-in-depth; here it's pure dead weight without cmd.exe.
+
+5. **Imports**: add `use std::ffi::OsString;` and `use windows::Win32::System::Threading::GetCurrentProcessId;` if not already in scope.
+
+6. **Compile check**: `cargo build --release`.
+
+7. **Manual smoke test**: run the binary, click Restart in the tray menu, verify:
+   - No console window flashes
+   - New instance appears within ~1s
+   - Old instance log shows "spawned detached child, posting quit"
+   - New instance log shows mutex acquired (via Phase 1's retry path)
+
+## Success Criteria
+
+- [ ] `cargo build --release` clean.
+- [ ] Manual restart from menu produces ZERO visible console window across 20 consecutive triggers.
+- [ ] New instance window appears within 1500ms of menu click.
+- [ ] Settings file (`settings.json`) shows updated mtime after restart, confirming defensive save still runs.
+- [ ] `restart_app` function is ≤25 lines.
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|---|---|
+| Mutex handle not yet dropped when child tries to acquire | Phase 1's `--wait-pid` + 5s `WaitForSingleObject` + 3s mutex retry covers race comfortably (8s total budget vs <1s actual parent exit) |
+| `PostQuitMessage` doesn't immediately exit; window-message pump may process more events | Phase 1 mutex retry tolerates up to 3s of overlap |
+| `current_exe()` returns a path that the child can't load (rare: deleted exe, fileshare disconnect) | Existing behavior preserved: log error, do not quit. User can manually retry |

plans/260521-1530-silent-update-no-cmd/phase-03-update-install-rename-move-native-spawn.md

@@ -0,0 +1,156 @@
+---
+phase: 3
+title: "Update install: rename + move + native spawn"
+status: complete
+priority: P1
+effort: "2h"
+dependencies: [1]
+---
+
+# Phase 3: Update install: rename + move + native spawn
+
+## Overview
+
+Replace `src/update/install.rs::begin`'s `cmd.exe /c "timeout & move & start ..."` handoff with native steps: `MoveFileExW` to rename the running exe sideways, `MoveFileExW` to move the staged exe into place, then `spawn_detached` of the new binary. Removes the only remaining cmd.exe invocation in the update flow.
+
+## Requirements
+
+**Functional**
+- Update install produces zero console flash.
+- New binary version starts after auto-update without user interaction.
+- SHA-256 verification continues to gate the swap (no swap on checksum mismatch).
+- On any failure step, the original exe must remain runnable (no half-state).
+
+**Non-functional**
+- `install.rs` net change ≈ -30 lines (cmd-quoting code is gone, replaced by short Win32 calls).
+- New code paths use the windows crate; no new dependencies.
+
+## Architecture
+
+```
+install::begin(http, release):
+  1. current = current_exe()
+  2. ensure_writable(current.parent())        (unchanged)
+  3. staging = stage_path()
+  4. reject_unsafe_path(current)              (kept for defense-in-depth; harmless now)
+  5. reject_unsafe_path(staging)
+  6. create_dir_all(staging.parent())
+  7. download(http, asset_url, staging, sha256)   (unchanged)
+  8. backup = current.with_file_name(format!("{}.old.{}", filename, pid))
+  9. MoveFileExW(current, backup, 0)          ← NEW: rename running exe sideways
+  10. MoveFileExW(staging, current, MOVEFILE_REPLACE_EXISTING)   ← NEW
+  11. our_pid = GetCurrentProcessId()
+  12. handoff::spawn_detached(current,
+        ["--wait-pid", our_pid, "--updated-to", version_str])    ← NEW
+  13. return Ok(())
+```
+
+Caller (`app.rs` Apply action) is responsible for `PostQuitMessage` after `begin` returns Ok — same as today.
+
+### Rollback semantics
+
+| Step that failed | State | Recovery |
+|---|---|---|
+| 7 (download) | Original exe untouched | Existing behavior: error surfaced, user retries |
+| 9 (rename current → backup) | Original exe untouched | Surface `Error::NotWritable`; do not proceed |
+| 10 (move staging → current) | Original exe is at backup path, current path empty | Best-effort revert: rename backup back to current; surface error |
+| 10 + revert (both fail) | Original at backup path; current path empty; user has no runnable binary at the install location | **Per Validation Session 1 decision:** show a Windows `MessageBoxW` (MB_OK \| MB_ICONERROR) telling the user where the backup is, then exit. Message: "Update failed. Your original binary is saved as `{backup_path}`. Please rename it back to `{exe_name}` manually." |
+| 12 (spawn child) | New exe at correct path, but app didn't restart | Log + tray balloon "Update applied; restart manually". Rare — `CreateProcessW` on a fresh fully-written exe almost never fails |
+
+<!-- Updated: Validation Session 1 - Rollback escalation MessageBox added -->
+
+### Rollback escalation helper
+
+Add a private `surface_rollback_failure(backup_path: &Path, target_name: &str)` helper that calls `MessageBoxW` with `MB_OK | MB_ICONERROR` and the localized message. Adds a new `LocaleStrings` field `update_rollback_failed_body` parameterized with `{backup_path}` and `{exe_name}` (Rust `format!` substitution at call site). The plain MessageBox uses the Win32 dialog, so no console can flash.
+
+## Related Code Files
+
+- **Modify**: `src/update/install.rs::begin`
+- **Modify**: `src/update/install.rs::spawn_handoff` → REMOVED entirely
+- **Modify**: `src/update/install.rs` imports (drop `os::windows::process::CommandExt`, `process::{Command, Stdio}`; add `MoveFileExW`, `MOVEFILE_REPLACE_EXISTING`, `GetCurrentProcessId`, `MessageBoxW`, `MB_OK`, `MB_ICONERROR`)
+- **Modify**: `src/update/mod.rs::Error` — add `Error::SwapFailed(String)` variant if MoveFileExW failures don't fit existing variants cleanly
+- **Modify**: `src/i18n/mod.rs::LocaleStrings` — add `update_rollback_failed_body: String` (also belongs to Phase 4 i18n group, but Phase 3 is the consumer)
+
+## Implementation Steps
+
+1. **Read current `install.rs::begin` + `spawn_handoff`** to confirm exact bounds (lines 19-36 + 99-121).
+
+2. **Decide path-safety policy**: keep `reject_unsafe_path` (the `%`-check) as defense-in-depth even though no cmd.exe runs. Update the function-level comment to reflect new reality (kept for paranoia, not strict need).
+
+3. **Add `swap_and_spawn` private helper** (replaces `spawn_handoff`):
+   ```rust
+   fn swap_and_spawn(
+       source: &Path,
+       target: &Path,
+       version: &super::release::Version,
+   ) -> Result<(), super::Error> {
+       let backup = backup_path(target);
+       move_file(target, &backup, 0)?;
+       if let Err(e) = move_file(source, target, MOVEFILE_REPLACE_EXISTING) {
+           // Best-effort revert
+           let _ = move_file(&backup, target, MOVEFILE_REPLACE_EXISTING);
+           return Err(e);
+       }
+       let pid = unsafe { GetCurrentProcessId() };
+       let args = vec![
+           OsString::from("--wait-pid"),
+           OsString::from(pid.to_string()),
+           OsString::from("--updated-to"),
+           OsString::from(format!("{}.{}.{}", version.major, version.minor, version.patch)),
+       ];
+       super::handoff::spawn_detached(target, &args)
+           .map_err(super::Error::Io)
+   }
+
+   fn move_file(src: &Path, dst: &Path, flags: MOVE_FILE_FLAGS) -> Result<(), super::Error> {
+       let src_w = to_utf16_nul(src);
+       let dst_w = to_utf16_nul(dst);
+       let r = unsafe {
+           MoveFileExW(
+               PCWSTR::from_raw(src_w.as_ptr()),
+               PCWSTR::from_raw(dst_w.as_ptr()),
+               flags,
+           )
+       };
+       r.ok().map_err(|e| super::Error::SwapFailed(e.to_string()))
+   }
+
+   fn backup_path(target: &Path) -> PathBuf {
+       let pid = unsafe { GetCurrentProcessId() };
+       let mut p = target.to_owned();
+       let fname = target.file_name().map(|s| s.to_string_lossy().into_owned())
+           .unwrap_or_else(|| "exe".to_string());
+       p.set_file_name(format!("{fname}.old.{pid}"));
+       p
+   }
+   ```
+   Use the existing `os::to_utf16_nul` helper for wide-char conversion (already used in `app.rs::run`).
+
+4. **Rewrite `begin`** to call `swap_and_spawn(&staging, &current, &release.version)` instead of `spawn_handoff(&staging, &current)`. Pass the version from the `Release` struct already in hand.
+
+5. **Add `Error::SwapFailed(String)` variant** to `src/update/mod.rs` if no existing variant fits the move-failure semantics. The `#[error(...)]` message should be `"file swap failed: {0}"`.
+
+6. **Remove `spawn_handoff` function** entirely. Remove now-unused imports (`std::os::windows::process::CommandExt`, `Command`, `Stdio`, `CREATE_NO_WINDOW`, `DETACHED_PROCESS` constants).
+
+7. **Compile check**: `cargo build --release`. Address any feature-flag gaps (likely need `Win32_Storage_FileSystem` added to Cargo `windows` features for `MoveFileExW`).
+
+8. **Test rollback path manually**: write a temp .exe to staging that is read-only or has wrong permissions to force step 10 to fail; verify backup is restored and original is still runnable.
+
+## Success Criteria
+
+- [ ] `cargo build --release` clean.
+- [ ] Manual auto-update from a test-tagged v0.1.99 produces ZERO visible console window across 5 consecutive runs.
+- [ ] SHA-256 mismatch still rejects the swap (verify by tampering with a downloaded asset before swap).
+- [ ] On forced step-10 failure (simulated): backup is restored, original binary still launches.
+- [ ] `spawn_handoff` function no longer exists in the codebase (`grep -r spawn_handoff src/` returns empty).
+- [ ] No `cmd.exe` string remains in `src/update/install.rs`.
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|---|---|
+| `MoveFileExW` fails because AV holds a handle on the running exe | Surface `Error::SwapFailed`; user retries. Rare on Defender (which scans on read, not perpetually) |
+| Two updates triggered in quick succession leave two `.old.<pid>` files | Phase 4 cleanup at startup handles this — glob removes ALL `.old.*` siblings |
+| User's install dir is on a network share where renaming-while-open is forbidden | Existing `ensure_writable` probe catches read-only / no-write cases. Network FS oddities → surface as `NotWritable` |
+| `MoveFileExW` with `REPLACE_EXISTING` on a non-NTFS volume | Works on FAT32 (per MS docs); the renaming-while-running concern is NTFS-specific but step 9 always renames an empty (just-emptied) path in step 10 |
+| Release-build inlines + LTO breaks symbol-level rollback assumption | Functional rollback path is exercised by phase 5's manual test under release profile |

plans/260521-1530-silent-update-no-cmd/phase-04-cleanup-tray-notification.md

@@ -0,0 +1,165 @@
+---
+phase: 4
+title: "Cleanup + tray notification"
+status: complete
+priority: P2
+effort: "1.5h"
+dependencies: [1, 3]
+---
+
+# Phase 4: Cleanup + tray notification
+
+## Overview
+
+Two additions that make the silent update visible to the user without being intrusive: (a) startup cleanup of stale `bubble.exe.old.<pid>` files from previous updates, and (b) a tray balloon "Updated to vX.Y.Z" on first launch after auto-update (driven by the `--updated-to` flag passed by phase 3).
+
+<!-- Updated: Validation Session 1 - i18n approach corrected to match TOML struct-field architecture -->
+
+## Requirements
+
+**Functional**
+- On every startup, scan `current_exe().parent()` for files matching `<exe-stem>.exe.old.*` and remove them silently. Errors logged at debug level, never surfaced to user.
+- When `--updated-to vX.Y.Z` is passed AND the tray subsystem is initialized, show a balloon notification with localized title + body.
+- Add **3 new fields** to `LocaleStrings` (`src/i18n/mod.rs:23-71`): `update_applied_title`, `update_applied_body`, `update_rollback_failed_body` (the last one is consumed by Phase 3 but the i18n change belongs to this phase's pattern). Body strings use Rust `format!` at call site — TOML strings hold raw text (e.g. body = `"Updated to v"`, then call site does `format!("{}{}", strings.update_applied_body, version)`). Choice of suffix vs prefix vs `{}` placeholder substitution is dialect-sensitive; use literal positional substitution via `format!` because TOML doesn't support template placeholders the i18n loader recognizes.
+- Translate the 3 new strings in all **8 existing locale files**: `src/i18n/locales/{en,nl,es,fr,de,ja,ko,zh-TW}.toml`.
+
+**Non-functional**
+- Cleanup runs in the foreground startup path (it's a few file operations — no need for a thread).
+- Balloon uses `NIIF_INFO` (blue info icon) not `NIIF_WARNING` (yellow triangle). The existing `tray::notify` (`src/tray/mod.rs:85`) hardcodes `NIIF_WARNING` and has **2 callers** (`src/app.rs:831` usage threshold, `src/app.rs:859` token expired) — both correctly semantically "warning". Rename existing `notify` → `notify_warning`; add new sibling `notify_info`.
+
+## Architecture
+
+### Cleanup
+
+Triggered from `app::run` after tray icons register but before main message loop. Implementation lives in `update::handoff::cleanup_stale_old_exes` (stub was added in phase 1).
+
+```rust
+pub fn cleanup_stale_old_exes(current_exe: &Path) {
+    let Some(dir) = current_exe.parent() else { return };
+    let Some(stem) = current_exe.file_name() else { return };
+    let prefix = format!("{}.old.", stem.to_string_lossy());
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        if name.to_string_lossy().starts_with(&prefix) {
+            if let Err(e) = std::fs::remove_file(entry.path()) {
+                log::debug!("cleanup_stale_old_exes: remove {:?} failed: {e}", entry.path());
+            }
+        }
+    }
+}
+```
+
+### Balloon notification
+
+Parse `--updated-to` argument early (alongside `--wait-pid` in main.rs), stash it on `AppState`. After the tray icons are registered for the first time, if the version string is present, call `tray::notify_info(hwnd, kind, title, body)`.
+
+```rust
+// main.rs (after --wait-pid parse):
+let updated_to = args.iter()
+    .position(|a| a == "--updated-to")
+    .and_then(|i| args.get(i + 1))
+    .cloned();
+// pass into app::run via existing arg-threading or a static OnceLock
+```
+
+```rust
+// tray/mod.rs: split notify into two variants
+pub fn notify_info(owner: HWND, kind: IconKind, title: &str, body: &str) {
+    notify_inner(owner, kind, title, body, NIIF_INFO);
+}
+pub fn notify_warning(owner: HWND, kind: IconKind, title: &str, body: &str) {
+    notify_inner(owner, kind, title, body, NIIF_WARNING);
+}
+fn notify_inner(owner: HWND, kind: IconKind, title: &str, body: &str, flags: NOTIFY_ICON_INFOTIP_FLAGS) {
+    // existing body, but use `flags` instead of hardcoded NIIF_WARNING
+}
+```
+
+If `tray::notify` has only one caller today (which the brainstorm scout suggested), just rename it to `notify_warning` and add `notify_info`.
+
+## Related Code Files
+
+- **Modify**: `src/update/handoff.rs::cleanup_stale_old_exes` (fill in phase-1 stub)
+- **Modify**: `src/app.rs::run` (call cleanup; call tray::notify_info after tray registration if updated_to is set)
+- **Modify**: `src/app.rs:831,859` (rename `tray::notify` → `tray::notify_warning` at both existing call sites)
+- **Modify**: `src/main.rs` (parse `--updated-to`, stash for app)
+- **Modify**: `src/tray/mod.rs` — rename `notify` → `notify_warning`; add `notify_info`; extract shared `notify_inner(... flags: NOTIFY_ICON_INFOTIP_FLAGS)`
+- **Modify**: `src/i18n/mod.rs::LocaleStrings` — add 3 new `String` fields: `update_applied_title`, `update_applied_body`, `update_rollback_failed_body`
+- **Modify**: `src/i18n/locales/{en,nl,es,fr,de,ja,ko,zh-TW}.toml` — 8 files, add the 3 new keys to each. Use machine translation for non-English where idiomatic translation unavailable; flag with comment for native-speaker review later
+
+## Implementation Steps
+
+1. **i18n: add 3 new fields to `LocaleStrings`** in `src/i18n/mod.rs:23-71`. After the existing `threshold_95_body` field, add:
+   ```rust
+   pub update_applied_title: String,
+   pub update_applied_body: String,
+   pub update_rollback_failed_body: String,
+   ```
+
+2. **Translate in 8 locale files** (`src/i18n/locales/{en,nl,es,fr,de,ja,ko,zh-TW}.toml`). Suggested English values (mirror style of existing `token_expired_title`/`token_expired_body`):
+   ```toml
+   update_applied_title = "Update applied"
+   update_applied_body = "Updated to v"          # call site appends version string
+   update_rollback_failed_body = "Update failed. Your original binary is saved as "  # call site appends backup path + suffix
+   ```
+   For non-English, machine-translate body+title, leave the trailing space/prefix structure intact. Comment in PR description: "Translations machine-generated; flagged for native-speaker review".
+
+3. **Split `tray::notify`** (`src/tray/mod.rs:85-94`) into:
+   - rename existing fn → `notify_warning` (preserves current `NIIF_WARNING` semantics)
+   - extract shared `fn notify_inner(owner, kind, title, body, flags: NOTIFY_ICON_INFOTIP_FLAGS)`
+   - add new `pub fn notify_info(owner, kind, title, body)` that calls `notify_inner(..., NIIF_INFO)`
+   Update both existing call sites (`src/app.rs:831,859`) to call `notify_warning` instead of `notify`.
+
+4. **Fill in `cleanup_stale_old_exes`** per architecture section.
+
+5. **Parse `--updated-to` in main.rs**, thread it into `app::run`. Two options:
+   - Pass as a new arg to `pub fn run(updated_to: Option<String>)`.
+   - Store in a `OnceLock<Option<String>>` inside `update::handoff`, set in main, read in app.
+   Pick the simpler one — direct function arg is preferred unless `run`'s signature is already heavily used elsewhere.
+
+6. **In `app::run`** after tray icons register and the main window message loop is about to enter:
+   ```rust
+   if let Some(v) = updated_to.as_ref() {
+       let strings = i18n.strings();
+       let title = strings.update_applied_title.clone();
+       let body = format!("{}{}", strings.update_applied_body, v);
+       tray::notify_info(msg_hwnd, IconKind::ClaudeCode, &title, &body);
+   }
+   update::handoff::cleanup_stale_old_exes(&exe);
+   ```
+   Use `ClaudeCode` IconKind because it's always present when Claude is enabled (default). If user disabled Claude and enabled only Codex, fall back to Codex kind. Cheapest: try ClaudeCode first; if `tray::notify_info` fails silently, no harm.
+
+7. **Compile check**: `cargo build --release`.
+
+8. **Manual test cleanup**:
+   - Create a file `claude-code-usage-bubble.exe.old.1234` next to the running binary.
+   - Launch the app.
+   - Verify the file is gone after launch.
+
+9. **Manual test notification**:
+   - Launch with `--updated-to 9.9.9` flag.
+   - Verify Windows notification appears with the title + version body.
+   - Verify it uses the blue info icon, not yellow warning.
+
+## Success Criteria
+
+- [ ] `cargo build --release` clean.
+- [ ] Stale `.old.<pid>` files in install dir are removed on every startup (idempotent).
+- [ ] Launching with `--updated-to vX.Y.Z` shows a tray balloon with localized title and version body.
+- [ ] Balloon icon is blue info (NIIF_INFO), not yellow warning.
+- [ ] Launching WITHOUT `--updated-to` shows no balloon (existing behavior preserved).
+- [ ] All 8 locale TOML files (`en, nl, es, fr, de, ja, ko, zh-TW`) contain the 3 new keys (`update_applied_title`, `update_applied_body`, `update_rollback_failed_body`); `cargo build --release` would fail to deserialize otherwise.
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|---|---|
+| Cleanup removes a `.old.<pid>` file that another running instance still depends on | Impossible by construction: only the spawning instance writes `.old.<pid>` and it has already exited by the time the new instance runs cleanup |
+| Glob false-positive (e.g. a user-created file matching the pattern) | Pattern requires `.old.` literal AND a numeric pid-like suffix is implied; we don't pattern-match the suffix strictly. Risk is theoretical; user-created files matching `claude-code-usage-bubble.exe.old.*` is extremely unlikely |
+| Tray balloon doesn't show because NIM_MODIFY runs before NIM_ADD completes | Defer the `notify_info` call by one tick (PostMessage to message loop) if testing shows races. Likely unnecessary because tray icons register synchronously |
+| i18n loader is struct-field based, no template substitution at the loader level | Confirmed by Validation Session 1: append/prepend the version via Rust `format!` at the call site. TOML strings are static text fragments only |
+| Translations diverge from idiomatic expression in non-English locales | Machine-translate for first cut, mark "FIXME: review by native speaker" in commit message. Subsequent crowd-sourced fixes are out of this plan's scope |

plans/260521-1530-silent-update-no-cmd/phase-05-manual-end-to-end-verification.md

@@ -0,0 +1,104 @@
+---
+phase: 5
+title: "Manual end-to-end verification"
+status: pending
+priority: P2
+effort: "1h"
+dependencies: [1, 2, 3, 4]
+---
+
+# Phase 5: Manual end-to-end verification
+
+## Overview
+
+Functional sign-off across all changed code paths. No unit tests added (the changed surface is Win32-heavy and effectively integration territory); instead, a documented manual checklist that the maintainer runs once before committing.
+
+## Requirements
+
+**Functional**
+- All success criteria from phases 1-4 verified on a real Windows machine (Win11 preferred, Win10 as secondary if available).
+- Build artifact runs without errors when launched plainly (no flags).
+- No regression in existing update / restart / refresh paths.
+
+**Non-functional**
+- Verification log saved as a section in `phase-05` after run, with date + outcome per item.
+
+## Test Matrix
+
+### Group A: Restart path (phase 2)
+
+| # | Step | Expected |
+|---|---|---|
+| A1 | Launch binary, open right-click menu, click "Restart" | No console flash; new instance appears within 1.5s |
+| A2 | Repeat A1 twenty times back-to-back | Zero flashes observed; settings.json mtime updates each time |
+| A3 | Launch with `--diagnose`, click Restart, inspect `%TEMP%\claude-code-usage-bubble.log` | Shows "restart: spawned detached child, posting quit" and new instance shows mutex acquired (within 200ms of the wait completing) |
+
+### Group B: Update install path (phase 3)
+
+Setup: tag a test release `v0.1.99` via the existing GitHub Actions workflow (per `plans/260516-1730-github-release-auto-update`). Bump local `Cargo.toml` back to `v0.1.0` before running. Build the local v0.1.0 with this plan's changes.
+
+| # | Step | Expected |
+|---|---|---|
+| B1 | Launch v0.1.0 build, set update channel to "Hourly", manually trigger "Check for updates" | "Update available" shown; click "Apply" |
+| B2 | During B1 apply | No console flash; new v0.1.99 instance appears |
+| B3 | After B1/B2 | Tray balloon "Update applied — Updated to v0.1.99" appears (blue info icon) |
+| B4 | Inspect install dir after B1/B2 | NO `.old.*` files remain (cleanup removed them) |
+| B5 | Repeat B1 four more times (after re-tagging v0.1.100 etc.) | Zero flashes across 5 update cycles |
+| B6 | Tamper test: edit downloaded asset on disk before swap (would require pausing between download and swap — gate via `--diagnose` log timestamps) | SHA-256 mismatch raises `Error::ChecksumMismatch`; swap is NOT performed; original binary still runs |
+| B7 | Rollback test: make staging path read-only or simulate step-10 failure | Backup restored; original binary still runs after a manual restart |
+
+### Group C: Cleanup + notification (phase 4)
+
+| # | Step | Expected |
+|---|---|---|
+| C1 | Manually drop `claude-code-usage-bubble.exe.old.9999` next to the running binary; launch app | Stale file is removed within 1s of launch |
+| C2 | Launch app with `--updated-to 9.9.9` arg from a terminal | Tray balloon shows title + "Updated to v9.9.9" in current UI language |
+| C3 | Repeat C2 with each supported locale | Each locale shows correct translation |
+| C4 | Launch normally (no `--updated-to`) | No balloon appears |
+
+### Group D: Regression smoke
+
+| # | Step | Expected |
+|---|---|---|
+| D1 | Launch binary fresh (cold start, no flags) | Bubble appears in <2s; usage refresh fires once; tray icon registers |
+| D2 | Open settings (right-click → Language → switch), confirm restart happens | Restart works without flash (this is the same `restart_app` path) |
+| D3 | Disable auto-update ("Disabled"), wait 30s, re-enable Hourly | No state corruption; check timer resets |
+| D4 | Run with `--diagnose --apply-update <some-path> <pid>` (legacy compat) | Returns exit code 0 cleanly (per `update::install::run_cli`) — unchanged |
+
+## Implementation Steps
+
+1. Build `cargo build --release`.
+2. Copy `target/release/claude-code-usage-bubble.exe` to `%LOCALAPPDATA%\ClaudeCodeUsageBubble\` (fresh test directory).
+3. Run through Test Matrix A → B → C → D in order.
+4. For each test row, record outcome (PASS/FAIL + notes) in the Verification Log section below.
+5. If any FAIL: open an issue describing the failure, do NOT mark phase complete.
+6. If all PASS: mark phase complete, commit changes following project commit conventions (no `chore:` or `docs:` per CLAUDE.md).
+
+## Success Criteria
+
+- [ ] All Group A tests PASS.
+- [ ] All Group B tests PASS (B6 + B7 may be skipped if test scaffolding too costly; document as such).
+- [ ] All Group C tests PASS.
+- [ ] All Group D tests PASS.
+- [ ] Verification Log filled in with date + outcomes.
+- [ ] No console flash observed across the entire test session.
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|---|---|
+| Manual testing skips Group B because tagging real releases is annoying | Alternative: build two local copies (v0.1.0 + v0.1.99), set up a local HTTP server with a fake GitHub-Releases-shaped JSON, point the app at it via a debug flag. Out of scope for this plan but noted |
+| "Flash" is subjective at 60Hz | Record screen with OBS at 60fps for one test run, scrub frame-by-frame to confirm zero console window appearance |
+| Win10-only flash regression (only test on Win11) | Document Win10 testing as "best effort"; primary target is Win11. Note Win10 result in Verification Log |
+
+## Verification Log
+
+<!-- Fill in after running the test matrix -->
+
+### Session 1 — TBD
+- Group A: TBD
+- Group B: TBD
+- Group C: TBD
+- Group D: TBD
+- Flash observed: TBD
+- Notes: TBD

plans/260521-1530-silent-update-no-cmd/plan.md

@@ -0,0 +1,96 @@
+---
+title: "Silent in-app update + restart (no cmd.exe)"
+description: "Replace cmd.exe handoff in update install + app restart paths with native Win32 (MoveFileExW + CreateProcessW) so no terminal window can ever flash. Add tray-balloon notification after auto-updates."
+status: in_progress
+priority: P2
+branch: "main"
+tags: ["update", "restart", "win32", "ux"]
+blockedBy: []
+blocks: []
+created: "2026-05-21T07:43:16.332Z"
+createdBy: "ck:plan"
+source: skill
+---
+
+# Silent in-app update + restart (no cmd.exe)
+
+## Overview
+
+Two paths today spawn `cmd.exe /c "timeout ... & start ..."` for update install (`src/update/install.rs::begin`) and app restart (`src/app.rs::restart_app`). Combination of `CREATE_NO_WINDOW | DETACHED_PROCESS` + inner `start ""` can still flash a console window on some Windows configs. This plan replaces both with native `MoveFileExW` + `CreateProcessW` (the main exe is `windows_subsystem = "windows"`, so direct spawn never allocates a console). Also wires a tray balloon "Updated to vX.Y.Z" on first launch after an auto-update.
+
+Brainstorm context: [`plans/reports/brainstormer-260521-1530-silent-update-no-cmd.md`](../reports/brainstormer-260521-1530-silent-update-no-cmd.md).
+
+Supersedes the cmd.exe mechanism decision in [`260518-0945-menu-restart-button`](../260518-0945-menu-restart-button/plan.md) (that plan picked cmd.exe deliberately, modeled on `update::install`; this plan replaces both call sites with the native path).
+
+## Phases
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [Foundation: CLI flags + native spawn helper + mutex retry](./phase-01-foundation-cli-flags-native-spawn-helper-mutex-retry.md) | Complete |
+| 2 | [Restart path: replace restart_app with native CreateProcessW](./phase-02-restart-path-replace-restart-app-with-native-createprocessw.md) | Complete |
+| 3 | [Update install: rename + move + native spawn](./phase-03-update-install-rename-move-native-spawn.md) | Complete |
+| 4 | [Cleanup + tray notification](./phase-04-cleanup-tray-notification.md) | Complete |
+| 5 | [Manual end-to-end verification](./phase-05-manual-end-to-end-verification.md) | Pending (user-driven) |
+
+## Key contracts (must hold across plan)
+
+| Contract | Source today | Invariant |
+|---|---|---|
+| Singleton mutex name | `app.rs` `APP_MUTEX_NAME` = `Global\ClaudeCodeUsageBubble` | New instance must wait for parent to release before acquiring |
+| Main binary subsystem | `main.rs:1` `#![windows_subsystem = "windows"]` | Direct spawn allocates no console |
+| Asset filename | `release.rs:7` `claude-code-usage-bubble.exe` | Unchanged |
+| SHA-256 verification | `install.rs:64-73` | Unchanged — still verified before swap |
+| Settings save on shutdown | `app.rs::restart_app` snap+save | Preserved in new restart helper |
+
+## Dependencies
+
+No cross-plan dependencies. Related (superseded mechanism): `260518-0945-menu-restart-button`.
+
+## Out of Scope
+
+- `src/usage/refresh.rs` CLI spawns (`claude.cmd`, `codex.cmd`, `powershell.exe`, `wsl.exe`) — already use `CREATE_NO_WINDOW`; tracked for follow-up.
+- `src/creds/wsl_bridge.rs` `wsl.exe` calls — same.
+- Code signing / SmartScreen suppression — separate roadmap item.
+- Cross-platform restart/update — Windows-only by design.
+
+## Unresolved Questions
+
+None.
+
+## Validation Log
+
+### Session 1 — 2026-05-21
+
+#### Verification Results
+- **Tier**: Full (5 phases)
+- **Claims checked**: 8
+- **Verified**: 6 | **Failed**: 2 | **Unverified**: 0
+- Verified: `app.rs:155` mutex creation; `app.rs:1378-1432` restart_app bounds; `install.rs:42-48` `--apply-update` exit-clean handler; `install.rs:99-121` `spawn_handoff`; `os::to_utf16_nul` exists and is in use; `windows = 0.58` features in Cargo.toml include `Win32_System_Threading` but NOT `Win32_Storage_FileSystem` (phase 3 must add it).
+- Failed: (V1) phase 4 said `tray::notify` has "one current caller" — actually 2 (`app.rs:831`, `app.rs:859`); (V2) phase 4 said i18n uses key-based template lookup with `{v}` placeholder — actually uses struct-field-based `LocaleStrings` with TOML, no template engine.
+
+#### Decisions
+
+1. **i18n approach: add 3 fields to `LocaleStrings` + translate 8 locale TOML files; use Rust `format!` at call site for version substitution.**
+   Reason: existing pattern is struct-field-based via `include_str!` of `src/i18n/locales/{en,nl,es,fr,de,ja,ko,zh-TW}.toml`. No template substitution at the loader level.
+   → Propagated to `phase-04-cleanup-tray-notification.md`: Requirements, Related Code Files, Implementation Steps, Success Criteria, Risk Assessment all updated.
+
+2. **Rollback failure escalation: Windows `MessageBoxW` (MB_OK | MB_ICONERROR) when MoveFileExW step 10 AND best-effort revert both fail.**
+   Reason: silent failure here would orphan the user — they'd have no exe at install path. A clear modal tells them where the backup is (`bubble.exe.old.<pid>`).
+   → Propagated to `phase-03-update-install-rename-move-native-spawn.md`: rollback table extended; imports list updated; new helper `surface_rollback_failure` added; new `LocaleStrings` field `update_rollback_failed_body` added to phase 4's i18n work.
+
+3. **Stuck-parent fallback: accept 8s total budget (5s `WaitForSingleObject` + 3s mutex retry), then exit cleanly. No `TerminateProcess`.**
+   Reason: forcing process termination would defeat the `settings::save` defensive flush guarantee. The 8s ceiling is generous for normal Windows scheduling; if a real hang persists, user can manually kill old process via Task Manager — acceptable failure mode.
+   → No phase file change needed. Phase 1 budget numbers (5s + 3s) already match.
+
+4. **Auto-update timing: apply when check fires, no idle-window deferral.**
+   Reason: matches user's brainstorm-phase choice ("Fully silent auto-update"). Idle detection adds complexity (state tracking, defer-budget, defer-never-applies edge case) for marginal UX gain — bubble flicker during ~1s restart is acceptable.
+   → No phase file change needed.
+
+#### Whole-Plan Consistency Sweep
+- Files reread: `plan.md`, `phase-01-…md`, `phase-02-…md`, `phase-03-…md`, `phase-04-…md`, `phase-05-…md`
+- Decision deltas checked: 4
+- Reconciled stale references: 2
+  - Phase 4 i18n section rewritten from key-based template to struct-field + Rust `format!`
+  - Phase 4 `tray::notify` caller count corrected from "1" to "2" with explicit file:line citations
+- Cross-phase touchpoints verified: Phase 3 adds `update_rollback_failed_body` to `LocaleStrings`, Phase 4 owns the full i18n change (3 fields + 8 TOMLs) — both phases reference the same struct, consistent
+- Unresolved contradictions: 0

plans/reports/brainstormer-260521-1530-silent-update-no-cmd.md

@@ -0,0 +1,124 @@
+# Silent in-app update + restart (no cmd.exe)
+
+**Date:** 2026-05-21
+**Author:** brainstormer
+**Status:** approved (ready for `/ck:plan`)
+
+## Problem
+
+User sees an occasional flash terminal window. Two paths today spawn `cmd.exe /c "timeout ... & start ..."` for update install and app restart, with `CREATE_NO_WINDOW | DETACHED_PROCESS`. Combination of those flags + the inner `start ""` invocation can still emit a brief console flash on some Windows configs (Defender hooks, conhost init, AV inspection). Goal: zero-flash, fully silent auto-update + restart, with in-app notification.
+
+## Scope
+
+**In scope**
+- `src/update/install.rs::begin` — kill cmd.exe handoff
+- `src/app.rs::restart_app` — kill cmd.exe handoff
+- New CLI flag `--wait-pid <pid>` on the main binary (cooperates with itself across update)
+- Cleanup of stale `bubble.exe.old.*` siblings at startup
+- Tray balloon "Updated to vX.Y.Z" on first run after auto-update
+
+**Out of scope (split as follow-up)**
+- `src/usage/refresh.rs` CLI spawns (`claude.cmd`, `codex.cmd`, `powershell.exe`, `wsl.exe`) — already use `CREATE_NO_WINDOW`; address separately if flash persists after this change
+- `src/creds/wsl_bridge.rs` `wsl.exe` calls — same reasoning
+
+## Approaches evaluated
+
+| Approach | Decision | Rationale |
+|---|---|---|
+| A: Native rename + direct `CreateProcessW` + `--wait-pid` | **CHOSEN** | Zero cmd.exe ⇒ zero flash possible; single-binary preserved; matches existing Win32 style; recoverable on interrupt |
+| B: Helper-exe pattern (`bubble-updater.exe`) | rejected | Reverses deliberate "no helper exe" decision (`src/update/install.rs:3-5`); release-pipeline change; helper bootstrap problem |
+| C: NTFS POSIX atomic replace (`FileRenameInfoEx`) | rejected | Obscure API; harder failure modes with AV / image-protection; not worth the elegance trade-off |
+
+## Final design — Approach A
+
+### Update install flow
+
+```
+1. fetch_latest()                              (unchanged — pure HTTP via WinHTTP)
+2. download(release_url, staging_path)         (unchanged — sha256 verify)
+3. rename current.exe -> current.exe.old.<pid> (MoveFileExW, allowed while running)
+4. move staging.exe   -> current.exe          (MoveFileExW REPLACE_EXISTING)
+5. settings::save(snap)                        (defensive flush, unchanged)
+6. release singleton mutex                     (explicit ReleaseMutex + CloseHandle)
+7. CreateProcessW(current.exe, "--wait-pid <our_pid> --updated-to vX.Y.Z",
+                  CREATE_NO_WINDOW | DETACHED_PROCESS)
+8. PostQuitMessage(0)
+```
+
+### Restart flow (settings-change path)
+
+```
+1. settings::save(snap)
+2. CreateProcessW(current.exe, "--wait-pid <our_pid>",
+                  CREATE_NO_WINDOW | DETACHED_PROCESS)
+3. release singleton mutex
+4. PostQuitMessage(0)
+```
+
+### New instance startup additions
+
+```rust
+// Before acquiring Global\ClaudeCodeUsageBubble mutex:
+if let Some(parent_pid) = parse_wait_pid_arg() {
+    let h = OpenProcess(SYNCHRONIZE, FALSE, parent_pid)?;
+    WaitForSingleObject(h, 5000);              // 5s cap; proceed regardless
+    CloseHandle(h);
+}
+
+// After main window is up:
+cleanup_old_exes(current_dir, "bubble.exe.old.*");
+
+if let Some(version) = parse_updated_to_arg() {
+    tray::show_balloon(t!("update.toast.updated_to", v = version));
+}
+```
+
+### Why `--wait-pid` instead of cmd's `timeout /t 2`
+
+- `timeout` is a cmd.exe builtin; using it requires cmd.exe.
+- `WaitForSingleObject` on the parent process handle is the canonical Win32 idiom: zero delay if parent already exited, exact timing when it actually exits, no console involvement.
+- Bonus: removes the magic "2 seconds is enough" guess.
+
+### Path safety
+
+The current `reject_unsafe_path` (`%` rejection) becomes unnecessary — no cmd.exe to expand `%var%`. Keep the function for defense-in-depth; revisit in code review.
+
+## Files touched
+
+| File | Change |
+|---|---|
+| `src/update/install.rs` | Replace `spawn_handoff` with `swap_and_spawn` using `MoveFileExW` + `CreateProcessW`; drop `cmd` arg-quoting code |
+| `src/update/mod.rs` | Add `Error::SwapFailed` variant if needed |
+| `src/app.rs::restart_app` | Replace cmd.exe spawn with `CreateProcessW` + mutex release ordering |
+| `src/app.rs` | Add CLI flag parsing for `--wait-pid` and `--updated-to`; cleanup pass for `.old.*` siblings; balloon tray call on successful update boot |
+| `src/main.rs` | Wire `--wait-pid` into the early-startup mutex-acquisition path (BEFORE `update::run_cli` check) |
+| `src/tray/mod.rs` (or `tray/badge.rs`) | Confirm `Shell_NotifyIconW` with `NIF_INFO` balloon is supported by current tray code; add helper if missing |
+| `src/i18n/*` | New string keys: `update.toast.updated_to` |
+
+## Risks + mitigations
+
+| Risk | Mitigation |
+|---|---|
+| `MoveFileExW` rename fails (NTFS permission denied, AV scanner holding handle) | Surface `Error::NotWritable` to user; do NOT proceed to step 4 (still recoverable — original exe untouched at this point) |
+| New instance crashes before clearing old exe ⇒ `.old.*` accumulates | Cleanup glob `bubble.exe.old.*` on every startup is idempotent and cheap |
+| Mutex race: new instance acquires before old releases | `--wait-pid` + `WaitForSingleObject(5000ms)` covers it; if it times out the new instance retries `CreateMutexW` in a 200ms loop for ~3s before giving up |
+| User on FAT32 / non-NTFS volume | `MoveFileExW` with `MOVEFILE_REPLACE_EXISTING` still works on FAT32; renaming-while-running is the NTFS-specific concern but the .exe is rarely on FAT32. Document the edge case |
+| `--wait-pid` arg parsed in legacy build that doesn't recognize it | Old builds will ignore unknown args (cargo CLI parser behavior — verify). If they crash, the user can manually launch. Acceptable: this is a one-way migration; once the new flag is in a release, future updates are smooth |
+
+## Success criteria
+
+1. Manual update from v0.1.9 → test-tagged v0.1.99 produces ZERO visible console window across 20 consecutive runs on Win11 + Win10
+2. Restart triggered from menu (e.g. language change) produces ZERO visible console
+3. Auto-update at scheduled interval (Hourly) produces a tray balloon "Updated to v0.1.99" on next launch
+4. `.old.*` files do not accumulate after 5 update cycles
+5. App still launches cleanly when no parent PID was passed (i.e. fresh user start)
+6. SHA-256 verification path unchanged and still rejects tampered binaries
+
+## Out-of-scope follow-ups
+
+1. **Audit `usage::refresh::spawn_local` / `spawn_wsl`**: the `wsl.exe` invocation in particular has known console-flash quirks even with `CREATE_NO_WINDOW`. If the user still sees occasional flashes after this change ships, that is the next investigation target.
+2. **`creds::wsl_bridge::wsl_run`**: same family of `wsl.exe` invocations.
+
+## Unresolved questions
+
+- None blocking implementation. (Open follow-up: whether to also pipe `--wait-pid` into the legacy `--apply-update` compatibility branch in `update::run_cli`, in case a very old build is doing the spawning.)

src/app.rs

@@ -6,8 +6,7 @@
 // message-only window owned by this module.
 
 use std::collections::HashMap;
-use std::os::windows::process::CommandExt;
-use std::process::{Command, Stdio};
+use std::ffi::OsString;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, MutexGuard, OnceLock};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
@@ -15,7 +14,7 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 use windows::core::PCWSTR;
 use windows::Win32::Foundation::*;
 use windows::Win32::System::LibraryLoader::GetModuleHandleW;
-use windows::Win32::System::Threading::CreateMutexW;
+use windows::Win32::System::Threading::{CreateMutexW, GetCurrentProcessId, Sleep};
 use windows::Win32::UI::HiDpi::{
     SetProcessDpiAwarenessContext, DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2,
 };
@@ -28,18 +27,17 @@ use crate::net;
 use crate::os;
 use crate::panel::{self, PanelData};
 use crate::settings::{self, Settings, POLL_15_MIN, POLL_1_HOUR, POLL_1_MIN, POLL_5_MIN};
-use crate::tray::{self, TrayAction, TrayIcon as TrayIconData};
-use crate::usage::ProviderId as TrayIconKind;
-use crate::tray::WM_APP_TRAY;
+use crate::tray::{self, TrayAction, TrayIcon as TrayIconData, WM_APP_TRAY};
 use crate::update::{self, Channel as InstallChannel, CheckOutcome};
 use crate::usage::{self, ProviderId, Registry, UsageWindows};
 
 // Win32 message IDs owned by this module.
 pub const WM_APP_USAGE_UPDATED: u32 = 0x8001;
-// Posted from the update worker thread when the swap-and-restart cmd
-// handoff has been launched successfully. The UI thread responds by
-// calling PostQuitMessage(0) to release the file lock on the running
-// .exe so cmd.exe can overwrite it.
+// Posted from the update worker thread after `install::begin` has
+// already swapped the binary on disk and spawned the new detached
+// child. The UI thread responds with PostQuitMessage(0) so the old
+// instance exits cleanly and releases the singleton mutex for the
+// child waiting on `--wait-pid`.
 pub const WM_APP_UPDATE_APPLIED: u32 = 0x8002;
 
 // Timer IDs used with `SetTimer(msg_hwnd, …)`.
@@ -110,7 +108,7 @@ enum UpdateStatus {
 
 struct AppState {
     msg_hwnd: SendHwnd,
-    bubbles: HashMap<TrayIconKind, SendHwnd>,
+    bubbles: HashMap<ProviderId, SendHwnd>,
     settings: Settings,
     i18n: I18n,
     is_dark: bool,
@@ -145,29 +143,69 @@ fn lock_state() -> MutexGuard<'static, Option<AppState>> {
     state().lock().expect("app state mutex poisoned")
 }
 
+/// Run `f` with mutable access to `AppState`, then snapshot `Settings` and
+/// persist it to disk. The lock is released before the disk write so the UI
+/// thread doesn't block on I/O. No-op if state hasn't been initialised yet.
+fn update_settings(f: impl FnOnce(&mut AppState)) {
+    let snap = {
+        let mut guard = lock_state();
+        let Some(s) = guard.as_mut() else {
+            return;
+        };
+        f(s);
+        s.settings.clone()
+    };
+    settings::save(&snap);
+}
+
 // ---------- Entry ----------
 
-pub fn run() {
+/// Acquire the singleton mutex, optionally retrying for ~3s if the
+/// caller passed `--wait-pid` (i.e. we just spawned from an exiting
+/// parent that has not yet released its handle).
+fn acquire_singleton_mutex(retry: bool) -> Option<HANDLE> {
+    let mutex_name_w = os::to_utf16_nul(APP_MUTEX_NAME);
+    let max_attempts = if retry { 15 } else { 1 };
+    for attempt in 0..max_attempts {
+        let handle = unsafe { CreateMutexW(None, false, PCWSTR::from_raw(mutex_name_w.as_ptr())) };
+        match handle {
+            Ok(h) => {
+                let already = unsafe { GetLastError() } == ERROR_ALREADY_EXISTS;
+                if !already {
+                    return Some(h);
+                }
+                // Mutex still held by parent. Close this handle and retry.
+                unsafe {
+                    let _ = CloseHandle(h);
+                }
+                if attempt + 1 == max_attempts {
+                    log::info!("another instance already running; exiting");
+                    return None;
+                }
+                log::debug!(
+                    "mutex still held by parent (attempt {}/{}), waiting 200ms",
+                    attempt + 1,
+                    max_attempts
+                );
+                unsafe { Sleep(200) };
+            }
+            Err(e) => {
+                log::error!("CreateMutex failed: {e}");
+                return None;
+            }
+        }
+    }
+    None
+}
+
+pub fn run(args: crate::AppArgs) {
     unsafe {
         let _ = SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
     }
 
-    let mutex_name_w = os::to_utf16_nul(APP_MUTEX_NAME);
-    let _mutex = unsafe {
-        let handle = CreateMutexW(None, false, PCWSTR::from_raw(mutex_name_w.as_ptr()));
-        match handle {
-            Ok(h) => {
-                if GetLastError() == ERROR_ALREADY_EXISTS {
-                    log::info!("another instance already running; exiting");
-                    return;
-                }
-                h
-            }
-            Err(e) => {
-                log::error!("CreateMutex failed: {e}");
-                return;
-            }
-        }
+    let _mutex = match acquire_singleton_mutex(args.wait_pid_present) {
+        Some(h) => h,
+        None => return,
     };
 
     let settings = settings::load();
@@ -205,9 +243,28 @@ pub fn run() {
         last_balloon_at: None,
     });
 
+    bubble::install_callbacks(bubble::Callbacks {
+        on_click: on_bubble_click,
+        on_right_click: on_bubble_right_click,
+        on_moved: on_bubble_moved,
+        on_resized: on_bubble_resized,
+        on_menu_command,
+        on_settings_changed: recheck_theme,
+    });
+
     create_initial_bubbles();
     refresh_tray_icons();
 
+    // Post-update tasks: show "Updated to vX.Y.Z" balloon (driven by
+    // --updated-to passed by the previous instance) and sweep any
+    // stale `<exe>.old.<pid>` siblings left by past in-place swaps.
+    if let Some(v) = args.updated_to.as_ref() {
+        announce_update_applied(msg_hwnd, v);
+    }
+    if let Ok(exe_path) = std::env::current_exe() {
+        update::handoff::cleanup_stale_old_exes(&exe_path);
+    }
+
     let poll_interval = lock_state()
         .as_ref()
         .map(|s| s.settings.poll_interval_ms)
@@ -272,7 +329,7 @@ fn create_initial_bubbles() {
     }
 }
 
-fn spawn_bubble(kind: TrayIconKind, settings: &Settings, is_dark: bool) {
+fn spawn_bubble(kind: ProviderId, settings: &Settings, is_dark: bool) {
     // "…" matches the in-flight/transient-error placeholder used by
     // `apply_results`, so the bubble has visible feedback during the first
     // poll rather than rendering with two empty grey tracks.
@@ -330,40 +387,24 @@ unsafe extern "system" fn msg_wnd_proc(
 
 // ---------- Bubble callbacks ----------
 
-pub fn on_bubble_click(hwnd: HWND, model: TrayIconKind) {
+fn on_bubble_click(hwnd: HWND, model: ProviderId) {
     let data = build_panel_data(model);
     panel::toggle(data, hwnd);
 }
 
-pub fn on_bubble_right_click(hwnd: HWND, _model: TrayIconKind, _pt: POINT) {
+fn on_bubble_right_click(hwnd: HWND, _model: ProviderId, _pt: POINT) {
     show_context_menu(hwnd);
 }
 
-pub fn on_bubble_moved(model: TrayIconKind, pos: (i32, i32)) {
-    let snap = {
-        let mut s = lock_state();
-        let Some(s) = s.as_mut() else {
-            return;
-        };
-        s.settings.bubble_positions.set(model, pos);
-        s.settings.clone()
-    };
-    settings::save(&snap);
+fn on_bubble_moved(model: ProviderId, pos: (i32, i32)) {
+    update_settings(|s| s.settings.bubble_positions.set(model, pos));
 }
 
-pub fn on_bubble_resized(_model: TrayIconKind, size_logical: i32) {
-    let snap = {
-        let mut s = lock_state();
-        let Some(s) = s.as_mut() else {
-            return;
-        };
-        s.settings.bubble_size_logical = size_logical;
-        s.settings.clone()
-    };
-    settings::save(&snap);
+fn on_bubble_resized(_model: ProviderId, size_logical: i32) {
+    update_settings(|s| s.settings.bubble_size_logical = size_logical);
 }
 
-pub fn on_menu_command(id: u32, _owner_hwnd: HWND) {
+fn on_menu_command(id: u32, _owner_hwnd: HWND) {
     let id = (id & 0xFFFF) as u16;
     match id {
         IDM_REFRESH => spawn_poll_thread(),
@@ -583,8 +624,7 @@ fn propagate_to_ui() {
     };
 
     for (kind, hwnd) in snap.bubbles.iter() {
-        let id = kind_to_provider(*kind);
-        let entry = snap.snapshots.get(&id);
+        let entry = snap.snapshots.get(kind);
         let session_pct = entry.map(|s| s.windows.primary.utilization);
         let weekly_pct = entry.map(|s| s.windows.secondary.utilization);
         // The bubble paints the percent inline inside the bar fill, so it
@@ -608,8 +648,7 @@ fn propagate_to_ui() {
 
     if panel::is_visible() {
         if let Some(model) = panel::current_model() {
-            let id = kind_to_provider(model);
-            if let Some(provider_state) = snap.snapshots.get(&id) {
+            if let Some(provider_state) = snap.snapshots.get(&model) {
                 panel::refresh_data(build_panel_data_from(&snap, model, provider_state));
             }
         }
@@ -619,7 +658,7 @@ fn propagate_to_ui() {
 
 #[derive(Clone)]
 struct UiSnapshot {
-    bubbles: HashMap<TrayIconKind, SendHwnd>,
+    bubbles: HashMap<ProviderId, SendHwnd>,
     snapshots: HashMap<ProviderId, ProviderUiState>,
     settings: Settings,
     i18n_strings: LocaleStrings,
@@ -628,21 +667,13 @@ struct UiSnapshot {
     last_poll_ok: bool,
 }
 
-fn kind_to_provider(k: TrayIconKind) -> ProviderId {
-    match k {
-        ProviderId::Claude => ProviderId::Claude,
-        ProviderId::ChatGpt => ProviderId::ChatGpt,
-    }
-}
-
-fn build_panel_data(model: TrayIconKind) -> PanelData {
+fn build_panel_data(model: ProviderId) -> PanelData {
     let s = lock_state();
     let Some(s) = s.as_ref() else {
         return placeholder_panel(model);
     };
-    let id = kind_to_provider(model);
     let strings = s.i18n.strings().clone();
-    let provider_state = s.snapshots.get(&id).cloned().unwrap_or_default();
+    let provider_state = s.snapshots.get(&model).cloned().unwrap_or_default();
     PanelData {
         model,
         session_pct: provider_state.windows.primary.utilization,
@@ -654,7 +685,7 @@ fn build_panel_data(model: TrayIconKind) -> PanelData {
     }
 }
 
-fn build_panel_data_from(snap: &UiSnapshot, model: TrayIconKind, p: &ProviderUiState) -> PanelData {
+fn build_panel_data_from(snap: &UiSnapshot, model: ProviderId, p: &ProviderUiState) -> PanelData {
     PanelData {
         model,
         session_pct: p.windows.primary.utilization,
@@ -666,7 +697,7 @@ fn build_panel_data_from(snap: &UiSnapshot, model: TrayIconKind, p: &ProviderUiS
     }
 }
 
-fn placeholder_panel(model: TrayIconKind) -> PanelData {
+fn placeholder_panel(model: ProviderId) -> PanelData {
     let strings = i18n::I18n::load(None).strings().clone();
     PanelData {
         model,
@@ -781,7 +812,7 @@ fn handle_tray_action(action: TrayAction) {
 /// the UI. Called from each bubble's WM_SETTINGCHANGE handler — Windows
 /// posts that to every top-level window when the user toggles light/dark
 /// in Settings, so this naturally fires once per change.
-pub fn recheck_theme() {
+fn recheck_theme() {
     let now_dark = os::theme::is_dark();
     let changed = {
         let mut s = lock_state();
@@ -828,7 +859,7 @@ fn show_threshold_balloon(provider: ProviderId, threshold: u8) {
         };
         (s.msg_hwnd, provider, title, body)
     };
-    tray::notify(payload.0.to_hwnd(), payload.1, &payload.2, &payload.3);
+    tray::notify_warning(payload.0.to_hwnd(), payload.1, &payload.2, &payload.3);
 }
 
 fn show_token_expired_balloon(failed: ProviderId) {
@@ -856,7 +887,30 @@ fn show_token_expired_balloon(failed: ProviderId) {
         };
         (s.msg_hwnd, failed, title, body)
     };
-    tray::notify(payload.0.to_hwnd(), payload.1, &payload.2, &payload.3);
+    tray::notify_warning(payload.0.to_hwnd(), payload.1, &payload.2, &payload.3);
+}
+
+/// Show the "Updated to vX.Y.Z" balloon on first launch after an
+/// auto-update. Picks Claude as the host icon if it's registered;
+/// otherwise falls back to Codex. If neither is registered the
+/// notification silently drops — better than crashing.
+fn announce_update_applied(_msg_hwnd: HWND, version: &str) {
+    let payload = {
+        let s = lock_state();
+        let Some(s) = s.as_ref() else {
+            return;
+        };
+        let strings = s.i18n.strings();
+        let title = strings.update_applied_title.clone();
+        let body = format!("{}{}", strings.update_applied_body, version);
+        let host = if s.settings.show_claude_code {
+            ProviderId::Claude
+        } else {
+            ProviderId::ChatGpt
+        };
+        (s.msg_hwnd, host, title, body)
+    };
+    tray::notify_info(payload.0.to_hwnd(), payload.1, &payload.2, &payload.3);
 }
 
 // ---------- Context menu ----------
@@ -1103,7 +1157,7 @@ fn set_poll_interval(ms: u32) {
     }
 }
 
-fn toggle_model(model: TrayIconKind) {
+fn toggle_model(model: ProviderId) {
     let (settings, is_dark) = {
         let mut s = lock_state();
         let Some(s) = s.as_mut() else {
@@ -1191,33 +1245,21 @@ fn reset_positions() {
 }
 
 fn set_language(_dummy: Option<()>) {
-    let snap = {
-        let mut s = lock_state();
-        let Some(s) = s.as_mut() else {
-            return;
-        };
+    update_settings(|s| {
         s.i18n.set_active(None);
         s.settings.language = None;
-        s.settings.clone()
-    };
-    settings::save(&snap);
+    });
     propagate_to_ui();
 }
 
 fn set_language_by_index(idx: usize) {
-    let snap = {
-        let mut s = lock_state();
-        let Some(s) = s.as_mut() else {
-            return;
-        };
+    update_settings(|s| {
         let code = s.i18n.available().nth(idx).map(|(c, _)| c.to_string());
         if let Some(c) = code.as_deref() {
             s.i18n.set_active(Some(c));
         }
         s.settings.language = code;
-        s.settings.clone()
-    };
-    settings::save(&snap);
+    });
     propagate_to_ui();
 }
 
@@ -1377,17 +1419,9 @@ fn set_update_check_interval(value: Option<u64>) {
 
 // ---------- Restart ----------
 
-// Windows CreateProcess flags. Match the values used by `update::install`
-// so the cmd-handoff child detaches cleanly without flashing a console.
-const RESTART_CREATE_NO_WINDOW: u32 = 0x0800_0000;
-const RESTART_DETACHED_PROCESS: u32 = 0x0000_0008;
-
-/// Relaunch the running binary via a detached cmd.exe handoff.
-///
-/// The 1-second `timeout` gives the current process time to release the
-/// `Global\ClaudeCodeUsageBubble` mutex before the relaunched instance's
-/// `CreateMutexW` runs, otherwise the new instance would see
-/// `ERROR_ALREADY_EXISTS` and exit immediately.
+/// Relaunch the running binary by spawning a detached child via
+/// `CreateProcessW`. The child waits on our PID before acquiring the
+/// singleton mutex, so no shell handoff or timer is required.
 fn restart_app() {
     // Defensive flush — bubble positions and most settings already persist
     // on change, but a final save is cheap insurance. Snapshot then drop the
@@ -1404,30 +1438,18 @@ fn restart_app() {
             return;
         }
     };
-    let exe_str = exe.to_string_lossy();
-    // cmd.exe expands `%var%` inside double quotes, so a path containing `%`
-    // would let the environment leak into the relaunch. Refuse — matches the
-    // defense already used in `update::install`.
-    if exe_str.contains('%') {
-        log::error!("restart: refusing path containing '%': {exe_str}");
-        return;
-    }
-    let exe_str = exe_str.replace('"', "");
-    let cmd = format!(r#"timeout /t 1 /nobreak >nul & start "" "{exe_str}""#);
-    let spawned = Command::new("cmd.exe")
-        .raw_arg("/c")
-        .raw_arg(format!("\"{cmd}\""))
-        .creation_flags(RESTART_CREATE_NO_WINDOW | RESTART_DETACHED_PROCESS)
-        .stdin(Stdio::null())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn();
-    match spawned {
-        Ok(_) => {
-            log::info!("restart: cmd handoff spawned, posting quit");
+
+    let pid = unsafe { GetCurrentProcessId() };
+    let args = vec![
+        OsString::from("--wait-pid"),
+        OsString::from(pid.to_string()),
+    ];
+    match update::handoff::spawn_detached(&exe, &args) {
+        Ok(()) => {
+            log::info!("restart: spawned detached child (parent pid={pid}), posting quit");
             unsafe { PostQuitMessage(0) };
         }
-        Err(e) => log::error!("restart: cmd spawn failed: {e}"),
+        Err(e) => log::error!("restart: spawn_detached failed: {e}"),
     }
 }
 

src/bubble.rs

@@ -26,13 +26,13 @@ use windows::Win32::UI::Shell::{
 };
 use windows::Win32::UI::WindowsAndMessaging::*;
 
+use crate::os::dpi::scale as scale_to_dpi;
 use crate::os::{to_utf16_nul as wide_str, Rgb as Color};
 
 const TIMER_FULLSCREEN_CHECK: usize = 5;
 const TIMER_PULSE: usize = 6;
 const PULSE_INTERVAL_MS: u32 = 80;
 use crate::usage::ProviderId;
-type TrayIconKind = ProviderId;
 
 // ---------- Public types & API ----------
 
@@ -88,7 +88,7 @@ fn aspect_at_width(w_logical: i32) -> (i32, i32) {
 }
 
 pub struct BubbleConfig {
-    pub model: TrayIconKind,
+    pub model: ProviderId,
     pub size_logical: i32,
     pub position: Option<(i32, i32)>,
     pub session_pct: Option<f64>,
@@ -103,6 +103,34 @@ fn bubble_height_logical(width_logical: i32) -> i32 {
     ((width_logical * den) / num).max(20)
 }
 
+/// Owner-supplied event callbacks. The bubble window proc is a leaf — it
+/// doesn't know about `app`. The owner installs these once at startup so the
+/// proc can dispatch UI events back without an upward `crate::app::` reach.
+pub struct Callbacks {
+    pub on_click: fn(HWND, ProviderId),
+    pub on_right_click: fn(HWND, ProviderId, POINT),
+    pub on_moved: fn(ProviderId, (i32, i32)),
+    pub on_resized: fn(ProviderId, i32),
+    pub on_menu_command: fn(u32, HWND),
+    pub on_settings_changed: fn(),
+}
+
+static CALLBACKS: OnceLock<Callbacks> = OnceLock::new();
+
+/// Install the owner's callbacks. Called once by `app::run` before any
+/// bubble is created. Subsequent calls are silently ignored.
+pub fn install_callbacks(cb: Callbacks) {
+    let _ = CALLBACKS.set(cb);
+}
+
+fn dispatch<F: FnOnce(&Callbacks)>(f: F) {
+    if let Some(cb) = CALLBACKS.get() {
+        f(cb);
+    } else {
+        log::warn!("bubble event dispatched before install_callbacks; event dropped");
+    }
+}
+
 /// Register the bubble window class. Idempotent; safe to call before the first
 /// `create()` from the UI thread.
 pub fn register_class() {
@@ -133,7 +161,7 @@ pub fn create(config: BubbleConfig) -> HWND {
     let initial_size_logical = config
         .size_logical
         .clamp(MIN_BUBBLE_SIZE, MAX_BUBBLE_SIZE);
-    let dpi_for_create = primary_dpi();
+    let dpi_for_create = crate::os::dpi::for_system();
     let width_px = scale_to_dpi(initial_size_logical, dpi_for_create);
     let height_px = scale_to_dpi(bubble_height_logical(initial_size_logical), dpi_for_create);
     let (x, y) = config
@@ -166,19 +194,11 @@ pub fn create(config: BubbleConfig) -> HWND {
     }
 
     // Embed app icon in window non-client (mostly cosmetic; toolwindows
-    // don't show captions but the icon helps in dev tooling).
+    // don't show captions but the icon helps in dev tooling). The HICONs
+    // are extracted once at process startup and reused across every bubble
+    // create() so we don't leak a pair per toggle cycle.
+    let (large_icon, small_icon) = app_icons();
     unsafe {
-        let mut large_icon = HICON::default();
-        let mut small_icon = HICON::default();
-        let mut exe = [0u16; 260];
-        GetModuleFileNameW(HMODULE::default(), &mut exe);
-        let _ = ExtractIconExW(
-            PCWSTR::from_raw(exe.as_ptr()),
-            0,
-            Some(&mut large_icon),
-            Some(&mut small_icon),
-            1,
-        );
         if !large_icon.is_invalid() {
             let _ = SendMessageW(
                 hwnd,
@@ -245,6 +265,33 @@ pub fn destroy(hwnd: HWND) {
     }
 }
 
+/// Extract the EXE's own icon pair once per process. Stored as raw pointer
+/// values because `HICON` is `!Send`/`!Sync`; reconstituted for each caller.
+/// The pair is intentionally never destroyed — Windows tears them down on
+/// process exit, and one pair per process is bounded leak rather than the
+/// O(bubble-toggles) leak we'd get from extracting per `create()`.
+fn app_icons() -> (HICON, HICON) {
+    static ICONS: OnceLock<(isize, isize)> = OnceLock::new();
+    let (big, small) = *ICONS.get_or_init(|| unsafe {
+        let mut large = HICON::default();
+        let mut small = HICON::default();
+        let mut exe = [0u16; 260];
+        GetModuleFileNameW(HMODULE::default(), &mut exe);
+        let _ = ExtractIconExW(
+            PCWSTR::from_raw(exe.as_ptr()),
+            0,
+            Some(&mut large),
+            Some(&mut small),
+            1,
+        );
+        if large.is_invalid() && small.is_invalid() {
+            log::warn!("ExtractIconExW yielded null handles; bubbles will be iconless");
+        }
+        (large.0 as isize, small.0 as isize)
+    });
+    (HICON(big as *mut _), HICON(small as *mut _))
+}
+
 pub fn update_data(
     hwnd: HWND,
     session_pct: Option<f64>,
@@ -339,7 +386,7 @@ pub fn position(hwnd: HWND) -> Option<(i32, i32)> {
     Some((r.left, r.top))
 }
 
-pub fn model(hwnd: HWND) -> Option<TrayIconKind> {
+pub fn model(hwnd: HWND) -> Option<ProviderId> {
     lock_bubbles()
         .get(&(hwnd.0 as isize))
         .map(|b| b.model)
@@ -354,7 +401,7 @@ pub fn size_logical(hwnd: HWND) -> Option<i32> {
 // ---------- State ----------
 
 struct BubbleState {
-    model: TrayIconKind,
+    model: ProviderId,
     size_logical: i32,
     dpi: u32,
     session_pct: Option<f64>,
@@ -422,18 +469,18 @@ unsafe extern "system" fn wnd_proc(
                 snap_to_edge(hwnd);
                 if let Some(model) = model(hwnd) {
                     if let Some(pos) = position(hwnd) {
-                        crate::app::on_bubble_moved(model, pos);
+                        dispatch(|cb| (cb.on_moved)(model, pos));
                     }
                 }
             } else if let Some(model) = model(hwnd) {
-                crate::app::on_bubble_click(hwnd, model);
+                dispatch(|cb| (cb.on_click)(hwnd, model));
             }
             LRESULT(0)
         }
         WM_NCRBUTTONUP => {
             if let Some(model) = model(hwnd) {
                 let pt = lparam_to_point(lparam);
-                crate::app::on_bubble_right_click(hwnd, model, pt);
+                dispatch(|cb| (cb.on_right_click)(hwnd, model, pt));
             }
             LRESULT(0)
         }
@@ -484,7 +531,7 @@ unsafe extern "system" fn wnd_proc(
             LRESULT(0)
         }
         WM_COMMAND => {
-            crate::app::on_menu_command(wparam.0 as u32, hwnd);
+            dispatch(|cb| (cb.on_menu_command)(wparam.0 as u32, hwnd));
             LRESULT(0)
         }
         WM_SETTINGCHANGE => {
@@ -494,7 +541,7 @@ unsafe extern "system" fn wnd_proc(
             // the app to re-read the light/dark setting — Windows fires
             // this message when the user flips the OS theme in Settings.
             clamp_into_work_area(hwnd);
-            crate::app::recheck_theme();
+            dispatch(|cb| (cb.on_settings_changed)());
             LRESULT(0)
         }
         WM_DESTROY => {
@@ -591,7 +638,7 @@ fn resize_step(hwnd: HWND, delta: i32) {
     }
     render(hwnd);
     if let Some(m) = model(hwnd) {
-        crate::app::on_bubble_resized(m, new_logical);
+        dispatch(|cb| (cb.on_resized)(m, new_logical));
     }
 }
 
@@ -810,7 +857,7 @@ fn clamp_into_work_area(hwnd: HWND) {
     // so they don't visually stack.
     let is_codex = lock_bubbles()
         .get(&(hwnd.0 as isize))
-        .is_some_and(|b| matches!(b.model, TrayIconKind::ChatGpt));
+        .is_some_and(|b| matches!(b.model, ProviderId::ChatGpt));
     if is_codex && nx == wa.right - w && ny == wa.bottom - h {
         const STAGGER_GAP: i32 = 24;
         ny = (ny - h - STAGGER_GAP).max(wa.top);
@@ -1060,7 +1107,7 @@ fn rgb_to_dib(c: Color) -> u32 {
 }
 
 struct PaintInputs {
-    model: TrayIconKind,
+    model: ProviderId,
     session_pct: Option<f64>,
     session_text: String,
     weekly_pct: Option<f64>,
@@ -1092,7 +1139,14 @@ fn render(hwnd: HWND) {
 
     unsafe {
         let screen_dc = GetDC(hwnd);
+        if screen_dc.is_invalid() {
+            return;
+        }
         let mem_dc = CreateCompatibleDC(screen_dc);
+        if mem_dc.is_invalid() {
+            ReleaseDC(hwnd, screen_dc);
+            return;
+        }
         let layout = compute_layout(size_logical, dpi, mem_dc);
 
         let bmi = BITMAPINFO {
@@ -1204,8 +1258,8 @@ fn row_band(layout: &BarLayout, row_top: i32) -> (i32, i32) {
     (top, bot)
 }
 
-fn paint_accent_stripe(pixels: &mut [u32], layout: &BarLayout, model: TrayIconKind, is_dark: bool) {
-    let stripe = rgb_to_dib(accent_color_for(model, is_dark));
+fn paint_accent_stripe(pixels: &mut [u32], layout: &BarLayout, model: ProviderId, is_dark: bool) {
+    let stripe = rgb_to_dib(crate::usage_color::accent_color_for(model, is_dark));
     for y in 0..layout.canvas_h {
         for x in 0..layout.accent_right {
             if !point_in_rounded_rect(x, y, layout.canvas_w, layout.canvas_h, layout.corner_radius) {
@@ -1216,22 +1270,6 @@ fn paint_accent_stripe(pixels: &mut [u32], layout: &BarLayout, model: TrayIconKi
     }
 }
 
-/// Per-provider identity color. Claude = orange. Codex = white-in-dark /
-/// charcoal-in-light — picking a pure white in light mode would vanish into
-/// the `#F3F3F3` background, so we mirror to a contrasting neutral.
-fn accent_color_for(model: TrayIconKind, is_dark: bool) -> Color {
-    match model {
-        ProviderId::Claude => Color::from_hex("#D97757"),
-        ProviderId::ChatGpt => {
-            if is_dark {
-                Color::from_hex("#FFFFFF")
-            } else {
-                Color::from_hex("#2A2A2A")
-            }
-        }
-    }
-}
-
 fn paint_bars(pixels: &mut [u32], layout: &BarLayout, inputs: &PaintInputs) {
     let track = if inputs.is_dark {
         Color::from_hex("#3A3A3A")
@@ -1267,7 +1305,7 @@ fn paint_one_bar(
     if fill_w <= 0 {
         return;
     }
-    let mut accent_rgb = bar_fill_color(inputs.model, inputs.is_dark, p);
+    let mut accent_rgb = crate::usage_color::bar_fill_color(inputs.model, inputs.is_dark, p);
     if p >= 95.0 {
         // Slow brightness triangle: 0.85 → 1.15 over 24 ticks (≈1.9s @ 80ms).
         let t = pulse_triangle(inputs.pulse_phase);
@@ -1461,27 +1499,6 @@ fn apply_alpha_mask(pixels: &mut [u32], layout: &BarLayout) {
     }
 }
 
-/// Discrete 4-band fill color. The "safe" band uses the provider's identity
-/// color so Codex bars stay white-on-dark while Claude bars stay orange; the
-/// warning bands are the same alarm palette regardless of provider so an
-/// approaching-limit always looks the same to the eye.
-///
-/// - <60%   → provider accent (Claude `#D97757` / Codex theme-derived)
-/// - 60–80% → amber           (#E0A040)
-/// - 80–95% → red             (#C45020)
-/// - ≥95%   → deep red        (#A01818) — paired with pulse animation
-pub fn bar_fill_color(model: TrayIconKind, is_dark: bool, percent: f64) -> Color {
-    if percent < 60.0 {
-        accent_color_for(model, is_dark)
-    } else if percent < 80.0 {
-        Color::from_hex("#E0A040")
-    } else if percent < 95.0 {
-        Color::from_hex("#C45020")
-    } else {
-        Color::from_hex("#A01818")
-    }
-}
-
 /// Relative luminance of an sRGB color in 0..255 space. Cheap approximation
 /// of the Rec. 709 coefficients — good enough for "should the text on this
 /// pixel be white or black?" decisions.
@@ -1497,15 +1514,7 @@ fn use_dark_text_over(c: Color) -> bool {
 
 // ---------- Helpers ----------
 
-fn primary_dpi() -> u32 {
-    unsafe { GetDpiForSystem().max(96) }
-}
-
-fn scale_to_dpi(logical: i32, dpi: u32) -> i32 {
-    ((logical as i64) * (dpi as i64) / 96) as i32
-}
-
-fn default_position(width_px: i32, height_px: i32, model: TrayIconKind) -> (i32, i32) {
+fn default_position(width_px: i32, height_px: i32, model: ProviderId) -> (i32, i32) {
     // Bottom-right of primary work area, with a 24-pixel gap from the edges.
     // Stagger the Codex bubble above the Claude one if both are enabled.
     unsafe {

src/i18n/locales/de.toml

@@ -1,46 +0,0 @@
-code = "de"
-native_name = "Deutsch"
-
-window_title = "Claude Code Usage Bubble"
-refresh = "Aktualisieren"
-update_frequency = "Aktualisierungsintervall"
-one_minute = "1 Minute"
-five_minutes = "5 Minuten"
-fifteen_minutes = "15 Minuten"
-one_hour = "1 Stunde"
-models = "Modelle"
-claude_label = "Claude Code"
-chatgpt_label = "Codex"
-settings = "Einstellungen"
-start_with_windows = "Mit Windows starten"
-reset_position = "Position zurücksetzen"
-language = "Sprache"
-system_default = "Systemstandard"
-check_for_updates = "Nach Updates suchen"
-checking_for_updates = "Suche läuft…"
-up_to_date = "Aktuell"
-update_failed = "Update fehlgeschlagen"
-applying_update = "Update wird angewendet…"
-update_available = "Update verfügbar"
-update_via_winget = "über WinGet"
-auto_update_check = "Automatische Updateprüfung"
-auto_check_disabled = "Deaktiviert"
-auto_check_hourly = "Stündlich"
-auto_check_daily = "Täglich"
-auto_check_weekly = "Wöchentlich"
-exit = "Beenden"
-restart = "Neu starten"
-show_widget = "Widget anzeigen"
-session_window = "5h"
-weekly_window = "7d"
-now = "jetzt"
-day_suffix = "T"
-hour_suffix = "h"
-minute_suffix = "m"
-second_suffix = "s"
-token_expired_title = "Claude Code-Sitzung abgelaufen"
-token_expired_body = "Melde dich erneut an, um die Nutzung weiter zu verfolgen."
-chatgpt_token_expired_title = "Codex-Sitzung abgelaufen"
-chatgpt_token_expired_body = "Melde dich erneut an, um die Nutzung weiter zu verfolgen."
-threshold_80_body = "5-Stunden-Limit naht."
-threshold_95_body = "Limit fast erreicht — gönn dir eine Pause."

src/i18n/locales/en.toml

@@ -44,3 +44,6 @@ chatgpt_token_expired_title = "Codex session expired"
 chatgpt_token_expired_body = "Sign in again to keep tracking your usage."
 threshold_80_body = "Approaching the 5-hour limit."
 threshold_95_body = "Limit is close — consider easing up."
+update_applied_title = "Update applied"
+update_applied_body = "Updated to v"
+update_rollback_failed_body = "Update failed. Your original binary is saved at: "

src/i18n/locales/es.toml

@@ -1,46 +0,0 @@
-code = "es"
-native_name = "Español"
-
-window_title = "Claude Code Usage Bubble"
-refresh = "Actualizar"
-update_frequency = "Frecuencia de actualización"
-one_minute = "1 minuto"
-five_minutes = "5 minutos"
-fifteen_minutes = "15 minutos"
-one_hour = "1 hora"
-models = "Modelos"
-claude_label = "Claude Code"
-chatgpt_label = "Codex"
-settings = "Ajustes"
-start_with_windows = "Iniciar con Windows"
-reset_position = "Restablecer posición"
-language = "Idioma"
-system_default = "Predeterminado del sistema"
-check_for_updates = "Buscar actualizaciones"
-checking_for_updates = "Buscando actualizaciones…"
-up_to_date = "Al día"
-update_failed = "Actualización fallida"
-applying_update = "Aplicando actualización…"
-update_available = "Actualización disponible"
-update_via_winget = "vía WinGet"
-auto_update_check = "Búsqueda automática de actualizaciones"
-auto_check_disabled = "Desactivada"
-auto_check_hourly = "Cada hora"
-auto_check_daily = "Cada día"
-auto_check_weekly = "Cada semana"
-exit = "Salir"
-restart = "Reiniciar"
-show_widget = "Mostrar widget"
-session_window = "5h"
-weekly_window = "7d"
-now = "ahora"
-day_suffix = "d"
-hour_suffix = "h"
-minute_suffix = "m"
-second_suffix = "s"
-token_expired_title = "Sesión de Claude Code caducada"
-token_expired_body = "Vuelve a iniciar sesión para seguir registrando el uso."
-chatgpt_token_expired_title = "Sesión de Codex caducada"
-chatgpt_token_expired_body = "Vuelve a iniciar sesión para seguir registrando el uso."
-threshold_80_body = "Cerca del límite de 5 horas."
-threshold_95_body = "Límite casi alcanzado — reduce el ritmo."

src/i18n/locales/fr.toml

@@ -1,46 +0,0 @@
-code = "fr"
-native_name = "Français"
-
-window_title = "Claude Code Usage Bubble"
-refresh = "Actualiser"
-update_frequency = "Fréquence de mise à jour"
-one_minute = "1 minute"
-five_minutes = "5 minutes"
-fifteen_minutes = "15 minutes"
-one_hour = "1 heure"
-models = "Modèles"
-claude_label = "Claude Code"
-chatgpt_label = "Codex"
-settings = "Paramètres"
-start_with_windows = "Lancer avec Windows"
-reset_position = "Réinitialiser la position"
-language = "Langue"
-system_default = "Paramètre système"
-check_for_updates = "Rechercher des mises à jour"
-checking_for_updates = "Recherche en cours…"
-up_to_date = "À jour"
-update_failed = "Mise à jour échouée"
-applying_update = "Mise à jour en cours…"
-update_available = "Mise à jour disponible"
-update_via_winget = "via WinGet"
-auto_update_check = "Vérification automatique des mises à jour"
-auto_check_disabled = "Désactivée"
-auto_check_hourly = "Toutes les heures"
-auto_check_daily = "Quotidienne"
-auto_check_weekly = "Hebdomadaire"
-exit = "Quitter"
-restart = "Redémarrer"
-show_widget = "Afficher le widget"
-session_window = "5h"
-weekly_window = "7j"
-now = "maintenant"
-day_suffix = "j"
-hour_suffix = "h"
-minute_suffix = "m"
-second_suffix = "s"
-token_expired_title = "Session Claude Code expirée"
-token_expired_body = "Reconnectez-vous pour continuer à suivre votre utilisation."
-chatgpt_token_expired_title = "Session Codex expirée"
-chatgpt_token_expired_body = "Reconnectez-vous pour continuer à suivre votre utilisation."
-threshold_80_body = "Approche de la limite de 5 heures."
-threshold_95_body = "Limite proche — pensez à lever le pied."

src/i18n/locales/ja.toml

@@ -44,3 +44,6 @@ chatgpt_token_expired_title = "Codexのセッションが切れました"
 chatgpt_token_expired_body = "使用状況の追跡を続けるには再度サインインしてください。"
 threshold_80_body = "5時間の上限に近づいています。"
 threshold_95_body = "上限に近づきました — ペースを落としましょう。"
+update_applied_title = "更新を適用しました"
+update_applied_body = "バージョン v"
+update_rollback_failed_body = "更新に失敗しました。元のバイナリは次の場所に保存されています: "

src/i18n/locales/ko.toml

@@ -44,3 +44,6 @@ chatgpt_token_expired_title = "Codex 세션 만료"
 chatgpt_token_expired_body = "사용량을 계속 추적하려면 다시 로그인하세요."
 threshold_80_body = "5시간 한도에 가까워지고 있어요."
 threshold_95_body = "한도 임박 — 잠시 쉬어가세요."
+update_applied_title = "업데이트가 적용되었습니다"
+update_applied_body = "버전 v"
+update_rollback_failed_body = "업데이트 실패. 원본 바이너리는 다음 위치에 저장되었습니다: "

src/i18n/locales/nl.toml

@@ -1,46 +0,0 @@
-code = "nl"
-native_name = "Nederlands"
-
-window_title = "Claude Code Usage Bubble"
-refresh = "Vernieuwen"
-update_frequency = "Bijwerkfrequentie"
-one_minute = "1 minuut"
-five_minutes = "5 minuten"
-fifteen_minutes = "15 minuten"
-one_hour = "1 uur"
-models = "Modellen"
-claude_label = "Claude Code"
-chatgpt_label = "Codex"
-settings = "Instellingen"
-start_with_windows = "Starten met Windows"
-reset_position = "Positie herstellen"
-language = "Taal"
-system_default = "Systeemstandaard"
-check_for_updates = "Controleren op updates"
-checking_for_updates = "Bezig met controleren…"
-up_to_date = "Up-to-date"
-update_failed = "Update mislukt"
-applying_update = "Update toepassen…"
-update_available = "Update beschikbaar"
-update_via_winget = "via WinGet"
-auto_update_check = "Automatische updatecontrole"
-auto_check_disabled = "Uitgeschakeld"
-auto_check_hourly = "Per uur"
-auto_check_daily = "Dagelijks"
-auto_check_weekly = "Wekelijks"
-exit = "Afsluiten"
-restart = "Opnieuw starten"
-show_widget = "Widget tonen"
-session_window = "5u"
-weekly_window = "7d"
-now = "nu"
-day_suffix = "d"
-hour_suffix = "u"
-minute_suffix = "m"
-second_suffix = "s"
-token_expired_title = "Claude Code-sessie verlopen"
-token_expired_body = "Meld je opnieuw aan om gebruik te blijven volgen."
-chatgpt_token_expired_title = "Codex-sessie verlopen"
-chatgpt_token_expired_body = "Meld je opnieuw aan om gebruik te blijven volgen."
-threshold_80_body = "Je nadert de 5-uurslimiet."
-threshold_95_body = "Limiet bijna bereikt — overweeg even gas terug te nemen."

src/i18n/locales/vi.toml

@@ -0,0 +1,49 @@
+code = "vi"
+native_name = "Tiếng Việt"
+
+window_title = "Claude Code Usage Bubble"
+refresh = "Làm mới"
+update_frequency = "Tần suất cập nhật"
+one_minute = "1 phút"
+five_minutes = "5 phút"
+fifteen_minutes = "15 phút"
+one_hour = "1 giờ"
+models = "Mô hình"
+claude_label = "Claude Code"
+chatgpt_label = "Codex"
+settings = "Cài đặt"
+start_with_windows = "Khởi động cùng Windows"
+reset_position = "Đặt lại vị trí"
+language = "Ngôn ngữ"
+system_default = "Mặc định hệ thống"
+check_for_updates = "Kiểm tra cập nhật"
+checking_for_updates = "Đang kiểm tra cập nhật…"
+up_to_date = "Đã là phiên bản mới nhất"
+update_failed = "Cập nhật thất bại"
+applying_update = "Đang áp dụng cập nhật…"
+update_available = "Có bản cập nhật mới"
+update_via_winget = "qua WinGet"
+auto_update_check = "Tự động kiểm tra cập nhật"
+auto_check_disabled = "Tắt"
+auto_check_hourly = "Mỗi giờ"
+auto_check_daily = "Hằng ngày"
+auto_check_weekly = "Hằng tuần"
+exit = "Thoát"
+restart = "Khởi động lại"
+show_widget = "Hiện widget"
+session_window = "5g"
+weekly_window = "7n"
+now = "ngay"
+day_suffix = "n"
+hour_suffix = "g"
+minute_suffix = "p"
+second_suffix = "s"
+token_expired_title = "Phiên Claude Code đã hết hạn"
+token_expired_body = "Hãy đăng nhập lại để tiếp tục theo dõi mức sử dụng."
+chatgpt_token_expired_title = "Phiên Codex đã hết hạn"
+chatgpt_token_expired_body = "Hãy đăng nhập lại để tiếp tục theo dõi mức sử dụng."
+threshold_80_body = "Sắp chạm giới hạn 5 giờ."
+threshold_95_body = "Sắp tới giới hạn — hãy cân nhắc giảm tốc."
+update_applied_title = "Đã áp dụng cập nhật"
+update_applied_body = "Đã cập nhật lên v"
+update_rollback_failed_body = "Cập nhật thất bại. Tệp gốc của bạn được lưu tại: "

src/i18n/locales/zh-TW.toml

@@ -44,3 +44,6 @@ chatgpt_token_expired_title = "Codex 工作階段已過期"
 chatgpt_token_expired_body = "請重新登入以繼續追蹤使用量。"
 threshold_80_body = "接近 5 小時上限。"
 threshold_95_body = "上限將至 — 建議稍作休息。"
+update_applied_title = "已套用更新"
+update_applied_body = "已更新至 v"
+update_rollback_failed_body = "更新失敗。您的原始執行檔已保存於: "

src/i18n/mod.rs

@@ -68,6 +68,13 @@ pub struct LocaleStrings {
     pub threshold_80_body: String,
     /// Body text for the 95% threshold balloon.
     pub threshold_95_body: String,
+    /// Title for the tray balloon shown on first launch after an auto-update.
+    pub update_applied_title: String,
+    /// Prefix for the tray balloon body. Call site appends the version (e.g. "0.1.10").
+    pub update_applied_body: String,
+    /// Prefix for the rollback-failed MessageBox body. Call site appends
+    /// the backup path and a separator with the expected target filename.
+    pub update_rollback_failed_body: String,
 }
 
 #[derive(Deserialize)]
@@ -80,12 +87,9 @@ struct LocaleFile {
 
 const RAW_LOCALES: &[(&str, &str)] = &[
     ("en", include_str!("locales/en.toml")),
-    ("nl", include_str!("locales/nl.toml")),
-    ("es", include_str!("locales/es.toml")),
-    ("fr", include_str!("locales/fr.toml")),
-    ("de", include_str!("locales/de.toml")),
     ("ja", include_str!("locales/ja.toml")),
     ("ko", include_str!("locales/ko.toml")),
+    ("vi", include_str!("locales/vi.toml")),
     ("zh-TW", include_str!("locales/zh-TW.toml")),
 ];
 

src/main.rs

@@ -13,6 +13,7 @@ mod os;
 mod tray;
 mod update;
 mod usage;
+mod usage_color;
 
 // Application surface.
 mod app;
@@ -36,8 +37,34 @@ fn main() {
         std::process::exit(exit_code);
     }
 
-    if diagnose_enabled {
-        log::info!("entering app::run");
+    let wait_pid = args
+        .iter()
+        .position(|a| a == "--wait-pid")
+        .and_then(|i| args.get(i + 1))
+        .and_then(|s| s.parse::<u32>().ok());
+    if let Some(pid) = wait_pid {
+        if diagnose_enabled {
+            log::info!("waiting up to 5s for parent pid {pid} to exit");
+        }
+        update::handoff::wait_for_parent_exit(pid, 5_000);
     }
-    app::run();
+
+    let updated_to = args
+        .iter()
+        .position(|a| a == "--updated-to")
+        .and_then(|i| args.get(i + 1))
+        .cloned();
+
+    if diagnose_enabled {
+        log::info!("entering app::run (wait_pid={wait_pid:?} updated_to={updated_to:?})");
+    }
+    app::run(AppArgs {
+        wait_pid_present: wait_pid.is_some(),
+        updated_to,
+    });
+}
+
+pub struct AppArgs {
+    pub wait_pid_present: bool,
+    pub updated_to: Option<String>,
 }

src/panel.rs

@@ -7,15 +7,18 @@ use std::sync::{Mutex, MutexGuard, OnceLock};
 
 use windows::core::PCWSTR;
 use windows::Win32::Foundation::*;
+use windows::Win32::Graphics::Dwm::{
+    DwmSetWindowAttribute, DWMWA_WINDOW_CORNER_PREFERENCE, DWMWCP_ROUND,
+};
 use windows::Win32::Graphics::Gdi::*;
 use windows::Win32::System::LibraryLoader::GetModuleHandleW;
 use windows::Win32::UI::HiDpi::GetDpiForWindow;
 use windows::Win32::UI::WindowsAndMessaging::*;
 
 use crate::i18n::LocaleStrings;
+use crate::os::dpi::scale as scale_to_dpi;
 use crate::os::{to_utf16_nul as wide_str, Rgb as Color};
 use crate::usage::ProviderId;
-type TrayIconKind = ProviderId;
 
 const CLASS_NAME: &str = "ClaudeCodeUsageBubblePanel";
 const PANEL_W_LOGICAL: i32 = 280;
@@ -27,7 +30,7 @@ const RIGHT_TEXT_W_LOGICAL: i32 = 96;
 const BAR_HEIGHT_LOGICAL: i32 = 14;
 
 pub struct PanelData {
-    pub model: TrayIconKind,
+    pub model: ProviderId,
     pub session_pct: f64,
     pub session_text: String,
     pub weekly_pct: f64,
@@ -83,7 +86,7 @@ pub fn is_visible() -> bool {
         .unwrap_or(false)
 }
 
-pub fn current_model() -> Option<TrayIconKind> {
+pub fn current_model() -> Option<ProviderId> {
     lock_state().as_ref().map(|p| p.data.model)
 }
 
@@ -118,6 +121,8 @@ pub fn show(data: PanelData, anchor_hwnd: HWND) {
         },
     };
 
+    apply_win11_window_chrome(hwnd);
+
     {
         let mut guard = lock_state();
         if let Some(p) = guard.as_mut() {
@@ -152,7 +157,7 @@ fn create_panel_window(x: i32, y: i32, w: i32, h: i32) -> Option<HWND> {
             WS_EX_TOOLWINDOW | WS_EX_TOPMOST,
             PCWSTR::from_raw(class_w.as_ptr()),
             PCWSTR::from_raw(title_w.as_ptr()),
-            WS_POPUP | WS_BORDER,
+            WS_POPUP,
             x,
             y,
             w,
@@ -172,6 +177,23 @@ fn create_panel_window(x: i32, y: i32, w: i32, h: i32) -> Option<HWND> {
     }
 }
 
+/// Apply Windows 11 rounded corners. Win11-only — `DwmSetWindowAttribute`
+/// returns an error on Win10 and earlier, which we deliberately swallow so
+/// the panel falls back to square corners without complaint. Idempotent:
+/// DWM ignores redundant identical-value sets, so calling this on every
+/// `show()` is safe.
+fn apply_win11_window_chrome(hwnd: HWND) {
+    unsafe {
+        let pref = DWMWCP_ROUND;
+        let _ = DwmSetWindowAttribute(
+            hwnd,
+            DWMWA_WINDOW_CORNER_PREFERENCE,
+            &pref as *const _ as *const _,
+            std::mem::size_of_val(&pref) as u32,
+        );
+    }
+}
+
 pub fn hide() {
     let hwnd_opt = lock_state().as_ref().map(|p| p.hwnd);
     if let Some(hwnd) = hwnd_opt {
@@ -269,21 +291,17 @@ fn paint(hwnd: HWND, hdc: HDC) {
     } else {
         Color::from_hex("#D6D6D6")
     };
-    let accent = bar_color_for(data.model, data.session_pct.max(data.weekly_pct), data.is_dark);
+    let session_accent =
+        crate::usage_color::bar_fill_color(data.model, data.is_dark, data.session_pct);
+    let weekly_accent =
+        crate::usage_color::bar_fill_color(data.model, data.is_dark, data.weekly_pct);
 
     unsafe {
         let bg_brush = CreateSolidBrush(COLORREF(bg.into_colorref()));
         FillRect(hdc, &rc, bg_brush);
         let _ = DeleteObject(bg_brush);
 
-        // 4-px accent stripe matching the bubble — same provider color so the
-        // identity carries across both surfaces. Codex is theme-aware so a
-        // pure white stripe doesn't vanish into the light-mode background.
-        let stripe_color = match (data.model, data.is_dark) {
-            (ProviderId::Claude, _) => Color::from_hex("#D97757"),
-            (ProviderId::ChatGpt, true) => Color::from_hex("#FFFFFF"),
-            (ProviderId::ChatGpt, false) => Color::from_hex("#2A2A2A"),
-        };
+        let stripe_color = crate::usage_color::accent_color_for(data.model, data.is_dark);
         let stripe_w = scaled(4);
         let stripe_rect = RECT {
             left: 0,
@@ -333,7 +351,7 @@ fn paint(hwnd: HWND, hdc: HDC) {
             &data.session_text,
             text_color,
             track,
-            accent,
+            session_accent,
             dpi,
         );
 
@@ -349,7 +367,7 @@ fn paint(hwnd: HWND, hdc: HDC) {
             &data.weekly_text,
             text_color,
             track,
-            accent,
+            weekly_accent,
             dpi,
         );
     }
@@ -482,10 +500,6 @@ fn draw_text(
     }
 }
 
-fn bar_color_for(model: ProviderId, percent: f64, is_dark: bool) -> Color {
-    crate::bubble::bar_fill_color(model, is_dark, percent)
-}
-
 fn clone_data() -> Option<PanelData> {
     let guard = lock_state();
     let p = guard.as_ref()?;
@@ -528,7 +542,3 @@ fn place_near(anchor: RECT, panel_w: i32, panel_h: i32) -> (i32, i32) {
     }
     (x, y)
 }
-
-fn scale_to_dpi(logical: i32, dpi: u32) -> i32 {
-    ((logical as i64) * (dpi as i64) / 96) as i32
-}

src/settings.rs

@@ -6,7 +6,6 @@ use windows::Win32::Graphics::Gdi::{MonitorFromRect, MONITOR_DEFAULTTONULL};
 
 use crate::bubble::DEFAULT_BUBBLE_SIZE;
 use crate::usage::ProviderId;
-type TrayIconKind = ProviderId;
 
 // 140px matches MIN_BUBBLE_SIZE — a saved top-left a few px past the work-area
 // edge still passes the validator, but a position fully on a disconnected
@@ -52,19 +51,19 @@ pub struct BubblePositions {
 }
 
 impl BubblePositions {
-    pub fn get(&self, model: TrayIconKind) -> Option<(i32, i32)> {
+    pub fn get(&self, model: ProviderId) -> Option<(i32, i32)> {
         match model {
             ProviderId::Claude => self.claude,
             ProviderId::ChatGpt => self.codex,
         }
     }
-    pub fn set(&mut self, model: TrayIconKind, pos: (i32, i32)) {
+    pub fn set(&mut self, model: ProviderId, pos: (i32, i32)) {
         match model {
             ProviderId::Claude => self.claude = Some(pos),
             ProviderId::ChatGpt => self.codex = Some(pos),
         }
     }
-    pub fn reset(&mut self, model: TrayIconKind) {
+    pub fn reset(&mut self, model: ProviderId) {
         match model {
             ProviderId::Claude => self.claude = None,
             ProviderId::ChatGpt => self.codex = None,

src/tray/badge.rs

@@ -9,8 +9,7 @@
 use std::ffi::c_void;
 
 use tiny_skia::{FillRule, Paint, PathBuilder, Pixmap, Stroke, Transform};
-use windows::core::PCWSTR;
-use windows::Win32::Foundation::HWND;
+use windows::Win32::Foundation::{BOOL, HWND};
 use windows::Win32::Graphics::Gdi::{
     CreateBitmap, CreateDIBSection, DeleteObject, GetDC, ReleaseDC, BITMAPINFO, BITMAPINFOHEADER,
     DIB_RGB_COLORS, HBITMAP,
@@ -66,7 +65,7 @@ fn render_pixmap(kind: ProviderId, percent: Option<f64>) -> Pixmap {
     if let Some(p) = percent {
         let sweep = (p.clamp(0.0, 100.0) / 100.0) as f32;
         if sweep > 0.0 {
-            let fill = usage_color(p);
+            let fill = usage_color(kind, p);
             let mut paint = Paint::default();
             paint.set_color_rgba8(fill[0], fill[1], fill[2], 255);
             paint.anti_alias = true;
@@ -116,33 +115,12 @@ fn base_color(kind: ProviderId) -> [u8; 3] {
     }
 }
 
-fn usage_color(percent: f64) -> [u8; 3] {
-    // Color gradient: soft orange (low usage) → red (near-cap).
-    let stops: [(f64, [u8; 3]); 5] = [
-        (0.0, [0xD9, 0x77, 0x57]),
-        (50.0, [0xD9, 0x77, 0x57]),
-        (75.0, [0xCC, 0x8C, 0x20]),
-        (90.0, [0xC4, 0x50, 0x20]),
-        (100.0, [0xB8, 0x20, 0x20]),
-    ];
-    for pair in stops.windows(2) {
-        let (a_p, a_c) = pair[0];
-        let (b_p, b_c) = pair[1];
-        if percent <= b_p {
-            let span = (b_p - a_p).max(f64::EPSILON);
-            let t = ((percent - a_p) / span).clamp(0.0, 1.0);
-            return [
-                lerp(a_c[0], b_c[0], t),
-                lerp(a_c[1], b_c[1], t),
-                lerp(a_c[2], b_c[2], t),
-            ];
-        }
-    }
-    stops[stops.len() - 1].1
-}
-
-fn lerp(a: u8, b: u8, t: f64) -> u8 {
-    (a as f64 + (b as f64 - a as f64) * t).round() as u8
+/// Sweep-ring fill color for the tray badge. The badge inner disk is always
+/// dark regardless of system theme, so we pass `is_dark = true` to keep the
+/// ring readable (Codex sweep stays white instead of charcoal).
+fn usage_color(kind: ProviderId, percent: f64) -> [u8; 3] {
+    let c = crate::usage_color::bar_fill_color(kind, true, percent);
+    [c.r, c.g, c.b]
 }
 
 // ---------- Pixmap → HICON ----------
@@ -220,9 +198,3 @@ fn pixmap_to_hicon(pixmap: &Pixmap) -> Option<HICON> {
         hicon
     }
 }
-
-// Silence import warnings if we end up not needing PCWSTR after later edits.
-#[allow(dead_code)]
-const _: PCWSTR = PCWSTR::null();
-
-use windows::Win32::Foundation::BOOL;

src/tray/mod.rs

@@ -11,8 +11,8 @@ use std::sync::{Mutex, OnceLock};
 
 use windows::Win32::Foundation::HWND;
 use windows::Win32::UI::Shell::{
-    Shell_NotifyIconW, NIF_ICON, NIF_INFO, NIF_MESSAGE, NIF_TIP, NIIF_WARNING, NIM_ADD,
-    NIM_DELETE, NIM_MODIFY, NOTIFYICONDATAW,
+    Shell_NotifyIconW, NIF_ICON, NIF_INFO, NIF_MESSAGE, NIF_TIP, NIIF_INFO, NIIF_WARNING,
+    NIM_ADD, NIM_DELETE, NIM_MODIFY, NOTIFYICONDATAW, NOTIFY_ICON_INFOTIP_FLAGS,
 };
 use windows::Win32::UI::WindowsAndMessaging::DestroyIcon;
 
@@ -81,13 +81,28 @@ pub fn sync(owner: HWND, desired: &[TrayIcon]) {
     }
 }
 
-/// Show a balloon notification on an already-registered icon.
-pub fn notify(owner: HWND, kind: IconKind, title: &str, body: &str) {
+/// Show a yellow-warning balloon on an already-registered icon.
+pub fn notify_warning(owner: HWND, kind: IconKind, title: &str, body: &str) {
+    notify_inner(owner, kind, title, body, NIIF_WARNING);
+}
+
+/// Show a blue-info balloon on an already-registered icon.
+pub fn notify_info(owner: HWND, kind: IconKind, title: &str, body: &str) {
+    notify_inner(owner, kind, title, body, NIIF_INFO);
+}
+
+fn notify_inner(
+    owner: HWND,
+    kind: IconKind,
+    title: &str,
+    body: &str,
+    flags: NOTIFY_ICON_INFOTIP_FLAGS,
+) {
     let mut data = build_data(owner, kind);
     data.uFlags = NIF_INFO;
     write_utf16(&mut data.szInfoTitle, title);
     write_utf16(&mut data.szInfo, body);
-    data.dwInfoFlags = NIIF_WARNING;
+    data.dwInfoFlags = flags;
     unsafe {
         let _ = Shell_NotifyIconW(NIM_MODIFY, &data);
     }

src/update/handoff.rs

@@ -0,0 +1,133 @@
+// Native Win32 process + file handoff primitives used by the in-app
+// restart path and the auto-update install path. The main binary uses
+// `windows_subsystem = "windows"`, so spawning the child directly via
+// `CreateProcessW` allocates no console — nothing can flash.
+
+use std::ffi::OsString;
+use std::io;
+use std::os::windows::ffi::OsStrExt;
+use std::path::Path;
+
+use windows::core::PCWSTR;
+use windows::Win32::Foundation::{CloseHandle, FALSE, HANDLE, WAIT_OBJECT_0};
+use windows::Win32::System::Threading::{
+    CreateProcessW, OpenProcess, WaitForSingleObject, CREATE_NEW_PROCESS_GROUP,
+    CREATE_NO_WINDOW, DETACHED_PROCESS, PROCESS_INFORMATION, PROCESS_SYNCHRONIZE,
+    STARTUPINFOW,
+};
+
+/// Spawn `exe` with the supplied args as a detached, console-less child.
+///
+/// Caller is fire-and-forget: the child's handles are closed immediately
+/// so no zombie wait is required.
+pub fn spawn_detached(exe: &Path, args: &[OsString]) -> io::Result<()> {
+    let mut cmdline = build_command_line(exe, args);
+
+    let si = STARTUPINFOW {
+        cb: std::mem::size_of::<STARTUPINFOW>() as u32,
+        ..Default::default()
+    };
+    let mut pi = PROCESS_INFORMATION::default();
+
+    let flags = CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP;
+    let ok = unsafe {
+        CreateProcessW(
+            PCWSTR::null(),
+            windows::core::PWSTR(cmdline.as_mut_ptr()),
+            None,
+            None,
+            FALSE,
+            flags,
+            None,
+            PCWSTR::null(),
+            &si,
+            &mut pi,
+        )
+    };
+
+    if ok.is_err() {
+        return Err(io::Error::last_os_error());
+    }
+
+    unsafe {
+        if !pi.hThread.is_invalid() {
+            let _ = CloseHandle(pi.hThread);
+        }
+        if !pi.hProcess.is_invalid() {
+            let _ = CloseHandle(pi.hProcess);
+        }
+    }
+    // Suppress the unused-variable warning until si.lpReserved fields ever matter.
+    let _ = &si;
+    Ok(())
+}
+
+/// Wait up to `timeout_ms` for `pid` to exit. Silent on any failure —
+/// caller treats this as a best-effort barrier before acquiring the
+/// singleton mutex.
+pub fn wait_for_parent_exit(pid: u32, timeout_ms: u32) {
+    let handle: HANDLE = match unsafe { OpenProcess(PROCESS_SYNCHRONIZE, FALSE, pid) } {
+        Ok(h) if !h.is_invalid() => h,
+        _ => return,
+    };
+    unsafe {
+        let res = WaitForSingleObject(handle, timeout_ms);
+        if res != WAIT_OBJECT_0 {
+            log::debug!("wait_for_parent_exit pid={pid} timeout/err res={:?}", res.0);
+        }
+        let _ = CloseHandle(handle);
+    }
+}
+
+/// Remove leftover `<exe>.old.<pid>` siblings from previous in-place updates.
+/// Filled in by phase 4; stubbed here so phase 1 can wire the call sites.
+pub fn cleanup_stale_old_exes(current_exe: &Path) {
+    let Some(dir) = current_exe.parent() else {
+        return;
+    };
+    let Some(stem) = current_exe.file_name() else {
+        return;
+    };
+    let prefix = format!("{}.old.", stem.to_string_lossy());
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        if name.to_string_lossy().starts_with(&prefix) {
+            if let Err(e) = std::fs::remove_file(entry.path()) {
+                log::debug!(
+                    "cleanup_stale_old_exes: remove {:?} failed: {e}",
+                    entry.path()
+                );
+            }
+        }
+    }
+}
+
+fn build_command_line(exe: &Path, args: &[OsString]) -> Vec<u16> {
+    // CreateProcessW parses argv[0] from a quoted exe path. We wrap the
+    // exe in `"…"` and join args separated by spaces. Args are quoted
+    // only when they contain whitespace; our callers pass simple tokens
+    // (--wait-pid <number>, --updated-to <version>) so naive quoting is
+    // sufficient.
+    let mut line = String::new();
+    line.push('"');
+    line.push_str(&exe.to_string_lossy());
+    line.push('"');
+    for a in args {
+        line.push(' ');
+        let s = a.to_string_lossy();
+        if s.chars().any(|c| c.is_whitespace()) {
+            line.push('"');
+            line.push_str(&s);
+            line.push('"');
+        } else {
+            line.push_str(&s);
+        }
+    }
+    let mut wide: Vec<u16> = std::ffi::OsString::from(line).encode_wide().collect();
+    wide.push(0);
+    wide
+}

src/update/install.rs

@@ -1,42 +1,47 @@
-// Download a release asset and hand off via inline `cmd /c`.
+// Download a release asset and swap it in via native Win32 calls.
 //
-// We avoid the helper-exe pattern entirely: after writing the new .exe
-// to a staging path, we spawn cmd.exe with a one-liner that waits 2 s,
-// moves the new binary over the running one (Windows releases the file
-// lock when our process exits), and relaunches it.
+// After writing the new .exe to a staging path and verifying its
+// SHA-256, we `MoveFileExW` the running exe sideways (so Windows
+// releases the file lock on our own image), then `MoveFileExW` the
+// staged exe into place, then spawn the new binary detached via
+// `handoff::spawn_detached`. No shell, no console allocation.
 
-use std::os::windows::process::CommandExt;
-use std::path::PathBuf;
-use std::process::{Command, Stdio};
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
 
 use sha2::{Digest, Sha256};
 
-use crate::net::Client;
+use windows::core::PCWSTR;
+use windows::Win32::Storage::FileSystem::{
+    MoveFileExW, MOVEFILE_COPY_ALLOWED, MOVEFILE_REPLACE_EXISTING, MOVE_FILE_FLAGS,
+};
+use windows::Win32::System::Threading::GetCurrentProcessId;
+use windows::Win32::UI::WindowsAndMessaging::{
+    MessageBoxW, MB_ICONERROR, MB_OK,
+};
 
-const CREATE_NO_WINDOW: u32 = 0x0800_0000;
-const DETACHED_PROCESS: u32 = 0x0000_0008;
+use crate::net::Client;
+use crate::os::to_utf16_nul;
 
 pub fn begin(http: &Client, release: &super::Release) -> Result<(), super::Error> {
     let current = std::env::current_exe()?;
     ensure_writable(&current)?;
     let staging = stage_path()?;
-    // Refuse to proceed if either path contains `%`. Inside double quotes
-    // cmd.exe still expands `%var%` references, so a path containing `%`
-    // would let cmd substitute environment variables into the swap step.
-    // Such paths are vanishingly rare on real Windows installs; failing
-    // fast is safer than rolling a bespoke cmd-escape layer.
+    // Defense in depth: `MoveFileExW` itself is immune to `%`-expansion
+    // (no shell parses our paths), but the existing rejection guards
+    // future code paths that might invoke external tools, so keep it.
     reject_unsafe_path(&current)?;
     reject_unsafe_path(&staging)?;
     if let Some(parent) = staging.parent() {
         std::fs::create_dir_all(parent)?;
     }
     download(http, &release.asset_url, &staging, release.asset_sha256.as_ref())?;
-    spawn_handoff(&staging, &current)?;
+    swap_and_spawn(&staging, &current, &release.version)?;
     Ok(())
 }
 
 /// CLI entry-point compatibility for `--apply-update <target> <source> <pid>`.
-/// The inline-cmd handoff already does the swap-and-restart; if this binary
+/// The native handoff already does the swap-and-restart; if this binary
 /// is invoked with the legacy flag (e.g. from an older release's helper)
 /// just exit cleanly so the upgrade still completes.
 pub fn run_cli(args: &[String]) -> Option<i32> {
@@ -50,7 +55,7 @@ pub fn run_cli(args: &[String]) -> Option<i32> {
 fn download(
     http: &Client,
     url: &str,
-    to: &std::path::Path,
+    to: &Path,
     expected_sha256: Option<&[u8; 32]>,
 ) -> Result<(), super::Error> {
     let resp = http
@@ -86,40 +91,119 @@ fn hex_encode(bytes: &[u8]) -> String {
     out
 }
 
-fn reject_unsafe_path(p: &std::path::Path) -> Result<(), super::Error> {
+fn reject_unsafe_path(p: &Path) -> Result<(), super::Error> {
     let s = p.to_string_lossy();
     if s.contains('%') {
         return Err(super::Error::UnsafePath(format!(
-            "path contains '%' which cmd.exe expands as a variable: {s}"
+            "path contains '%': {s}"
         )));
     }
     Ok(())
 }
 
-fn spawn_handoff(source: &std::path::Path, target: &std::path::Path) -> Result<(), super::Error> {
-    let src_str = source.to_string_lossy().replace('"', "");
-    let tgt_str = target.to_string_lossy().replace('"', "");
-    // 2-second wait gives the current process time to exit and release the
-    // file lock before `move` overwrites it.
-    let cmd = format!(
-        r#"timeout /t 2 /nobreak >nul & move /y "{src_str}" "{tgt_str}" & start "" "{tgt_str}""#
-    );
-    // raw_arg bypasses Rust's std auto-escaping which would turn the inner
-    // `"` characters into `\"`. cmd.exe does not recognise `\"`, so the
-    // escaped form makes `start` see the path as `\\` and emit a
-    // "Windows cannot find '\\'" dialog. Feeding the command line raw
-    // preserves the quotes cmd.exe actually expects.
-    Command::new("cmd.exe")
-        .raw_arg("/c")
-        .raw_arg(format!("\"{cmd}\""))
-        .creation_flags(CREATE_NO_WINDOW | DETACHED_PROCESS)
-        .stdin(Stdio::null())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()?;
+fn swap_and_spawn(
+    source: &Path,
+    target: &Path,
+    version: &super::release::Version,
+) -> Result<(), super::Error> {
+    let backup = backup_path(target);
+    // Step 1: rename running exe sideways. Windows allows renaming a
+    // file even while its image is mapped into memory; this releases
+    // the lock on the original `target` path. Same directory by
+    // construction, so plain MoveFileExW with no flags is sufficient.
+    move_file(target, &backup, MOVE_FILE_FLAGS(0))?;
+
+    // Step 2: move staged exe into place. Staging lives under
+    // %LOCALAPPDATA%, target lives wherever the user installed —
+    // COPY_ALLOWED lets MoveFileExW fall back to copy+delete when
+    // the two paths cross volumes (portable installs on D:/E:/etc.).
+    let step2_flags = MOVEFILE_REPLACE_EXISTING | MOVEFILE_COPY_ALLOWED;
+    if let Err(swap_err) = move_file(source, target, step2_flags) {
+        // Best-effort revert. Same volume, no COPY_ALLOWED needed.
+        if let Err(revert_err) = move_file(&backup, target, MOVEFILE_REPLACE_EXISTING) {
+            log::error!("rollback also failed: {revert_err}; surfacing modal");
+            let target_name = target
+                .file_name()
+                .map(|s| s.to_string_lossy().into_owned())
+                .unwrap_or_else(|| "claude-code-usage-bubble.exe".to_string());
+            surface_rollback_failure(&backup, &target_name);
+        }
+        return Err(swap_err);
+    }
+
+    // Step 3: spawn the new exe detached with --wait-pid + --updated-to.
+    let pid = unsafe { GetCurrentProcessId() };
+    let version_str = format!("{}.{}.{}", version.major, version.minor, version.patch);
+    let args = vec![
+        OsString::from("--wait-pid"),
+        OsString::from(pid.to_string()),
+        OsString::from("--updated-to"),
+        OsString::from(version_str),
+    ];
+    if let Err(spawn_err) = super::handoff::spawn_detached(target, &args) {
+        // New binary is on disk but won't auto-launch. Roll back so
+        // the user's next "Restart" stays on the known-good version.
+        log::error!("spawn_detached failed after swap: {spawn_err}; attempting revert");
+        if let Err(revert_err) = move_file(&backup, target, MOVEFILE_REPLACE_EXISTING) {
+            log::error!("post-spawn revert failed: {revert_err}");
+        }
+        return Err(super::Error::Io(spawn_err));
+    }
     Ok(())
 }
 
+fn move_file(src: &Path, dst: &Path, flags: MOVE_FILE_FLAGS) -> Result<(), super::Error> {
+    let src_w = to_utf16_nul(&src.to_string_lossy());
+    let dst_w = to_utf16_nul(&dst.to_string_lossy());
+    let result = unsafe {
+        MoveFileExW(
+            PCWSTR::from_raw(src_w.as_ptr()),
+            PCWSTR::from_raw(dst_w.as_ptr()),
+            flags,
+        )
+    };
+    result.map_err(|e| {
+        super::Error::SwapFailed(format!(
+            "MoveFileExW({} -> {}): {e}",
+            src.display(),
+            dst.display()
+        ))
+    })
+}
+
+fn backup_path(target: &Path) -> PathBuf {
+    let pid = unsafe { GetCurrentProcessId() };
+    let fname = target
+        .file_name()
+        .map(|s| s.to_string_lossy().into_owned())
+        .unwrap_or_else(|| "exe".to_string());
+    let mut p = target.to_owned();
+    p.set_file_name(format!("{fname}.old.{pid}"));
+    p
+}
+
+fn surface_rollback_failure(backup: &Path, target_name: &str) {
+    // Pull the localized body from i18n; the caller passes the
+    // user-meaningful filename so we can format it in-place.
+    let strings = crate::i18n::I18n::load(None).strings().clone();
+    let body = format!(
+        "{}{}\n\n{}",
+        strings.update_rollback_failed_body,
+        backup.display(),
+        target_name
+    );
+    let title_w = to_utf16_nul(&strings.update_failed);
+    let body_w = to_utf16_nul(&body);
+    unsafe {
+        MessageBoxW(
+            None,
+            PCWSTR::from_raw(body_w.as_ptr()),
+            PCWSTR::from_raw(title_w.as_ptr()),
+            MB_OK | MB_ICONERROR,
+        );
+    }
+}
+
 fn stage_path() -> Result<PathBuf, super::Error> {
     let base = dirs::data_local_dir().ok_or_else(|| {
         super::Error::NotWritable("no local data directory available".to_string())
@@ -130,7 +214,7 @@ fn stage_path() -> Result<PathBuf, super::Error> {
         .join("update.exe"))
 }
 
-fn ensure_writable(target: &std::path::Path) -> Result<(), super::Error> {
+fn ensure_writable(target: &Path) -> Result<(), super::Error> {
     let parent = target.parent().ok_or_else(|| {
         super::Error::NotWritable("could not resolve install directory".to_string())
     })?;

src/update/mod.rs

@@ -1,10 +1,12 @@
 // Self-update subsystem.
 //
 // Two stages: `release::fetch_latest` checks GitHub releases for a newer
-// build; `install::begin` downloads the .exe and hands off to a detached
-// `cmd /c` script that swaps the binary and restarts.
+// build; `install::begin` downloads the .exe, swaps it in via native
+// `MoveFileExW`, then spawns the new binary detached via
+// `CreateProcessW`. No shell handoff — nothing can flash a console.
 
 pub mod channel;
+pub mod handoff;
 pub mod install;
 pub mod release;
 
@@ -24,6 +26,8 @@ pub enum Error {
     ChecksumMismatch { expected: String, actual: String },
     #[error("path rejected for safety: {0}")]
     UnsafePath(String),
+    #[error("file swap failed: {0}")]
+    SwapFailed(String),
 }
 
 pub use channel::{current as current_channel, Channel};

src/usage/anthropic.rs

@@ -133,7 +133,7 @@ fn try_messages_endpoint(http: &Client, token: &str) -> Result<UsageWindows, Err
 
 fn bucket_to_window(bucket: Bucket) -> Window {
     Window {
-        utilization: bucket.utilization,
+        utilization: bucket.utilization.clamp(0.0, 100.0),
         resets_at: bucket.resets_at.as_deref().and_then(parse_iso8601),
     }
 }
@@ -163,18 +163,21 @@ fn token_is_expired(expires_at_unix_ms: Option<i64>) -> bool {
     now_ms >= exp_ms
 }
 
-// --- ISO 8601 parsing (minimal — handles "YYYY-MM-DDTHH:MM:SS[.frac][Z|+00:00]") ---
+// --- ISO 8601 parsing (minimal — handles "YYYY-MM-DDTHH:MM:SS[.frac][Z|±HH:MM]") ---
 
 fn parse_iso8601(s: &str) -> Option<SystemTime> {
-    let trimmed = s.split('Z').next().unwrap_or(s);
-    let trimmed = trimmed.split('+').next().unwrap_or(trimmed);
-    let trimmed = trimmed.split('-').take(3).collect::<Vec<_>>().join("-");
-    // We want the original `s` for parsing time-part. Re-split on 'T'.
-    let (date, time) = s
-        .split_once('T')
-        .map(|(d, t)| (d, t))
-        .or_else(|| Some(("", "")))?;
-    let _ = trimmed; // shadow; using the raw `date` + `time` below.
+    let (date, time_with_offset) = s.split_once('T')?;
+
+    // Split the time-and-offset on the first 'Z' / '+' / '-' marker.
+    let offset_pos = time_with_offset
+        .char_indices()
+        .find(|(_, c)| matches!(c, 'Z' | '+' | '-'))
+        .map(|(i, _)| i);
+    let (time, offset_str) = match offset_pos {
+        Some(p) => (&time_with_offset[..p], &time_with_offset[p..]),
+        None => (time_with_offset, ""),
+    };
+    let time = time.split_once('.').map_or(time, |(t, _)| t);
 
     let date_parts: Vec<&str> = date.split('-').collect();
     if date_parts.len() != 3 {
@@ -183,13 +186,16 @@ fn parse_iso8601(s: &str) -> Option<SystemTime> {
     let y: u64 = date_parts[0].parse().ok()?;
     let mo: u64 = date_parts[1].parse().ok()?;
     let d: u64 = date_parts[2].parse().ok()?;
+    if y < 1970 || mo == 0 || mo > 12 || d == 0 {
+        return None;
+    }
+    const DAYS_IN_MONTH: [u64; 13] = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    let max_day = DAYS_IN_MONTH[mo as usize] + if mo == 2 && is_leap(y) { 1 } else { 0 };
+    if d > max_day {
+        return None;
+    }
 
-    let time_no_offset = time
-        .split(|c| c == 'Z' || c == '+' || (c == '-' && time.find(c) != Some(0)))
-        .next()
-        .unwrap_or(time);
-    let time_no_frac = time_no_offset.split('.').next().unwrap_or(time_no_offset);
-    let time_parts: Vec<&str> = time_no_frac.split(':').collect();
+    let time_parts: Vec<&str> = time.split(':').collect();
     if time_parts.len() != 3 {
         return None;
     }
@@ -197,11 +203,26 @@ fn parse_iso8601(s: &str) -> Option<SystemTime> {
     let mi: u64 = time_parts[1].parse().ok()?;
     let se: u64 = time_parts[2].parse().ok()?;
 
+    let offset_minutes: i64 = if offset_str.is_empty() || offset_str == "Z" {
+        0
+    } else {
+        let sign: i64 = if offset_str.starts_with('+') {
+            1
+        } else if offset_str.starts_with('-') {
+            -1
+        } else {
+            return None;
+        };
+        let (oh_str, om_str) = offset_str[1..].split_once(':')?;
+        let oh: i64 = oh_str.parse().ok()?;
+        let om: i64 = om_str.parse().ok()?;
+        sign * (oh * 60 + om)
+    };
+
     let mut days: u64 = 0;
     for year in 1970..y {
         days += if is_leap(year) { 366 } else { 365 };
     }
-    const DAYS_IN_MONTH: [u64; 13] = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
     for month in 1..mo {
         days += DAYS_IN_MONTH[month as usize];
         if month == 2 && is_leap(y) {
@@ -209,8 +230,13 @@ fn parse_iso8601(s: &str) -> Option<SystemTime> {
         }
     }
     days += d - 1;
-    let secs = days * 86_400 + h * 3_600 + mi * 60 + se;
-    Some(UNIX_EPOCH + Duration::from_secs(secs))
+
+    let local_secs = days * 86_400 + h * 3_600 + mi * 60 + se;
+    let utc_secs = (local_secs as i64) - offset_minutes * 60;
+    if utc_secs < 0 {
+        return None;
+    }
+    Some(UNIX_EPOCH + Duration::from_secs(utc_secs as u64))
 }
 
 fn is_leap(year: u64) -> bool {

src/usage/chatgpt.rs

@@ -84,7 +84,7 @@ fn envelope_to_windows(envelope: Envelope) -> Option<UsageWindows> {
 
 fn window_from(w: ApiWindow) -> Window {
     Window {
-        utilization: w.used_percent,
+        utilization: w.used_percent.clamp(0.0, 100.0),
         resets_at: unix_to_systemtime(Some(w.reset_at)),
     }
 }

src/usage/headers.rs

@@ -15,14 +15,18 @@ use crate::usage::{UsageWindows, Window};
 pub fn parse_anthropic(response: &Response) -> UsageWindows {
     UsageWindows {
         primary: Window {
-            utilization: header_f64(response, "anthropic-ratelimit-unified-5h-utilization") * 100.0,
+            utilization: (header_f64(response, "anthropic-ratelimit-unified-5h-utilization")
+                * 100.0)
+                .clamp(0.0, 100.0),
             resets_at: unix_to_systemtime(header_i64(
                 response,
                 "anthropic-ratelimit-unified-5h-reset",
             )),
         },
         secondary: Window {
-            utilization: header_f64(response, "anthropic-ratelimit-unified-7d-utilization") * 100.0,
+            utilization: (header_f64(response, "anthropic-ratelimit-unified-7d-utilization")
+                * 100.0)
+                .clamp(0.0, 100.0),
             resets_at: unix_to_systemtime(header_i64(
                 response,
                 "anthropic-ratelimit-unified-7d-reset",

src/usage_color.rs

@@ -0,0 +1,41 @@
+// Shared usage→color ramp used by the floating bubble, the expanded panel,
+// and the tray badge. Keeping the function in one place ensures the three
+// surfaces never disagree about what "78% used" looks like.
+
+use crate::os::Rgb as Color;
+use crate::usage::ProviderId;
+
+/// Per-provider identity color. Claude = warm orange `#D97757`. Codex =
+/// OpenAI brand teal `#10A37F`, used consistently across dark and light
+/// themes so the badge/bubble/panel never disagree on Codex identity.
+pub fn accent_color_for(model: ProviderId, _is_dark: bool) -> Color {
+    match model {
+        ProviderId::Claude => Color::from_hex("#D97757"),
+        ProviderId::ChatGpt => Color::from_hex("#10A37F"),
+    }
+}
+
+/// Discrete 4-band fill color. The "safe" band uses the provider's identity
+/// color so Codex bars stay white-on-dark while Claude bars stay orange; the
+/// warning bands are theme-aware so light-mode amber stays readable against
+/// the `#F3F3F3` background.
+///
+/// - <60%   → provider accent
+/// - 60–80% → amber (dark `#E0A040`, light `#B47A20` for WCAG AA contrast)
+/// - 80–95% → red `#C45020`
+/// - ≥95%   → deep red `#A01818` — paired with pulse animation
+pub fn bar_fill_color(model: ProviderId, is_dark: bool, percent: f64) -> Color {
+    if percent < 60.0 {
+        accent_color_for(model, is_dark)
+    } else if percent < 80.0 {
+        if is_dark {
+            Color::from_hex("#E0A040")
+        } else {
+            Color::from_hex("#B47A20")
+        }
+    } else if percent < 95.0 {
+        Color::from_hex("#C45020")
+    } else {
+        Color::from_hex("#A01818")
+    }
+}