@pellux/goodvibes-tui 1.16.1 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.16.1",
+  "version": "1.18.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.9.0",
+    "@pellux/goodvibes-terminal-shell": "1.9.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.1",
-    "@pellux/goodvibes-tui-linux-arm64": "1.16.1",
-    "@pellux/goodvibes-tui-darwin-x64": "1.16.1",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.16.1"
+    "@pellux/goodvibes-tui-linux-x64": "1.18.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.18.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.18.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.18.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/management-commands.ts

@@ -5,12 +5,16 @@ import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, r
 import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
 import { inspectProviderAuth } from '@/runtime/index.ts';
-import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnectionPayload, formatConnectionBlock } from '@pellux/goodvibes-sdk/platform/pairing';
-import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
+import { generateQrMatrix, renderQrToString, PAIRING_HANDOFF_OFFER_KINDS, type PairingHandoffOfferKind } from '@pellux/goodvibes-sdk/platform/pairing';
+import { ensurePublicBaseUrl } from '../core/pairing-origin.ts';
+import { formatPairingOffers, formatPostureCapabilities, pairingPostureNotice } from '../core/pairing-offers.ts';
+import { defaultPairingTokenName } from '../core/pairing-handoff.ts';
+import { stableUrlHostForBindHost } from '../core/stable-host.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './types.ts';
-import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, runNonInteractiveAgent, urlHostForBindHost, withRuntimeServices, yesNo } from './management-utils.ts';
+import type { RuntimeServices } from '../runtime/services.ts';
+import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, readOptionValue, runNonInteractiveAgent, withRuntimeServices, yesNo } from './management-utils.ts';
 
 export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
@@ -368,19 +372,80 @@ export async function renderControlPlaneStatus(runtime: CliCommandRuntime): Prom
   return formatControlPlaneStatus(runtime, await buildControlPlaneStatusResult(runtime));
 }
 
+interface PairingHandoffCreateResult {
+  readonly token: { readonly id: string; readonly name: string; readonly token: string };
+  readonly offers: readonly { readonly kind: PairingHandoffOfferKind }[];
+  readonly fragment: string;
+  readonly deepLink?: string | undefined;
+  /** The honest TLS/capability posture of the origin the QR points at (SDK-computed). */
+  readonly posture?: import('@pellux/goodvibes-sdk/platform/pairing').OriginPosture | undefined;
+}
+
 export async function renderPairing(runtime: CliCommandRuntime): Promise<string> {
-  const daemonHomeDir = join(runtime.homeDirectory, '.goodvibes', 'daemon');
-  const tokenRecord = getOrCreateCompanionToken('tui', { daemonHomeDir });
-  const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'controlPlane');
-  const daemonUrl = `http://${urlHostForBindHost(binding.host)}:${binding.port}`;
-  const info = buildCompanionConnectionInfo({
-    daemonUrl,
-    token: tokenRecord.token,
-    username: 'admin',
+  return await withRuntimeServices(runtime, async (services) => {
+    // Freeze a stable web origin once (never clobbering a user-set value) so the
+    // printed link and the daemon's own handoff origin agree and survive a DHCP
+    // lease change where a stable name exists. The verb re-derives the same origin
+    // and returns its honest posture, so this call is a persistence side effect.
+    ensurePublicBaseUrl(runtime.configManager);
+    const name = readOptionValue(runtime.cli.commandArgs, 'name') ?? defaultPairingTokenName();
+    // Mint through the canonical hand-off verb: it mints a fresh per-device token
+    // and returns the exact `#pair=<token>` deep link the web app consumes. The
+    // daemon filters the requested offer set down to what it can actually satisfy.
+    const result = (await services.gatewayMethods.invoke('pairing.handoff.create', {
+      body: { name, offers: [...PAIRING_HANDOFF_OFFER_KINDS] },
+      context: { principalId: 'admin', principalKind: 'user', admin: true },
+    })) as PairingHandoffCreateResult;
+    const link = result.deepLink ?? result.fragment;
+    const qr = renderQrToString(generateQrMatrix(link));
+    const lines: string[] = [
+      'Scan to pair a device — the QR opens the web app already signed in:',
+      '',
+      `  ${link}`,
+      `  Token name: ${result.token.name}  (rename or revoke later in /settings → security → devices)`,
+    ];
+    if (result.offers.length > 0) {
+      lines.push('', 'Offers carried in this pairing (each declinable in the web app):', ...formatPairingOffers(result.offers.map((o) => o.kind)));
+    }
+    // The labeled browser-capability list and the one honest LAN line both render
+    // from the SDK posture the verb returned — never a locally-authored string.
+    const capabilities = formatPostureCapabilities(result.posture);
+    if (capabilities.length > 0) lines.push('', 'This device will get:', ...capabilities);
+    const notice = pairingPostureNotice(result.posture);
+    if (notice) lines.push('', notice);
+    // Tailscale detection is read-only here (the interactive serve lives in the
+    // pairing modal); when detected with an https MagicDNS URL, name the encrypted
+    // path. Absence stays quiet.
+    lines.push(...(await renderPairingTailscaleLines(services)));
+    lines.push('', qr);
+    return lines.join('\n');
   });
-  const payload = encodeConnectionPayload(info);
-  const qr = renderQrToString(generateQrMatrix(payload));
-  return [formatConnectionBlock(info, payload), '', qr].join('\n');
+}
+
+interface TailscaleGetResult {
+  readonly available: boolean;
+  readonly httpsUrl?: string | undefined;
+  readonly detail: string;
+}
+
+/**
+ * Read-only tailscale detection for the `gv pair` block: when tailscale is
+ * available with a served https MagicDNS URL, name the encrypted path (the
+ * interactive one-action serve lives in the pairing modal). Quiet — an empty
+ * array — when tailscale is absent or the probe fails.
+ */
+async function renderPairingTailscaleLines(services: RuntimeServices): Promise<string[]> {
+  try {
+    const ts = (await services.gatewayMethods.invoke('tailscale.get', {
+      body: {},
+      context: { principalId: 'admin', principalKind: 'user', admin: true },
+    })) as TailscaleGetResult;
+    if (!ts.available) return [];
+    if (ts.httpsUrl) return ['', `Encrypted access (Tailscale): ${ts.httpsUrl}`];
+    return ['', 'Tailscale detected — run it as a serve target for encrypted https access (see the pairing modal).'];
+  } catch {
+    return [];
+  }
 }
 
 export async function renderRemote(runtime: CliCommandRuntime, label: 'remote' | 'bridge'): Promise<string> {
@@ -408,9 +473,11 @@ export function renderWeb(runtime: CliCommandRuntime): string {
   const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'web');
   const publicBaseUrl = String(runtime.configManager.get('web.publicBaseUrl') ?? '');
   const hasEndpointOverride = runtime.cli.flags.hostname !== undefined || runtime.cli.flags.port !== undefined;
+  // Prefer the stable-name resolution over the raw first-non-internal IPv4 so the
+  // printed URL survives a DHCP lease change where a stable name exists.
   const url = !hasEndpointOverride && publicBaseUrl
     ? publicBaseUrl
-    : `http://${urlHostForBindHost(binding.host)}:${binding.port}`;
+    : `http://${stableUrlHostForBindHost(binding.host).host}:${binding.port}`;
   const value = {
     enabled: runtime.configManager.get('web.enabled'),
     ...binding,

package/src/cli/management.ts

@@ -11,8 +11,6 @@ import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, r
 import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
 import { inspectProviderAuth } from '@/runtime/index.ts';
-import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnectionPayload, formatConnectionBlock } from '@pellux/goodvibes-sdk/platform/pairing';
-import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
 import type { CliCommandRuntime, GoodVibesCliParseResult } from './types.ts';
 import { formatProviderAuthRoute, summarizeProviderAuthRoutes } from './provider-auth-routes.ts';
 import { classifyProviderSetup } from './provider-classification.ts';