Skip to content

fix(stt): report local Codex start faults as retryable and clarify Codex setup copy - #39597

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
pearcekieser/codex-stt-followups
Nov 20, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
pearcekieser/codex-stt-followups

Conversation

@Pearcekieser

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When Codex dictation fails to start because of a local fault, the user sees a failure they can retry, a desktop build for a target without Codex media wheels still ships, and the Codex setup messages say what to run and where.

These are the follow-ups from the last reviews of #26076, which added Codex as an experimental dictation provider:

  1. A start failure that is not a CodexError (a fault in the media stack, the peer connection or a malformed reply) is reported as stt_codex_voice_unavailable. That message tells the user that their Codex build or account cannot start voice. The fault is local, a retry can clear it, and the gateway logs nothing about the cause.
  2. packaging/build-desktop.sh installs the voice-codex extra with no guard. On a target with no prebuilt aiortc or PyAV wheel, the whole desktop build fails.
  3. No test pins the transcript caps or the two event-queue limits at their exact values.
  4. Four Codex setup strings are unclear. The not-installed and signed-out messages give commands but do not say to run them in a terminal. The extra-missing message does not say what to do next. The "Is my audio kept?" line for Codex does not open with an answer.

Why it matters

A user who picks Codex and hits a local fault is told that their account cannot use voice, so they can give up on a provider that works on the next try. A maintainer who gets that report has no log line to start from. A release build for a target without aiortc wheels stops, although only one experimental, opt-in provider is missing.

Not a goal

  • Codex dictation on Windows. The Windows bundle omits it because Windows has no agent sandbox.
  • Monospace formatting for the commands inside these messages. Settings renders the messages as plain text, so that needs a rendering change.
  • A label on each command in the Settings prerequisites panel that names the extra it installs.

What changed (motivation → approach → change)

A local fault at Codex start tells the user to record again instead of blaming their account. A desktop build without Codex media wheels ships without Codex dictation. Four setup messages say where to run each command.

Area Change
Start failure, src/kiro_crew/stt/codex.py StreamingSession.start passes a CodexError through unchanged. Any other exception becomes stt_codex_failed. website/src/lib/sttProviders.ts maps that code to "Codex dictation stopped before it could finish. Your draft is kept; try recording again." The warning log names only the exception type. The traceback goes to debug, because the exception text can carry the reply.
Desktop build, packaging/build-desktop.sh The voice-codex install has the same if ! guard as the recognizer install. If it fails, the build logs one line and the bundle ships without Codex dictation. Settings then reports stt_codex_extra_missing. docs/system-specs/modules/stt-streaming.md says the same.
Setup copy, website/src/i18n Four strings change in en.manual.json and the 11 translated locales, and en-XA.json is regenerated. The next table has the English.
Key New English
unavailable_codex_missing In a terminal, run npm i -g @agentclientprotocol/codex-acp, or set CODEX_PATH. Then run codex login to sign in with ChatGPT.
unavailable_codex_extra The optional voice-codex package is not installed in the gateway's Python environment. If Settings lists a pip command, run it in a terminal and restart {{productName}}. Otherwise, pick another provider.
unavailable_codex_login Run codex login in a terminal and sign in with ChatGPT. API-key logins are not supported here.
retention_codex Not by {{productName}}. Audio goes to OpenAI through your Codex ChatGPT sign-in, and your OpenAI account’s retention rules apply.

The extra-missing message says "a pip command" for two reasons. First, the command Settings shows for this extra is <python> -m pip install 'aiortc>=1.15,<2', which does not contain the word voice-codex. Second, the same panel can list ffmpeg commands, which do not restore Codex. A sealed bundle has no pip channel, so Settings shows no pip command there and the message sends the user to another provider.

The build guard applies to every target. No list of targets without aiortc wheels exists, and the provider is opt-in, so a narrower guard would fail builds that nobody can predict.

Backwards compatibility

Compatible: stt_codex_failed and stt_codex_voice_unavailable both exist on main, in the metrics schema and in website/src/lib/sttProviders.ts. A Codex refusal still returns stt_codex_voice_unavailable.

Removes nothing: the diff changes which existing code one exception path returns, makes one build step non-fatal, and rewords four strings. No key, code, route or setting is removed or renamed.

Tests

Proof: PROVEN test/test_codex_stt.py::test_a_local_start_fault_is_a_retryable_failure_with_its_type_logged (head d14e14e)

Test What it locks in
test_a_local_start_fault_is_a_retryable_failure_with_its_type_logged A RuntimeError from the media stack during start returns stt_codex_failed. The codex logger writes one warning, "codex dictation did not start: RuntimeError", and that warning does not contain the exception text.
test_transcript_item_id_at_its_cap_is_accepted An item id at exactly its length cap is accepted.
test_transcript_text_cap_admits_exactly_its_limit Text up to _MAX_TEXT_CHARS is kept, and one more character raises.
test_transcript_item_cap_admits_exactly_its_limit _MAX_ITEMS items are kept, and one more raises.
test_session_event_queue_holds_its_limit_then_reports_falling_behind The session queue holds _MAX_EVENTS events. The next event sets stt_codex_failed. The oldest event makes room for the error, which is delivered last.
test_rpc_event_queue_holds_its_limit The RPC queue holds codex_rpc._MAX_EVENTS events with no failure.
test_rpc_event_queue_overflow_is_a_transport_failure One more RPC event sets stt_codex_failed and queues TRANSPORT_FAILED.
website/electron/test/packaging.test.js The voice-codex install is inside if ! ...; then log ...; fi with no exit 1.

The seven new backend tests ran 20 times at -n0 and 10 times at -n 4 next to test/test_codex_media.py and test/test_stt_session.py, with no failure. They also passed in shuffled order with seed 24839.

The scoped backend run on this host had 25 failures in files the diff does not touch. 24 are in test/test_cloud_source.py and test/test_host_git_repo_exec_neutralization.py::TestCloudSourceTarball. On this host / is owned by uid 65534, and src/kiro_crew/cloud/source.py refuses an ancestor that neither the user nor root owns. The last one is test/test_find_ui_auto.py::test_the_generated_auto_tier_answers_labels_only_it_carries[continue with github-en-Continue with GitHub-path0]. It fails the same way when this PR's files are reverted to 775dd6d.

Manual verification

The screenshots come from the built SPA at head d14e14e. Playwright served website/dist on loopback and answered every /api call from stubs, so no gateway ran. GET /api/stt/status returned each Codex reason code in turn.

Not run by hand: a real Codex start with a broken media stack, and a desktop build on a target without aiortc wheels. The first test injects the start fault, and the packaging pin fixes the shape of the guard.

Local review ran on claude-opus-5.5 and gpt-5.6-sol. The profile names gpt-6.1-sol, which the backend does not serve, so the GPT pass ran at reduced fidelity.

Real-machine verification

Not run. The changed start path needs a local media-stack fault, which only the unit test can force on demand. The changed build step needs a desktop target that has no aiortc wheel, and no such target is known.

Screenshots / video

The extra-missing message, with the pip-command wording:

Settings, Codex extra missing

Codex not installed, signed out, and the retention line

Settings, Codex not installed

Settings, Codex signed out

Settings, Codex retention line

Related Issues

Follow-up to #26076.

Sibling sweep

Swept: git grep -n -E "except Exception as exc" -- src/kiro_crew/stt/
Swept: git grep -n -E '"$ROOT[' -- packaging/
Sibling: src/kiro_crew/stt/codex_rpc.py:212 -- not affected -- a write fault there already becomes CODE_FAILED
Sibling: src/kiro_crew/stt/codex.py:127 -- not affected -- a failed sandbox pre-check counts as a refusal on purpose, per its docstring
Sibling: packaging/build-desktop.sh:551 -- not affected -- the cloud transports at line 551 install unconditionally by design, lark-oapi at line 575 is pure Python, and the recognizer install at line 561 already has the guard

Pattern harvest

Not generalizable: the Codex start path was the one place that gave an unexpected local exception the code for a provider refusal, and the Codex RPC writer next to it already maps the same case to CODE_FAILED.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Fixes #39596

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d14e14e10bb9f1353ec514c1781c23732a02b146 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change is proportionate, reuses codes that already exist, can be reverted, and four rendered screenshots are attached for the reworded copy.

Notes

  • If voice-codex fails to install, the build still succeeds and only writes a log line, so a release artifact can lose Codex dictation without anyone noticing. Showing that log line in the release job summary would make the loss visible, and a full build failure isn't needed for that.

[DESIGN-REVIEWED] d14e14e

Description read

[DESCRIPTION-READ] dade36ef959f9183b26bcde5846c9f8250409fc53b8a4549825fe4aa3334e22c

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d14e14e10bb9f1353ec514c1781c23732a02b146 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The start-fault fix reuses the existing CODE_FAILED path, and the new test fails on base. The build guard uses the same if ! form as the recogniser install. Every reworded string is part of the Goal.

What this change ships

Inventory (6 items) — 6 justified

Intent: when Codex dictation fails because of a local fault, the user is told to retry instead of being told their account can't use voice, and desktop builds without Codex media wheels still ship. FIX.

  1. A local fault at Codex start now shows "try recording again" instead of "your build or account cannot start voice" — justified
  2. The gateway logs the exception type as a warning and the traceback at debug level only — justified
  3. A desktop build on a target without aiortc or PyAV wheels now ships without Codex dictation instead of failing — justified
  4. Setup messages for a missing Codex adapter, a missing voice-codex package and a missing login now say to run the command in a terminal and what to do next — justified
  5. The "Is my audio kept?" line for Codex now opens with an answer ("Not by …") — justified
  6. Tests pin the transcript caps and both event-queue limits at their exact values — justified

[FIRST-PRINCIPLES-REVIEWED] d14e14e

Description read

[DESCRIPTION-READ] fbff6c369a0969f069dd9233abc4fa2628d9a7605897c0b3fb85ab30bfaf17b2

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of d14e14e10bb9f1353ec514c1781c23732a02b146 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: the change only rewords four setup strings, and screenshots 1–4 show every one of them. The blind reader understood that each one is setup guidance.

Notes

  • unavailable_codex_extra: "If Settings lists a pip command…" sends users to Settings while they are already in it, and no command appears on screen. The blind reader said: "I think I'm already in Settings, and I can't see any pip command anywhere." The gateway already knows whether a pip channel exists, so show one of two strings: one that includes the command, or one that says "Pick another provider".
  • unavailable_codex_missing and unavailable_codex_login: users have to retype the terminal commands by hand. The blind reader said there is "no button to do it for me or to copy the command". Add a copy button for each command, in the same style as UpdateFoundModal.
  • "not installed" and "not working" use the same yellow pill, but only the "not working" line turns red. The blind reader said: "I can't tell how serious each one is." Use one severity treatment for both.

[UX-REVIEWED] d14e14e

Description read

[DESCRIPTION-READ] 99268c2e66f8fea1f5dcc04e05eba4483d801dd845ae87628e3b72ab67dbca9f

That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed d14e14e10bb9f1353ec514c1781c23732a02b146 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d14e14e

Verdict parsed from the review's SHA-scoped output markers for commit d14e14e10bb9f1353ec514c1781c23732a02b146.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d14e14e10bb9f1353ec514c1781c23732a02b146 false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d14e14e10bb9f1353ec514c1781c23732a02b146 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d14e14e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d14e14e10bb9f1353ec514c1781c23732a02b146 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 19, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: reviewer-finding: Design Review.

Narrow follow-up. In StreamingSession.start, a CodexError still passes through unchanged, so real refusals keep stt_codex_voice_unavailable: the JSON-RPC error reply, the old-version check and thread/realtime/error all raise CodexError(CODE_UNAVAILABLE). Any other exception now maps to the existing stt_codex_failed code. The warning log names only the exception type and the traceback goes to debug. The caller (stt_adapted_stream) reads session.failure.code and relays SESSION_ERROR_CODES, which already include CODE_FAILED. The new test fails on base. The build-desktop voice-codex install gets the same if ! guard as the recognizer install. It is valid under set -euo pipefail and uses in-scope variables, and no later packaging step needs aiortc. Settings reports the missing extra through extra_importable(). The new limit tests match the _emit and CodexRpc._read semantics. Locale strings are updated consistently across all locales, and CI (including the i18n render gate and the desktop builds) is green.

Tier: 2, held for a person: reviewer-finding: Design Review.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit d14e14e10b · 251 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 20, 2026 00:07

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The review checked this head and approves it. A non-CodexError raised during start() now maps to stt_codex_failed, and the dashboard already maps that code to "try recording again". Real Codex refusals (the version gate and JSON-RPC errors) still arrive as CodexError and pass through unchanged. The if ! guard in build-desktop.sh is safe under set -euo pipefail, the default recogniser keeps its exit 1, and a bundle without the extra still reports stt_codex_extra_missing. All 11 translated locales keep {{productName}} and the literal commands. The new test fails when the codex.py hunk is reverted, and the packaging.test.js pin fails when the build guard is reverted. The tests are deterministic.

Done well: the new warning logs only the exception type and keeps the traceback at debug level, so reply text stays out of the logs.

  • Optional: the comment at src/kiro_crew/stt/codex.py:290 says a retry can clear "a malformed reply". A reply shape mismatch from an incompatible Codex build, or a native PyAV library that fails to load, will fail again on every retry. Consider rewording the comment, or mapping those cases to a non-retryable code.
  • Optional: test/test_codex_stt.py:408 checks only getMessage(). Adding exc_info=True to the warning would still pass. Also asserting r.exc_info is None for WARNING records would pin the privacy half.
  • Optional: a release build can now drop Codex dictation and record it only as a log line. Printing that line in the release job summary would make the loss visible.

@KiroCrewCaptain
KiroCrewCaptain merged commit 02f20fd into main Nov 20, 2026
103 of 107 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the pearcekieser/codex-stt-followups branch November 20, 2026 00:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex dictation follow-ups from #26076

2 participants