fix(dev): stop watcher when primary process exits

[Paulkm2006]

Description

Fix wails3 dev remaining alive after Ctrl+C terminates the primary application but does not deliver SIGINT to the watcher process group.

This change upgrades github.com/atterpac/refresh from v1.0.0 to v1.1.3 and defaults primary development processes to its shutdown exit policy. Explicit user-configured exit policies are preserved. It also removes the redundant Wails signal wait after the refresh supervisor returns, so the watcher exits together with its managed background processes.

When the primary process receives SIGINT directly, refresh reports the resulting process exit as an error. Wails now identifies that exit using structured platform process state and reports it as the same graceful interrupt used when the watcher receives SIGINT itself. Other signals and non-zero exits remain errors. Unix SIGINT and Windows STATUS_CONTROL_C_EXIT are handled separately.

Newly generated project configurations include exit_policy: shutdown. Existing configurations receive the same default at runtime, so no migration is required.

Fixes #6048

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• WEP (proposal only; no implementation)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• Windows
• macOS
• Linux

Recording.2026-08-28.at.17-10-04.mp4

Runtime reproduction was performed on macOS using the repository and revision from #6048:

git clone https://github.com/Paulkm2006/wails.git /tmp/wails-pr-6048
cd /tmp/wails-pr-6048
git checkout codex/fix-dev-ctrl-c
cd v3
GOTOOLCHAIN=go1.25.0 go build -o /tmp/wails3 ./cmd/wails3

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

PATH="/tmp:$PATH" /tmp/wails3 dev -config ./build/config.yml -port 9258

After the native application and Vite started, pressing Ctrl+C once:

• printed WRN graceful exit requested signal=interrupt;
• returned control to the shell without an error;
• stopped the watcher, native application, and Vite process; and
• released port 9258.

Additional verification:

GOTOOLCHAIN=go1.25.0 go test ./...
GOTOOLCHAIN=go1.25.0 go vet ./internal/commands
staticcheck -checks=inherit,-ST1005,-U1000,-S1017 ./internal/commands
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 GOTOOLCHAIN=go1.25.0 go test -c -o /tmp/wails-commands.test.exe ./internal/commands

The Windows command package and platform-specific test compile successfully, but the runtime behavior has not been tested on Windows. Linux has not been tested.

Test Configuration

Wails v3.0.0-dev › 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-dev |
| Go Version   | go1.25.0   |
| -buildmode   | exe        |
| -compiler    | gc         |
| CGO_CFLAGS   |            |
| CGO_CPPFLAGS |            |
| CGO_CXXFLAGS |            |
| CGO_ENABLED  | 1          |
| CGO_LDFLAGS  |            |
| 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!

Checklist:

• (v2 only) I have updated website/src/pages/changelog.mdx with details of this PR (not applicable: this is a v3 change)
• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (not applicable: no public API or documented configuration changes)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• Bug Fixes
  • wails3 dev and its background processes now shut down automatically when the main application exits.
  • Interrupt-based exits are handled as graceful shutdowns instead of being reported as errors.
• Documentation
  • Added a changelog entry documenting the improved shutdown behavior.
• Tests
  • Added coverage for shutdown policies and interrupt handling across supported platforms.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f48792fd-17e5-47d3-a3c9-6eb574b485b3

📥 Commits

Reviewing files that changed from the base of the PR and between f2260d1 and 8cd4e4b.

⛔ Files ignored due to path filters (1)

• v3/go.sum is excluded by !**/*.sum

📒 Files selected for processing (10)

• v3/UNRELEASED_CHANGELOG.md
• v3/go.mod
• v3/internal/commands/build_assets/config.yml
• v3/internal/commands/watcher.go
• v3/internal/commands/watcher_interrupt_other.go
• v3/internal/commands/watcher_interrupt_unix.go
• v3/internal/commands/watcher_interrupt_unix_test.go
• v3/internal/commands/watcher_interrupt_windows.go
• v3/internal/commands/watcher_interrupt_windows_test.go
• v3/internal/commands/watcher_test.go

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

Walkthrough

Changes

Watcher shutdown supervision

Layer / File(s)	Summary
Exit policy setup v3/go.mod, v3/internal/commands/build_assets/config.yml	The refresh dependency updates to v1.1.3. The primary task uses exit_policy: shutdown; the other entry remains unchanged.
Watcher orchestration v3/internal/commands/watcher.go, v3/internal/commands/watcher_test.go	The watcher applies default shutdown policies, starts the engine directly, logs interrupt exits as graceful shutdowns, and preserves other errors. Tests cover policy selection.
Platform interrupt handling v3/internal/commands/watcher_interrupt_*.go, v3/internal/commands/watcher_interrupt_*_test.go, v3/UNRELEASED_CHANGELOG.md	Platform-specific interrupt detection and tests cover Unix, Windows, and fallback behavior. The changelog records development-session shutdown.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 8cd4e

The change improves Ctrl+C cleanup for standard development configurations, but an accepted list-form configuration can still leave the watcher or background processes running after the primary process exits. The PR is mergeable with explicit owner awareness and follow-up to apply the shutdown default consistently across both configuration forms.

Suggested reviewers: leaanthony

Sequence Diagram(s)

sequenceDiagram
  participant Watcher as wails3 dev watcher
  participant Refresh as refresh engine
  participant Primary as primary process
  participant Background as background processes
  Watcher->>Primary: apply shutdown exit policy
  Watcher->>Refresh: start engine
  Primary-->>Refresh: report interrupt exit
  Refresh->>Background: stop background processes
  Refresh-->>Watcher: return interrupt error
  Watcher->>Watcher: log graceful shutdown and return nil

Loading

Poem

A rabbit tunes the watcher’s care

Shutdown signals now travel there
The primary hops, then backgrounds cease
Interrupts bring a log of peace
The shell is free, the run is done
Carrots applaud the graceful one

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #6048 by upgrading refresh, applying the shutdown exit policy to primary processes, preserving explicit policies, removing redundant signal waiting, and handling interrupt ex…
Out of Scope Changes check	✅ Passed	All reviewed changes support the linked issue. The changelog entry, dependency update, generated configuration, watcher changes, platform-specific interrupt handling, and tests are directly related to…
Title check	✅ Passed	The title clearly and concisely describes the primary change: stopping the development watcher when the primary process exits.
Description check	✅ Passed	The description is complete and follows the template. It explains the fix, links issue #6048, identifies the dependency update, marks the change as a bug fix, documents macOS testing and validation co…

Full details: Linked Issues check

Explanation

The changes address issue #6048 by upgrading refresh, applying the shutdown exit policy to primary processes, preserving explicit policies, removing redundant signal waiting, and handling interrupt exits on Unix and Windows. The macOS behavior was verified, and Windows code was cross-compiled; Linux and Windows runtime behavior were not tested.

Full details: Out of Scope Changes check

Explanation

All reviewed changes support the linked issue. The changelog entry, dependency update, generated configuration, watcher changes, platform-specific interrupt handling, and tests are directly related to terminating the complete development session after Ctrl+C.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (3 skipped: 3 unsupported.)

Full details: Description check

Explanation

The description is complete and follows the template. It explains the fix, links issue #6048, identifies the dependency update, marks the change as a bug fix, documents macOS testing and validation commands, includes test configuration, and records that Windows and Linux runtime testing was not performed.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}