Skip to content

feat(stt): allow a custom pinned whisper model - #8281

Closed
LuisBrel wants to merge 2 commits into
kirodotdev:mainfrom
LuisBrel:feat/stt-custom-model
Closed

LuisBrel wants to merge 2 commits into
kirodotdev:mainfrom
LuisBrel:feat/stt-custom-model

Conversation

@LuisBrel

@LuisBrel LuisBrel commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Voice input can only run one of four catalog models (tiny, base, small, large-v3-turbo). There is no way to point it at any other whisper.cpp ggml model - a language or domain fine-tune, a quantised build sized for a small machine, a language or domain fine-tune, or a quantised build sized for a small machine. The only recourse today is to edit stt/models.py and rebuild. (Re-hosting one of the four for an air-gapped install is separately covered by MODEL_URL_ENV.)

Why it matters

A short catalog is the right first-run default, but it makes the recogniser a closed set. Users whose speech the offered models mishear (heavy accent, domain jargon, a language with a better community fine-tune) have no supported path at all, and an operator holding different weights ??? a fine-tune, a quantised build ??? cannot substitute them even with the digest in hand. (A catalog model mirrored for an air-gapped install is already served: MODEL_URL_ENV in stt/models.py overrides the publisher base URL and keeps the pin. What is unserved is different weights, not a different host.) memory.embed_model_path already solves exactly this shape for the embedding model; speech-to-text had no equivalent.

What changed (motivation to approach to change)

Goal: run any whisper.cpp ggml model without weakening the sha256 pin. That pin is the trust anchor of the whole download path: the file is handed to a native GGML parser and re-opened by name, so the digest is what makes the loaded bytes the verified bytes.

Rejected: a new stt.provider (a second inference backend for a whisper-only engine), and a bare local-path escape hatch (no pin at all, strictly weaker than the gate beside it). Taken: keep one download path and move the digest from 'this module pins it' to 'the caller pins it'.

  • stt/models.py - WhisperModel gains an optional url (empty means compose from the catalog publisher, as today) and treats size_bytes 0 as 'size unknown'. resolve of custom builds the model from config, so engine.ensure_loaded, session, the dashboard handlers and cli_doctor all work unchanged. _download_blocking is reused as-is except for one thing: a catalog row's pinned size IS its transfer ceiling and a custom model has none, so an absolute _CUSTOM_MAX_BYTES of 8 GiB stands in (the largest published whisper weights are about 3.1 GB). Dropping that pre-check instead would let a hostile URL stream until the disk filled, since a digest is only known to be wrong once the last byte has arrived.

  • config sections.py, loader.py, validation.py - new stt.custom_model_url (https only) and stt.custom_model_sha256 (64 hex), validated by the same helpers the API uses; stt.model accepts the custom sentinel. _validated_stt_model takes the sibling pair and is the one path that does not call resolve for custom, which is what stops a config-reading resolver recursing during a config load. validation.py had a second, earlier call site that rewrote stt.model before the parse site saw it; it now passes the pair too.

  • The two new validators reach loader.py through the module, not the facade - import kiro_crew.config.sections as _sections, because the from ... import block above it is a FROZEN snapshot of the names loader re-exported before the config split, pinned by identity in test_config_module_boundaries.py. A new helper added to that block is a new public alias of a module internal rather than a pre-split name, so it fails that ratchet; these two are only called at one site, so a module reference keeps the loader namespace unchanged.

  • Degrade, never raise - an absent or malformed pair resolves to DEFAULT_MODEL with a warning at both layers, exactly like an unknown catalog name. A hand-editable setting must not fail the voice session that read it.

  • Dashboard - PUT /api/config/stt accepts custom plus the two fields independently of model, so the pair can be saved before the selection; that is the only order that survives the degrade. GET /api/stt/status appends the configured custom row so its presence line and download button have something to render against.

  • Settings UI - a Custom option in the existing model picker reveals two SettingsInput rows following the AWS profile and region pattern, plus one line explaining the degrade when the pair is incomplete. No new JS helper, no new component.

  • Download transport - the module's one network seam (_urlopen) now builds a private opener carrying _HttpsOnlyRedirectHandler, because the process-wide urlopen accepts no policy argument: a Location that leaves https is refused, and so is one pointing at a non-public address, which is the hop this host did not choose. On a CUSTOM download the configured address is screened too, not just the hops after it - stt.custom_model_url arrives from config.json, which an agent can read and, at the shell, write, so it is not the operator statement an environment variable is; MODEL_URL_ENV keeps its unscreened internal-mirror behaviour precisely because it IS one. Three consequences ship with that and are intended, not incidental: a new KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE re-admits named ORIGINS (not an on/off switch, which would have re-admitted every private address through the same agent-writable value); a custom download through an https_proxy is refused outright, because a tunnel hands the hook the proxy's address, so screening what it sees would approve the proxy and say nothing about the destination; and the custom pair is owner-only on GET/PUT /api/config/stt, since an app token that could set it would be aiming a gateway download. All three are in docs/configuration.md and in the owning docs/system-specs/modules/stt-streaming.md spec section. New url_redaction.py holds the host-only reduction those refusals log, since a model URL can carry a credential in its userinfo, path or query and these messages reach the gateway log, /api/logs and a status field the settings page reads back. Two further copies of that reduction remain in papyrus and pptx-maker and are left for a separate change. It also refuses a value whose scheme or authority is not printable: urlsplit strips only tab, CR and LF, so an ESC, a BEL or a bidi override in the Location a redirecting server chose would otherwise be rebuilt into the returned string and written to the operator's terminal. embeddings.py carries no copy of the reduction any more - its own download path goes through asset_downloader upstream, and kirocrew doctor imports this module directly.

Deliberately not here: no new provider, no new backend, no change to the retired-provider list, no bypass of the write-protected models directory.

Tests

New test/test_stt_custom_model.py, 51 test functions (128 collected cases), three of which pin the redactor refusing a control-byte or bidi-override authority:

  • a matching digest installs the weights at their final path, and a wrong digest is refused leaving neither the target nor a staging file

  • an already-present custom model whose digest stops matching is deleted on the load path, not returned. That is the case a caller-supplied pin has to cover to be worth anything

  • six unusable-pair shapes (missing half, plaintext URL, short or non-hex digest) degrade to the default at both the loader and resolve

  • an unreadable config degrades rather than raising, since resolve sits on a live voice session's path

  • the custom URL is fetched verbatim, so the catalog base-URL override cannot be prepended to it

  • a response past the ceiling is refused mid-stream, asserted on what reached the disk rather than on the exception

  • custom is absent from CATALOG and from the alias table

In test/test_config_loader.py the advertised-menu ratchet is now exact in both directions (catalog plus custom), so a second sentinel cannot be added without a download path behind it, plus one case pinning that custom is accepted only with a usable pair.

Manual verification

N/A for the download path: the tests drive the real _download_blocking against a stubbed socket rather than mocking the verification.

Not yet done is an end-to-end fetch of a real third-party model followed by a decode. That needs a hosted ggml artifact plus the voice extra, and it exercises no code this PR adds, since _build_model already loaded by absolute path before this change.

Screenshots / video

Captured by a new sibling harness, website/scripts/capture-stt-custom-model.mjs, built the same way as capture-stt-local-voice.mjs beside it: the REAL built SPA behind serveDist with every /api/** call answered from fixtures, so there is no gateway, no recogniser and no network in the frames. They are fixture states rather than a click sequence because each one is a steady state the panel reaches from the gateway's answer. The model picker's own open popup gets no frame: the option list adds nothing this change is about, since the Custom row is one more entry in a list the panel already rendered.

1. Custom selected, both halves pinned, weights already on disk. The settled everyday case. The two rows carry the values the digest was checked against, which is the point of moving the pin to the caller.

Settings Voice card with Model set to Custom, the custom model URL and SHA-256 rows filled in, and the line "This model is already on this machine."

2. The same pair, before the one-time fetch. The prompt is the unsized string. A custom row publishes no size, and the sized sentence used for catalog rows would render "0 B" here and read as a free download, so this branch exists specifically to avoid quoting a wrong number.

The same card with the weights absent, showing "Not on this machine yet. Fetching it now avoids a wait during your first dictation." above a Download now button, with no size quoted

3. Half a pair. The URL is set and the digest is not, so the selection degraded to the default model instead of failing the voice session - which means the picker legitimately reads base (148MB) after a user picked Custom. The line under the rows is what stops that looking like a select that ignored the click, and it is the frame most worth having.

The same card with Model showing base (148MB), the custom URL row filled, the SHA-256 row empty, and the explanation "Both the URL and the SHA-256 are needed before a custom model can be used, so the default model stays in force until then."

Review findings addressed

Three findings from the automated review round on 58c2244, all fixed in code. Opus 4.8 passed with no findings.

1. An app token could configure a custom model (blocking). PUT /api/config/stt accepted model: "custom" and the custom_model_url / custom_model_sha256 pair from any caller. stt.status, stt.prepare and stt.prewarm already deny an app token, precisely because they fetch weights and load them into the gateway. The pair reaches that same outcome by a longer road: it names a URL the gateway will fetch, verify against a digest the same caller supplied, and load, and the transcription surfaces that trigger the load are deliberately app-reachable. So an app able to write those fields obtained the download the other three refuse it, aimed wherever it liked.

Now refused per-field rather than per-endpoint, because an app may legitimately hold config.stt for the language and the toggles, and a blanket gate would be a silent regression for shipped apps. The GET also withholds the pair from an app token, so there is nothing for one to echo back. model is refused on presence of custom, unconditionally. An earlier revision refused it only when it would change the selection, so an app could write back a custom already in force. GPT 5.6 was right that this is not the no-op it looks like: the handler reads its config before taking the write lock, so "custom is already active" can be stale by the time the write lands ??? the operator switches to a catalog model in between and the app's write puts custom back. The convenience of an unmodified round-trip loses to the race it opened. The existing boundary is reused rather than reimplemented: the fail-closed _is_dashboard_user test and the audited 403 are now shared with _deny_app_token.

2. Correcting a custom pin left the old weights in force (blocking). WhisperModel.filename was the constant ggml-custom.bin for every custom model that has ever existed, and three separate mechanisms key off that path:

  • WhisperEngine.ensure_loaded builds its LoadedKey from it, so a corrected URL or digest kept serving the old resident weights and never asked the store to verify the new ones. The correction took effect only after a restart.

  • is_present has no pinned size to check a custom model against, so any non-empty file at the shared path reported the new model as already downloaded.

  • _verified_on_disk deletes a file whose digest does not match, so one mistyped-but-well-formed digest destroyed weights that were fine ??? unrecoverable on a machine that is offline, with no symptom beyond dictation stopping.

The filename now carries the digest, which fixes all three at the source instead of patching each: a different pin is a different path, so it is a different LoadedKey, it is correctly absent, and it cannot delete the file the previous pin still names. The whole digest, not a prefix: a prefix is ample against collision, but collision is not the risk being managed here ??? a typo is, and a typo in any character past a prefix lands back on the good file's path and deletes it. The name stays inside security._WHISPER_WEIGHT_NAME, the shell fence over these files.

3. The explanation line was gated backwards (UX/Design concern, and a real bug). It fired on a non-custom stt.model plus either field filled. That is silent in the empty first-run state ??? the one case it exists to explain, where the selection degrades to base and the picker looks like it ignored the click ??? and it asserted "both are needed" over a complete pair whenever a catalog model was reselected, persisting across reloads. It now fires when a custom model is what the user intends and the pair cannot deliver one. Intent is tracked separately from whether the rows are open, because stt.model cannot answer it: a custom selection with an unusable pair is served back as the default.

Second review round (5427a63) ??? both blocking findings fixed

4. A stale pre-lock config read let an app token reactivate a custom model (blocking, GPT 5.6). Verified against the code before changing it: api_stt_config calls KiroCrewConfig.load() at entry, outside the shared config lock, and the gate compared body["model"] against that cfg.stt.model. So an app-token PUT could read "custom is already active", the dashboard user could switch to a catalog model, and the app's write ??? landing later, inside the lock ??? would put custom back. Fixed by dropping the comparison: model: "custom" from an app token is now refused on presence. The test that asserted the old carve-out was replaced by one asserting the 403.

5. A non-object JSON body returned 500 instead of 400 (blocking, GPT 5.6). Every field in this handler is a membership test followed by a subscript, so the array ["custom_model_url"] satisfies "custom_model_url" in body and then raises TypeError on body["custom_model_url"]. The hole is not specific to the new fields ??? the pre-existing "enabled" in body line has it too ??? and it fired inside the security gate that runs first. Fixed once, immediately after the parse, matching the sibling theme handler in the same module: 400 unless the parsed body is a dict. The gate's own defensive non-dict branch became unreachable and was removed with the now-unused cfg parameter.

6. Subtraction accepted (First Principles). Removed the if not written: raise ModelDownloadError(...the response carried no bytes) branch from _download_blocking. An empty body cannot match a pinned digest, so the compare two lines later already refuses it before anything is stored; the branch only changed the message. test_an_empty_response_is_refused now asserts sha256 mismatch and additionally that no file was installed.

7. A rejected URL or digest kept displaying, which also silenced the explanation line (UX concern, verified against the code before changing it). The row commits on blur and the handler keeps the value only if it validates, so a 63-character or sha256:-prefixed paste is dropped and answered without it. The initRef guard on the hydrating effect fires once, so the field went on showing the typed text: both rows looked filled, which made customIntended && (!url || !sha) false and suppressed the "both are needed" line as well ??? the user saw a complete pair, base (148MB) in force, and no message at all until a reload. mut.onSuccess now re-reads the two rows from the answer, so a refused value visibly clears and the shipped line fires. Only the rows the patch carried are resynced: blurring the URL must not clear a digest the user has already started typing, and that is pinned by its own test.

Deliberately deferred

A field-level validation message when a malformed URL or digest is discarded on blur (First-Principles / Design minor). Left out on purpose rather than overlooked: it needs two new i18n keys across fourteen locale files, and the shipped custom_model_incomplete string ("Both the URL and the SHA-256 are needed") would misdescribe a value that is present but malformed. Doing it properly is a self-contained follow-up; doing it here would widen a review round into new copy in twelve languages. The malformed case is not silent in the meantime ??? the value is refused by the same validators the loader uses, and the selection degrades with a warning rather than running something unverified.

Verification

Narrow by path, not the full suite.

| Gate | Result |

| --- | --- |

| pytest test/test_stt_custom_model.py test/test_dashboard_handlers_core_coverage.py -q | 206 passed |

| Same two files with both backend fixes reverted | 14 failed ??? the tests bind |

| npx vitest run src/test/SttSettings.customModelGuard.test.tsx | 6 passed; 1 fails with the onSuccess resync removed, 2 fail with the old guard restored |

| npx vitest run src/i18n/catalogParity.test.ts | 77 passed (no new keys, so parity is untouched) |

| The five existing SttSettings* / SttProviders files | 36 passed |

| black --target-version py310 --check on all four Python files | 4 unchanged |

| npm run typecheck, npm run lint | exit 0 |

Two pre-existing failures on this Windows host are environmental and reproduce on the unmodified base commit: test_a_planted_symlink_at_a_predictable_staging_path_is_not_followed and test_a_symlink_out_of_the_data_home_gets_no_lock_sidecar, both WinError 1314 (the symlink privilege is not held).

Related Issues

no linked issue: a self-contained enhancement rather than a report someone filed.

Checklist

  • At most two commits, with a Conventional Commits title

  • Existing tests pass and new tests added for new functionality

  • Self-review completed; code follows project style guidelines

  • Documentation updated (configuration reference, config module spec, regenerated config baseline)

  • No secrets, credentials, or internal references in the diff

What else this ships, declared plainly

The First Principles lane was right that the description carried the feature and left the rest to be inferred from the diff. Six things ride along with the custom-model pair. They are listed so a reviewer can scope them, not defended:

  1. Every model download now refuses a redirect that leaves https ??? the pre-existing catalog path included.
  2. ???and a cross-host redirect that resolves to a non-public address. Fails closed on DNS failure.
  3. Model-download error text is host-only, re-wrapped at the transport seam ??? the URL can carry a pre-signed signature, and an exception's own string is not one of this module's redacted messages.
  4. The custom pair is owner-only on PUT /api/config/stt and withheld from GET for everyone else.
  5. PUT /api/config/stt answers 400 instead of 500 for a non-object JSON body. Symptom-level: two siblings in the same file still call .get on an unchecked body (api_kirocrew_config, api_kirocrew_config_patch) and are deliberately left alone.
  6. kirocrew doctor's model-url line and the embedding download log lose the URL path.
  7. One inherited comment-history line is reworded in test/test_config_loader.py. The comment-history gate reports that file above its baseline (14 vs 13) on the base branch itself; this diff adds none of the matched lines, and the gate's own message says rewording a matched line is what clears it. One phrase is put in the present tense; no assertion changes.

Items 1???3 harden a path that exists in base today, so they are separable from this feature and could be split into their own PR if a maintainer prefers that.

The DNS-rebind window, now closed at the socket

The previous round screened a redirect's addresses and then handed the URL back to urllib, which resolves again at connect time. A resolver answering a public address to the screen and a private one to the connect was not stopped ??? a real TOCTOU, and the reason the review lane held this blocking.

The screen now happens at the socket, and the socket is opened to the exact address the screen approved: _PinnedAddressHTTPSConnection.connect resolves once, refuses unless every answer is public, then socket.create_connections to that address and wraps it with server_hostname still set to the hostname ??? so SNI and the certificate check are unchanged, and urllib derives Host from the request, which the connection never rewrites. _ScreenedHTTPSHandler routes only a marked request through it, and only a cross-host redirect hop is marked.

That marker is also the answer to the Design lane's regression worry. A hop that stays on the same host the operator configured is exempt, because that host's first hop is deliberately unscreened and an artifact store answering 302 to its own blob path is an ordinary topology rather than an attack. A hop to a different host is screened twice: eagerly, for a clear refusal before a socket opens, and again at connect.

Also fixed from the same review: the custom-URL validator now refuses an authority carrying a userinfo part. urlsplit().hostname reports it stripped, so a screen reading hostname and a connection reading the authority disagreed about which host the request was for ??? and urllib does not turn userinfo into an Authorization header, so the download failed anyway, after the value had been stored and read back through the status field.

Tests for this round

pytest test/test_stt_custom_model.py test/test_stt_config_field_types.py ??? 113 passed. New cases, all mutation-proved:

  • test_a_rebinding_resolver_cannot_move_the_connection_off_the_screened_address ??? a resolver answering public once and private afterwards; asserted on the address the socket was opened to, because a refusal raised after the wrong connection was made is the same SSRF. Point the connect back at the name and it fails with AssertionError: the socket must use the vetted address.
  • test_the_pinned_connection_refuses_a_non_public_answer_without_connecting ??? parametrised over all five non-public ranges, asserting nothing was opened.
  • test_the_pinned_connection_keeps_the_hostname_for_tls ??? server_hostname is the host, not the address, so a certificate for the host still has to verify.
  • test_a_same_host_redirect_on_an_internal_mirror_is_still_followed ??? remove the same-host exemption and it fails with refusing a non-public address for: https://models.example.
  • test_the_download_opener_carries_the_https_only_policy_and_drops_the_default ??? extended to pin the new handler into the opener.

Two test gaps, named rather than papered over. The write guard on this machine refused, repeatedly, every edit that put (a) a _ScreenedHTTPSHandler subclass stubbing do_open into the test file, and (b) a userinfo-bearing URL literal into it. So the handler's request-to-connection selection is covered only indirectly ??? by the opener wiring test plus the two redirect tests that prove a cross-host hop is refused and a same-host hop is followed ??? and the userinfo refusal has no test at all. Both are small and worth adding by anyone whose tooling permits it.

Third review round ??? both blocking findings fixed

8. The custom config read ran on the event loop (blocking, GPT 5.6; upheld by the
adjudicator against no-blocking-call-on-event-loop, which AUTOSDE.yaml declares
blocking for src/kiro_crew/**/*.py). Verified before changing anything:
resolve(CUSTOM_MODEL) calls KiroCrewConfig.load(), a synchronous stat + read +
validate of config.json, and resolve is reached from three async paths ??? the voice
websocket's WhisperEngine.ensure_loaded, the transport's pending_download, and the
settings panel's stt.ensure_model. Called inline, that read ran on the gateway's
single event loop and stalled every other session.

Fixed by offloading at all three call sites with asyncio.to_thread, which is the
pattern ensure_loaded already uses two lines above for probe and for the same
reason. Offloaded unconditionally rather than only for the custom name: the executor
hop is microseconds beside the model load it precedes, and duplicating resolve's own
dispatch at three call sites is how one of them ends up keeping the blocking read. No
signature changed, so no caller and no test had to be rewritten.

9. A same-host redirect onto another PORT skipped the address screen (blocking,
security-fenced). The mirror exemption compared hostname only, so
mirror -> mirror:8443 read as "still on the operator's host" and was handed both the
eager screen's pass and the socket pinning's. A co-located internal service on
another port of the operator's own mirror host is an ordinary deployment shape, so that
was a way through rather than a corner.

The comparison is now per origin ??? scheme, host and effective port ??? via a small
_origin() helper. The port is effective, not literal, because https://h/ and
https://h:443/ are one origin and a comparison on parts.port (None against 443)
would have screened a hop that never left, refusing the internal-mirror install this
feature documents. An unparseable port reduces to -1, which matches nothing, so such
a hop is screened rather than crashing.

Tests for this round

pytest test/test_stt_custom_model.py test/test_stt_config_field_types.py test/test_stt_session.py test/test_stt_engine.py test/test_stt_stream.py ???
291 passed, 15 skipped, 1 pre-existing WinError 1314 symlink failure that
reproduces on the unmodified base.

  • test_resolving_the_custom_model_is_kept_off_the_event_loop ??? asserts on the THREAD
    the resolve ran on, not on a timing, because a timing assertion for something this
    fast is a flake. Mutation-proved: restore the inline models.resolve(...) and it
    fails with AssertionError: [<_MainThread(MainThread, ...)>].
  • test_a_same_host_hop_onto_another_port_is_screened_not_exempted ??? asserted in both
    directions against a host that resolves NON-publicly, which is what a configured
    internal mirror does: the same-origin hop must still be followed, the :8443 hop must
    refuse. Mutation-proved: drop the port from _origin() and it fails with
    Failed: DID NOT RAISE ModelDownloadError.
  • test_an_explicit_default_port_is_the_same_origin ??? guards the regression the port fix
    could have introduced.

black, isort, flake8 and mypy clean on all five changed files.

Fourth review round ??? the security-fenced blocking finding, fixed by refusal

10. A credential-bearing custom model URL was persisted into agent-readable
config.json
(blocking, GPT 5.6, security-fenced so the verdict could not be
adjudicated away). Verified against the code before changing anything, and the finding
is half right in a way that matters: valid_custom_url already refused userinfo
(round three, finding above), so https://user:token@host/??? never reached
config.json. What it still accepted was a pre-signed URL, whose entire bearer
credential rides in the query (or the fragment). security/paths.py states in its own
comment that config.json is deliberately not in the sensitive read gate ??? only
writes are fenced, because reading it is routine ??? so a value stored there is readable
by an untrusted or prompt-injected agent, and none of this PR's owner-gating or
status-field masking touches a direct file read.

Fixed by refusing the shape rather than relocating it. The review's suggested fix
was an agent-hidden credential store with an opaque reference; there is no such store
for config values in this tree, so taking that route means designing one, and it would
still leave a credential on disk under a different fence. A whisper model artifact is a
static file: neither a query nor a fragment carries anything the fetch needs, while
those two components are exactly where a signature lives. valid_custom_url now
returns "" for either, one line below the userinfo refusal it mirrors and for the
same stated reason. Both writers store precisely valid_custom_url(...) ??? the settings
PUT (core.py) and the config loader ??? so one validator covers both.

The residual is named, not hidden. A token in a path segment is
indistinguishable from a filename, so it is still accepted and still stored. That is
the operator's own risk and cannot be fenced without refusing every URL.

Cost, stated plainly: an operator hosting their weights behind a pre-signed URL can
no longer configure one. That is the credential exposure being refused, and the refusal
lands at the field while they are still looking at it rather than after the value is on
disk.

Tests for this round

pytest test/test_stt_custom_model.py ??? 116 passed. Also
pytest test/test_config_loader.py test/test_dashboard_handlers_core_coverage.py test/test_stt_engine.py test/test_stt_stream.py ??? 832 passed, 21 skipped, with the
one pre-existing WinError 1314 symlink failure that reproduces on the unmodified base.

  • test_a_presigned_url_cannot_be_persisted_into_agent_readable_config ??? asserts the
    validator returns "" for a X-Amz-Credential / X-Amz-Signature URL, that it is
    not silently trimmed back to the bare URL (which would store a dead link the
    signature was required for), and that custom_model cannot build a pair from it.
  • Four cases added to the shared validator table: a signed query, a bare ?token=, a
    fragment, and the userinfo shape that had no test at all until now ??? which closes one
    of the two test gaps this PR previously declared.

black, isort, flake8 and the repository's check_black_formatting.py and
check_comment_history.py gates are clean on this head.



Fifth review round ??? the loop stall's missed sibling, and the private-mirror override

9. pending_load() was still resolving the model on the event loop (blocking, Opus 4.8
and GPT 5.6 F3, and the adjudication upheld it).

Round three offloaded pending_download, engine.resolve and session.ensure_model, but
_run_local_session still called session.pending_load() inline ???
models.resolve ??? _configured_custom_model() ??? KiroCrewConfig.load(), a synchronous
config read plus jsonschema validation, on the single gateway event loop. And it is the path
that always runs: pending_download returning None is exactly what leads here, so the
downloaded-custom-model-with-a-cold-engine session hit the stall the round-three comment says
was moved off the loop. The reviewers named the one-line remedy and it is the pattern already
used two lines above.

Fixed: if await asyncio.to_thread(session.pending_load):.

10. KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE authorised every private address, not the
operator's own
(blocking, GPT 5.6 F2).

The override was a boolean, so it re-allowed the operator's internal mirror by switching the
address screen OFF ??? and the address being screened arrives from stt.custom_model_url in
config.json, the agent-reachable value the screen exists to distrust. So the air-gapped
install was the one install where a rewritten URL could have the gateway reach an arbitrary
internal https service. The screen's own reasoning already said a config value is not an
operator statement; the override contradicted it.

Fixed: the variable now names the one origin the operator authorises
(KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE=https://mirror.internal:8443) and the screen is
skipped only for that origin. Compared on origin, so a co-located service on another port of
the mirror host is not the mirror. A value that is not a parseable https origin ??? including
the old 1 ??? matches nothing and therefore disables nothing, so the failure mode of a stale
setting is a refusal rather than an open screen. The env var ships in this PR, so no
installed configuration depends on the boolean form. docs/configuration.md is updated.

Where the credential-in-a-path residual stands. An earlier round left this as GPT's F1: valid_custom_url admits a credential embedded in a URL PATH segment, and the named remedy is an agent-hidden credential store that does not exist in this codebase. It is still the honest residual, the module comment states it and the field is marked sensitive -- but it is no longer what the review blocks on: the lane's F1 moved to the unaudited read side of the owner gate, which the seventh round below fixes in code.

Tests for this round

pytest test/test_stt_custom_model.py test/test_stt_stream.py test/test_stt_stream_cov80.py test/test_stt_session.py test/test_stt_engine.py ??? 331 passed, 19 skipped.
black, isort, flake8 and mypy clean on the changed files.

  • test_neither_model_probe_runs_on_the_gateway_event_loop ??? asserts the THREAD each of
    pending_download and pending_load ran on is not the loop thread, because an inline call
    and an offloaded one are indistinguishable by call count. Put pending_load back inline and
    it fails with assert <tid> != <tid>.
  • test_the_override_authorises_one_origin_and_not_private_addresses_at_large ??? with the
    mirror's origin declared, a different private https URL is still refused. This is the
    finding itself; under the old boolean it passes through.
  • test_the_override_matches_an_origin_and_not_a_host_on_another_port ??? mirror:8443 is not
    mirror.
  • test_the_private_custom_mirror_override_takes_only_a_parseable_https_origin ??? 1, true,
    0, empty, yes, a bare hostname and an http:// origin each disable nothing.


Why this touches .github/ ??? one line, and it needs a maintainer label

This branch deletes exactly one line from .github/coverage-baselines/frontend.txt:

-src/pages/settings/SttSettings.tsx 67.8   # 78/115

That deletion is not optional and is not a CI change. scripts/check_per_file_coverage.py
states the third baseline rule itself: "a file in the baseline that clears the floor by that
same band must be removed from it ??? this is the ratchet, and it is what makes the list
shrink."
SttSettings.tsx was baselined at 67.8% because it sat below the 80% per-file
floor; the tests added here lift it clear of that floor, so leaving the entry in place fails
Coverage Gate as a stale exemption. No other file under .github/ is touched.

Because the path is under .github/**, the Fork Workflow-Change Guard blocks the PR by
design and asks a maintainer to read the change and apply the allow-fork-workflow-change
label. There is no contributor-side way to satisfy both gates at once, so that label is the
only remaining blocker on this branch.

Sixth review round ΓÇö the rebase, two real CI failures, and the duplicate this PR claimed to remove

Rebased onto main (90 commits). One content conflict, in config/loader.py: main had
lifted the inline SttConfig(...) construction into a new _build_stt_config(stt_data)
helper, so this branch's three additions (custom_model_url, custom_model_sha256, and
the custom_url / custom_sha256 arguments to _validated_stt_model) moved into that
helper instead of being reapplied to a call site that no longer exists.

Two failures on the previous head were real, and both are fixed here.

  • test_security_posture.py::TestOmissionDetection::test_allowlist_has_no_stale_entries
    failed on all three platforms: embeddings.py was allowlisted as a non-egress redactor
    caller, and this branch removes its last redactor call. The allowlist entry is now gone.
    That test exists precisely so a dead entry cannot become a place a future sink hides, so
    the failure was the guard doing its job, not noise.
  • SttSettings.customModelGuard.test.tsx > withholds the hand-off while a rejected URL is still in the row failed on one frontend shard only: the helper waited for the model
    combobox and then addressed the custom rows synchronously, but those rows mount on the
    config query resolving, which is a later tick (setCustomOpen(true) runs in an effect
    over the query data). Waiting on the combobox never implied the row existed; the three
    call sites now await the row itself. The test passes in isolation either way, which is
    why a shard under load was the only thing that showed it.

The First Principles finding is correct and the module is no longer a copy.
asset_downloader.redact_url already implemented this exact scheme-and-host reduction,
with the same reasoning about a path segment being able to carry a token ΓÇö so the count in
url_redaction.py's own docstring was wrong in both directions, and the cycle it claimed
was not real (asset_downloader imports no config module). redact_model_url now CALLS
asset_downloader.redact_url for the reduction and adds only the strictness a failure path
needs and a bulk transfer does not: a value that is not a string at all (the config
validator holds whatever the JSON held), a value with no authority to keep, and a host that
cannot be printed to a terminal. Two hand-written copies still survive, in papyrus's
Tectonic download and pptx-maker's engine download; migrating them is a mechanical import
swap against two live download paths with their own tests, and the docstring now says so
rather than implying the duplication is already gone.

Two changes this description had not declared

  • kirocrew doctor no longer prints the resolved embedding model's file PATH, only its
    host. The pin it replaced argued the path was the operator's own override and never a
    value a remote party chose; that is not safe as a general rule ΓÇö a mirror can tokenise a
    path segment, which is the case the papyrus and pptx download paths already record ΓÇö so
    the diagnostic gives up the filename to keep the token out of a terminal.
  • PUT /api/config/stt answers 400 instead of 500 when the body is not a JSON object.
    Pre-existing behaviour, unrelated to the feature, and harm-free; declaring it rather than
    leaving a reviewer to find it.

Tests for this round

  • pytest test/test_security_posture.py test/test_stt_custom_model.py test/test_config_loader.py test/test_stt_engine.py test/test_stt_stream.py test/test_dashboard_handlers_core_coverage.py -q
    -> 1056 passed, 22 skipped.
  • npx vitest run src/test/SttSettings.customModelGuard.test.tsx -> 9 passed;
    tsc --noEmit and eslint both clean.
  • black --check, isort --check-only, flake8, mypy clean on the four changed modules.

What the two BLOCK verdicts are waiting for

Both the UX and Design lanes reported the same thing, and neither was a code finding: the three
screenshots were linked as committed raw/<sha>/... files, which those lanes cannot fetch. They
are now user-attachments assets, so both lanes can download and render them. The frames themselves exist in the branch
and are unchanged by this round. They need to be attached to this description as
attachments; the temp-screenshots/ commits can then come out of the branch rather than
ship into history.

Tests for this round

Rebased onto current main (112 commits, no conflict) and acted on the GPT
non-blocking finding at stt/models.py:842, which was verified against the code
first and is real: redirect_request pinned the ADDRESS on every hop, and the pin
refuses a private address outright, so an operator who named their air-gapped
origin in KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE lost the exemption on their
mirror's first /model -> /blob/... redirect. The escape hatch therefore only
worked for a mirror that never redirects. A hop that stays on that declared origin
is exempt from the public-address requirement; crosses_origin is sticky, so a
chain that has left can never claim it back, and a Location naming any other
private origin still crosses and is still refused eagerly.

  • pytest test/test_stt_custom_model.py test/test_security_posture.py test/test_config_loader.py test/test_stt_engine.py -q
    -> 818 passed, 5 skipped.
  • black --check, isort --check-only, flake8, mypy -> all clean on both changed files.

Seventh review round - the fenced blocking finding, fixed in code

Rebased again onto current main (30 commits, no conflict). Every claim below was checked
against the code before anything was edited.

11. The READ side of the custom-model owner gate was not audited (blocking, GPT 5.6,
security-class and adjudicated UPHOLD-FENCED, so no argument could clear it). Real, and
narrower than it first reads: the WRITE path audited only its refusal
(_deny_non_owner_stt_custom_model), while the same owner predicate decides whether
GET /api/config/stt serves or withholds the URL/digest pair -- and neither branch wrote an
event. So "nobody but the owner was ever served this pair" was not answerable from the log,
and a served pair is exactly the value a caller would need to echo back on a write it may not
make. Both outcomes now emit stt.custom_model.read with outcome allowed or denied,
best-effort like every other audit on this endpoint, because an unwrapped SEL failure must
never turn a served config into a 500.

Only when a pair is IN PLAY. With no URL, no digest and a catalog model in force the branch
discloses two empty strings and there is no decision to record -- and this endpoint is fetched
by the chat composer's voice hook on mount, not only by the settings page, so an unconditional
row per GET would bury the decisions that carry a value. A second test pins that silence, so
the gate cannot quietly widen into an audit of everything.

12. With the private-origin override set, an https_proxy install tunnelled the request
(non-blocking finding, GPT 5.6). Also real, and a consequence of how the sixth round expressed
its own fix: the declared origin's request was left UNMARKED, which put it on the plain
connection, so urllib tunnelled it and the proxy refusal this module documents never ran. The
exemption then covered whatever the proxy chose to CONNECT to rather than the one origin the
operator named. Now every screened request is marked and rides the pinned connection; the
exemption travels as its own flag and lifts only the requirement that the address be PUBLIC.
The tunnel refusal is reached first, so a proxied install is still refused by name.

13. The incomplete-pair line asserted the opposite of the state in force (UX watch). For a
non-owner dashboard session with custom running, the GET omits the pair, so both rows read
empty and the line said the default model stays in force -- false, and said to the one caller
who cannot see the pair proving otherwise. The keys are OMITTED rather than emptied, so key
presence is the signal, and the line is now gated on the pair having been served.

Tests for this round

  • pytest test/test_stt_custom_model.py test/test_dashboard_handlers_core_coverage.py test/test_security_posture.py test/test_config_loader.py test/test_stt_engine.py -q
    -> 1003 passed, 5 skipped.
  • npx vitest run src/test/SttSettings.customModelGuard.test.tsx src/test/SttSettings.streaming.test.tsx
    -> 16 passed; tsc -p tsconfig.app.json --noEmit and eslint both clean.
  • black --check, isort --check-only, flake8, mypy -> clean on the four changed modules.

Each new assertion is mutation-proved, and each carries a control that must still pass:

  • test_the_read_side_of_the_owner_gate_is_audited_on_both_branches -- deleting the emit call
    gives 1 failed, 1 passed: the audit case fails while the no-row control still passes.
  • test_a_declared_private_origin_is_still_refused_through_a_proxy_tunnel -- consulting the
    exemption before rejecting the tunnel (if tunnel_host and not self.declared_private_origin)
    fails it, which is the finding's exact shape.
  • test_an_operator_can_re_allow_a_private_custom_mirror_by_environment -- restoring the
    unmarked request (screen_address = not declared_private) fails it.
  • stays silent for a caller the pair was withheld from -- dropping customPairServed from the
    condition fails that one case and nothing else (1 failed, 9 passed).

Still not a code finding

The UX and Design BLOCKs were evidence-only and that evidence is now attached: the three frames
are user-attachments assets in the Screenshots section above, so both lanes can download them.

One CI row is red and is not this branch's: Backend Tests (Windows) (8) failed on
test/test_workflows_service.py::test_finished_run_busy_slot_queues_turn, a file this PR's
44-file diff does not touch, at the await asyncio.sleep(0.05) on line 1437 -- the same fixed
sleep that #11148 replaces with a durable wait. It passed on the other eleven shards.

Eighth review round - the admitted write is now audited too

Rebased onto current main (no conflict). Every claim below was checked against the code
before anything was edited.

14. The owner gate audited the write it REFUSED and not the write it ADMITTED (blocking,
GPT 5.6 F2 at dashboard/handlers/core.py, security-class and fenced). Real. The seventh
round closed the READ side (stt.custom_model.read, both branches), but
_deny_non_owner_stt_custom_model's own owner branch is still a bare
if is_owner_dashboard_request(request): return None - so the log answered "who was turned
away" and never "who aimed a download", and only the second names the URL and digest the
gateway then fetches, verifies and hands to the native GGML loader. A denial-only record also
cannot tell an endpoint nobody exercised from one exercised successfully.

An admitted write now emits stt.custom_model with outcome: allowed, under the same
operation name and the same best-effort contract as the refusal it pairs with, so both
outcomes of one authorization decision read as one operation. Unconditional, unlike the read
audit's "only when a pair is in play" gate: that gate exists because GET /api/config/stt is
fetched on every chat mount by useComposerVoice, whereas this is the write, already reached
only by a body naming custom or one of the two fields. A second assertion pins that an
ordinary write (language_code) stays silent.

15. Two refusals named a mechanism and no way out (UX watch, and the fix the lane named).
refusing a non-public address for: <host> and the proxy-tunnel line reach the operator
verbatim in Settings > Voice ("The download failed: {{error}}"), and a mirror on a private
network is a core audience for a self-supplied model - so every attempt failed identically
until they found the env var in the docs. Both messages now carry the documented next step:
name the mirror's origin in KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE, and for the proxy case
also that a custom fetch needs a connection not using https_proxy.

Where the First Principles subtraction on item 7 stands, and why it is not taken. The lane
asks to make the non-https redirect refusal conditional on screen_addresses=True, leaving the
catalog path on stock redirect behaviour. Declining, with the reason stated rather than
deferred: the address screening is already conditional on that flag and always was, so what the
subtraction removes is only the SCHEME floor - and an https -> http downgrade on a
model download is not a shape worth following on any path, catalog included. The risk the lane
weighs it against is that the publisher's own chain leaves https, which the lane itself marks
asserted rather than measured. Removing a floor to hedge an unmeasured risk is the wrong
direction; if a real catalog fetch is ever observed to need it, the one-line change is where
the lane says it is.

Tests for this round

  • pytest test/test_stt_custom_model.py test/test_stt_engine.py test/test_stt_stream.py test/test_dashboard_handlers_core_coverage.py test/test_security_posture.py test/test_config_loader.py -q -> 1066 passed, 22 skipped, exit 0.
  • black --check, isort --check-only, flake8, mypy -> clean on the three changed files.

The new assertion is mutation-proved with a control that still passes: remove the
_audit_stt_custom_model_write_allowed(request) call and
test_the_owner_gate_audits_the_write_it_admits_not_only_the_one_it_refuses fails with
assert [] == ['allowed'] while test_the_read_side_of_the_owner_gate_is_audited_on_both_branches
still passes - so the new case binds to the write path specifically and not to the read audit
beside it.

Where the remaining blocker sits, stated plainly

GPT's other blocking finding is unchanged and is an architectural question rather than a defect
to patch: stt.custom_model_url and stt.custom_model_sha256 both live in config.json, so
the same writer sets the byte source and its trust pin, and the digest defends only against a
mirror substituting bytes - never against the writer choosing them. The owner gate covers the
API write path and not a direct file write. Closing it means moving the pair off config.json
to an operator-controlled surface, which changes what this feature offers (the Settings rows
would go, or become read-only over an environment-supplied pair). That is a maintainer's call
on product shape, not something to decide inside a review round, so it is left named rather
than unilaterally reworked.

Ninth review round - the CI failure that was ours, the connect fallback, and the reversed pin

The one red test row was ours, and is fixed. Frontend Tests (1) failed in
src/i18n/style/frStyle.test.ts: the French custom_model_incomplete value put a plain
U+0020 before its semicolon, and that gate holds a branch's own changed values to U+202F
(the narrow no-break space) with zero tolerance, even though the inherited catalog is
mostly U+0020. The space is now U+202F. The other three red rows were downstream of it -
Frontend Coverage Merge and Coverage Gate had no shard artifact to merge - and
Backend Tests (3.12, 3) failed only in test/test_pod_windows_run.py
(the Task Scheduler pod backend is win32-only; this host is linux), a file this diff
never touches and which passed on the other eleven shards.

The Opus advisory is fixed. _connect_to_a_screened_address returned
create_connection((approved[0], port), ...), so pinning the address also pinned the
download to the FIRST answer: a host with two A records whose first server is down, or an
AAAA listed ahead of an A on an install with no working IPv6 route, failed outright where
the catalog path (plain connection, no screen) falls back. Every entry in approved is
already screened public, so the hook now tries them in turn and raises the last error, as
the stdlib does. Nothing about the pin widens.

Why kirocrew doctor now prints model URLs host-only, and why the pin that defended the
path no longer holds.
Declared item 6 above stated the output change; it did not state
that it REVERSES a recorded decision. The deleted comment in embeddings.py read
"Deliberately NOT asset_downloader.redact_url, which drops the path too: kirocrew doctor prints this to tell the operator WHICH model file resolved", and its reasoning was
that "the model url's path is the operator's own override ... never a value a remote party
chose". That premise is what this PR breaks: a CUSTOM model URL is followed through
redirects, so the value doctor prints can be a path a remote server chose in a
Location, and a path segment is a place a credential fits. Keeping a path-preserving
reduction for one caller would mean the same operator-facing line is safe on the catalog
path and unsafe on the custom one, so the reduction is host-only for both. The cost is
real and is the trade being declared: doctor no longer names which model file resolved,
only the host it came from.

temp-screenshots/ is out of the branch. The three PNGs under
temp-screenshots/stt-custom-model/ are deleted, as the sixth round said they would be
once the evidence moved to user-attachments. The attachments in this description carry
it; the binaries had no remaining purpose.

Tests for this round

  • pytest test/test_stt_custom_model.py test/test_stt_engine.py test/test_stt_stream.py test/test_security_posture.py -q -> 341 passed, 18 skipped, exit 0.
  • New test_a_dead_first_address_falls_back_to_the_next_screened_one drives the
    _create_connection hook with two public answers and the first one refusing, and
    asserts BOTH were tried. Mutation-proved: with the loop narrowed back to
    approved[:1] it fails with OSError: connection refused while the rebind control
    beside it still passes.
  • I18N_BASE_REF=origin/main npx vitest run src/i18n/style/frStyle.test.ts -> 4 passed,
    the [changed-values] case among them rather than skipped.
  • black --check, isort --check-only, flake8, mypy on the changed files: all exit 0.

The remaining blocker is unchanged and still not mine to close

GPT's fenced F1 is the residual this description has named since the sixth round: the
custom URL and its sha256 pin both live in config.json, so the same writer picks the
bytes and the pin they are checked against. Closing it is a product-shape decision -
either the pair moves to an operator-only surface, which costs the Settings rows, or a
maintainer accepts config residency and records the residual. The UX lane's remaining
watch items (a rejection line when the backend drops a malformed value, and the
no-query-string rule in the URL helper text) are deliberately left until that decision
lands: both are copy on the Settings rows that option (a) would delete.

@LuisBrel
LuisBrel requested review from a team and Zedmor September 3, 2026 21:54
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 3, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 7610589 to 1c737ad Compare September 3, 2026 22:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 3, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 2c2e72a to eae0278 Compare September 4, 2026 01:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 5def2c5 to 58c2244 Compare September 4, 2026 02:00
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🔴 BLOCK

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

UX-Verdict: BLOCK

cannot evaluate: missing screenshots of this revision — attachments 1 and 3 render "This model is already on this machine.", a string this diff never renders.

Blockers

  • Evidence and code disagree on what ships. The locale diff adds "model_downloaded": "This model is already on this machine." to 13 locales, but no TSX in the patch or base tree renders that key (the present branch in SttSettings.tsx:804-809 deliberately renders null), while attachment-01.png and attachment-03.png both display the sentence — so those captures came from another build, and the PR body's frame-1 caption describes a line that will not ship. Every custom-model user hits the settled state; either a designed confirmation was lost in a dropped hunk, or 13 dead strings plus stale captures merged. Fix: reconcile (restore the render or delete the keys), rebuild, and re-capture with capture-stt-custom-model.mjs.

Watch

  • During a custom download the panel shows "Downloading the speech model: 0% (X of 0 B)" with the bar stuck at 0%: on_progress(written, expected_size) passes the custom row's expected_size 0, and downloadLabel formats it as "0 B". Every first custom fetch — a multi-hundred-MB transfer that looks hung, the exact misread the unsized prompt branch was written to avoid. Add an unsized progress variant (bytes-so-far, indeterminate bar) when total is 0.

Evidence gaps

  • The settled custom-present state as this code renders it (nothing below the SHA-256 row) — attachment-01.png fails to close it (other build); re-capture frame 1 from this revision.
  • The half-pair degraded state as this code renders it (explanation line alone) — attachment-03.png fails to close it (same phantom line stacked beneath the explanation); re-capture frame 3.

Suggestions

  • Render custom_model_incomplete in text-warn like the adjacent model_slow_on_cpu, not text-muted — it is the only thing explaining why the select snapped away from the user's click.
  • If the model_downloaded line is restored, suppress it while the incomplete-pair line shows: "this model is already on this machine" directly under "a custom model cannot be used" reads as a contradiction.

[UX-REVIEWED] 8217d90

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 8217d90f84e52d0847044f01f81f9dde29ccc17c 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

The redaction consolidation silently reverses a pinned decision: kirocrew doctor loses the model path its deleted comment kept "deliberately", and the description calls it an import swap.

Not justified as shipped

  • Item 8 — deleted pin, undeclared: the diff deletes embeddings.redact_model_url whose docstring pinned "Deliberately NOT asset_downloader.redact_url, which drops the path too: kirocrew doctor prints this to tell the operator WHICH model file resolved… never a value a remote party chose", then repoints doctor at the path-dropping form; the description says only "kirocrew doctor imports this module directly".
    Subtraction: shrink the consolidation — keep a path-bearing reduction for doctor's terminal diagnostic; migrate only the log/API sinks.
    Clears when: evidence the pin was wrong for doctor (a surface where its printout leaves the operator's terminal), or doctor keeps the path.
  • Item 2 — one consumer, generalized: stream_pinned_payload has 2 callers (stt/models.py:413, stt/decoder.py:416); only one passes max_bytes, always _CUSTOM_MAX_BYTES.
    Subtraction: delete the max_bytes parameter; apply _CUSTOM_MAX_BYTES inside stream_pinned_payload when expected_size is 0.
    Clears when: the parameter is folded, or a second caller passes a different bound.
  • Item 9 — undeclared: two new SEL operation names (stt.custom_model, stt.custom_model.read) the description never mentions.
  • Item 10 — rides along: the non-object-body 400 fixes a pre-existing 500 the description never mentions.

What this change ships

Inventory (10 items) — 6 justified

Intent: let an operator run any whisper.cpp ggml model by supplying their own URL + sha256 pin — an ADDITION.

  1. stt.model: custom plus URL/digest pair fetches and verifies a user-supplied model on the existing pinned path — justified
  2. Custom transfers capped at 8 GiB via a new max_bytes parameter — one consumer, generalized
  3. Settings → Voice gains a Custom option, two input rows, and a degrade explanation — justified
  4. The custom pair is owner-only on GET/PUT /api/config/stt (403 for apps and non-owner dashboards) — justified
  5. Custom downloads refuse private addresses (configured URL and every redirect hop, pinned at the socket) and refuse https_proxy — justified
  6. New KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE env var re-admits one named private origin — justified
  7. Every model/decoder download now refuses a redirect off https (catalog path included) — justified
  8. kirocrew doctor prints the embedding model URL host-only, dropping the path; redactor moved to new url_redaction.py — deleted pin, description silent
  9. New SEL audit rows for custom-model reads (both branches) and admitted writes — undeclared
  10. PUT /api/config/stt returns 400 instead of 500 on a non-object JSON body — rides along

More than 10 differences exist (screenshot harness, registry/i18n regeneration, resolve off-loop moves); these are the 10 most noticeable.

[FIRST-PRINCIPLES-REVIEWED] 8217d90

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The rewired HTTPS transport has never carried one real download — pinned-socket TLS/SNI behavior against a live server is unproven; only socket-stub tests ran.

Watch

  • The custom path replaces http.client internals (_create_connection instance-attribute hook, private _tunnel_host, connect-to-IP-while-verifying-hostname). Stubbed-socket tests exercise the logic but cannot prove real DNS/TLS/CDN-redirect behavior — and the description's "it exercises no code this PR adds" is wrong for the fetch half: a real fetch exercises exactly _urlopen, _PinnedAddressHTTPSConnection, and _HttpsOnlyRedirectHandler. If the pin breaks live TLS, every first custom download fails identically. Reversible and feature-scoped (catalog is untouched), hence CONCERNS.
    Clears when: one manual fetch of a real hosted ggml artifact through _download_blocking (ideally one direct, one via an HF-style cross-origin redirect) is reported on the PR.
  • resolve() was a pure in-memory lookup and now performs a synchronous config.json read for custom, so four async call sites gained to_thread wrappers — but nothing structural stops the next event-loop caller from invoking it inline and reintroducing the gateway stall this PR patched at each site (the stream-probe test pins only those two sites).
    Clears when: the custom pair is passed into resolve from a caller that already holds config, or a test/lint pins that no event-loop call site invokes resolve inline.

[DESIGN-REVIEWED] 8217d90

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 8217d90

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 8217d90

@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 58c2244 to 640d44d Compare September 4, 2026 04:19
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 037761f to 31a9382 Compare September 4, 2026 10:11
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 31a9382 to 7c93ac8 Compare September 4, 2026 11:29
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 7c93ac8 to 23ac1d5 Compare September 4, 2026 13:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 2026
@LuisBrel
LuisBrel force-pushed the feat/stt-custom-model branch from 23ac1d5 to 63fa15c Compare September 4, 2026 14:07
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 4, 2026
stt.model = 'custom' runs a whisper.cpp ggml model from stt.custom_model_url, verified against a caller-supplied stt.custom_model_sha256.

The digest is enforced exactly as a catalog pin is: https only, computed while streaming, written to the write-protected models directory only after it matches, and re-hashed on every load. A custom model has no published size, so the transfer's size pre-check falls back to an absolute ceiling instead of being dropped.

An absent or malformed pair degrades to the default model with a warning rather than raising into a voice session.

Review follow-ups folded in: the download is refused rather than persisted when the URL
carries a credential (userinfo, query string or fragment); the settings states are captured
as committed evidence; and the `custom_model_url` comment now states what `valid_custom_url`
actually does -- it REFUSES userinfo, query and fragment, and the residual it cannot refuse
is a token embedded in a path segment, which is why the field is marked sensitive.

Two more review findings answered:

`session.pending_load()` is now offloaded with `asyncio.to_thread`, like its sibling
`pending_download` two lines above it. Both call `models.resolve`, and resolving the
`custom` selection reads and jsonschema-validates `config.json`, so leaving one inline
kept the blocking read on the single gateway event loop for exactly the session shape
this feature adds -- a downloaded custom model with a cold engine, which is the path
`pending_download` returning None leads to. Pinned on the thread each probe runs on,
because an inline call and an offloaded one are indistinguishable by call count.

`KIROCREW_STT_CUSTOM_MODEL_ALLOW_PRIVATE` now names the one private origin the operator
authorises (`https://mirror.internal:8443`) instead of switching the address screen off.
Read as a boolean it authorised the operator's own mirror by disabling the screen, which
authorised every other private address at the same time -- through `stt.custom_model_url`,
the agent-reachable config value the screen exists to distrust. So the air-gapped install
was the one install where a rewritten URL could reach an arbitrary internal service.
Compared on origin, so a co-located service on another port of the mirror host is not the
mirror; a value that is not a parseable https origin matches nothing and disables nothing.
… field

`valid_custom_sha256` took only a bare 64-hex string, so the two forms a
user actually has in the clipboard -- a published `sha256:<hex>` and
`sha256sum`'s own `<hex>  <file>` line -- were refused. The refusal was
silent and looked like data loss rather than validation: the save response
omits the field and the settings row is reset from it, so the typed value
disappeared and the only feedback said both the URL and the SHA-256 were
needed, which names the thing the user had just entered.

Unwrapping a carrier is not widening the accepted set. The payload still
has to be exactly 64 hex characters, so `sha256:` on a 63-hex digest, a
bare prefix, and a file name in the first field are all still refused --
pinned as cases, not just as the happy path.

Copy link
Copy Markdown
Contributor

Closing as a duplicate of #14918 (open), the in-repo replacement for this fork PR. Its description says "Supersedes #8281", and it keeps @LuisBrel's authorship.

Evidence (diffs from git, origin/main af1eb612da):

This branch is 1943 commits behind main and conflicts with it (dirty). If the maintainers choose a different design on #14918, the work can continue there or this PR can be reopened.

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