@pellux/goodvibes-tui 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.17.0",
+  "version": "1.19.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.8.0",
-    "@pellux/goodvibes-terminal-shell": "1.8.0",
+    "@pellux/goodvibes-sdk": "1.10.0",
+    "@pellux/goodvibes-terminal-shell": "1.10.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.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"
+    "@pellux/goodvibes-tui-linux-x64": "1.19.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.19.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.19.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.19.0"
   },
   "trustedDependencies": [],
   "overrides": {

package/src/cli/endpoints.ts

@@ -36,6 +36,30 @@ export interface RuntimeEndpointBinding {
   readonly configuredHost: string;
   readonly host: string;
   readonly port: number;
+  /**
+   * False when the stored hostMode is not one of the SDK's recognized modes
+   * ('local' | 'network' | 'custom'). The SDK's resolveHostBinding is a switch
+   * with NO default case: an unrecognized mode yields an undefined binding and
+   * the daemon throws in its constructor before ever binding. Displays must
+   * therefore never present the host/port below as a definite binding when
+   * this is false — the fallback values exist only so display code has
+   * something structured to show alongside the warning.
+   */
+  readonly recognized: boolean;
+}
+
+/**
+ * THE one display seam for endpoint bindings: every surface that renders a
+ * binding as text goes through this, so no surface can present the resolver's
+ * loopback fallback as a definite bind for a hostMode the SDK cannot handle
+ * (its bind resolver has no default case — the daemon throws before binding).
+ * The recognized case renders the familiar `<mode> <host>:<port>`.
+ */
+export function formatRuntimeEndpointBinding(binding: RuntimeEndpointBinding): string {
+  if (binding.recognized) {
+    return `${binding.hostMode} ${binding.host}:${binding.port}`;
+  }
+  return `'${binding.hostMode}' — not a recognized host mode (expected local|network|custom); the daemon cannot bind this endpoint until it is corrected`;
 }
 
 export function hostModeForHostname(hostname: string): RuntimeHostMode {
@@ -52,12 +76,34 @@ export function resolveRuntimeEndpointBinding(
   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]);
+  // Port coercion is anchored PER ENDPOINT to what the SDK actually does with
+  // the stored value, so a display never disagrees with the machinery:
+  //   - controlPlane / httpListener bind via resolveHostBinding, which is fed
+  //     `Number(raw ?? default)` and applies `customPort || DEFAULT` — a
+  //     stored 0 or non-numeric value collapses to the endpoint default.
+  //   - web has NO resolveHostBinding consumer in the SDK at all; its closest
+  //     machinery (resolveWebPort, which drives tailscale-serve, plus the
+  //     surface registry/announcements) uses bare `Number(raw ?? default)`
+  //     with no || collapse — 0 stays 0 and a non-numeric value stays NaN.
+  //     Collapsing here would make the display assert a port the tailscale/
+  //     announcement machinery is not actually using. (The SDK's web-port
+  //     handling is inconsistent-by-absence — a proper resolveHostBinding-style
+  //     web resolver is an SDK-side fix; until then this mirrors resolveWebPort.)
+  const rawPort = Number(config.get(keys.port) ?? RUNTIME_ENDPOINT_DEFAULT_PORTS[endpoint]);
+  const port = endpoint === 'web' ? rawPort : (rawPort || RUNTIME_ENDPOINT_DEFAULT_PORTS[endpoint]);
   if (hostMode === 'network') {
-    return { hostMode, configuredHost, host: '0.0.0.0', port };
+    return { hostMode, configuredHost, host: '0.0.0.0', port, recognized: true };
   }
   if (hostMode === 'custom') {
-    return { hostMode, configuredHost, host: configuredHost || '127.0.0.1', port };
+    return { hostMode, configuredHost, host: configuredHost || '127.0.0.1', port, recognized: true };
+  }
+  if (hostMode === 'local') {
+    return { hostMode, configuredHost, host: '127.0.0.1', port, recognized: true };
   }
-  return { hostMode, configuredHost, host: '127.0.0.1', port };
+  // Unrecognized hostMode ('LAN', 'Network', '', a trimmed variant, …): the
+  // SDK bind path has NO default case for this — resolveHostBinding returns
+  // undefined and the daemon throws before binding. There IS no real binding
+  // to display; recognized:false tells callers to warn instead of asserting
+  // the loopback fallback below as fact.
+  return { hostMode, configuredHost, host: '127.0.0.1', port, recognized: false };
 }

package/src/cli/help.ts

@@ -6,8 +6,13 @@ import { VERSION } from '../version.ts';
 function readJsonVersion(path: string): string | null {
   try {
     if (!existsSync(path)) return null;
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown };
-    return typeof parsed.version === 'string' ? parsed.version : null;
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { name?: unknown; version?: unknown };
+    // Only trust OUR package.json — a compiled single-file binary can resolve
+    // this path to a different package.json (a bundled dependency's) that
+    // reports a placeholder like "0.0.0". Fall through to the baked VERSION in
+    // that case rather than rendering a stray version in `--version`/banners.
+    if (parsed.name !== '@pellux/goodvibes-tui') return null;
+    return typeof parsed.version === 'string' && parsed.version.length > 0 ? parsed.version : null;
   } catch {
     return null;
   }
@@ -23,6 +28,28 @@ export function renderGoodVibesVersion(binary = 'goodvibes'): string {
   return `${binary} ${getPackageVersion()}`;
 }
 
+/**
+ * Honest one-line startup identity for the daemon binary, emitted right as it
+ * begins serving — including on a bare (no-arg) systemd launch. It states the
+ * RESOLVED version (never a placeholder), the home/host/port it actually bound,
+ * and points at the real service-setup command. This replaces the field
+ * behavior where a bare launch showed a wrong "v0.0.0" banner and gave an
+ * operator nothing to act on. `version` is passed in (never read from the live
+ * build here) so callers/tests can pin a sentinel and never compare the live
+ * VERSION.
+ */
+export function renderDaemonStartupBanner(
+  version: string,
+  binding: { readonly homeDir: string; readonly host: string; readonly port: number },
+  binary = 'goodvibes-daemon',
+): string {
+  return (
+    `${binary} ${version} starting — ` +
+    `home=${binding.homeDir} host=${binding.host} port=${binding.port} ` +
+    `(manage as a service: ${binary} install-service)`
+  );
+}
+
 export function renderGoodVibesHelp(binary = 'goodvibes'): string {
   return [
     `Usage: ${binary} [OPTIONS] [PROMPT]`,

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 { resolveRuntimeEndpointBinding } from './endpoints.ts';
+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 { formatRuntimeEndpointBinding, 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) => {
@@ -309,8 +313,10 @@ export interface ControlPlaneStatusResult {
   readonly configuredHost: string;
   readonly host: string;
   readonly port: number;
+  readonly recognized: boolean;
   readonly posture: ReturnType<typeof classifyBindPosture>;
-  readonly reachable: boolean;
+  /** undefined = NOT PROBED (unrecognized host mode) — a tri-state, never coerced to false. */
+  readonly reachable: boolean | undefined;
   readonly auth: ReturnType<typeof readAuthPaths>;
   readonly service: {
     readonly enabled: unknown;
@@ -323,7 +329,13 @@ export interface ControlPlaneStatusResult {
 export async function buildControlPlaneStatusResult(runtime: CliCommandRuntime): Promise<ControlPlaneStatusResult> {
   const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'controlPlane');
   const enabled = runtime.configManager.get('controlPlane.enabled');
-  const reachable = enabled === true ? await probeTcp(binding.host, binding.port) : false;
+  // Never TCP-probe the fallback endpoint of an unrecognized hostMode — a
+  // probe asserts a binding that does not exist. Not-probed is its own state
+  // (undefined), NEVER coerced to a definite false: a daemon launched with
+  // flag overrides can be serving healthily regardless of the stored mode.
+  const reachable = enabled === true
+    ? (binding.recognized ? await probeTcp(binding.host, binding.port) : undefined)
+    : false;
   const auth = readAuthPaths(runtime);
   const service = {
     enabled: runtime.configManager.get('service.enabled'),
@@ -331,7 +343,8 @@ export async function buildControlPlaneStatusResult(runtime: CliCommandRuntime):
     restartOnFailure: runtime.configManager.get('service.restartOnFailure'),
   };
   const issues: string[] = [];
-  if (enabled === true && !reachable) issues.push(`Control plane is enabled but not reachable on ${binding.host}:${binding.port}.`);
+  if (!binding.recognized) issues.push(`controlPlane.hostMode '${binding.hostMode}' is not a recognized mode (local|network|custom) — the daemon cannot bind until it is corrected.`);
+  if (enabled === true && binding.recognized && !reachable) issues.push(`Control plane is enabled but not reachable on ${binding.host}:${binding.port}.`);
   if (enabled === true && service.enabled !== true) issues.push('Control plane is enabled but service mode is off.');
   if (enabled === true && service.autostart !== true) issues.push('Control plane is enabled but service autostart is off.');
   if (enabled === true && service.restartOnFailure !== true) issues.push('Control plane is enabled but service restart-on-failure is off.');
@@ -352,9 +365,9 @@ export function formatControlPlaneStatus(runtime: CliCommandRuntime, value: Cont
   return formatJsonOrText(runtime.cli)(value, [
     'GoodVibes control-plane status',
     `  enabled: ${yesNo(value.enabled)}`,
-    `  bind: ${value.hostMode} ${value.host}:${value.port}`,
-    `  bind posture: ${value.posture.label}`,
-    `  reachable: ${yesNo(value.reachable)}`,
+    `  bind: ${formatRuntimeEndpointBinding(value)}`,
+    `  bind posture: ${value.recognized ? value.posture.label : 'unknown (unrecognized host mode)'}`,
+    `  reachable: ${value.reachable === undefined ? 'not probed (unrecognized host mode)' : yesNo(value.reachable)}`,
     `  service: enabled=${yesNo(value.service.enabled)} autostart=${yesNo(value.service.autostart)} restartOnFailure=${yesNo(value.service.restartOnFailure)}`,
     `  local auth users: ${value.auth.userStorePresent ? 'present' : 'missing'}`,
     `  bootstrap credential: ${value.auth.bootstrapCredentialPresent ? 'present' : 'missing'}`,
@@ -368,19 +381,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 +482,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,
@@ -419,7 +495,7 @@ export function renderWeb(runtime: CliCommandRuntime): string {
   return formatJsonOrText(runtime.cli)(value, [
     'GoodVibes web',
     `  enabled: ${yesNo(value.enabled)}`,
-    `  bind: ${value.hostMode} ${value.host}:${value.port}`,
+    `  bind: ${formatRuntimeEndpointBinding(value)}`,
     `  url: ${value.url}`,
     ...(runtime.cli.flags.open ? [`  open: ${openBrowser(value.url)}`] : []),
   ].join('\n'));

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';

package/src/cli/service-posture.ts

@@ -7,7 +7,7 @@ import { PlatformServiceManager } from '@pellux/goodvibes-sdk/platform/daemon';
 import type { ManagedServiceStatus } from '@pellux/goodvibes-sdk/platform/daemon';
 import { resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConfigManager } from '../config/index.ts';
-import { resolveRuntimeEndpointBinding } from './endpoints.ts';
+import { formatRuntimeEndpointBinding, resolveRuntimeEndpointBinding } from './endpoints.ts';
 import type { RuntimeEndpointBinding, RuntimeEndpointId } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import { redactText } from './redaction.ts';
@@ -395,7 +395,9 @@ export async function buildCliServicePosture(
       binding,
       bindPosture: classifyBindPosture(binding),
       networkFacing: isNetworkFacing(enabled, binding),
-      ...(options.probe && enabled ? { reachable: await probeTcp(binding.host, binding.port) } : {}),
+      // Never TCP-probe the fallback endpoint of an unrecognized hostMode —
+      // a probe asserts a binding that does not exist.
+      ...(options.probe && enabled && binding.recognized ? { reachable: await probeTcp(binding.host, binding.port) } : {}),
     };
   }));
 
@@ -485,7 +487,7 @@ export function formatCliServicePosture(posture: CliServicePosture, json = false
     '',
     'Endpoints:',
     ...posture.endpoints.map((endpoint) =>
-      `  ${endpoint.label}: enabled=${yesNo(endpoint.enabled)} ${endpoint.binding.hostMode} ${endpoint.binding.host}:${endpoint.binding.port} posture=${endpoint.bindPosture.label}${endpoint.reachable === undefined ? '' : ` reachable=${yesNo(endpoint.reachable)}`}`,
+      `  ${endpoint.label}: enabled=${yesNo(endpoint.enabled)} ${formatRuntimeEndpointBinding(endpoint.binding)} posture=${endpoint.binding.recognized ? endpoint.bindPosture.label : 'unknown'}${endpoint.reachable === undefined ? '' : ` reachable=${yesNo(endpoint.reachable)}`}`,
     ),
     '',
     posture.issues.length === 0 ? 'Readiness: ready' : 'Readiness: needs attention',

package/src/cli/status.ts

@@ -1,8 +1,8 @@
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
 import type { OnboardingCheckMarkersState } from '../runtime/onboarding/index.ts';
-import { resolveRuntimeEndpointBinding } from './endpoints.ts';
-import type { RuntimeEndpointId } from './endpoints.ts';
+import { formatRuntimeEndpointBinding, resolveRuntimeEndpointBinding } from './endpoints.ts';
+import type { RuntimeEndpointBinding, RuntimeEndpointId } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { GoodVibesCliOutputFormat } from './types.ts';
 import type { CliServicePosture } from './service-posture.ts';
@@ -165,8 +165,8 @@ function secretPolicyLabel(policy: unknown): string {
   return String(policy ?? 'unknown');
 }
 
-function bindLine(label: string, enabled: unknown, binding: { readonly hostMode: string; readonly host: string; readonly port: number }): string {
-  return `  ${label}: ${yesNo(enabled)} (${binding.hostMode} ${binding.host}:${binding.port})`;
+function bindLine(label: string, enabled: unknown, binding: RuntimeEndpointBinding): string {
+  return `  ${label}: ${yesNo(enabled)} (${formatRuntimeEndpointBinding(binding)})`;
 }
 
 /** Describe registration coverage for the Workspace status section. */
@@ -300,8 +300,8 @@ export function buildCliExposureReport(options: CliStatusOptions): readonly CliE
       id: surface.id,
       label: surface.label,
       enabled,
-      bind: `${binding.hostMode} ${binding.host}:${binding.port}`,
-      reach: classifyBindPosture(binding).label,
+      bind: formatRuntimeEndpointBinding(binding),
+      reach: binding.recognized ? classifyBindPosture(binding).label : 'Unknown (unrecognized host mode)',
       networkFacing,
       authMode: surfaceAuthMode(networkFacing, options.auth),
       originAllowlist: surfaceOriginAllowlist(surface.id, config),
@@ -333,6 +333,27 @@ export function buildCliDoctorFindings(options: CliStatusOptions): readonly CliD
 
   const findings: CliDoctorFinding[] = [];
 
+  // An unrecognized hostMode has NO binding the SDK can produce (its bind
+  // resolver has no default case — the daemon throws before binding), so it
+  // is surfaced as a doctor finding on every endpoint that carries one,
+  // instead of the fallback loopback binding being presented as fact.
+  for (const [endpointId, endpointLabel, endpointBinding] of [
+    ['controlPlane', 'control plane', controlPlaneBinding],
+    ['httpListener', 'HTTP listener', httpListenerBinding],
+    ['web', 'web surface', webBinding],
+  ] as const) {
+    if (endpointBinding.recognized) continue;
+    findings.push({
+      id: `unrecognized-host-mode-${endpointId}`,
+      area: 'service',
+      severity: 'warning',
+      summary: `${endpointLabel} hostMode '${endpointBinding.hostMode}' is not a recognized mode.`,
+      cause: `${endpointId}.hostMode is set to '${endpointBinding.hostMode}', but only local|network|custom are recognized.`,
+      impact: 'The daemon cannot resolve a binding for this endpoint and will fail to start it; displays cannot show a real bind address.',
+      action: `Set ${endpointId}.hostMode to local, network, or custom.`,
+    });
+  }
+
   if (serverBackedEnabled && !serviceEnabled) {
     findings.push({
       id: 'service-disabled-for-server-surfaces',

package/src/cli/surface-command.ts

@@ -6,7 +6,7 @@ import {
   resolveGoodVibesNtfyTopics,
 } from '@pellux/goodvibes-sdk/platform/integrations';
 import { enableFeatureFlags, getMissingSurfaceFeatureFlags, getServerSurfaceFeatureFlags, surfaceFeatureGateSettingsKeys } from '../runtime/surface-feature-flags.ts';
-import { resolveRuntimeEndpointBinding } from './endpoints.ts';
+import { formatRuntimeEndpointBinding, resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './types.ts';
 import {
@@ -103,9 +103,9 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
   const shouldProbeListener = includeProbe && (!target || targetExternalSurface);
   const [controlPlaneReachable, webReachable, listenerReachable] = includeProbe
     ? await Promise.all([
-      shouldProbeControlPlane ? probeTcp(controlPlane.host, controlPlane.port) : Promise.resolve(undefined),
-      shouldProbeWeb ? probeTcp(web.host, web.port) : Promise.resolve(undefined),
-      shouldProbeListener ? probeTcp(httpListener.host, httpListener.port) : Promise.resolve(undefined),
+      shouldProbeControlPlane && controlPlane.recognized ? probeTcp(controlPlane.host, controlPlane.port) : Promise.resolve(undefined),
+      shouldProbeWeb && web.recognized ? probeTcp(web.host, web.port) : Promise.resolve(undefined),
+      shouldProbeListener && httpListener.recognized ? probeTcp(httpListener.host, httpListener.port) : Promise.resolve(undefined),
     ])
     : [undefined, undefined, undefined];
   const externalSurfaces = SURFACE_CONFIGS.map(([id, label, requiredKeys]) => {
@@ -129,13 +129,18 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     remoteTopic: String(config.get('surfaces.ntfy.remoteTopic' as ConfigKey) || GOODVIBES_NTFY_REMOTE_TOPIC),
   });
   const readinessIssues: string[] = [];
-  if (shouldProbeControlPlane && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
+  for (const [endpointLabel, endpointBinding] of [['controlPlane', controlPlane], ['web', web], ['httpListener', httpListener]] as const) {
+    if (!endpointBinding.recognized) {
+      readinessIssues.push(`${endpointLabel}.hostMode '${endpointBinding.hostMode}' is not a recognized mode (local|network|custom) — the daemon cannot bind this endpoint until it is corrected.`);
+    }
+  }
+  if (shouldProbeControlPlane && controlPlane.recognized && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
     readinessIssues.push(`Control plane is enabled but not reachable on ${controlPlane.host}:${controlPlane.port}.`);
   }
-  if (shouldProbeWeb && config.get('web.enabled') === true && !webReachable) {
+  if (shouldProbeWeb && web.recognized && config.get('web.enabled') === true && !webReachable) {
     readinessIssues.push(`Web surface is enabled but not reachable on ${web.host}:${web.port}.`);
   }
-  if (shouldProbeListener && config.get('danger.httpListener') === true && !listenerReachable) {
+  if (shouldProbeListener && httpListener.recognized && config.get('danger.httpListener') === true && !listenerReachable) {
     readinessIssues.push(`HTTP listener is enabled but not reachable on ${httpListener.host}:${httpListener.port}.`);
   }
   for (const surface of filteredSurfaces) {
@@ -157,6 +162,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
       configuredHost: controlPlane.configuredHost,
       host: controlPlane.host,
       port: controlPlane.port,
+      recognized: controlPlane.recognized,
       reachable: controlPlaneReachable,
     },
     web: {
@@ -165,6 +171,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
       configuredHost: web.configuredHost,
       host: web.host,
       port: web.port,
+      recognized: web.recognized,
       reachable: webReachable,
     },
     httpListener: {
@@ -173,6 +180,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
       configuredHost: httpListener.configuredHost,
       host: httpListener.host,
       port: httpListener.port,
+      recognized: httpListener.recognized,
       reachable: listenerReachable,
     },
     surfaces: filteredSurfaces,
@@ -180,9 +188,9 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
   };
   const output = formatJsonOrText(runtime.cli)(value, [
     'GoodVibes surfaces',
-    `  control-plane: ${yesNo(value.controlPlane.enabled)} (${value.controlPlane.hostMode} ${value.controlPlane.host}:${value.controlPlane.port})${includeProbe ? ` reachable=${yesNo(value.controlPlane.reachable)}` : ''}`,
-    `  web: ${yesNo(value.web.enabled)} (${value.web.hostMode} ${value.web.host}:${value.web.port})${includeProbe ? ` reachable=${yesNo(value.web.reachable)}` : ''}`,
-    `  http-listener: ${yesNo(value.httpListener.enabled)} (${value.httpListener.hostMode} ${value.httpListener.host}:${value.httpListener.port})${includeProbe ? ` reachable=${yesNo(value.httpListener.reachable)}` : ''}`,
+    `  control-plane: ${yesNo(value.controlPlane.enabled)} (${formatRuntimeEndpointBinding(value.controlPlane)})${includeProbe && value.controlPlane.reachable !== undefined ? ` reachable=${yesNo(value.controlPlane.reachable)}` : ''}`,
+    `  web: ${yesNo(value.web.enabled)} (${formatRuntimeEndpointBinding(value.web)})${includeProbe && value.web.reachable !== undefined ? ` reachable=${yesNo(value.web.reachable)}` : ''}`,
+    `  http-listener: ${yesNo(value.httpListener.enabled)} (${formatRuntimeEndpointBinding(value.httpListener)})${includeProbe && value.httpListener.reachable !== undefined ? ` 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 ? ` settingsOff=${surfaceFeatureGateSettingsKeys(surface.missingFeatureFlags).join(',')}` : ''}`),
@@ -208,8 +216,10 @@ export interface ListenerTestResult {
   readonly configuredHost: string;
   readonly host: string;
   readonly port: number;
+  readonly recognized: boolean;
   readonly posture: ReturnType<typeof classifyBindPosture>;
-  readonly reachable: boolean;
+  /** undefined = NOT PROBED (unrecognized host mode) — a tri-state, never coerced to false. */
+  readonly reachable: boolean | undefined;
   readonly service: {
     readonly enabled: unknown;
     readonly autostart: unknown;
@@ -231,7 +241,10 @@ export async function buildListenerTestResult(runtime: CliCommandRuntime): Promi
   const enabled = runtime.configManager.get('danger.httpListener');
   const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'httpListener');
   const posture = classifyBindPosture(binding);
-  const reachable = enabled === true ? await probeTcp(binding.host, binding.port) : false;
+  // Not-probed (unrecognized host mode) stays undefined — never a definite false.
+  const reachable = enabled === true
+    ? (binding.recognized ? await probeTcp(binding.host, binding.port) : undefined)
+    : false;
   const auth = readAuthPaths(runtime);
   const service = {
     enabled: runtime.configManager.get('service.enabled'),
@@ -252,6 +265,7 @@ export async function buildListenerTestResult(runtime: CliCommandRuntime): Promi
     };
   }).filter((surface) => surface.enabled === true);
   const issues: string[] = [];
+  if (!binding.recognized) issues.push(`httpListener.hostMode '${binding.hostMode}' is not a recognized mode (local|network|custom) — the daemon cannot bind until it is corrected.`);
   if (enabled !== true) issues.push('HTTP listener is disabled.');
   if (enabled === true && service.enabled !== true) issues.push('HTTP listener is enabled but service mode is off.');
   if (enabled === true && service.autostart !== true) issues.push('HTTP listener is enabled but service autostart is off.');
@@ -269,9 +283,9 @@ export function formatListenerTestResult(runtime: CliCommandRuntime, value: List
   return formatJsonOrText(runtime.cli)(value, [
     'GoodVibes listener test',
     `  enabled: ${yesNo(value.enabled)}`,
-    `  endpoint: ${value.hostMode} ${value.host}:${value.port}`,
-    `  bind posture: ${value.posture.label}`,
-    `  reachable: ${yesNo(value.reachable)}`,
+    `  endpoint: ${formatRuntimeEndpointBinding(value)}`,
+    `  bind posture: ${value.recognized ? value.posture.label : 'unknown (unrecognized host mode)'}`,
+    `  reachable: ${value.reachable === undefined ? 'not probed (unrecognized host mode)' : yesNo(value.reachable)}`,
     `  service: enabled=${yesNo(value.service.enabled)} autostart=${yesNo(value.service.autostart)} restartOnFailure=${yesNo(value.service.restartOnFailure)}`,
     `  local auth users: ${value.auth.userStorePresent ? 'present' : 'missing'}`,
     `  bootstrap credential: ${value.auth.bootstrapCredentialPresent ? 'present' : 'missing'}`,

package/src/core/consolidation-receipt.ts

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// consolidation-receipt.ts — the one-line notice for an idle-time memory
+// consolidation run.
+//
+// The SDK's MemoryConsolidationScheduler runs at idle and produces a
+// MemoryConsolidationRunReceipt (merged / archived / decayed / proposed). This
+// formats it into the same one-line shape every other attach-time receipt
+// uses, so a run that changed something surfaces on the next attach like a
+// crash/update/migration receipt. A pure no-op run yields null — no noise.
+//
+// A run that PROPOSED something (a contradiction or cross-scope-duplicate
+// awaiting human judgment — never auto-applied) names where to actually look:
+// the Memory modal's Proposals tab (`/memory`, then the Proposals tab —
+// memory-modal.ts's proposalsTab()), which lists each proposal's kind,
+// reason, and affected record ids and jumps to them in the Review Queue.
+// Without this pointer the receipt line was the only trace a proposal ever
+// existed — a count with nowhere to go.
+// ---------------------------------------------------------------------------
+
+import type { MemoryConsolidationRunReceipt } from '@pellux/goodvibes-sdk/platform/state';
+
+/**
+ * A one-line receipt for a consolidation run that changed something, or null
+ * when the run merged/archived/decayed/proposed nothing (a quiet idle pass —
+ * no notice, matching the check-in "stayed quiet" discipline).
+ */
+export function formatConsolidationReceipt(receipt: MemoryConsolidationRunReceipt): string | null {
+  const merged = receipt.merged.length;
+  const archived = receipt.archived.length;
+  const decayed = receipt.decayed.length;
+  const proposed = receipt.proposed.length;
+  if (merged + archived + decayed + proposed === 0) return null;
+  const parts: string[] = [];
+  if (merged) parts.push(`${merged} merged`);
+  if (archived) parts.push(`${archived} archived`);
+  if (decayed) parts.push(`${decayed} decayed`);
+  if (proposed) parts.push(`${proposed} proposed`);
+  const base = `Memory consolidation: ${parts.join(', ')} (scanned ${receipt.scanned}).`;
+  if (proposed === 0) return base;
+  return `${base} Review the ${proposed} proposed change${proposed === 1 ? '' : 's'} with /memory (Proposals tab).`;
+}