@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

package/src/server/responses/request-send-budget.ts

@@ -274,6 +274,9 @@ export function createResponsesSendBudget(
     noteAdapterRecoveryWithheld,
     sendBudgetExhausted,
     claimAmbiguousResend,
+    get ambiguousResendSpent(): boolean {
+      return isRequestExecutionBudget(sendBudget) && sendBudget.ambiguousResendSpent === true;
+    },
     get pendingHopPermit(): SingleUseDispatchPermit | undefined {
       return pendingHopPermit;
     },
@@ -313,6 +316,7 @@ function adapterDispatchBudgetView(
     get lastTargetKey(): string | undefined { return budget.lastTargetKey; },
     remainingBaseSends: (cap: number): number => budget.remainingBaseSends(cap),
     claimAmbiguousResend: (limit: number): boolean => budget.claimAmbiguousResend?.(limit) === true,
+    get ambiguousResendSpent(): boolean { return budget.ambiguousResendSpent === true; },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       // A dispatch whose upstream state is unknown is refused on its own merits. A hop that
       // already paid does not make an unsafe replay safe, so that check stays with the budget.

package/src/server/responses/run-turn-execution.ts

@@ -18,9 +18,9 @@ import type { AdapterEventQueue } from "../../adapters/run-turn-queue";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { providerFetch } from "./fetch-helpers";
 import { normalizeLogConversationId } from "../request-log-conversation";
-import type { AdapterEvent, OcxProviderContinuationState } from "../../types";
+import { normalizeDeclaredToolName, type AdapterEvent, type OcxProviderContinuationState } from "../../types";
 import { adapterFailureFromMessage, SEND_BUDGET_EXHAUSTED_CODE } from "../../lib/errors";
-import { SendBudgetExhaustedError } from "../../lib/upstream-retry";
+import { SendBudgetExhaustedError, markResponseNonReplayable } from "../../lib/upstream-retry";
 import {
   GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST,
   hasEligibleGenericOAuthFailoverTarget,
@@ -39,6 +39,7 @@ import {
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
 import { awaitThoughtSignatureDurability } from "../../responses/thought-signature-replay";
+import { undeclaredToolCallMessage } from "../responses-undeclared-tool-guard";
 
 /** One responsibility of the Responses request pipeline; state owners are explicit. */
 export async function executeResponsesRunTurn(
@@ -366,6 +367,20 @@ export async function executeResponsesRunTurn(
     };
 
     const { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames } = toolBridgeMaps;
+    const enforceDeclaredToolNames = inboundWire !== "chat" && inboundWire !== "anthropic";
+    const classifyUndeclaredFirstTool = (
+      event: AdapterEvent,
+    ): Extract<AdapterEvent, { type: "error" }> | undefined => {
+      if (!enforceDeclaredToolNames || event.type !== "tool_call_start") return undefined;
+      const effectiveName = normalizeDeclaredToolName(event.name, declaredToolNames);
+      if (declaredToolNames.has(effectiveName)) return undefined;
+      return {
+        type: "error",
+        status: 502,
+        errorType: "upstream_error",
+        message: undeclaredToolCallMessage(effectiveName),
+      };
+    };
     if (parsed.stream) {
       void runTurn();
       let eventSource: AsyncIterable<AdapterEvent> = queue.stream();
@@ -375,12 +390,16 @@ export async function executeResponsesRunTurn(
         eventSource = await preflightRunTurnFailover(eventSource);
       }
       if (options.comboAttempt) {
-        const preflight = await preflightAdapterEvents(eventSource);
+        const preflight = await preflightAdapterEvents(eventSource, classifyUndeclaredFirstTool);
         if (preflight.error || preflight.empty) {
           runTurnAbort.abort();
           queue.close();
           const message = preflight.error?.message ?? "Adapter ended before producing a response";
-          return formatErrorResponse(502, "upstream_error", redactSecretString(message));
+          const failure = formatErrorResponse(502, "upstream_error", redactSecretString(message));
+          // A replay-unsafe heartbeat means the adapter already ran a local side effect, so the
+          // combo must not send this turn to another target: the failure stays with this child.
+          if (preflight.replayUnsafe) markResponseNonReplayable(failure);
+          return failure;
         }
         eventSource = preflight.stream;
       }
@@ -412,7 +431,7 @@ export async function executeResponsesRunTurn(
           stallTimeoutSec: config.stallTimeoutSec,
           hideThinkingSummary: parsed.options.hideThinkingSummary,
           declaredToolNames,
-          enforceDeclaredToolNames: inboundWire !== "chat" && inboundWire !== "anthropic",
+          enforceDeclaredToolNames,
           toolParameterSchemas,
           ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
           ...(routedCompaction ? { compaction: true } : {}),
@@ -468,12 +487,24 @@ export async function executeResponsesRunTurn(
       events = runTurnEvents;
     }
     if (options.comboAttempt) {
-      const firstMeaningful = events.find(event => event.type !== "heartbeat");
-      if (!firstMeaningful || firstMeaningful.type === "error") {
-        const message = firstMeaningful?.type === "error"
+      const firstMeaningfulIndex = events.findIndex(event => event.type !== "heartbeat");
+      const firstMeaningful = firstMeaningfulIndex === -1 ? undefined : events[firstMeaningfulIndex];
+      // Same boundary as the streaming preflight: a replay-unsafe heartbeat means the adapter
+      // already ran a local side effect, so an undeclared tool call after it keeps the bridge's
+      // fail-closed refusal instead of becoming a hop that sends the turn to another target.
+      const replayUnsafe = events
+        .slice(0, firstMeaningfulIndex === -1 ? events.length : firstMeaningfulIndex)
+        .some(event => event.type === "heartbeat" && event.replayUnsafe === true);
+      const classifiedError = firstMeaningful && !replayUnsafe
+        ? classifyUndeclaredFirstTool(firstMeaningful)
+        : undefined;
+      if (!firstMeaningful || firstMeaningful.type === "error" || classifiedError) {
+        const message = classifiedError?.message ?? (firstMeaningful?.type === "error"
           ? firstMeaningful.message
-          : "Adapter ended before producing a response";
-        return formatErrorResponse(502, "upstream_error", redactSecretString(message));
+          : "Adapter ended before producing a response");
+        const failure = formatErrorResponse(502, "upstream_error", redactSecretString(message));
+        if (replayUnsafe) markResponseNonReplayable(failure);
+        return failure;
       }
     }
     let providerState: OcxProviderContinuationState | undefined;
@@ -483,7 +514,7 @@ export async function executeResponsesRunTurn(
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       toolNsMap,
       declaredToolNames,
-      enforceDeclaredToolNames: inboundWire !== "chat" && inboundWire !== "anthropic",
+      enforceDeclaredToolNames,
       toolParameterSchemas,
       freeformToolNames,
       toolSearchToolNames,

package/src/server/responses/ws-upstream.ts

@@ -85,10 +85,11 @@ export function shouldUseCodexWsUpstream(
   url: string,
   init?: RequestInit,
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
-  upstreamWebsocketConfigured = false,
+  upstreamWebsocketConfigured?: boolean,
 ): boolean {
   if (!bunSupportsBoundedCodexWsRelay(runtime)) return false;
   if (socks5ProxyFromEnv()) return false;
+  if (url === CODEX_RESPONSES_HTTP_URL && upstreamWebsocketConfigured === false) return false;
   // Bun's client WebSocket API delivers only fully assembled messages and has
   // no enforceable inbound payload limit. Keep arbitrary provider endpoints on
   // bounded HTTP/SSE until the client can reject fragmented text and binary

package/src/server/system-env-shell.ts

@@ -120,7 +120,6 @@ export function writeShellEnvFile(
   const maxCtx = config.claudeCode?.maxContextTokens;
   if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
     lines.push(conditional("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx))));
-    lines.push(conditional("DISABLE_COMPACT", "1"));
   }
   // Auto-context (devlog 260712 020): same contract as `ocx claude` / launchctl.
   const autoShell = auto ?? resolveAutoContext(config.claudeCode);

package/src/server/system-env.ts

@@ -282,9 +282,12 @@ export async function injectSystemEnv(
     }
     // Lever keys (devlog 136 B6): user-wins — skip any key the user already set in the
     // launchd domain, and track ONLY the keys we actually injected so revert cannot
-    // delete a pre-existing user value (audit 139 #3).
+    // delete a pre-existing user value (audit 139 #3). A key we already track is ours
+    // (revertSystemEnv unsets it regardless of value), so it is refreshed, not skipped.
+    const producedLevers = new Set<string>();
     const injectLever = (name: string, value: string) => {
-      if (launchctlGetenv(name) !== undefined) return;
+      producedLevers.add(name);
+      if (launchctlGetenv(name) !== undefined && !injectedKeys.includes(name)) return;
       inject(name, value);
     };
     // Model slots (default + tier defaults + legacy small-fast) with [1m] auto-marking
@@ -293,7 +296,9 @@ export async function injectSystemEnv(
     // Auto-context: a user-owned launchd value drives the marking predicate so the
     // marker and threshold never separate (audit 021 #2); injectLever's user-wins
     // check below keeps that value untouched.
-    const userAutoCompact = launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
+    const userAutoCompact = injectedKeys.includes("CLAUDE_CODE_AUTO_COMPACT_WINDOW")
+      ? undefined
+      : launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
     const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
     const { modelEnv, windows } = await computeEffectiveModelEnv(config, auto);
     for (const [name, value] of Object.entries(modelEnv)) {
@@ -303,7 +308,6 @@ export async function injectSystemEnv(
     const maxCtx = config.claudeCode?.maxContextTokens;
     if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
       injectLever("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
-      injectLever("DISABLE_COMPACT", "1");
     }
     // Auto-context (devlog 260712 020): user-wins lever, inert when maxContextTokens set.
     if (auto.enabled) injectLever("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
@@ -315,6 +319,23 @@ export async function injectSystemEnv(
     // instead of only terminal sessions. injectLever keeps a user-owned launchd value.
     const toolSearch = claudeToolSearchEnv(config.claudeCode?.toolSearch);
     if (toolSearch !== undefined) injectLever("ENABLE_TOOL_SEARCH", toolSearch);
+    // A lever injected on an earlier run that this config no longer produces (a cleared
+    // smallFastModel, a removed tier slot, or the DISABLE_COMPACT older releases paired with
+    // maxContextTokens) would otherwise stay in launchd until the proxy stops, and a
+    // same-port restart keeps the tracking record. Only tracked keys are touched, so a user-owned value is never removed.
+    for (const name of [...injectedKeys]) {
+      if ((SYSTEM_ENV_NAMES as readonly string[]).includes(name) || producedLevers.has(name)) continue;
+      // Older releases only ever injected DISABLE_COMPACT=1. Any other value was set by hand,
+      // so ownership is released without deleting it.
+      if (name === "DISABLE_COMPACT" && launchctlGetenv(name) !== "1") {
+        injectedKeys.splice(injectedKeys.indexOf(name), 1);
+        writeTracking(port, injectedKeys, tracked);
+        continue;
+      }
+      unsetLaunchctlEnv(name);
+      injectedKeys.splice(injectedKeys.indexOf(name), 1);
+      writeTracking(port, injectedKeys, tracked);
+    }
 
     // Shell-hook env file: works for new shells in already-running Terminal.app.
     writeShellEnvFile(port, config, modelEnv, auto, deps);

package/src/service/cli.ts

@@ -1,9 +1,12 @@
-import { existsSync, unlinkSync } from "node:fs";
+import { existsSync, lstatSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { restoreNativeCodexAsync } from "../codex/inject";
 import { describeRetainedCodexProviderTable } from "../codex/inject/restore";
 import { stripGrokConfig } from "../grok/inject";
-import { serviceApiTokenFilePath } from "../lib/service-secrets";
+import { withConfigMutationLockSync } from "../config/mutation-lock";
+import { withClientLifecycleSync, type ClientLifecycleLockDeps } from "../client/lifecycle-lock";
+import { pendingClientConnectMayOwnToken, readClientConnectionState } from "../client/state";
+import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { statusWinswRaw, type WinswStatus } from "../lib/winsw";
 import { withWindowsServiceMutationLock } from "../lib/windows-service-mutation-lock";
 import { maybeShowStarPrompt } from "../cli/star-prompt";
@@ -182,6 +185,32 @@ export function parseServiceArgs(args: string[]): ParsedServiceArgs {
   return { sub: normalizeServiceSubcommand(sub), backend, invalid };
 }
 
+/** Remove the service credential only when no client connection can own it. */
+export function removeServiceTokenAfterUninstall(
+  lockDeps: ClientLifecycleLockDeps = {},
+): "removed" | "absent" | "retained" | "unverified" {
+  try {
+    return withClientLifecycleSync(() => withConfigMutationLockSync(() => {
+      const path = serviceApiTokenFilePath();
+      try { lstatSync(path); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+        throw error;
+      }
+      if (readClientConnectionState().kind !== "disconnected") return "retained";
+      const token = readServiceApiTokenState();
+      if (token.kind !== "present") return token.kind === "absent" ? "absent" : "unverified";
+      if (pendingClientConnectMayOwnToken(token.fingerprint)) return "retained";
+      unlinkSync(path);
+      return "removed";
+    }), lockDeps);
+  } catch {
+    // Lock, state-read and unlink failures all leave cleanup unverified, not successful.
+    return "unverified";
+  }
+}
+
+/** Execute a service verb while preserving client-owned credentials during uninstall. */
 export async function serviceCommand(...args: (string | undefined)[]): Promise<void> {
   const filteredArgs = args.filter((a): a is string => Boolean(a));
   const execute = async (): Promise<void> => {
@@ -424,7 +453,9 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         }
       }
       removeServiceInstallState();
-      try { if (existsSync(serviceApiTokenFilePath())) unlinkSync(serviceApiTokenFilePath()); } catch { /* best-effort */ }
+      const tokenCleanup = removeServiceTokenAfterUninstall();
+      if (tokenCleanup === "retained") console.warn("⚠️  Service token kept because client state may own it.");
+      else if (tokenCleanup === "unverified") console.warn("⚠️  Service token cleanup could not be verified; inspect client state before deleting it.");
       console.log("✅ service uninstalled.");
       break;
     default:

package/src/tray/windows-tray.ps1

@@ -41,6 +41,9 @@ function Load-TrayIcon([string]$Name, [System.Drawing.Icon]$Fallback) {
 $onlineIcon = Load-TrayIcon "opencodex-tray-online.ico" ([System.Drawing.SystemIcons]::Information)
 $warningIcon = Load-TrayIcon "opencodex-tray-warning.ico" ([System.Drawing.SystemIcons]::Warning)
 $offlineIcon = Load-TrayIcon "opencodex-tray-offline.ico" ([System.Drawing.SystemIcons]::Error)
+$onlineUpdateIcon = Load-TrayIcon "opencodex-tray-online-update.ico" $onlineIcon
+$warningUpdateIcon = Load-TrayIcon "opencodex-tray-warning-update.ico" $warningIcon
+$offlineUpdateIcon = Load-TrayIcon "opencodex-tray-offline-update.ico" $offlineIcon
 
 function Get-StableHash([string]$Value) {
   $sha = [System.Security.Cryptography.SHA256]::Create()
@@ -86,6 +89,20 @@ function ConvertTo-NativeArgument([string]$Value) {
   return '"' + $Value + '"'
 }
 
+# A fresh profile may not have created the default %USERPROFILE%.codex yet, and the
+# CLI rejects a CODEX_HOME that does not exist. Only that default home is dropped so
+# children resolve it themselves; any other home is passed through unchanged.
+function Set-OcxChildEnvironment([System.Diagnostics.ProcessStartInfo]$StartInfo) {
+  $defaultHome = Normalize-HomePath (Join-Path $env:USERPROFILE ".codex")
+  $isDefaultHome = [string]::Equals($CodexHome, $defaultHome, [System.StringComparison]::OrdinalIgnoreCase)
+  if ($isDefaultHome -and -not [System.IO.Directory]::Exists($CodexHome)) {
+    $StartInfo.EnvironmentVariables.Remove("CODEX_HOME")
+  } else {
+    $StartInfo.EnvironmentVariables["CODEX_HOME"] = $CodexHome
+  }
+  $StartInfo.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+}
+
 function Start-OcxCommand([string[]]$CommandArgs, [switch]$TrackExit) {
   try {
     $allArgs = @($CliPath) + $CommandArgs
@@ -95,8 +112,7 @@ function Start-OcxCommand([string[]]$CommandArgs, [switch]$TrackExit) {
     $psi.UseShellExecute = $false
     $psi.CreateNoWindow = $true
     $psi.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
-    $psi.EnvironmentVariables["CODEX_HOME"] = $CodexHome
-    $psi.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+    Set-OcxChildEnvironment $psi
     if ($BunRuntimeSource) {
       $psi.EnvironmentVariables["OCX_BUN_RUNTIME_SOURCE"] = $BunRuntimeSource
       # Paired with the source so a later relaunch can tell the marker still describes
@@ -155,8 +171,7 @@ function Start-StartupHealthProbe {
     $psi.RedirectStandardError = $true
     $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
     $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
-    $psi.EnvironmentVariables["CODEX_HOME"] = $CodexHome
-    $psi.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+    Set-OcxChildEnvironment $psi
     if ($BunRuntimeSource) {
       $psi.EnvironmentVariables["OCX_BUN_RUNTIME_SOURCE"] = $BunRuntimeSource
       $psi.EnvironmentVariables["OCX_BUN_RUNTIME_PATH"] = $BunPath
@@ -198,6 +213,147 @@ function Complete-StartupHealthProbe {
   }
 }
 
+function Initialize-UpdateBadgeReader {
+  if (([System.Management.Automation.PSTypeName]"TrayUpdateBadgeReader").Type) { return }
+  Add-Type -TypeDefinition @'
+using System;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+public static class TrayUpdateBadgeReader {
+  public static async Task<string> ReadAsync(Stream input, int maxBytes) {
+    byte[] chunk = new byte[4096];
+    using (var content = new MemoryStream()) {
+      while (true) {
+        int count = await input.ReadAsync(chunk, 0, chunk.Length).ConfigureAwait(false);
+        if (count == 0) break;
+        if (content.Length + count > maxBytes) throw new InvalidDataException("badge pipe byte cap exceeded");
+        content.Write(chunk, 0, count);
+      }
+      return new UTF8Encoding(false, true).GetString(content.ToArray());
+    }
+  }
+}
+'@
+}
+
+function Parse-UpdateBadgeText([string]$Text) {
+  $lines = @($Text -split "\r?\n" | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+  if ($lines.Count -ne 1) { return $null }
+  try {
+    $badge = $lines[0] | ConvertFrom-Json
+    if (($badge.updateAvailable -isnot [bool]) -or ($badge.unknown -isnot [bool]) -or
+        ($badge.canUpdate -isnot [bool])) { return $null }
+    return [bool]($badge.updateAvailable -and -not $badge.unknown -and $badge.canUpdate)
+  } catch { return $null }
+}
+
+function Complete-UpdateBadgeProbe {
+  $process = $script:updateBadgeProcess
+  $script:updateBadgeProcess = $null
+  $script:updateBadgeOutputTask = $null
+  $script:updateBadgeErrorTask = $null
+  $script:updateBadgeTerminating = $false
+  if ($null -ne $process) {
+    try {
+      $process.StandardOutput.Dispose()
+      $process.StandardError.Dispose()
+      $process.Dispose()
+    } catch { Write-ActionLog "update badge probe dispose failed: $($_.Exception.GetType().Name)" }
+  }
+}
+
+function Stop-UpdateBadgeProbe([switch]$Shutdown) {
+  if ($null -eq $script:updateBadgeProcess) { return }
+  $script:updateBadgeTerminating = $true
+  try {
+    if (-not $script:updateBadgeProcess.HasExited) { $script:updateBadgeProcess.Kill() }
+  } catch { Write-ActionLog "update badge probe termination failed: $($_.Exception.GetType().Name)" }
+  if ($Shutdown) {
+    # Only shutdown may wait, and it is bounded; the UI tick never calls this branch.
+    try { [void]$script:updateBadgeProcess.WaitForExit(500) } catch { $null = $_ }
+    Complete-UpdateBadgeProbe
+  }
+}
+
+function Start-UpdateBadgeProbe {
+  try {
+    Initialize-UpdateBadgeReader
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = $BunPath
+    $psi.Arguments = ((@($CliPath, "__update-badge") | ForEach-Object { ConvertTo-NativeArgument $_ }) -join " ")
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+    $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+    Set-OcxChildEnvironment $psi
+    if ($BunRuntimeSource) {
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_SOURCE"] = $BunRuntimeSource
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_PATH"] = $BunPath
+    }
+    $script:updateBadgeProcess = [System.Diagnostics.Process]::Start($psi)
+    if ($null -eq $script:updateBadgeProcess) { throw "Process did not start" }
+    $script:updateBadgeOutputTask = [TrayUpdateBadgeReader]::ReadAsync($script:updateBadgeProcess.StandardOutput.BaseStream, $script:updateBadgeMaxBytesPerStream)
+    $script:updateBadgeErrorTask = [TrayUpdateBadgeReader]::ReadAsync($script:updateBadgeProcess.StandardError.BaseStream, $script:updateBadgeMaxBytesPerStream)
+    $script:updateBadgeStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  } catch {
+    Write-ActionLog "update badge probe launch failed: $($_.Exception.GetType().Name)"
+    if ($null -ne $script:updateBadgeProcess) { Stop-UpdateBadgeProbe }
+  }
+}
+
+function Maintain-UpdateBadgeProbe([long]$Now) {
+  if ($null -ne $script:updateBadgeProcess) {
+    $terminatingAtStart = $script:updateBadgeTerminating
+    $expired = ($Now - $script:updateBadgeStarted) -gt $script:updateBadgeTimeoutMs
+    $exited = $false
+    try { $exited = $script:updateBadgeProcess.HasExited } catch { Stop-UpdateBadgeProbe }
+    $drained = ($null -eq $script:updateBadgeOutputTask -or $script:updateBadgeOutputTask.IsCompleted) -and
+      ($null -eq $script:updateBadgeErrorTask -or $script:updateBadgeErrorTask.IsCompleted)
+    $failedRead = ($null -ne $script:updateBadgeOutputTask -and
+      ($script:updateBadgeOutputTask.IsFaulted -or $script:updateBadgeOutputTask.IsCanceled)) -or
+      ($null -ne $script:updateBadgeErrorTask -and
+      ($script:updateBadgeErrorTask.IsFaulted -or $script:updateBadgeErrorTask.IsCanceled))
+    if ($failedRead -and -not $script:updateBadgeTerminating) {
+      Write-ActionLog "update badge probe pipe read failed or exceeded byte cap"
+      Stop-UpdateBadgeProbe
+    }
+    if ($script:updateBadgeTerminating) {
+      # Reap on a later tick after both bounded readers settle; no replacement starts meanwhile.
+      if ($terminatingAtStart -and -not $exited) { Stop-UpdateBadgeProbe }
+      if ($terminatingAtStart -and $exited -and $drained) { Complete-UpdateBadgeProbe }
+    } elseif ($exited -and $drained -and $null -ne $script:updateBadgeOutputTask -and
+        $null -ne $script:updateBadgeErrorTask) {
+      $answer = $null
+      try {
+        if ($script:updateBadgeProcess.ExitCode -eq 0) {
+          $answer = Parse-UpdateBadgeText $script:updateBadgeOutputTask.Result
+        }
+      } catch { Write-ActionLog "update badge probe read failed: $($_.Exception.GetType().Name)" }
+      if ($null -ne $answer) {
+        $script:updateAvailable = [bool]$answer
+        $script:updateBadgeObservedAt = $Now
+      }
+      Complete-UpdateBadgeProbe
+    } elseif ($expired) {
+      Write-ActionLog "update badge probe timed out"
+      Stop-UpdateBadgeProbe
+    }
+  }
+  if ($script:updateBadgeObservedAt -eq 0 -or
+      ($Now - $script:updateBadgeObservedAt) -gt $script:updateBadgeExpiryMs) {
+    $script:updateAvailable = $false
+  }
+  if ($null -eq $script:updateBadgeProcess -and -not $script:updateBadgeTerminating -and
+      ($script:updateBadgeAttemptAt -eq 0 -or ($Now - $script:updateBadgeAttemptAt) -ge $script:updateBadgeRefreshMs)) {
+    $script:updateBadgeAttemptAt = $Now
+    Start-UpdateBadgeProbe
+  }
+}
+
 function Read-ListenTarget {
   foreach ($path in @((Join-Path $OpenCodexHome "runtime-port.json"), (Join-Path $OpenCodexHome "config.json"))) {
     try {
@@ -241,6 +397,9 @@ $statusItem.Enabled = $false
 $safetyItem = New-Object System.Windows.Forms.ToolStripMenuItem
 $safetyItem.Enabled = $false
 $openItem = $menu.Items.Add("Open Dashboard")
+$updateItem = $menu.Items.Add("Update available")
+$updateItem.Visible = $false
+$updateItem.Enabled = $false
 $startItem = $menu.Items.Add("Start Proxy")
 $stopItem = $menu.Items.Add("Stop Proxy and Restore Native Routing")
 $restartItem = $menu.Items.Add("Restart Proxy")
@@ -263,6 +422,18 @@ $script:startupProbeOutputTask = $null
 $script:startupProbeErrorTask = $null
 $script:startupProbeStarted = 0L
 $script:startupProbeTimeoutMs = 30000L
+$script:updateAvailable = $false
+$script:updateBadgeObservedAt = 0L
+$script:updateBadgeAttemptAt = 0L
+$script:updateBadgeRefreshMs = 60000L
+$script:updateBadgeExpiryMs = 180000L
+$script:updateBadgeTimeoutMs = 12000L
+$script:updateBadgeMaxBytesPerStream = 16384
+$script:updateBadgeProcess = $null
+$script:updateBadgeOutputTask = $null
+$script:updateBadgeErrorTask = $null
+$script:updateBadgeStarted = 0L
+$script:updateBadgeTerminating = $false
 $script:pendingAction = $null
 $script:pendingStarted = 0L
 $script:pendingDeadline = 0L
@@ -322,6 +493,7 @@ function Update-TrayState {
   $cameOnline = $script:online -and -not $script:wasOnline
   $script:wasOnline = $script:online
   $now = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  Maintain-UpdateBadgeProbe $now
   if ($null -ne $script:startupProbeProcess) {
     $probeExited = $false
     try {
@@ -377,20 +549,26 @@ function Update-TrayState {
     if ($null -ne $startup) {
       $label = if ($startup.status -eq "at-risk") { "At risk" } elseif ($startup.status -eq "protected") { "Protected" } else { "Native routing" }
       $safetyItem.Text = "Restart safety: $label"
-      $notify.Icon = if ($startup.status -eq "at-risk") { $warningIcon } else { $onlineIcon }
+      $notify.Icon = if ($startup.status -eq "at-risk") {
+        if ($script:updateAvailable) { $warningUpdateIcon } else { $warningIcon }
+      } else {
+        if ($script:updateAvailable) { $onlineUpdateIcon } else { $onlineIcon }
+      }
     } else {
       $safetyItem.Text = "Restart safety: unavailable"
-      $notify.Icon = $warningIcon
+      $notify.Icon = if ($script:updateAvailable) { $warningUpdateIcon } else { $warningIcon }
     }
   } else {
     $statusItem.Text = "Proxy: Offline"
     $safetyItem.Text = "Restart safety: start the proxy to inspect"
     $notify.Text = "opencodex: Offline"
-    $notify.Icon = $offlineIcon
+    $notify.Icon = if ($script:updateAvailable) { $offlineUpdateIcon } else { $offlineIcon }
     $startItem.Enabled = $true
     $stopItem.Enabled = $false
     $restartItem.Enabled = $false
   }
+  $updateItem.Visible = $script:updateAvailable
+  $updateItem.Enabled = $script:updateAvailable
   if ($null -ne $script:pendingAction) {
     $startItem.Enabled = $false
     $stopItem.Enabled = $false
@@ -426,6 +604,7 @@ function Update-TrayState {
 }
 
 $openItem.add_Click({ Start-OcxCommand @("gui") })
+$updateItem.add_Click({ Start-OcxCommand @("gui") })
 $startItem.add_Click({
   if (-not (Set-PendingAction "Start Proxy" 75)) { return }
   $statusItem.Text = "Proxy: Starting..."
@@ -489,6 +668,7 @@ $notify.Visible = $true
 $notify.Text = "opencodex: Checking..."
 
 try {
+  Initialize-UpdateBadgeReader
   Update-TrayState
   $timer.Start()
   [System.Windows.Forms.Application]::Run()
@@ -512,6 +692,7 @@ try {
     }
     Complete-StartupHealthProbe
   }
+  Stop-UpdateBadgeProbe -Shutdown
   $notify.Dispose()
   foreach ($icon in $script:ownedIcons) { $icon.Dispose() }
   $menu.Dispose()

package/src/tray/windows.ts

@@ -19,6 +19,9 @@ const TRAY_ICON_FILES = [
   "opencodex-tray-online.ico",
   "opencodex-tray-warning.ico",
   "opencodex-tray-offline.ico",
+  "opencodex-tray-online-update.ico",
+  "opencodex-tray-warning-update.ico",
+  "opencodex-tray-offline-update.ico",
 ] as const;
 
 export interface WindowsTrayEntry {
@@ -68,6 +71,25 @@ function installedTrayIconPaths(): string[] {
   return TRAY_ICON_FILES.map(name => join(getConfigDir(), name));
 }
 
+/**
+ * Files an installed tray must still have for its registration to count as ours.
+ *
+ * The dotted update icons arrived after the tray shipped, so an install made by an older
+ * release has only the three base icons. Requiring all six here classified that install as
+ * stale, and the updater then stopped the tray without reinstalling it (trayWasInstalled was
+ * false). The dotted icons stay in the install, rollback and uninstall lists; the tray script
+ * falls back to the base icon when one is missing, and the next `tray install` adds them.
+ */
+export function windowsTrayRequiredFilesPresent(
+  state: Pick<WindowsTrayEntry, "bun" | "cli" | "script"> & { launcherPath?: string },
+  iconPaths: readonly string[],
+  exists: (path: string) => boolean = existsSync,
+): boolean {
+  const baseIcons = iconPaths.filter(path => !/-update\.ico$/i.test(path));
+  return [state.bun, state.cli, state.script, ...(state.launcherPath ? [state.launcherPath] : []), ...baseIcons]
+    .every(path => exists(path));
+}
+
 export function windowsTrayStatePathsOwned(
   state: Pick<WindowsTrayEntry, "script" | "opencodexHome"> & { launcherPath?: string },
   configDir = getConfigDir(),
@@ -469,8 +491,7 @@ function trayStatusFrom(registered: string | null): WindowsTrayStatus {
   const running = heartbeatProcessAlive(heartbeat);
   const registrationOwned = state !== null
     && registered === state.runCommand
-    && [state.bun, state.cli, state.script, ...(state.launcherPath ? [state.launcherPath] : []), ...installedTrayIconPaths()]
-      .every(path => existsSync(path));
+    && windowsTrayRequiredFilesPresent(state, installedTrayIconPaths());
   const stale = windowsTrayRegistrationIsStale({
     registered: registered !== null,
     registrationOwned,