[MODSetter]

What

pnpm build:audiocpp (stage.mjs) now stages audio.cpp again when the staged server lacks a curated family. Before, it kept any staged server as it was.

• built-families.mjs reads each family's probe as built, missing (the server refuses it by name) or unknown (the server never got that far). verifyBuiltFamilies now puts the server's own output in its error.

• New staged-server.mjs decides whether the staged server is absent, current or stale. stage.mjs keeps a current one and stages a stale one again.

• Without --strict, a stale server is kept, with a warning naming what it lacks, in three cases:

  • no toolchain is installed;
  • the app holds electron/audiocpp/ (checked before compiling, so no 5-minute compile is wasted);
  • staging again fails.

  pnpm dev then goes on with every family the server has. With --strict, as in CI and release, each case fails.

• packaging.md and the proposal describe the rule.

Why

#2273 added Canary 180M Flash (canary_asr) to FAMILIES. A checkout staged before that kept its old server, so choosing Canary failed on every phrase:

TranscriptionUnavailableError: unsupported model family hint: canary_asr

Developers had to know to delete electron/audiocpp/ by hand. Canary was also measured only on an Apple M2, where staging downloads upstream's archive, which has every family. This PR is the first time it was compiled and run on Windows.

Fixes #

How to test

• Unit tests: node --test scripts/audiocpp/*.test.mjs scripts/msvc-runtime.test.mjs in surfsense_local/electron gives 27 pass. The new tests cover the three probe verdicts and the absent, current, stale and did-not-run decisions.

• On Windows (Ryzen 7 5800X, MSVC 19.42, MinGW CMake first on PATH), with the old four-family build staged:

  • stage.mjs said "was built without canary_asr; staging it again". It compiled all five families in 4.5 min, and a rerun said "already staged".
  • With a process holding the folder, it stopped before compiling, said the folder is in use and kept the build (exit 0).
  • Without CMake on PATH it kept the build with the install command (exit 0); with --strict it exited 1.

• Canary on that Windows build, through the app's own path: the engine wrote transcription.json, the sidecar's flags were used, AudioCppTranscriber sent the Settings language, and cleaned() ran.

  Clip	Length	Time	Word error
  English, Kokoro	12.5 s	0.69 s	0%
  French, Kokoro	9.2 s	0.63 s	0%
  English, LibriSpeech	24.7 s	1.23 s	0%

  Peak memory was 718 MiB. The silent warm-up with no language succeeds.

• Packaging test: tests/packaging/test_audiocpp_transcription_config.py[canary-180m-flash] passes against this build.

High-level PR Summary

This PR fixes an issue where the audio.cpp build staging script would keep an outdated server that was missing newly added model families (like canary_asr), causing runtime errors. The build system now probes staged servers to verify they contain all curated families and automatically re-stages when families are missing. In non-strict mode, stale servers are kept with warnings when toolchains are unavailable or compilation fails, allowing development to continue with existing families. The change includes comprehensive unit tests and updates documentation to reflect the new behavior.

⏱️ Estimated Review Time: 5-15 minutes

💡 Review Order Suggestion

Order	File Path
1	surfsense_local/electron/scripts/audiocpp/built-families.mjs
2	surfsense_local/electron/scripts/audiocpp/built-families.test.mjs
3	surfsense_local/electron/scripts/audiocpp/staged-server.mjs
4	surfsense_local/electron/scripts/audiocpp/staged-server.test.mjs
5	surfsense_local/electron/scripts/audiocpp/stage.mjs
6	docs/architecture/packaging.md
7	docs/proposals/local-speech-to-text.md

Summary by CodeRabbit

• Bug Fixes
  • Audio server staging now checks that the existing server supports all curated model families and rebuilds it when support is missing or cannot be verified.
  • If rebuilding a stale server isn’t possible, non-strict mode preserves it and displays a warning; strict mode reports the failure. Staging also detects when the server folder is locked.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
surf-sense-frontend	Ready	Preview	Oct 15, 2026 11:37pm UTC

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: MODSetter/SurfSense/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 87eddcc9-0317-4d90-91fa-bdc14e12164e

📥 Commits

Reviewing files that changed from the base of the PR and between 3133d68 and be961a5.

📒 Files selected for processing: 7

• docs/architecture/packaging.md
• docs/proposals/local-speech-to-text.md
• surfsense_local/electron/scripts/audiocpp/built-families.mjs
• surfsense_local/electron/scripts/audiocpp/built-families.test.mjs
• surfsense_local/electron/scripts/audiocpp/stage.mjs
• surfsense_local/electron/scripts/audiocpp/staged-server.mjs
• surfsense_local/electron/scripts/audiocpp/staged-server.test.mjs

+-----------------------------------------------------------------------------------------------------------+
| A CodeRabbit review a day keeps the merge cop away: https://x.com/ThePrimeagen/status/1986151686839116209 |
+-----------------------------------------------------------------------------------------------------------+
  \
   \     /)/)
        ( '')
        /  |
      o(___)

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}