Repository navigation
fix(stt): report local Codex start faults as retryable and clarify Codex setup copy - #39597
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of 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
[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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The start-fault fix reuses the existing What this change shipsInventory (6 items) — 6 justifiedIntent: 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.
[FIRST-PRINCIPLES-REVIEWED] d14e14e Description read[DESCRIPTION-READ] fbff6c369a0969f069dd9233abc4fa2628d9a7605897c0b3fb85ab30bfaf17b2 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of 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
[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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: A person should decideWhy: 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 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 |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
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(). Addingexc_info=Trueto the warning would still pass. Also assertingr.exc_info is Nonefor 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.
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:
CodexError(a fault in the media stack, the peer connection or a malformed reply) is reported asstt_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.packaging/build-desktop.shinstalls thevoice-codexextra with no guard. On a target with no prebuilt aiortc or PyAV wheel, the whole desktop build fails.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
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.
src/kiro_crew/stt/codex.pyStreamingSession.startpasses aCodexErrorthrough unchanged. Any other exception becomesstt_codex_failed.website/src/lib/sttProviders.tsmaps 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.packaging/build-desktop.shvoice-codexinstall has the sameif !guard as the recognizer install. If it fails, the build logs one line and the bundle ships without Codex dictation. Settings then reportsstt_codex_extra_missing.docs/system-specs/modules/stt-streaming.mdsays the same.website/src/i18nen.manual.jsonand the 11 translated locales, anden-XA.jsonis regenerated. The next table has the English.unavailable_codex_missingunavailable_codex_extraunavailable_codex_loginretention_codexThe 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_failedandstt_codex_voice_unavailableboth exist on main, in the metrics schema and inwebsite/src/lib/sttProviders.ts. A Codex refusal still returnsstt_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_a_local_start_fault_is_a_retryable_failure_with_its_type_loggedRuntimeErrorfrom the media stack during start returnsstt_codex_failed. Thecodexlogger 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_acceptedtest_transcript_text_cap_admits_exactly_its_limit_MAX_TEXT_CHARSis kept, and one more character raises.test_transcript_item_cap_admits_exactly_its_limit_MAX_ITEMSitems are kept, and one more raises.test_session_event_queue_holds_its_limit_then_reports_falling_behind_MAX_EVENTSevents. The next event setsstt_codex_failed. The oldest event makes room for the error, which is delivered last.test_rpc_event_queue_holds_its_limitcodex_rpc._MAX_EVENTSevents with no failure.test_rpc_event_queue_overflow_is_a_transport_failurestt_codex_failedand queuesTRANSPORT_FAILED.website/electron/test/packaging.test.jsvoice-codexinstall is insideif ! ...; then log ...; fiwith noexit 1.The seven new backend tests ran 20 times at
-n0and 10 times at-n 4next totest/test_codex_media.pyandtest/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.pyandtest/test_host_git_repo_exec_neutralization.py::TestCloudSourceTarball. On this host/is owned by uid 65534, andsrc/kiro_crew/cloud/source.pyrefuses an ancestor that neither the user nor root owns. The last one istest/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/diston loopback and answered every/apicall from stubs, so no gateway ran.GET /api/stt/statusreturned 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:
Codex not installed, signed out, and the 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_FAILEDSibling: 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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commitsFixes #39596