@pellux/goodvibes-tui 0.18.13 → 0.18.18

package/CHANGELOG.md

@@ -4,6 +4,145 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.18.18] — 2026-04-16
+
+### Performance
+
+- **R1 — Render coalescing** (`src/runtime/bootstrap-core.ts`): `requestRender()` is now wrapped in a `setImmediate`-based coalescer. A burst of N synchronous `requestRender()` calls in a single microtask produces exactly one render pass. A 16ms minimum-interval gate is applied to cap rendering at ~60fps during streaming (prevents hundreds of full pipeline runs per second on LLM token bursts).
+- **R2 — Panel dirty-flag activation** (`src/renderer/panel-composite.ts`, `src/panels/base-panel.ts`, `src/panels/types.ts`): The existing `needsRender` field is now enforced. Added `invalidate(): void` and `markRendered(): void` to the `Panel` interface and `BasePanel`. `buildPanelCompositeData` routes all panel renders through a new `renderPanel()` helper backed by a per-panel `WeakMap` cache — panels that have not changed and whose dimensions are unchanged are skipped entirely. `ScrollableListPanel` and all 40+ panels that write `needsRender = true` on state mutation are compatible without changes (the contract was already partially in place; this activates it).
+- **R3 — Buffer reuse** (`src/renderer/buffer.ts`, `src/renderer/compositor.ts`): `TerminalBuffer` gains a `reset(width, height): void` method that overwrites cells in-place instead of reallocating. `Compositor` now holds two long-lived `TerminalBuffer` instances (front/back). Each `composite()` call resets the back buffer, composites into it, diffs against the front buffer (the last-rendered frame), writes the diff, then swaps front/back. The `clone()` call that doubled allocation cost every frame is eliminated. `TerminalBuffer` constructor is called twice per session (once per buffer), not once per frame.
+
+### Tests
+
+- Added `src/test/renderer/render-perf.test.ts` with 10 new tests covering R1 coalescing logic, R2 dirty-flag skip/invalidate/markRendered contract, and R3 `TerminalBuffer.reset()` behavior.
+- Extended `src/test/renderer/compositor.test.ts` with 3 new tests covering R3 double-buffer reuse correctness (buffer identity after swap, resetDiff clearing both buffers, resize handling).
+- Updated mock `Panel` objects in `src/test/renderer/panel-navigation.test.ts`, `src/test/panels/panel-manager.test.ts`, `src/test/panels/panel-list-panel.test.ts`, and `src/test/daemon/server.test.ts` to implement the new `invalidate()`/`markRendered()` interface methods.
+- Test suite: 438/438 passing, typecheck clean, architecture check green.
+
+---
+
+## [0.18.17] — 2026-04-16
+
+### Bug Fixes
+
+- **Companion pairing token registered with embedded daemon**: `src/runtime/bootstrap.ts` now loads the persistent companion-pairing token via `getOrCreateCompanionToken('tui')` and passes it as `sharedDaemonToken` to `startExternalServices`. The TUI's QR panel advertises this token as the bearer for phone pairing; before this fix, the embedded daemon was started with no shared token and rejected every scanned token with `authenticated: false, authMode: "invalid"`
+- **QR code visual alignment**: `src/renderer/qr-renderer.ts` now uses `leftPad = 1` (down from 2) and prepends a single top quiet-band row. The QR's finder patterns now register symmetrically on both axes; previous rendering was mis-aligned by one cell horizontally and had no top quiet band
+
+### Dependencies
+
+- Bumped `@pellux/goodvibes-sdk` 0.18.36 → 0.18.37, picking up: `sharedDaemonToken`/`sharedHttpListenerToken` factory options on `startHostServices`, bootstrap credential drift detection that warns when `auth-bootstrap.txt` falls out of sync with `auth-users.json`
+- Regenerated `docs/foundation-artifacts/*` against SDK 0.18.37
+
+### Tests
+
+- Updated `src/test/runtime/bootstrap-services.test.ts` `daemonEnable`/`listenerEnable` expectations to include the new second argument (`undefined` when no shared token is supplied)
+- Test suite: 437/437 passing, typecheck clean, architecture check green
+
+---
+
+## [0.18.16] — 2026-04-16
+
+### Bug Fixes
+
+- **resolveToolLLM tests**: enabled `tools.llmEnabled` by default in `createTestManagers()` (`src/test/helpers/test-managers.ts`) so tool LLM resolution tests exercise the resolution logic directly; previously every test hit the gate and resolved to `null`
+- **Domain boundary contract test (GC-ARCH-001)**: removed `'conversation'` and `'permissions'` from the `DOMAINS` array in `src/runtime/store/domains/domain-read-matrix.ts` — the files they referenced were deleted in 0.18.15 and the filesystem↔array consistency check was failing
+
+### Architecture
+
+- **settings-modal decomposition**: extracted 10 pure helpers (`formatValue`, `valueColor`, `flagStateColor`, `mcpTrustColor`, `subscriptionStateColor`, `inferSubscriptionRouteReason`, `CATEGORY_LABELS`, `SETTING_LABELS`, `getSettingLabel`, `describeUiRouting`) into `src/renderer/settings-modal-helpers.ts`. `settings-modal.ts` drops from 844 → 737 lines, back under the 800-line architecture cap
+
+### Dependencies
+
+- Bumped `@pellux/goodvibes-sdk` 0.18.33 → 0.18.36, picking up: daemon shutdown symmetry, event bus iteration fix, atomic session writes, rate limiter TTL + LRU + sweep, `fetchWithTimeout` helper, restored port honoring in `resolveHostBinding` for `local`/`network` hostModes, and restored constructor-injected port/host in `resolveDaemonFacadeRuntime`
+- Regenerated `docs/foundation-artifacts/*` against the new SDK
+
+### Tests & Checks
+
+- Test suite: 437/437 passing (was 431/437 after 0.18.15)
+- Architecture check: passing (was failing with `settings-modal.ts` 844 > 800-line cap)
+- Typecheck: clean
+
+---
+
+## [0.18.15] — 2026-04-16
+
+### Correctness Fix
+
+- **daemon SIGINT/SIGTERM drain**: `src/daemon/cli.ts` — added AbortController signaling for in-flight requests, 15-second `Promise.race` shutdown deadline, hard `process.exit(1)` if deadline exceeded, debounced double-signal guard (`shutdownInFlight` flag)
+
+### Dead Code Removal (Tier 3 items 15-17)
+
+- Deleted 15 TUI mirror files with zero external importers:
+  - `src/runtime/diagnostics/index.ts`, `provider.ts`, `actions.ts`
+  - `src/runtime/diagnostics/panels/agents.ts`, `events.ts`, `health.ts`, `tasks.ts`, `tool-calls.ts`
+  - `src/runtime/store/helpers/reducers.ts` (barrel) and 4 sub-reducers
+  - `src/runtime/store/domains/permissions.ts`, `conversation.ts`
+- Updated `src/runtime/diagnostics/panels/index.ts` to re-export deleted panels from SDK
+
+### Config Re-export Shim Inlining (Tier 3 item 18)
+
+- Deleted `src/config/service-registry.ts` and `src/config/subscription-providers.ts` (1-line SDK re-exports)
+- Updated 29 call sites to import directly from `@pellux/goodvibes-sdk/platform/config/*`
+
+### SDK Consolidation — UI Read Models (Tier 3 items 19-20)
+
+- Converted 9 TUI mirror files to 1-line SDK re-exports (preserving all call-site import paths):
+  - `ui-events.ts`, `ui-service-queries.ts`, `ui-read-model-helpers.ts`
+  - `ui-read-models-observability.ts` and 4 observability sub-files (maintenance, options, remote, security, system)
+- Skipped (TUI-specific divergence): `ui-services.ts` (uses TUI `SecretsManager` subclass), `ui-read-models.ts` (depends on TUI `RuntimeServices`)
+- panel-resources drift: TUI version (119 lines) uses `panel-health-monitor.ts`; SDK version (152 lines) uses `component-health-monitor.js` — different monitor interfaces, TUI-specific binding kept
+
+---
+
+## [0.18.14] — 2026-04-16
+
+### Panel Navigation Overhaul
+
+- Created `ScrollableListPanel<T>` and `SearchableListPanel<T>` base classes in `src/panels/scrollable-list-panel.ts`
+- Migrated 30 panels from hand-coded scroll/cursor management to the shared base classes
+- All list panels now have consistent navigation: up/down/j/k, pageup/pagedown, home/end/g/G, enter to select
+- Selection is always visible within the viewport — guaranteed by `getVisibleWindow()` from `surface-layout.ts`
+- Removed ~150 lines of duplicated scroll boilerplate across panels
+
+### Modal Viewport Fixes
+
+- Fixed modal sizing: height is exactly 45% of viewport (both min and max — all modals same size), width is 50% with 25% minimum
+- Fixed modal scroll/selection: 6 modal/overlay files updated to use shared `getVisibleWindow()` instead of inline scroll math
+- Autocomplete overlay, file picker, bookmark modal, session picker, profile picker, and live tail modal all use the same viewport function
+
+### Settings Modal: Tools Tab
+
+- Added proper tools tab UI with "Tool LLM" and "Helper Model" section headers
+- Helper config keys (`helper.enabled`, `helper.globalProvider`, `helper.globalModel`) now routed into the tools tab
+- Boolean settings display as [on]/[off] toggles
+- Selecting a provider/model setting opens the full model picker instead of a text field
+- Model picker now supports 3 target modes: main, helper, and tool
+- Selecting a helper/tool model auto-enables the feature (`helper.enabled: true` / `tools.llmEnabled: true`)
+
+### QR Code Pairing for Companion Apps
+
+- Added `/qrcode` command (aliases `/qr`, `/pair`) that opens a QR code panel
+- QR panel displays connection info (daemon URL, token, username) + scannable QR code
+- QR rendered using Unicode half-block characters (▀/▄/█) for compact terminal display
+- Supports `r` to regenerate token (invalidates old one) and `c` to copy token to clipboard
+- Daemon standalone mode (`goodvibes-daemon`) now prints QR + connection info to stdout on startup
+- Companion tokens persist to `.goodvibes/tui/companion-token.json` with `gv_` prefix
+- Built on SDK 0.18.30 pairing module
+
+### Health Monitoring Rename
+
+- Renamed `panelHealthMonitor` to `componentHealthMonitor` across 20 files to align with SDK 0.18.29's generic naming
+- Deprecated `Panel*` type aliases preserved for backward compatibility
+
+### SDK 0.18.30 Update
+
+- Updated to `@pellux/goodvibes-sdk@0.18.30`
+- Consumes new pairing module, `tools.llmEnabled` config, and all 0.18.29 boundary cleanup
+
+### Verification
+
+- Full typecheck passes: `bun x tsc --noEmit` — 0 errors
+
 ## [0.18.13] — 2026-04-16
 
 ### SDK/TUI Boundary Separation

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.18.13-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.18.18-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.18.29"
+    "version": "0.18.37"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.18.13",
+  "version": "0.18.18",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -16,6 +16,7 @@
     "src",
     "!src/test",
     "!src/**/*.test.ts",
+    "!src/**/__tests__",
     "scripts/postinstall.js",
     "README.md",
     "CHANGELOG.md",
@@ -88,7 +89,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.18.29",
+    "@pellux/goodvibes-sdk": "0.18.37",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/daemon/cli.ts

@@ -1,4 +1,5 @@
-import { homedir } from 'node:os';
+import { homedir, networkInterfaces } from 'node:os';
+import { readFileSync } from 'node:fs';
 import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 import { RuntimeEventBus } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
 import { createRuntimeStore } from '../runtime/store/index.ts';
@@ -8,6 +9,13 @@ import { HttpListener } from '@pellux/goodvibes-sdk/platform/daemon/http-listene
 import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
 import { GlobalNetworkTransportInstaller } from '@pellux/goodvibes-sdk/platform/runtime/network/index';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+import {
+  getOrCreateCompanionToken,
+  buildCompanionConnectionInfo,
+  encodeConnectionPayload,
+  formatConnectionBlock,
+} from '@pellux/goodvibes-sdk/platform/pairing/index';
+import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing/qr-generator';
 
 type DaemonCliOwnership = {
   readonly workingDirectory: string;
@@ -19,6 +27,32 @@ type DaemonCliTokens = {
   readonly httpToken: string | undefined;
 };
 
+function getLocalNetworkIp(): string {
+  const nets = networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name] ?? []) {
+      if (net.family === 'IPv4' && !net.internal) {
+        return net.address;
+      }
+    }
+  }
+  return 'localhost';
+}
+
+function readBootstrapPassword(credentialPath: string): string | undefined {
+  try {
+    const content = readFileSync(credentialPath, 'utf-8');
+    for (const line of content.split('\n')) {
+      if (line.startsWith('password=')) {
+        return line.slice('password='.length).trim();
+      }
+    }
+  } catch {
+    // credential file may not exist yet
+  }
+  return undefined;
+}
+
 function resolveDaemonCliOwnership(): DaemonCliOwnership {
   return {
     workingDirectory: process.cwd(),
@@ -58,26 +92,68 @@ async function main(): Promise<void> {
   });
   const { daemonToken, httpToken } = readDaemonCliTokens(process.env);
 
-  daemon.enable({ daemon: true }, daemonToken);
-  listener.enable({ httpListener: true }, httpToken);
+  // If no explicit daemon token is set, use the companion token so mobile apps can connect.
+  const companionTokenRecord = getOrCreateCompanionToken('tui');
+  const effectiveDaemonToken = daemonToken ?? companionTokenRecord.token;
+  const effectiveHttpToken = httpToken ?? effectiveDaemonToken;
+
+  daemon.enable({ daemon: true }, effectiveDaemonToken);
+  listener.enable({ httpListener: true }, effectiveHttpToken);
 
   await Promise.all([
     daemon.start(),
     config.get('danger.httpListener') ? listener.start() : Promise.resolve(),
   ]);
 
+  const abortController = new AbortController();
+
   const shutdown = async (): Promise<void> => {
-    await Promise.allSettled([listener.stop(), daemon.stop()]);
+    abortController.abort();
+    const SHUTDOWN_DEADLINE_MS = 15_000;
+    const timeout = new Promise<'timeout'>((resolve) =>
+      setTimeout(() => resolve('timeout'), SHUTDOWN_DEADLINE_MS)
+    );
+    const stop = Promise.allSettled([listener.stop(), daemon.stop()]).then(() => 'done' as const);
+    const result = await Promise.race([stop, timeout]);
+    if (result === 'timeout') {
+      logger.warn('shutdown deadline exceeded — forcing exit');
+      process.exit(1);
+    }
     process.exit(0);
   };
 
-  process.on('SIGINT', () => void shutdown());
-  process.on('SIGTERM', () => void shutdown());
+  let shutdownInFlight = false;
+  const handleSignal = (): void => {
+    if (shutdownInFlight) return;
+    shutdownInFlight = true;
+    void shutdown();
+  };
+
+  process.on('SIGINT', handleSignal);
+  process.on('SIGTERM', handleSignal);
 
   logger.info('goodvibes daemon host started', {
     daemon: config.get('danger.daemon'),
     httpListener: config.get('danger.httpListener'),
   });
+
+  // Print companion connection info + QR code to stdout.
+  // Use the config-driven control plane port, not a hardcoded default.
+  const daemonPort = config.get('controlPlane.port');
+  const daemonHost = String(process.env.GOODVIBES_DAEMON_HOST ?? getLocalNetworkIp());
+  const daemonUrl = `http://${daemonHost}:${daemonPort}`;
+  const bootstrapPassword = readBootstrapPassword(userAuth.getBootstrapCredentialPath());
+  const connectionInfo = buildCompanionConnectionInfo({
+    daemonUrl,
+    token: companionTokenRecord.token,
+    password: bootstrapPassword,
+    surface: 'tui',
+  });
+  const payload = encodeConnectionPayload(connectionInfo);
+  const qrMatrix = generateQrMatrix(payload);
+  const qrString = renderQrToString(qrMatrix);
+  // eslint-disable-next-line no-console
+  console.log(formatConnectionBlock(connectionInfo, qrString));
 }
 
 void main().catch(async (error) => {

package/src/input/command-registry.ts

@@ -62,6 +62,8 @@ export interface CommandUiActions {
     model: { id: string; provider: string; displayName: string; registryKey: string };
     effort: string;
     contextCap?: number | null;
+    /** Which config target to write the selected model to. Defaults to 'main'. */
+    target?: import('./model-picker.ts').ModelPickerTarget;
   }) => void;
   clearScreen?: () => void;
   activatePlan?: (planId: string, task: string) => void;

package/src/input/commands/control-room-runtime.ts

@@ -1,7 +1,7 @@
 import type { CommandRegistry } from '../command-registry.ts';
 import { buildMcpAttackPathReview } from '@pellux/goodvibes-sdk/platform/runtime/mcp/index';
 import { buildKnowledgeInjectionPrompt, selectKnowledgeForTask } from '@pellux/goodvibes-sdk/platform/state/knowledge-injection';
-import { listBuiltinSubscriptionProviders } from '../../config/subscription-providers.ts';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import { requireReadModels, requireSubscriptionManager, requireTokenAuditor } from './runtime-services.ts';
 import { getMemoryApi } from './recall-query.ts';
 

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

@@ -1,4 +1,4 @@
-import { ServiceRegistry } from '../../config/service-registry.ts';
+import { ServiceRegistry } from '@pellux/goodvibes-sdk/platform/config/service-registry';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 import { evaluateSessionMaintenance, formatSessionMaintenanceLines } from '@pellux/goodvibes-sdk/platform/runtime/session-maintenance';
 import { estimateConversationTokens } from '@pellux/goodvibes-sdk/platform/core/context-compaction';

package/src/input/commands/local-setup-review.ts

@@ -5,7 +5,7 @@ import { discoverSkills } from '../../panels/skills-panel.ts';
 import { buildSandboxReview, isRunningInWsl } from '@pellux/goodvibes-sdk/platform/runtime/sandbox/manager';
 import { renderQemuWrapperTemplate } from '@pellux/goodvibes-sdk/platform/runtime/sandbox/qemu-wrapper-template';
 import { getPluginDirectories } from '../../plugins/loader';
-import { listBuiltinSubscriptionProviders } from '../../config/subscription-providers.ts';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import type { SetupReviewSnapshot } from './local-setup-transfer.ts';
 import { requireProviderApi, requireReadModels, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from './runtime-services.ts';
 

package/src/input/commands/platform-access-runtime.ts

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import type { CommandRegistry } from '../command-registry.ts';
 import { VERSION } from '../../version.ts';
-import { listBuiltinSubscriptionProviders } from '../../config/subscription-providers.ts';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import { handleLocalAuthCommand } from './local-auth-runtime.ts';
 import { buildAuthInspectionSnapshot, inspectProviderAuth } from '@pellux/goodvibes-sdk/platform/runtime/auth/inspection';
 import { requireProfileManager, requireSecretsManager, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from './runtime-services.ts';

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

@@ -0,0 +1,20 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { openCommandPanel } from './runtime-services.ts';
+
+/**
+ * Register the /qrcode command.
+ *
+ * Opens the QR Code panel which displays a scannable QR code for
+ * companion app pairing, along with connection URL, token, and username.
+ */
+export function registerQrcodeRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'qrcode',
+    aliases: ['qr', 'pair'],
+    description: 'Open the QR code panel for companion app pairing',
+    usage: '',
+    handler(_args, ctx) {
+      openCommandPanel(ctx, 'qr-code');
+    },
+  });
+}

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

@@ -4,7 +4,7 @@ import type { CommandContext, CommandRegistry } from '../command-registry.ts';
 import { createOAuthLocalListener } from '@pellux/goodvibes-sdk/platform/config/oauth-local-listener';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config/openai-codex-auth';
 import type { OAuthProviderConfig, ProviderSubscription } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
-import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '../../config/subscription-providers.ts';
+import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import { inspectProviderAuth } from '@pellux/goodvibes-sdk/platform/runtime/auth/inspection';
 import { openExternalUrl } from '@pellux/goodvibes-sdk/platform/utils/open-external';
 import { requireSecretsManager, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from './runtime-services.ts';

package/src/input/commands.ts

@@ -52,6 +52,7 @@ import { registerProviderAccountsRuntimeCommands } from './commands/provider-acc
 import { registerLocalAuthRuntimeCommands } from './commands/local-auth-runtime.ts';
 import { registerIntelligenceRuntimeCommands } from './commands/intelligence-runtime.ts';
 import { registerConversationRuntimeCommands } from './commands/conversation-runtime.ts';
+import { registerQrcodeRuntimeCommands } from './commands/qrcode-runtime.ts';
 
 /**
  * registerBuiltinCommands - Register all built-in slash commands into the registry.
@@ -98,6 +99,7 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registerLocalAuthRuntimeCommands(registry);
   registerIntelligenceRuntimeCommands(registry);
   registerConversationRuntimeCommands(registry);
+  registerQrcodeRuntimeCommands(registry);
   registerLocalRuntimeCommands(registry);
   registerSessionWorkflowCommands(registry);
   registerDiscoveryRuntimeCommands(registry);

package/src/input/handler-feed.ts

@@ -166,6 +166,12 @@ export function feedInputTokens(context: InputFeedContext, tokens: readonly Inpu
       searchManager: context.searchManager,
       scroll: context.scroll,
       getScrollTop: context.getScrollTop,
+      openModelPickerWithTarget: context.commandContext?.openModelPicker
+        ? (target: import('./model-picker.ts').ModelPickerTarget) => {
+            context.modelPicker.target = target;
+            context.commandContext!.openModelPicker!();
+          }
+        : undefined,
     }, token);
     context.selectionCallback = modalRoute.selectionCallback;
     context.helpOverlayActive = modalRoute.helpOverlayActive;

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

@@ -215,7 +215,10 @@ type SettingsRouteState = {
     nextCategory: () => void;
     editBackspace: () => void;
     editChar: (char: string) => void;
+    pendingModelPickerTarget: import('./model-picker.ts').ModelPickerTarget | null;
   };
+  /** Called when the settings modal requests the model picker for a non-main target. */
+  openModelPickerWithTarget?: (target: import('./model-picker.ts').ModelPickerTarget) => void;
   requestRender: () => void;
   handleEscape: () => void;
 };
@@ -231,7 +234,14 @@ export function handleSettingsModalToken(state: SettingsRouteState, token: Input
     if (token.logicalName === 'enter' || (token.logicalName === 'space' && !state.settingsModal.editingMode)) {
       if (state.settingsModal.editingMode) state.settingsModal.commitEdit();
       else if (state.settingsModal.currentCategory === 'flags') state.settingsModal.toggleSelectedFlag();
-      else state.settingsModal.activateSelected();
+      else {
+        state.settingsModal.activateSelected();
+        const pickerTarget = state.settingsModal.pendingModelPickerTarget;
+        if (pickerTarget !== null) {
+          state.settingsModal.pendingModelPickerTarget = null;
+          state.openModelPickerWithTarget?.(pickerTarget);
+        }
+      }
     } else if ((token.logicalName === 'left' || token.logicalName === 'right') && !state.settingsModal.editingMode) {
       state.settingsModal.adjustSelected(token.logicalName, token.shift ? 10 : 1);
     } else if (token.logicalName === 'up') state.settingsModal.moveUp();
@@ -241,7 +251,14 @@ export function handleSettingsModalToken(state: SettingsRouteState, token: Input
   } else if (token.type === 'text') {
     if (token.value === ' ' && !state.settingsModal.editingMode) {
       if (state.settingsModal.currentCategory === 'flags') state.settingsModal.toggleSelectedFlag();
-      else state.settingsModal.activateSelected();
+      else {
+        state.settingsModal.activateSelected();
+        const pickerTarget = state.settingsModal.pendingModelPickerTarget;
+        if (pickerTarget !== null) {
+          state.settingsModal.pendingModelPickerTarget = null;
+          state.openModelPickerWithTarget?.(pickerTarget);
+        }
+      }
     } else if (state.settingsModal.editingMode) {
       state.settingsModal.editChar(token.value);
     }

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

@@ -72,6 +72,8 @@ export type ModalTokenRouteState = {
   searchManager: SearchManager;
   scroll: (delta: number) => void;
   getScrollTop: () => number;
+  /** Callback to open the model picker with a specific target (helper or tool). Optional — only wired when available. */
+  openModelPickerWithTarget?: (target: import('./model-picker.ts').ModelPickerTarget) => void;
 };
 
 export function handleModalTokenRoutes(state: ModalTokenRouteState, token: InputToken): {
@@ -117,6 +119,7 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
 
   if (handleSettingsModalToken({
     settingsModal: state.settingsModal,
+    openModelPickerWithTarget: state.openModelPickerWithTarget,
     requestRender: state.requestRender,
     handleEscape: state.handleEscape,
   }, token)) {

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

@@ -57,9 +57,11 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
           if (selected.reasoningEffort && selected.reasoningEffort.length > 0) {
             state.modelPicker.showEffortPicker(selected, currentEffort);
           } else {
+            const target = state.modelPicker.target;
             state.commandContext?.completeModelSelection?.({
               model: selected,
               effort: currentEffort,
+              target,
             });
             state.modelPicker.close();
             if (state.modalStack[state.modalStack.length - 1] === 'modelPicker') state.modalStack.pop();
@@ -76,7 +78,7 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
       } else if (mode === 'effort') {
         const model = state.modelPicker.pendingModel;
         const effort = state.modelPicker.effortLevels[idx];
-        if (model && effort) state.commandContext?.completeModelSelection?.({ model, effort });
+        if (model && effort) state.commandContext?.completeModelSelection?.({ model, effort, target: state.modelPicker.target });
         state.modelPicker.close();
         if (state.modalStack[state.modalStack.length - 1] === 'modelPicker') state.modalStack.pop();
       } else if (mode === 'contextCap') {
@@ -86,7 +88,7 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
           const parsedCap = rawInput.length > 0 ? parseInt(rawInput, 10) : null;
           const validCap = parsedCap !== null && parsedCap > 0 && parsedCap <= 10_000_000 ? parsedCap : null;
           const effort = state.commandContext?.session.runtime.reasoningEffort ?? 'medium';
-          state.commandContext?.completeModelSelection?.({ model: capModel, effort, contextCap: validCap });
+          state.commandContext?.completeModelSelection?.({ model: capModel, effort, contextCap: validCap, target: state.modelPicker.target });
         }
         state.modelPicker.close();
         if (state.modalStack[state.modalStack.length - 1] === 'modelPicker') state.modalStack.pop();

package/src/input/model-picker.ts

@@ -7,6 +7,14 @@ import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers/
 
 export type PickerMode = 'model' | 'provider' | 'effort' | 'contextCap';
 
+/**
+ * Which config keys the model picker writes to on commit.
+ * 'main'   → provider.provider + provider.model (default)
+ * 'helper' → helper.globalProvider + helper.globalModel (+ helper.enabled: true)
+ * 'tool'   → tools.llmProvider + tools.llmModel (+ tools.llmEnabled: true)
+ */
+export type ModelPickerTarget = 'main' | 'helper' | 'tool';
+
 /**
  * Pricing tier filter.
  * 'paid' matches ModelDefinition tiers 'standard' and 'premium' for forward-compat
@@ -129,6 +137,8 @@ export class ModelPickerModal {
 
   public active = false;
   public mode: PickerMode = 'model';
+  /** Which config target this picker session will write to on commit. */
+  public target: ModelPickerTarget = 'main';
   public searchFocused = false;
   /** Tracks the mode we came from, for back-navigation. */
   public previousMode: PickerMode | null = null;
@@ -288,6 +298,7 @@ export class ModelPickerModal {
   close(): void {
     this.active = false;
     this.mode = 'model';
+    this.target = 'main';
     this.models = [];
     this.providers = [];
     this.pendingModel = null;

package/src/input/settings-modal.ts

@@ -11,9 +11,10 @@
  */
 
 import { CONFIG_SCHEMA, type ConfigSetting, type ConfigKey, type PersistedFlagState } from '@pellux/goodvibes-sdk/platform/config/schema';
+import type { ModelPickerTarget } from './model-picker.ts';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
-import { listBuiltinSubscriptionProviders } from '../config/subscription-providers.ts';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import type { ProviderAuthFreshness, ProviderAuthRoute } from '@pellux/goodvibes-sdk/platform/runtime/provider-accounts/registry';
 import { getResolvedSettingLookup } from '@pellux/goodvibes-sdk/platform/runtime/settings/control-plane';
 import type { ServiceInspectionQuery } from '../runtime/ui-service-queries.ts';
@@ -84,6 +85,16 @@ export interface SubscriptionEntry {
   nextActions?: string[];
 }
 
+/**
+ * Map a config key to the model picker target it should open, or null if the
+ * setting should use the normal inline text-edit flow.
+ */
+function _modelPickerTargetForKey(key: string): ModelPickerTarget | null {
+  if (key === 'helper.globalProvider' || key === 'helper.globalModel') return 'helper';
+  if (key === 'tools.llmProvider' || key === 'tools.llmModel') return 'tool';
+  return null;
+}
+
 function roundToPrecision(value: number, precision: number): number {
   const factor = 10 ** precision;
   return Math.round(value * factor) / factor;
@@ -121,6 +132,12 @@ export class SettingsModal {
   public editBuffer = '';
   /** Server awaiting explicit allow-all confirmation, if any. */
   public mcpAllowAllConfirmationTarget: string | null = null;
+  /**
+   * Set by activateSelected() when the highlighted setting should open the
+   * model picker rather than entering inline text edit mode.
+   * Consumed and cleared by the route handler after each Enter/Space action.
+   */
+  public pendingModelPickerTarget: ModelPickerTarget | null = null;
   /** Provider awaiting explicit logout confirmation, if any. */
   public subscriptionLogoutConfirmationTarget: string | null = null;
 
@@ -307,6 +324,13 @@ export class SettingsModal {
 
     const { setting } = entry;
 
+    // Delegate provider/model picker settings to the model picker UI
+    const pickerTarget = _modelPickerTargetForKey(setting.key);
+    if (pickerTarget !== null) {
+      this.pendingModelPickerTarget = pickerTarget;
+      return;
+    }
+
     if (setting.type === 'boolean') {
       const newVal = !entry.currentValue;
       this._setValue(setting.key, newVal);
@@ -522,7 +546,9 @@ export class SettingsModal {
     }
 
     for (const setting of CONFIG_SCHEMA) {
-      const cat = setting.key.split('.')[0] as SettingsCategory;
+      const rawCat = setting.key.split('.')[0] as string;
+      // Route helper.* settings into the tools group for unified display
+      const cat = (rawCat === 'helper' ? 'tools' : rawCat) as SettingsCategory;
       if (!this.groups.has(cat)) continue;
       const currentValue = configManager.get(setting.key as ConfigKey);
       const resolved = getResolvedSettingLookup(configManager, setting.key as ConfigKey)?.entry;
@@ -702,7 +728,9 @@ export class SettingsModal {
     try {
       this.configManager.setDynamic(key, value);
       // Update the cached entry in-place — avoids full schema re-scan on each edit
-      const cat = key.split('.')[0] as SettingsCategory;
+      const rawCat = key.split('.')[0] as string;
+      // helper.* entries are stored in the tools group
+      const cat = (rawCat === 'helper' ? 'tools' : rawCat) as SettingsCategory;
       const entries = this.groups.get(cat);
       if (entries) {
         const entry = entries.find(e => e.setting.key === key);