TUI: known limitations and how to debug it¶
Current terminal limits, debugging guidance and dated runtime observations. The capability and acceptance map separates source/test evidence from native-terminal and live-provider acceptance.
Telling a bad key apart from a bad model¶
Both surface to the user as "it does not work", and they are different faults with different fixes. Two checks separate them in under a minute.
Is the key valid? Ask the provider directly:
# read the stored key, then probe it (the key itself is never printed)
Invoke-WebRequest https://openrouter.ai/api/v1/key -Headers @{ Authorization = "Bearer $key" }
200 confirms that this endpoint accepted the credential. Completion access,
model availability and account permissions still need their own checks.
Does the model exist? A model id the provider does not serve returns 404
on the completion, and the adapters map that to model_unavailable
(OpenAiCompatibleModelProvider, OpenAiResponsesModelProvider,
AnthropicMessagesModelProvider). So model_unavailable usually means the id is
wrong, not that the provider is down.
stepfun/step-3.7-flash:free -> 404 (no such model)
stepfun/step-3.7-flash -> 200
Two traps that cost real time here:
catalog_unauthorizedis not always about the key. It is thrown both when the credential is empty and when the provider answers 401/403, and the catalog keeps a failed attempt cached for 30 seconds (ProviderCatalogService.RefreshIfNeededAsync). Two runs inside that window both report the first failure, which makes a transient fault look permanent. Wait out the window, or restart, before concluding anything.- Catalog validation precedes the first model request. Every provider's
selected model must exist in its usable catalog and support the selected
protocol. Missing models fail as
model_unavailable; stale/unavailable catalogs retain their named failure. CLI startup warnings are advisory; the Host remains authoritative. A resumed run uses its durable provider selection, so changing settings does not repair that run by selecting a different model.
Colour output¶
TuiPalette resolves a colour depth once, in this order: RU_TUI_COLOR, then
NO_COLOR, then a redirected stdout, then TERM=dumb, then truecolour
detection (COLORTERM, WT_SESSION, TERM=…direct, TERM_PROGRAM), and
otherwise 256-colour. A monochrome TUI therefore means NO_COLOR is set or
stdout is redirected, not that colour is broken — the palette itself is the
OpenCode-cloned dark set (steel blue / violet / warm neutrals) kept local to
the CLI.
To see colour while a shell has NO_COLOR=1:
$env:NO_COLOR=$null
# or pin a depth explicitly
$env:RU_TUI_COLOR=truecolor # truecolor | 256 | 16 | none
Open limitations¶
Native terminal acceptance¶
The multiline composer, adaptive picker/approval cards, queued-state footer and retained tool-block navigation have headless ANSI regression coverage. Command Prompt rendering, Vietnamese IME input, physical resize and Windows clipboard copy/paste still require manual acceptance. Ctrl+J and backslash/Enter are the portable newline paths; Shift+Enter depends on terminal key reporting. Explicit copy returns retained text, including any code gutters, rather than original tool payloads. See the CLI controls.
The 2026-10-31 typing investigation identified redundant whole-window redraws during slash-menu edits and the native loop's default iteration cap. The current implementation skips closed/stable-menu parent redraws, preserves unchanged match selection and uses a 60-iteration native input/render cap while retaining the welcome animation's independent clock. Controlled native measurements use real ConPTY input and production views with pinned logical viewports; they do not measure the physical Windows Terminal font/compositor or IME composition.
The live row and the animation clock¶
The transcript's live activity row (thinking / running tool / writing) is drawn
from a pure time-based clock (TuiSpinner), so its spinner advances at
100 ms per frame whatever the ticker cadence; the running-tool glyph rotates its
half-circle on the same clock. The row clears when the activity settles (the
writer clears it as the permanent tool row lands) or when the turn ends.
A parked run keeps the row static (no rotation) with its reason;
scrolled back, the live row sits below the viewport and the hints-row spinner is
the only running indicator. The 18 ms frame timer still runs for the landing
meteors while the frame is live; when idle its callback only clears the live row
and refreshes the hint frame, so measure before claiming an idle-CPU change.
Earlier free-tier observations (not rerun for the current build)¶
This started as "a free model can chat but never calls a tool": across 31 runs read
from the session database there were 0 tool activity records and 0
model_tool_call_invalid events. Eliminated as causes at the time:
- Not a missing tool. Every step sends the full manifest
(
read_file/list/grep/glob/write_file/edit_file/powershell, …). - Not a permission denial. With preset
standard, reads inside the workspace are auto-allowed byPolicySnapshotEvaluator's effective fallback, so areadwould not have been blocked.
The pipeline executed end to end in that earlier live observation.
cohere/north-mini-code:free asked to list the workspace produced
tool.proposed → tool.execution_requested (read_only) →
tool.execution_completed (ok) → run.state_changed (completed). So the earlier
zero-tool runs were the model choosing to answer in prose, not a broken pipeline.
These observations do not establish current model availability or eliminate Harness defects. Results from OpenRouter's free tier in that sitting:
| Model | Result |
|---|---|
cohere/north-mini-code:free |
works, calls tools |
nvidia/nemotron-3-super-120b-a12b:free |
works |
stealth/space-bunny-alpha |
works |
qwen/qwen3.8-27b:free |
provider_rate_limited |
google/gemma-4-31b-it:free |
provider_rate_limited |
Roughly a third of that free list answered 429 on the first attempt. Other
observed failures included empty_model_reply and 404s. Verify current catalog
and provider responses before using those model IDs. The picker marks catalog
rows without tool-call support as unsupported. An explicitly continued run
retries its pinned provider/model; choosing a different model requires a new run.
The models.dev cache on a developer machine can be stale¶
A cached catalog with no :free models at all was observed here, which
makes the /model picker look like it is hiding entries. The cache is the
first thing to check when the picker's contents disagree with models.dev.
The picker no longer hides the failure: when GET /models fails or returns an
empty catalog it prints catalog unavailable (<reason>) - showing configured
models and names the backend plus row count in the footer, so a short list is
distinguishable from a failed fetch.
Interrupting a chat turn now cancels server-side — but best-effort¶
In Terminal.Gui, Escape during an active turn interrupts it after any open
command or modal panel handles the key. The append-only reader uses its own
line-input cancellation path. Idle Escape preserves the draft and never quits
the chat; /exit is the sole quit command. Interrupts no longer only detach the local stream:
both POST /agent/v1/runs/{runId}/cancel so the run releases its workspace
lock. The POST is best-effort — on failure the TUI prints run_cancel_failed
plus the manual ru agent cancel <run-id> fallback, and until that is run the
server may still own the run. A run waiting on the user (an approval or an
ask_user question) is never cancelled by an interrupt.
Runs do not park for Continue, and only the newest run is adopted¶
There is no Continue gate (ADR 0048): a run that stops ends with its named code,
and a new message starts a fresh run with the session's handoff. ru agent continue
answers continue_removed. Replaying a run an older build parked still shows
▲ run paused · <code> with one notice to send a new message; startup recovery
has failed such a run with that code. Opening chat --session <id> adopts the
session's newest non-terminal run, so a run left behind by a host restart is
visible again; typed Continue reopens it in that chat when it is running or
waiting on an approval or a question, and accepts only runs belonging to the
current session. An adopted running run can also be attached with
ru agent attach <run-id>; it is never followed automatically.
Retained approval recovery differs between GUI and TUI¶
Adoption reads a run summary, which carries no approval id, so the approval
panel cannot be rebuilt. The GUI now says so instead of pretending the run is
running: an adopted waiting_approval run reads
Waiting for approval: <run-id> — review the approval in the session (or cancel the run)
and keeps Stop enabled, without faking a pending-approval re-arm. An approval
requested before the restart is not re-delivered on the resumed cursor, so it
cannot be answered from the adopted session and the run fails as
approval_expired once the 24-hour approval lifetime passes. The
TUI adopts waiting_approval and offers ru agent attach <run-id>. That command reads
at most 2,048 durable events through the captured cursor with a four-second
deadline, recovers the latest approval and checks a fresh run version before
posting the user's decision. Missing/incomplete replay fails closed. Another
client may resolve the approval first; no approval is granted automatically.
Session delete and --session replay have limits¶
/delete [session-id] refuses the current session — switch first, then
delete it — because the transcript, status card, and parked-run tracking all
point at it. With --json or no interactive picker it reports
interactive_required and deletes nothing; the non-interactive route is the CLI
agent session delete <session-id> --yes. Opening chat --session <id> redraws
every turn of the newest history page (up to 200 messages, as the Desktop opens it)
through the live renderer, within the transcript's 2,000-row retention: prompt, narration, thought, plan
and tool rows from each finished run's activity record, then its footer with the
run's real duration. A turn whose record cannot be read falls back to its text; a
run still working is drawn by the follow that adopts it. Ctrl+O reasoning, diffs
and tool output are not part of the record, --json skips replay entirely, and a
history rewind still replays text only.
RPC subscriptions can end without a terminal event¶
ru agent rpc publishes run.detached when a subscription pump ends before the
run is terminal. The reason is bounded to stream_interrupted, subscription_ended
or event_filtered, and the SDK throws a bounded BridgeTransportError for it
instead of waiting forever; subscription_ended does not distinguish "not
terminal" from "could not confirm terminal", so a client that needs certainty
must call run.status. A full outbound queue does not publish run.detached at
all — that path already fails closed with bridge.shutdown.
Debugging a live TUI¶
RU_TUI_DEBUG=<path> writes a layout trace for diagnosing resize and redraw
problems on a real terminal. The transcript is otherwise silent about layout
decisions.
To run the TUI reliably while iterating:
bin/ru.cmd(andruagent.cmd) resolve to the shared publish output undergui-winui3/bin/Release/net10.0-windows10.0.26100.0/win-x64/publish/, so a rebuiltRuAgent.Cli.exehas to be published and copied there.- Close running Ru applications before rebuilding the shared publish package. Windows locks running images; the build reports a failure when stale publish output cannot be removed. Avoid stopping a shared Host while another client has an active run.
- Launch it in its own console window. Started from a parent with no console the process runs but has nowhere to draw, and nothing appears.
Writing tests against the event stream¶
Two separate defects — a turn that rendered nothing, and a successful turn with no footer — were both green tests sitting on a dead code path:
AgentAssistantDeltaModelaccepted onlytrue/falseforreset, but the Host serializes an explicit"reset":null, so every delta frame was dropped.nullnow means an ordinary delta.TuiTranscriptwaited forrun.completed, an event the protocol does not have. Runs really end withrun.state_changedcarryingStatus="completed", which was in the skip list — so the completion flag could never be set. Three tests fabricatedrun.completedand passed on the dead branch.
Take event shapes from HarnessEventContractValidator.AllowedEventTypes and
AgentV1Shared.MapRunState rather than inventing names. This is the second
time event names drifted (the first was model.turn_started /
tool.executed).