Managed terminal UX audit
Validated for the OpenCode-first AUTO experience on 2026-09-04. The guiding rule is one authoritative state model: session, executor, quota and knowledge data originate in IVOAI and are rendered by the managed frontend. JSON and non-TTY output never receive branding or ANSI decoration.
Information hierarchy
The normal path is ivoai auto: preflight, knowledge selection, private backend,
then the IVOAI-themed OpenCode TUI. The home footer shows only actionable summary
state; the sidebar shows knowledge sources; /ivoai opens the complete bounded
panel. Symbols are always paired with words, so status never depends on color alone.
| UI field | Authoritative source | Missing evidence |
|---|---|---|
| version | binary build metadata | N/A |
| frontend | session metadata | N/A |
| primary executor | quota scheduler/session | Unknown |
| worker | task ledger/runtime | Not available |
| authentication | official executor auth probe | authentication required |
| quota | quota manager | N/A |
| Memory / Context | session knowledge bootstrap | degraded |
| servers | ServerPool + session router observations | not-probed; never infer live health from enrollment |
| OpenCode permissions | session startup configuration | interactive default |
| knowledge scope | Knowledge Router selection | automatic or restricted |
| compression | CompressionProvider policy | Unknown |
| skills | Skill Registry | Not available |
Menu and route inventory
Multi-server Connections (v0.9.7)
The old single-default Connect/Disconnect pair is replaced by IVOAI Servers. Add is create-only; each profile has Test, Enable/Disable, Edit metadata, Re-enroll and confirmed Remove. Both CLI and TUI use ServerConnector/ServerPool and the existing stable-ID secret store. No separate TUI configuration exists. Enrollment status is never rendered as a live health probe. Recent explicit tests are cached for one minute; restart returns to not_probed.
The existing terminal tokens, monospaced terminal font, left-aligned lists, keyboard selection, adaptive width and NO_COLOR fallback are retained. No new palette or decorative chrome was introduced. Destructive confirmation names the target alias. Normal labels distinguish enabled, connection, health and credential metadata without relying on color. Fixture smoke covers the actual launcher, keyboard navigation, no-echo input, persistence, failures and selective removal.
| Surface | Decision | Rationale in managed mode |
|---|---|---|
| IVOAI launcher: Automatic | KEEP / PRIMARY | Opens the OpenCode frontend under IVOAI control. |
| IVOAI launcher: Codex | KEEP | Explicit official Codex TUI escape hatch. |
| IVOAI launcher: Claude | KEEP | Explicit official Claude Code TUI escape hatch. |
| IVOAI launcher: OpenCode | RENAME | Opens the managed IVOAI OpenCode frontend. |
ivoai opencode | KEEP | Same managed control plane as AUTO. |
| standalone OpenCode provider | MOVE | Explicit session start --executor opencode --mode direct. |
| status / doctor | KEEP | Operational and machine-readable diagnostics. |
| monitor | KEEP | Existing read-only runtime view; not duplicated in the TUI panel. |
OpenCode /ivoai | ADD | Full session, executor, quota and source status. |
| OpenCode home footer/sidebar | ADD | Persistent, compact scope and health. |
OpenCode /connect | HIDE BY CONFIG | Only the IVOAI provider is enabled; executor auth stays official. |
| OpenCode model/provider picker | KEEP / GROUP BY CONFIG | AUTO plus capability-discovered explicit models and native reasoning variants; no duplicate login. |
| OpenCode approval policy | ADD | Persistent IVOAI opencode.permission_mode; /ivoai displays the session mode. Changes take effect next session. |
| OpenCode share | DISABLE IN MANAGED MODE | Prevents accidental conversation publication. |
| OpenCode auto-update | DISABLE IN MANAGED MODE | Supply-chain pin and rollback stay authoritative. |
| OpenCode update | HIDE IN MANAGED MODE | IVOAI updates the pinned component. |
| session picker | KEEP | OpenCode sessions map to bounded IVOAI executor session IDs. |
| theme picker | KEEP | IVOAI theme is installed and selected; accessibility remains available. |
direct opencode menus | KEEP UPSTREAM | IVOAI does not modify use outside managed mode. |
Responsive terminal policy
IVOAI uses OpenCode's supported renderer and plugin slots rather than parsing ANSI or
automating keystrokes. Long aliases and purposes are sanitized and capped; the panel
shows at most eight source rows plus a remainder count. OpenCode owns Unicode width,
resize, focus, cursor and terminal cleanup. TERM=dumb, NO_COLOR, pipes and JSON
continue through the existing non-TUI IVOAI surfaces.
Stable public action inventory
Every action below is covered by the menu-tree regression test. The decisions are
KEEP unless the table above explicitly says RENAME, MOVE, HIDE, DISABLE, or
ADD; nested section entries are grouped in the launcher instead of duplicated at
the top level.
auto
status doctor doctor.inventory version
setup update.dry-run update rollback uninstall
connect.list connect.chatgpt disconnect.chatgpt connect.claude disconnect.claude connect.server
servers.list servers.add servers.manage servers.test servers.toggle servers.edit servers.re-enroll servers.remove
mcp.list mcp.add mcp.remove mcp.auth mcp.auth.remove mcp.header mcp.test
mcp.tools mcp.enable mcp.policy mcp.direct-policy
launch.codex launch.claude launch.opencode
memory.status memory.configure
session.direct.codex session.direct.claude session.direct.opencode session.orchestrated.codex session.orchestrated.claude
session.list session.monitor session.stop
session.continuity session.scope.adopt session.scope.restore
project.status project.init
config.show config.headroom config.memory config.ruflo config.auto config.auto-planner config.auto-failover config.auto-checkpoint
config.auto-strategy config.auto-parallel config.auto-bootstrap config.auto-escalation config.session-mode config.primary config.reviewer config.workers
config.auto-gate config.auto-plan
config.auto-policy policy.sources policy.concurrency policy.worker-cap policy.writes policy.provider policy.low-quota policy.primary policy.mcp policy.confirmation
capabilities.update capabilities.ponytail capability.inspect capability.enable capability.disable capability.pin capability.unpin capability.update capability.rollback
server.setup server.status server.doctor server.start server.stop server.restart server.logs
server.enrollment.create server.enrollment.list server.enrollment.revoke
server.web-access.create server.web-access.list server.web-access.revoke
server.connector.list server.connector.add server.connector.remove server.context.status server.memory.status
server.gateway.configure server.backup server.restore
remote.status remote.doctor remote.connector.list
Visual system
The TUI theme uses neutral ink/slate surfaces, a restrained blue primary and amber
accent. Semantic success, warning and error colors have textual markers. Light and
dark palettes are authored independently with high-contrast text, borders and diff
colors. IVOAI lettering uses the official home_logo slot; the upstream OpenCode
binary, license, notices and provenance are not patched or hidden.
Backlog P1/P2 capability acceptance (2026-10-12)
Every changed public capability must reuse its runtime contract, expose a useful
managed interface, and record its validation. TestUXAuditCoversEveryPublicMenuAction
checks the menu inventory in CI; canonical help is checked against CLI structure.
The pull request template requires evidence and a justification for exceptions.
| Action / capability | Managed interface | Shared authority / boundaries |
|---|---|---|
config.auto-profiles, profile.show, profile.restore | Configuration → Automation Profiles; preview, exact APPLY/RESTORE | Config Store allowlisted atomic change and rollback receipt; effective inherited/custom settings shown; affects future sessions |
doctor.repair-hooks | Dashboard diagnostics, explicit repair | Memory receipt ownership; diagnostic preview through doctor; foreign hooks never adopted by name |
| Operational telemetry | OpenCode /ivoai, activity panel, live status | Versioned session observations and authenticated SSE; bounded replay, reconnect gap and stale feedback; no provider probes per event |
| Session scope adoption/restoration | Session Control → conversation actions | Account-verified explicit metadata transition with private backup; retained native history remains visible to the resumed provider |
| Raw telemetry transport and scope backup paths | CLI/bridge administrative interface | Not a second event editor or arbitrary state import; TUI uses the same session service |
Codex experience parity
| Capability | Existing behavior | P1/P2 delivery / validation boundary |
|---|---|---|
| Model and reasoning | Native model picker and capability-discovered variants | Preserved; display requested/effective values from session ledger |
| History and resume | Native picker and IVOAI mappings | Scope-aware lookup; explicit adoption of legacy scope with backup; synthetic and opt-in live continuity tests |
| Diffs, clipboard, keyboard navigation | Managed OpenCode native controls | Preserved; existing semantic/keyboard and native integration tests remain required |
| Approvals and cancellation | IVOAI approval contract and native cancel | Observed task/approval lifecycle events; policy remains in IVOAI |
| Tools and workers | Existing task ledger and tool streaming | Correlated events, DAG dependencies and real duration, bounded activity display |
| Context and quota | Provider observations; partial availability | Cached observations only in UI reads; unavailable/stale data never interpreted as zero |
| Profiles | Manual advanced settings | Seven allowlisted presets; preview, explicit TUI confirmation, restore and customization detection |
| Claude inference | Existing supported adapter | Contract fixtures only in this round; real validation requires an available subscription |