Skip to content

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

Merged
bolichen97 merged 2 commits into
mainfrom
fix/stt-polish-error-lifetime
Oct 3, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/stt-polish-error-lifetime

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #12701 by @leonlaiyc

Problem / Motivation

Goal: Scope the transcript-cleanup (stt.polish) failure notice to the delivery it describes, so a stale notice no longer blanks the next recording's live dictation panel.

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

Why it matters

That channel is also a gate. ChatInput's showDictation blanks the live dictation panel whenever voiceError is set, on the 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 fail: the notice survives a later successful cleanup, survives into the next capture, and follows the user into a slot that never dictated.

Not a goal

  • Changing how stt.polish runs, or when a cleanup pass is attempted.
  • Moving polishError off the shared dismissible channel or giving useVoiceInput a new setter.
  • Altering the microphone-error path or the showDictation gate's premise.

What changed

The fix declares polishError beside composerEpochRef and clears it 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, and a slot change. The last three are the epoch's own list; 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 an object with no polish key, so a refetch turned the feature off partway through any test that delivered twice — pinned with staleTime: Infinity.

Tests

  • website/src/chat-core/composer/useComposerVoicePolish.test.tsx — 13 tests pass locally. Four observables, each failing without its line of the fix: the notice survives a later successful cleanup; survives into the next capture; follows the user into a slot that never dictated; and the send pins it.
  • tsc --noEmit: 0 errors. eslint on touched files: clean.

Pattern harvest

Rule candidate: review-prompt
Pattern: state merged into a shared error/UI channel without being cleared on that channel's own lifecycle resets, so a stale value from one producer gates the UI for the next.

A piece of state that joins a shared channel must also join that channel's lifetime — declare it where the channel's resets live (here, beside composerEpochRef), not beside the request that raises it. The channel here doubles as a UI gate (showDictation), carrying an implicit "an error here means the microphone" contract, so state entering it must either honor that contract or clear when it stops being true. Related test-only trap: a fixture that seeds a cache AND mocks a module must agree on shape, or a mid-test refetch silently flips a feature flag.

Original author: @leonlaiyc (#12701)

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>

Co-authored-by: leonlaiyc <276034861+leonlaiyc@users.noreply.github.com>
@iamwhatever
iamwhatever requested a review from a team October 1, 2026 14:04
@iamwhatever
iamwhatever requested a review from a team as a code owner October 1, 2026 14:04
@iamwhatever
iamwhatever requested a review from bolichen97 October 1, 2026 14:04
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 19e8a708ba7d645ecfcc08cee58366ae0d18eea2 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the "What changed" section covers the late-rejection .catch guard — the HEAD commit ships it, the description still describes only the four clears.

Not justified as shipped

  • Item 5 — undeclared: the owner/epoch/capture-generation guard in .catch (and capture in .then) is in the diff and the spec, but the description's "What changed" and "Tests" name only the four clears and "Four observables". It is inside the frozen Goal (a late rejection re-blanks the next recording's waveform) and its premise checks out (_POLISH_TIMEOUT_SECS = 12.0, handlers/core.py:1334); nothing more.

What this change ships

Inventory (7 items) — 6 justified

Intent: stop a stale transcript-cleanup failure notice from outliving the delivery it describes and blanking the next recording's dictation panel — a FIX.

Note: the patch artifact carries ~240 files of base-side drift (hunks match main's merged #15925, #15920, #15902 et al.); the PR's own change is useComposerVoice.ts, its test, and stt-streaming.md, inventoried below. Premises verified in the checkout: the shared channel has exactly 2 producers (voice.error ?? polishError, useComposerVoice.ts:1051 — no unfixed siblings) and the gate is real (showDictation requires !voiceError, chat-input/voice.ts:101).

  1. A failed-cleanup notice now clears when the next recording starts — justified
  2. The notice clears when a later dictation lands — justified
  3. The notice clears when the draft is sent — justified
  4. The notice no longer follows the user into a slot that never dictated — justified
  5. A polish failure settling late (after a capture, send, or slot change) can no longer resurrect the notice — undeclared: absent from "What changed"
  6. Polish tests pin the seeded STT config for the whole test (staleTime: Infinity) — justified
  7. The STT spec pins a fifth property, the notice's lifetime — justified

[FIRST-PRINCIPLES-REVIEWED] 19e8a70

Description read

[DESCRIPTION-READ] 218ccd99a5765df70ea5710e0643661de3ff2c0b4e4d1a6d3281ce3a0895b529

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

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 19e8a708ba7d645ecfcc08cee58366ae0d18eea2 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 19e8a70

Description read

[DESCRIPTION-READ] 9481114d360db18a499871510b06cc903114d9728a81a809d7e858db0a974198

That sha256 names everything this verdict read: the PR description, plus the 9 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

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 19e8a708ba7d645ecfcc08cee58366ae0d18eea2 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 19e8a70

Description read

[DESCRIPTION-READ] ac4952f584a12f192e6692166407ced6b2eecbc0ea6c435aefc96f7c41128a65

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

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 19e8a708ba7d645ecfcc08cee58366ae0d18eea2 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 19e8a70

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 19e8a708ba7d645ecfcc08cee58366ae0d18eea2: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

Nothing blocks; one advisory: the new notice-clear in disarmForSend also fires on the optionText send that deliberately leaves the dictated draft in place.

FINDING — website/src/chat-core/composer/useComposerVoice.ts:976 — setPolishError(null) runs under the comment "The composer is empty after this", but ChatPane.doSend/ChatPage.send call disarmForSend() unconditionally before their if (!optionText) clear, so a follow-up chip direct-send dismisses the failed-cleanup notice while the unpolished dictated draft is still sitting in the composer (and the pre-existing epoch bump already suppresses the late rejection), leaving the user never told the cleanup failed → Fix: carry the "this send consumes the composer" condition into the clear (e.g. disarmForSend(consumesComposer: boolean) passed !optionText at the two call sites) so only a send that empties the composer drops the notice — note the call sites are in files this PR does not touch.

[OPUS-REVIEWED] 19e8a70

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 19e8a708ba7d645ecfcc08cee58366ae0d18eea2: <one-sentence reason>

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

@buluoray buluoray left a comment

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.

Review at fc0e1e7a5506d58d35f482e89af8c09904758e78 — requesting changes (one narrow gap, small fix)

The diagnosis is right and the four clears do what they say. I checked the premise in source: voiceError: voice.error ?? polishError (useComposerVoice.ts:1036), and showDictation = … && !voiceError && … (components/chat-input/voice.ts:101-102). So a cleanup notice that stays up does blank the panel for the next recording.

Verified

  • useComposerVoicePolish.test.tsx passes at head: 13/13.
  • I removed each clear one at a time. Each one's removal fails exactly one named test:
    • slot-change clear (:147) → does not follow the user into another slot
    • delivery clear (:441) → stops reporting a failed cleanup once a later dictation lands cleanly
    • capture clear (:692) → does not carry a failed cleanup into the next capture
    • send clear (:961) → does not outlive the draft it describes, once that draft is sent
  • The staleTime: Infinity pin is needed. The api/client mock's sttConfig resolves an object with no polish key.
  • The spec bullet is in the same commit, as AGENTS.md requires.

Blocking: a late rejection brings the notice back after every clear

polishDictation's .catch(() => setPolishError(...)) (useComposerVoice.ts:363-365) has none of the guards its own .then checks. Say a sttPolish request is still in flight when the user starts a new capture, sends, or switches slots. The server allows up to _POLISH_TIMEOUT_SECS = 12.0, and a transport drop or gateway restart rejects the request after the clear has already run. The notice comes back for a delivery that no longer exists. In the capture case it blanks the waveform for a working microphone, which is the bug this PR fixes.

I reproduced all three orderings at head with a pending promise that rejects after the lifecycle event: capture, send and slot each end with voiceError truthy (3/3 red).

This blocks because the new spec property says the notice lives "as long as the delivery it describes, and no longer". At this head that statement is false, and it would land in main.

Suggested fix (I checked it locally: 16/16 green, including the three race probes)

const owner = sessionIdRef.current
const epoch = composerEpochRef.current
const capture = startGenRef.current
void api.sttPolish(raw)
  .then(/* unchanged */)
  .catch(() => {
    if (sessionIdRef.current !== owner || composerEpochRef.current !== epoch || startGenRef.current !== capture) return
    setPolishError(i18nT('hooks.useVoiceInput.polish_failed'))
  })

The owner/epoch guard on its own (the bots' suggestion) does not cover the new-capture case. startVoice() does not bump composerEpochRef, so the guard also has to check the capture generation (startGenRef). Please add a test where the rejection settles after startVoice / disarmForSend / switchSlot. All four current tests let the rejection settle before the lifecycle event.

Bot dispositions

  • Design (CONCERNS) and Opus (FINDING, :363): checked and reproduced. This is the blocking item above. Their proposed guard is incomplete for the capture path, as noted.
  • First Principles PASS, UX PASS, GPT no findings: agree. Nothing further.

Non-blocking

  • The design bot's {epoch, message} idea is a reasonable follow-up. It would make future epoch bumps clear the notice without someone having to remember the call. It doesn't need to be in this PR.

chenmingwei23
chenmingwei23 previously approved these changes Oct 1, 2026
Clearing `polishError` at the four lifecycle moments is not enough on its
own. `polishDictation`'s request can still be in flight across any of them:
the server allows up to `_POLISH_TIMEOUT_SECS`, and a transport drop or a
gateway restart can reject it after the clear has already run. The `.catch`
then re-raises the notice for a delivery that no longer exists -- and in the
new-capture case blanks the live waveform of a microphone that works, the
exact bug this PR fixes.

The `.then` already snapshots owner + epoch and bails when either moved on;
the `.catch` had none of those guards. It now carries the same snapshot, plus
the capture generation (`startGenRef`): `startVoice()` clears the notice and
bumps the capture generation but does NOT bump `composerEpochRef`, so an
owner/epoch pair alone cannot tell a reply the finished capture owns from one
the new capture would own.

Three race tests pin the three orderings, each settling the rejection AFTER
the lifecycle event (new capture, send, slot change). All three are red
without the guard and green with it; the file is 16/16.

The spec's fifth property is extended to state the late-rejection guard.
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray Thank you — this was a real gap, and your reproduction of the three orderings made it precise. Addressed at 19e8a708ba7d645ecfcc08cee58366ae0d18eea2.

Blocking: a late rejection brings the notice back after every clear
Fixed exactly as you described. polishDictation now snapshots the capture generation alongside owner/epoch when the request goes out (const capture = startGenRef.current), and the .catch applies all three guards before setPolishError:

const owner = sessionIdRef.current
const epoch = composerEpochRef.current
const capture = startGenRef.current
void api.sttPolish(raw)
  .then(/* unchanged */)
  .catch(() => {
    if (sessionIdRef.current !== owner) return
    if (composerEpochRef.current !== epoch) return
    if (startGenRef.current !== capture) return
    setPolishError(i18nT('hooks.useVoiceInput.polish_failed'))
  })

You were right that owner/epoch alone is incomplete for the new-capture path: startVoice() bumps startGenRef but not composerEpochRef, so the capture-generation check is what covers it.

Tests where the rejection settles after the lifecycle event
Added a new describe block, "a late rejection does not resurrect the notice", with the three orderings you asked for — the request is held pending, the lifecycle event fires, then the promise rejects:

  • a rejection that settles after the next capture leaves the fresh waveform alone (startVoice)
  • a rejection that settles after a send does not re-report the gone draft (disarmForSend)
  • a rejection that settles after a slot change does not follow the user (switchSlot)

I confirmed all three are red on the pre-fix source (3/3, matching your reproduction) and green with the guard. The file is 16/16. eslint and tsc -p tsconfig.app.json are both clean.

Spec
The fifth property in docs/system-specs/modules/stt-streaming.md now states the late-rejection guard explicitly — that clearing at the four moments is not sufficient on its own and the .catch carries the same owner/epoch/capture-generation snapshot — in the same commit.

Non-blocking — the design bot's {epoch, message} idea: agreed, left as a follow-up, not in this PR.

New head: 19e8a708ba7d645ecfcc08cee58366ae0d18eea2. Re-requesting your review.

@iamwhatever
iamwhatever requested a review from buluoray October 1, 2026 18:37
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 1, 2026

@buluoray buluoray left a comment

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.

Re-review at 19e8a708ba7d645ecfcc08cee58366ae0d18eea2: approving

The blocking item from my last review is fixed. The .catch now checks owner, epoch and capture generation (useComposerVoice.ts:376-378). startGenRef is only bumped in startVoice (:710), so the capture check cannot hide a rejection that belongs to the delivery on screen.

Verified at this head

  • useComposerVoicePolish.test.tsx: 16/16 pass.
  • I removed each .catch guard one at a time:
    • capture guard: a rejection that settles after the next capture leaves the fresh waveform alone goes red
    • epoch guard: a rejection that settles after a send does not re-report the gone draft goes red
    • owner guard: nothing goes red, because a slot change also bumps the epoch. With owner and epoch both removed, a rejection that settles after a slot change does not follow the user goes red too. So the slot test is real, and the owner check is defense in depth, the same as in .then.
  • The spec's fifth property in stt-streaming.md describes the late-rejection guard and is in the same commit.
  • CI: 86 success, 8 skipped, 0 failures. All five bot lanes pass on this SHA.

Non-blocking follow-up (Opus advisory, checked)
The new setPolishError(null) in disarmForSend (:976) also runs on an optionText send. ChatPane.doSend (ChatPane.tsx:1021) and ChatPage.send (ChatPage.tsx:2695) call disarmForSend() before their if (!optionText) branch, so a follow-up-chip send hides the cleanup-failed notice while the unpolished draft stays in the composer. The draft is still correct and sendable, so this does not gate. Passing a consumesComposer flag into disarmForSend would fix it, but that touches call sites this PR does not change.

@iamwhatever
iamwhatever added this pull request to the merge queue Oct 2, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Oct 2, 2026
@iamwhatever
iamwhatever added this pull request to the merge queue Oct 2, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 3, 2026 01:30
@bolichen97
bolichen97 merged commit 6ecfbbe into main Oct 3, 2026
103 checks passed
@bolichen97
bolichen97 deleted the fix/stt-polish-error-lifetime branch October 3, 2026 01:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 3, 2026
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.

6 participants