UHP and Gemini CLI

Diagnose a model-selection failure at the right layer

A Gemini model can be known upstream while unavailable in your configured HarnessRouter route. The stable CE entrypoint installs Gemini CLI 0.58.0; the current native stable is 0.62.0. Record the installed version and exact requested model ID before debugging.

Symptom	Likely layer to inspect	Evidence you need
Model absent from CE catalogue	HarnessRouter’s supported model IDs	Catalogue response and configured provider
Catalogue entry present but unavailable	Connection/account/model access	Availability flag and useful provider error
Model runs but a tool is missing	Adapter tool policy or MCP configuration	Declared tool set and actual execution event
Terminal output stalls	CLI process/PTY/stream lifetime	Partial events, process state and terminal Response

Do not solve a removed catalogue ID by relying on upstream fuzzy aliases or silently substituting a different model. The historical removal section below records why the three Gemini 2.5 text IDs left HarnessRouter’s catalogue. If your application depends on a specific model, reject unavailable selection clearly and show alternatives from current discovery.

A focused acceptance task reads a known fixture, reports the served model, and then continues the same session. Follow it with one unavailable-model request and verify structured failure. This separates model routing, tool execution and continuity rather than interpreting a successful text answer as proof of all three. Use the API map for selection and session recovery when a partially streamed turn loses its worker. No fresh provider run is asserted here.

Release check — 4 October 2026

The latest stable release observed in the upstream GitHub release API is v0.62.0, published 2026-09-29. The stable release includes ACP tool-title formatting, OAuth refresh-token retention and PTY execution/finalization fixes. The earlier preview/nightly discussion below is a historical development record, not the current release channel.

HarnessRouter integration, checked 4 October 2026: the v0.29.0 entrypoint retains the default pin Gemini CLI 0.58.0. This is source-verified adapter configuration, not a fresh runtime or provider test. HarnessRouter now has 20 released backends; the earlier counts and measurements below retain their dated scope.

Evidence scope: the integration details, commands, measurements and development-head references below preserve the 19 Sep 2026 source snapshot. They are not presented as a fresh test of this newer release. For the current UHP protocol, HarnessRouter release and suite coordinates, use the release tracker and conformance guide. Adapter support does not establish upstream-native UHP adoption.

Source snapshot — 19 Sep 2026

Gemini CLI is a released HarnessRouter backend. It first shipped in HarnessRouter v0.13.24 as the ninth backend and remains present in stable v0.18.4 / efd320b3, which contains twelve released backends. Checked HarnessRouter main is the same efd320b313891191967871de28ff4757528ae6a7 coordinate at this cutoff. The v0.18.3 and v0.18.4 changes did not change the Gemini runner contract: HarnessRouter’s current entrypoint still pins Gemini CLI 0.58.0 rather than tracking upstream automatically.

Checked upstream Gemini CLI coordinates are now:

• stable v0.60.0, published 15 September 2026 at 20:31:02 UTC;
• preview v0.61.0-preview.0, published 15 September 2026 at 20:22:07 UTC;
• latest observed nightly v0.62.0-nightly.20260918.g9450ade79, published 18 September 2026 at 01:23:37 UTC;
• checked upstream main cfbcaa8df13ea4610bb379b377b56d62980c0032, which contains the post-nightly ConPTY finality, cancellation-safety and bounded terminal-cleanup fixes described below.

Those upstream versions do not change HarnessRouter’s separately pinned 0.58.0 adapter coordinate unless HarnessRouter updates and revalidates that pin.

Caution

HarnessRouter integration is not native UHP adoption by Gemini CLI. The UHP server is HarnessRouter. Gemini CLI itself exposes first-party MCP behavior and experimental ACP/A2A surfaces, but reviewed primary sources still do not establish that Gemini CLI itself implements or endorses UHP.

v0.17.3: the three general Gemini 2.5 text models leave the support catalog

HarnessRouter PR #196, merged 17 September 2026 as 54fadfb34dcfb143aac885c2a0a5c46984dad9e0, removes these model ids from the reference implementation’s active support catalog ahead of their planned provider retirement:

• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite

That commit became the HarnessRouter v0.17.3 release tip. The removal is inherited by current stable v0.18.4 and current main. The change is implementation-wide: the Gemini backend catalog, the other backend _MODEL_CATALOG lists, Vercel/OpenRouter provider maps, the Google vendor table, the runner’s pinned Gemini CLI model tuple and console placeholders are reconciled together. The ids are removed, not renamed or aliased.

If a client still requests one of those removed ids, HarnessRouter treats it like any model the selected harness cannot serve under the existing Tasks fallback rule: the authorized default may run instead, while the response records the requested model plus model_fallback: true and a reason. PR #196 records a live built-image check where a request for gemini-2.5-flash was served by gemini-3.8-flash with the fallback metadata present.

The support matrix is also reconciled rather than retaining rows for models the product no longer advertises. PR #196 removes 81 previously measured harness/model pairs involving those ids from the rendered current matrix; historical notes remain historical evidence rather than being rewritten.

Two boundaries matter:

1. gemini-2.5-flash-image is a different media-model line and is not part of PR #196’s removal.
2. Gemini CLI’s internal alias/context entries such as gemini-2.5-flash-base and chat-compression-2.5-* remain because they are part of the pinned CLI’s own model-rewrite table, not advertised HarnessRouter serving ids.

Google Cloud’s Vertex AI release notes publish 16 October 2026 as the updated retirement date for Gemini 2.5 Pro, Flash and Flash-Lite. The Gemini API deprecation documentation has recently shown inconsistent crawl/localization state around those same dates, so this guide does not generalize that date into a universal shutdown claim across every Google Gemini surface. The verified product fact here is narrower: HarnessRouter removed the three ids from its own support catalog in v0.17.3, and later releases retain that policy.

The same PR also tightens local blob-store cleanup: deleting the final object beneath a generated key directory now removes newly empty parent directories up to, but never past, the store root while preserving siblings and idempotent repeat deletion. That storage cleanup is unrelated to Gemini protocol semantics and is mentioned only because it ships in the same release-tip merge.

Stable v0.60.0: upstream security and sandbox hardening

Gemini CLI v0.60.0 promotes the security/runtime work that this site previously tracked in the preview line. Primary release notes include:

• RFC 9207 issuer identification enforcement in the MCP OAuth flow;
• stronger web-fetch destination validation and connection routing;
• isolated temporary/settings directories in sandbox environments;
• extension path-resolution and filesystem-boundary hardening;
• consent and sanitization for runtime-altering extension environment changes;
• stricter system-wide config ownership/permission checks;
• NTFS 8.3 short-name path mitigation;
• provenance preservation for untrusted tool-output envelopes; and
• removal/sanitization of a hardcoded CrUX API key in the Chrome DevTools MCP integration.

These are upstream Gemini CLI implementation changes. They do not revise UHP 2026-09-12, MCP itself, ACP or A2A.

v0.61.0-preview.0 and the v0.62.0 nightly line

The current preview/nightly line adds another cluster of execution-boundary fixes:

• explicit versioned Flash model ids are preserved rather than being silently normalized away;
• restricted-workspace indirect prompt injection through build-file changes and untrusted flags is blocked/confirmed more carefully;
• sandbox filesystem boundaries and runtime-state isolation are hardened;
• AgentLoopContext properties survive object spread instead of disappearing across loop-state handoff;
• OAuth refresh keeps the existing refresh token when a refresh response omits a replacement, while credential deletion is idempotent; and
• PTY execution now tightens file-descriptor cleanup and execution-lifecycle management.

The latest observed nightly is v0.62.0-nightly.20260918.g9450ade79. Its source suffix corresponds to commit 9450ade797302e7c89e13423271aabdea74c7abb, followed by release-bump commit 09e048fd61bc56df18676211f65703e7f0075f3a. Upstream main has since advanced through cfbcaa8df13ea4610bb379b377b56d62980c0032. The material post-nightly runtime changes in that ancestry include PR #29379, PR #29343 and PR #29380; later VS Code focus and authentication-documentation commits do not change the runtime boundaries described here. Nightly coordinates are useful for research, but they should not be substituted for stable or for HarnessRouter’s separately pinned adapter version. The OAuth and PTY changes are Gemini CLI implementation reliability/security behavior, not new MCP, ACP, A2A or UHP wire semantics.

Post-nightly current main: execution finality, cancellation and bounded terminal state

Windows ConPTY finality

Gemini CLI PR #29379, merged 18 September 2026 at 16:54:53 UTC as 4577750da8e9fcee42297a2f54fbae18c0fa6324, fixes a Windows ConPTY failure where a shell command could finish at the OS level while Gemini CLI remained stuck showing the command as active or waiting for input. The linked P1 issue describes simple completed commands remaining active on Windows even though they were not actually waiting for user input.

The failure crosses several lifecycle signals that should not be treated as interchangeable. With @lydell/node-pty, the native Windows process-exit callback can arrive out of order with the named-pipe connection/close path used to surface pty.onExit. A fast process or retained ConPTY pipe handle can therefore leave the public PTY exit event absent while the underlying process is already dead. Deferred resize work can also be queued before the first terminal data event and then execute after process exit, throwing inside the data-event path and interrupting cleanup.

The merged fix adds three defensive boundaries:

• the shell service observes the native Windows PTY agent exit state and schedules a deterministic drain-and-finalize fallback when the normal PTY exit event is lost;
• deferred and active resize calls are suppressed once the ConPTY agent has recorded process exit; and
• output-event and asynchronous processing failures can no longer prevent idempotent execution finalization from settling the command result.

The reusable harness invariant is process death, output drain and host-level execution settlement are distinct events. A runtime should not infer that an execution is still live merely because one wrapper-level close callback did not arrive, and post-exit UI/output work should not be able to strand terminal settlement.

Upstream reports 72 targeted unit tests passing, including regressions for lost pty.onExit, post-exit deferred resize and output-processing failure. The PR’s contributor validation matrix marks Linux as tested and Windows/macOS as not tested, so this guide treats the merge plus focused tests as strong implementation evidence but not as a real-Windows end-to-end validation claim.

Cancellation is expected control flow, not a fatal process exception

Gemini CLI PR #29343, merged 18 September 2026 at 20:16:21 UTC as e128cd6fefa17eec2714c3eabcc2b7bc1d234d0c, fixes a separate cancellation crash observed on modern Node.js runtimes. An AbortError raised synchronously from an AbortSignal event listener can reach Node’s uncaughtException path instead of the Promise unhandledRejection path. Treating only the latter as expected cancellation therefore left an execution-control action capable of terminating the CLI.

The merged handler now recognizes expected AbortError on both paths while retaining failure semantics for genuinely unexpected exceptions: unexpected failures set a non-zero exit code, run exit cleanup and retain a bounded forced-exit fallback. The important boundary is cancellation classification is transport/path independent. A user cancel action should remain expected control flow whether an underlying HTTP/auth library reports it as a rejected Promise or throws synchronously from an event callback.

This does not mean arbitrary uncaught exceptions are ignored. The suppression is scoped to AbortError; the general uncaught-exception path remains fatal after cleanup.

Terminal history and cleanup now have explicit resource bounds

Gemini CLI PR #29380, merged 18 September 2026 at 20:26:27 UTC as 196c772a970166a26fa0e5f92f4fbd89ec265301, hardens the same shell-execution service against memory growth and lifecycle residue during repeated or high-output commands.

The merge:

• reduces the headless terminal scrollback ceiling from 300,000 to 50,000 lines;
• caps full-buffer extraction at 16 MiB (16 * 1024 * 1024 bytes) and truncates the middle when necessary rather than serializing an unbounded retained buffer;
• avoids unnecessary color conversion/allocation when color output is disabled;
• removes the temporary abort-during-drain listener on normal exit;
• clears intermediate output/sniff buffers and pending render timers during finalization; and
• makes test reset tear down active PTYs, child processes and background log streams.

The reusable invariant is execution finality is incomplete if the runtime settles the result but retains unbounded terminal state, event listeners or closure buffers. Process lifecycle and resource lifecycle therefore need separate, explicit completion conditions. PR #29380’s checklist records validation on macOS, Windows and Linux, alongside focused unit coverage for serialization, listener cleanup, reset teardown and diagnostic-path formatting.

Together, PRs #29379, #29343 and #29380 form one coherent post-nightly execution-lifecycle boundary: detect real process death, settle output/result deterministically, classify user cancellation correctly, and release bounded terminal resources. They are current-main behavior, not part of stable v0.60.0 or the observed v0.62.0-nightly.20260918.g9450ade79. They do not update HarnessRouter’s Gemini CLI 0.58.0 pin and do not change UHP, MCP, ACP or A2A wire semantics.

HarnessRouter’s Gemini adapter

HarnessRouter’s Gemini CLI backend is a backend adapter, not a protocol transplant. The reference implementation launches Gemini CLI in its non-interactive stream-JSON mode, supplies provider/model state through HarnessRouter’s runner and normalizes the resulting execution into UHP tasks/sessions/files.

Important released/reference-runtime boundaries include:

• Gemini CLI first became a backend in v0.13.24.
• The recorded runner pin remains 0.58.0 rather than tracking upstream latest automatically; current v0.18.4 still carries that exact default.
• The dedicated backend uses the direct Google API-key path, while provider routing elsewhere in HarnessRouter can use other compatible serving surfaces.
• HarnessRouter v0.14.x made requested-versus-served Gemini identity explicit, removed silent model fallback in the measured routing path, added TokenRouter’s native Google route, tied helper tiers/aliases to the requested turn model and made deleted sessions final.
• UHP 2026-09-12 Harness Plugins can supply MCP components to Gemini CLI; HarnessRouter maps plugin SSE and Streamable HTTP into the Gemini client’s distinct url / httpUrl configuration forms.
• v0.17.3 / PR #196 removed the three general Gemini 2.5 ids from HarnessRouter’s advertised product catalog while leaving the runner’s Gemini CLI binary pin unchanged; stable v0.18.4 inherits that removal.

The last point is intentionally version-bounded: a product catalog change can ship independently of a new UHP version or Gemini CLI binary.

Native MCP, ACP and A2A remain separate boundaries

MCP

Gemini CLI has first-party MCP client behavior. The current upstream release line continues to harden OAuth, transport and trust boundaries around that client. HarnessRouter can also configure MCP for the Gemini backend, including plugin-derived servers, but that is an adapter path into Gemini CLI’s native MCP client rather than a new UHP transport.

ACP

Gemini CLI has an experimental ACP surface. ACP is the editor/client ↔ coding-agent boundary; UHP is the product/client ↔ harness-server boundary. Presence of both in the same harness does not make their session, permission or transport semantics interchangeable.

A2A

Gemini CLI also has an experimental A2A surface. A2A addresses agent-to-agent interoperability, not complete harness execution behind a UHP server. Native A2A capability therefore does not imply native UHP adoption.

Evidence boundaries

Question	Verified answer
Is Gemini CLI a released HarnessRouter backend?	Yes. Since v0.13.24; stable v0.18.4 contains it among twelve backends.
What Gemini CLI version does HarnessRouter pin?	0.58.0 in the checked v0.18.4 runner install path.
What is current upstream stable Gemini CLI?	v0.60.0, published 15 Sep 2026.
What is current upstream preview/nightly evidence?	v0.61.0-preview.0 and observed nightly v0.62.0-nightly.20260918.g9450ade79.
What is checked upstream Gemini CLI main?	cfbcaa8d; the material post-nightly execution-lifecycle fixes in its ancestry are PRs #29379, #29343 and #29380.
What is HarnessRouter stable/current main?	Stable v0.18.4 / efd320b3; current main is the same efd320b3 coordinate at this cutoff.
Are gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite still in current HarnessRouter support lists?	No. PR #196 removes them and reconciles provider/backend/UI catalogs plus current support-matrix rows; later releases inherit the change.
Does PR #196 remove gemini-2.5-flash-image?	No. The PR explicitly treats it as a different product line.
Does Gemini CLI natively implement UHP?	Not established by reviewed primary sources.

Why this matters

Gemini CLI illustrates three independent compatibility coordinates that must not be collapsed:

1. upstream harness version — currently stable v0.60.0, preview v0.61.0-preview.0, nightly v0.62.0-nightly.20260918.g9450ade79, and later checked main cfbcaa8d;
2. HarnessRouter adapter pin — still 0.58.0; and
3. HarnessRouter product catalog policy — the v0.17.3 removal of three retiring Gemini 2.5 serving ids is inherited by stable v0.18.4 even though the runner binary pin itself did not change.

A model can therefore disappear from the reference implementation’s advertised support surface without a new UHP version or a new Gemini CLI binary. Likewise, material upstream execution-lifecycle changes can land on Gemini CLI main without changing HarnessRouter’s pinned binary or the UHP protocol. Those distinctions are exactly why requested-model metadata, explicit fallback evidence and source-pinned runtime claims matter.

Related pages

Read HarnessRouter Community Edition, release tracker, UHP vs MCP, UHP vs ACP, UHP vs A2A and adoption tracker.

Primary sources

• HarnessRouter v0.18.4
• HarnessRouter v0.18.4 / current-main commit efd320b3
• HarnessRouter Gemini runner pin at stable v0.18.4
• HarnessRouter v0.17.3
• HarnessRouter PR #196 — Gemini 2.5 leaves the active catalog
• Google Cloud Vertex AI release notes — Gemini 2.5 retirement-date update
• Google AI Gemini deprecation tracker
• Gemini CLI v0.60.0
• Gemini CLI v0.61.0-preview.0
• Gemini CLI nightly v0.62.0-nightly.20260918.g9450ade79
• Gemini CLI nightly source — PTY lifecycle fix 9450ade7
• Gemini CLI OAuth refresh-token / credential-delete fix 8fd119f7
• Gemini CLI PR #29379 — Windows ConPTY finality
• Gemini CLI issue #25166 — completed command remains active
• Gemini CLI PR #29343 — cancellation AbortError handling
• Gemini CLI PR #29380 — bounded terminal buffers and execution cleanup
• Gemini CLI checked main cfbcaa8d
• Gemini CLI repository