@pellux/goodvibes-tui 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -104,8 +104,8 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "1.7.1",
-    "@pellux/goodvibes-terminal-shell": "1.7.1",
+    "@pellux/goodvibes-sdk": "1.8.0",
+    "@pellux/goodvibes-terminal-shell": "1.8.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",
@@ -131,10 +131,10 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@pellux/goodvibes-tui-linux-x64": "1.16.0",
-    "@pellux/goodvibes-tui-linux-arm64": "1.16.0",
-    "@pellux/goodvibes-tui-darwin-x64": "1.16.0",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.16.0"
+    "@pellux/goodvibes-tui-linux-x64": "1.17.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.17.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.17.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.17.0"
   },
   "trustedDependencies": [],
   "overrides": {

package/src/cli/completions/generate.ts

@@ -93,8 +93,8 @@ export const GLOBAL_FLAGS: readonly CompletionFlag[] = [
     takesValue: true,
     description: 'Override a config value (key=value)',
   },
-  { name: '--enable', takesValue: true, description: 'Enable a feature flag for this launch' },
-  { name: '--disable', takesValue: true, description: 'Disable a feature flag for this launch' },
+  { name: '--enable', takesValue: true, description: 'Enable a platform feature for this launch (writes its domain setting)' },
+  { name: '--disable', takesValue: true, description: 'Disable a platform feature for this launch (writes its domain setting)' },
   {
     name: '--prompt',
     short: '-p',
@@ -139,6 +139,7 @@ export const GLOBAL_FLAGS: readonly CompletionFlag[] = [
   { name: '--fork', takesValue: false, description: 'Fork session when supported' },
   { name: '--yes', short: '-y', takesValue: false, description: 'Auto-confirm prompts (non-interactive)' },
   { name: '--non-interactive', takesValue: false, description: 'Disable all interactive prompts (implies --yes)' },
+  { name: '--strict', takesValue: false, description: 'doctor: also fail on advisory findings, for CI' },
 ] as const;
 
 // ---------------------------------------------------------------------------
@@ -504,8 +505,8 @@ export function generateZsh(surface: CompletionSurface): string {
   lines.push(`    '--working-dir[Alias for --cd]:dir:_files -/' \\`);
   lines.push(`    '--daemon-home[Override daemon home]:dir:_files -/' \\`);
   lines.push(`    '(-c --config)'{-c,--config}'[Override config value]:key=value:' \\`);
-  lines.push(`    '--enable[Enable feature flag]:feature:' \\`);
-  lines.push(`    '--disable[Disable feature flag]:feature:' \\`);
+  lines.push(`    '--enable[Enable platform feature]:feature:' \\`);
+  lines.push(`    '--disable[Disable platform feature]:feature:' \\`);
   lines.push(`    '(-p --prompt)'{-p,--prompt}'[Run non-interactive prompt]:text:' \\`);
   lines.push(`    '--print[Non-interactive run mode]' \\`);
   lines.push(`    '(-o --output --output-format)'{-o,--output}'[Output format]:format:(text json stream-json)' \\`);

package/src/cli/config-overrides.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
-import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig, PersistedFlagState } from '../config/index.ts';
+import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig } from '../config/index.ts';
 import { CONFIG_SCHEMA, ConfigError } from '../config/index.ts';
+import { featureEnablementWrite, getFeatureSetting } from '../runtime/feature-settings.ts';
 import type { GoodVibesCliCommand, GoodVibesCliFlags } from './types.ts';
 import { RUNTIME_ENDPOINT_CONFIG_KEYS, hostModeForHostname } from './endpoints.ts';
 import type { RuntimeEndpointId } from './endpoints.ts';
@@ -130,6 +131,32 @@ export function applyRuntimeConfigDefault(configManager: ConfigManager, key: Con
   applyRuntimeConfigValue(configManager, key, defaultValue);
 }
 
+/**
+ * Every TUI-side config default applied at startup, in one place. Currently:
+ * show token speed ON (the SDK schema default is false). applyRuntimeConfigDefault
+ * reads the global + project settings files and only applies the default
+ * in-memory when the key is absent from both (e.g. a new install); an explicit
+ * user value is respected. No disk write.
+ */
+export function applyTuiRuntimeConfigDefaults(configManager: ConfigManager): void {
+  applyRuntimeConfigDefault(configManager, 'display.showTokenSpeed', true);
+}
+
+/**
+ * Applies the persisted `behavior.hitlMode` config value to the live mode
+ * manager at startup, ignoring unset or unrecognized values. Extracted from
+ * main() verbatim (a plain move, no behavior change).
+ */
+export function applyConfiguredHitlMode(
+  configManager: ConfigManager,
+  modeManager: { setHITLMode(mode: 'quiet' | 'balanced' | 'operator'): void },
+): void {
+  const hitlMode = configManager.get('behavior.hitlMode');
+  if (hitlMode === 'quiet' || hitlMode === 'balanced' || hitlMode === 'operator') {
+    modeManager.setHITLMode(hitlMode);
+  }
+}
+
 export function applyRuntimeConfigValue(configManager: ConfigManager, key: ConfigKey, value: unknown): void {
   const setting = CONFIG_SCHEMA_BY_KEY.get(key);
   if (!setting) {
@@ -161,23 +188,36 @@ export function applyRuntimeConfigOverrides(
   return errors;
 }
 
+/**
+ * Session-only feature overrides (--enable-feature / --disable-feature).
+ * Each feature is switched through its real domain settings key (e.g.
+ * sandbox.enabled, behavior.compactionStrategy) in the runtime config layer;
+ * features without an off position (constant capabilities on non-boolean
+ * keys) and unknown ids are reported as errors rather than silently ignored.
+ */
 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;
+): readonly string[] {
+  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;
+  const errors: string[] = [];
+  const apply = (feature: string, enabled: boolean, flagName: string): void => {
+    const write = featureEnablementWrite(feature, enabled);
+    if (!write) {
+      errors.push(getFeatureSetting(feature)
+        ? `${flagName} ${feature}: this capability has no ${enabled ? 'on' : 'off'} switch (its domain settings govern it directly).`
+        : `${flagName} ${feature}: unknown feature id.`);
+      return;
+    }
+    setNestedConfigValue(config, write.key, write.value);
+  };
+  for (const feature of options.enableFeatures) apply(feature, true, '--enable-feature');
+  for (const feature of options.disableFeatures) apply(feature, false, '--disable-feature');
+  return errors;
 }
 
 export function applyRuntimeEndpointFlagOverrides(

package/src/cli/doctor.ts

@@ -1,8 +1,7 @@
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { PermissionManager, createPermissionConfigReader } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { PermissionCategory, PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions';
-import { PolicyRuntimeState, createFeatureFlagManager } from '@/runtime/index.ts';
-import type { FlagState } from '@/runtime/index.ts';
+import { PolicyRuntimeState, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { getProviderIdFromModel } from '../config/provider-model.ts';
 import type { CliCommandOutput } from './types.ts';
 import type { GoodVibesCliOutputFormat } from './types.ts';
@@ -76,7 +75,7 @@ function resolveExplainTarget(args: readonly string[]): { tool: string; args: Re
 const LAYER_NAMES: readonly string[] = [
   'Auto-approve override (behavior.autoApprove / --no-worries-just-vibes)',
   'Session permission mode (permissions.mode)',
-  'Runtime policy engine (feature flag: permissions-policy-engine)',
+  'Runtime policy engine (permissions.engine = policy-engine)',
   'Per-tool config rule (permissions.tools.<tool>)',
   'Default read auto-approve (prompt mode)',
   'Session approval cache (remembered [A] decisions)',
@@ -164,7 +163,7 @@ async function explain(options: DoctorSubcommandOptions): Promise<CliCommandOutp
   // Feature flags come from live config so the policy engine layer is walked
   // exactly when the running app would walk it.
   const featureFlags = createFeatureFlagManager();
-  featureFlags.loadFromConfig({ flags: (config.getCategory('featureFlags') as Record<string, FlagState>) ?? {} });
+  featureFlags.loadFromConfig({ flags: deriveFeatureStates(config) });
   const policyEngineOn = featureFlags.isEnabled('permissions-policy-engine');
   const policyRuntimeState = new PolicyRuntimeState();
   const manager = new PermissionManager(
@@ -214,7 +213,7 @@ async function explain(options: DoctorSubcommandOptions): Promise<CliCommandOutp
     'Current settings:',
     `  mode        : ${mode} (${permissionModeLabel(mode)})`,
     `  autoApprove : ${autoApprove ? 'yes (behavior.autoApprove)' : 'no'}`,
-    `  policyEngine: ${policyEngineOn ? 'enabled' : 'disabled'} (feature flag permissions-policy-engine)`,
+    `  policyEngine: ${policyEngineOn ? 'enabled' : 'disabled'} (permissions.engine)`,
     '',
     'Analysis (from the platform analyzer):',
     `  risk        : ${a.riskLevel.toUpperCase()} (${a.classification})`,

package/src/cli/entrypoint.ts

@@ -21,6 +21,7 @@ import {
   renderGoodVibesHelp,
   renderGoodVibesVersion,
   renderOnboardingCliStatus,
+  resolveDoctorExitCode,
 } from './index.ts';
 import { buildCliServicePosture, getGoodVibesPackageRoot, resolveGoodVibesDaemonExecutable } from './service-posture.ts';
 import { runInstallSelfCheck } from '../runtime/install-self-check.ts';
@@ -28,8 +29,7 @@ import { readPersistedWorkspaceTrust } from '../runtime/trust/workspace-trust.ts
 import { WorkspaceRegistrationManager } from '../runtime/trust/workspace-registration.ts';
 import type { CliWorkspaceStatus, CliSandboxStatus, CliRelayStatus } from './status.ts';
 import { detectSandboxAvailability, probeSandboxHost } from '@pellux/goodvibes-sdk/platform/tools/exec/sandbox';
-import { createFeatureFlagManager } from '@/runtime/index.ts';
-import type { FlagState } from '@/runtime/index.ts';
+import { createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { ensureGoodvibesGitignore } from './ensure-goodvibes-gitignore.ts';
 
 type ShellEntrypointOwnership = {
@@ -117,10 +117,14 @@ export async function prepareShellCliRuntime(
     console.error(overrideErrors.join('\n'));
     process.exit(2);
   }
-  applyRuntimeFeatureFlagOverrides(configManager, {
+  const featureOverrideErrors = applyRuntimeFeatureFlagOverrides(configManager, {
     enableFeatures: cli.flags.enableFeatures,
     disableFeatures: cli.flags.disableFeatures,
   });
+  if (featureOverrideErrors.length > 0) {
+    console.error(featureOverrideErrors.join('\n'));
+    process.exit(2);
+  }
 
   if (cli.flags.provider !== undefined || cli.flags.model !== undefined) {
     const currentModel = configManager.get('provider.model');
@@ -181,9 +185,7 @@ export async function prepareShellCliRuntime(
     // Linux, a no-op elsewhere) is what makes "available" trustworthy.
     const sandboxAvailability = detectSandboxAvailability(probeSandboxHost());
     const sandboxFeatureFlags = createFeatureFlagManager();
-    sandboxFeatureFlags.loadFromConfig({
-      flags: (configManager.getCategory('featureFlags') as Record<string, FlagState>) ?? {},
-    });
+    sandboxFeatureFlags.loadFromConfig({ flags: deriveFeatureStates(configManager) });
     const sandboxStatus: CliSandboxStatus = {
       configEnabled: Boolean(configManager.getCategory('sandbox').enabled),
       featureEnabled: sandboxFeatureFlags.isEnabled('exec-sandbox'),
@@ -192,7 +194,7 @@ export async function prepareShellCliRuntime(
       reason: sandboxAvailability.reason,
       networkIsolationGuaranteed: sandboxAvailability.networkIsolationGuaranteed,
     };
-    // Reuses sandboxFeatureFlags (already loaded from the same featureFlags config category)
+    // Reuses sandboxFeatureFlags (already derived from the same domain settings keys)
     // for the relay-connect gate rather than constructing a second FeatureFlagManager.
     const relayCategory = configManager.getCategory('relay');
     const relayStatus: CliRelayStatus = {
@@ -232,7 +234,10 @@ export async function prepareShellCliRuntime(
     console.log(cli.command === 'onboarding'
       ? renderOnboardingCliStatus(statusOptions)
       : renderCliStatus(statusOptions));
-    process.exit(cli.command === 'doctor' && snapshot.findings.length > 0 ? 1 : 0);
+    // Advisory findings are notes on an otherwise-usable install and must
+    // never make a healthy install report failure — only a must-fix finding
+    // exits non-zero; --strict (for CI) flips advisories to failures too.
+    process.exit(cli.command === 'doctor' ? resolveDoctorExitCode(snapshot.findings, cli.flags.strict) : 0);
   }
 
   const cliCommandResult = await handleGoodVibesCliCommand({

package/src/cli/help.ts

@@ -68,8 +68,8 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     '      --working-dir <dir>        Alias for --cd',
     '      --daemon-home <dir>        Override daemon home for daemon-backed commands',
     '  -c, --config <key=value>       Override a config value for this launch',
-    '      --enable <feature>         Enable a feature flag for this launch',
-    '      --disable <feature>        Disable a feature flag for this launch',
+    '      --enable <feature>         Enable a platform feature for this launch',
+    '      --disable <feature>        Disable a platform feature for this launch',
     '  -p, --prompt <text>            Run a non-interactive prompt',
     '      --print                    Alias for non-interactive run mode',
     '  -o, --output <format>          text, json, or stream-json',
@@ -85,6 +85,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     '      --fork [id]                Fork session (current or specific id) when supported',
     '  -y, --yes                      Auto-confirm prompts (non-interactive)',
     '      --non-interactive          Disable all interactive prompts (implies --yes)',
+    '      --strict                   doctor: also fail on advisory findings, for CI',
     '  -h, --help                     Print help',
     '  -v, --version                  Print version',
     '',
@@ -139,9 +140,9 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     examples: ['status', 'status --json'],
   },
   doctor: {
-    usage: ['doctor', 'doctor --json', 'doctor explain <tool|command>', 'doctor routing', 'doctor hooks'],
-    summary: 'Print status plus setup warnings, or explain a platform decision: explain (why a tool/command would be allowed/asked/denied under the current mode), routing (which model/provider serves which role), hooks (registered hooks, their source, and validation status).',
-    examples: ['doctor', 'doctor explain "rm -rf build"', 'doctor explain write ./src/app.ts', 'doctor routing', 'doctor hooks --json'],
+    usage: ['doctor', 'doctor --json', 'doctor --strict', 'doctor explain <tool|command>', 'doctor routing', 'doctor hooks'],
+    summary: 'Print status plus setup warnings, or explain a platform decision: explain (why a tool/command would be allowed/asked/denied under the current mode), routing (which model/provider serves which role), hooks (registered hooks, their source, and validation status). Exits 0 when the install is usable (advisory findings render as notes); non-zero only for a must-fix finding. --strict also fails on advisory findings, for CI.',
+    examples: ['doctor', 'doctor --strict', 'doctor explain "rm -rf build"', 'doctor explain write ./src/app.ts', 'doctor routing', 'doctor hooks --json'],
   },
   providers: {
     usage: ['providers [list]', 'providers current', 'providers inspect <provider>', 'providers use <provider> [modelRegistryKey]'],
@@ -311,7 +312,7 @@ export function renderGoodVibesDaemonHelp(binary = 'goodvibes-daemon'): string {
     '  install-service                Install + enable the daemon as a systemd user service (survives reboots)',
     '  uninstall-service              Disable + remove the daemon systemd user service',
     '  service-status                 Show whether the daemon service is installed / enabled / active',
-    '  migrate-service                Guided takeover of a legacy goodvibes-daemon.service unit; prints a plan',
+    '  migrate-service                Guided migration from an install-script goodvibes-daemon.service unit; prints a plan',
     '                                 unless run with -y/--yes (never auto-migrates)',
     '',
     'Options:',

package/src/cli/launch-auto-update.ts

@@ -0,0 +1,214 @@
+/**
+ * Launch-time self-update — clients land on the newest release at startup so
+ * an installed binary never drifts behind. At TUI launch (before any runtime
+ * bootstrap or terminal mode change) this runs a quick version check and, when
+ * a newer release exists, installs it through the SAME checksum-verified
+ * download/verify/swap path `/update apply` and scripts/install.sh use
+ * (src/input/commands/update-runtime.ts — there is deliberately no second
+ * updater), then asks the caller to restart onto the new binary.
+ *
+ * Honesty rules, in both directions:
+ *   - the check gets a short timeout; when it cannot complete (offline, slow
+ *     network) the CURRENT version starts with exactly one line saying the
+ *     check was skipped — launch is never held hostage by the network.
+ *   - a successful update restarts into the new binary and the restarted
+ *     process prints a receipt naming both versions, so the swap is never
+ *     silent.
+ *   - every swap keeps the outgoing file at `<path>.previous`; rollback is
+ *     one command (`/update rollback`).
+ *
+ * The feature is a real configurable setting (`update.autoUpdateAtLaunch` in
+ * settings.json, read via readUpdateSettings): default ON, off with an
+ * explicit false. Only binary installs self-update — package-manager and
+ * from-source runs are skipped silently because a swap there would fight the
+ * package manager (see detectInstallKind).
+ *
+ * Everything effectful is injectable; tests drive the decision logic with a
+ * stubbed fetch, a stubbed apply, and pinned fixture versions — never the
+ * live build VERSION and never the real network.
+ */
+import { spawnSync } from 'node:child_process';
+import { detectInstallKind, normalizeVersion, type UpdateFetchLike } from '../runtime/update-check.ts';
+import { applyUpdate, checkForUpdate, type ApplyUpdateOptions } from '../input/commands/update-runtime.ts';
+import { readUpdateSettings, type UpdateSettings } from '../config/tui-extension-settings.ts';
+import type { ConfigManager } from '../config/index.ts';
+import { VERSION } from '../version.ts';
+
+/**
+ * Set on the restarted process by restartOntoUpdatedBinary, carrying the
+ * version that performed the update. Its presence means "an update already
+ * happened this launch": the restarted process prints the receipt and skips
+ * its own check, which also makes an update-that-didn't-change-the-version
+ * structurally unable to restart-loop.
+ */
+export const LAUNCH_UPDATED_FROM_ENV = 'GOODVIBES_LAUNCH_UPDATED_FROM';
+
+/** Default budget for the launch-time version check; user-tunable via update.launchCheckTimeoutMs. */
+export const LAUNCH_UPDATE_CHECK_TIMEOUT_MS = 2500;
+
+export type LaunchAutoUpdateOutcome =
+  | {
+      readonly action: 'continue';
+      readonly reason: 'just-updated' | 'disabled' | 'not-swappable-install' | 'already-current' | 'check-skipped' | 'update-failed';
+    }
+  | { readonly action: 'restart'; readonly latestTag: string };
+
+export interface RunLaunchAutoUpdateOptions {
+  readonly fetchImpl: UpdateFetchLike;
+  readonly execPath: string;
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly currentVersion: string;
+  readonly settings: UpdateSettings;
+  readonly env: NodeJS.ProcessEnv;
+  readonly print: (line: string) => void;
+  readonly configManager: { get(key: string): unknown };
+  /** Injectable so tests observe the install step instead of swapping real files. */
+  readonly apply?: (options: ApplyUpdateOptions) => Promise<void>;
+  readonly timeoutMs?: number;
+}
+
+/** Resolves to 'timeout' when `promise` does not settle within `ms`; the timer never keeps the process alive. */
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<'timeout'>((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), ms);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The launch-time decision: receipt-and-continue (restarted process), skip
+ * (disabled / unswappable / current / unreachable), install-and-restart, or
+ * fail-and-continue on the current version. Never throws.
+ */
+export async function runLaunchAutoUpdate(options: RunLaunchAutoUpdateOptions): Promise<LaunchAutoUpdateOutcome> {
+  const updatedFrom = options.env[LAUNCH_UPDATED_FROM_ENV];
+  if (typeof updatedFrom === 'string' && updatedFrom.length > 0) {
+    // Consumed here so sessions spawned from inside this one never inherit it.
+    delete options.env[LAUNCH_UPDATED_FROM_ENV];
+    options.print(`auto-update: updated from v${normalizeVersion(updatedFrom)} to v${normalizeVersion(options.currentVersion)} at launch`);
+    return { action: 'continue', reason: 'just-updated' };
+  }
+
+  if (!(options.settings.autoUpdateAtLaunch ?? true)) {
+    return { action: 'continue', reason: 'disabled' };
+  }
+
+  if (detectInstallKind(options.execPath) !== 'binary') {
+    return { action: 'continue', reason: 'not-swappable-install' };
+  }
+
+  const timeoutMs = options.timeoutMs ?? options.settings.launchCheckTimeoutMs ?? LAUNCH_UPDATE_CHECK_TIMEOUT_MS;
+  let check: Awaited<ReturnType<typeof checkForUpdate>> | 'timeout';
+  try {
+    check = await withTimeout(checkForUpdate(options.fetchImpl, options.currentVersion), timeoutMs);
+  } catch {
+    check = 'timeout';
+  }
+  if (check === 'timeout') {
+    options.print('update check skipped: offline');
+    return { action: 'continue', reason: 'check-skipped' };
+  }
+  if (check.isCurrent) {
+    return { action: 'continue', reason: 'already-current' };
+  }
+
+  try {
+    const apply = options.apply ?? applyUpdate;
+    await apply({
+      fetchImpl: options.fetchImpl,
+      execPath: options.execPath,
+      platform: options.platform,
+      arch: options.arch,
+      currentVersion: options.currentVersion,
+      print: options.print,
+      configManager: options.configManager,
+    });
+    options.print(`auto-update: ${check.latestTag} installed — restarting onto the new version`);
+    return { action: 'restart', latestTag: check.latestTag };
+  } catch (error) {
+    options.print(
+      `auto-update failed: ${error instanceof Error ? error.message : String(error)} — starting the current version v${normalizeVersion(options.currentVersion)}`,
+    );
+    return { action: 'continue', reason: 'update-failed' };
+  }
+}
+
+export interface SelfUpdateAtLaunchParams {
+  readonly configManager: Pick<ConfigManager, 'get' | 'getRaw'>;
+  readonly stdout: { write(chunk: string): unknown };
+}
+
+/**
+ * The complete launch wiring for main(), with real host inputs: run the
+ * decision above; when an update was installed, restart onto the swapped
+ * binary and EXIT THIS PROCESS with the new instance's exit code (this call
+ * never returns in that case); otherwise return the honest lines that were
+ * printed (receipt / skipped check / failed update) so the caller can
+ * re-surface them through the system message router once it exists — the
+ * stdout copies written here are wiped by the TUI's alternate screen.
+ */
+export async function selfUpdateAtLaunch(params: SelfUpdateAtLaunchParams): Promise<readonly string[]> {
+  const lines: string[] = [];
+  const outcome = await runLaunchAutoUpdate({
+    fetchImpl: fetch as UpdateFetchLike,
+    execPath: process.execPath,
+    platform: process.platform,
+    arch: process.arch,
+    currentVersion: VERSION,
+    settings: readUpdateSettings(params.configManager),
+    env: process.env,
+    configManager: params.configManager,
+    print: (line) => {
+      lines.push(line);
+      params.stdout.write(`${line}\n`);
+    },
+  });
+  if (outcome.action === 'restart') {
+    process.exit(
+      restartOntoUpdatedBinary({
+        execPath: process.execPath,
+        argv: process.argv.slice(2),
+        env: process.env,
+        fromVersion: VERSION,
+      }),
+    );
+  }
+  return lines;
+}
+
+export interface RestartOntoUpdatedBinaryOptions {
+  readonly execPath: string;
+  readonly argv: readonly string[];
+  readonly env: NodeJS.ProcessEnv;
+  /** The version that performed the update — the restarted process prints it in its receipt line. */
+  readonly fromVersion: string;
+  /** Injectable so tests observe the restart instead of spawning a process. */
+  readonly spawn?: (execPath: string, argv: readonly string[], env: NodeJS.ProcessEnv) => number | null;
+}
+
+/**
+ * Runs the (just-swapped) binary at execPath with the original CLI arguments
+ * and an inherited terminal, blocking until it exits, and returns its exit
+ * code for the caller to process.exit with. The receipt marker travels in the
+ * child's environment, never on the command line.
+ */
+export function restartOntoUpdatedBinary(options: RestartOntoUpdatedBinaryOptions): number {
+  const spawn =
+    options.spawn ??
+    ((execPath: string, argv: readonly string[], env: NodeJS.ProcessEnv) =>
+      spawnSync(execPath, [...argv], { stdio: 'inherit', env }).status);
+  const status = spawn(options.execPath, options.argv, {
+    ...options.env,
+    [LAUNCH_UPDATED_FROM_ENV]: options.fromVersion,
+  });
+  return status ?? 0;
+}

package/src/cli/parser.ts

@@ -87,6 +87,7 @@ function createDefaultFlags(): GoodVibesCliFlags {
     fork: undefined,
     yes: false,
     nonInteractive: false,
+    strict: false,
   };
 }
 
@@ -260,6 +261,10 @@ export function parseGoodVibesCli(
       flags = withFlag(withFlag(flags, 'nonInteractive', true), 'yes', true);
       continue;
     }
+    if (name === '--strict') {
+      flags = withFlag(flags, 'strict', true);
+      continue;
+    }
 
     if (name === '--provider') {
       const consumed = getValue(argv, index, inlineValue, name, errors);

package/src/cli/status.ts

@@ -502,6 +502,19 @@ export function buildCliDoctorFindings(options: CliStatusOptions): readonly CliD
   return findings;
 }
 
+/**
+ * The doctor command's exit code. Advisory findings (`severity: 'warning'`)
+ * are notes on an otherwise-usable install and must never make a healthy
+ * install report failure — only a must-fix (`severity: 'risk'`) finding
+ * exits non-zero. `strict` (for CI) flips warnings to failures too, so a
+ * pipeline can require a fully clean report instead of just "usable".
+ */
+export function resolveDoctorExitCode(findings: readonly CliDoctorFinding[], strict = false): number {
+  if (findings.some((finding) => finding.severity === 'risk')) return 1;
+  if (strict && findings.length > 0) return 1;
+  return 0;
+}
+
 export function buildCliStatusSnapshot(options: CliStatusOptions): CliStatusSnapshot {
   const config = options.configManager;
   const controlPlaneBinding = resolveRuntimeEndpointBinding(config, 'controlPlane');

package/src/cli/surface-command.ts

@@ -5,7 +5,7 @@ import {
   GOODVIBES_NTFY_REMOTE_TOPIC,
   resolveGoodVibesNtfyTopics,
 } from '@pellux/goodvibes-sdk/platform/integrations';
-import { enableFeatureFlags, getMissingSurfaceFeatureFlags, getServerSurfaceFeatureFlags } from '../runtime/surface-feature-flags.ts';
+import { enableFeatureFlags, getMissingSurfaceFeatureFlags, getServerSurfaceFeatureFlags, surfaceFeatureGateSettingsKeys } from '../runtime/surface-feature-flags.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './types.ts';
@@ -147,7 +147,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
       readinessIssues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
     }
     if (surface.missingFeatureFlags.length > 0) {
-      readinessIssues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.join(', ')}.`);
+      readinessIssues.push(`${surface.label} is enabled but these settings are off: ${surfaceFeatureGateSettingsKeys(surface.missingFeatureFlags).join(', ')}.`);
     }
   }
   const value = {
@@ -185,7 +185,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     `  http-listener: ${yesNo(value.httpListener.enabled)} (${value.httpListener.hostMode} ${value.httpListener.host}:${value.httpListener.port})${includeProbe ? ` reachable=${yesNo(value.httpListener.reachable)}` : ''}`,
     '',
     'External surfaces:',
-    ...value.surfaces.map((surface) => `  ${surface.label.padEnd(16)} enabled=${yesNo(surface.enabled)} ready=${yesNo(surface.ready)}${surface.enabled && surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.enabled && surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
+    ...value.surfaces.map((surface) => `  ${surface.label.padEnd(16)} enabled=${yesNo(surface.enabled)} ready=${yesNo(surface.ready)}${surface.enabled && surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.enabled && surface.missingFeatureFlags.length > 0 ? ` settingsOff=${surfaceFeatureGateSettingsKeys(surface.missingFeatureFlags).join(',')}` : ''}`),
     ...(filteredSurfaces.some((surface) => surface.id === 'ntfy') ? [
       '',
       'ntfy inbound topics:',
@@ -260,7 +260,7 @@ export async function buildListenerTestResult(runtime: CliCommandRuntime): Promi
   if (isNetworkFacing(enabled, binding) && auth.bootstrapCredentialPresent) issues.push('Network-facing listener still has a bootstrap credential file.');
   for (const surface of surfaces) {
     if (surface.missing.length > 0) issues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
-    if (surface.missingFeatureFlags.length > 0) issues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.join(', ')}.`);
+    if (surface.missingFeatureFlags.length > 0) issues.push(`${surface.label} is enabled but these settings are off: ${surfaceFeatureGateSettingsKeys(surface.missingFeatureFlags).join(', ')}.`);
   }
   return { enabled, ...binding, posture, reachable, service, auth, surfaces, issues };
 }
@@ -276,7 +276,7 @@ export function formatListenerTestResult(runtime: CliCommandRuntime, value: List
     `  local auth users: ${value.auth.userStorePresent ? 'present' : 'missing'}`,
     `  bootstrap credential: ${value.auth.bootstrapCredentialPresent ? 'present' : 'missing'}`,
     value.surfaces.length === 0 ? '  enabled webhook surfaces: none' : '  enabled webhook surfaces:',
-    ...value.surfaces.map((surface) => `    ${surface.label}: ready=${yesNo(surface.ready)}${surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
+    ...value.surfaces.map((surface) => `    ${surface.label}: ready=${yesNo(surface.ready)}${surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.missingFeatureFlags.length > 0 ? ` settingsOff=${surfaceFeatureGateSettingsKeys(surface.missingFeatureFlags).join(',')}` : ''}`),
     value.issues.length === 0 ? '  readiness: ready' : '  readiness: needs attention',
     ...value.issues.map((issue) => `    - ${issue}`),
   ].join('\n'));