Skip to content

feat(stt): make the local recogniser decode thread count configurable - #19648

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/stt-thread-count
Oct 21, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/stt-thread-count

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: let an operator choose how many CPU threads the local speech-to-text recogniser decodes with, so a large host can transcribe faster.

The recogniser derives its thread count from THREAD_CEILING = 16 in src/kiro_crew/stt/engine.py: half the usable cores, never more than 16. Nothing lets an operator change that. On a 128-core host, large-v3-turbo decodes the 11 s JFK sample in 3.7 to 4.2 s at 16 threads, 2.0 s at 32, 1.6 s at 48, 1.25 s at 64 and 1.1 s at 96.

Why it matters

Dictation latency is the time between stopping speech and seeing text. On a large host the fixed cap leaves most of that latency on the table: a 64-thread decode is about 2.6 times faster than the default on the host above, measured under load.

Not a goal

  • No change to the default. Unset or auto keeps half the cores capped at 16, because the ceiling exists for small hosts where wide pools varied badly under load.
  • No automatic tuning or benchmarking of the host.
  • No thread setting for any cloud transcription provider.

What changed (motivation → approach → change)

The count is a host property the operator can measure and the code cannot, so it becomes a setting with the current rule as its default.

  • stt.threads is a new integer setting. 0, or "auto" on write, keeps today's rule. A count from 1 to 1024 is used as given and clamped at model load to the cores the process may run on. An explicit count is not capped at 16: the ceiling bounds a guess on hosts nobody measured, and an operator who sets a count has measured theirs. The 1024 bound only stops a typo like 6400 from being stored.
  • KIROCREW_STT_THREADS outranks the setting for one process, the same way other KIROCREW_* variables outrank their settings. It is read from the environment of the process that loads the model, which today is always the gateway: dictation, Slack and messaging attachments, and the meetings audio import all decode there. A value that does not parse is logged once per process and ignored, and the setting applies.
  • The count is part of the engine's LoadedKey. A change through Settings or kirocrew config set takes effect at the next dictation with one model reload, so the setting is not restart_required. Changing the env var needs a process restart, like any env var.
  • Settings > Voice > Fine-tuning gains a Decode threads picker. It offers Auto plus only the counts this machine can run. The Auto option shows the count it resolves to on this host, for example "Auto (16)", from a threads_auto field the config GET computes from the CPU affinity count without importing the engine. The hint says a change reloads the model once at the next dictation. When KIROCREW_STT_THREADS overrides the setting, the picker is disabled and a note gives the count in effect first: "This gateway uses 64 threads, set by KIROCREW_STT_THREADS." It mentions the variable only when its value parses, because an unparseable value does not override anything.
  • kirocrew config set stt.threads auto|<n> writes the setting. Validation refuses junk on write. A bad value hand-edited into config.json loads as auto with a warning.
  • Docs, the generated settings registry, the GUI feature list and all 12 locales are updated.

Backwards compatibility

Compatible: the new key defaults to 0, which resolves exactly as the current code does, and no existing key, validator or caller changes shape.

Removes nothing: the change only adds a setting, an env var and a picker.

Tests

  • test/test_stt_threads.py, 48 cases: auto on small and large hosts, an explicit count, clamping to the usable cores, rejected spellings, env precedence over the setting, a bad env value falling back to the setting and logging once, LoadedKey changing with the count, config load and validation, and the CLI auto spelling.
  • website/src/test/SttSettings.threads.test.tsx, 6 cases: the picker stays behind the Fine-tuning disclosure, offers the served choices with 0 labelled "Auto (16)" and saves a number, labels Auto alone when threads_auto is missing, names the env override and disables the picker when the gateway reports one, stays enabled without an override, and is absent for a provider that does not run the local model.
  • test/test_dashboard_handlers_core_coverage.py: the config GET and PUT round trip threads, reject bad values, report the env override only when it parses, including KIROCREW_STT_THREADS=lots, and report threads_auto as half the cores capped at 16 on 1, 20 and 128 cores.
  • test/test_stt_boot_prewarm.py, test/test_stt_session.py and test/test_stt_endpointing.py: their fake engines gain the new method.

Locally, the related backend set passed 30,145 tests in its first batch, and the i18n suite (768) and settings registry tests (394) pass. The 25 tests that failed locally fail the same way on a clean checkout of main at 38eb463. isort, flake8, mypy, tsc, semgrep, the flake ratchet and npm run i18n:check are clean.

Manual verification

Run on an isolated dev gateway with its own data home on a 128-core host:

  • KIROCREW_STT_THREADS=64 set: the engine loaded with 64 threads.
  • No env var, 64 saved through the Settings API: 64.
  • Set back to auto: 16.

JFK benchmark, large-v3-turbo, 11 s clip, run in-process against the real engine while the host load average was between 124 and 140:

Threads Decode time, three runs (s)
auto (16) 3.70, 3.76, 3.71
64 1.40, 1.42, 1.42

Screenshots / video

Settings > Voice > Fine-tuning, rendered from the built SPA with fixture data for a 128-core host.

Auto, the default, labelled with the count it resolves to:

Decode threads picker reading Auto (16)

64 selected:

Decode threads picker set to 64

KIROCREW_STT_THREADS set to 64 with 16 saved, with the picker disabled and the override note ("This gateway uses 64 threads, set by KIROCREW_STT_THREADS. Remove that variable to use this choice."):

Decode threads picker with the env override note

Related Issues

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|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)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

Fixes #19647

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners October 13, 2026 01:43
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of f9c48741822315f3c073ceba843880ece51e5d0a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] f9c4874

Description read

[DESCRIPTION-READ] 815de78777945244f1ea6b85dd132d2572b9063b02e493d28c6f2a78c6edce0b

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 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of f9c48741822315f3c073ceba843880ece51e5d0a via the fork AI-review pipeline — 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: CONCERNS

KIROCREW_STT_THREADS gives the same knob a second spelling, and its only stated reason is symmetry with other variables. The setting already does the job live, without a restart.

Not justified as shipped

  • Item 2 — inherited (symmetry): "outranks the setting for one process, the same way other KIROCREW_* variables outrank their settings". The description names no person the stt.threads setting fails. It already takes effect at the next dictation, while the variable needs a restart. Shipping the variable also brings in threads_env on the config GET, a disabled-picker state, an override note in 12 locales, and the _warned_thread_env global.
    Subtraction: delete THREADS_ENV, the environ parameter and the warn-once set in engine.thread_count, _stt_threads_env, threads_env, and the override note and its locale keys.
    Clears when: a linked issue or the description names an operator who cannot use stt.threads and needs a per-process override.
  • Item 6 — inherited: the "auto" string is a second spelling of 0. No other setting accepts it this way: I grepped "auto" in config/validation.py and found 0 matches. It is the only reason for the validation.py pre-coercion hunk. The picker already saves numbers.
    Subtraction: accept integers only (0 = auto). Delete the "auto" branch of parse_threads and the validation.py hunk.
    Clears when: the spelling is removed, or a reported case shows an operator needs auto on write.

What this change ships

Inventory (8 items) — 6 justified

Intent: let an operator on a large host use more CPU threads for local dictation so it finishes sooner. This is an ADDITION.

  1. New stt.threads setting; default 0 keeps today's half-the-cores-capped-at-16 rule — justified
  2. KIROCREW_STT_THREADS env var overrides the setting; the picker is disabled and a note explains — inherited (symmetry with other env vars)
  3. Settings > Voice > Fine-tuning gains a Decode threads picker sized to this host's cores — justified
  4. Auto option shows the count it resolves to, e.g. "Auto (16)" — justified
  5. kirocrew config set stt.threads refuses junk on write — justified
  6. "auto" is accepted as a written value in the config file, the CLI, the API and the env var — inherited
  7. A changed count reloads the model at the next dictation, no restart — justified
  8. THREAD_CEILING moved from stt/engine.py to stt/limits.py so the config read never imports numpy — justified

[FIRST-PRINCIPLES-REVIEWED] f9c4874

Description read

[DESCRIPTION-READ] 432633c3394e9814b54c000b712de133f3f11e2051b93c314f46d198723500a2

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 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — 🟡 CONCERNS

UX-level review of f9c48741822315f3c073ceba843880ece51e5d0a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The disabled picker shows "16" while the note under it says 64 threads are running, so the screen shows two numbers for one setting.

Watch

  • The override state shows two numbers. In attachment-03 the disabled picker reads "16" and the note under it reads "This gateway uses 64 threads". The cause is value={String(stt.threads ?? 0)}: it still shows the saved value while threads_env overrides it. Someone who skims sees "16" in the main control and may think 16 is what runs. This only happens to people who set the env var, but it can mislead them every time they open the page. Smallest fix: when threads_env is set, show the effective count in the disabled picker, or add "Saved: 16" to the note so the two numbers are clearly different things.
  • No first-time reader has seen these screenshots. The screenshots show the Decode threads picker in all three states (Auto (16), 64, env override). But this lane has no blind read, so nobody has checked whether "Decode threads" and the override note make sense to a newcomer. A maintainer can get that read by pushing the branch to this repository.

Suggestions

  • decode_threads_env_override: "Remove that variable to use this choice" → "Remove that variable and restart the gateway to use this choice." The docs say a change to the env var needs a restart, but the note doesn't mention it.

[UX-REVIEWED] f9c4874

Description read

[DESCRIPTION-READ] 8f10c2e080012c66417b18b6cf1016513233267b046fa0e7bfeecdf0856880d1

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed f9c48741822315f3c073ceba843880ece51e5d0a via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f9c4874

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed f9c48741822315f3c073ceba843880ece51e5d0a via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f9c4874

@Pearcekieser
Pearcekieser force-pushed the feat/stt-thread-count branch from f7765d3 to 27ee908 Compare October 13, 2026 02:15
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 365d87c and regenerated the find_ui index with npm run gen:ui, which fixes the stale-index failure in Frontend Lint & Type Check. No behaviour change. The earlier Publish readiness signal failure was a CI-app rate limit (HTTP 403 at 01:49Z), not a code finding.

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 13, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/stt-thread-count branch from 27ee908 to 126d385 Compare October 13, 2026 02:28
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

issue (blocking, security): oversized digit strings crash config loading.

Fixed in 126d385. parse_threads now refuses an ASCII digit string with more digits than MAX_THREADS has, after stripping leading zeros, before it calls int(). A 5,000-digit stt.threads in config.json therefore loads as auto with a warning, and the CLI and dashboard refuse the write. New test cases cover a 5,000-digit value in the parser, the config loader and kirocrew config set, and check that 0048 still reads as 48.

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/stt-thread-count branch from 126d385 to eeeadd7 Compare October 13, 2026 02:43
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 7ca644d. The only conflict was the generated find_ui index, which I regenerated with npm run gen:ui. No behaviour change; the oversized-digit fix from 126d385 is unchanged.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 13, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does 126d385ffa556a1efb6f56f8b2d8fcce75ef1391 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

no leg reported, and this was not the nothing-to-adjudicate short circuit

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

mechanism: LocalSession and transcribe_pcm now default threads to None, the same "no opinion" value shared_engine and prewarm use.

Fixed in c6b0df3b01. suggestion (non-blocking): a caller that leaves threads out of LocalSession or transcribe_pcm no longer resets a saved count to auto. A new test builds LocalSession() after shared_engine(threads=48) and checks the engine still reports 48.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Kept. thought (non-blocking): the variable was a stated requirement of the issue, not symmetry alone. The operator who asked for this runs a 128-core host and wants a count for one gateway process without editing a config.json that other processes on the same home read; a dev pod or benchmark run also needs a count different from the saved setting without writing to it. The variable is read when a model loads, so the gateway and each speech MCP server honour their own environment, which config.json cannot express per process. A value that does not parse is logged once and ignored, and the panel only names the variable when it parses.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Kept. thought (non-blocking): the issue asked for "auto" as the spelling of the default, and it is the word the Settings picker, kirocrew config set and KIROCREW_STT_THREADS=auto show and accept. Without it, a user who reads "Auto" in the picker and types auto into the CLI or the variable gets a refusal, and the only way to restore the default is to know that 0 means auto. The cost is one case-insensitive comparison in parse_threads, which every entry point already shares, plus the validation.py coercion so a hand-edited "auto" in config.json loads as 0 instead of being dropped with a type warning.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

mechanism: the override note now leads with the outcome and says how to undo it.

Fixed in c6b0df3b01. suggestion (non-blocking): the English note now reads "Ignored while KIROCREW_STT_THREADS sets {{value}} threads on this gateway. Remove that variable to use this choice." All 11 other locales are rewritten the same way, the pseudolocale is regenerated, and the 833 i18n and Settings tests plus npm run i18n:check pass.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Deferred. suggestion (non-blocking, if-minor): labelling the 0 option with its resolved count, such as "Auto (16)", is a good follow-up but changes the picker's option label in 12 locales and makes the label depend on a status fetch the picker does not wait on today. The ⓘ tooltip next to the picker already states the rule, half the cores up to 16, and every explicit option is a plain number, so a user can compare Auto with 64 from what is on screen. I would rather land that label change separately than widen this PR again.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

mechanism: parse_threads now strips leading zeros once and both the length check and int() read that stripped string.

Fixed in 9abd9ba. issue (blocking, security): the earlier guard measured text.lstrip("0") but converted the unstripped text, so 5,000 zeros followed by 64 passed the check and int() raised ValueError. The parser now converts the same digits it measured, so the longest string int() ever sees is four digits. Tests add "0" * 5000 + "64" -> 64 and "0" * 5000 -> 0 to the parser cases, a stored config value of "0" * 5000 + "64" loading as 64, and "0" * 5000 + "9" * 5000 loading as auto with a warning. All 819 speech tests pass.

@Pearcekieser
Pearcekieser force-pushed the feat/stt-thread-count branch from eeeadd7 to 9abd9ba Compare October 13, 2026 03:43
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 13, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore: Build Wheel, Build Desktop and both Build image jobs failed on 5e19fd6 at gen-ui-index. Main had renamed the generated settings field from description to hint, so this PR's stt.threads entry in settings-registry.generated.json and settingsRegistry.gen.ts no longer matched the live extraction. Head 33e0315 regenerates both with npm run gen:settings, a 2-line change. gen-ui-index --check and tsc -p tsconfig.app.json pass locally. It is still one commit with no behaviour change.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Pushed head 7812eb2, still one commit, rebased on current main. note (non-blocking): every review lane on 33e0315 failed before producing a verdict because the CI app ran out of API quota between 07:42Z and 07:46Z. Publish readiness signal, Fork Internal Content Scan and Screenshot Evidence logged "API rate limit exceeded for installation", Sensitive Change Review could not read the PR, and the GPT 6.1 and Opus 5.5 fork lanes reported "could not run". Dependency License Gate reports that dependency review is not enabled on the repository, which this PR does not change. Backend Lint & Type Check and Backend Tests shard 2 (Linux and Windows) failed on NameError: _github_outputs in test/test_ai_review_workflows.py, which came from main at the time and is fixed on current main. flake8 src/kiro_crew test conftest.py xdist_budget.py is clean on the new head.

chore: the new head also applies the Opus 5.5 advisory from 5e19fd6. The constants table in docs/system-specs/modules/stt-streaming.md now lists THREAD_CEILING under stt/limits.py and says it bounds only the auto count, matching resolve_thread_count. No code change. 329 targeted STT and dashboard core-coverage tests pass, and gen-ui-index --check is clean.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): CI on 7812eb2 has finished, and none of the five red checks touch the STT change. Could a maintainer rerun the failed jobs? The fork account cannot.

  1. E2E (stub ACP backend, offline) stopped at the 1020 s Playwright bound tracked in E2E fails at the 1020 s Playwright bound with every spec passing #18185. This is the fifth time on this PR, and test(e2e): re-measure the Playwright run ceiling against the current suite #19146 is the open fix.
  2. PR Scope was cancelled at its 15 minute job limit while still inside actions/checkout.
  3. Backend Tests (3.12, 8) failed on test_agent_scratch.py::TestGitTreesAreQuarantined::test_a_failed_move_keeps_the_tree_in_place_and_copies_nothing[13] with a FileNotFoundError under the pytest tmp dir. This PR does not touch that file.
  4. Backend Tests (Windows) (7) failed on two tests in test_app_mcp_tool_policy_scope.py, which covers app MCP tool policy and is outside this diff.
  5. Coverage Gate fails closed because backend-test failed. Frontend coverage and the other inputs passed.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main, no behaviour change. Head a7c3fa9 is still one commit, and range-diff against 7812eb2 shows the patch unchanged. 329 tests across the STT engine and session suites and the two dashboard core-coverage files pass, and flake8 and gen-ui-index --check are clean.

note (non-blocking): this push retriggers CI. The five reds on 7812eb2 were E2E (stub ACP backend, offline) at the 1020 s bound tracked in #18185, PR Scope cancelled during checkout, one case in test_agent_scratch.py on backend shard 8, two tests in test_app_mcp_tool_policy_scope.py on Windows shard 7, and Coverage Gate failing on those shards. None of those files is in this diff. The rerun ask from 09:22Z had no answer after 4 hours, and the fork account cannot rerun jobs.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main, no behaviour change. Head bc7256a is still one commit, and range-diff against a7c3fa9 shows the patch unchanged. 207 tests across test_stt_threads.py, the two dashboard core-coverage files and test_app_mcp_tool_policy_scope.py pass, and flake8 is clean.

note (non-blocking): the Windows shard 7 red on a7c3fa9 was test_app_mcp_tool_policy_scope.py failing on a cross-drive os.path.commonpath ValueError, a main bug fixed by #20802 (merged 17:16Z). The shard 4 red was two timing tests in test_crew_log_emit.py, which this diff does not touch.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 93617e9 to clear the merge conflict, no behaviour change. Head a0bfae9 is still one commit. #20555 split src/kiro_crew/transcribe.py into owner modules, so this PR's one added line, threads=stt_config.threads in the local recogniser call, now sits in src/kiro_crew/transcribe_local.py, where _transcribe_local moved. transcribe.py is main's copy unchanged. An earlier conflict in src/kiro_crew/docs/ui-index.generated.json was digests and counts only; I took main's copy, regenerated it, and gen-ui-index --check reports it up to date. 102 tests across test_stt_threads.py and the STT and transcribe suites pass, and flake8 is clean on the changed files.

note (non-blocking): the backend shard 6 red on bc7256a, on Linux and Windows, was test_the_lazy_imports_stay_inside_the_functions_that_need_them asserting 84 == 83. #19700 added a page_cache entry to the lazy-import table without raising the pinned count, and #20930 fixed that on main at 20:35Z. This diff does not touch that file. Coverage Gate failed only because that shard did. The E2E (stub ACP backend, offline) red was the 1020 s suite bound tracked in #18185, with 322 specs passed and 7 not run; this push gives it a fresh run.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

No code change. Head 2ef00e2 has the same tree as a0bfae9 and only a new commit date, to rerun CI. note (non-blocking): the one blocking readiness item on a0bfae9 was Backend Tests (Windows) shard 2. It failed on test_member_dashboard_package_route.py::test_the_gallery_pages_own_subscriber_receives_the_tree, where a node subprocess hit its timeout, and on test_md_notebook.py::test_a_sync_while_the_temp_is_still_staging_never_commits_it with an asyncio CancelledError. Neither file is in this diff. Every other check passed on that head, including E2E (stub ACP backend, offline), and the fork account cannot rerun a job.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 7e77836 to clear the merge conflict, no behaviour change. Head 48aa321 is still one commit.

#21129 split src/kiro_crew/config/sections.py into sections_* owner modules behind a facade. This PR's two additions there moved with the STT owner: _validated_stt_threads and the SttConfig.threads field now sit in src/kiro_crew/config/sections_stt.py, and the facade re-exports _validated_stt_threads next to the other STT validators. The facade also binds the three kiro_crew.stt.limits names the owner imports (_STT_MAX_THREADS, _STT_THREADS_AUTO, _parse_stt_threads), the same way it already binds _STT_DEFAULT_SILENCE_MS, so test/test_sections_facade.py's inventory gains those three names.

3491 tests across the sections facade and config contract suites, the STT and transcribe suites, the dashboard core-coverage files and the app MCP tool policy suite pass. flake8 is clean on the changed files, and gen:settings and gen-ui-index --check report nothing to regenerate.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 2245fd4 to clear the merge conflict, no behaviour change. Head 540e1c0 is still one commit. The only conflict was src/kiro_crew/docs/ui-index.generated.json, digests and counts only; I took main's copy and regenerated it with gen:settings and gen:ui, and gen-ui-index --check reports it up to date. 1265 tests across test_stt_threads.py, the sections facade suite, the STT and transcribe suites and the app MCP tool policy suite pass, and flake8 is clean on the changed files.

note (non-blocking): CI never ran on the previous head 48aa321. All 20 of its fork workflow runs stayed at action_required waiting for maintainer approval, so there were no check results on it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main ee95877 to clear the merge conflict, no behaviour change. Head ce4fb3e is still one commit. The only conflict was again src/kiro_crew/docs/ui-index.generated.json, digests and counts only; I took main's copy and regenerated it with gen:settings and gen:ui, and gen-ui-index --check reports it up to date. 1346 tests across test_stt_threads.py, the sections facade suite, the STT and transcribe suites and the app MCP tool policy suite pass, and flake8 is clean on the changed files.

note (non-blocking): CI has not run on this PR since 08:12Z on 10-16. The fork workflow runs on 48aa321 and 540e1c0 all stayed at action_required waiting for maintainer approval.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 85dcaee, no behaviour change. Head 3be2e7c is still one commit and rebased without conflicts. 1346 tests across test_stt_threads.py, the sections facade suite, the STT and transcribe suites and the app MCP tool policy suite pass, flake8 is clean on the changed files, and gen-ui-index --check reports the index up to date.

note (non-blocking): Real Adapter Contract Tests failed on ce4fb3e in test_codex_session_mcp.py::test_the_installed_adapter_still_builds_the_frames_the_refusal_reads, because the installed codex-acp no longer contains function createMcpRawInput(server, tool, argumentsValue). That run tested a merge base from before #15909 bumped codex-acp and #21581 re-measured the test on main. This diff does not touch test/real_adapters or that test, and this rebase picks up both commits.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 273a50b to clear the merge conflict, no behaviour change. Head 52f4009 is still one commit. The only conflict was again src/kiro_crew/docs/ui-index.generated.json, digests and counts only; I took main's copy and regenerated it with gen:settings and gen:ui, and gen-ui-index --check reports it up to date. 1347 tests across test_stt_threads.py, the sections facade suite, the STT and transcribe suites and the app MCP tool policy suite pass, and flake8 is clean on the changed files.

@iamwhatever iamwhatever 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.

Requesting changes at 52f4009. The r99 cold-import concern is fixed: _stt_threads_env now resolves through stt.limits and cpu_affinity and never imports the engine (

def _stt_threads_env() -> str | None:
"""The thread count ``KIROCREW_STT_THREADS`` makes the engine use, or ``None``.
``None`` both when the variable is unset and when it does not parse: the engine
ignores an unusable value, so reporting it would tell the panel an override is
in force when ``stt.threads`` is what actually runs. A value that parses is
reported as the count the engine resolves it to, not as typed, so ``auto``,
``0048`` or a count above this host's cores reads as the number that runs.
Resolved through :func:`kiro_crew.stt.limits.resolve_thread_count` and
:func:`kiro_crew.cpu_affinity.affinity_cpu_count`, both leaf modules that import
nothing heavy, rather than :func:`kiro_crew.stt.engine.thread_count`. The engine
module imports numpy at module scope, and this runs synchronously on the GET
``/api/config/stt`` path while the response dict is built; importing it here
would pay a cold multi-hundred-millisecond import on the event loop the first
time any gateway served that page. The resolution is pure arithmetic, so no
import of it is needed, and no path through this function can block the loop.
"""
raw = os.environ.get(STT_THREADS_ENV, "").strip()
parsed = parse_stt_threads(raw) if raw else None
if parsed is None:
return None
return str(resolve_stt_thread_count(parsed, affinity_cpu_count() or 1))
), and a test pins it. Checks are green.

Remaining blockers:

  1. The three deferred items (Auto resolved-count label, reload note, thread-options comment) are tracked only in Pearcekieser#36 on your fork, which is not linked in the PR description and cannot carry this repository's deferred-finding label, assignee and Due line. Please fix them here, or open one issue per item in kirodotdev/KiroCrew and link each in the description.
  2. The UX Review suggestion on this head about the zh-CN hint is unanswered. decode_threads_desc still describes threads as CPU cores (https://github.com/kirodotdev/KiroCrew/blob/52f40098fbb7b11465e27dfb4bdfe0ebe502f1a2/website/src/i18n/locales/zh-CN.json#L17260). Fix the wording or post a disposition.
  3. The First Principles CONCERNS on this head have replies only on older heads. Your #19647 reasoning stands; a current-head disposition is enough.

— crew-pr-reviewer (r111)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for r111. Head 75d0c17 addresses all three items. It is one commit rebased on main 45d21f5; the only conflict was the generated ui-index digests, regenerated.

todo (blocking): deferred items tracked only on the fork.
Fixed here instead of in separate issues, so nothing is tracked outside this repository. All five items from Pearcekieser#36 are in this head, not just the three you named, and I will close that fork issue.

  1. The Auto option reads "Auto (16)". The config GET now sends threads_auto, computed as resolve_thread_count(0, affinity_cpu_count()). Like _stt_threads_env, it is arithmetic over two leaf modules and never imports the engine. The picker therefore needs no status fetch. Without the field it falls back to "Auto".
  2. decode_threads_desc ends with "A change applies at the next dictation, which reloads the model once." in all 12 locales.
  3. The thread_options comment in SttSettings.tsx now says the Auto option resolves to a count derived from the host and is never run as a literal 0.
  4. The override note gives the count in effect first: "This gateway uses {{value}} threads, set by KIROCREW_STT_THREADS. Remove that variable to use this choice."
  5. The picker is disabled while threads_env is set, because a choice there has no effect.
    Tests: test_threads_auto_is_the_count_auto_resolves_to covers 1, 20 and 128 cores. SttSettings.threads.test.tsx goes from 4 cases to 6 and covers the Auto label, the missing-field fallback, and the picker enabled and disabled. The PR body screenshots are re-rendered for this head.

issue (non-blocking): UX Review suggestion on the zh-CN hint.
Fixed. decode_threads_desc in zh-CN said 同时使用的 CPU 核心数, which reads as CPU cores. It now says 在 CPU 上使用的解码并发数. I kept 并发数 rather than 线程数 because the zh-CN style test (style/zh-CN.md §2) reserves 线程 and renders 'thread' as 话题. The label, value and override strings already use 解码并发数.

note (non-blocking): First Principles CONCERNS on the current head, about KIROCREW_STT_THREADS.
Kept, for the reason given on #19647. The setting is read once per process when a model loads, so the gateway and each MCP server that runs the recogniser can each use a count suited to the cores they may use. A config.json value cannot do that because those processes share it. The variable adds no other surface: one parse in stt.limits, and the override note shows it only when the value parses.

Checks run locally: 1456 backend tests across the STT, transcribe, sections facade, dashboard core-coverage, settings registry and app MCP tool policy suites, plus 1169 frontend tests including the i18n suite. tsc -p tsconfig.app.json, flake8, npm run i18n:check with I18N_BASE_REF=origin/main and gen-ui-index --check are clean.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 75d0c17. The r111 blockers are cleared: the three deferred items are now fixed in this PR (Auto (n) label from threads_auto, the reload note, the thread_options comment), the zh-CN hint no longer says CPU cores, and your reply on this head answers the First Principles env-var concern with the per-process reason. Checks are green.

Two current-head AI items still have no reply:

  1. Opus advisory: the stt.threads help says auto uses half "this machine's cores", but resolve_thread_count halves the affinity count, so under taskset/cpuset the text is wrong (
    "`auto`) uses half this machine's cores, at most 16, which stays steady "
    , same wording in config-baseline.json and decode_threads_desc). Smallest fix: say "the cores this process may run on", or post a disposition.
  2. UX watch item: with KIROCREW_STT_THREADS set, the disabled picker shows the saved value while the note says another count is in use (
    value={String(stt.threads ?? 0)}
    ). Show the effective count, explain the saved value in the note, or post a disposition.

Either a fix (which needs a fresh review) or a current-head disposition per item clears this hold. No PR code was run locally.

— crew-pr-reviewer (r112)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for r112. Dispositions for the two current-head items on 75d0c17, with no push so readiness stays as it is.

note (non-blocking): Opus advisory, "this machine's cores" in the stt.threads help, config-baseline.json and decode_threads_desc.
Kept as written. The wording is exact on any host without a CPU restriction, which covers every gateway the setting was measured on. Under taskset or a cpuset, Auto halves the cores the process may run on, so on a restricted host it reports a smaller number than "half this machine's cores" suggests. The picker now shows that number directly as "Auto (n)", computed from the same affinity count, so a reader on a restricted host sees the count Auto actually uses. "The cores this process may run on" would be more precise but harder to read for the common case, and changing it touches 12 locales and the baseline. If you want the precise wording, say so and I will push it.

note (non-blocking): UX watch item, the disabled picker shows the saved value while KIROCREW_STT_THREADS is set.
Kept as written. The picker shows what is saved in config.json, which is what a user gets back once the variable is removed. The note under it states the count in effect and its source first: "This gateway uses 64 threads, set by KIROCREW_STT_THREADS. Remove that variable to use this choice." "This choice" names the value shown in the disabled picker. Showing the env count in the picker instead would make the control display a value that is not the setting it edits, and removing the variable would then appear to change the setting.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 8e686e5 to clear the merge conflict, no behaviour change. Head 3712064 is still one commit. Main added ptt_save_refused at the end of the same block of 11 locale files where this PR's decode_threads* keys sit. I kept both sides, regenerated the pseudolocale, settings registry and ui-index, and every locale still parses. npm run i18n:check, tsc and gen-ui-index --check are clean, and 1170 frontend tests and 1430 backend tests across the STT, transcribe, sections facade, dashboard core-coverage and settings registry suites pass.

note (non-blocking): the two r112 items have their dispositions on 75d0c17 in issuecomment-6268967889. This rebase leaves those lines unchanged.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 02eeb00, no behaviour change. Head 71be0cc is still one commit, and the rebase had no conflicts.

note (non-blocking): the Harness Parity Gate red on 3712064, which also failed Await Fast Gate and Coverage Gate, came from main. The x-capture check reported "ACP_BACKENDS_MEMBER_CAPABILITIES [claude]: allowlisted but now proven; delete the entry", and the same error reproduced on a clean checkout of main 6257f69. #22178 removed that entry at 17:19Z. On this head scripts/check_harness_parity.py passes with no errors.

1170 frontend tests and 1430 backend tests across the STT, transcribe, sections facade, dashboard core-coverage and settings registry suites pass. tsc, npm run i18n:check and gen-ui-index --check are clean. The two r112 items keep their dispositions in issuecomment-6268967889.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 71be0cc.

Our r111 and r112 items are answered, and the replies on the env override and the auto spelling hold, since #19647 asks for both.

Two current-head AI items still have no reply:

  • Opus: the override note passes the raw stt.threads_env string (SttSettings.tsx#L1592), while the options use fmtNumber. In bn the picker reads ৬৪ and the note reads 64. The fix is fmtNumber(Number(stt.threads_env)), or post a disposition.
  • UX Watch 2: the reload sentence is the last line of the tooltip, and the lane asks for an inline note under the select. Move it or post a disposition.

The replies also say each speech MCP server reads KIROCREW_STT_THREADS on its own. I found no MCP module that loads the STT engine at this head. If another process does run it (the meetings audio import, for example), say which one, because the Design punchline asks whether the note's "This gateway uses" stays correct there.

CI is green on this head.

— crew-pr-reviewer (r114)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for r114. Head 992c8db is still one commit on main 02eeb00.

issue (non-blocking): the override note passes the raw stt.threads_env string.
Fixed. The note now formats the count with fmtNumber(Number(stt.threads_env)), the same way the options do, so in bn the picker and the note both read ৬৪. The gateway always sends threads_env as a resolved integer string or null, so Number never gives NaN there. tsc is clean and the 148 SttSettings frontend tests pass.

note (non-blocking): UX Watch 2, the reload sentence sits in the tooltip.
Kept as written. The hint already holds the other facts about the setting, and the reload costs one slow dictation once per change. On this panel, the inline line under a select is reserved for warnings that apply now, like the override note and the model speed note, and a permanent inline line would show on every visit for something that matters only right after a change.

question (non-blocking): which process reads KIROCREW_STT_THREADS.
You are right, and my earlier reply was wrong. No MCP server loads the STT engine. Every caller of transcribe_audio or the engine runs inside the gateway: dictation through stt_stream and stt_hooks, Slack events, messaging attachments, and the meetings audio import route, which is registered on the gateway through register_app_routes. So "This gateway uses" is correct wherever the note appears. I corrected the comment on THREADS_ENV in src/kiro_crew/stt/limits.py and the PR description to say that the variable is read from the environment of the process that loads the model, which today is always the gateway. The per-process reason for the variable still stands: it lets one gateway differ from the shared config.json, for example a dev gateway on the same host.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 5ccd492 to clear the merge conflict, no behaviour change. Head 9b3f563 is still one commit.

#22362 split src/kiro_crew/dashboard/handlers/core.py into core_* owner modules behind a facade. I took main's core.py and moved this PR's additions into the owners that now hold that code:

  1. core_stt_settings.py gets _STT_THREAD_LADDER, _stt_thread_options and _stt_threads_env, the threads parse in the PUT handler, and the threads, thread_options, threads_auto and threads_env fields in the GET response. It also gets the affinity_cpu_count and kiro_crew.stt.limits imports those need.
  2. core_stt_status.py gets the thread_count(cfg.stt.threads) call in api_stt_status and the threads=cfg.stt.threads argument to stt.prewarm.
  3. The facade's core_stt_settings import block lists _stt_thread_options and _stt_threads_env next to the other STT settings names.

The tests that patch core.affinity_cpu_count reach the owner through the facade mirror, so they are unchanged. 1626 backend tests pass, covering test_core_handlers_facade.py, the dashboard core-coverage files, the composition contract, settings registry, sections facade, STT and transcribe suites. 1170 frontend tests also pass. flake8 and mypy are clean on the changed owners, and tsc, npm run i18n:check, gen-ui-index --check and scripts/check_harness_parity.py all pass.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

fix: Backend Tests (3.12, 2) on 9b3f563 failed in test_facade_mirror_guards.py::test_every_mirrored_facade_manifest_names_what_it_forwards. The core facade served _STT_THREAD_LADDER from core_stt_settings without listing it in its manifest. I missed it when I moved this PR's additions into the owner modules. Head e6bc96b adds it to the facade's core_stt_settings import block, next to _STT_MODEL_SIZES, and changes nothing else. It is still one commit.

note (non-blocking): the same shard also hit the 120 s timeout on test_every_name_the_test_trees_patch_through_a_facade_reaches_its_readers. Locally that test takes 59 s and passes on this head, so I am treating the CI timeout as runner load. If it times out again on this head, I will look at it as a real failure.

test_facade_mirror_guards.py, test_core_handlers_facade.py and the dashboard core-coverage file pass, 171 tests in all, and flake8 is clean.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main dea18bc to clear the merge conflict, no behaviour change. Head 310213e is still one commit. The only conflict was src/kiro_crew/docs/ui-index.generated.json, in its digests and counts. I took main's copy and regenerated it with gen:settings and gen:ui, and gen-ui-index --check reports it up to date.

1645 backend tests pass, covering the facade mirror guards, the core facade, the dashboard core-coverage files, the settings registry, the sections facade, and the STT and transcribe suites. 1170 frontend tests also pass. tsc, npm run i18n:check and scripts/check_harness_parity.py are clean.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main 4d5cb47 to clear the merge conflict, no behaviour change. Head f9c4874 is still one commit. The only conflict was src/kiro_crew/docs/ui-index.generated.json, in its digests and counts. I took main's copy and regenerated it with gen:settings and gen:ui, and gen-ui-index --check reports it up to date.

1645 backend tests pass, covering the facade mirror guards, the core facade, the dashboard core-coverage files, the settings registry, the sections facade, and the STT and transcribe suites. 1170 frontend tests also pass. tsc, npm run i18n:check and scripts/check_harness_parity.py are clean.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at f9c4874.

The r114 items are handled: the override note now formats the count with fmtNumber, the reload sentence stays in the tooltip with a stated reason, and the THREADS_ENV comment and description now say the gateway is the only process that loads the model. The move into core_stt_settings and core_stt_status after the core.py split matches main's layout and keeps the GET path free of engine imports. CI is green on this head. The First Principles items (env override, auto spelling) stay answered by #19647, and the UX two-numbers item by your disposition in issuecomment-6268967889.

One current-head AI item has no reply:

  • UX Review suggestion: the override note says "Remove that variable to use this choice" (en.manual.json#L8296), but the variable is read when the model loads and configuration.md says changing it needs a gateway restart. Add the restart step to the note, or post a disposition.

A disposition with no push clears this hold. A fix needs a fresh review. No PR code was run locally.

— crew-pr-reviewer (r116)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for r116. Disposition for the one current-head item on f9c4874, with no push so readiness stays as it is.

note (non-blocking): UX Review suggestion, the override note does not mention the restart.
Kept as written. The note appears only when KIROCREW_STT_THREADS is set in the gateway's own environment, so the reader is the operator who set it in the shell, service unit or launcher that starts the gateway. Removing a variable from a running process's environment is impossible without restarting that process, and the same holds for every other KIROCREW_* override. The restart step is documented with the variable in src/kiro_crew/docs/configuration.md. Adding it to the note would change the string in 12 locales and reset readiness again for a step the reader already has to take to make the change at all.

@iamwhatever iamwhatever 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.

Approving f9c4874.

Your disposition on the override note's restart step answers the last open item from r116. The note appears only to an operator who set KIROCREW_STT_THREADS in the gateway's environment, and configuration.md documents the restart.

The change is sound. parse_threads refuses bools, non-ASCII digits and over-long digit strings before int() runs, and an explicit count is clamped to the cores the process may use. The config GET resolves the counts without importing the engine (core_stt_settings.py#L152-L174), and callers that pass no thread setting keep the operator's count. #19647 asks for both the env override and the auto spelling, which answers First Principles. Every other lane item has a reply, the description defers nothing, and all checks on this head are green.

No PR code was run locally. Any new push needs a fresh review.

— crew-pr-reviewer (r117)

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)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Speech-to-text: make the local recogniser decode thread count configurable

2 participants