[v3] wails3 dev remains running after Ctrl+C exits the primary process

[Paulkm2006]

Wails version family

v3

Exact Wails version

v3.0.0-beta.15

Operating System

Multiple / Other

Description

Pressing Ctrl+C after wails3 dev has fully started does not terminate the development session.

The native application exits, but the parent wails3 dev watcher and the background Vite process remain running. The terminal does not return to the shell until SIGINT is sent directly to the wails3 dev process.

This appears to be a process-group/supervision issue rather than an application shutdown deadlock.

To Reproduce

1. Clone the reproduction repository:

   git clone https://github.com/MaimoryLab/codeoff-server.git
   cd codeoff-server
   git checkout 7f1325a48d493673058add6f4b2a1ca75c443854

2. Start the application:

   wails3 dev -config ./build/config.yml

3. Wait for the native application and Vite development server to start.

4. Press Ctrl+C once.

5. Observe that the native application exits, but wails3 dev and Vite remain:

   pgrep -fl 'wails3 dev|vite'
   

6. Send SIGINT directly to the watcher:

   pkill -INT -f '^wails3 dev'
   

7. Observe that the watcher reports a graceful exit and terminates the remaining development processes.

Expected behaviour

Pressing Ctrl+C once should terminate the complete wails3 dev session, including the primary native application and all background development processes, and return control to the shell.

Screenshots

Recording.2026-08-28.at.16-02-52.mp4

Attempted Fixes

• Sending SIGINT directly to the wails3 dev process terminates the complete session successfully:

  pkill -INT -f '^wails3 dev'
  

• Process inspection after Ctrl+C showed:

  wails3 dev: PGID 13050, TPGID 13185
  Vite task:  PGID 13184, TPGID 13185
  

  The foreground process group (13185) had already exited, while the watcher and Vite remained alive.

• Sending kill -INT 13050 directly to the watcher produced graceful exit requested and cleaned up the remaining processes.

Related historical reports were reviewed:

• V2 - watcher keep running after closing app #1232 — v2 watcher remains after the application exits
• wails dev doesn't call OnShutdown #2421 — wails dev does not call shutdown during process replacement
• Terminating a Wails App with Ctrl+C Causes Premature Application Termination #3077 — Ctrl+C prematurely terminates a Wails application
  These reports concern Wails v2 and do not appear to cover the current v3
  watcher implementation.

System Details

Wails v3.0.0-beta.15 › Wails Doctor
                                                                                                                        
# System
        
┌──────────────────────────────┐
| Name          | MacOS        |
| Version       | 26.6.2       |
| ID            | 25G83        |
| Branding      | MacOS 26.6.2 |
| Platform      | darwin       |
| Architecture  | arm64        |
| Apple Silicon | true         |
| CPU           | Apple M2 Pro |
| CPU           | Apple M2 Pro |
| GPU           | 16 cores     |
| Memory        | 16 GB        |
└──────────────────────────────┘
                   
# Build Environment
                   
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
| Wails CLI      | v3.0.0-beta.15                                                                                      |
| Go Version     | go1.27.0                                                                                            |
| -buildmode     | exe                                                                                                 |
| -compiler      | gc                                                                                                  |
| CGO_CFLAGS     |                                                                                                     |
| CGO_CPPFLAGS   |                                                                                                     |
| CGO_CXXFLAGS   |                                                                                                     |
| CGO_ENABLED    | 1                                                                                                   |
| CGO_LDFLAGS    |                                                                                                     |
| DefaultGODEBUG | cryptocustomrand=1,tlssecpmlkem=0,tracebacklabels=0,urlstrictcolons=0,x509sslcertoverrideplatform=0 |
| GOARCH         | arm64                                                                                               |
| GOARM64        | v8.0                                                                                                |
| GOOS           | darwin                                                                                              |
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
              
# Dependencies
              
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
| *Android NDK            | /Users/ppio/Library/Android/sdk/ndk/28.2.13676358                         |
| *Android SDK            | /Users/ppio/Library/Android/sdk                                           |
| *Android platform-tools | Installed                                                                 |
| *Java (Android)         | Not found. Install a JDK (e.g. brew install openjdk@21) or set JAVA_HOME. |
| *NSIS                   | Not Installed. Install with `brew install makensis`.                      |
| *Xcode (iOS)            | Xcode 26.6, Build version 17F113                                          |
| *iOS Device SDK         | 26.5                                                                      |
| *iOS Simulator SDK      | 26.5                                                                      |
| Xcode cli tools         | 2416                                                                      |
| npm                     | 12.0.2                                                                    |
| docker                  | *Docker version 29.7.2, build a7dcaa6fdb (cross-compilation ready)        |
|                                                                                                     |
└────────────────────────────────────── * - Optional Dependency ──────────────────────────────────────┘
         
# Signing
         
┌───────────────────────────────────────────────────────────────────┐
| macOS Signing   | Developer ID Application: steve li (F2VC757B28) |
| Windows Signing | Not configured                                  |
| Linux Signing   | Not configured (GPG)                            |
└───────────────────────────────────────────────────────────────────┘
                     
# Checking for issues
                     
 SUCCESS  No issues found
           
# Diagnosis
           
 SUCCESS  Your system is ready for Wails development!

Need documentation? Run: wails3 docs
 ♥   If Wails is useful to you or your company, please consider sponsoring the project: wails3 sponsor

Additional context

The wails3 binary includes github.com/atterpac/refresh v1.0.0.

During reproduction, the terminal foreground process group belonged to the primary application task rather than the wails3 dev watcher. Ctrl+C therefore terminated the primary task without delivering SIGINT to the watcher.

refresh v1.0.0 does not end the watcher when the primary process exits.
refresh v1.1.3 introduced structured process lifecycle supervision and configurable exit policies, but Wails v3.0.0-beta.15 still uses v1.0.0.

The open PR #5828 upgrades refresh to v1.1.2 for frontend readiness handling, but it does not appear to include the v1.1.3 lifecycle supervision change or configure the primary process with exit_policy: shutdown.

The Unix process-group implementation is shared by macOS and Linux, so Linux may also be affected. I have only reproduced and verified the issue on macOS. The Windows implementation does not create separate process groups and may behave differently.