feat(desktop): land Electron desktop app (consolidated stack)

[johnwschoi]

What

Lands the remaining content of the desktop stack ([4b/5] runtime orchestrator, [4c/5] main wiring + OAuth/protocol, [5/5] electron-builder packaging) as a single squash-merge to avoid cascading review dismissals from sequential base-branch changes.

Why this PR ate the rest of the stack

#396 ([4a/5] window primitives) merged successfully as 62f4095. The original plan was to merge #397 → #398 → #373 sequentially. But every base change in a stacked workflow dismisses approvals on this repo, so a 4-PR sequential merge would have cost 3 separate re-review cycles, AND each step inherited add/add conflicts because the squashed parent on main couldn't auto-merge against the cumulative-history branches below.

Instead we consolidated #397's branch (pr/desktop-6b-orchestrator) to contain the full stack tip + a merge of current main, so a single re-review unblocks everything. #398 and #373 will auto-close when this lands.

Branch history

• 76fc9f3d — root package.json / package-lock.json / CHANGELOG kept matching main (root manifest doesn't need to change in a stack scoped to packages/desktop/; was reverting main's 0.1.64/65/66 release bumps)
• e17c0ba1 — merge of origin/main into the stack tip, resolving 6 conflicts:
  • 4 add/add files (packages/desktop/src/window-{factory,registry,state}.ts, packages/desktop/test/window-state.test.ts) → took stack's later-refactored versions
  • 2 content conflicts (packages/desktop/package.json, packages/desktop/package-lock.json) → stack is a strict superset of main's [4a/5] feat(desktop): window management primitives #396 snapshot; took stack
  • Removed packages/desktop/test/window-factory.test.ts to match stack tip's intent (file added by squashed [4a/5] feat(desktop): window management primitives #396 but dropped by later stack work)

Diff vs main

29 files. 27 in packages/desktop/. Non-desktop changes:

• .gitignore: +1 line for packages/desktop/cli
• .github/workflows/test.yml: macOS-only actions/setup-python@v5 step for node-gyp/distutils on macos-latest

Zero changes to web-ui/, src/, test/, scripts/.

Prior approvals (now archived as audit trail on #398/#373)

• [4c/5] feat(desktop): protocol handling, OAuth relay, and main wiring #398 [4c/5] was approved by @maxpaulus43 (commit fe589ac) and @robinnewhouse (commit fe589ac)
• [5/5] feat(desktop): electron-builder packaging, CLI shims, and release scripts #373 [5/5] was approved by @maxpaulus43 (commits bf1de07, 816b64a)

The content of those PRs lives in this branch's history (c122fb9f..76fc9f3d carries the full stack chain).

cc @maxpaulus43 @robinnewhouse for re-approval — same content as previously approved on #398 and #373, plus the merge-with-main resolution above.

Update: also folds in #427

Commit 1c4e7b1a strips trailing blank lines at EOF in 6 files (originally proposed as #427, also by @johnwschoi). #427 has been closed and points back here. 8 line deletions:

• packages/desktop/scripts/launch-electron.mjs
• packages/desktop/src/window-state.ts
• packages/desktop/test/main.test.ts
• packages/desktop/test/protocol-handler.test.ts
• packages/desktop/test/runtime-orchestrator.test.ts
• packages/desktop/test/window-state.test.ts

[greptile-apps]

Greptile Summary

This PR lands the consolidated Electron desktop stack for Kanban: the runtime orchestrator ([4b/5]), main process wiring with OAuth/protocol handling ([4c/5]), and electron-builder packaging ([5/5]). The implementation is thorough — probe generation tokens, terminated flag fencing at every await boundary, local-capture patterns to guard against null-dereference during async teardown, and a clean notarize/stage/patch-node-pty build pipeline. Most of the races previously flagged in review threads appear addressed in the current code.

Confidence Score: 5/5

Safe to merge; the single finding is a hardening suggestion, not a current defect.

All findings are P2. The missing fetch timeout in relayOAuthCallback is a best-practice gap rather than a present defect — the relay targets localhost and the runtime is only called when getUrl() is non-null. No P0/P1 issues identified.

packages/desktop/src/oauth-relay.ts — minor fetch-timeout hardening suggested.

Important Files Changed

Filename	Overview
packages/desktop/src/main.ts	Main Electron entry: wires orchestrator, window factory, protocol handler, IPC, and lifecycle hooks. The before-quit orphan-window gap (isOwned() false during spawn) is a pre-existing open thread; rest of the logic looks correct with well-guarded async paths.
packages/desktop/src/runtime-orchestrator.ts	Core orchestrator: all previously flagged races (terminated guard, dispose null-guard, orphan-cleanup capture, restart stale URL, startRecoveryProbe ordering) appear addressed. Generation tokens for in-flight probes are a clean approach.
packages/desktop/src/oauth-relay.ts	OAuth relay: retry loop is clean, but missing AbortController/timeout on fetch unlike the checkHealth pattern; could stall unbounded on each attempt if the runtime is slow.
packages/desktop/src/protocol-handler.ts	Protocol parsing correctly handles non-special kanban:// scheme by rejoining hostname+pathname; registration guard prevents double-registration.
packages/desktop/scripts/notarize.cjs	afterSign hook: correctly checks electronPlatformName (darwin vs mac), validates required env vars before importing @electron/notarize; exports helpers for unit testing.
packages/desktop/electron-builder.yml	Packaging config: asarUnpack covers cli/** and node-pty for real-path requirements; extraResources filter explicitly excludes kanban-dev shims; DMG artifact naming is correct.

Sequence Diagram

sequenceDiagram
    participant App as main.ts
    participant Orch as RuntimeOrchestrator
    participant Child as RuntimeChildManager
    participant Runtime as Kanban Runtime (CLI)
    participant Browser as BrowserWindow

    App->>Orch: connect()
    Orch->>Runtime: checkHealth(origin)
    alt Runtime already running
        Runtime-->>Orch: 200 OK
        Orch->>Orch: setUrl(origin, owns=false)
        Orch->>Orch: startAttachedProbe()
    else No runtime found
        Runtime-->>Orch: error/timeout
        Orch->>Child: createManager() + start()
        Child->>Runtime: spawn CLI shim
        Runtime-->>Child: ready URL
        Child-->>Orch: url
        Orch->>Orch: setUrl(url, owns=true)
    end
    Orch-->>App: emit url-changed(url)
    App->>Browser: loadUrlInAllWindows(url)

    note over Orch,Runtime: Crash / detach path
    Runtime--xChild: process exit
    Child-->>Orch: emit crashed
    Orch->>Orch: handleCrash() → startRecoveryProbe()
    Orch->>Orch: setUrl(null)
    Orch-->>App: emit crashed
    App->>Browser: showDisconnectedScreen()

    note over App,Orch: Quit path
    App->>Orch: shutdown() [if owned]
    Orch->>Orch: terminated=true, drain promises
    Orch->>Child: manager.shutdown()
    Child->>Runtime: SIGTERM → SIGKILL
    Orch->>App: returns
    App->>App: app.quit()

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
packages/desktop/src/oauth-relay.ts:19-21
**No fetch timeout in `relayOAuthCallback`**

Unlike `checkHealth` — which wraps its `fetch` with an `AbortController` — `relayOAuthCallback` issues bare `fetch` calls with no timeout. With the default `retries = 2`, three consecutive requests can each hang indefinitely before the 1-second inter-attempt delay even begins, stalling the OAuth flow silently for an unbounded duration if the runtime is momentarily unresponsive.

Suggested pattern matching `checkHealth`:
```typescript
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5_000);
try {
  const response = await deps.fetch(relayUrl, { signal: controller.signal });
  if (response.ok) return;
  lastFailure = `HTTP ${response.status}`;
} catch (err) {
  lastFailure = err instanceof Error ? err.message : String(err);
} finally {
  clearTimeout(timer);
}
```

_{Reviews (18): Last reviewed commit: "fix(desktop): address remaining review c..." | Re-trigger Greptile}

[johnwschoi]

@greptileai

The base branch was changed.

[johnwschoi]

@greptileai