@pellux/goodvibes-tui 0.19.24 → 0.19.26

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.19.26] — 2026-04-24
+
+### Changes
+- f1e0ac3 feat: harden CLI operations and support bundles
+- 0c94095 feat: enforce readiness command exit codes
+- 566bc34 feat: improve CLI help and listener readiness
+- d620637 feat: harden CLI diagnostics and provider posture
+
+## [0.19.25] — 2026-04-24
+
+### Changes
+- 705a19b feat: add onboarding wizard and CLI management
+
 ## [0.19.24] — 2026-04-22
 
 Four correctness and honesty fixes from an external architecture review. No SDK change (pinned at 0.23.2).

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.19.24-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.19.26-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.
 
@@ -380,10 +380,10 @@ Alternatively, store keys encrypted using the `/secrets` command. Environment va
 For self-hosted or external secret managers, link a GoodVibes key to a provider-backed SecretRef:
 
 ```sh
-/secrets link OPENAI_API_KEY bw://GoodVibes%20OpenAI/password?sessionEnv=BW_SESSION
-/secrets link SLACK_BOT_TOKEN vaultwarden://GoodVibes%20Slack/password?server=https%3A%2F%2Fvault.example.test
-/secrets link STRIPE_TOKEN bws://00000000-0000-0000-0000-000000000000/value?accessTokenEnv=BWS_ACCESS_TOKEN
-/secrets link OPENAI_API_KEY op://Private/GoodVibes%20OpenAI/API%20Key
+/secrets link OPENAI_API_KEY goodvibes://secrets/bitwarden?item=GoodVibes%20OpenAI&field=password&sessionEnv=BW_SESSION
+/secrets link SLACK_BOT_TOKEN goodvibes://secrets/vaultwarden?item=GoodVibes%20Slack&field=password&server=https%3A%2F%2Fvault.example.test
+/secrets link STRIPE_TOKEN goodvibes://secrets/bws/00000000-0000-0000-0000-000000000000?field=value&accessTokenEnv=BWS_ACCESS_TOKEN
+/secrets link OPENAI_API_KEY goodvibes://secrets/1password?vault=Private&item=GoodVibes%20OpenAI&field=API%20Key
 ```
 
 Use `/secrets providers` for supported provider shapes and `/secrets test <secret-ref>` to validate a ref without printing its value.

package/bin/goodvibes

@@ -39,8 +39,18 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localPlatformBuild = artifactName ? join(packageRoot, 'dist', artifactName) : null;
+const localBuild = join(packageRoot, 'dist', 'goodvibes');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (localPlatformBuild && isExecutable(localPlatformBuild)) {
+  run(localPlatformBuild, process.argv.slice(2));
+}
+
+if (isExecutable(localBuild)) {
+  run(localBuild, process.argv.slice(2));
+}
+
 if (vendoredBinary && isExecutable(vendoredBinary)) {
   run(vendoredBinary, process.argv.slice(2));
 }

package/bin/goodvibes-daemon

@@ -39,8 +39,18 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localPlatformBuild = artifactName ? join(packageRoot, 'dist', artifactName) : null;
+const localBuild = join(packageRoot, 'dist', 'goodvibes-daemon');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (localPlatformBuild && isExecutable(localPlatformBuild)) {
+  run(localPlatformBuild, process.argv.slice(2));
+}
+
+if (isExecutable(localBuild)) {
+  run(localBuild, process.argv.slice(2));
+}
+
 if (vendoredBinary && isExecutable(vendoredBinary)) {
   run(vendoredBinary, process.argv.slice(2));
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.24",
+  "version": "0.19.26",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -49,6 +49,7 @@
     "publish:dry-run": "bun run scripts/publish-package.ts --dry-run",
     "publish:dry-run:github": "GOODVIBES_PUBLIC_PACKAGE_NAME=@mgd34msu/goodvibes-tui GOODVIBES_PUBLISH_REGISTRY=https://npm.pkg.github.com bun run scripts/publish-package.ts --dry-run",
     "publish:check": "bun run scripts/publish-check.ts",
+    "package:install-check": "bun run scripts/package-install-check.ts",
     "build:prod": "bun run scripts/build.ts",
     "build:all": "bun run scripts/build.ts --all",
     "perf:check": "bun run scripts/perf-check.ts",
@@ -90,7 +91,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.23.2",
+    "@pellux/goodvibes-sdk": "^0.25.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/bundle-command.ts

@@ -0,0 +1,225 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { RuntimeEventBus } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
+import { createShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
+import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers/runtime-snapshot';
+import { createRuntimeServices } from '../runtime/services.ts';
+import { createRuntimeStore } from '../runtime/store/index.ts';
+import { CONFIG_SCHEMA } from '../config/index.ts';
+import { SecretsManager } from '../config/secrets.ts';
+import type { ConfigKey } from '../config/index.ts';
+import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandOutput } from './types.ts';
+import { getPackageVersion } from './help.ts';
+import { classifyProviderSetup } from './provider-classification.ts';
+import { buildCliServicePosture } from './service-posture.ts';
+import { REDACTED_VALUE, collectSensitiveConfigValues, isRedactedValue, redactConfig, redactSerializedSecrets } from './redaction.ts';
+
+interface BundleInspectSummary {
+  readonly type: string;
+  readonly version: string;
+  readonly path: string;
+  readonly capturedAt: number | null;
+  readonly configKeys: number;
+  readonly redactedConfigPaths: readonly string[];
+  readonly hasDiagnostics: boolean;
+}
+
+function formatJsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function getNestedValue(source: unknown, key: string): unknown {
+  let cursor = source;
+  for (const part of key.split('.')) {
+    if (cursor == null || typeof cursor !== 'object') return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+function readJsonFile(path: string): { readonly ok: true; readonly value: Record<string, unknown> } | { readonly ok: false; readonly error: string } {
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown> };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function inspectBundle(path: string, parsed: Record<string, unknown>): BundleInspectSummary {
+  return {
+    type: String(parsed['type'] ?? 'unknown'),
+    version: String(parsed['version'] ?? 'unknown'),
+    path,
+    capturedAt: typeof parsed['capturedAt'] === 'number' ? parsed['capturedAt'] : null,
+    configKeys: parsed['config'] && typeof parsed['config'] === 'object'
+      ? CONFIG_SCHEMA.filter((setting) => getNestedValue(parsed['config'], setting.key) !== undefined).length
+      : 0,
+    redactedConfigPaths: Array.isArray((parsed['redaction'] as { redactedConfigPaths?: unknown } | undefined)?.redactedConfigPaths)
+      ? (parsed['redaction'] as { redactedConfigPaths: string[] }).redactedConfigPaths
+      : [],
+    hasDiagnostics: Boolean(parsed['diagnostics'] && typeof parsed['diagnostics'] === 'object'),
+  };
+}
+
+function readAuthPosture(runtime: CliCommandRuntime) {
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  const userStorePath = shellPaths.resolveUserPath('tui', 'auth-users.json');
+  const bootstrapCredentialPath = shellPaths.resolveUserPath('tui', 'auth-bootstrap.txt');
+  const operatorTokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  return {
+    userStorePath,
+    userStorePresent: existsSync(userStorePath),
+    bootstrapCredentialPath,
+    bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
+    operatorTokenPath,
+    operatorTokenPresent: existsSync(operatorTokenPath),
+  };
+}
+
+async function buildProviderReadiness(runtime: CliCommandRuntime) {
+  const runtimeBus = new RuntimeEventBus();
+  const runtimeStore = createRuntimeStore();
+  const services = createRuntimeServices({
+    configManager: runtime.configManager,
+    runtimeBus,
+    runtimeStore,
+    workingDir: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  services.providerRegistry.initModelLimits();
+  services.benchmarkStore.initBenchmarks();
+  services.providerRegistry.initCatalog();
+  try {
+    await services.providerRegistry.ready();
+    const snapshots = await listProviderRuntimeSnapshots(services.providerRegistry);
+    return snapshots.map((snapshot) => ({
+      provider: snapshot.providerId,
+      active: snapshot.active,
+      configured: snapshot.runtime.auth?.configured ?? true,
+      configuredVia: snapshot.runtime.auth?.mode ?? 'unknown',
+      models: snapshot.modelCount,
+      setup: classifyProviderSetup({
+        providerId: snapshot.providerId,
+        authMode: snapshot.runtime.auth?.mode,
+        configured: snapshot.runtime.auth?.configured ?? true,
+        modelCount: snapshot.modelCount,
+      }),
+    }));
+  } finally {
+    services.providerRegistry.stopWatching();
+  }
+}
+
+export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub = 'inspect', ...rest] = runtime.cli.commandArgs;
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+
+  if (sub === 'inspect') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle inspect <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const summary = inspectBundle(sourcePath, parsed.value);
+    return {
+      output: formatJsonOrText(runtime, summary, [
+        'GoodVibes bundle',
+        `  type: ${summary.type}`,
+        `  version: ${summary.version}`,
+        `  path: ${summary.path}`,
+        `  capturedAt: ${summary.capturedAt === null ? 'n/a' : new Date(summary.capturedAt).toISOString()}`,
+        `  configKeys: ${summary.configKeys}`,
+        `  redactedConfigKeys: ${summary.redactedConfigPaths.length}`,
+        `  diagnostics: ${summary.hasDiagnostics ? 'present' : 'missing'}`,
+      ].join('\n')),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'export') {
+    const outputPath = rest[0] ?? 'goodvibes-bundle.json';
+    const secrets = new SecretsManager({
+      projectRoot: runtime.workingDirectory,
+      globalHome: runtime.homeDirectory,
+      configManager: runtime.configManager,
+    });
+    const rawConfig = runtime.configManager.getRaw();
+    const sensitiveValues = collectSensitiveConfigValues(rawConfig);
+    const redactedConfig = redactConfig(rawConfig);
+    const service = await buildCliServicePosture(runtime, { logTailBytes: 8192 });
+    const bundle = {
+      version: 2,
+      type: 'goodvibes.support',
+      capturedAt: Date.now(),
+      package: {
+        name: '@pellux/goodvibes-tui',
+        version: getPackageVersion(),
+      },
+      roots: {
+        workingDirectory: runtime.workingDirectory,
+        homeDirectory: runtime.homeDirectory,
+      },
+      config: redactedConfig.value,
+      redaction: {
+        sentinel: REDACTED_VALUE,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+      },
+      diagnostics: {
+        service,
+        auth: readAuthPosture(runtime),
+        providers: await buildProviderReadiness(runtime),
+      },
+      secrets: await secrets.inspect(),
+      onboarding: {
+        projectMarker: existsSync(shellPaths.resolveProjectPath('tui', 'onboarding.json')),
+        userMarker: existsSync(shellPaths.resolveUserPath('tui', 'onboarding.json')),
+      },
+    };
+    const targetPath = shellPaths.resolveWorkspacePath(outputPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, redactSerializedSecrets(JSON.stringify(bundle, null, 2), sensitiveValues) + '\n', 'utf-8');
+    return {
+      output: formatJsonOrText(runtime, {
+        path: targetPath,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+        serviceIssues: service.issues,
+      }, `Bundle exported: ${targetPath}\n  redactedConfigKeys: ${redactedConfig.redactedPaths.length}\n  serviceIssues: ${service.issues.length}`),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'import') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle import <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const config = parsed.value['config'];
+    if (!config || typeof config !== 'object') return { output: 'Bundle has no config object to import.', exitCode: 1 };
+    let count = 0;
+    let skippedRedacted = 0;
+    for (const setting of CONFIG_SCHEMA) {
+      const value = getNestedValue(config, setting.key);
+      if (value === undefined) continue;
+      if (isRedactedValue(value)) {
+        skippedRedacted++;
+        continue;
+      }
+      runtime.configManager.setDynamic(setting.key as ConfigKey, value as never);
+      count++;
+    }
+    return {
+      output: `Bundle imported: ${count} config value${count === 1 ? '' : 's'} applied.${skippedRedacted ? ` ${skippedRedacted} redacted value${skippedRedacted === 1 ? '' : 's'} skipped.` : ''}`,
+      exitCode: 0,
+    };
+  }
+
+  return { output: 'Usage: goodvibes bundle export [path]|inspect <path>|import <path>', exitCode: 2 };
+}

package/src/cli/completion.ts

@@ -0,0 +1,90 @@
+const COMMANDS = [
+  'tui',
+  'run',
+  'exec',
+  'serve',
+  'web',
+  'service',
+  'onboarding',
+  'setup',
+  'doctor',
+  'status',
+  'models',
+  'providers',
+  'auth',
+  'subscription',
+  'secrets',
+  'sessions',
+  'tasks',
+  'pair',
+  'qrcode',
+  'surfaces',
+  'listener',
+  'control-plane',
+  'bundle',
+  'remote',
+  'bridge',
+  'completion',
+  'version',
+  'help',
+] as const;
+
+const OPTIONS = [
+  '--help',
+  '--version',
+  '--model',
+  '--provider',
+  '--cd',
+  '--working-dir',
+  '--daemon-home',
+  '--config',
+  '--enable',
+  '--disable',
+  '--prompt',
+  '--print',
+  '--output',
+  '--output-format',
+  '--json',
+  '--no-alt-screen',
+  '--port',
+  '--hostname',
+  '--open',
+  '--resume',
+  '--session',
+  '--continue',
+  '--fork',
+  '--password',
+  '--password-stdin',
+  '--role',
+  '--manual',
+] as const;
+
+export function renderCompletion(shell: string | undefined, binary = 'goodvibes'): string {
+  const normalized = (shell ?? 'bash').toLowerCase();
+  const words = [...COMMANDS, ...OPTIONS].join(' ');
+
+  if (normalized === 'zsh') {
+    return [
+      `#compdef ${binary}`,
+      `_${binary}() {`,
+      `  compadd -- ${words}`,
+      '}',
+      `_${binary} "$@"`,
+    ].join('\n');
+  }
+
+  if (normalized === 'fish') {
+    return [...COMMANDS, ...OPTIONS]
+      .map((word) => `complete -c ${binary} -a ${JSON.stringify(word)}`)
+      .join('\n');
+  }
+
+  return [
+    `_${binary}() {`,
+    '  local cur',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    `  COMPREPLY=( $(compgen -W "${words}" -- "$cur") )`,
+    '}',
+    `complete -F _${binary} ${binary}`,
+  ].join('\n');
+}

package/src/cli/config-overrides.ts

@@ -0,0 +1,159 @@
+import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig, PersistedFlagState } from '../config/index.ts';
+import { CONFIG_SCHEMA, ConfigError } from '../config/index.ts';
+import type { GoodVibesCliCommand, GoodVibesCliFlags } from './types.ts';
+import { RUNTIME_ENDPOINT_CONFIG_KEYS, hostModeForHostname } from './endpoints.ts';
+import type { RuntimeEndpointId } from './endpoints.ts';
+
+const CONFIG_SCHEMA_BY_KEY = new Map<string, ConfigSetting>(
+  CONFIG_SCHEMA.map((setting) => [setting.key, setting]),
+);
+
+function parseConfigOverrideValue(value: string): unknown {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return '';
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+    return value;
+  }
+}
+
+function getRuntimeConfig(configManager: ConfigManager): GoodVibesConfig {
+  const mutable = configManager as unknown as { config?: GoodVibesConfig };
+  if (!mutable.config || typeof mutable.config !== 'object') {
+    throw new ConfigError('ConfigManager runtime config is not available for CLI overrides.');
+  }
+  return mutable.config;
+}
+
+function validateConfigValue(setting: ConfigSetting, value: unknown): void {
+  if (setting.type === 'boolean' && typeof value !== 'boolean') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected boolean.`);
+  }
+  if (setting.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected number.`);
+  }
+  if (setting.type === 'string' && typeof value !== 'string') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected string.`);
+  }
+  if (setting.type === 'enum' && setting.enumValues && !setting.enumValues.includes(String(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: "${String(value)}". Allowed: ${setting.enumValues.join(', ')}`);
+  }
+  if (setting.validate && !setting.validate(value)) {
+    throw new ConfigError(`Invalid value for ${setting.key}: ${String(value)}`);
+  }
+}
+
+function setNestedConfigValue(config: GoodVibesConfig, key: ConfigKey, value: unknown): void {
+  const parts = key.split('.');
+  let cursor: unknown = config;
+  for (const part of parts.slice(0, -1)) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in cursor)) {
+      throw new ConfigError(`Invalid config path: section '${part}' does not exist`);
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  if (cursor == null || typeof cursor !== 'object') {
+    throw new ConfigError(`Invalid config path: section '${parts.slice(0, -1).join('.')}' does not exist`);
+  }
+  (cursor as Record<string, unknown>)[parts[parts.length - 1]!] = value;
+}
+
+export function applyRuntimeConfigValue(configManager: ConfigManager, key: ConfigKey, value: unknown): void {
+  const setting = CONFIG_SCHEMA_BY_KEY.get(key);
+  if (!setting) {
+    throw new ConfigError(`Unknown config key: ${key}`);
+  }
+  validateConfigValue(setting, value);
+  setNestedConfigValue(getRuntimeConfig(configManager), key, value);
+}
+
+export function applyRuntimeConfigOverrides(
+  configManager: ConfigManager,
+  overrides: readonly string[],
+): readonly string[] {
+  const errors: string[] = [];
+  for (const override of overrides) {
+    const index = override.indexOf('=');
+    if (index <= 0) {
+      errors.push(`Invalid --config override "${override}". Expected key=value.`);
+      continue;
+    }
+    const key = override.slice(0, index) as ConfigKey;
+    const rawValue = override.slice(index + 1);
+    try {
+      applyRuntimeConfigValue(configManager, key, parseConfigOverrideValue(rawValue));
+    } catch (error) {
+      errors.push(error instanceof Error ? `Invalid --config ${override}: ${error.message}` : `Invalid --config ${override}`);
+    }
+  }
+  return errors;
+}
+
+export function applyRuntimeFeatureFlagOverrides(
+  configManager: ConfigManager,
+  options: {
+    readonly enableFeatures: readonly string[];
+    readonly disableFeatures: readonly string[];
+  },
+): void {
+  if (options.enableFeatures.length === 0 && options.disableFeatures.length === 0) return;
+  const config = getRuntimeConfig(configManager);
+  const flags = { ...config.featureFlags };
+  for (const feature of options.enableFeatures) {
+    flags[feature] = 'enabled' satisfies PersistedFlagState;
+  }
+  for (const feature of options.disableFeatures) {
+    flags[feature] = 'disabled' satisfies PersistedFlagState;
+  }
+  config.featureFlags = flags;
+}
+
+export function applyRuntimeEndpointFlagOverrides(
+  configManager: ConfigManager,
+  endpoint: RuntimeEndpointId,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const errors: string[] = [];
+
+  if (flags.hostname !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.hostMode, hostModeForHostname(flags.hostname));
+      applyRuntimeConfigValue(configManager, keys.host, flags.hostname);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --hostname ${flags.hostname}: ${error.message}`
+        : `Invalid --hostname ${flags.hostname}`);
+    }
+  }
+
+  if (flags.port !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.port, flags.port);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --port ${flags.port}: ${error.message}`
+        : `Invalid --port ${flags.port}`);
+    }
+  }
+
+  return errors;
+}
+
+export function applyRuntimeCommandEndpointFlagOverrides(
+  configManager: ConfigManager,
+  command: GoodVibesCliCommand,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  if (flags.hostname === undefined && flags.port === undefined) return [];
+  if (command === 'web') return applyRuntimeEndpointFlagOverrides(configManager, 'web', flags);
+  if (command === 'listener') return applyRuntimeEndpointFlagOverrides(configManager, 'httpListener', flags);
+  if (command === 'control-plane' || command === 'pair' || command === 'serve') {
+    return applyRuntimeEndpointFlagOverrides(configManager, 'controlPlane', flags);
+  }
+  return [];
+}

package/src/cli/endpoints.ts

@@ -0,0 +1,63 @@
+import type { ConfigKey, ConfigManager } from '../config/index.ts';
+
+export type RuntimeEndpointId = 'controlPlane' | 'httpListener' | 'web';
+export type RuntimeHostMode = 'local' | 'network' | 'custom';
+
+export const RUNTIME_ENDPOINT_DEFAULT_PORTS: Record<RuntimeEndpointId, number> = {
+  controlPlane: 3421,
+  httpListener: 3422,
+  web: 3423,
+};
+
+export const RUNTIME_ENDPOINT_CONFIG_KEYS: Record<RuntimeEndpointId, {
+  readonly hostMode: ConfigKey;
+  readonly host: ConfigKey;
+  readonly port: ConfigKey;
+}> = {
+  controlPlane: {
+    hostMode: 'controlPlane.hostMode',
+    host: 'controlPlane.host',
+    port: 'controlPlane.port',
+  },
+  httpListener: {
+    hostMode: 'httpListener.hostMode',
+    host: 'httpListener.host',
+    port: 'httpListener.port',
+  },
+  web: {
+    hostMode: 'web.hostMode',
+    host: 'web.host',
+    port: 'web.port',
+  },
+};
+
+export interface RuntimeEndpointBinding {
+  readonly hostMode: string;
+  readonly configuredHost: string;
+  readonly host: string;
+  readonly port: number;
+}
+
+export function hostModeForHostname(hostname: string): RuntimeHostMode {
+  const normalized = hostname.toLowerCase();
+  if (normalized === '0.0.0.0' || normalized === '::') return 'network';
+  if (normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1') return 'local';
+  return 'custom';
+}
+
+export function resolveRuntimeEndpointBinding(
+  config: Pick<ConfigManager, 'get'>,
+  endpoint: RuntimeEndpointId,
+): RuntimeEndpointBinding {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const hostMode = String(config.get(keys.hostMode) ?? 'local');
+  const configuredHost = String(config.get(keys.host) ?? '127.0.0.1');
+  const port = Number(config.get(keys.port) || RUNTIME_ENDPOINT_DEFAULT_PORTS[endpoint]);
+  if (hostMode === 'network') {
+    return { hostMode, configuredHost, host: '0.0.0.0', port };
+  }
+  if (hostMode === 'custom') {
+    return { hostMode, configuredHost, host: configuredHost || '127.0.0.1', port };
+  }
+  return { hostMode, configuredHost, host: '127.0.0.1', port };
+}