Notify users and agents when a newer CLI version is available

[ernestoongaro]

Problem

Users who install the Omni CLI through Homebrew, the install script, or a downloaded binary are not told when a newer stable release is available. AI agents invoking the CLI non-interactively also have no stable way to discover and surface an available update.

Proposed behavior

Add a best-effort update check against the latest stable GitHub release.

Human/interactive use

• Check at most once every 24 hours and cache the result in the user cache/state directory.

• Run only when stdout and stderr are TTYs, outside CI, and the current build has a valid release version.

• Use a short timeout; failures must be silent and must never fail or materially delay the requested command.

• After a successful command, print a concise notice to stderr:

  A newer Omni CLI is available: v1.2.3 -> v1.3.0
  Homebrew: brew upgrade omni
  Other installs: https://github.com/exploreomni/cli#installation
  

• If Homebrew is detected, allow a short grace period after release so the tap/core formula has time to update.

• Support an opt-out such as OMNI_NO_UPDATE_NOTIFIER=1.

Agent/non-interactive use

Do not inject a human banner into normal JSON output. Preserve the current contract that API responses are JSON on stdout and errors are JSON on stderr.

• Add an explicit command such as omni update check --format json that returns stable structured data including currentVersion, latestVersion, updateAvailable, releaseUrl, and suggested upgrade commands.
• Document that command in omni agent-help.
• Consider an opt-in environment variable (for example OMNI_AGENT_NOTICES=json) that emits a structured update notice on stderr after successful commands. Keep this opt-in because many automation tools treat any stderr output as a failure.
• Never append an update notice to an API error document.

Example structured result:

{
 "updateAvailable": true,
 "currentVersion": "v1.2.3",
 "latestVersion": "v1.3.0",
 "releaseUrl": "https://github.com/exploreomni/cli/releases/tag/v1.3.0",
 "upgrade": {
 "homebrew": "brew upgrade omni",
 "other": "re-run the installer or replace the binary"
 }
}

Implementation notes

• The release version is already embedded in the binary.
• The install script already queries GitHub's latest-release endpoint.
• The release workflow already publishes stable versions to the Homebrew tap.
• Use semantic-version comparison and ignore prereleases unless the running build is on a prerelease channel.
• Start the network check concurrently and cancel it when the primary command finishes if it has not completed, so update discovery does not add command latency.

Acceptance criteria

• Interactive users see a notice no more than once per 24 hours when a newer stable version exists.
• Homebrew and non-Homebrew upgrade guidance is correct.
• Piped/JSON output and API error documents remain unchanged by default.
• CI, development builds, disabled checks, timeouts, malformed responses, and network failures produce no notice and no command failure.
• Agents have an explicit JSON command for checking update status.
• Tests cover gating, caching, semantic version comparison, Homebrew guidance, timeout/failure behavior, and structured agent output.

Prior art

• GitHub CLI checks once per 24 hours, requires stdout and stderr TTYs, skips CI, offers GH_NO_UPDATE_NOTIFIER, writes the notice to stderr, and delays Homebrew notices for 24 hours after publication.
• Pulumi offers PULUMI_SKIP_UPDATE_CHECK and prints a reinstall command.
• Terraform makes update checks optional and exposes both environment and config opt-outs.
• Bun delegates upgrades to the package manager when it detects a package-manager installation.