From 2011edf485657211eeaad7cfe52a6c36595b53bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Tue, 11 Aug 2026 23:28:02 +0100 Subject: [PATCH] fix(desktop): preserve nested health token ownership (#2538) --- apps/backend/internal/launcher/env.go | 10 ++ apps/backend/internal/launcher/start.go | 2 +- apps/backend/internal/launcher/start_test.go | 86 ++++++++++ .../desktop-health-token-handoff/plan.md | 150 ++++++++++++++++++ ...task-01-restore-desktop-token-ownership.md | 85 ++++++++++ ...k-02-validate-desktop-release-candidate.md | 72 +++++++++ .../task-03-publish-v0-86-2.md | 98 ++++++++++++ docs/specs/desktop-tauri-app/spec.md | 13 +- docs/specs/port-collision-safety/spec.md | 25 ++- 9 files changed, 532 insertions(+), 9 deletions(-) create mode 100644 docs/plans/desktop-health-token-handoff/plan.md create mode 100644 docs/plans/desktop-health-token-handoff/task-01-restore-desktop-token-ownership.md create mode 100644 docs/plans/desktop-health-token-handoff/task-02-validate-desktop-release-candidate.md create mode 100644 docs/plans/desktop-health-token-handoff/task-03-publish-v0-86-2.md diff --git a/apps/backend/internal/launcher/env.go b/apps/backend/internal/launcher/env.go index 37bd000104..69240ac5f7 100644 --- a/apps/backend/internal/launcher/env.go +++ b/apps/backend/internal/launcher/env.go @@ -9,6 +9,7 @@ import ( ) const healthTokenBytes = 32 +const desktopNativeNotificationsEnabled = "true" func newHealthToken() (string, error) { token := make([]byte, healthTokenBytes) @@ -18,6 +19,15 @@ func newHealthToken() (string, error) { return hex.EncodeToString(token), nil } +func launchHealthToken() (string, error) { + if os.Getenv("KANDEV_DESKTOP_NATIVE_NOTIFICATIONS") == desktopNativeNotificationsEnabled { + if token := os.Getenv("KANDEV_DESKTOP_HEALTH_TOKEN"); token != "" { + return token, nil + } + } + return newHealthToken() +} + func backendEnv(ports portConfig, logLevel, consoleLogLevel string, debug bool, healthToken string, extra []string) []string { env := os.Environ() env = upsertEnv(env, "KANDEV_SERVER_PORT", fmt.Sprint(ports.BackendPort)) diff --git a/apps/backend/internal/launcher/start.go b/apps/backend/internal/launcher/start.go index 4beef554dc..96e6829362 100644 --- a/apps/backend/internal/launcher/start.go +++ b/apps/backend/internal/launcher/start.go @@ -92,7 +92,7 @@ func runManagedApp(ctx context.Context, cfg managedAppConfig) int { supervisor := newSupervisorFn() attachSignalsFn(supervisor) shutdownDebugf("runManagedApp signal handler attached") - healthToken, err := newHealthToken() + healthToken, err := launchHealthToken() if err != nil { fmt.Fprintln(os.Stderr, "[kandev] "+err.Error()) return 1 diff --git a/apps/backend/internal/launcher/start_test.go b/apps/backend/internal/launcher/start_test.go index 0a04bf0b93..8c965cd228 100644 --- a/apps/backend/internal/launcher/start_test.go +++ b/apps/backend/internal/launcher/start_test.go @@ -237,6 +237,92 @@ func TestRunManagedAppAttachesSignalsBeforeBackendLaunch(t *testing.T) { } } +func TestRunManagedAppPreservesDesktopOwnedHealthToken(t *testing.T) { + oldNewSupervisor := newSupervisorFn + oldLaunchBackend := launchBackendFn + oldAttachSignals := attachSignalsFn + oldWaitForHealth := waitForHealthFn + t.Cleanup(func() { + newSupervisorFn = oldNewSupervisor + launchBackendFn = oldLaunchBackend + attachSignalsFn = oldAttachSignals + waitForHealthFn = oldWaitForHealth + }) + + const desktopToken = "desktop-owned-token" + var launchedHealthToken string + var waitedHealthToken string + newSupervisorFn = newSupervisor + attachSignalsFn = func(_ *processSupervisor) {} + launchBackendFn = func(cfg backendLaunchConfig) (*restartableBackend, func(), error) { + launchedHealthToken = envValue(cfg.Env, "KANDEV_DESKTOP_HEALTH_TOKEN") + exitCh := make(chan int, 1) + exitCh <- 0 + return &restartableBackend{exitCh: exitCh}, func() {}, nil + } + waitForHealthFn = func(_ context.Context, _ string, _ childState, _ time.Duration, expectedToken string, _ func()) error { + waitedHealthToken = expectedToken + return nil + } + t.Setenv("KANDEV_HOME_DIR", t.TempDir()) + t.Setenv("KANDEV_DESKTOP_NATIVE_NOTIFICATIONS", "true") + t.Setenv("KANDEV_DESKTOP_HEALTH_TOKEN", desktopToken) + + code := runManagedApp(context.Background(), managedAppConfig{ + Header: "test", + Mode: "start", + Backend: "kandev", + BackendCWD: t.TempDir(), + Ports: portConfig{ + BackendPort: 48123, + BackendURL: "http://localhost:48123", + }, + Opts: Options{Headless: true}, + }) + if code != 0 { + t.Fatalf("runManagedApp() = %d, want 0", code) + } + if launchedHealthToken != desktopToken || waitedHealthToken != desktopToken { + t.Fatalf("health tokens launched=%q waited=%q, want %q", launchedHealthToken, waitedHealthToken, desktopToken) + } +} + +func TestLaunchHealthTokenOwnership(t *testing.T) { + const staleToken = "stale-token" + tests := []struct { + name string + marker string + healthToken string + want string + wantFresh bool + }{ + {name: "desktop-owned", marker: "true", healthToken: "desktop-token", want: "desktop-token"}, + {name: "desktop-owned-without-token", marker: "true", wantFresh: true}, + {name: "ordinary-launch-with-stale-token", healthToken: staleToken, wantFresh: true}, + {name: "non-exact-marker-with-stale-token", marker: "TRUE", healthToken: staleToken, wantFresh: true}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + t.Setenv("KANDEV_DESKTOP_NATIVE_NOTIFICATIONS", test.marker) + t.Setenv("KANDEV_DESKTOP_HEALTH_TOKEN", test.healthToken) + + got, err := launchHealthToken() + if err != nil { + t.Fatal(err) + } + if test.wantFresh { + if got == "" || got == test.healthToken { + t.Fatalf("health token = %q, want a fresh non-empty token", got) + } + return + } + if got != test.want { + t.Fatalf("health token = %q, want %q", got, test.want) + } + }) + } +} + func envValue(env []string, key string) string { prefix := key + "=" for _, item := range env { diff --git a/docs/plans/desktop-health-token-handoff/plan.md b/docs/plans/desktop-health-token-handoff/plan.md new file mode 100644 index 0000000000..d315c14ed6 --- /dev/null +++ b/docs/plans/desktop-health-token-handoff/plan.md @@ -0,0 +1,150 @@ +--- +spec: docs/specs/port-collision-safety/spec.md +created: 2026-08-11 +status: in_progress +--- + +# Implementation Plan: Desktop Health Token Handoff + +## Overview + +Kandev v0.86.1 introduced a nested readiness-owner regression. The Tauri shell creates a token, +but the native Go launcher creates a second token and overwrites the inherited value. The backend +becomes ready with the launcher's token, the shell rejects it for 60 seconds, and the shell then +terminates the healthy backend. + +The repair preserves the desktop-owned token only when the exact desktop launch marker and a +non-empty token are both present. Ordinary CLI, development, and service launches continue to +generate a fresh token and ignore stale inherited values. After targeted tests and a five-platform +desktop validation run, the stable release workflow publishes v0.86.2. + +The companion desktop contract is +[Tauri Desktop App](../../specs/desktop-tauri-app/spec.md). Launcher ownership remains governed by +[ADR-2026-08-08-go-launcher-owns-all-launch-modes](../../decisions/2026-08-08-go-launcher-owns-all-launch-modes.md). + +## Backend + +### Readiness-token ownership selection + +Update `apps/backend/internal/launcher/env.go` with a small `launchHealthToken` helper. It returns +the inherited `KANDEV_DESKTOP_HEALTH_TOKEN` only when +`KANDEV_DESKTOP_NATIVE_NOTIFICATIONS` is exactly `true` and the inherited token is non-empty. +Otherwise it calls the existing `newHealthToken` generator. + +Update `runManagedApp` in `apps/backend/internal/launcher/start.go` to use the selected token for +both `backendEnv` and `waitForHealthFn`. This keeps the backend, supervisor manifest, native +launcher poll, and Tauri shell on one token for desktop-owned launches while retaining a fresh +launcher-owned token everywhere else. Token values remain absent from logs and errors. + +No backend health route, Tauri Rust production code, command-line option, database, or migration +changes are required. + +## Tests + +- **What:** A desktop-owned nested launch preserves the Tauri-generated token through the native + launcher child environment and health poll. + **File:** `apps/backend/internal/launcher/start_test.go`. + **How:** Set both desktop environment values, inject the existing backend-launch and health-poll + seams, and assert the same known token reaches both. This test must fail before the production + change because v0.86.1 replaces the known token. +- **What:** An ordinary CLI launch does not trust a stale inherited desktop health token. + **File:** `apps/backend/internal/launcher/start_test.go`. + **How:** Set an inherited token without the desktop marker and assert the backend and health poll + share a fresh non-empty value different from the stale token. +- **What:** A malformed desktop ownership environment does not bypass fresh token generation. + **File:** `apps/backend/internal/launcher/start_test.go`. + **How:** Cover a missing token and a marker value other than exact `true`. +- **What:** The Tauri shell still supplies both the ownership marker and generated token to the + bundled launcher. + **File:** `apps/desktop/src-tauri/src/backend.rs` (existing Rust unit test). + **How:** Run the focused `command_spec_uses_headless_launcher_and_loopback_env` test alongside + the Go regression suite. +- **What:** The changed backend code passes the repository's static checks. + **File:** `apps/backend/`. + **How:** Run `golangci-lint run ./... --new-from-rev=31907ba651221b3bdb09a1db2f19786b43457863 + --timeout=5m` and require zero issues. + +## E2E Tests + +- **Scenario:** Given a v0.86.2 desktop build starts its bundled native launcher, when the backend + becomes ready, then the WebView leaves the startup surface and the backend remains alive past the + former 60-second timeout. +- **Evidence:** The Go boundary regression exercises the real nested token-selection path. The + existing Rust command-spec test proves the Tauri producer. A `desktop_validation_only` Release + workflow run builds all five desktop targets before publication. After publication, update the + affected macOS installation from v0.86.1 and confirm the SPA opens and remains connected. + +## Verification Results + +Task 01 completed locally. The required Rust toolchain was available outside `PATH`, and Cargo +needed writable temporary cache directories in this environment. + +- RED: `go test ./internal/launcher -run TestRunManagedAppPreservesDesktopOwnedHealthToken + -count=1` failed with a generated launcher token instead of the desktop-owned token. +- GREEN: `go test ./internal/launcher -run 'Test(LaunchHealthToken|RunManagedApp)' -count=1` + passed. +- Package regression: `go test ./internal/launcher -count=1` passed. +- Desktop producer: `cargo test --features desktop-runtime + backend::tests::command_spec_uses_headless_launcher_and_loopback_env` passed with the checked-in + Rust toolchain and temporary `CARGO_HOME`/`CARGO_TARGET_DIR`. +- Changed-code lint: `golangci-lint run ./... --new-from-rev=31907ba651221b3bdb09a1db2f19786b43457863 + --timeout=5m` passed with zero issues after the `goconst` cleanup. + +Tasks 02 and 03 remain pending until the fix is merged to `main` and the release workflow can be +run under their documented preconditions. + +## Implementation Waves And Parallel Candidates + +All work is sequential because validation and publication depend on the merged fix. + +Wave 1: + +- [x] [Task 01: Restore desktop token ownership](task-01-restore-desktop-token-ownership.md) + +Wave 2: + +- [ ] [Task 02: Validate desktop release candidate](task-02-validate-desktop-release-candidate.md) + +Wave 3: + +- [ ] [Task 03: Publish stable v0.86.2](task-03-publish-v0-86-2.md) + +No task is parallel-safe, and this plan does not authorize subagents. + +## Release + +The current stable baseline is v0.86.1. Its GitHub Release, five desktop builds, updater feed, +five native runtime packages plus `kandev` on npm, GHCR images, and Homebrew formula were verified +before this plan was written. + +After the fix PR merges, run the Release workflow from `main` first with +`desktop_validation_only=true`. If all five desktop builds succeed, run normal Stable mode with +`bump=patch`, which computes v0.86.2, creates and merges the release PR, signs and pushes the tag, +and publishes every channel. Do not use `backfill_tag`: v0.86.1 contains defective immutable code, +so the release contract requires a new patch. + +Declare the release complete only after `Publish GitHub release`, `Publish npm packages`, and +`Update Homebrew tap` succeed, the versioned GHCR manifests exist, the updater feed references +v0.86.2, and the affected macOS desktop launch succeeds. + +## Risks + +- Reusing every inherited token would weaken launcher ownership and reintroduce wrong-process + readiness. Reuse is limited to the exact desktop marker plus a non-empty token. +- The desktop marker currently also suppresses duplicate backend notifications. The repair reuses + that established desktop-owned launch signal but does not change notification behavior. +- A green aggregate Release run can hide skipped publication jobs. Required publication jobs and + artifacts must be inspected individually. +- macOS and Windows signing depend on configured release secrets. Missing signing must remain + visible in release notes and must not be misreported as a signed release. + +## Out of Scope + +- Changing health header names, the 60-second timeout, default ports, or WebView navigation. +- Adding a public CLI flag or user-configurable health token. +- Changing release automation, version-channel policy, or updater behavior. +- Rolling back the v0.86.1 database migrations. + +## Open Questions + +None. diff --git a/docs/plans/desktop-health-token-handoff/task-01-restore-desktop-token-ownership.md b/docs/plans/desktop-health-token-handoff/task-01-restore-desktop-token-ownership.md new file mode 100644 index 0000000000..80e9c26090 --- /dev/null +++ b/docs/plans/desktop-health-token-handoff/task-01-restore-desktop-token-ownership.md @@ -0,0 +1,85 @@ +--- +id: "01-restore-desktop-token-ownership" +title: "Restore desktop token ownership" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +spec: "../../specs/port-collision-safety/spec.md" +--- + +# Task 01: Restore desktop token ownership + +## Acceptance + +- A desktop-owned launch reuses its exact non-empty inherited health token for the backend child, + native launcher poll, and supervisor restart manifest. +- An ordinary CLI, development, or service launch generates a fresh token even if its environment + contains a stale `KANDEV_DESKTOP_HEALTH_TOKEN`. +- Missing or non-exact desktop ownership values fall back to fresh token generation, and no token + value appears in logs or errors. + +## Verification + +Use TDD. Add the desktop-owned `runManagedApp` regression first and confirm it fails because the +known token is replaced. Implement the smallest selection helper, then run: + +```bash +cd apps/backend && \ + go test ./internal/launcher -run 'Test(LaunchHealthToken|RunManagedApp)' -count=1 && \ + go test ./internal/launcher -count=1 && \ + cd ../../apps/desktop/src-tauri && \ + cargo test --features desktop-runtime backend::tests::command_spec_uses_headless_launcher_and_loopback_env && \ + cd ../../../apps/backend && \ + golangci-lint run ./... --new-from-rev=31907ba651221b3bdb09a1db2f19786b43457863 --timeout=5m +``` + +## Files likely touched + +- `apps/backend/internal/launcher/env.go` +- `apps/backend/internal/launcher/start.go` +- `apps/backend/internal/launcher/start_test.go` +- `docs/plans/desktop-health-token-handoff/plan.md` +- `docs/plans/desktop-health-token-handoff/task-01-restore-desktop-token-ownership.md` + +## Dependencies + +None. + +## Parallelism + +`sequential`. The test seams and launcher environment are shared within one package. + +## Inputs + +- `docs/specs/port-collision-safety/spec.md`, Backend readiness ownership and Issue #2372 scenarios. +- `docs/specs/desktop-tauri-app/spec.md`, Existing launch and data contract. +- `apps/desktop/src-tauri/src/backend.rs`, `launch_and_wait` and + `command_spec_uses_headless_launcher_and_loopback_env`. +- `apps/backend/internal/launcher/start.go`, `runManagedApp`. +- `apps/backend/internal/launcher/env.go`, `newHealthToken` and `backendEnv`. + +## Output contract + +Report the red test failure, minimal production change, exact command results, files changed, +security boundary, blockers, risks, and synchronized task/plan status in the primary conversation. + +## Results + +RED: `go test ./internal/launcher -run TestRunManagedAppPreservesDesktopOwnedHealthToken -count=1` +failed because the launcher replaced the known desktop-owned token with a generated value. + +GREEN and verification: + +- `go test ./internal/launcher -run 'Test(LaunchHealthToken|RunManagedApp)' -count=1` passed. +- `go test ./internal/launcher -count=1` passed. +- `cargo test --features desktop-runtime + backend::tests::command_spec_uses_headless_launcher_and_loopback_env` passed using the checked-in + Rust toolchain with temporary writable Cargo cache and target directories. +- `golangci-lint run ./... --new-from-rev=31907ba651221b3bdb09a1db2f19786b43457863 + --timeout=5m` passed with zero issues after the `goconst` cleanup. + +The launcher now reuses the inherited token only when the desktop-owned marker is exactly `true` +and the token is non-empty. Ordinary and malformed launches still generate a fresh token. The +backend child environment and health poll receive the same selected token, and no token is added +to logs or errors. diff --git a/docs/plans/desktop-health-token-handoff/task-02-validate-desktop-release-candidate.md b/docs/plans/desktop-health-token-handoff/task-02-validate-desktop-release-candidate.md new file mode 100644 index 0000000000..8185e912f6 --- /dev/null +++ b/docs/plans/desktop-health-token-handoff/task-02-validate-desktop-release-candidate.md @@ -0,0 +1,72 @@ +--- +id: "02-validate-desktop-release-candidate" +title: "Validate desktop release candidate" +status: pending +wave: 2 +depends_on: ["01-restore-desktop-token-ownership"] +plan: "plan.md" +spec: "../../specs/port-collision-safety/spec.md" +--- + +# Task 02: Validate desktop release candidate + +## Acceptance + +- Task 01 is committed, reviewed, merged to `main`, and required checks are green. +- A `desktop_validation_only` Release workflow run from that exact `main` commit succeeds for all + five runtime bundles and desktop targets. +- The validation run creates no release PR, tag, GitHub Release, GHCR tag, npm package, or Homebrew + update. + +## Verification + +Confirm `main` contains the merged fix and capture that immutable commit before dispatching the +non-publishing validation mode: + +```bash +main_sha=$(gh api repos/kdlbs/kandev/git/ref/heads/main --jq '.object.sha') +test -n "$main_sha" +gh workflow run release.yml --repo kdlbs/kandev --ref "$main_sha" \ + -f channel=stable \ + -f bump=patch \ + -f dry_run=false \ + -f desktop_validation_only=true \ + -f backfill_tag= +gh run watch --repo kdlbs/kandev --exit-status +validation_head_sha=$(gh run view --repo kdlbs/kandev --json headSha --jq '.headSha') +test "$validation_head_sha" = "$main_sha" +gh run view --repo kdlbs/kandev --json headSha,jobs,url +``` + +Inspect the job list rather than only the aggregate conclusion. Record successful runtime and +desktop jobs for Linux x64/arm64, macOS x64/arm64, and Windows x64, plus skipped publication jobs. +After the run, verify that no release PR, `v0.86.2` tag or GitHub Release, GHCR `0.86.2` tag, +npm `0.86.2` package, or Homebrew `0.86.2` formula update exists. + +## Files likely touched + +- `docs/plans/desktop-health-token-handoff/plan.md` +- `docs/plans/desktop-health-token-handoff/task-02-validate-desktop-release-candidate.md` + +## Dependencies + +Task 01 and its merged fix PR. + +## Parallelism + +`sequential`. Validation must use the merged fix commit and the repository-wide Release workflow. + +## Inputs + +- Task 01 results and merged PR URL. +- `.github/workflows/release.yml`, `desktop_validation_only` mode. +- `docs/public/release-process.md`, Before dispatch and Desktop validation requirements. + +## Output contract + +Report the exact `main` SHA, workflow run URL, per-target results, absence of publication side +effects, blockers, risks, and synchronized task/plan status in the primary conversation. + +## Results + +Pending. diff --git a/docs/plans/desktop-health-token-handoff/task-03-publish-v0-86-2.md b/docs/plans/desktop-health-token-handoff/task-03-publish-v0-86-2.md new file mode 100644 index 0000000000..0519f39b55 --- /dev/null +++ b/docs/plans/desktop-health-token-handoff/task-03-publish-v0-86-2.md @@ -0,0 +1,98 @@ +--- +id: "03-publish-v0-86-2" +title: "Publish stable v0.86.2" +status: pending +wave: 3 +depends_on: ["02-validate-desktop-release-candidate"] +plan: "plan.md" +spec: "../../specs/port-collision-safety/spec.md" +--- + +# Task 03: Publish stable v0.86.2 + +## Acceptance + +- The latest Stable version is still v0.86.1, no release is active, and the validated fix commit is + on `main`. If the Stable baseline changed, stop and recalculate instead of publishing the wrong + version. +- Normal Stable mode publishes v0.86.2 from `main`; the release PR merge and signed tag contain the + desktop health-token fix. +- GitHub Release/updater assets, six npm packages, versioned GHCR base/universal manifests, and the + Homebrew formula all report 0.86.2, and a macOS v0.86.1-to-v0.86.2 update starts successfully. + +## Verification + +After confirming the preconditions, record the Task 02 validated SHA and dispatch the one-click +Stable patch flow from that immutable commit: + +```bash +validated_sha="" +test -n "$validated_sha" +gh workflow run release.yml --repo kdlbs/kandev --ref "$validated_sha" \ + -f channel=stable \ + -f bump=patch \ + -f dry_run=false \ + -f desktop_validation_only=false \ + -f backfill_tag= +gh run watch --repo kdlbs/kandev --exit-status +release_head_sha=$(gh run view --repo kdlbs/kandev --json headSha --jq '.headSha') +test "$release_head_sha" = "$validated_sha" +gh run view --repo kdlbs/kandev --json headSha,jobs,url +``` + +Verify every channel individually: + +```bash +set -euo pipefail + +git fetch --tags origin && git tag -v v0.86.2 +tag_sha=$(git rev-list -n 1 v0.86.2) +git merge-base --is-ancestor "$validated_sha" "$tag_sha" +gh release view v0.86.2 --repo kdlbs/kandev --json tagName,isDraft,isPrerelease,publishedAt,url,assets +for package_path in kandev \ + %40kdlbs%2Fruntime-linux-x64 %40kdlbs%2Fruntime-linux-arm64 \ + %40kdlbs%2Fruntime-darwin-x64 %40kdlbs%2Fruntime-darwin-arm64 \ + %40kdlbs%2Fruntime-win32-x64; do + curl -fsSL "https://registry.npmjs.org/$package_path/0.86.2" | jq -e '.version == "0.86.2"' +done +gh api repos/kdlbs/homebrew-kandev/contents/Formula/kandev.rb \ + -H 'Accept: application/vnd.github.raw+json' | rg 'version "0.86.2"' +docker buildx imagetools inspect ghcr.io/kdlbs/kandev:0.86.2 +docker buildx imagetools inspect ghcr.io/kdlbs/kandev:0.86.2-universal +``` + +Inspect the Release jobs individually. `Publish GitHub release`, `Publish npm packages`, and +`Update Homebrew tap` must all succeed. Confirm `latest.json` and both macOS updater archives are +present. Update the affected macOS installation from v0.86.1, launch it, and confirm the SPA opens +and its backend remains alive beyond the former 60-second termination point. + +## Files likely touched + +- Release workflow-generated version and changelog files on its release branch. +- `docs/plans/desktop-health-token-handoff/plan.md` +- `docs/plans/desktop-health-token-handoff/task-03-publish-v0-86-2.md` + +## Dependencies + +Task 02 and its successful validation workflow run. + +## Parallelism + +`sequential`. Stable publication is a single serialized workflow with immutable outputs. + +## Inputs + +- Task 02 validation run URL and exact `main` SHA. +- `.github/workflows/release.yml`, normal Stable mode. +- `docs/public/release-process.md`, Normal release flow and Verify every channel. +- `.agents/skills/release/SKILL.md`, Stable completion and backfill rules. + +## Output contract + +Report the release PR, signed tag verification, workflow run, artifact URLs/digests, each channel's +version, macOS update smoke evidence, blockers, risks, and synchronized task/plan status in the +primary conversation. + +## Results + +Pending. diff --git a/docs/specs/desktop-tauri-app/spec.md b/docs/specs/desktop-tauri-app/spec.md index 5a99089b24..ee789a5757 100644 --- a/docs/specs/desktop-tauri-app/spec.md +++ b/docs/specs/desktop-tauri-app/spec.md @@ -1,7 +1,7 @@ --- status: shipped created: 2026-06-23 -updated: 2026-07-15 +updated: 2026-08-11 owner: tbd --- @@ -62,8 +62,11 @@ kandev --headless --port with `KANDEV_SERVER_HOST=127.0.0.1`, and waits for `GET /health`. Each launch supplies a generated `KANDEV_DESKTOP_HEALTH_TOKEN`; readiness requires the same value in the successful response's -`X-Kandev-Desktop-Health-Token` header before the WebView navigates to the backend origin. A second -instance focuses the first and does not start another backend. +`X-Kandev-Desktop-Health-Token` header before the WebView navigates to the backend origin. The +desktop shell also sets `KANDEV_DESKTOP_NATIVE_NOTIFICATIONS=true` to identify the launch as +desktop-owned. The nested native launcher must forward the shell's exact non-empty health token to +the backend and use it for its own readiness poll rather than replacing it with another token. A +second instance focuses the first and does not start another backend. The shell preserves the existing GUI-launch `PATH` normalization and the existing Kandev data directory, SQLite database, worktrees, executor settings, integrations, and agent configuration. @@ -244,6 +247,10 @@ display before being shown. **THEN** the current WebView zoom decreases, increases, or resets without resizing the window. - **GIVEN** the machine has no Node.js runtime, **WHEN** the packaged desktop app starts, **THEN** its bundled native launcher/backend and embedded SPA become ready without a Node web server. +- **GIVEN** the desktop shell starts its bundled native launcher with a generated health token, + **WHEN** the launcher starts and polls the backend, **THEN** the launcher preserves that exact + token through the backend response and the WebView navigates without reaching the startup + timeout. - **GIVEN** New Task is the topmost dismissible dialog, **WHEN** the user presses `Cmd+W`, **THEN** that dialog closes and the app and backend remain running. - **GIVEN** a closable file tab is focused and no dismissible overlay is open, **WHEN** the user diff --git a/docs/specs/port-collision-safety/spec.md b/docs/specs/port-collision-safety/spec.md index 44edc74d97..78d95a2ebf 100644 --- a/docs/specs/port-collision-safety/spec.md +++ b/docs/specs/port-collision-safety/spec.md @@ -1,7 +1,7 @@ --- status: building created: 2026-08-07 -updated: 2026-08-09 +updated: 2026-08-11 --- # Port collision and backend ownership safety @@ -48,10 +48,19 @@ starting their backend child: ### Backend readiness ownership -Every TypeScript or native Go launcher invocation must create a fresh opaque health token before -starting its backend. It passes the token to the child through the existing -KANDEV_DESKTOP_HEALTH_TOKEN environment variable and retains it for supervisor-managed backend -restarts. +The process that owns user-visible readiness must create one fresh opaque health token for the +launch. An ordinary TypeScript or native Go launcher invocation owns readiness, creates the token, +passes it to the backend through the existing KANDEV_DESKTOP_HEALTH_TOKEN environment variable, +and retains it for supervisor-managed backend restarts. + +The Tauri desktop shell is a nested-launch exception because it owns the outer readiness check and +WebView navigation. It creates the token before invoking `kandev --headless`, identifies the launch +as desktop-owned with `KANDEV_DESKTOP_NATIVE_NOTIFICATIONS=true`, and passes the token to the native +launcher. When both the desktop-owned marker and a non-empty token are present, the native launcher +must preserve that exact token for its backend child and its own health poll. It must not replace the +desktop-owned token with a second generated value. Without that marker, the native launcher must +replace any ambient KANDEV_DESKTOP_HEALTH_TOKEN with a fresh token so a stale shell environment +cannot claim readiness ownership. The launcher health poll succeeds only when the response is a 2xx response and its X-Kandev-Desktop-Health-Token response header exactly matches the token generated for that @@ -124,6 +133,12 @@ not part of this contract. health, then it announces readiness exactly once. 4. Given the supervisor restarts the backend for the same launcher invocation, when the restarted backend responds with the retained token, then health succeeds without accepting a stranger. +5. Given the Tauri shell marks a launch as desktop-owned and supplies a non-empty token, when the + nested native launcher starts and polls the backend, then the backend and both readiness checks + use that same token and the WebView can navigate without waiting for the startup timeout. +6. Given an ordinary CLI launch inherits a stale health token without the desktop-owned marker, + when the native launcher starts, then it replaces the stale value with a fresh token for the + backend and its own health poll. ### Issue #2371: Windows allocator retry