discoclaw 1.2.3 → 1.3.0

package/.context/voice.md

@@ -29,10 +29,16 @@ Two native npm packages power the Discord voice integration:
 | `src/voice/transcript-mirror.ts` | Posts user transcriptions and bot responses to a text channel |
 | `src/voice/voice-action-flags.ts` | Restricted action subset for voice invocations (messaging + tasks + memory only) |
 | `src/voice/conversation-buffer.ts` | Per-guild conversation ring buffer (10 turns) — stores user/model exchanges in memory; backfills from voice-log channel on join |
+| `src/voice/providers/gemini-live-types.ts` | TypeScript interfaces for Gemini Live: `GeminiLiveOpts`, `GeminiLiveEvent`, `GeminiLiveState` |
+| `src/voice/providers/gemini-live-provider.ts` | Bidirectional WebSocket session wrapper for the Gemini Multimodal Live API — connect/disconnect, audio send/receive, reconnect with exponential backoff |
+| `src/voice/providers/gemini-live-responder.ts` | Bridges `GeminiLiveProvider` audio/text events to Discord `AudioPlayer` playback and `TranscriptMirror` logging |
+| `src/voice/providers/index.ts` | Barrel re-export for Gemini Live provider modules |
 | `src/discord/actions-voice.ts` | Discord action types: `voiceJoin`, `voiceLeave`, `voiceStatus`, `voiceMute`, `voiceDeafen` |
 
 ## Audio Data Flow
 
+### Default pipeline (`voiceProvider: 'pipeline'`)
+
 ```
 User speaks in Discord voice channel
   → @discordjs/voice receiver emits Opus packets per user
@@ -47,6 +53,23 @@ User speaks in Discord voice channel
                     → AudioPlayer → Discord voice connection
 ```
 
+### Gemini Live (`voiceProvider: 'gemini-live'`)
+
+Bypasses separate STT/TTS/AI stages — Gemini handles speech recognition, reasoning, and speech synthesis in a single bidirectional WebSocket session.
+
+```
+User speaks in Discord voice channel
+  → @discordjs/voice receiver emits Opus packets per user
+    → AudioReceiver: allowlist gate → OpusDecoder (48 kHz stereo PCM)
+      → downsample to 16 kHz mono
+        → SttProvider shim → GeminiLiveProvider.sendAudio() (WebSocket)
+          → Gemini Live: STT + reasoning + TTS (server-side)
+            ← audio events (24 kHz mono PCM) + text events
+              → GeminiLiveResponder: upsampleToDiscord (48 kHz stereo)
+                → AudioPlayer → Discord voice connection
+              → onBotResponse callback → TranscriptMirror (text channel)
+```
+
 ## Key Patterns
 
 - **Allowlist gating** — `AudioReceiver` only subscribes to users in `DISCORD_ALLOW_USER_IDS`. Empty allowlist = ignore everyone (fail-closed).
@@ -56,6 +79,8 @@ User speaks in Discord voice channel
 - **Generation-based cancellation** — `VoiceResponder` increments a generation counter on each new transcription. If a newer transcription arrives mid-pipeline, the older one is silently abandoned.
 - **Barge-in** — Gated on a non-empty STT transcription result, not the raw VAD `speaking.start` event. Echo from the bot's own TTS leaking through the user's mic produces empty transcriptions and is ignored. Only when `VoiceResponder.handleTranscription()` receives a non-empty transcript while the player is active does it stop playback and advance the generation counter. This eliminates false positives from echo without relying on a static grace-period timeout.
 - **Conversation ring buffer** — `ConversationBuffer` maintains a per-guild 10-turn ring buffer of user/model exchanges that gets injected into the voice prompt as formatted conversation history. Turns are appended live during a session. On voice join, the buffer backfills from recent voice-log channel messages so context carries across disconnects. The buffer is cleared when the bot leaves the voice channel.
+- **`SttProvider` shim for Gemini Live** — In `gemini-live` mode, the pipeline still uses `AudioReceiver` for Opus decode and downsampling, but replaces the real STT provider with a lightweight shim object that implements the `SttProvider` interface. The shim's `feedAudio()` forwards PCM frames directly to `GeminiLiveProvider.sendAudio()`, while its `start()`/`stop()`/`onTranscription()` are no-ops. This reuses the existing audio-receive path without duplicating Opus decode or downsample logic.
+- **Session rotation timer** — `GeminiLiveProvider` starts a timer on each successful connection that fires at `DISCOCLAW_GEMINI_SESSION_ROTATION_MS` (default 13 min), proactively triggering a graceful reconnect before Gemini's ~15 min server-side session limit. The timer reuses the existing reconnect-with-resume-handle path (ws-039), so audio gap is minimal. The timer is cleared on disconnect and reset on each reconnect. Set to `0` to disable rotation (the server will eventually kill the session).
 - **Re-entrancy guard** — `AudioPipelineManager.startPipeline` uses a `starting` set because `VoiceConnection.subscribe()` synchronously fires a Ready state change.
 - **Error containment** — `VoiceConnectionManager` catches connection errors and destroys the connection to prevent process crashes (e.g. DAVE handshake failures).
 - **Deepgram TTS 2000-char limit** — Deepgram Aura REST TTS returns HTTP 413 (silent failure) for inputs exceeding ~2000 characters. `tts-deepgram.ts` truncates the input to 2000 chars before sending to prevent silent audio dropouts. If the AI response is unexpectedly long (e.g. from a missing `VOICE_STYLE_INSTRUCTION`), the user will still hear a truncated response rather than silence.
@@ -78,8 +103,9 @@ When `voiceEnabled=true`, the post-connect block in `src/index.ts` initializes t
 | `DISCOCLAW_VOICE_ENABLED` | `0` | Master switch |
 | `DISCOCLAW_DISCORD_ACTIONS_VOICE` | `0` | Enable voice action types |
 | `DISCOCLAW_VOICE_AUTO_JOIN` | `0` | Auto-join when allowlisted user enters |
-| `DISCOCLAW_STT_PROVIDER` | `deepgram` | STT backend |
-| `DISCOCLAW_TTS_PROVIDER` | `cartesia` | TTS backend (`cartesia`, `deepgram`, `openai`, `kokoro`) |
+| `DISCOCLAW_VOICE_PIPELINE_PROVIDER` | `pipeline` | Voice pipeline mode: `pipeline` (separate STT/AI/TTS stages) or `gemini-live` (single bidirectional Gemini WebSocket). Requires `GEMINI_API_KEY` when set to `gemini-live`. |
+| `DISCOCLAW_STT_PROVIDER` | `deepgram` | STT backend (used in `pipeline` mode only; ignored in `gemini-live` mode) |
+| `DISCOCLAW_TTS_PROVIDER` | `cartesia` | TTS backend (`cartesia`, `deepgram`, `openai`, `kokoro`) (used in `pipeline` mode only; ignored in `gemini-live` mode) |
 | `DISCOCLAW_VOICE_HOME_CHANNEL` | — | Voice audio channel name/ID used for prompt context (not transcript mirroring) |
 | `DISCOCLAW_VOICE_LOG_CHANNEL` | — | Text channel name/ID where `TranscriptMirror` posts user transcriptions and bot responses; falls back to bootstrap-provided `voiceLogChannelId` if unset |
 | `DISCOCLAW_VOICE_MODEL` | `capable` | AI model tier for voice responses |
@@ -89,5 +115,7 @@ When `voiceEnabled=true`, the post-connect block in `src/index.ts` initializes t
 | `DEEPGRAM_TTS_VOICE` | `aura-2-asteria-en` | Deepgram TTS voice name |
 | `DEEPGRAM_TTS_SPEED` | `1.3` | Deepgram TTS playback speed (range 0.5–1.5) |
 | `CARTESIA_API_KEY` | — | Required for cartesia TTS |
+| `DISCOCLAW_GEMINI_SESSION_ROTATION_MS` | `780000` (13 min) | Time before proactive session rotation in `gemini-live` mode. Must be less than Gemini's ~15 min server-side limit. Set to `0` to disable. |
+| `GEMINI_API_KEY` | — | Required when `DISCOCLAW_VOICE_PIPELINE_PROVIDER=gemini-live`. Authenticates the Gemini Multimodal Live WebSocket session. Also used by the `gemini-api` runtime adapter (see `runtime.md`). |
 | `ANTHROPIC_API_KEY` | — | Enables the Anthropic REST adapter; when set and voice is enabled, voice auto-wires to the direct Messages API path (zero CLI cold-start). See `runtime.md § Anthropic REST Runtime`. |
 | *(built-in)* | — | Telegraphic style instruction hardcoded into every voice AI invocation — front-loads the answer, strips preambles/markdown/filler, keeps responses short for TTS latency. Not an env var; not overridable by `DISCOCLAW_VOICE_SYSTEM_PROMPT`. |

package/.env.example

@@ -193,6 +193,12 @@ DISCORD_GUILD_ID=
 # Run `pnpm setup` or `discoclaw init` to enable voice interactively,
 # or set these vars manually to enable voice chat (STT/TTS via Deepgram).
 #DISCOCLAW_VOICE_ENABLED=0
+# Voice pipeline provider: pipeline (default, Deepgram STT/TTS) or gemini-live
+# (Gemini Live WebSocket — requires GEMINI_API_KEY).
+#DISCOCLAW_VOICE_PIPELINE_PROVIDER=pipeline
+# Gemini Live session rotation threshold (ms). The provider proactively reconnects
+# before Gemini's ~15 min session limit to minimize audio gap. Default: 780000 (13 min).
+#DISCOCLAW_GEMINI_SESSION_ROTATION_MS=780000
 # Text channel used for voice prompt context and actions (e.g. posting action results,
 # reading pinned notes). Required for full voice functionality when voice is enabled.
 #DISCOCLAW_VOICE_HOME_CHANNEL= # e.g. "voice"

package/dist/cli/dashboard.js

@@ -146,7 +146,13 @@ function normalizeRuntimeName(value) {
     const trimmed = value?.trim().toLowerCase();
     if (!trimmed)
         return undefined;
-    const normalized = trimmed === 'claude_code' ? 'claude' : trimmed;
+    let normalized = trimmed === 'claude_code' ? 'claude' : trimmed;
+    if (normalized === 'claude-cli')
+        normalized = 'claude';
+    if (normalized === 'codex-cli')
+        normalized = 'codex';
+    if (normalized === 'claude' || normalized === 'codex')
+        return normalized;
     return KNOWN_RUNTIMES.has(normalized) ? normalized : undefined;
 }
 function trimEnvValue(value) {

package/dist/config.js

@@ -512,6 +512,8 @@ export function parseConfig(env) {
     const voiceAutoJoin = parseBoolean(env, 'DISCOCLAW_VOICE_AUTO_JOIN', false);
     const voiceSttProvider = parseEnum(env, 'DISCOCLAW_STT_PROVIDER', ['deepgram', 'whisper', 'openai'], 'deepgram');
     const voiceTtsProvider = parseEnum(env, 'DISCOCLAW_TTS_PROVIDER', ['cartesia', 'deepgram', 'kokoro', 'openai'], 'cartesia');
+    const voicePipelineProvider = parseEnum(env, 'DISCOCLAW_VOICE_PIPELINE_PROVIDER', ['pipeline', 'gemini-live'], 'pipeline');
+    const geminiSessionRotationMs = parseNonNegativeInt(env, 'DISCOCLAW_GEMINI_SESSION_ROTATION_MS', 780_000);
     let voiceHomeChannel = parseTrimmedString(env, 'DISCOCLAW_VOICE_HOME_CHANNEL');
     if (!voiceHomeChannel) {
         const legacy = parseTrimmedString(env, 'DISCOCLAW_VOICE_TRANSCRIPT_CHANNEL');
@@ -563,6 +565,9 @@ export function parseConfig(env) {
     if (voiceEnabled && !voiceHomeChannel) {
         warnings.push('DISCOCLAW_VOICE_ENABLED=1 but DISCOCLAW_VOICE_HOME_CHANNEL is not set; voice actions will be disabled (no target channel for action execution).');
     }
+    if (voiceEnabled && voicePipelineProvider === 'gemini-live' && !geminiApiKey) {
+        warnings.push('DISCOCLAW_VOICE_PIPELINE_PROVIDER=gemini-live but GEMINI_API_KEY is not set; voice pipeline will fail at runtime.');
+    }
     const coldStorageEnabled = parseBoolean(env, 'DISCOCLAW_COLD_STORAGE_ENABLED', false);
     const coldStorageApiKey = parseTrimmedString(env, 'COLD_STORAGE_API_KEY') ?? openaiApiKey;
     const coldStorageProvider = parseEnum(env, 'COLD_STORAGE_PROVIDER', ['openai', 'openai-compat'], 'openai');
@@ -743,6 +748,8 @@ export function parseConfig(env) {
             voiceSystemPrompt,
             voiceSttProvider,
             voiceTtsProvider,
+            voicePipelineProvider,
+            geminiSessionRotationMs,
             voiceHomeChannel,
             voiceLogChannel,
             deepgramApiKey,

package/dist/cron/executor.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { execa } from 'execa';
 import { resolveDefaultModel as resolveImagegenDefaultModel } from '../discord/actions-imagegen.js';
 import { acquireCronLock, releaseCronLock } from './job-lock.js';
@@ -9,6 +10,7 @@ import { sendChunks, appendUnavailableActionTypesNotice, appendParseFailureNotic
 import { buildPromptPreamble, loadWorkspacePaFiles, inlineContextFiles, resolveEffectiveTools } from '../discord/prompt-common.js';
 import { ensureStatusMessage } from './discord-sync.js';
 import { globalMetrics } from '../observability/metrics.js';
+import { globalTraceStore } from '../observability/trace-store.js';
 import { mapRuntimeErrorToUserMessage } from '../discord/user-errors.js';
 import { resolveModel } from '../runtime/model-tiers.js';
 import { cliExecaEnv, stripAnsi } from '../runtime/cli-shared.js';
@@ -223,6 +225,10 @@ export async function executeCronJob(job, ctx) {
             return;
         }
     }
+    const traceId = `cron_${randomUUID()}`;
+    const sessionKey = `cron:${job.cronId || job.id}`;
+    let traceOutcome = 'success';
+    globalTraceStore.startTrace(traceId, sessionKey, 'cron', undefined);
     job.running = true;
     activeCronRunKeys.add(runKey);
     ctx.runControl?.register(job.id, requestCancel);
@@ -244,6 +250,13 @@ export async function executeCronJob(job, ctx) {
         const guild = ctx.client.guilds.cache.get(job.guildId);
         if (!guild) {
             ctx.log?.error({ jobId: job.id, guildId: job.guildId }, 'cron:exec guild not found');
+            traceOutcome = 'error';
+            globalTraceStore.addEvent(traceId, {
+                type: 'error',
+                at: Date.now(),
+                message: `guild ${job.guildId} not found`,
+                stage: 'cron_setup',
+            });
             await ctx.status?.runtimeError({ sessionKey: `cron:${job.id}` }, `Cron "${job.name}": guild ${job.guildId} not found`);
             await recordError(ctx, job, `guild ${job.guildId} not found`);
             return;
@@ -251,6 +264,13 @@ export async function executeCronJob(job, ctx) {
         const targetChannel = resolveChannel(guild, job.def.channel);
         if (!targetChannel) {
             ctx.log?.error({ jobId: job.id, channel: job.def.channel }, 'cron:exec target channel not found');
+            traceOutcome = 'error';
+            globalTraceStore.addEvent(traceId, {
+                type: 'error',
+                at: Date.now(),
+                message: `target channel "${job.def.channel}" not found`,
+                stage: 'cron_setup',
+            });
             await ctx.status?.runtimeError({ sessionKey: `cron:${job.id}`, channelName: job.def.channel }, `Cron "${job.name}": target channel "${job.def.channel}" not found`);
             await recordError(ctx, job, `target channel "${job.def.channel}" not found`);
             return;
@@ -264,6 +284,13 @@ export async function executeCronJob(job, ctx) {
                 (parentId && ctx.allowChannelIds.has(parentId));
             if (!allowed) {
                 ctx.log?.error({ jobId: job.id, channel: job.def.channel }, 'cron:exec target channel not allowlisted');
+                traceOutcome = 'error';
+                globalTraceStore.addEvent(traceId, {
+                    type: 'error',
+                    at: Date.now(),
+                    message: `target channel "${job.def.channel}" not allowlisted`,
+                    stage: 'cron_setup',
+                });
                 await ctx.status?.runtimeError({ sessionKey: `cron:${job.id}`, channelName: job.def.channel }, `Cron "${job.name}": target channel "${job.def.channel}" is not allowlisted`);
                 await recordError(ctx, job, `target channel "${job.def.channel}" not allowlisted`);
                 return;
@@ -367,6 +394,12 @@ export async function executeCronJob(job, ctx) {
             }
         }
         metrics.recordInvokeStart('cron');
+        globalTraceStore.addEvent(traceId, {
+            type: 'invoke_start',
+            at: Date.now(),
+            summary: `cron job "${job.name}"`,
+            promptPreview: prompt.slice(0, 220),
+        });
         ctx.log?.info({ flow: 'cron', jobId: job.id, cronId: job.cronId }, 'obs.invoke.start');
         let finalText = '';
         let deltaText = '';
@@ -401,6 +434,13 @@ export async function executeCronJob(job, ctx) {
                     collectedImages.push(evt.image);
                 }
                 else if (evt.type === 'error') {
+                    traceOutcome = 'error';
+                    globalTraceStore.addEvent(traceId, {
+                        type: 'error',
+                        at: Date.now(),
+                        message: evt.message,
+                        stage: 'runtime',
+                    });
                     metrics.recordInvokeResult('cron', Date.now() - t0, false, evt.message);
                     metrics.increment('cron.run.error');
                     ctx.log?.error({ jobId: job.id, error: evt.message }, 'cron:exec runtime error');
@@ -425,11 +465,24 @@ export async function executeCronJob(job, ctx) {
             if (runtimeIterator?.return) {
                 await runtimeIterator.return();
             }
+            traceOutcome = 'canceled';
+            globalTraceStore.addEvent(traceId, {
+                type: 'error',
+                at: Date.now(),
+                message: cancelReason,
+                stage: 'runtime',
+            });
             metrics.increment('cron.run.canceled');
             ctx.log?.warn({ jobId: job.id, cronId: job.cronId }, 'cron:exec canceled');
             await recordError(ctx, job, cancelReason);
             return;
         }
+        globalTraceStore.addEvent(traceId, {
+            type: 'invoke_end',
+            at: Date.now(),
+            ok: true,
+            summary: `completed in ${Date.now() - t0}ms`,
+        });
         metrics.recordInvokeResult('cron', Date.now() - t0, true);
         ctx.log?.info({ flow: 'cron', jobId: job.id, ms: Date.now() - t0, ok: true }, 'obs.invoke.end');
         let output = finalText || deltaText;
@@ -518,8 +571,16 @@ export async function executeCronJob(job, ctx) {
                     imagegenCtx: ctx.imagegenCtx,
                     voiceCtx: ctx.voiceCtx,
                 });
-                for (const result of results) {
+                for (let i = 0; i < results.length; i++) {
+                    const result = results[i];
                     metrics.recordActionResult(result.ok);
+                    globalTraceStore.addEvent(traceId, {
+                        type: 'action_result',
+                        at: Date.now(),
+                        action: actions[i].type,
+                        ok: result.ok,
+                        detail: result.ok ? undefined : ('error' in result ? result.error : undefined),
+                    });
                     ctx.log?.info({ flow: 'cron', jobId: job.id, ok: result.ok }, 'obs.action.result');
                 }
                 const anyActionSucceeded = results.some((r) => r.ok);
@@ -604,6 +665,15 @@ export async function executeCronJob(job, ctx) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        traceOutcome = 'error';
+        globalTraceStore.addEvent(traceId, {
+            type: 'error',
+            at: Date.now(),
+            message: msg,
+            name: err instanceof Error ? err.name : undefined,
+            stage: 'cron_flow',
+            stack: err instanceof Error ? err.stack?.slice(0, 400) : undefined,
+        });
         metrics.increment('cron.run.error');
         ctx.log?.error({ err, jobId: job.id }, 'cron:exec failed');
         await ctx.status?.runtimeError({ sessionKey: `cron:${job.id}`, channelName: job.def.channel }, `Cron "${job.name}": ${msg}`);
@@ -623,6 +693,7 @@ export async function executeCronJob(job, ctx) {
         await recordError(ctx, job, msg);
     }
     finally {
+        globalTraceStore.endTrace(traceId, traceOutcome);
         const shouldRerun = queuedCronRerunKeys.delete(runKey);
         if (lockToken && ctx.lockDir && job.cronId) {
             await releaseCronLock(ctx.lockDir, job.cronId, lockToken).catch((err) => {

package/dist/dashboard/api/metrics.js

@@ -0,0 +1,7 @@
+import { globalMetrics } from '../../observability/metrics.js';
+export function buildMetricsResponse() {
+    return {
+        ok: true,
+        metrics: globalMetrics.snapshot(),
+    };
+}

package/dist/dashboard/api/metrics.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { buildMetricsResponse } from './metrics.js';
+describe('buildMetricsResponse', () => {
+    it('returns ok with a metrics snapshot', () => {
+        const response = buildMetricsResponse();
+        expect(response.ok).toBe(true);
+        expect(response.metrics).toBeDefined();
+        expect(typeof response.metrics.startedAt).toBe('number');
+        expect(response.metrics.counters).toBeDefined();
+        expect(response.metrics.latencies).toBeDefined();
+        expect(response.metrics.latencies).toHaveProperty('message');
+        expect(response.metrics.latencies).toHaveProperty('reaction');
+        expect(response.metrics.latencies).toHaveProperty('cron');
+        expect(response.metrics.latencies).toHaveProperty('defer');
+    });
+});

package/dist/dashboard/api/traces.js

@@ -0,0 +1,14 @@
+import { globalTraceStore } from '../../observability/trace-store.js';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+export function buildTracesResponse(limitParam) {
+    const parsed = limitParam !== null ? Math.floor(Number(limitParam)) : DEFAULT_LIMIT;
+    const limit = Number.isFinite(parsed)
+        ? Math.max(1, Math.min(MAX_LIMIT, parsed))
+        : DEFAULT_LIMIT;
+    return {
+        ok: true,
+        summary: globalTraceStore.summary(),
+        recentTraces: globalTraceStore.listRecent(limit),
+    };
+}

package/dist/dashboard/api/traces.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { buildTracesResponse } from './traces.js';
+import { globalTraceStore } from '../../observability/trace-store.js';
+describe('buildTracesResponse', () => {
+    it('returns ok with summary and recent traces', () => {
+        const response = buildTracesResponse(null);
+        expect(response.ok).toBe(true);
+        expect(response.summary).toBeDefined();
+        expect(typeof response.summary.total).toBe('number');
+        expect(response.summary.byFlow).toBeDefined();
+        expect(Array.isArray(response.recentTraces)).toBe(true);
+    });
+    it('uses default limit of 50 when param is null', () => {
+        const response = buildTracesResponse(null);
+        expect(response.ok).toBe(true);
+        // With an empty store, recentTraces should be empty
+        expect(response.recentTraces.length).toBeLessThanOrEqual(50);
+    });
+    it('respects a custom limit param', () => {
+        // Seed a few traces
+        globalTraceStore.startTrace('t1', 'user:ch', 'message');
+        globalTraceStore.endTrace('t1', 'success');
+        globalTraceStore.startTrace('t2', 'user:ch', 'cron');
+        globalTraceStore.endTrace('t2', 'success');
+        globalTraceStore.startTrace('t3', 'user:ch', 'reaction');
+        globalTraceStore.endTrace('t3', 'success');
+        const response = buildTracesResponse('2');
+        expect(response.ok).toBe(true);
+        expect(response.recentTraces.length).toBeLessThanOrEqual(2);
+    });
+    it('clamps limit to max of 200', () => {
+        const response = buildTracesResponse('999');
+        expect(response.ok).toBe(true);
+        // Just verify it doesn't throw — the limit is clamped internally
+    });
+    it('falls back to default for non-numeric limit', () => {
+        const response = buildTracesResponse('abc');
+        expect(response.ok).toBe(true);
+    });
+});

package/dist/dashboard/page.js

@@ -697,7 +697,7 @@ export function renderDashboardPage() {
               </label>
             </div>
             <div class="actions">
-              <button id="chat-runtime-submit-btn" type="submit">Apply Runtime</button>
+              <button id="chat-runtime-submit-btn" type="submit">Apply Runtime + Save</button>
               <button id="chat-auth-btn" class="secondary" type="button">Check Auth</button>
             </div>
           </form>
@@ -709,9 +709,9 @@ export function renderDashboardPage() {
                 <select id="chat-model-select" name="model" required></select>
               </label>
             </div>
-            <div class="field-note">Tier options double as the practical thinking profile on runtimes that support explicit effort.</div>
+            <div class="field-note">Tier options double as the practical thinking profile on runtimes that support explicit effort. These chat controls also save the next-start default.</div>
             <div class="actions">
-              <button id="chat-model-submit-btn" type="submit">Apply Model</button>
+              <button id="chat-model-submit-btn" type="submit">Apply Model + Save</button>
             </div>
           </form>
         </div>
@@ -839,6 +839,52 @@ export function renderDashboardPage() {
         </details>
       </section>
 
+      <section class="card span-12">
+        <div class="card-header">
+          <div>
+            <h2>Observability</h2>
+          </div>
+          <div class="actions">
+            <button id="traces-btn" class="secondary" type="button">Refresh Traces</button>
+          </div>
+        </div>
+        <div id="traces-summary" class="metrics"></div>
+        <details>
+          <summary>Runtime Metrics</summary>
+          <div class="details-body">
+            <div id="metrics-counters" class="metrics"></div>
+            <div id="metrics-latencies" class="metrics"></div>
+            <div id="metrics-memory" class="metrics"></div>
+          </div>
+        </details>
+        <details>
+          <summary>Recent Traces</summary>
+          <div class="details-body">
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Flow</th>
+                    <th>Outcome</th>
+                    <th>Duration</th>
+                    <th>Started</th>
+                    <th>Events</th>
+                  </tr>
+                </thead>
+                <tbody id="traces-body"></tbody>
+              </table>
+            </div>
+          </div>
+        </details>
+        <details>
+          <summary>Recent Errors</summary>
+          <div class="details-body">
+            <div id="traces-errors" class="checklist"></div>
+          </div>
+        </details>
+        <div id="traces-status" class="status"></div>
+      </section>
+
       <section class="card span-12">
         <div class="card-header">
           <div>
@@ -955,6 +1001,13 @@ export function renderDashboardPage() {
     const secretValueInput = document.getElementById('secret-value-input');
     const settingsContainer = document.getElementById('settings-container');
     const settingsStatus = document.getElementById('settings-status');
+    const tracesSummary = document.getElementById('traces-summary');
+    const tracesBody = document.getElementById('traces-body');
+    const tracesErrors = document.getElementById('traces-errors');
+    const tracesStatus = document.getElementById('traces-status');
+    const metricsCounters = document.getElementById('metrics-counters');
+    const metricsLatencies = document.getElementById('metrics-latencies');
+    const metricsMemory = document.getElementById('metrics-memory');
     const ROLE_LABELS = {
       chat: 'Chat',
       'plan-run': 'Plan Run',
@@ -1265,7 +1318,9 @@ export function renderDashboardPage() {
       chatRuntimeSelect.value = live.chatRuntime || snapshot.primaryRuntime;
 
       clearNode(chatModelSelect);
-      (snapshot.modelOptions.chat || []).forEach(function (model) {
+      (snapshot.modelOptions.chat || []).filter(function (model) {
+        return model !== 'default';
+      }).forEach(function (model) {
         appendSelectOption(chatModelSelect, model, formatModelOptionLabel('chat', model));
       });
       if ((snapshot.modelOptions.chat || []).indexOf(live.chatModel) >= 0) {
@@ -1303,6 +1358,121 @@ export function renderDashboardPage() {
       secretKeySelect.value = recommendSecretKey(snapshot);
     }
 
+    function renderTraces(data) {
+      var summary = data.summary || {};
+      var recentTraces = data.recentTraces || [];
+      var byFlow = summary.byFlow || {};
+      clearNode(tracesSummary);
+      appendMetric(tracesSummary, 'total traces', String(summary.total || 0));
+      appendMetric(tracesSummary, 'in progress', String(summary.inProgress || 0));
+      var flows = ['message', 'reaction', 'cron', 'defer'];
+      flows.forEach(function (flow) {
+        var fs = byFlow[flow];
+        if (!fs || fs.total === 0) return;
+        var avg = fs.avgDurationMs > 0 ? ' avg ' + fs.avgDurationMs + 'ms' : '';
+        appendMetric(tracesSummary, flow, fs.succeeded + ' ok / ' + fs.failed + ' err / ' + fs.inProgress + ' running' + avg);
+      });
+
+      clearNode(tracesBody);
+      recentTraces.forEach(function (trace) {
+        var tr = document.createElement('tr');
+        var flowCell = document.createElement('td');
+        flowCell.textContent = trace.flow;
+        var outcomeCell = document.createElement('td');
+        outcomeCell.textContent = trace.outcome;
+        if (trace.outcome === 'success') outcomeCell.style.color = 'var(--green)';
+        else if (trace.outcome === 'in_progress') outcomeCell.style.color = 'var(--amber)';
+        else if (trace.outcome !== 'success') outcomeCell.style.color = 'var(--red)';
+        var durationCell = document.createElement('td');
+        durationCell.textContent = trace.outcome === 'in_progress' ? '\u2014' : trace.durationMs + 'ms';
+        var startedCell = document.createElement('td');
+        startedCell.textContent = new Date(trace.startedAt).toLocaleTimeString();
+        var eventsCell = document.createElement('td');
+        eventsCell.textContent = String((trace.events || []).length);
+        tr.append(flowCell, outcomeCell, durationCell, startedCell, eventsCell);
+        tracesBody.append(tr);
+      });
+
+      clearNode(tracesErrors);
+      var recentErrors = summary.recentErrors || [];
+      if (recentErrors.length === 0) {
+        var noErrors = document.createElement('div');
+        noErrors.className = 'card-copy';
+        noErrors.textContent = 'No recent errors.';
+        tracesErrors.append(noErrors);
+      } else {
+        recentErrors.forEach(function (err) {
+          var item = document.createElement('div');
+          item.className = 'checklist-item';
+          var top = document.createElement('div');
+          top.className = 'checklist-top';
+          var dot = document.createElement('div');
+          dot.className = 'status-dot error';
+          var label = document.createElement('div');
+          label.className = 'checklist-label';
+          label.textContent = err.flow + ': ' + err.message;
+          top.append(dot, label);
+          var body = document.createElement('div');
+          body.className = 'checklist-body';
+          body.textContent = new Date(err.at).toLocaleString();
+          item.append(top, body);
+          tracesErrors.append(item);
+        });
+      }
+    }
+
+    async function refreshTraces() {
+      var response = await fetchJson('/api/traces');
+      renderTraces(response);
+    }
+
+    function renderMetrics(data) {
+      var m = data.metrics || {};
+      var counters = m.counters || {};
+      var latencies = m.latencies || {};
+      var memory = m.memory;
+
+      clearNode(metricsCounters);
+      var upSince = m.startedAt ? new Date(m.startedAt).toLocaleString() : 'unknown';
+      appendMetric(metricsCounters, 'up since', upSince);
+      var counterKeys = Object.keys(counters).sort();
+      counterKeys.forEach(function (key) {
+        appendMetric(metricsCounters, key, String(counters[key]));
+      });
+      if (counterKeys.length === 0) {
+        appendMetric(metricsCounters, 'counters', 'none recorded yet');
+      }
+
+      clearNode(metricsLatencies);
+      var flows = ['message', 'reaction', 'cron', 'defer'];
+      flows.forEach(function (flow) {
+        var lat = latencies[flow];
+        if (!lat || lat.count === 0) return;
+        appendMetric(metricsLatencies, flow + ' latency',
+          'p50=' + lat.p50Ms + 'ms  p95=' + lat.p95Ms + 'ms  max=' + lat.maxMs + 'ms  (n=' + lat.count + ')');
+      });
+      if (metricsLatencies.children.length === 0) {
+        appendMetric(metricsLatencies, 'latencies', 'no samples yet');
+      }
+
+      clearNode(metricsMemory);
+      if (memory) {
+        function fmtMB(bytes) { return bytes ? (bytes / 1048576).toFixed(1) + ' MB' : 'n/a'; }
+        appendMetric(metricsMemory, 'rss', fmtMB(memory.rssBytes) + '  (hwm ' + fmtMB(memory.rssHwmBytes) + ')');
+        appendMetric(metricsMemory, 'heap used', fmtMB(memory.heapUsedBytes) + '  (hwm ' + fmtMB(memory.heapUsedHwmBytes) + ')');
+        appendMetric(metricsMemory, 'heap total', fmtMB(memory.heapTotalBytes));
+        appendMetric(metricsMemory, 'external', fmtMB(memory.externalBytes));
+        appendMetric(metricsMemory, 'samples', String(memory.sampleCount || 0));
+      } else {
+        appendMetric(metricsMemory, 'memory', 'sampler not active');
+      }
+    }
+
+    async function refreshMetrics() {
+      var response = await fetchJson('/api/metrics');
+      renderMetrics(response);
+    }
+
     function renderSnapshot(snapshot) {
       if (!snapshot.live) snapshot.live = {};
       const selectedRole = roleSelect.value;
@@ -1560,13 +1730,22 @@ export function renderDashboardPage() {
 
     document.getElementById('refresh-btn').addEventListener('click', async function () {
       try {
-        await Promise.all([refreshSnapshot(false), refreshDoctor(false)]);
+        await Promise.all([refreshSnapshot(false), refreshDoctor(false), refreshTraces(), refreshMetrics()]);
         setStatus(heroStatus, 'Dashboard refreshed.', 'ok');
       } catch (error) {
         setStatus(heroStatus, String(error), 'error');
       }
     });
 
+    document.getElementById('traces-btn').addEventListener('click', async function () {
+      try {
+        await Promise.all([refreshTraces(), refreshMetrics()]);
+        setStatus(tracesStatus, 'Traces refreshed.', 'ok');
+      } catch (error) {
+        setStatus(tracesStatus, String(error), 'error');
+      }
+    });
+
     document.getElementById('status-btn').addEventListener('click', async function () {
       try {
         const response = await fetchJson('/api/status');
@@ -1639,7 +1818,7 @@ export function renderDashboardPage() {
         const response = await fetchJson('/api/live-model', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ role: 'chat', model: chatRuntimeSelect.value })
+          body: JSON.stringify({ role: 'chat', model: chatRuntimeSelect.value, persist: true })
         });
         renderSnapshot(response.snapshot);
         setStatus(chatStatus, response.message, 'ok');
@@ -1655,7 +1834,7 @@ export function renderDashboardPage() {
         const response = await fetchJson('/api/live-model', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ role: 'chat', model: chatModelSelect.value })
+          body: JSON.stringify({ role: 'chat', model: chatModelSelect.value, persist: true })
         });
         renderSnapshot(response.snapshot);
         setStatus(chatStatus, response.message, 'ok');
@@ -1762,7 +1941,7 @@ export function renderDashboardPage() {
       syncSecondaryModelOptions(roleSelect.value, '');
     });
 
-    Promise.all([refreshSnapshot(false), refreshDoctor(false), loadSettings()]).then(function () {
+    Promise.all([refreshSnapshot(false), refreshDoctor(false), loadSettings(), refreshTraces(), refreshMetrics()]).then(function () {
       setStatus(heroStatus, 'Dashboard ready.', 'ok');
       if (lastSnapshot) {
         populateSecondaryRoleForm('', '');