@iislee/opencodex 2.11.0

package/src/storage/storage-mutation-coordinator.ts

@@ -0,0 +1,139 @@
+/**
+ * Single-flight gate for CODEX_HOME storage mutations (cleanup, restore, policy).
+ *
+ * Manual cleanup, trash restore, and (Phase 3) policy-driven cleanup share one
+ * in-flight slot per resolved CODEX_HOME. A second caller receives
+ * `storage_mutation_busy` immediately — no per-operation queues.
+ */
+import { resolve } from "node:path";
+import { resolveCodexHomeDir } from "../codex/home";
+import { createAdmissionGate, type AdmissionLease, type AdmissionMetrics } from "../lib/admission";
+
+export type StorageMutationKind = "cleanup" | "restore" | "policy";
+
+export type StorageMutationBusyError = "storage_mutation_busy";
+
+export interface StorageMutationCoordinatorTestHooks {
+  /** Block after acquiring the slot, before mutation work (race tests). */
+  blockMs?: number;
+}
+
+interface ActiveSlot {
+  kind: StorageMutationKind;
+  startedAt: number;
+  lease: AdmissionLease;
+}
+
+export const MAX_ACTIVE_STORAGE_HOME_SLOTS = 32;
+const slots = new Map<string, ActiveSlot>();
+const slotGate = createAdmissionGate("storage_home_slots", MAX_ACTIVE_STORAGE_HOME_SLOTS);
+let releaseMisses = 0;
+let testHooks: StorageMutationCoordinatorTestHooks | null = null;
+
+function slotKey(codexHome?: string): string {
+  return resolve(codexHome ?? resolveCodexHomeDir());
+}
+
+export function setStorageMutationCoordinatorTestHooks(
+  hooks: StorageMutationCoordinatorTestHooks | null,
+): void {
+  testHooks = hooks;
+}
+
+export function resetStorageMutationCoordinatorForTests(): void {
+  testHooks = null;
+  for (const slot of slots.values()) slot.lease.release();
+  slots.clear();
+}
+
+export function storageMutationAdmissionMetrics(): AdmissionMetrics {
+  const metrics = slotGate.metrics();
+  return { ...metrics, releaseMisses: metrics.releaseMisses + releaseMisses };
+}
+
+export function getActiveStorageMutation(
+  codexHome?: string,
+): { kind: StorageMutationKind; startedAt: number } | null {
+  const active = slots.get(slotKey(codexHome));
+  return active ? { kind: active.kind, startedAt: active.startedAt } : null;
+}
+
+export function tryBeginStorageMutation(
+  kind: StorageMutationKind,
+  codexHome?: string,
+): { acquired: true; lease: AdmissionLease } | { acquired: false; error: StorageMutationBusyError } {
+  const key = slotKey(codexHome);
+  if (slots.has(key)) {
+    return { acquired: false, error: "storage_mutation_busy" };
+  }
+  const lease = slotGate.tryAcquire();
+  if (!lease) return { acquired: false, error: "storage_mutation_busy" };
+  let active = true;
+  const ownerLease: AdmissionLease = {
+    release() {
+      if (!active) return;
+      active = false;
+      const owner = slots.get(key);
+      if (owner?.lease === ownerLease) slots.delete(key);
+      lease.release();
+    },
+  };
+  slots.set(key, { kind, startedAt: Date.now(), lease: ownerLease });
+  return { acquired: true, lease: ownerLease };
+}
+
+export function endStorageMutation(codexHome?: string): void {
+  const key = slotKey(codexHome);
+  const slot = slots.get(key);
+  if (!slot) {
+    releaseMisses += 1;
+    return;
+  }
+  slots.delete(key);
+  slot.lease.release();
+}
+
+async function applyCoordinatorBlock(): Promise<void> {
+  const blockMs = testHooks?.blockMs;
+  if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
+    await Bun.sleep(Math.floor(blockMs));
+  }
+}
+
+/**
+ * Phase 3 policy worker integration — wrap policy-driven cleanup FS/DB work.
+ * Returns `{ ok: false, error: 'storage_mutation_busy' }` when another mutation
+ * holds the CODEX_HOME slot.
+ */
+export async function runPolicyStorageMutation<T>(
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation("policy", codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    gate.lease.release();
+  }
+}
+
+export async function withStorageMutationSlot<T>(
+  kind: StorageMutationKind,
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation(kind, codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    gate.lease.release();
+  }
+}

package/src/storage/worker-lifecycle.ts

@@ -0,0 +1,215 @@
+/**
+ * Deterministic teardown for the storage Bun Workers.
+ *
+ * `Worker.terminate()` returns void and does NOT wait for the thread to be
+ * reclaimed. Callers that fire-and-forget leave a window where
+ * `bun test --isolate` reclaims the file realm while a Windows worker thread
+ * is still exiting — Bun then panics with
+ * `workers_spawned(N) workers_terminated(N-1)` / Internal assertion failure.
+ *
+ * Invariant: every registered worker has a `close` listener attached at spawn
+ * time (so we cannot miss `self.close()` / early exit), stays in `liveWorkers`
+ * until that close settles, and `drainStorageWorkers()` joins every in-flight
+ * terminate. Spawns are serialized through `withStorageWorkerSpawnGate` so the
+ * next Worker cannot be created until prior threads have exited. On Windows and
+ * macOS, a post-close settle covers the OS join gap Bun does not expose
+ * (Windows unbalanced join panic; macOS Silicon balanced-count segfault under
+ * `bun test --isolate`).
+ */
+
+import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
+
+type TrackedWorker = {
+  worker: Worker;
+  closed: Promise<void>;
+  resolveClosed: () => void;
+  terminatePromise?: Promise<void>;
+  reservation?: AdmissionReservation<Worker>;
+};
+
+export const MAX_RESERVED_STORAGE_WORKER_SPAWNS = 16;
+export class StorageWorkerAdmissionBusyError extends Error {
+  readonly code = "storage_mutation_busy";
+
+  constructor() {
+    super("storage worker spawn queue is busy");
+    this.name = "StorageWorkerAdmissionBusyError";
+  }
+}
+
+const liveWorkers = new Map<Worker, TrackedWorker>();
+const workerGate = createAdmissionGate("storage_worker_reservations", MAX_RESERVED_STORAGE_WORKER_SPAWNS);
+
+/** Serialize spawns so a new Worker never overlaps a still-exiting predecessor. */
+let spawnGate: Promise<void> = Promise.resolve();
+
+/**
+ * Bumped by teardown so a spawn still queued on `spawnGate` (not yet in
+ * `liveWorkers`) cannot create a Worker after reset/shutdown reported idle.
+ */
+let spawnCancelEpoch = 0;
+
+/**
+ * OS-join gap after the `close` event on platforms where Bun's Worker reclaim
+ * races the isolate/file boundary (not a CI job-timeout bump).
+ * Windows GHA at 250ms and 750ms still left `workers_spawned(N)
+ * workers_terminated(N-1)` panics under isolate (seen mid
+ * `storage-mutation-race` with 11/10). 1500ms covers deferred reclaim under
+ * stacked policy/restore workers. Darwin uses 250ms.
+ */
+const WORKER_OS_JOIN_MS = process.platform === "win32" ? 1_500 : 250;
+
+function needsWorkerOsJoinSettle(): boolean {
+  return process.platform === "win32" || process.platform === "darwin";
+}
+
+/** Invalidate spawn callbacks still waiting on the gate (reset / server drain). */
+export function cancelQueuedStorageWorkerSpawns(): void {
+  spawnCancelEpoch += 1;
+}
+
+/** Track a freshly spawned worker so teardown can wait for it later. */
+export function registerStorageWorker(worker: Worker): void {
+  if (liveWorkers.has(worker)) return;
+
+  let resolveClosed!: () => void;
+  const closed = new Promise<void>(resolve => {
+    resolveClosed = resolve;
+  });
+
+  const tracked: TrackedWorker = { worker, closed, resolveClosed };
+  liveWorkers.set(worker, tracked);
+
+  try {
+    worker.addEventListener("close", () => {
+      resolveClosed();
+    }, { once: true });
+  } catch {
+    // No close event — terminate path will still resolve via timeout/settle.
+  }
+}
+
+export function tryReserveStorageWorker(): AdmissionReservation<Worker> | null {
+  const gateLease = workerGate.tryAcquire();
+  if (!gateLease) return null;
+  let active = true;
+  let bound: Worker | undefined;
+  const reservation: AdmissionReservation<Worker> = {
+    bind(worker) {
+      if (!active) return;
+      bound = worker;
+      registerStorageWorker(worker);
+      const tracked = liveWorkers.get(worker);
+      if (tracked) tracked.reservation = reservation;
+    },
+    release() {
+      if (!active) return;
+      active = false;
+      if (bound) {
+        const tracked = liveWorkers.get(bound);
+        if (tracked?.reservation === reservation) tracked.reservation = undefined;
+      }
+      bound = undefined;
+      gateLease.release();
+    },
+  };
+  return reservation;
+}
+
+export function storageWorkerAdmissionMetrics(): AdmissionMetrics {
+  return workerGate.metrics();
+}
+
+/**
+ * Run `fn` only after every previously gated spawn has finished tearing down.
+ * Used around `new Worker(...)` so tests cannot overlap Windows thread exit.
+ */
+export function withStorageWorkerSpawnGate<T>(fn: () => Promise<T>): Promise<T> {
+  const epochAtEnqueue = spawnCancelEpoch;
+  const run = spawnGate.then(async () => {
+    if (epochAtEnqueue !== spawnCancelEpoch) {
+      throw new Error("storage_worker_spawn_cancelled");
+    }
+    await drainStorageWorkers();
+    if (epochAtEnqueue !== spawnCancelEpoch) {
+      throw new Error("storage_worker_spawn_cancelled");
+    }
+    return fn();
+  });
+  spawnGate = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+export function queuedStorageWorkerSpawnCount(): number {
+  return Math.max(0, workerGate.metrics().active - liveWorkers.size);
+}
+
+/**
+ * Terminate a worker and resolve once its thread has actually exited.
+ *
+ * Safe to call twice: the second call joins the in-flight terminate promise.
+ */
+export function terminateStorageWorker(worker: Worker, timeoutMs = 5_000): Promise<void> {
+  const tracked = liveWorkers.get(worker);
+  if (!tracked) {
+    try { worker.terminate(); } catch { /* already gone */ }
+    return Promise.resolve();
+  }
+  if (tracked.terminatePromise) return tracked.terminatePromise;
+
+  tracked.terminatePromise = (async () => {
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      tracked.resolveClosed();
+    }, timeoutMs);
+
+    try {
+      try {
+        worker.terminate();
+      } catch {
+        tracked.resolveClosed();
+      }
+      await tracked.closed;
+      // Disarm before the OS-join settle: a late timer firing during the sleep
+      // would set timedOut after close already won and throw a false timeout.
+      clearTimeout(timer);
+      // Always run the OS-join settle before throwing on timeout: the timer
+      // only forces `closed`, it does not prove the OS thread has exited.
+      // Callers that catch and continue (e.g. drainAndShutdown) still need
+      // that gap before the next isolate reclaim or server.stop.
+      if (needsWorkerOsJoinSettle()) {
+        await Bun.sleep(0);
+        await Bun.sleep(WORKER_OS_JOIN_MS);
+      }
+      if (timedOut) {
+        throw new Error(`storage worker did not exit within ${timeoutMs}ms`);
+      }
+    } finally {
+      clearTimeout(timer);
+      liveWorkers.delete(worker);
+      tracked.reservation?.release();
+      tracked.reservation = undefined;
+    }
+  })();
+
+  return tracked.terminatePromise;
+}
+
+/**
+ * Await every worker this module still tracks (including terminations already
+ * in flight). Used by test resets so no storage worker outlives the file that
+ * spawned it.
+ */
+export async function drainStorageWorkers(timeoutMs = 5_000): Promise<void> {
+  const pending = [...liveWorkers.keys()].map(worker => terminateStorageWorker(worker, timeoutMs));
+  await Promise.all(pending);
+}
+
+/** Live worker count — exported so a regression test can assert the invariant. */
+export function liveStorageWorkerCount(): number {
+  return liveWorkers.size;
+}

package/src/tray/windows-tray.ps1

@@ -0,0 +1,290 @@
+param(
+  [Parameter(Mandatory = $true)][string]$BunPath,
+  [Parameter(Mandatory = $true)][string]$CliPath,
+  [Parameter(Mandatory = $true)][string]$CodexHome,
+  [Parameter(Mandatory = $true)][string]$OpenCodexHome,
+  [ValidateSet("Run", "Stop")][string]$Mode = "Run",
+  [int]$HostPid = 0
+)
+
+$ErrorActionPreference = "Stop"
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+# Normalize aliases before deriving singleton/event names. Without this,
+# C:\path and C:\path\. create separate tray instances for the same home.
+function Normalize-HomePath([string]$Value) {
+  $full = [System.IO.Path]::GetFullPath($Value)
+  $root = [System.IO.Path]::GetPathRoot($full)
+  if ($full -eq $root) { return $full }
+  return $full.TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)
+}
+$OpenCodexHome = Normalize-HomePath $OpenCodexHome
+$CodexHome = Normalize-HomePath $CodexHome
+
+$script:ownedIcons = New-Object System.Collections.Generic.List[System.Drawing.Icon]
+function Load-TrayIcon([string]$Name, [System.Drawing.Icon]$Fallback) {
+  $path = Join-Path $OpenCodexHome $Name
+  if (-not [System.IO.File]::Exists($path)) { return $Fallback }
+  try {
+    $icon = New-Object System.Drawing.Icon($path)
+    [void]$script:ownedIcons.Add($icon)
+    return $icon
+  } catch {
+    return $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)
+
+function Get-StableHash([string]$Value) {
+  $sha = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($Value.ToLowerInvariant())
+    $hash = [System.BitConverter]::ToString($sha.ComputeHash($bytes)).Replace("-", "").Substring(0, 20)
+    return $hash
+  } finally {
+    $sha.Dispose()
+  }
+}
+
+$stableHash = Get-StableHash $OpenCodexHome
+$stopEventCreated = $false
+$stopEvent = New-Object System.Threading.EventWaitHandle($false, [System.Threading.EventResetMode]::AutoReset, "Local\OpenCodexTrayStop-$stableHash", [ref]$stopEventCreated)
+if ($Mode -eq "Stop") {
+  [void]$stopEvent.Set()
+  $stopEvent.Dispose()
+  exit 0
+}
+
+$createdNew = $false
+$mutex = New-Object System.Threading.Mutex($true, "Local\OpenCodexTray-$stableHash", [ref]$createdNew)
+if (-not $createdNew) {
+  $stopEvent.Dispose()
+  $mutex.Dispose()
+  exit 0
+}
+
+$heartbeatPath = Join-Path $OpenCodexHome "tray-heartbeat.json"
+$actionLogPath = Join-Path $OpenCodexHome "tray-actions.log"
+
+function Write-ActionLog([string]$Message) {
+  $line = "[$([DateTimeOffset]::Now.ToString('o'))] $Message"
+  [System.IO.File]::AppendAllText($actionLogPath, $line + [Environment]::NewLine, (New-Object System.Text.UTF8Encoding($false)))
+}
+
+function ConvertTo-NativeArgument([string]$Value) {
+  if ($Value.Contains('"') -or $Value.Contains("`r") -or $Value.Contains("`n")) {
+    throw "Invalid native command argument"
+  }
+  return '"' + $Value + '"'
+}
+
+function Start-OcxCommand([string[]]$CommandArgs) {
+  try {
+    $allArgs = @($CliPath) + $CommandArgs
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = $BunPath
+    $psi.Arguments = (($allArgs | ForEach-Object { ConvertTo-NativeArgument $_ }) -join " ")
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+    $psi.EnvironmentVariables["CODEX_HOME"] = $CodexHome
+    $psi.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+    $process = [System.Diagnostics.Process]::Start($psi)
+    if ($null -ne $process) { $process.Dispose() }
+    Write-ActionLog "dispatched $($CommandArgs -join ' ')"
+    return $true
+  } catch {
+    Write-ActionLog "launch failed: $($_.Exception.GetType().Name)"
+    $notify.ShowBalloonTip(5000, "opencodex action failed", "The action could not start. Open the logs folder or run ocx doctor.", [System.Windows.Forms.ToolTipIcon]::Error)
+    return $false
+  }
+}
+
+function Read-ListenTarget {
+  foreach ($path in @((Join-Path $OpenCodexHome "runtime-port.json"), (Join-Path $OpenCodexHome "config.json"))) {
+    try {
+      $value = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json
+      $candidate = [int]$value.port
+      if ($candidate -gt 0 -and $candidate -le 65535) {
+        $candidateHost = [string]$value.hostname
+        $ip = $null
+        $hostName = if ([string]::IsNullOrWhiteSpace($candidateHost) -or $candidateHost -in @("localhost", "0.0.0.0", "::", "[::]")) {
+          "127.0.0.1"
+        } elseif ([System.Net.IPAddress]::TryParse($candidateHost.Trim("[", "]"), [ref]$ip)) {
+          if ($ip.AddressFamily -eq [System.Net.Sockets.AddressFamily]::InterNetworkV6) { "[$($ip.ToString())]" } else { $ip.ToString() }
+        } else {
+          "127.0.0.1"
+        }
+        return @{ port = $candidate; host = $hostName; pid = $value.pid }
+      }
+    } catch { }
+  }
+  return @{ port = 10100; host = "127.0.0.1"; pid = $null }
+}
+
+function Read-JsonUrl([string]$Url) {
+  $request = [System.Net.HttpWebRequest]::Create($Url)
+  $request.Method = "GET"
+  $request.Timeout = 700
+  $request.ReadWriteTimeout = 700
+  $response = $request.GetResponse()
+  try {
+    $reader = New-Object System.IO.StreamReader($response.GetResponseStream())
+    try { return ($reader.ReadToEnd() | ConvertFrom-Json) } finally { $reader.Dispose() }
+  } finally {
+    $response.Dispose()
+  }
+}
+
+$notify = New-Object System.Windows.Forms.NotifyIcon
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+$statusItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$statusItem.Enabled = $false
+$safetyItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$safetyItem.Enabled = $false
+$openItem = $menu.Items.Add("Open Dashboard")
+$startItem = $menu.Items.Add("Start Proxy")
+$stopItem = $menu.Items.Add("Stop Proxy and Restore Native Routing")
+$restartItem = $menu.Items.Add("Restart Proxy")
+[void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+[void]$menu.Items.Add($statusItem)
+[void]$menu.Items.Add($safetyItem)
+$logsItem = $menu.Items.Add("Open Logs Folder")
+[void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+$exitItem = $menu.Items.Add("Exit Tray")
+
+$script:online = $false
+$script:port = 10100
+$script:proxyPid = $null
+$script:pendingAction = $null
+$script:pendingStarted = 0L
+$script:pendingDeadline = 0L
+$script:pendingOldProxyPid = $null
+
+function Set-PendingAction([string]$Action, [int]$TimeoutSeconds) {
+  $script:pendingAction = $Action
+  $script:pendingStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  $script:pendingDeadline = $script:pendingStarted + ($TimeoutSeconds * 1000)
+  $script:pendingOldProxyPid = $script:proxyPid
+}
+
+function Complete-PendingAction([bool]$Success) {
+  if ($null -eq $script:pendingAction) { return }
+  $action = $script:pendingAction
+  $script:pendingAction = $null
+  if ($Success) {
+    Write-ActionLog "$action completed (port=$($script:port), pid=$($script:proxyPid))"
+    $notify.ShowBalloonTip(2500, "opencodex", "$action completed.", [System.Windows.Forms.ToolTipIcon]::Info)
+  } else {
+    Write-ActionLog "$action failed to reach the expected state"
+    $notify.ShowBalloonTip(5000, "opencodex action failed", "$action did not reach the expected state. Open the logs folder or run ocx doctor.", [System.Windows.Forms.ToolTipIcon]::Error)
+  }
+}
+
+function Update-TrayState {
+  $target = Read-ListenTarget
+  $script:port = [int]$target.port
+  $health = $null
+  $origin = "http://$($target.host):$($script:port)"
+  try { $health = Read-JsonUrl "$origin/healthz" } catch { }
+  $pidMatches = $null -eq $target.pid -or [int]$target.pid -eq [int]$health.pid
+  $script:online = $null -ne $health -and $health.status -eq "ok" -and $health.service -eq "opencodex" -and [int]$health.port -eq $script:port -and $pidMatches
+  $script:proxyPid = if ($script:online) { [int]$health.pid } else { $null }
+  if ($script:online) {
+    $statusItem.Text = "Proxy: Online (port $($script:port))"
+    $notify.Text = "opencodex: Online"
+    $startItem.Enabled = $false
+    $stopItem.Enabled = $true
+    $restartItem.Enabled = $true
+    try {
+      $startup = Read-JsonUrl "$origin/api/startup-health"
+      $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 }
+    } catch {
+      $safetyItem.Text = "Restart safety: unavailable"
+      $notify.Icon = $warningIcon
+    }
+  } else {
+    $statusItem.Text = "Proxy: Offline"
+    $safetyItem.Text = "Restart safety: start the proxy to inspect"
+    $notify.Text = "opencodex: Offline"
+    $notify.Icon = $offlineIcon
+    $startItem.Enabled = $true
+    $stopItem.Enabled = $false
+    $restartItem.Enabled = $false
+  }
+  $heartbeat = @{ pid = $PID; timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() }
+  if ($HostPid -gt 0) { $heartbeat.hostPid = $HostPid }
+  $heartbeatJson = $heartbeat | ConvertTo-Json -Compress
+  [System.IO.File]::WriteAllText($heartbeatPath, $heartbeatJson, (New-Object System.Text.UTF8Encoding($false)))
+
+  if ($null -ne $script:pendingAction) {
+    $now = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+    $elapsed = $now - $script:pendingStarted
+    $reached = ($script:pendingAction -eq "Start Proxy" -and $script:online) -or
+      ($script:pendingAction -eq "Stop Proxy" -and -not $script:online) -or
+      ($script:pendingAction -eq "Restart Proxy" -and $elapsed -gt 3000 -and $script:online -and $script:proxyPid -ne $script:pendingOldProxyPid)
+    if ($reached) { Complete-PendingAction $true }
+    elseif ($now -gt $script:pendingDeadline) { Complete-PendingAction $false }
+  }
+}
+
+$openItem.add_Click({ Start-OcxCommand @("gui") })
+$startItem.add_Click({
+  $statusItem.Text = "Proxy: Starting..."
+  Set-PendingAction "Start Proxy" 15
+  if (-not (Start-OcxCommand @("__tray-start"))) { $script:pendingAction = $null }
+})
+$stopItem.add_Click({
+  $statusItem.Text = "Proxy: Stopping..."
+  Set-PendingAction "Stop Proxy" 15
+  if (-not (Start-OcxCommand @("stop"))) { $script:pendingAction = $null }
+})
+$restartItem.add_Click({
+  $statusItem.Text = "Proxy: Restarting..."
+  Set-PendingAction "Restart Proxy" 20
+  if (-not (Start-OcxCommand @("__tray-restart"))) { $script:pendingAction = $null }
+})
+$logsItem.add_Click({
+  $psi = New-Object System.Diagnostics.ProcessStartInfo
+  $psi.FileName = $OpenCodexHome
+  $psi.UseShellExecute = $true
+  [void][System.Diagnostics.Process]::Start($psi)
+})
+$exitItem.add_Click({ [System.Windows.Forms.Application]::Exit() })
+$notify.add_DoubleClick({ Start-OcxCommand @("gui") })
+
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 3000
+$timer.add_Tick({
+  if ($stopEvent.WaitOne(0)) {
+    [System.Windows.Forms.Application]::Exit()
+    return
+  }
+  Update-TrayState
+})
+$notify.ContextMenuStrip = $menu
+$notify.Icon = $offlineIcon
+$notify.Visible = $true
+$notify.Text = "opencodex: Checking..."
+
+try {
+  Update-TrayState
+  $timer.Start()
+  [System.Windows.Forms.Application]::Run()
+} finally {
+  $timer.Stop()
+  $timer.Dispose()
+  $notify.Visible = $false
+  $notify.Dispose()
+  foreach ($icon in $script:ownedIcons) { $icon.Dispose() }
+  $menu.Dispose()
+  try { Remove-Item -LiteralPath $heartbeatPath -Force -ErrorAction SilentlyContinue } catch { }
+  try { $mutex.ReleaseMutex() } catch { }
+  $mutex.Dispose()
+  $stopEvent.Dispose()
+}