Kumo 0.0.7

Kumo 0.0.7 is an incremental release focused on making routing actually take effect, making the toolbar Stop button reliably kill Mihomo, and welcoming first-run users with a guided sheet that installs the kumo CLI and the bundled Agent Skill.

Important: Kumo is still at an early stage. Features and data formats may continue to evolve quickly across macOS environments and runtime setups. Keep backups of important profiles and settings, and treat this build as an early preview.

What changed since 0.0.6

Compared with 0.0.6, this release focuses on three practical tracks:

1. Fixing routing rules not actually being applied in the generated runtime config.
2. Making the toolbar Stop reliably terminate the Mihomo core that Kumo started.
3. Adding a first-run onboarding sheet that bundles the kumo CLI install and Agent Skill registration.

Highlights

Structured runtime configuration merge

RuntimeConfigBuilder now parses profile and override YAML through Yams and merges them structurally, instead of the previous top-level text-block replacement. Routing rules from subscriptions, overrides, and Kumo-controlled keys finally compose with deterministic precedence.

• Added structured mapping-aware deep merge of profile + override YAML.
• Added Sparkle-style sequence operators +rules and rules+ for prepending and appending.
• Added Clash Verge Rev-style prepend-rules, append-rules, and delete-rules for the same effect using the upstream Mihomo key names.
• Added key! syntax to fully replace a nested mapping when overrides need to discard the base value.
• Kept Kumo-controlled keys (controller, ports, mode, geo data, TUN/DNS) as the final layer that always wins.
• Removed sequence operator keys from the final config.yaml so Mihomo only sees the resolved arrays.

Reliable core stop

CoreSupervisor no longer relies solely on the in-memory PID from state.json. It now writes and reads a work/core.pid fallback, reaps child processes with waitpid(WNOHANG), and recovers running status when the JSON state and the live process disagree.

• Added a work/core.pid file written on start and cleared on stop.
• Added waitpid(WNOHANG) based exit detection so already-exited children are not mistaken for live zombies.
• Added stop fallback that signals every PID known to Kumo (state PID + pid file) through SIGINT → SIGTERM → SIGKILL escalation.
• Added status recovery that re-marks the core as running when the PID file points at a live process even if state.json lost the PID.
• Refreshed UI store on stop so service mode, TUN, traffic, rules, connections, and providers reset to the stopped state instead of showing stale data.

First-run onboarding sheet

A native multi-step sheet greets new installs and walks users through the optional helpers. The flow is opt-in at every step and can be reopened later from Settings.

• Added an OnboardingView with Welcome / Command Line Tool / Agent Skill / Done steps gated by UserPreferences.hasCompletedOnboarding.
• Each step is composed with Liquid Glass cards (kumoGlassCard), keeping the visual language consistent with Overview and SubStore surfaces.
• Step indicator animates with snappy spring; step content transitions with a smooth fade.
• Welcome step uses the live NSApp.applicationIconImage hero so it feels like the app's own page.
• Done step shows a green hero checkmark and summary cards for what was actually installed.

CLI install from the GUI

Kumo now ships the kumo CLI inside the app bundle and offers a one-click install of /usr/local/bin/kumo through a single macOS administrator authorization prompt.

• Added CLILinkInstaller in KumoCoreKit that manages the symlink (status / install / uninstall) with the same osascript administrator flow used by the privileged helper.
• Added KumoController.cliLinkStatus(), installCLILink(), and uninstallCLILink() for both the GUI and future automation surfaces.
• Added Kumo.app/Contents/Helpers/kumo bundling so the CLI is always available next to the app. Helpers/ rather than MacOS/ because macOS volumes are case-insensitive by default and Contents/MacOS/kumo would silently overwrite the GUI main binary Contents/MacOS/Kumo.
• Added a Setup section in Settings → General with Run Setup Again and live Command Line Tool install / remove controls so the same flow is available outside onboarding.

Agent Skill registration with brand icons

The onboarding Skill step and the existing Configure surface now share the same brand iconography.

• Promoted AgentBrandIcon to KumoUIComponents and added a size parameter, so Cursor, Claude Code, Codex CLI, and Gemini CLI render their bundled brand PNGs (Generic .agents still falls back to a hierarchical SF Symbol).
• Skill rows in onboarding are fully tappable to toggle selection, with an accent-tinted glass card when selected and a chip showing Installed / Update Available.

Fixes and hardening

Fixed routing rules not taking effect

Profile and override rule sets composed unpredictably under the previous text-block merge. Structured merging plus explicit prepend/append/delete operators ensure routing rules land in the final work/config.yaml exactly as authored.

Fixed Stop sometimes leaving Mihomo running

When the JSON state PID drifted (for example after a Helper restart) or when the child process had exited but not yet been reaped, Stop could report success while the core kept running. The new pid file fallback plus waitpid reaping closes both paths.

Fixed make app shadowing the GUI binary with the CLI

The first attempt at shipping the CLI copied kumo to Contents/MacOS/kumo, which collided with the GUI's Contents/MacOS/Kumo on case-insensitive volumes and replaced the main binary. The CLI now ships under Contents/Helpers/kumo so both binaries coexist.

Documentation and tests

• Updated docs/core/profiles-runtime-configuration.md and docs/core/mihomo-runtime-controller.md for the structured merge contract, sequence operators, and the pid file + waitpid stop pipeline.
• Updated docs/operations/system-integration-permissions.md and docs/interfaces/cli-agent-control.md for the bundled CLI, the Helpers/kumo layout, and the administrator-authorized install flow.
• Updated docs/interfaces/macos-swiftui-interface.md for the onboarding sheet and Settings entries.
• Updated docs/roadmap/sparkle-parity-roadmap.md to mark structured runtime merge and graceful shutdown as implemented.
• New unit tests: CLILinkInstallerTests (7 cases), CoreSupervisorTests (3 cases), UserPreferencesTests (3 cases); expanded RuntimeConfigBuilderTests for new operators and bang replacement. Full suite passes (94 tests).

Assets

• Kumo-macos-0.0.7-arm64.dmg
• latest.yml

SHA-256 for the DMG:

ab74efca50ad76c0c21b0eba72197fa8681302bc4f97a759ead8f401138b4896