Skip to content

fix(stt): scope the transcript-cleanup notice to its own delivery - #12701

Closed
leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/polish-error-capture-lifetime
Closed

leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/polish-error-capture-lifetime

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

With stt.polish on, a failed transcript-cleanup pass raises a notice that never
goes away on its own. Three things a user can do reproduce it:

  • Dictate again. Utterance 1's cleanup fails; utterance 2's cleanup runs and
    succeeds; the composer still reads "AI cleanup didn't run. Your transcript is
    unchanged."
  • Start the next recording. The notice is still up while the new capture runs.
  • Switch chat slots. The notice follows the user into a slot that never
    dictated anything.

The second one is the expensive one, because that channel is not only a notice.
ChatInput's showDictation gate is
dictationUsable && voiceRecording && !voiceError && voiceSampleRef
(ChatInput.tsx:1406),
and its own comment states the premise: "A mic error always falls through to
VoiceStatusBar, which owns the dismissible error affordance — the panel has no
way to surface it."
A cleanup that did not run says nothing about the
microphone, so a stale cleanup notice blanks the live dictation panel for the
whole of the next recording, on a microphone that is working.

Why it matters

Dictation is used by people who are not reading the screen while they speak; the
waveform is the one thing that tells them the microphone is live. Losing it for
an entire utterance, because of a failure in an optional cosmetic pass that
already completed, is the opposite of what the notice was added for. And a notice
that reports a failure for a cleanup that succeeded trains the user to ignore the
channel the microphone's real errors arrive on.

What changed (motivation → approach → change)

Symptom → cause. polishError (#12444) is merged into the composer's
existing error channel at the boundary:
voiceError: voice.error ?? polishError. That channel already had a lifetime —
useVoiceInput.start() does setError(null) before every capture, so the
composer's error has only ever described the capture on screen. polishError
joined the channel without joining the lifetime: nothing cleared it but a user
dismissal.

Change. Give it the lifetime the channel already has. polishError is
declared beside composerEpochRef — the hook's existing name for "which delivery
this is" — and cleared at the four moments the delivery it describes stops being
the one in front of the user:

site why
startVoice pairs with voice.start()'s own setError(null)
applyVoiceText a new delivery is about to get its own answer
disarmForSend the composer is empty; the notice has nothing to point at
slot change (render) the new slot never dictated

The last three are the epoch's own list, already written down in its doc comment
("Advanced on a SEND and on a SLOT CHANGE … and on each new delivery"); this
change only makes the notice obey the same list. The slot-change clear is a
setState during the render that observed the prop change — React's documented
pattern — placed there rather than in an effect for the same reason the epoch
bump already is: it must land before a reply can be applied in the new slot's
render.

Nothing else moves: the request, the span check, the three ownership guards and
the dismiss path are untouched.

One thing read rather than measured, stated plainly: the dictation-panel
consequence is established by reading showDictation at ChatInput.tsx:1406 and
its stated premise. What the tests measure is the value that gate consumes —
composerVoiceInputProps(cv).voiceError — which is also the value
VoiceStatusBar renders. No frame of the panel was captured.

Backwards compatibility

Compatible. Nothing is rejected, renamed or removed: polishError and
clearVoiceError keep their names, types and export shape, the manual dismiss
still clears both halves, and the only behaviour change is that a notice which
previously outlived its delivery now ends with it.

Tests

website/src/chat-core/composer/useComposerVoicePolish.test.tsx, four new cases
in one describe block. Each asserts on
composerVoiceInputProps(view.result.current).voiceError — the exact value both
consumers read — and each has a truthy precondition assertion first, so a test
that stopped raising the notice at all would not pass vacuously:

  • stops reporting a failed cleanup once a later dictation lands cleanly
  • does not outlive the draft it describes, once that draft is sent
  • does not follow the user into another slot
  • does not carry a failed cleanup into the next capture

RED before / GREEN after. On 0f5cc7b87 the four fail and the nine existing
polish tests pass; with the fix, 13/13.

Mutation-verified, one line at a time. Removing each of the four
setPolishError(null) calls individually makes exactly one test fail and the
other twelve pass — so no clear in this diff is decoration:

never dictated (slot change)  -> Tests 1 failed | 12 passed (13)
on top of it   (delivery)     -> Tests 1 failed | 12 passed (13)
nothing left   (send)         -> Tests 1 failed | 12 passed (13)
microphone     (capture)      -> Tests 1 failed | 12 passed (13)

One harness repair was needed to write the first test, and it is worth
flagging.
mount() seeded sttConfig into the query cache, but the module
mock's api.sttConfig resolves a different object with no polish key, so the
first refetch turned the feature under test off. Every existing test delivers
once and settles before that lands, which is why it was invisible; a test that
delivers twice silently stops exercising polish on the second delivery. Pinned
with staleTime: Infinity, which is what those tests already assume.

Adjacent, all green on this branch: npx tsc --noEmit (0), eslint on both
changed files (0), npm run jscpd (0), scripts/docs-lint.sh (0),
src/chat-core/composer + the three useVoiceInput suites (46/46), and
src/test/ChatInput* (556/556).

Manual verification

N/A — unit coverage sufficient. The four cases assert at
composerVoiceInputProps(...).voiceError, which is the single value both the
notice (VoiceStatusBar) and the dictation-panel gate read, so a manual pass
would observe the same value one render later.

Related Issues

None. The surface arrived with #12444 (perf(stt): report the real speech backend…), merged 2026-09-21; this is a follow-up on its composer half.

Pattern harvest

Rule candidate: review-prompt

Pattern: a value merged into an existing UI channel (existing ?? new) must
adopt that channel's reset points, and every consumer that gated on the original
now gates on both.
The merge here was deliberate and documented — "Both travel
the same dismissible channel" — but a shared channel is a shared contract in two
directions: the lifetime the old value had, and the meaning every reader already
attached to it. showDictation reads "error set" as "the microphone", which was
true for every value that channel could carry until one more was added.

Checkable by a reviewer in two greps, not mechanically lintable: for the new
value, find every site that clears the original; for the channel, find every
consumer that branches on it.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — docs/system-specs/modules/stt-streaming.md gains the notice's lifetime as a fifth pinned property of the polish feature
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

A failed `stt.polish` pass is surfaced on the composer's dismissible error
channel, which it SHARES with the microphone's error from `useVoiceInput`
(`voiceError: voice.error ?? polishError`). It joined that channel without
joining its lifetime: `useVoiceInput.start()` clears its half before every
capture, and nothing ever cleared `polishError` but a user dismissal.

That channel is not only a notice. `ChatInput`'s `showDictation` gate blanks
the live dictation panel whenever `voiceError` is set, on the stated premise
that an error there means the microphone. A cleanup failure says nothing
about the microphone, so a notice left standing takes the waveform down for
the whole of the NEXT recording, whose microphone is fine.

Three user-reachable observables, each now a test that fails without its own
line of the fix: the notice survives a later dictation whose cleanup ran and
succeeded; it survives into the next capture; and it follows the user into a
slot that never dictated. A fourth pins the send.

`polishError` is therefore declared beside `composerEpochRef` and cleared at
the four moments the delivery it describes stops being the one in front of
the user -- a new capture, a new delivery, a send, a slot change. The last
three are the epoch's own list, already written down there; the first is the
capture start the engine already resets on.

The test harness seeded `sttConfig` into the query cache while the module
mock resolved a different object with no `polish` key, so a refetch turned
the feature off partway through any test that delivered twice. Pinned with
`staleTime: Infinity`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and chenmingwei23 September 22, 2026 03:24
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 22, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this fix, @leonlaiyc — the diagnosis (polishError sharing the composer's dismissible error channel without sharing its lifetime, so a stale cleanup notice blanks the next recording's dictation panel via showDictation) is exactly right, and the four epoch-reset clears are the correct scope.

To get it through the in-repo CI and review lanes (fork PRs can't run the full adjudicating pipeline), I've opened an in-repo replacement that cherry-picks your commit verbatim onto fresh main, with you credited as author and co-author: #15889. It's fully green there. Closing this one in favor of that. Credit for the fix is yours.

@iamwhatever iamwhatever closed this Oct 1, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants