feat(recorder): on-device recorder host + whisper transcription + chat/RAG

.claude/agents/device-verifier.md

@@ -0,0 +1,33 @@
+---
+name: device-verifier
+description: Prove a change works on the physical device — build, install, pull the debug log, grep the state-machine traces. Use when a fix needs on-device evidence rather than a passing test. Runs ONE AT A TIME (there is a single device) and only in the main checkout.
+tools: Bash, Read, Grep, Glob
+---
+
+You confirm behaviour on real hardware. You do not design or refactor.
+
+## Hard constraints
+
+- **Main checkout only.** Never run in a git worktree: a fresh worktree has no `pro/` submodule
+  checkout and no gradle/CocoaPods cache, so the build is cold and the artifact paths differ.
+- **One instance at a time.** There is one connected device. Two of you racing `adb install`
+  or reading the log leaves both traces interleaved and useless.
+- **Install is pre-authorized, building is not.** If `adb devices` shows a device after a build,
+  install it yourself with `adb install -r`. Do not kick off a build the user didn't ask for.
+
+## The loop
+
+1. Build only what the user asked for.
+2. Install (Android: `adb install -r`; iOS: the Debug config, bundle id `ai.offgridmobile.dev`).
+3. Pull the log — see the **Device Logs** section of `CLAUDE.md` for the exact
+   `devicectl` / `adb pull` commands. Do not re-derive them and do not hardcode a device UDID.
+4. **Read only the live-session tail** — from the last `===== session start =====` marker
+   forward. Never dump the whole file.
+5. Grep the relevant state machine (`[TTS-SM]`, `[GEN-SM]`, `[MODEL-SM]`, `[DL-SM]`,
+   `[ROUTE-SM]`, `[IMG-SM]`, `[MEM-SM]`, `[FAIL-SM]`) and quote the lines that decide the question.
+
+## Reporting
+
+Return the log lines that prove or disprove the claim, then your verdict. If the trace is absent
+or ambiguous, say so — an absent line is not evidence of success. Never infer device behaviour
+from source code when you were asked to verify it on the device.

.claude/agents/pro-feature.md

@@ -0,0 +1,42 @@
+---
+name: pro-feature
+description: Implement or change a Pro feature (locket/recorder, TTS, MCP tools, speaker ID, any paid surface). Keeps the edit inside the pro/ submodule and keeps Pro code out of the public core repo. Use for any work whose files land under pro/.
+tools: Bash, Read, Edit, Write, Grep, Glob, Skill
+---
+
+You work on the Pro surface. Your job includes keeping the open-core boundary intact.
+
+## Where code goes
+
+Read `pro/CLAUDE.md` first — it is the contract for this submodule. Core only wires Pro in
+through the slot/hook registries and never imports Pro code directly.
+
+- Feature code, its native Kotlin/Swift, and its tests live under `pro/`.
+- The only legitimate change in core is registry wiring.
+- If a change seems to need core edits beyond wiring, that is a signal the seam is wrong.
+  Say so instead of reaching into core.
+
+## The boundary (this is the part that gets violated)
+
+Never let these reach the public core repo:
+
+- `docs/plans/*.md` — architecture, handoff, and R&D docs stay out of core entirely.
+- Tests that `import` from `pro/` — they belong in the pro repo.
+- Any Pro implementation detail leaking upward into a core screen, store, or service.
+
+Before you finish, `git status` core and confirm the only staged core files are registry wiring.
+
+## Branches and PRs
+
+`pro/` is its own git repo (`@offgrid/pro`). A Pro change is a **separate branch and separate PR
+in that repo**, stacked on the relevant pro base branch — not a commit onto an existing shared
+branch, and not folded into the core PR. Confirm the remote and base branch before pushing;
+the pro remote is not `origin`.
+
+## Standards
+
+Follow the repo standards in `CLAUDE.md` — they apply inside `pro/` too. Use the `hygiene` skill
+when designing a new subsystem and the `tests` skill when writing or fixing a test. Do not
+restate those rules here; load the skill.
+
+Commit each cohesive green step. Do not commit or push without explicit instruction.

.github/workflows/uat-dev.yml

@@ -70,12 +70,12 @@ jobs:
       - uses: ruby/setup-ruby@v1
         with: { ruby-version: '3.3', bundler-cache: true }
       - name: pod install
-        # Restore Podfile.lock afterward: a CI CocoaPods version can rewrite it, which would
-        # dirty the tree and trip uat.sh's clean-tree pre-check. The pods are already installed,
-        # so the lock's content doesn't affect the build.
-        run: |
-          cd ios && pod install
-          cd .. && git checkout -- ios/Podfile.lock 2>/dev/null || true
+        # Do NOT restore Podfile.lock afterward. CI's CocoaPods can rewrite it (e.g. the fmt patch),
+        # and the archive's "[CP] Check Pods Manifest.lock" phase compares Podfile.lock against the
+        # freshly generated Pods/Manifest.lock — restoring the committed lock makes them diverge and
+        # fails the archive. Let the regenerated lock stand (it matches Manifest.lock); uat.sh's
+        # clean-tree check whitelists ios/Podfile.lock so this no longer trips the pre-check.
+        run: cd ios && pod install
       - name: Decode signing secrets
         run: |
           echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > "$RUNNER_TEMP/release.keystore"

.gitignore

@@ -86,6 +86,11 @@ fastlane/*.p8
 !.yarn/sdks
 !.yarn/versions
 docs/TRACTION_KNOWLEDGE_BASE.md
+# Dev-only insights sim harness + private real recordings (never commit)
+/sim/
+# Debug screenshots (scratch)
+/image.png
+/image-*.png
 # Local marketing drafts (not part of the app)
 marketing/
 
@@ -94,3 +99,20 @@ docs/DEVICE_SESSION_COMMENTARY.md
 
 # Device wire-capture logs (raw, large, session-specific — kept locally, not versioned)
 docs/wire-captures/
+
+# On-device diarization embedder model (test build; ~28MB)
+pro/android/src/main/assets/diar/
+poc-archive/
+android/app/src/main/assets/cactus-models/
+pro/android/src/main/jniLibs/arm64-v8a/libsherpa-onnx-jni.so
+
+# Built app binaries. These land in the repo root from a local/BrowserStack build run
+# (whisper-npu-s23.apk was 803MB, OffgridMobile.ipa 75MB) and were untracked but NOT
+# ignored - one `git add .` from being committed into a repo whose .git is already ~9GB.
+*.apk
+*.aab
+*.ipa
+pro/android/libs/sherpa-onnx-static-1.13.4.jar
+
+# Local Claude Code skill lockfile - machine state, not project config.
+skills-lock.json

.husky/pre-push

@@ -47,6 +47,16 @@ if [ -n "$PUSHED_JS" ]; then
   echo "▶ TypeScript type check..."
   npx tsc --noEmit
 
+  # The root tsconfig EXCLUDES pro/** (the public repo's CI does not check the submodule out), so
+  # the check above only sees a pro file when a core file imports it - and pro screens are reached
+  # through the registry at runtime, not by an import. That left every pro-only screen, hook and
+  # service completely untypechecked on push; two real errors were sitting in the tree unseen.
+  # pro has its own tsconfig, so run it too whenever the submodule is actually present.
+  if [ -f pro/tsconfig.json ]; then
+    echo "▶ TypeScript type check (pro submodule)..."
+    npx tsc --noEmit -p pro/tsconfig.json
+  fi
+
   echo "▶ JS/TS tests (related to changed files)..."
   echo "$PUSHED_JS" | tr '\n' '\0' | xargs -0 npx jest --findRelatedTests --passWithNoTests
 

App.tsx

@@ -17,6 +17,7 @@ import logger from './src/utils/logger';
 import { useAppStore, useAuthStore, useRemoteServerStore, useWhisperStore } from './src/stores';
 import { useDebugLogsStore } from './src/stores/debugLogsStore';
 import { initDebugLogFile, appendDebugLine } from './src/utils/debugLogFile';
+import { warmUpPackagerLocalNetwork } from './src/utils/packagerLocalNetworkWarmup';
 import { loadProFeatures } from './src/bootstrap/loadProFeatures';
 import { checkProStatus } from './src/services/proLicenseService';
 import { hydrateDownloadStore } from './src/services/downloadHydration';
@@ -31,6 +32,7 @@ import { LockScreen } from './src/screens';
 import { useAppState } from './src/hooks/useAppState';
 import { useDownloadStore } from './src/stores/downloadStore';
 import { ErrorBoundary } from './src/components/ErrorBoundary';
+import { Toast } from './src/components';
 
 LogBox.ignoreAllLogs(); // Suppress all logs
 
@@ -69,10 +71,19 @@ const ensureRemoteServerStoreHydrated = async () => {
 
 function App() {
   useDownloadListeners();
+  // Dev iOS only: re-issue RN's packager probe now that we have a foreground UI,
+  // so iOS can actually present the Local Network permission alert it refuses to
+  // show during didFinishLaunchingWithOptions. See packagerLocalNetworkWarmup.ts.
+  useEffect(() => {
+    void warmUpPackagerLocalNetwork();
+  }, []);
   // Reactive: when Pro is activated at runtime (license key → loadProFeatures),
   // the appRoot slot (TTS engine bridge) registers and this re-renders to mount
   // it live — no restart needed.
   const AppRoot = useSlot(SLOTS.appRoot);
+  // Root-mounted recorder prompt (the speech-model download sheet). Its own slot, because
+  // appRoot already holds the TTS engine bridge and a slot maps to ONE component.
+  const SttModelPrompt = useSlot(SLOTS.sttModelPrompt);
   const [isInitializing, setIsInitializing] = useState(true);
   const setDeviceInfo = useAppStore((s) => s.setDeviceInfo);
   const setModelRecommendation = useAppStore((s) => s.setModelRecommendation);
@@ -359,6 +370,7 @@ function App() {
       <SafeAreaProvider>
         <SystemBars style={isDark ? 'light' : 'dark'} />
         {AppRoot ? <AppRoot /> : null}
+        {SttModelPrompt ? <SttModelPrompt /> : null}
         <NavigationContainer
           theme={{
             dark: isDark,
@@ -392,6 +404,7 @@ function App() {
         >
           <AppNavigator />
         </NavigationContainer>
+        <Toast />
       </SafeAreaProvider>
     </GestureHandlerRootView>
   );

__tests__/harness/nativeBoundary.ts

@@ -559,6 +559,21 @@ export interface WhisperFake {
   holdNextLoad(): void;
   /** Release a load held via holdNextLoad(). No-op if not held. */
   releaseLoad(): void;
+  /** HOLD the next file transcribe (context.transcribe) open until releaseTranscribe() - the
+   *  device-shaped window a real whole-file transcribe occupies (tens of seconds), so anything
+   *  that runs DURING an in-flight transcription (e.g. an iOS memory warning) is observable.
+   *  One-shot. */
+  holdNextTranscribe(): void;
+  /** Resolve a transcribe held via holdNextTranscribe(). No-op if not held. */
+  releaseTranscribe(): void;
+  /** True while a held transcribe is still in flight (never resolved, never stopped). */
+  transcribeInFlight(): boolean;
+  /** Script the ggml Silero VAD (initWhisperVad → ctx.detectSpeech) the locket declutter/trim scan uses.
+   *  Segments are VadSegment[] with t0/t1 in CENTISECONDS (vadDetect maps t*10 → ms). Default = one 0–30s
+   *  speech run; setVadSegments([]) models silence (→ 'none'); scriptVadThrow() makes EVERY detectSpeech
+   *  throw — the swallowed per-chunk error the fail-open path must treat as 'unknown', never as silence. */
+  setVadSegments(segs: Array<{ t0: number; t1: number }>): void;
+  scriptVadThrow(throwIt?: boolean): void;
 }
 
 function makeWhisperFake(): WhisperFake {
@@ -568,13 +583,38 @@ function makeWhisperFake(): WhisperFake {
   // Load hold: opens the in-flight model-load window a real (seconds-long) ggml init has.
   let loadHoldPending = false;
   let loadHoldRelease: (() => void) | null = null;
+  let txHoldPending = false;
+  let txHoldResolve: ((v: unknown) => void) | null = null;
+  // ggml Silero VAD (initWhisperVad → ctx.detectSpeech), used by the locket declutter/trim scan.
+  let vadSegments: Array<{ t0: number; t1: number }> = [{ t0: 0, t1: 3000 }]; // default: 0–30s speech (centiseconds)
+  let vadThrows = false;
+  const vadContext: Record<string, jest.Mock> = {
+    detectSpeech: jest.fn(async () => {
+      if (vadThrows) throw new Error('detectSpeech failed (native VAD error)');
+      return vadSegments;
+    }),
+    release: jest.fn(async () => {}),
+  };
   const context: Record<string, jest.Mock> = {
     // Faithful to whisper.rn: transcribe(path, opts) returns { stop, promise }, the promise resolving to
     // { result, segments } — this is the method whisperService.transcribeFile (the voice-mode file path) drives.
-    transcribe: jest.fn((_path: string) => ({
-      stop: jest.fn(async () => {}),
-      promise: Promise.resolve({ result: fileTranscript, segments: [{ text: fileTranscript, t0: 0, t1: 100 }] }),
-    })),
+    transcribe: jest.fn((_path: string) => {
+      const done = { result: fileTranscript, segments: [{ text: fileTranscript, t0: 0, t1: 100 }] };
+      if (!txHoldPending) {
+        return { stop: jest.fn(async () => {}), promise: Promise.resolve(done) };
+      }
+      txHoldPending = false;
+      // Parked until releaseTranscribe() - or until stop(), which is what unloadModel calls to
+      // cancel the native job. whisper.rn surfaces that cancellation as Code: -999.
+      const promise = new Promise((res) => { txHoldResolve = res; });
+      return {
+        stop: jest.fn(async () => {
+          const f = txHoldResolve; txHoldResolve = null;
+          f?.({ result: '', segments: [], isAborted: true });
+        }),
+        promise,
+      };
+    }),
     transcribeFile: jest.fn(async () => ({ result: fileTranscript, segments: [{ text: fileTranscript, t0: 0, t1: 100 }] })),
     transcribeRealtime: jest.fn(async () => {
       rtActive = true; // native mic session starts capturing
@@ -597,11 +637,15 @@ function makeWhisperFake(): WhisperFake {
       return context;
     }),
     releaseAllWhisper: jest.fn(async () => {}),
+    // Named export the locket VAD path imports: `import { initWhisperVad } from 'whisper.rn'`.
+    initWhisperVad: jest.fn(async () => vadContext),
     // Some call sites read module-level too; mirror the context.
     transcribeFile: context.transcribeFile,
   };
   return {
     module,
+    setVadSegments: (segs: Array<{ t0: number; t1: number }>) => { vadSegments = segs; },
+    scriptVadThrow: (throwIt = true) => { vadThrows = throwIt; },
     emitRealtime: ({ text, isCapturing, recordingTime, noData }) => {
       if (!realtimeCb) return;
       realtimeCb({
@@ -616,6 +660,12 @@ function makeWhisperFake(): WhisperFake {
     realtimeActive: () => rtActive,
     holdNextLoad: () => { loadHoldPending = true; },
     releaseLoad: () => { const f = loadHoldRelease; loadHoldRelease = null; f?.(); },
+    holdNextTranscribe: () => { txHoldPending = true; },
+    releaseTranscribe: () => {
+      const f = txHoldResolve; txHoldResolve = null;
+      f?.({ result: fileTranscript, segments: [{ text: fileTranscript, t0: 0, t1: 100 }] });
+    },
+    transcribeInFlight: () => txHoldResolve != null,
   };
 }
 
@@ -704,6 +754,44 @@ function makeFsFake(): FsFake {
   return { module, seedFile, seedDir, DocumentDirectoryPath };
 }
 
+// ---------------------------------------------------------------------------
+// Fake: AudioNormalizer (NativeModules.AudioNormalizer) — the native WAV slicer/concat/compressor the
+// locket VAD scan (extractWavSlice) and trim (concatWavSlices/compressToAac/normalizeToWav16kMono) use.
+// Each op WRITES its output to the (memfs) disk so the real downstream reads (stat/exists/unlink) find a
+// file — outputs are device-shaped SIZES derived from the args, so the real trim math runs on top.
+// Needs the fs fake to seed; install with { fs: true, audio: true }.
+// ---------------------------------------------------------------------------
+
+export interface AudioNormalizerFake { module: Record<string, jest.Mock>; }
+
+function makeAudioNormalizerFake(seedFile?: (path: string, sizeBytes: number) => void): AudioNormalizerFake {
+  // 16k mono 16-bit PCM = 32000 bytes/sec — used to size slice/concat outputs realistically.
+  const pcmBytes = (ms: number) => 44 + Math.max(0, Math.round((ms / 1000) * 32000));
+  let n = 0;
+  const module: Record<string, jest.Mock> = {
+    extractWavSlice: jest.fn(async (_src: string, _startMs: number, durationMs: number) => {
+      const p = `/docs/slice-${++n}.wav`;
+      seedFile?.(p, pcmBytes(durationMs));
+      return p;
+    }),
+    concatWavSlices: jest.fn(async (_src: string, ranges: Array<{ startMs: number; durationMs: number }>, outPath: string) => {
+      const kept = ranges.reduce((a, r) => a + (r.durationMs || 0), 0);
+      seedFile?.(outPath, pcmBytes(kept));
+      return outPath;
+    }),
+    compressToAac: jest.fn(async (_src: string, outPath: string) => {
+      const sizeBytes = 50_000; // a small AAC backup
+      seedFile?.(outPath, sizeBytes);
+      return { path: outPath, sizeBytes };
+    }),
+    normalizeToWav16kMono: jest.fn(async (_in: string, outPath: string) => {
+      seedFile?.(outPath, 5_000_000);
+      return outPath;
+    }),
+  };
+  return { module };
+}
+
 // ---------------------------------------------------------------------------
 // installNativeBoundary — seed the set, then freshly require services/stores on top.
 // ---------------------------------------------------------------------------
@@ -723,6 +811,9 @@ export interface InstallOpts {
   download?: boolean;
   /** Replace the global whisper.rn stub with a driveable STT context (boundary.whisper). */
   whisper?: boolean;
+  /** Seed the native AudioNormalizer (WAV slice/concat/compress) — the locket VAD-scan + trim boundary.
+   *  Needs { fs: true } (its outputs are written to the memfs disk). */
+  audio?: boolean;
 }
 
 export interface NativeBoundary {
@@ -739,6 +830,8 @@ export interface NativeBoundary {
   download?: DownloadFake;
   /** Driveable whisper STT context — present only when installed with { whisper: true }. */
   whisper?: WhisperFake;
+  /** Native AudioNormalizer (WAV slice/concat/compress) — present only when installed with { audio: true }. */
+  audio?: AudioNormalizerFake;
   /** Re-read RAM at the leaf mid-test (e.g. simulate OS pressure between a pre-check and the load). */
   setRam(profile: RamProfile): void;
   /** Fire the OS 'memoryWarning' AppState event the app's residency manager listens to (auto-eviction). */
@@ -787,13 +880,17 @@ export function installNativeBoundary(opts: InstallOpts = {}): NativeBoundary {
   const whisperFake = opts.whisper ? makeWhisperFake() : undefined;
   if (whisperFake) jest.doMock('whisper.rn', () => whisperFake.module);
 
+  // Native AudioNormalizer (WAV slice/concat/compress) — outputs written to the memfs disk.
+  const audioFake = opts.audio ? makeAudioNormalizerFake(fsFake?.seedFile) : undefined;
+
 
   const RN = require('react-native');
   RN.NativeModules.LiteRTModule = litert.module;
   // Both platform names point at the same fake; localDreamGenerator's Platform.select picks one.
   RN.NativeModules.LocalDreamModule = diffusion.module;
   RN.NativeModules.CoreMLDiffusionModule = diffusion.module;
   if (downloadFake) RN.NativeModules.DownloadManagerModule = downloadFake.module;
+  if (audioFake) RN.NativeModules.AudioNormalizer = audioFake.module;
   // Mic permission is a device boundary: whisper STT refuses to start recording without RECORD_AUDIO
   // granted (whisperService.requestPermissions → PermissionsAndroid.request). Grant it when whisper is
   // installed so the real STT flow runs; the default jest PermissionsAndroid returns undefined (= denied).
@@ -856,5 +953,5 @@ export function installNativeBoundary(opts: InstallOpts = {}): NativeBoundary {
     Object.defineProperty(RN.Platform, 'Version', { value: profile.platform === 'android' ? 34 : '17.0', configurable: true });
   };
 
-  return { litert, litertEvents: handle, diffusion, fs: fsFake, llama: llamaFake, download: downloadFake, whisper: whisperFake, setRam, emitMemoryWarning: () => appState.handle.emit('memoryWarning') };
+  return { litert, litertEvents: handle, diffusion, fs: fsFake, llama: llamaFake, download: downloadFake, whisper: whisperFake, audio: audioFake, setRam, emitMemoryWarning: () => appState.handle.emit('memoryWarning') };
 }