ai-battery 0.1.6 → 0.1.9

package/README.md

@@ -51,7 +51,7 @@ Codex 86% │ 5h 18:09 │ 7d 82%  ┃  Claude 4% │ 5h 18:10 │ 7d 71%
 | `ai-battery --watch` | 지원 | 지원 | 지원 | 지원 | 터미널 안에서 주기적으로 갱신합니다. |
 | Claude statusLine | 지원 | 지원 | 지원 | 지원 | Claude Code `statusLine`에 `node <script>` 명령을 저장합니다. |
 | Codex terminal row | 지원 | 지원 | 지원 | 지원 | Windows는 `node-pty`/ConPTY가 있으면 reserved row, 없으면 overlay fallback을 사용합니다. WSL/Linux/macOS는 POSIX PTY와 `python3`를 사용합니다. |
-| `ai-battery setup codex` | 지원 | 지원 | 지원 | 지원 | Windows는 `codex.cmd` wrapper, WSL/Linux/macOS는 POSIX shell wrapper를 설치합니다. |
+| `ai-battery setup codex` | 지원 | 지원 | 지원 | 지원 | Codex `[tui].status_line`을 맞추고, Windows는 `codex.cmd` wrapper, WSL/Linux/macOS는 POSIX shell wrapper를 설치합니다. |
 | `ai-battery hud` | 지원 | 지원 | 미지원 | 지원 | Windows/WSL은 PowerShell/WinForms HUD, macOS는 menu bar status item입니다. |
 
 실행 중 감지(흰색/회색 표시)는 Linux/WSL은 `/proc`, macOS는 `ps`, Windows는 PowerShell 프로세스 목록을 사용합니다.
@@ -141,7 +141,7 @@ ai-battery uninstall claude
 ai-battery uninstall hud
 ```
 
-이 명령은 AI Battery가 관리 마커를 넣은 Codex wrapper, Claude `statusLine`, HUD/menu bar autostart와 실행 중인 HUD를 정리합니다. 다른 도구가 만든 `codex` 파일이나 Claude `statusLine`은 건드리지 않습니다. 이전 버전이나 `--force`로 기존 파일을 백업한 경우에는 가능한 한 원래 파일/symlink를 복원합니다. 현재 이미 AI Battery wrapper 안에서 실행 중인 Codex 세션의 terminal row는 그 세션을 종료해야 사라집니다.
+이 명령은 AI Battery가 관리 마커를 넣은 Codex wrapper, Codex `[tui].status_line`, Claude `statusLine`, HUD/menu bar autostart와 실행 중인 HUD를 정리합니다. 다른 도구가 만든 `codex` 파일이나 Claude `statusLine`은 건드리지 않습니다. Codex config가 setup 이후 사용자가 수정한 상태라면 안전하게 그대로 둡니다. 이전 버전이나 `--force`로 기존 파일을 백업한 경우에는 가능한 한 원래 파일/symlink를 복원합니다. 현재 이미 AI Battery wrapper 안에서 실행 중인 Codex 세션의 terminal row는 그 세션을 종료해야 사라집니다.
 
 최신 npm은 패키지의 uninstall lifecycle을 실행하지 않기 때문에 `npm uninstall ai-battery` 또는 `npm uninstall -g ai-battery`만으로는 외부 통합 지점을 자동 정리할 수 없습니다. 완전히 제거하려면 npm 패키지를 지우기 전에 먼저 실행하세요.
 
@@ -150,11 +150,11 @@ ai-battery uninstall
 npm uninstall -g ai-battery
 ```
 
-이미 npm 패키지를 먼저 지운 뒤라면, 다시 설치한 다음 `ai-battery uninstall`을 실행하거나 아래 항목을 직접 확인해 제거해야 합니다: AI Battery가 만든 Codex wrapper, shell rc의 `# >>> ai-battery setup >>>` block, Claude `statusLine`, HUD/menu bar autostart.
+이미 npm 패키지를 먼저 지운 뒤라면, 다시 설치한 다음 `ai-battery uninstall`을 실행하거나 아래 항목을 직접 확인해 제거해야 합니다: AI Battery가 만든 Codex wrapper, shell rc의 `# >>> ai-battery setup >>>` block, Codex `~/.codex/config.toml`의 `[tui].status_line`, Claude `statusLine`, HUD/menu bar autostart.
 
 ## Setup
 
-`setup`은 한 번만 실행합니다. Claude Code에는 statusLine hook을 설치하고, Codex에는 platform wrapper를 설치해서 이후에는 추가 명령 없이 원래처럼 실행하게 합니다.
+`setup`은 한 번만 실행합니다. Claude Code에는 statusLine hook을 설치하고, Codex에는 기본 status line 구성과 platform wrapper를 설치해서 이후에는 추가 명령 없이 원래처럼 실행하게 합니다.
 
 ```bash
 ai-battery setup
@@ -167,7 +167,7 @@ ai-battery setup claude
 ai-battery setup codex
 ```
 
-Codex wrapper는 기존 `codex` 명령을 직접 덮어쓰지 않습니다. `~/.local/bin`이 이미 PATH에서 원본 `codex`보다 앞에 있고 `~/.local/bin/codex`가 비어 있거나 AI Battery 관리 파일이면 그 위치에 wrapper를 둬서 바로 잡히게 합니다. 그렇지 않으면 `~/.local/share/ai-battery/bin/codex`에 관리형 wrapper를 만들고, 필요한 경우 셸 설정에 이 디렉터리를 PATH 앞쪽으로 추가합니다. `~/.local/bin/codex` 같은 공용 위치에 이미 다른 파일이 있으면 덮어쓰지 않습니다. 새 터미널부터 `codex`가 자동으로 AI Battery 하단 행과 함께 실행됩니다. 같은 터미널에서 이미 `codex`를 실행한 적이 있으면 셸 캐시 때문에 `hash -r`이 한 번 필요할 수 있고, PATH 추가가 필요한 경우에는 `setup` 출력에 표시되는 `source ...` 명령을 실행하세요.
+Codex setup은 `~/.codex/config.toml`의 `[tui]`에 `model-with-reasoning`, `current-dir`, `git-branch` status line을 설정합니다. 기존 값이 있으면 uninstall 복구용으로 백업합니다. Codex wrapper는 기존 `codex` 명령을 직접 덮어쓰지 않습니다. `~/.local/bin`이 이미 PATH에서 원본 `codex`보다 앞에 있고 `~/.local/bin/codex`가 비어 있거나 AI Battery 관리 파일이면 그 위치에 wrapper를 둬서 바로 잡히게 합니다. 그렇지 않으면 `~/.local/share/ai-battery/bin/codex`에 관리형 wrapper를 만들고, 필요한 경우 셸 설정에 이 디렉터리를 PATH 앞쪽으로 추가합니다. `~/.local/bin/codex` 같은 공용 위치에 이미 다른 파일이 있으면 덮어쓰지 않습니다. 새 터미널부터 `codex`가 자동으로 AI Battery 하단 행과 함께 실행됩니다. 같은 터미널에서 이미 `codex`를 실행한 적이 있으면 셸 캐시 때문에 `hash -r`이 한 번 필요할 수 있고, PATH 추가가 필요한 경우에는 `setup` 출력에 표시되는 `source ...` 명령을 실행하세요.
 
 Windows native `cmd`/PowerShell에서는 `codex.cmd` wrapper가 Windows runner를 실행합니다. `node-pty`가 설치되어 있으면 ConPTY로 Codex 화면을 한 줄 짧게 띄워 하단 row를 예약하고, `node-pty`가 없거나 로드되지 않으면 같은 콘솔의 하단에 overlay row를 다시 그리는 fallback을 사용합니다. Claude statusLine은 일반 `cmd`/PowerShell 프롬프트가 아니라 Claude Code 안에서만 표시됩니다.
 
@@ -192,7 +192,7 @@ ai-battery on all
 
 ## Codex Terminal Row
 
-Codex 자체 status line은 수정하지 않습니다. `ai-battery setup`은 `codex` wrapper를 설치해서 사용자가 원래처럼 `codex`만 입력해도 `ai-battery-run`이 내부에서 Codex를 한 줄 짧은 PTY 안에서 실행하도록 합니다.
+`ai-battery setup`은 Codex 자체 status line을 `모델/추론강도 · 워크스페이스 · git branch` 구성으로 맞춥니다. 사용량 표시는 별도의 `codex` wrapper가 담당하므로, 사용자는 원래처럼 `codex`만 입력하면 `ai-battery-run`이 내부에서 Codex를 한 줄 짧은 PTY 안에서 실행합니다.
 
 ```bash
 codex

package/bin/ai-battery-hud.js

@@ -74,6 +74,23 @@ function buildStartProcessCommand(filePath, args) {
   return `Start-Process -WindowStyle Hidden -FilePath ${psSingleQuote(filePath)} -ArgumentList ${psSingleQuote(commandLine)}`;
 }
 
+function psInvocationArg(value) {
+  const text = String(value);
+  if (/^-[A-Za-z][A-Za-z0-9]*$/.test(text)) return text;
+  return psSingleQuote(text);
+}
+
+function powerShellCommandArgs(scriptPath, scriptArgs) {
+  const invocation = `& ${psSingleQuote(scriptPath)} ${scriptArgs.map(psInvocationArg).join(" ")}`;
+  return [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-Command",
+    invocation
+  ];
+}
+
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -413,6 +430,7 @@ const envPrefix = useWsl ? wslEnvPrefix() : "";
 const batteryCommand = configuredCommand || (useWsl
   ? `${envPrefix ? `${envPrefix} ` : ""}HOME=${shellQuote(os.homedir())} ${shellQuote(nodePath)} ${shellQuote(batteryJs)} --json`
   : `${winArgQuote(nodePath)} ${winArgQuote(batteryJs)} --json`);
+const batteryCommandBase64 = Buffer.from(batteryCommand, "utf8").toString("base64");
 
 const AUTOSTART_REG_PATH = "HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
 const AUTOSTART_REG_NAME = "AiBatteryHud";
@@ -430,7 +448,7 @@ function hudProcessStatus() {
     + "$_.Name -match '^(powershell|pwsh)' -and "
     + "$_.CommandLine -like '*ai-battery-hud.ps1*' -and "
     + "$_.CommandLine -notlike '*Start-Process*' }; "
-    + "if ($hud) { 'running (PID ' + @($hud)[0].ProcessId + ')' } else { 'stopped' }";
+    + "if ($hud) { $p = @($hud)[0]; $source = if ($p.CommandLine -like '*-UseWsl*') { 'WSL' } else { 'Windows' }; 'running (' + $source + ', PID ' + $p.ProcessId + ')' } else { 'stopped' }";
   const result = runPowerShell(query);
   return (result.stdout || "").trim() || "unknown";
 }
@@ -448,26 +466,17 @@ function autostartEnable() {
   // autostart.ps1 refreshes the local copy of the HUD script when the source
   // is reachable (the WSL share is not mounted until the distro starts), then
   // launches the copy so sign-in start never depends on WSL being up. The HUD
-  // must run as a separate "powershell -File ...ai-battery-hud.ps1" process:
-  // stop/status and the single-instance cleanup all match that command line.
-  const hudArgLiterals = [
-    "'-NoProfile'",
-    "'-ExecutionPolicy'",
-    "'Bypass'",
-    "'-File'",
-    "('\"' + $hud + '\"')",
-    "'-BatteryCommand'",
-    "('\"' + ($battery -replace '\"', '\\\"') + '\"')"
-  ];
-  if (useWsl) hudArgLiterals.push("'-UseWsl'");
-
+  // must run as a separate PowerShell process whose command line contains
+  // ai-battery-hud.ps1: stop/status and single-instance cleanup match it.
   const autostartScript = [
     "# Generated by: ai-battery hud autostart on",
     `$src = ${psSingleQuote(hudScript)}`,
     "$hud = Join-Path $PSScriptRoot 'ai-battery-hud.ps1'",
     "try { Copy-Item $src $hud -Force -ErrorAction Stop } catch { }",
     `$battery = ${psSingleQuote(batteryCommand)}`,
-    `$argList = @(${hudArgLiterals.join(", ")}) -join ' '`,
+    "$batteryB64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($battery))",
+    "$invoke = '& ' + \"'\" + ($hud -replace \"'\", \"''\") + \"'\" + ' -BatteryCommandBase64 ' + $batteryB64" + (useWsl ? " + ' -UseWsl'" : ""),
+    "$argList = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', ('\"' + ($invoke -replace '\"', '\\\"') + '\"')) -join ' '",
     "Start-Process -WindowStyle Hidden -FilePath 'powershell.exe' -ArgumentList $argList",
     ""
   ].join("\r\n");
@@ -527,29 +536,26 @@ const readyPath = (!useWsl && process.platform === "win32" && !foreground && !on
   ? path.join(os.tmpdir(), `ai-battery-hud-ready-${process.pid}-${Date.now()}.json`)
   : null;
 
-const psArgs = [
-  "-NoProfile",
-  "-ExecutionPolicy",
-  "Bypass",
-  "-File",
-  hudScript,
-  "-BatteryCommand",
-  batteryCommand,
+const hudScriptArgs = [
+  "-BatteryCommandBase64",
+  batteryCommandBase64,
   ...filteredArgs
 ];
 
 if (readyPath) {
-  psArgs.push("-ReadyPath", readyPath);
+  hudScriptArgs.push("-ReadyPath", readyPath);
 }
 
 if (initialJson) {
-  psArgs.push("-InitialJsonBase64", Buffer.from(initialJson, "utf8").toString("base64"));
+  hudScriptArgs.push("-InitialJsonBase64", Buffer.from(initialJson, "utf8").toString("base64"));
 }
 
 if (useWsl) {
-  psArgs.push("-UseWsl");
+  hudScriptArgs.push("-UseWsl");
 }
 
+const psArgs = powerShellCommandArgs(hudScript, hudScriptArgs);
+
 if (foreground || once || stop) {
   const result = spawnSync(powershell, psArgs, { stdio: "inherit", windowsHide: true });
   if (stop && (result.status ?? 0) === 0) {
@@ -571,12 +577,17 @@ if (useWsl) {
   });
   if (start.status !== 0) process.exit(start.status ?? 1);
 } else {
-  const child = spawn(powershell, psArgs, {
-    detached: true,
+  const start = spawnSync(powershell, [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-Command",
+    buildStartProcessCommand("powershell.exe", psArgs)
+  ], {
     stdio: "ignore",
     windowsHide: true
   });
-  child.unref();
+  if (start.status !== 0) process.exit(start.status ?? 1);
 }
 
 if (readyPath && !waitForFile(readyPath)) {

package/bin/ai-battery-hud.ps1

@@ -4,6 +4,7 @@ param(
   [ValidateSet("tray", "statusline", "floating")]
   [string]$Mode = $(if ($env:AI_BATTERY_HUD_MODE) { $env:AI_BATTERY_HUD_MODE } elseif ($env:CLAUDEX_BATTERY_HUD_MODE) { $env:CLAUDEX_BATTERY_HUD_MODE } else { "floating" }),
   [string]$BatteryCommand = $(if ($env:AI_BATTERY_COMMAND) { $env:AI_BATTERY_COMMAND } elseif ($env:CLAUDEX_BATTERY_COMMAND) { $env:CLAUDEX_BATTERY_COMMAND } else { "ai-battery --json" }),
+  [string]$BatteryCommandBase64 = "",
   [string]$InitialJsonBase64 = "",
   [int]$Width = 282,
   [double]$Opacity = $(if ($env:AI_BATTERY_HUD_OPACITY) { [double]$env:AI_BATTERY_HUD_OPACITY } elseif ($env:CLAUDEX_BATTERY_HUD_OPACITY) { [double]$env:CLAUDEX_BATTERY_HUD_OPACITY } else { 1.0 }),
@@ -20,6 +21,14 @@ $ErrorActionPreference = "Stop"
 Add-Type -AssemblyName System.Drawing
 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
 
+if (-not [string]::IsNullOrWhiteSpace($BatteryCommandBase64)) {
+  try {
+    $BatteryCommand = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($BatteryCommandBase64))
+  } catch {
+    # Fall back to BatteryCommand/env defaults; the HUD can still show an error row.
+  }
+}
+
 function Stop-ExistingHudProcesses {
   $currentPid = $PID
   Get-CimInstance Win32_Process |
@@ -89,6 +98,11 @@ function Get-HudStatePath {
   return Join-Path $root "hud-position.json"
 }
 
+function Get-HudSourceId {
+  if ($UseWsl) { return "wsl" }
+  return "windows"
+}
+
 function Get-HudSnapshotPath {
   $root = if ($env:LOCALAPPDATA) {
     Join-Path $env:LOCALAPPDATA "ai-battery"
@@ -96,7 +110,7 @@ function Get-HudSnapshotPath {
     Join-Path $env:TEMP "ai-battery"
   }
   New-Item -ItemType Directory -Force -Path $root | Out-Null
-  return Join-Path $root "hud-snapshot.json"
+  return Join-Path $root "hud-snapshot-$(Get-HudSourceId).json"
 }
 
 function Get-LegacyHudStatePath {
@@ -206,6 +220,7 @@ function Read-InitialHudSnapshot {
 function Write-HudSnapshot($Snapshot) {
   try {
     if (-not $Snapshot) { return }
+    $Snapshot | Add-Member -NotePropertyName "hudSource" -NotePropertyValue (Get-HudSourceId) -Force
     $Snapshot | ConvertTo-Json -Depth 20 -Compress | Set-Content -Encoding UTF8 -Path (Get-HudSnapshotPath)
   } catch {
     # The HUD can still run without a warm-start cache.
@@ -231,12 +246,36 @@ public struct AiBatteryMonitorInfo {
   public AiBatteryRect Work;
   public int Flags;
 }
+[StructLayout(LayoutKind.Sequential)]
+public struct AiBatteryPowerThrottlingState {
+  public uint Version;
+  public uint ControlMask;
+  public uint StateMask;
+}
+public delegate void AiBatteryWinEventDelegate(IntPtr hWinEventHook, uint eventType, IntPtr hwnd, int idObject, int idChild, uint dwEventThread, uint dwmsEventTime);
 public static class AiBatteryNative {
+  public const int ProcessPowerThrottling = 4;
+  public const uint PROCESS_POWER_THROTTLING_CURRENT_VERSION = 1;
+  public const uint PROCESS_POWER_THROTTLING_EXECUTION_SPEED = 0x1;
+  public const int OBJID_WINDOW = 0;
   public const int GWL_EXSTYLE = -20;
   public const int WS_EX_TRANSPARENT = 0x20;
   public const int WS_EX_TOOLWINDOW = 0x80;
   public const int WS_EX_NOACTIVATE = 0x08000000;
+  public const int SW_HIDE = 0;
+  public const int SW_SHOWNOACTIVATE = 4;
   public const UInt32 MONITOR_DEFAULTTONEAREST = 2;
+  public const UInt32 GW_HWNDNEXT = 2;
+  public const int DWMWA_CLOAKED = 14;
+  public const uint EVENT_SYSTEM_FOREGROUND = 0x0003;
+  public const uint EVENT_OBJECT_SHOW = 0x8002;
+  public const uint EVENT_OBJECT_HIDE = 0x8003;
+  public const uint EVENT_OBJECT_REORDER = 0x8004;
+  public const uint EVENT_OBJECT_LOCATIONCHANGE = 0x800B;
+  public const uint EVENT_OBJECT_CLOAKED = 0x8017;
+  public const uint EVENT_OBJECT_UNCLOAKED = 0x8018;
+  public const uint WINEVENT_OUTOFCONTEXT = 0x0000;
+  public const uint WINEVENT_SKIPOWNPROCESS = 0x0002;
   public static readonly IntPtr HWND_TOPMOST = new IntPtr(-1);
   public const UInt32 SWP_NOSIZE = 0x0001;
   public const UInt32 SWP_NOMOVE = 0x0002;
@@ -250,6 +289,26 @@ public static class AiBatteryNative {
   public static extern int SetWindowLong(IntPtr hWnd, int nIndex, int dwNewLong);
   [DllImport("user32.dll")]
   public static extern bool SetWindowPos(IntPtr hWnd, IntPtr hWndInsertAfter, int X, int Y, int cx, int cy, UInt32 uFlags);
+  [DllImport("user32.dll")]
+  public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+  [DllImport("user32.dll")]
+  public static extern IntPtr GetWindow(IntPtr hWnd, UInt32 uCmd);
+  [DllImport("user32.dll")]
+  public static extern IntPtr GetTopWindow(IntPtr hWnd);
+  [DllImport("user32.dll")]
+  public static extern bool IsWindowVisible(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet=CharSet.Auto)]
+  public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder lpClassName, int nMaxCount);
+  [DllImport("dwmapi.dll")]
+  public static extern int DwmGetWindowAttribute(IntPtr hWnd, int dwAttribute, out int pvAttribute, int cbAttribute);
+  [DllImport("kernel32.dll")]
+  public static extern IntPtr GetCurrentProcess();
+  [DllImport("kernel32.dll", SetLastError=true)]
+  public static extern bool SetProcessInformation(IntPtr hProcess, int ProcessInformationClass, ref AiBatteryPowerThrottlingState ProcessInformation, int ProcessInformationSize);
+  [DllImport("user32.dll")]
+  public static extern IntPtr SetWinEventHook(uint eventMin, uint eventMax, IntPtr hmodWinEventProc, AiBatteryWinEventDelegate lpfnWinEventProc, uint idProcess, uint idThread, uint dwFlags);
+  [DllImport("user32.dll")]
+  public static extern bool UnhookWinEvent(IntPtr hWinEventHook);
   [DllImport("user32.dll", CharSet=CharSet.Auto)]
   public static extern IntPtr FindWindow(string lpClassName, string lpWindowName);
   [DllImport("user32.dll", CharSet=CharSet.Auto)]
@@ -266,6 +325,27 @@ public static class AiBatteryNative {
 "@
 Add-Type -TypeDefinition $nativeCode
 
+function Disable-ProcessPowerThrottling {
+  # When a fullscreen app is in the foreground, Windows applies EcoQoS power
+  # throttling to background processes like this HUD, which stretches the
+  # WinForms timer from 250ms out to several seconds. That made the HUD linger
+  # over a fullscreen window for 3-5s before hiding (while unhide, which happens
+  # after throttling lifts, stayed instant). Opt the process out so the
+  # fullscreen check keeps firing on time even while backgrounded.
+  try {
+    $state = New-Object AiBatteryPowerThrottlingState
+    $state.Version = [AiBatteryNative]::PROCESS_POWER_THROTTLING_CURRENT_VERSION
+    $state.ControlMask = [AiBatteryNative]::PROCESS_POWER_THROTTLING_EXECUTION_SPEED
+    $state.StateMask = 0
+    $size = [System.Runtime.InteropServices.Marshal]::SizeOf([type][AiBatteryPowerThrottlingState])
+    return [AiBatteryNative]::SetProcessInformation([AiBatteryNative]::GetCurrentProcess(), [AiBatteryNative]::ProcessPowerThrottling, [ref]$state, $size)
+  } catch {
+    # Older Windows builds lack ProcessPowerThrottling; the HUD still works.
+    return $false
+  }
+}
+$script:powerThrottlingDisabled = Disable-ProcessPowerThrottling
+
 function Invoke-AiBatteryJson {
   if ($UseWsl) {
     $output = & wsl.exe bash -lc "$BatteryCommand 2>/dev/null"
@@ -1154,7 +1234,7 @@ function Show-HitForm {
     $hitForm.Show()
   }
   $style = [AiBatteryNative]::GetWindowLong($hitForm.Handle, [AiBatteryNative]::GWL_EXSTYLE)
-  $style = $style -bor [AiBatteryNative]::WS_EX_TOOLWINDOW
+  $style = $style -bor [AiBatteryNative]::WS_EX_TOOLWINDOW -bor [AiBatteryNative]::WS_EX_NOACTIVATE
   [AiBatteryNative]::SetWindowLong($hitForm.Handle, [AiBatteryNative]::GWL_EXSTYLE, $style) | Out-Null
 }
 
@@ -1274,21 +1354,89 @@ function Test-RectCoversMonitor($WindowRect, $MonitorRect) {
   )
 }
 
-function Test-ForegroundFullscreen {
-  if (-not $form -or $form.IsDisposed) { return $false }
-  $foreground = [AiBatteryNative]::GetForegroundWindow()
-  if ($foreground -eq [IntPtr]::Zero) { return $false }
-  if ($foreground -eq $form.Handle) { return $false }
-  if ($hitForm -and -not $hitForm.IsDisposed -and $foreground -eq $hitForm.Handle) { return $false }
+function Test-RectIsSubstantialOnMonitor($WindowRect, $MonitorRect) {
+  if (-not $WindowRect -or -not $MonitorRect) { return $false }
+  $left = [math]::Max([int]$WindowRect.Left, [int]$MonitorRect.Left)
+  $top = [math]::Max([int]$WindowRect.Top, [int]$MonitorRect.Top)
+  $right = [math]::Min([int]$WindowRect.Right, [int]$MonitorRect.Right)
+  $bottom = [math]::Min([int]$WindowRect.Bottom, [int]$MonitorRect.Bottom)
+  $width = [math]::Max(0, $right - $left)
+  $height = [math]::Max(0, $bottom - $top)
+  $monitorArea = [math]::Max(1, [int]$MonitorRect.Width * [int]$MonitorRect.Height)
+  $windowArea = $width * $height
+  return (($windowArea / $monitorArea) -ge 0.20)
+}
+
+function Test-HudWindowHandle([IntPtr]$Handle) {
+  if ($Handle -eq [IntPtr]::Zero) { return $false }
+  if ($form -and -not $form.IsDisposed -and $Handle -eq $form.Handle) { return $true }
+  if ($hitForm -and -not $hitForm.IsDisposed -and $Handle -eq $hitForm.Handle) { return $true }
+  return $false
+}
+
+function Get-WindowClassName([IntPtr]$Handle) {
+  if ($Handle -eq [IntPtr]::Zero) { return "" }
+  $builder = New-Object System.Text.StringBuilder 256
+  [AiBatteryNative]::GetClassName($Handle, $builder, $builder.Capacity) | Out-Null
+  return $builder.ToString()
+}
+
+function Test-WindowCloaked([IntPtr]$Handle) {
+  if ($Handle -eq [IntPtr]::Zero) { return $false }
+  $value = 0
+  try {
+    $hr = [AiBatteryNative]::DwmGetWindowAttribute($Handle, [AiBatteryNative]::DWMWA_CLOAKED, [ref]$value, 4)
+  } catch {
+    return $false
+  }
+  if ($hr -ne 0) { return $false }
+  return ($value -ne 0)
+}
+
+# Desktop and shell surfaces span the monitor but must never hide the HUD.
+$script:hudSkipWindowClasses = @(
+  "Shell_TrayWnd",
+  "Shell_SecondaryTrayWnd",
+  "NotifyIconOverflowWindow",
+  "Progman",
+  "WorkerW"
+)
 
+function Test-FullscreenOnHudMonitor {
+  if (-not $form -or $form.IsDisposed) { return $false }
   $hudMonitor = [AiBatteryNative]::MonitorFromWindow($form.Handle, [AiBatteryNative]::MONITOR_DEFAULTTONEAREST)
-  $foregroundMonitor = [AiBatteryNative]::MonitorFromWindow($foreground, [AiBatteryNative]::MONITOR_DEFAULTTONEAREST)
-  if ($hudMonitor -eq [IntPtr]::Zero -or $foregroundMonitor -eq [IntPtr]::Zero) { return $false }
-  if ($hudMonitor -ne $foregroundMonitor) { return $false }
+  if ($hudMonitor -eq [IntPtr]::Zero) { return $false }
+  $monitorRect = Get-MonitorRectObject $hudMonitor
+  if (-not $monitorRect) { return $false }
+
+  # Walk the Z-order from the top down. Small transient overlays (volume, IME,
+  # Game Bar, browser controls) are ignored so we can still see the fullscreen
+  # window beneath them. A substantial normal window stops the search: any
+  # fullscreen window below it is not the visible fullscreen surface.
+  $handle = [AiBatteryNative]::GetTopWindow([IntPtr]::Zero)
+  for ($scanned = 0; $scanned -lt 400 -and $handle -ne [IntPtr]::Zero; $scanned += 1) {
+    $next = [AiBatteryNative]::GetWindow($handle, [AiBatteryNative]::GW_HWNDNEXT)
+    # Filter cheapest-first: most windows live on another monitor, so skip the
+    # DWM cloak and class-name lookups until a window is on the HUD monitor.
+    if ((-not (Test-HudWindowHandle $handle)) -and
+        [AiBatteryNative]::IsWindowVisible($handle) -and
+        ([AiBatteryNative]::MonitorFromWindow($handle, [AiBatteryNative]::MONITOR_DEFAULTTONEAREST) -eq $hudMonitor) -and
+        (-not (Test-WindowCloaked $handle)) -and
+        ($script:hudSkipWindowClasses -notcontains (Get-WindowClassName $handle))) {
+      $windowRect = Get-WindowRectObject $handle
+      if ($windowRect -and $windowRect.Width -gt 0 -and $windowRect.Height -gt 0) {
+        if (Test-RectCoversMonitor $windowRect $monitorRect) {
+          return $true
+        }
+        if (Test-RectIsSubstantialOnMonitor $windowRect $monitorRect) {
+          return $false
+        }
+      }
+    }
+    $handle = $next
+  }
 
-  $windowRect = Get-WindowRectObject $foreground
-  $monitorRect = Get-MonitorRectObject $foregroundMonitor
-  return Test-RectCoversMonitor $windowRect $monitorRect
+  return $false
 }
 
 function Set-TaskbarPosition {
@@ -1418,9 +1566,11 @@ function Set-HudHiddenForFullscreen([bool]$Hidden) {
   $script:hudHiddenForFullscreen = $Hidden
   if ($Hidden) {
     if ($hitForm -and -not $hitForm.IsDisposed -and $hitForm.Visible) {
+      [AiBatteryNative]::ShowWindow($hitForm.Handle, [AiBatteryNative]::SW_HIDE) | Out-Null
       $hitForm.Hide()
     }
     if ($form -and -not $form.IsDisposed -and $form.Visible) {
+      [AiBatteryNative]::ShowWindow($form.Handle, [AiBatteryNative]::SW_HIDE) | Out-Null
       $form.Hide()
     }
     return
@@ -1428,21 +1578,95 @@ function Set-HudHiddenForFullscreen([bool]$Hidden) {
 
   if ($form -and -not $form.IsDisposed -and -not $form.Visible) {
     $form.Show()
+    [AiBatteryNative]::ShowWindow($form.Handle, [AiBatteryNative]::SW_SHOWNOACTIVATE) | Out-Null
   }
   Show-HitForm
   Sync-HitFormBounds
 }
 
+$script:fullscreenClearCount = 0
+
 function Update-HudVisibilityForFullscreen {
   if (-not $form -or $form.IsDisposed) { return }
-  if (Test-ForegroundFullscreen) {
+  if (Test-FullscreenOnHudMonitor) {
+    $script:fullscreenClearCount = 0
     Set-HudHiddenForFullscreen $true
     return
   }
+  if ($script:hudHiddenForFullscreen) {
+    $script:fullscreenClearCount += 1
+    if ($script:fullscreenClearCount -lt 2) { return }
+  }
+  $script:fullscreenClearCount = 0
   Set-HudHiddenForFullscreen $false
   Ensure-HudTopMost
 }
 
+$script:fullscreenCheckPending = $false
+
+function Request-FullscreenCheck {
+  if (-not $form -or $form.IsDisposed) { return }
+  if ($form.InvokeRequired) {
+    if ($script:fullscreenCheckPending) { return }
+    $script:fullscreenCheckPending = $true
+    try {
+      $form.BeginInvoke([Action]{
+        $script:fullscreenCheckPending = $false
+        Update-HudVisibilityForFullscreen
+      }) | Out-Null
+    } catch {
+      $script:fullscreenCheckPending = $false
+    }
+    return
+  }
+  Update-HudVisibilityForFullscreen
+}
+
+$script:fullscreenEventCallback = $null
+$script:fullscreenEventHooks = @()
+
+function Start-FullscreenEventHooks {
+  if ($script:fullscreenEventCallback) { return }
+  $script:fullscreenEventCallback = [AiBatteryWinEventDelegate]{
+    param($hook, $eventType, $hwnd, $idObject, $idChild, $eventThread, $eventTime)
+    if ($idObject -ne [AiBatteryNative]::OBJID_WINDOW) { return }
+    Request-FullscreenCheck
+  }
+
+  $events = @(
+    [AiBatteryNative]::EVENT_SYSTEM_FOREGROUND,
+    [AiBatteryNative]::EVENT_OBJECT_SHOW,
+    [AiBatteryNative]::EVENT_OBJECT_HIDE,
+    [AiBatteryNative]::EVENT_OBJECT_REORDER,
+    [AiBatteryNative]::EVENT_OBJECT_LOCATIONCHANGE,
+    [AiBatteryNative]::EVENT_OBJECT_CLOAKED,
+    [AiBatteryNative]::EVENT_OBJECT_UNCLOAKED
+  )
+  $flags = [AiBatteryNative]::WINEVENT_OUTOFCONTEXT -bor [AiBatteryNative]::WINEVENT_SKIPOWNPROCESS
+  foreach ($eventId in $events) {
+    try {
+      $hook = [AiBatteryNative]::SetWinEventHook($eventId, $eventId, [IntPtr]::Zero, $script:fullscreenEventCallback, 0, 0, $flags)
+      if ($hook -ne [IntPtr]::Zero) {
+        $script:fullscreenEventHooks += $hook
+      }
+    } catch {
+      # Polling still covers older or restricted Windows environments.
+    }
+  }
+}
+
+function Stop-FullscreenEventHooks {
+  foreach ($hook in $script:fullscreenEventHooks) {
+    try {
+      [AiBatteryNative]::UnhookWinEvent($hook) | Out-Null
+    } catch {
+      # The hook may already be gone during shutdown.
+    }
+  }
+  $script:fullscreenEventHooks = @()
+  $script:fullscreenEventCallback = $null
+}
+
 function Set-HudBatteryImage($Box, [Nullable[int]]$Percent, [bool]$Running) {
   $oldImage = $Box.Image
   $Box.Image = New-BatteryImage $Percent $Running
@@ -1789,8 +2013,11 @@ function Invoke-HudPump {
 $timer = New-Object System.Windows.Forms.Timer
 $timer.Interval = 1000
 $timer.add_Tick({ Invoke-HudPump })
+# WinEvent hooks wake fullscreen checks immediately on foreground/Z-order/show
+# changes. The UI timer is only a fallback for Windows builds or shells that do
+# not deliver every event we subscribe to.
 $topMostTimer = New-Object System.Windows.Forms.Timer
-$topMostTimer.Interval = 1000
+$topMostTimer.Interval = 150
 $topMostTimer.add_Tick({ Update-HudVisibilityForFullscreen })
 $form.add_FormClosed({
   if ($canMove) {
@@ -1800,6 +2027,7 @@ $form.add_FormClosed({
   $timer.Dispose()
   $topMostTimer.Stop()
   $topMostTimer.Dispose()
+  Stop-FullscreenEventHooks
   Stop-SnapshotFetch
   foreach ($box in @($codexIconLabel, $claudeIconLabel)) {
     if ($box.Image) {
@@ -1841,14 +2069,13 @@ if ($script:initialHudSnapshot) {
 }
 Update-HudFromSnapshot $script:latestSnapshot
 Start-SnapshotFetch
-if ($Mode -eq "statusline" -or $ClickThrough) {
-  $style = [AiBatteryNative]::GetWindowLong($form.Handle, [AiBatteryNative]::GWL_EXSTYLE)
-  $style = $style -bor [AiBatteryNative]::WS_EX_TOOLWINDOW -bor [AiBatteryNative]::WS_EX_NOACTIVATE
-  if ($ClickThrough) {
-    $style = $style -bor [AiBatteryNative]::WS_EX_TRANSPARENT
-  }
-  [AiBatteryNative]::SetWindowLong($form.Handle, [AiBatteryNative]::GWL_EXSTYLE, $style) | Out-Null
+$style = [AiBatteryNative]::GetWindowLong($form.Handle, [AiBatteryNative]::GWL_EXSTYLE)
+$style = $style -bor [AiBatteryNative]::WS_EX_TOOLWINDOW -bor [AiBatteryNative]::WS_EX_NOACTIVATE
+if ($ClickThrough) {
+  $style = $style -bor [AiBatteryNative]::WS_EX_TRANSPARENT
 }
+[AiBatteryNative]::SetWindowLong($form.Handle, [AiBatteryNative]::GWL_EXSTYLE, $style) | Out-Null
 $timer.Start()
+Start-FullscreenEventHooks
 $topMostTimer.Start()
 [System.Windows.Forms.Application]::Run($form)