Skip to content

feat(codex): show Smart Router state in the footer - #1728

Open
masonc08 wants to merge 16 commits into
masonc08/codex-stable-upgradefrom
masonc08/codex-smart-router-statusline
Open

masonc08 wants to merge 16 commits into
masonc08/codex-stable-upgradefrom
masonc08/codex-smart-router-statusline

Conversation

@masonc08

@masonc08 masonc08 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Routed Codex terminal sessions now show a persistent Smart Router indicator: a green ON badge or gray OFF badge beside the current model, directory, and remaining context. Installed-skill toggles update it without restarting. Unreadable controls show UNKNOWN and recover on a later refresh.

Stacked on the required Codex upgrade PR; merge that first. Version-floor enforcement, managed upgrade behavior, and CI version pins belong to the base PR. This diff adds the indicator, launch wiring, focused tests, and documentation.

The provider uses launch-only MCP registration and selection, reads session-local controls, and starts Python with -P. Saved preferences and unrelated MCP registrations remain on disk; UG selects its footer layout for the routed session. The base PR's required-version gate guarantees API availability, so the footer needs no separate version probe.

Verified Claude's real behavior: its banner uses green ON and gray OFF badges, and the plain ON/OFF prompt hint remains visible in both states after the temporary banner hides. Codex keeps the corresponding badge in its persistent footer.

Validation

  • Native stable Codex 0.171.0 passed ON/OFF/ON badge colors, bold foreground, and UNKNOWN/read recovery.
  • An isolated-wheel Arclet run against the requested workspace completed five hidden-file tasks across two concurrent sessions and a first-prompt launch. Installed-skill toggles preserved conversation identity, independent controls, saved footer preferences, and the UG profile. GPT-6-Luna was selected through ordinary user settings.
  • Final-wheel smoke completed a hidden-file task and installed-skill ON/OFF/ON transitions on stable 0.171.0. The base PR's updated managed-default behavior passed six live Arclet scenarios: decline on 0.164.0 and 0.170.0, manual/automatic updater failure, EOF followed by updater failure, and successful upgrade to 0.171.0. Each completed a hidden-file task; fallback required no disable flag. Five used the TUI and EOF used native exec.
  • After merging the managed-fallback fix, all 100 footer/launcher checks passed. Ruff lint/format and type checks passed. The base PR's 733 agent/version/launcher/contract tests and 944 CLI tests passed independently.
  • Seven selected installation checks passed in the earlier stable validation. A broader combined run encountered four order-dependent desktop lifecycle failures that also reproduce on unchanged main; all four pass alone.
  • Router selection remains a separate limitation: first-prompt selection returned HTTP 400/downstream 422 and used fallback; delegated file tasks completed but recorded no routing decision. Successful router selection is unverified. Native Windows footer rendering remains untested.

Videos

Stable Codex Smart Router footer

Both videos render captured PTY output at original timing. Media is on a separate branch and excluded from this source change.

Stable upstream contract. Manual validation and upgrade behavior: docs/codex-smart-router-statusline.md.

Checklist before requesting review

  • Comment /ug-review and address the comments.
  • Comment /integration-test and address any failures.

@masonc08

Copy link
Copy Markdown
Collaborator Author

/ug-review

return {}
return {
"features.tui_extensions_statusline": True,
"tui.status_line_provider": {"server": SERVER_NAME, "tool": TOOL_NAME},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

other · medium
this replaces any tui.status_line the user/admin set for every smart-routed launch. can we skip the provider when one is configured, and add these launch-only keys to the Codex ownership table?

Comment on lines +72 to +73
thread = state.get("thread", {})
model = thread.get("model", {})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · low
what happens if the snapshot has "thread": null or "model": null? .get raises AttributeError, so the read returns -32602 and no footer. can we fall back to {} when the value isn't a dict?

Suggestion:

Suggested change
thread = state.get("thread", {})
model = thread.get("model", {})
thread = state.get("thread") if isinstance(state.get("thread"), dict) else {}
model = thread.get("model") if isinstance(thread.get("model"), dict) else {}

Comment thread src/ucode/smart_routing/v2.py Outdated
Comment on lines +939 to +940
statusline_config = codex_statusline.launch_config(codex_version, session_env_path)
config_io.deep_merge_dict(overlay, statusline_config)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · medium
this always overrides tui.status_line_provider and turns on an experimental feature. what happens to a user who set their own provider? can we skip it if one is configured, add an opt-out, and add it to the Codex launch-only table in AGENTS.md?

Comment thread src/ucode/smart_routing/v2.py Outdated
binary,
*provider_args,
*codex_config_args(
{key: value for key, value in statusline_config.items() if key != "mcp_servers"}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maintainability · low
can codex_statusline expose a tui_config(...) helper (or split app-server/TUI dicts) instead of filtering "mcp_servers" here? any new server-only key would silently leak into the TUI argv.

Comment thread tests/test_codex_smart_routing_v2.py Outdated

@pytest.mark.parametrize("platform_name", ["posix", "nt"])
@pytest.mark.parametrize("first_prompt", [False, True])
@pytest.mark.parametrize("codex_version", ["0.169.0", "0.171.0-alpha.11", "0.171.0-alpha.12"])

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test · low
are all these cases necessary? this triples the lifecycle matrix (12 runs). version gating is already covered in test_codex_statusline. can we keep just one supported and one unsupported version?

@github-actions

Copy link
Copy Markdown
Contributor

Polly AI Review

Blocking issues

  • [P2] src/ucode/agents/codex.py:2111 — can we reuse the successful 10s probe? after a 2s timeout caches unknown, this lookup returns that stale result and disables the footer on supported Codex.

    minimum_version_error retries with timeout=10, but agent_version caches that call separately from the default-timeout call. Extend TestLaunchCodex.test_codex_smart_routing_launch_dispatches_to_v2 to cover default-probe timeout followed by successful retry.

Security vulnerabilities

None identified in the frozen diff.

Non-blocking notes

None.

Approach

The native status-line provider and launch-only overrides fit the outcome without another proxy or persistent configuration writes. Reusing the resolved version would avoid the additional cached lookup and the failure above.

Summary

Diff size (computed): 11 files; +550 / -9 lines (559 changed text lines); 0 binary files.

Category Files Added Deleted Share of changed text lines
Tests and test support 4 298 5 54.2%
Documentation 3 79 0 14.1%
Dependencies and lockfiles 0 0 0 0.0%
Implementation / other 4 173 4 31.7%

Shares use additions + deletions, including generated text and lockfiles. Binary files have no line count. Tests include fixtures/helpers under test paths and colocated test/spec files; categories are path-based, not coverage measurements.

Changes

Adds a session-local MCP footer provider, version-gated launcher wiring, and an optional no-retry controls read. Supporting tests cover rendering, protocol handling, session isolation, and launcher composition; documentation records ownership and rollout requirements. No dependencies or generated assets change.

The size is proportional to the protocol, process-boundary, and compatibility coverage. No concrete removable scaffolding or unrelated cleanup was identified. Added source comments are concise.

Tests

Test-by-test assessment

Static review only; no PR code was executed. Reported test and lint results were not independently verified. The default-probe-timeout/successful-retry path lacks regression coverage and exposes the blocking issue above.

Test / case Behavior protected Layer Needed? Action / rationale
tests/README.md:3 — documentation-only addition Inventories footer coverage and native-validation limits Test documentation keep Describes what component checks establish without claiming native execution.
tests/integration/README.md:3 — documentation-only addition Separates offline checks from native renderer and gateway validation Test documentation keep Records the stable-release validation gate without adding another E2E scenario.
tests/test_codex_smart_routing_v2.py:79 — TestLaunchCodex.test_codex_smart_routing_launch_dispatches_to_v2; supported, upgraded, auto-upgraded, declined, failed, still-old, unknown, unknown-auto-upgrade, unknown-after-upgrade, each with empty arguments or a prompt Minimum-version handling, upgrade outcomes, and forwarding the detected version Component keep Extends the existing dispatch journey. Add the timeout-then-successful-retry regression identified above; its version stub currently cannot expose separate cache entries.
tests/test_codex_smart_routing_v2.py:258 — TestLaunchCodex.test_owns_app_server_interposer_and_tui_lifecycle; 0.171.0-alpha.12 × both first-prompt modes × POSIX/Windows Provider registration reaches app-server; footer selection reaches TUI; unrelated overlay MCP and lifecycle survive Launcher component keep Extends the nearest lifecycle scenario. Simulated Windows arguments do not establish native Windows behavior.
tests/test_codex_smart_routing_v2.py:258 — TestLaunchCodex.test_owns_app_server_interposer_and_tui_lifecycle; 0.169.0 and 0.171.0-alpha.11 × both first-prompt modes × POSIX/Windows Unsupported versions still launch without footer configuration Launcher component keep Checks compatibility at configuration composition, beyond the isolated version predicate.
tests/test_codex_statusline.py:18 — _labels; tests/test_codex_statusline.py:24 — _read_lines Readable render assertions and bounded subprocess-output receipt Test support keep Small local helpers leave faults and assertions in the tests.
tests/test_codex_statusline.py:47 — test_statusline_version_boundary; unknown, older releases, early alphas, and dev Rejects unsupported or unrecognized versions Unit keep Numeric alpha boundaries catch lexical-comparison errors at the lowest reliable layer.
tests/test_codex_statusline.py:47 — test_statusline_version_boundary; alpha.12/.13, beta, rc, stable, build suffix, and later release Accepts versions allowed by the stated experimental contract Unit keep Centralizes the version matrix without repeating it through real processes.
tests/test_codex_statusline.py:51 — test_launch_config_pins_session_without_credentials Interpreter/module invocation, UTF-8, spaced controls path, launch-only selection, and unsupported-version omission Unit keep Protects configuration construction separately from launcher composition. Checks the generated entry, not the entire inherited process environment.
tests/test_codex_statusline.py:66 — test_footer_tracks_session_toggles_and_current_thread ON→OFF→ON, current model/reasoning, project name, remaining context, and removal of stale thread data Unit with real file keep Exercises session-state transitions and rendered output without requiring native UI.
tests/test_codex_statusline.py:94 — test_footer_handles_missing_snapshot_and_windows_paths Missing-snapshot defaults and Windows project basename Unit keep Distinct renderer boundaries; Windows path parsing does not require E2E coverage.
tests/test_codex_statusline.py:105 — test_unreadable_controls_show_unknown_and_recover; missing file, invalid JSON, array root, and unrecognized key UNKNOWN on invalid controls, followed by recovery Unit with real file keep Covers distinct material read/validation failures and subsequent successful refresh.
tests/test_codex_statusline.py:115 — test_footer_does_not_retry_blocked_file_reads Permission denial does not enter routing’s retry delay Unit keep Protects the footer’s immediate-fallback behavior, distinct from retry-positive routing coverage.
tests/test_codex_statusline.py:127 — test_missing_session_controls_never_uses_inherited_on_state Missing session identity cannot inherit another routing indication Unit keep Protects session-local attribution, unlike an identified but unreadable controls file.
tests/test_codex_statusline.py:133 — test_stdio_errors_leave_provider_available Protocol errors, notification silence, and continued availability In-process protocol component keep Checks serialized replies and recovery; does not establish interoperability with native Codex.
tests/test_codex_statusline.py:153 — test_real_stdio_process_keeps_sessions_separate_and_polls_live_controls Real stdio initialization/resource replies, two-session isolation, live toggles, and Unicode transport Subprocess component keep Process, environment, and transport boundaries justify this layer; it is not redundant renderer coverage.

No test functions or parameterized cases are removed. Relevant existing configuration, metadata, and routing tests were inspected. The trusted checkout lacks tests/_helpers/README.md, so that catalog was unavailable.

Launcher assertions establish configuration composition and unchanged saved bytes for the seeded configuration. They do not establish native consumption of the experimental API. Reported alpha rendering, stable-build compatibility, completed gateway inference, and native Windows behavior remain unverified. No downstream usage-data verification is established or claimed by these component checks.

For manual validation, follow docs/codex-smart-router-statusline.md:13: complete a task requiring an agent response, verify ON→OFF→ON and second-session isolation, then repeat on the actual stable build and native Windows before delivery.

Scope

All changes support the session-local Smart Router footer; no unrelated changes were found. The patch does not install an alpha or raise the minimum version. Stable-build validation and the subsequent minimum-version/upgrade update remain explicit delivery gates in docs/codex-smart-router-statusline.md:51; this review does not establish release readiness.


Automated review by Polly · workflow run

@masonc08

Copy link
Copy Markdown
Collaborator Author

/ug-review

"mcp_servers": {
SERVER_NAME: {
"command": sys.executable,
"args": ["-X", "utf8", "-m", __name__],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security · medium
Codex starts this server from the project directory, and -m puts that directory first on sys.path. If a checked-out repo has its own top-level ucode/ package, that code runs on every smart-routed launch. Can we add -P (Python 3.11+) so the working directory isn't put on the import path?

Suggestion:

Suggested change
"args": ["-X", "utf8", "-m", __name__],
"args": ["-P", "-X", "utf8", "-m", __name__],

Comment on lines +108 to +109
if model.get("reasoning_level"):
model_name += " " + model["reasoning_level"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · low
can we type-check these snapshot fields? a non-string display_name/reasoning_level/cwd raises TypeError, serve returns -32602, and the whole footer disappears instead of degrading.

@github-actions

Copy link
Copy Markdown
Contributor

Polly AI Review

Blocking issues

  • [P2] src/ucode/agents/codex.py:2111 — can we reuse the successful fallback version? after a cached 2s timeout, the 10s probe permits launch, but this call still passes unknown, disabling the footer on supported Codex.

Security vulnerabilities

No confirmed vulnerabilities. Native MCP startup timing and working-directory behavior remain unverified.

Non-blocking notes

  • src/ucode/smart_routing/codex_statusline.py:50 — can we add -P, as the metrics exporter does, to avoid importing modules from the provider’s working directory?
  • tests/test_codex_smart_routing_v2.py:257 — can we seed saved footer preferences and an MCP server? the current fixture does not exercise preservation of those settings.
  • tests/test_codex_smart_routing_v2.py:444 — can we remove this duplicate saved-config assertion? the assertion at line 375 already checks the same completed lifecycle.
  • tests/test_codex_statusline.py:215 — can this stdio journey include discovery and tools/call before resource reads? those successful MCP exchanges currently lack assertions.

Approach

The launch-only provider fits the outcome without another proxy or persisted configuration. It reuses the existing MCP override serialization and session-controls reader. Reusing the version resolved by the minimum-version gate would avoid a second, inconsistent version decision.

Summary

Diff size (computed): 11 files; +656 / -9 lines (665 changed text lines); 0 binary files.

Category Files Added Deleted Share of changed text lines
Tests and test support 4 364 5 55.5%
Documentation 3 88 0 13.2%
Dependencies and lockfiles 0 0 0 0.0%
Implementation / other 4 204 4 31.3%

Shares use additions + deletions, including generated text and lockfiles. Binary files have no line count. Tests include fixtures/helpers under test paths and colocated test/spec files; categories are path-based, not coverage measurements.

Changes

Adds a version-gated MCP footer provider, separates app-server registration from terminal selection, and reads session controls on refresh for ON/OFF/UNKNOWN recovery. Documentation covers configuration ownership, manual validation, and the stable rollout gate. No dependency or generated-file changes are included.

The size is broadly justified by rendering, protocol handling, launcher compatibility, and process-isolation coverage. The duplicate saved-config assertion identified above can be removed without losing coverage.

Tests

Test-by-test assessment

Static assessment only: no PR code or tests were executed. The reported focused checks, lint/typechecks, recordings, and earlier credentialed runs remain unverified here. Mocked launch assertions and local stdio exchanges do not establish native Codex rendering, gateway routing, or usage attribution. Native Windows UI and the eventual stable build remain unverified.

Test / case Behavior protected Layer Needed? Action / rationale
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 Detected version reaches routed launch across existing launch/version cases Mocked launch component keep Preserves dispatch coverage. Extend with short-probe timeout followed by an eligible long-probe result to catch the blocking defect.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_owns_app_server_interposer_and_tui_lifecycle — 0.169.0 and 0.171.0-alpha.11, platform and first-prompt variants Unsupported versions omit footer settings while retaining lifecycle behavior Mocked process/config component keep Exercises compatibility exclusions through the launcher; does not establish native platform behavior.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_owns_app_server_interposer_and_tui_lifecycle — 0.171.0-alpha.12, platform and first-prompt variants Provider registration, terminal-only selection, sibling MCP preservation and saved-file preservation Mocked process/config component keep Distinct launch-boundary assertions. Seed actual saved footer/MCP settings as noted above. Content-based hook lookup retains the existing assertions.
tests/test_codex_smart_routing_v2.py:444 — added saved-config assertion Saved file remains unchanged after launch completes Assertion support remove Duplicates the retained assertion at line 375, with no intervening lifecycle operation.
tests/test_codex_statusline.py::test_statusline_version_boundary — all version parameters Unknown, older, alpha-boundary, beta, release-candidate, stable and suffixed version handling Unit keep Low-cost parser boundary coverage belongs at this layer.
tests/test_codex_statusline.py::test_launch_config_pins_session_without_credentials Provider argv/environment, spaced controls path and unsupported-version exclusion Unit/config keep Protects provider construction; does not establish the child’s complete inherited environment.
tests/test_codex_statusline.py::test_terminal_config_contains_only_feature_and_selection Terminal excludes registration/private fields; empty input remains empty Unit/config keep Directly protects app-server/terminal configuration separation.
tests/test_codex_statusline.py::test_nullable_snapshots_keep_footer_available — all nullable/malformed-section parameters Optional snapshot sections retain usable output Unit keep Consolidated input-boundary matrix with meaningful fallback assertions.
tests/test_codex_statusline.py::test_footer_tracks_session_toggles_and_current_thread ON→OFF→ON, current model/reasoning, directory and remaining context File-backed component keep Tests live controls and replacement of thread state without requiring a native client.
tests/test_codex_statusline.py::test_footer_handles_missing_snapshot_and_windows_paths Default-model fallback and Windows directory parsing Unit keep Path parsing is independently testable; this is not native Windows UI evidence.
tests/test_codex_statusline.py::test_footer_matches_claude_badges — ON/OFF parameters Badge foreground, background and weight Unit/render tree keep Protects styling data, but cannot prove terminal appearance.
tests/test_codex_statusline.py::test_unreadable_controls_show_unknown_and_recover — missing, invalid JSON, array and unknown-key parameters UNKNOWN followed by recovery after controls are repaired File-backed component keep Covers distinct controls failure inputs at the smallest reliable layer.
tests/test_codex_statusline.py::test_footer_does_not_retry_blocked_file_reads Permission failure returns UNKNOWN without retry sleeps Mocked failure component keep Protects the footer-specific latency policy without changing routing retries.
tests/test_codex_statusline.py::test_missing_session_controls_never_uses_inherited_on_state Missing session marker cannot report inherited ON Unit/environment keep Distinct from an unreadable file at a configured path.
tests/test_codex_statusline.py::test_stdio_errors_leave_provider_available Parse/request errors, notification silence, unknown methods/resources and continued service In-memory protocol component keep Exercises error framing and recovery independently of process transport.
tests/test_codex_statusline.py::test_real_stdio_process_keeps_sessions_separate_and_polls_live_controls Two-process isolation, repeated controls reads and Unicode transport Local subprocess component keep The process boundary adds distinct evidence. Extend this journey with successful discovery/tool exchanges rather than adding another process test.
tests/test_codex_statusline.py::_labels Shared extraction of labels from render trees Assertion helper keep Small helper avoids repeated traversal logic.
tests/test_codex_statusline.py::_read_lines Bounded waits for subprocess replies Process helper keep Supports the necessary stdio boundary without live-service setup.
tests/README.md — added coverage description Distinguishes offline coverage from native/gateway validation Documentation keep Accurately limits what the component tests establish.
tests/integration/README.md — added footer guidance Explains stable-baseline limitations and native validation requirements Documentation keep Prevents existing stable CI from being mistaken for footer-rendering evidence.

No test functions or parametrized cases are removed. Relevant existing minimum-version fallback, controls-recovery, session-toggle, and native metadata journeys cover adjacent behavior, but do not protect propagation of the successful fallback version into this new gate.

After fixing that propagation, verify the timeout→successful-fallback launch regression. On the intended native build, follow docs/codex-smart-router-statusline.md: check ON→OFF→ON, UNKNOWN→recovery, concurrent-session isolation, and unchanged saved footer/MCP settings. Stable-build validation remains necessary before lifting the draft rollout gate.

Scope

All changed paths support the persistent, session-local Smart Router footer or its validation and documentation. No clearly unrelated changes were found. The minimum-version floor remains unchanged; accepting future version strings does not itself establish stable API compatibility.


Automated review by Polly · workflow run

@masonc08 masonc08 changed the title feat(codex): show Smart Router state in experimental footer feat(codex): show Smart Router state and require stable 0.171.0 Nov 20, 2026
@masonc08
masonc08 marked this pull request as ready for review November 20, 2026 13:51
Comment thread src/ucode/agents/codex.py
Comment on lines +150 to +151
MINIMUM_SMART_ROUTING_CODEX_VERSION = (0, 171, 0)
MINIMUM_SMART_ROUTING_CODEX_VERSION_TEXT = "0.171.0"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

other · high
will this break current ug users? on codex 0.164–0.170, smart-routed launches now fail via ensure_minimum_version. routing worked there; can we gate only the statusline overlay on 0.171 and keep routing without the footer?

Comment thread src/ucode/cli.py Outdated
Comment on lines +4461 to +4467
else:
if routing_unavailable:
ensure_minimum_version(
"codex",
lambda: codex_agent.minimum_version_error(smart_routing_enabled=True),
)
routing_unavailable = None

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · high
Managed routing used to fall back to a warning. Now a dev on Codex 0.164–0.170 who declines the prompt, or whose codex update fails (offline, or no native upgrader), hits a RuntimeError and gets exit 1. So an admin's routing setting blocks the launch, and the dev has no flag to opt out. Can we catch the RuntimeError here and keep the 'Running without smart routing' fallback?

Suggestion:

Suggested change
else:
if routing_unavailable:
ensure_minimum_version(
"codex",
lambda: codex_agent.minimum_version_error(smart_routing_enabled=True),
)
routing_unavailable = None
else:
if routing_unavailable:
try:
ensure_minimum_version(
"codex",
lambda: codex_agent.minimum_version_error(
smart_routing_enabled=True
),
)
except RuntimeError as exc:
routing_unavailable = str(exc)
else:
routing_unavailable = None

Comment on lines +1152 to 1154
statusline_config = codex_statusline.launch_config(session_env_path)
config_io.deep_merge_dict(overlay, statusline_config)
config_args = codex_config_args(overlay)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · medium
is this needed for codex app-server launches? the caller owns those clients, but this still spawns the footer MCP server and exposes its statusline tool to IDE/desktop sessions. can we merge it only on the TUI path?

version_match = re.search(r"\b(\d+)\.(\d+)\.(\d+)\b", version_output)
assert version_match is not None, version_output
routing_supported = tuple(int(part) for part in version_match.groups()) >= (0, 164, 0)
routing_supported = tuple(int(part) for part in version_match.groups()) >= (0, 171, 0)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test · low
what happens with a 0.171.0-alpha codex? _smart_routing_version_supported treats it as below the floor, but this check (and the app-server early return) treats it as supported. can we match the prerelease rule?

Comment on lines +1038 to +1041
gate.send("n\r", "decline the required upgrade")
gate.wait_for(lambda _: gate.ended, "blocked launch to exit")
gate.child.close()
assert gate.child.exitstatus != 0

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · high
this locks in a hard block on managed-default launches for codex <0.171 when the user declines the upgrade (used to warn and continue). will this break current ug users on 0.164–0.170? can we keep the warn-and-run fallback?

Comment thread tests/test_cli.py Outdated
Comment on lines +1242 to +1244
assert result.exit_code == (1 if recovery in {"decline", "managed-default"} else 0), (
result.output
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test · medium
This test now treats exit 1 on a managed-default decline as correct, which locks in the hard block from cli.py. Can it assert the old warn-and-launch-without-routing result for managed launches instead?

@github-actions

Copy link
Copy Markdown
Contributor

UG review recommendation

RECOMMENDATION: REJECT (request changes)

Reasons:

  • codex.py 150-151 (high): Raising the minimum version to 0.171 breaks smart-routed launches for existing users on Codex 0.164–0.170, where routing used to work. Only the statusline overlay should be gated on 0.171.
  • cli.py 4461-4467 (high): Managed routing used to fall back to a warning. Now it raises a RuntimeError and exits 1 when the user declines the upgrade or codex update fails. An admin's routing setting then blocks the launch, and the developer has no flag to opt out.
  • test_ug_smart_routing_hooks.py 1038-1041 (high) and test_cli.py 1242-1244 (medium): These tests lock in the hard block as correct. Regression coverage for the previous warn-and-continue path is gone.
  • v2.py 1152-1154 (medium): The footer MCP server is spawned and its statusline tool is exposed to codex app-server (IDE/desktop) sessions, which the caller owns. It should be merged only on the TUI path.
  • codex_statusline.py 92-93 (low): A non-string reasoning_level or display_name raises TypeError, so that poll shows no footer. This is minor but should be hardened, and cwd needs the same check.
  • test_ug_smart_routing_hooks.py 1015 (low): Prereleases such as 0.171.0-alpha are handled inconsistently. _smart_routing_version_supported treats them as below the floor, while this check and the app-server early return treat them as supported.

Findings considered: 7 (severities: high: 3, low: 2, medium: 2); see the inline review comments.

Advisory only: this recommendation never approves or merges the pull request. The ready-to-approve label tracks it.

@masonc08 masonc08 changed the title feat(codex): show Smart Router state and require stable 0.171.0 feat(codex): show Smart Router state in the footer Nov 20, 2026
@masonc08
masonc08 changed the base branch from main to masonc08/codex-stable-upgrade November 20, 2026 14:00
@github-actions

Copy link
Copy Markdown
Contributor

Polly AI Review

Blocking issues

  • P1 — Upgrade gate runs before launch eligibility: src/ucode/cli.py:4463
    can we gate upgrades on effective routing and avoid app-server stdin? With managed routing on 0.170.0, this consumes JSON-RPC input; declining also blocks unrouted exec.
  • can we extend tests/test_cli.py::TestSubcommandRouting.test_codex_routing_version_requires_upgrade_or_explicit_disable with managed old-client exec and app-server cases that forbid prompting?

Security vulnerabilities

None identified by static review.

Non-blocking notes

None.

Approach

Native status-line configuration and session-local controls avoid another proxy. Reuse the existing codex.launch() version gate, where routing eligibility and protocol ownership are known.

Summary

Diff size (computed): 18 files; +729 / -82 lines (811 changed text lines); 0 binary files.

Category Files Added Deleted Share of changed text lines
Tests and test support 9 406 55 56.8%
Documentation 3 112 14 15.5%
Dependencies and lockfiles 0 0 0 0.0%
Implementation / other 6 211 13 27.6%

Shares use additions + deletions, including generated text and lockfiles. Binary files have no line count. Tests include fixtures/helpers under test paths and colocated test/spec files; categories are path-based, not coverage measurements.

Changes

The change adds a persistent Codex routing indicator, session-control recovery, and a newer routing minimum through the existing upgrade flow. Implementation, tests, CI pins, ownership guidance, and documentation contribute to the diff; dependencies and generated assets are unchanged.

The size is broadly justified by the rendering, process, and compatibility boundaries. Removing the duplicate CLI upgrade gate would reduce implementation and fix the blocker.

Tests

Test-by-test assessment

Static assessment of the checksum-verified frozen snapshot. Both trusted policies were read. No tests were executed. Base/head commit objects were unavailable locally, so changed-line evidence comes from the snapshot and surrounding context from the trusted default-branch checkout.

Parameterized cases are grouped only where their purpose and recommendation match.

Test / case Behavior protected Layer Needed? Action / rationale
tests/test_codex_statusline.py::test_launch_config_pins_session_without_credentials Interpreter, -P, UTF-8, session controls, provider selection Unit keep Directly protects the provider configuration contract. It checks declared environment values, not whether credentials are inherited by the process.
tests/test_codex_statusline.py::test_terminal_config_contains_only_feature_and_selection Terminal overrides exclude provider-only configuration Unit keep Small, focused assertion on the terminal/provider configuration split.
tests/test_codex_statusline.py::test_nullable_snapshots_keep_footer_available — null root and null/wrong-shaped nested fields Incomplete snapshots remain renderable Unit keep Defensive input matrix belongs at the rendering layer.
tests/test_codex_statusline.py::test_footer_tracks_session_toggles_and_current_thread ON/OFF transitions and current model, effort, directory, context Unit/filesystem keep Protects dynamic rendering beyond process transport.
tests/test_codex_statusline.py::test_footer_handles_missing_snapshot_and_windows_paths Missing-snapshot fallback and Windows basename handling Unit keep Cheap cross-platform rendering coverage without a native Windows dependency.
tests/test_codex_statusline.py::test_footer_matches_claude_badges — ON and OFF Badge text and green/gray styling Unit keep Checks the visual-tree contract; native rendering remains a separate verification boundary.
tests/test_codex_statusline.py::test_unreadable_controls_show_unknown_and_recover — missing, malformed, wrong-shaped, unrecognized controls UNKNOWN state and later recovery Unit/filesystem keep Distinct failure categories share one recovery contract; no live matrix is needed.
tests/test_codex_statusline.py::test_footer_does_not_retry_blocked_file_reads Refresh does not sleep after permission errors Unit/fault injection keep Protects the new non-retrying refresh path and its latency boundary.
tests/test_codex_statusline.py::test_missing_session_controls_never_uses_inherited_on_state Session indicator cannot borrow inherited routing state Unit keep Distinct isolation failure from an unreadable named controls file.
tests/test_codex_statusline.py::test_stdio_errors_leave_provider_available Protocol errors and notifications do not terminate service In-process protocol keep Exercises error recovery through the dispatcher rather than only rendering helpers.
tests/test_codex_statusline.py::test_real_stdio_process_keeps_sessions_separate_and_polls_live_controls Two real providers, independent controls, live transitions, Unicode Local subprocess keep Uniquely checks process imports, transport encoding, and session separation. It does not establish native Codex rendering.
tests/test_codex_statusline.py — _labels, _read_lines, process/queue cleanup Support for rendering and subprocess assertions Test support keep Local support serves the distinct process boundary; no separate executable cases.
tests/test_agent_codex.py::TestMinimumVersion::test_supported_version — below-floor versions Routing rejects older clients independently of the ordinary minimum Unit keep Correct lowest layer for threshold boundaries.
tests/test_agent_codex.py::TestMinimumVersion::test_supported_version — minimum prereleases, stable release, build metadata, newer versions Version suffix and boundary semantics Unit keep Explicitly covers rejection of minimum-version prereleases. A newer prerelease is intentionally accepted by the test.
tests/test_agent_codex.py::TestMinimumVersion::test_smart_routing_rechecks_an_unknown_version_with_a_longer_bound — supported, old, unknown, timeout Slow-probe recovery and bounded version checks Component keep Version fixtures change; existing recovery and timeout protections remain.
tests/test_cli.py::TestSubcommandRouting::test_managed_smart_routing_overrides_env_vars_but_not_the_flag_or_a_version — existing cross-agent matrix Managed configuration, flags, version selectors, environment restoration CLI component keep Supported-version fixture update preserves useful precedence coverage.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — decline cases Explicit routed launch stops after upgrade refusal CLI component keep Public-command enforcement retains actionable errors and environment restoration.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — successful upgrade cases Accepted upgrade reaches routed execution CLI component keep Exercises CLI-to-updater-to-agent behavior rather than only dispatcher calls.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — explicit-disable cases Ordinary execution bypasses the routing minimum CLI component keep Extend with managed old-client exec without explicit disable; current cases avoid the faulty branch.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — managed decline cases Managed terminal routing stops after refusal CLI component keep Add managed stdio app-server input and forbid interactive prompting. Current cases invoke only the terminal shape.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — managed upgrade cases Managed routing survives a successful upgrade CLI component keep Distinct from explicit routing selection.
tests/test_cli.py::TestSubcommandRouting::test_codex_routing_version_requires_upgrade_or_explicit_disable — retired 0.163.0 parameter cases Earlier below-floor examples CLI component remove Replaced by nearer-boundary and minimum-prerelease cases; no distinct failure category is lost.
tests/test_cli.py::TestSubcommandRouting::test_warns_once_and_launches_unrouted_when_version_leaves_codex_unrouted — existing eligibility matrix Warnings and unrouted paths across agents, flags, versions, subcommands CLI component keep Fixture update only. Its native-subcommand case is unmanaged and supported, so it misses the blocker.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — supported interactive/prompt cases Supported clients dispatch through V2 Agent component keep Retargets the floor while retaining both launch shapes.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — upgraded cases Required upgrade succeeds before dispatch Agent component keep Existing updater boundary complements public CLI coverage.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — auto-upgraded cases Automatic upgrade skips confirmation Agent component keep Sufficient coverage of UG_AUTO_UPGRADE_AGENT=1; another CLI matrix is unnecessary.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — declined cases Refusal prevents native execution Agent component keep Retains prompt and no-execution assertions.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — failed-update cases Updater failure prevents execution Agent component keep Material failure path distinct from refusal.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — still-old cases Successful updater exit cannot bypass version validation Agent component keep Protects post-upgrade verification.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — unknown-version cases Unidentified client cannot route Agent component keep Protects actionable failure without offering an uninformed update.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — unknown with auto-upgrade cases Automatic mode does not update an unidentified client Agent component keep Distinct automatic-upgrade safety boundary.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_smart_routing_launch_dispatches_to_v2 — unknown-after-upgrade cases Unverifiable upgrade cannot launch Agent component keep Covers failed verification after nominal updater success.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_app_server_routes_only_from_codex_routing_floor — below/at floor Agent-level app-server fallback versus routing Agent component keep Useful boundary, but direct codex.launch() invocation bypasses the new earlier CLI gate.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_codex_launch_normalizes_cached_bootstrap_model Cached model normalization Agent component keep Fixture-only version update; existing behavior remains protected.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_startup_config_precedence — managed/profile/user precedence, default/custom home Startup model ownership and precedence Component/filesystem keep Version fixture changes do not justify changing this existing matrix.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_startup_config_precedence — invalid values and malformed TOML Invalid higher-priority configuration preserves valid fallback Component/filesystem keep Distinct value-validation and parsing boundaries remain covered.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_startup_config_precedence — no saved model Cached bootstrap-model fallback Component/filesystem keep Retains the final fallback category.
tests/test_codex_smart_routing_v2.py::TestLaunchCodex::test_owns_app_server_interposer_and_tui_lifecycle — POSIX/Windows and routing-mode cases Provider registration, terminal selectors, controls, unrelated overlay server, cleanup, saved-file preservation Launcher component keep Appropriate consumer-level wiring coverage. Saved-file checks do not establish native Codex configuration merging or rendering.
tests/test_codex_smart_routing_v2.py::TestCustomCatalogModels::test_start_model_comes_from_custom_catalog Catalog-selected startup model Agent component keep Supported-version fixture update; no new scenario needed.
tests/test_codex_smart_routing_v2.py — local render_overlay wrapper and import changes Unrelated-server preservation setup Test support keep Bounded setup extends the existing lifecycle scenario rather than adding another harness.
tests/integration/test_ug_codex_app_server.py::test_ug_codex_app_server_runs_unrouted_below_routing_floor Real initialize response, clean protocol stdout, old-client handling Native integration keep Threshold update preserves a distinct transport boundary. Explicit environment routing does not exercise managed selection.
tests/integration/test_ug_smart_routing_hooks.py::test_smart_router_managed_default_matches_codex_version_at_launch — old-client branch Real refusal blocks; explicit disable permits completed work Native integration keep Replaces intentional warn-and-continue behavior with the new terminal contract.
tests/integration/test_ug_smart_routing_hooks.py::test_smart_router_managed_default_matches_codex_version_at_launch — supported branch Managed skills, routed child work, correlated completion Native integration keep Existing journey covers the native boundary; no duplicate E2E is needed.
tests/integration/test_ug_smart_routing_hooks.py — TerminalProcess import/setup Observing and answering the real upgrade prompt Test support keep Supports the changed refusal branch without another test function.
tests/test_integration_contract.py::test_live_ci_lanes_together_cover_every_blocking_live_case — Claude/Codex Lane coverage and ordinary/routing pins Workflow contract keep Existing assertion owns the pin update; collection coverage does not prove execution.
tests/test_integration_contract.py::test_dedicated_cuj_ci_runs_each_discovered_file_on_its_own_runner Dedicated runner setup and routing pin Workflow contract keep Updates the existing workflow contract without another test.
tests/README.md Component coverage and verification boundaries Documentation keep Documentation-only edit; no executable cases.
tests/integration/README.md Native/component split, upgrade behavior, routing pins Documentation keep Documentation-only edit; no executable cases.

No test functions were removed. Existing subcommand environment-suppression and lower-level launch-shape tests do not cover managed routing being reconsidered before dispatch. The smallest missing coverage is the public-CLI regression identified above.

The target checkout lacks tests/_helpers/README.md; its test guides and neighboring scenarios were available.

The PR describes native badge transitions, completed file tasks, and concurrent-session isolation; those runs were not independently verified here. Successful router selection remains explicitly unverified after the reported HTTP 400/downstream 422 fallback. Native Windows rendering and downstream usage attribution are also unverified; request headers alone would not establish usage correctness.

For human verification after the fix: use Codex 0.170.0 with managed routing enabled and automatic upgrade unset. Confirm ug codex exec "reply OK" reaches ordinary execution without an upgrade prompt. Send an initialize request through ug codex app-server; it must receive a protocol response or an actionable stderr refusal without consuming input as upgrade answers.

Scope

No clearly unrelated changes were found. The provider, routing minimum, CI pins, tests, and documentation support the stated workflow. The managed gate’s effect on ordinary commands and app-server stdin is a correctness regression within that scope, not separate feature work.


Automated review by Polly · workflow run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant