@pellux/goodvibes-tui 0.21.0 → 0.23.0

package/src/input/commands/session-workflow.ts

@@ -1,6 +1,6 @@
 import { randomBytes } from 'node:crypto';
 
-import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import type { CommandContext } from '../command-registry.ts';
 import { type SessionMeta } from '@pellux/goodvibes-sdk/platform/sessions';
 import type { TranscriptEventKind } from '@pellux/goodvibes-sdk/platform/core';
 import type { ConversationTitleSource } from '../../core/conversation';
@@ -441,21 +441,13 @@ export async function handleSessionWorkflowCommand(args: string[], ctx: CommandC
   return false;
 }
 
-export function registerSessionWorkflowCommands(registry: CommandRegistry): void {
-  registry.register({
-    name: 'session-mgmt',
-    aliases: ['smgmt'],
-    description: 'Manage sessions, resume posture, and transcript structure',
-    usage: '[list | rename <name> | resume <id|name> | fork | save | info <id> | events [kind] | groups [kind] | hotspots | export <id> [format] | search <query> | delete <id>]',
-    argsHint: '<list|rename|resume|fork|save|info|events|groups|hotspots|export|search|delete>',
-    async handler(args, ctx) {
-      const handled = await handleSessionWorkflowCommand(args, ctx);
-      if (!handled) {
-        ctx.print('Unknown subcommand: ' + (args[0] ?? '') + '\nUsage: /session-mgmt [list | rename <name> | resume <id> | fork [name] | save [name] | info [id] | events [kind] | groups [kind] | hotspots | export <id> [format] | search <query> | delete <id>]');
-      }
-    },
-  });
-}
+// session-mgmt / smgmt was removed in TASK-032.
+// All session lifecycle operations are now first-class subcommands of /session.
+// Use /session list, /session resume, /session save, etc.
+//
+// CommandRegistry.register() throws on duplicate names/aliases, so this
+// registration was intentionally deleted rather than left as dead code.
+
 interface SessionExportData {
   readonly messages: object[];
   readonly timestamp?: number;

package/src/input/commands/session.ts

@@ -319,18 +319,52 @@ function handleCancel(args: string[], context: CommandContext): void {
 /**
  * sessionCommand — The `/session` slash command.
  *
- * Routes to multi-session orchestration subcommand handlers based on args[0].
+ * The ONE front-door for all session operations. Owns two domains:
+ *
+ * Lifecycle (continuity, export, resume, pruning):
+ *   list | rename | resume | fork | save | info | events | groups | hotspots | export | search | delete
+ *
+ * Orchestration (cross-session task DAG — 40 tests, cycle detection):
+ *   link-task | handoff | graph | cancel
+ *
+ * Orchestration-command decision (TASK-032):
+ *   Both domains live under /session rather than splitting orchestration into
+ *   a separate /session-orch command. Rationale: they share the same entity
+ *   (a session) and the same operator mental model ("I am working with sessions").
+ *   A second front-door would create ambiguity about which command to reach for.
+ *   Explicit switch routing (not fallthrough) makes both domains first-class;
+ *   the former /session-mgmt alias (session-mgmt/smgmt) is removed so there
+ *   is exactly one registration and no silent shadowing.
  */
 export const sessionCommand: SlashCommand = {
   name: 'session',
   aliases: ['sess'],
-  description: 'Multi-session orchestration: link tasks, handoff, view graph, and cancel across sessions.',
+  description: 'Session lifecycle and orchestration: list, resume, fork, save, export, link-task, handoff, graph, cancel.',
   usage: '<subcommand> [args]',
-  argsHint: 'link-task|handoff|graph|cancel',
+  argsHint: 'list|rename|resume|fork|save|info|export|search|delete|events|groups|hotspots|link-task|handoff|graph|cancel',
   handler: async (args: string[], context: CommandContext): Promise<void> => {
     const [sub, ...rest] = args;
 
     switch (sub) {
+      // ── Lifecycle subcommands ────────────────────────────────────────────────
+      // Each delegates explicitly to handleSessionWorkflowCommand so every
+      // subcommand has a deterministic, named path — no silent fallthrough.
+      case 'list':
+      case 'rename':
+      case 'resume':
+      case 'fork':
+      case 'save':
+      case 'info':
+      case 'export':
+      case 'search':
+      case 'delete':
+      case 'events':
+      case 'groups':
+      case 'hotspots':
+        await handleSessionWorkflowCommand(args, context);
+        break;
+
+      // ── Orchestration subcommands ─────────────────────────────────────────────
       case 'link-task':
       case 'link':
         handleLinkTask(rest, context);
@@ -350,24 +384,40 @@ export const sessionCommand: SlashCommand = {
         handleCancel(rest, context);
         break;
 
+      // ── No-arg: show current session info ────────────────────────────────────
+      case undefined:
+        await handleSessionWorkflowCommand([], context);
+        break;
+
       default: {
-        const handled = await handleSessionWorkflowCommand(args, context);
-        if (!handled) {
-          const usage = [
-            'Usage: /session <subcommand>',
-            '  list | rename <name> | resume <id|name> | fork [name] | save [name] | info [id] | export <id> [format] | search <query> | delete <id>',
-            '                                 — Session continuity, export, resume, and pruning',
-            '  link-task <taskId> [--session <sid>] [--depends-on <sid:taskId>] [--label <label>]',
-            '                                 — Register a task in the cross-session graph',
-            '  handoff <taskId> --to <sid>  [--session <sid>] [--reason <reason>]',
-            '                                 — Hand a task off to another session',
-            '  graph [--session <sid>] [--format text|json]',
-            '                                 — Display the cross-session task dependency graph',
-            '  cancel <taskId> [--scope task|subtree|session] [--session <sid>] [--reason <reason>]',
-            '                                 — Cancel tasks with scoped semantics',
-          ].join('\n');
-          context.print(usage);
-        }
+        const usage = [
+          'Usage: /session <subcommand>',
+          '',
+          'Lifecycle:',
+          '  list                                    — List saved sessions',
+          '  rename <name>                           — Rename the current session',
+          '  resume <id|name>                        — Resume a saved session',
+          '  fork [name]                             — Fork the current session',
+          '  save [name]                             — Save the current session',
+          '  info [id]                               — Show session info',
+          '  export <id|.> [markdown|text]           — Export session transcript',
+          '  search <query>                          — Search session content',
+          '  delete <id>                             — Delete a saved session',
+          '  events [kind]                           — Show transcript events',
+          '  groups [kind]                           — Show transcript groups',
+          '  hotspots                                — Show transcript hotspots',
+          '',
+          'Orchestration:',
+          '  link-task <taskId> [--session <sid>] [--depends-on <sid:taskId>] [--label <label>]',
+          '                                          — Register a task in the cross-session graph',
+          '  handoff <taskId> --to <sid> [--session <sid>] [--reason <reason>]',
+          '                                          — Hand a task off to another session',
+          '  graph [--session <sid>] [--format text|json]',
+          '                                          — Display the cross-session task dependency graph',
+          '  cancel <taskId> [--scope task|subtree|session] [--session <sid>] [--reason <reason>]',
+          '                                          — Cancel tasks with scoped semantics',
+        ].join('\n');
+        context.print(usage);
         break;
       }
     }

package/src/input/commands/share-runtime.ts

@@ -17,7 +17,7 @@ import {
   resolveGithubToken,
 } from '../../export/gist-uploader.ts';
 import { copyToClipboard } from '../../utils/clipboard.ts';
-import { openBrowser } from '../../cli/management.ts';
+import { openBrowser } from '../../utils/browser.ts';
 
 export function registerShareRuntimeCommands(registry: CommandRegistry): void {
   registry.register({

package/src/input/commands/shell-core.ts

@@ -3,7 +3,9 @@ import type { SelectionItem } from '../selection-modal.ts';
 import { EFFORT_DESCRIPTIONS } from '@pellux/goodvibes-sdk/platform/providers';
 import { REASONING_BUDGET_MAP } from '@pellux/goodvibes-sdk/platform/providers';
 import { executeWriteQuit } from './quit-shared.ts';
-import { compactConversation, requireKeybindingsManager, requireProviderApi } from './runtime-services.ts';
+import { compactConversation, requireKeybindingsManager, requireProviderApi, requireSessionMemoryStore } from './runtime-services.ts';
+import { buildCompactionPreview, buildCompactionAfterNotice, buildPinUsageText, buildPinSuccessText } from '../../renderer/compaction-preview.ts';
+import { buildCompactionHistoryText } from '../../renderer/compaction-history-modal.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
@@ -204,9 +206,57 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
     aliases: [],
     description: 'Summarize conversation to free context window',
     async handler(_args, ctx) {
-      ctx.print('Compacting conversation...');
-      await compactConversation(ctx);
-      ctx.print('Conversation compacted.');
+      const messages = ctx.session.conversationManager.getMessagesForLLM();
+      // contextWindow is not on CommandContext; preview shows message/token counts
+      // without the capacity-% clause (still honest; no fabricated value).
+      const contextWindow = 0;
+      const memStore = ctx.session.sessionMemoryStore;
+      const pinnedMemoryCount = memStore ? memStore.list().length : 0;
+      // Pre-compact preview: honest estimate, clearly labelled.
+      const preview = buildCompactionPreview({ messages, contextWindow, pinnedMemoryCount, trigger: 'manual' });
+      ctx.print(preview);
+      const event = await compactConversation(ctx);
+      if (event) {
+        // Post-compact notice: uses real CompactionEvent figures.
+        ctx.print(buildCompactionAfterNotice({ event, pinnedMemoryCount }));
+      } else {
+        ctx.print('[Context] Compact complete.');
+      }
+      ctx.renderRequest();
+    },
+  });
+
+  registry.register({
+    name: 'compact-history',
+    aliases: ['compaction-history'],
+    description: 'Show compaction history for this session',
+    handler(_args, ctx) {
+      ctx.print(buildCompactionHistoryText());
+      ctx.renderRequest();
+    },
+  });
+
+  registry.register({
+    name: 'keep',
+    aliases: [],
+    description: 'Pin text to session memory (survives compaction)',
+    usage: '<text>',
+    argsHint: '<text to preserve>',
+    handler(args, ctx) {
+      const text = args.join(' ').trim();
+      if (!text) {
+        ctx.print(buildPinUsageText());
+        ctx.renderRequest();
+        return;
+      }
+      const memStore = requireSessionMemoryStore(ctx);
+      const id = memStore.add(text);
+      if (!id) {
+        ctx.print('[Pin] Nothing pinned — text was blank.');
+      } else {
+        const count = memStore.list().length;
+        ctx.print(buildPinSuccessText(id, text, count));
+      }
       ctx.renderRequest();
     },
   });

package/src/input/commands.ts

@@ -7,7 +7,6 @@ import { recallCommand } from './commands/memory.ts';
 import { knowledgeCommand } from './commands/knowledge.ts';
 import { registerShellCoreCommands } from './commands/shell-core.ts';
 import { registerConfigCommand } from './commands/config.ts';
-import { registerSessionWorkflowCommands } from './commands/session-workflow.ts';
 import { registerDiscoveryRuntimeCommands } from './commands/discovery-runtime.ts';
 import { registerPlanningRuntimeCommands } from './commands/planning-runtime.ts';
 import { registerScheduleRuntimeCommands } from './commands/schedule-runtime.ts';
@@ -19,6 +18,7 @@ import { registerGitRuntimeCommands } from './commands/git-runtime.ts';
 import { registerNotifyRuntimeCommands } from './commands/notify-runtime.ts';
 import { registerReplayRuntimeCommands } from './commands/replay-runtime.ts';
 import { registerShareRuntimeCommands } from './commands/share-runtime.ts';
+import { registerChannelRuntimeCommands } from './commands/channel-runtime.ts';
 import { registerLocalSetupCommands } from './commands/local-setup.ts';
 import { registerProductRuntimeCommands } from './commands/product-runtime.ts';
 import { registerPlatformRuntimeCommands } from './commands/platform-runtime.ts';
@@ -71,6 +71,7 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registerNotifyRuntimeCommands(registry);
   registerReplayRuntimeCommands(registry);
   registerShareRuntimeCommands(registry);
+  registerChannelRuntimeCommands(registry);
   registerLocalSetupCommands(registry);
   registerProductRuntimeCommands(registry);
   registerPlatformRuntimeCommands(registry);
@@ -107,7 +108,6 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registerCloudflareRuntimeCommands(registry);
   registerWorkPlanRuntimeCommands(registry);
   registerLocalRuntimeCommands(registry);
-  registerSessionWorkflowCommands(registry);
   registerDiscoveryRuntimeCommands(registry);
   registerPlanningRuntimeCommands(registry);
   registerScheduleRuntimeCommands(registry);

package/src/input/handler-modal-routes.ts

@@ -250,6 +250,15 @@ type SettingsRouteState = {
     pendingProviderModelPickerTarget?: import('./model-picker.ts').ModelPickerTarget | null;
     pendingSettingsPickerAction?: 'tts-provider' | 'tts-voice' | null;
     resetSelected?: () => { key: string; value: unknown } | null;
+    initiateResetCategory?: () => void;
+    initiateResetAll?: () => void;
+    handleResetConfirmKey?: (
+      key: string,
+    ) =>
+      | { result: 'confirmed'; entries: ReadonlyArray<{ key: string; value: unknown }> }
+      | 'cancelled'
+      | 'absorbed'
+      | 'inactive';
   };
   commandContext?: CommandContext;
   /** Called when the settings modal requests the model picker for a non-main target. */
@@ -313,6 +322,28 @@ export function handleSettingsModalToken(state: SettingsRouteState, token: Input
     }
   }
 
+  // Reset confirm gate: routes all keys through the confirm contract before
+  // normal dispatch when a category or all-settings reset is pending.
+  if (state.settingsModal.handleResetConfirmKey) {
+    const key = token.type === 'key'
+      ? (token.logicalName ?? '')
+      : token.type === 'text'
+        ? token.value
+        : '';
+    const resetResult = state.settingsModal.handleResetConfirmKey(key);
+    if (resetResult !== 'inactive') {
+      if (typeof resetResult === 'object' && resetResult.result === 'confirmed') {
+        // Sync runtime for every reset entry so provider.model / reasoningEffort
+        // stay consistent with the live session without requiring a restart.
+        for (const entry of resetResult.entries) {
+          syncRuntimeAfterSettingReset(state.commandContext, entry.key, entry.value);
+        }
+      }
+      state.requestRender();
+      return true;
+    }
+  }
+
   if (token.type === 'key') {
     const focusPane = state.settingsModal.focusPane ?? 'settings';
     if (token.logicalName === 'escape') {
@@ -360,6 +391,12 @@ export function handleSettingsModalToken(state: SettingsRouteState, token: Input
       } else if (state.settingsModal.moveFocusedDown) state.settingsModal.moveFocusedDown();
       else state.settingsModal.moveDown?.();
     }
+    else if (token.logicalName === 'r' && token.shift && token.ctrl && !state.settingsModal.editingMode && !state.settingsModal.searchFocused) {
+      state.settingsModal.initiateResetAll?.();
+    }
+    else if (token.logicalName === 'r' && token.shift && !state.settingsModal.editingMode && !state.settingsModal.searchFocused) {
+      state.settingsModal.initiateResetCategory?.();
+    }
     else if (token.logicalName === 'r' && !state.settingsModal.editingMode && !state.settingsModal.searchFocused) {
       const reset = state.settingsModal.resetSelected?.();
       if (reset) syncRuntimeAfterSettingReset(state.commandContext, reset.key, reset.value);

package/src/input/handler-modal-token-routes.ts

@@ -232,11 +232,25 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
     return withState(state, true);
   }
 
-  if (handleEscapeOnlyModalToken({
-    active: state.agentDetailModal.active,
-    requestRender: state.requestRender,
-    handleEscape: state.handleEscape,
-  }, token)) {
+  // Agent detail modal: route c + confirm keys before escape-close.
+  // handleKey() consumes confirm-flow keys (y, Enter, n, Esc) and the 'c'
+  // initiator; unhandled keys (including Esc when no confirm is pending)
+  // fall through to escape-close below.
+  if (state.agentDetailModal.active) {
+    const keyStr: string =
+      token.type === 'key' ? (token.logicalName ?? '') :
+      token.type === 'text' ? token.value : '';
+    if (keyStr && state.agentDetailModal.handleKey(keyStr)) {
+      state.requestRender();
+      return withState(state, true);
+    }
+    // 'c' was not consumed (non-cancellable), or any other key.
+    // Esc closes the modal; all other keys are absorbed by the active modal.
+    if (token.type === 'key' && token.logicalName === 'escape') {
+      state.handleEscape();
+      return withState(state, true);
+    }
+    state.requestRender();
     return withState(state, true);
   }
 

package/src/input/handler-onboarding.ts

@@ -13,6 +13,7 @@ import {
   formatOnboardingApplyCompletionMessage,
   isLoopbackHostValue,
 } from './onboarding/onboarding-verification-helpers.ts';
+import { focusFirstOffendingField, getStepValidationErrors } from './onboarding/onboarding-wizard-validation.ts';
 import type { ModelPickerTarget } from './model-picker.ts';
 import { captureOnboardingWizardSnapshot, restoreOnboardingWizardSnapshot } from './handler-ui-state.ts';
 import type { InputHandlerLike as InputHandler, OnboardingRuntimePosture } from './handler-types.ts';
@@ -82,6 +83,23 @@ function showOnboardingApplyFeedbackForHandler(handler: InputHandler, feedback:
 
 function continueOnboardingSection(handler: InputHandler): void {
     handler.onboardingWizard.commitEdit();
+
+    const step = handler.onboardingWizard.currentStep;
+    const { errors, firstOffendingFieldId } = getStepValidationErrors(handler.onboardingWizard, step);
+    if (errors.length > 0) {
+      handler.onboardingWizard.setApplyFeedback({
+        severity: 'error',
+        title: 'Required fields missing',
+        summary: 'Fill in the required fields below before continuing.',
+        messages: errors,
+      });
+      if (firstOffendingFieldId !== null) {
+        focusFirstOffendingField(handler.onboardingWizard, firstOffendingFieldId);
+      }
+      handler.requestRender();
+      return;
+    }
+
     handler.onboardingWizard.clearApplyFeedback();
     handler.onboardingWizard.nextStep();
     handler.requestRender();

package/src/input/handler.ts

@@ -248,6 +248,7 @@ export class InputHandler implements InputHandlerLike {
       sessionLogPathResolver: (agentId) => uiServices.environment.shellPaths.resolveProjectPath('tui', 'sessions', `${agentId}.jsonl`),
       // SDK 0.23.0: supply wrfcController so the modal can show constraint data
       wrfcController: uiServices.agents.wrfcController,
+      cancelAgent: (agentId: string) => uiServices.agents.agentManager.cancel(agentId),
     });
     this.bookmarkModal = new BookmarkModal(uiServices.shell.bookmarkManager);
     this.sessionPickerModal = new SessionPickerModal(uiServices.sessions.sessionManager);

package/src/input/onboarding/onboarding-wizard-apply.ts

@@ -248,6 +248,16 @@ function addCloudflareOperations(
     setConfig('cloudflare.maxQueueOpsPerDay', controller.getNumberFieldValue('cloudflare.max-queue-ops-per-day', config?.maxQueueOpsPerDay ?? 10000, 1));
     setConfig('batch.mode', batchMode);
     setConfig('batch.queueBackend', batchMode !== 'off' && components.queues ? 'cloudflare' : 'local');
+    // Zero Trust Tunnel auto-enables trustProxy on both services so the
+    // login-rate-limiter keys on the real CF-Connecting-IP rather than the tunnel
+    // egress address. RESIDUAL RISK: until the SDK validates CF-Connecting-IP
+    // against Cloudflare's published IP ranges (SDK handoff Item 5), a client
+    // that reaches the listener directly can spoof the header to bypass the
+    // per-IP limiter. The wizard surfaces this in the cloudflare step notice.
+    if (components.zeroTrustTunnel) {
+      setConfig('controlPlane.trustProxy', true);
+      setConfig('httpListener.trustProxy', true);
+    }
   }
 
 export function addNetworkOperations(

package/src/input/onboarding/onboarding-wizard-cloudflare-step.ts

@@ -257,6 +257,19 @@ export function buildCloudflareStep(controller: OnboardingWizardControllerLike):
       );
     }
 
+    // Trust-proxy notice — shown when Tunnel is selected so the
+    // operator sees the security implication before applying.
+    const tunnelSelected = enabled && components.zeroTrustTunnel;
+    if (tunnelSelected) {
+      fields.push({
+        kind: 'status',
+        id: 'cloudflare.trust-proxy-notice',
+        label: 'trustProxy will be enabled for control plane and HTTP listener',
+        defaultValue: 'Notice',
+        hint: 'Selecting Zero Trust Tunnel auto-writes controlPlane.trustProxy=true and httpListener.trustProxy=true so the login rate-limiter keys on the real client IP (CF-Connecting-IP) rather than the tunnel egress address. RESIDUAL RISK: until the SDK validates CF-Connecting-IP against Cloudflare published IP ranges (handoff Item 5), a client that reaches the listener directly can spoof this header to bypass the per-IP rate-limiter. See docs/deployment-and-services.md for the full risk posture.',
+      });
+    }
+
     if (components.zeroTrustAccess) {
       fields.push(
         {
@@ -463,6 +476,7 @@ export function buildCloudflareStep(controller: OnboardingWizardControllerLike):
       `Components: ${enabled ? componentCount : 0} selected`,
       `Token setup: ${enabled ? setupSource : 'not used'}`,
       `Provision on final apply: ${enabled ? controller.getStringFieldValue('cloudflare.provision-on-apply', 'no') : 'no'}`,
+      ...(enabled && components.zeroTrustTunnel ? ['trustProxy: enabled for control plane and HTTP listener (see security notice)'] : []),
     ],
     fields,
   };

package/src/input/onboarding/onboarding-wizard-steps.ts

@@ -621,6 +621,12 @@ export function buildNetworkStep(controller: OnboardingWizardControllerLike): On
       }
     }
 
+    if (controlPlaneRemote || listenerEnabled || browserEnabled) { // TLS warn + CORS notice.
+      const cpOff = controlPlaneRemote && String(controller.runtimeSnapshot?.config.controlPlane?.tls?.mode ?? 'off') === 'off';
+      const hlOff = listenerEnabled && String(controller.runtimeSnapshot?.config.httpListener?.tls?.mode ?? 'off') === 'off';
+      if (cpOff || hlOff) { const a = [cpOff ? 'control plane' : '', hlOff ? 'HTTP listener' : ''].filter(Boolean).join(' and '); fields.push({ kind: 'status', id: 'network.tls-warn', label: `TLS off — ${a} transmits plaintext`, defaultValue: 'Warning', hint: `The ${a} is network-reachable but TLS is off. Traffic travels in plaintext. Enable TLS or use a terminating reverse proxy.` }); }
+      if (listenerEnabled) { fields.push({ kind: 'status', id: 'network.cors-note', label: 'CORS must be configured manually', defaultValue: 'Info', hint: 'httpListener.enforceCors and httpListener.allowedOrigins are not in ConfigKey union (SDK handoff Item 5). Edit ~/.goodvibes/tui/settings.json to set them, then restart the daemon.' }); }
+    }
     return {
       id: 'network',
       title: 'Network setup',

package/src/input/onboarding/onboarding-wizard-validation.ts

@@ -0,0 +1,77 @@
+import { normalizeText } from './onboarding-wizard-helpers.ts';
+import type { OnboardingWizardControllerLike } from './onboarding-wizard-types.ts';
+import type { OnboardingWizardFieldDefinition, OnboardingWizardStepDefinition } from './onboarding-wizard-types.ts';
+
+export interface WizardStepValidationResult {
+  /** Human-readable error strings for each violating field. */
+  readonly errors: readonly string[];
+  /** ID of the first field that has an error, or null when all pass. */
+  readonly firstOffendingFieldId: string | null;
+}
+
+/**
+ * Validate all fields on a single wizard step, checking:
+ *  - required text / masked fields that are empty
+ *  - required acknowledgement fields that are unchecked
+ *  - any general field-level validation errors (via getFieldValidationError)
+ *
+ * Returns per-field error messages and the first offending field id so the
+ * caller can block navigation and jump focus to the first problem.
+ */
+export function getStepValidationErrors(
+  controller: OnboardingWizardControllerLike,
+  step: OnboardingWizardStepDefinition,
+): WizardStepValidationResult {
+  const errors: string[] = [];
+  let firstOffendingFieldId: string | null = null;
+
+  for (const field of step.fields) {
+    const error = getFieldError(controller, step, field);
+    if (error !== null) {
+      errors.push(error);
+      if (firstOffendingFieldId === null) firstOffendingFieldId = field.id;
+    }
+  }
+
+  return { errors, firstOffendingFieldId };
+}
+
+function getFieldError(
+  controller: OnboardingWizardControllerLike,
+  step: OnboardingWizardStepDefinition,
+  field: OnboardingWizardFieldDefinition,
+): string | null {
+  // Required acknowledgement not checked
+  if (field.kind === 'acknowledgement' && field.required) {
+    if (!controller.isFieldSatisfied(field)) {
+      return `${step.shortLabel}: ${field.label} must be acknowledged before continuing.`;
+    }
+    return null;
+  }
+
+  // Required text / masked field that is empty
+  if ((field.kind === 'text' || field.kind === 'masked') && field.required === true) {
+    const value = normalizeText(controller.getFieldValue(field) as string);
+    if (value.length === 0) {
+      return `${step.shortLabel}: ${field.label} is required.`;
+    }
+  }
+
+  // Delegate all other field-level validation (format errors, port range, etc.)
+  return controller.getFieldValidationError(step, field);
+}
+
+/**
+ * Focus the first offending field on the current step by mutating the
+ * controller's selectedFieldIndices.  The renderer will pick up the change on
+ * the next paint cycle.
+ */
+export function focusFirstOffendingField(
+  controller: OnboardingWizardControllerLike,
+  fieldId: string,
+): void {
+  const fields = controller.currentStep.fields;
+  const index = fields.findIndex((f) => f.id === fieldId);
+  if (index < 0) return;
+  controller.selectedFieldIndices[controller.stepIndex] = index;
+}

package/src/input/settings-modal-behavior.ts

@@ -33,5 +33,10 @@ export function getNumericAdjustmentMeta(setting: ConfigSetting): {
   if (setting.key === 'wrfc.scoreThreshold') {
     return { step: 0.1, min: 0, max: 10, precision: 1 };
   }
+  if ((setting.key as string) === 'tts.speed') {
+    // Speed multiplier: 0.1 increments, min 0.1, no hard max (provider-defined).
+    // tts.speed is not yet a ConfigKey in the SDK schema; cast required.
+    return { step: 0.1, min: 0.1, precision: 1 };
+  }
   return { step: 1, precision: 0 };
 }