feat(desktop): respawn host-service on every Electron auto-update

[Kitenite]

Plan: apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md

Summary

• Auto-updated desktops now always end up running a freshly spawned host-service. The coordinator pins host-service adoption to the desktop's app.getVersion(): if a running host-service was spawned by a different desktop version, it's killed (SIGTERM) and respawned from the bundled binary on the next Electron launch.
• Pty-daemon — the durable session-state holder — has its own manifest + supervisor and is unaffected, so terminal sessions survive the host-service swap.
• MIN_HOST_SERVICE_VERSION is retained for the renderer-side remote-host gate (useRemoteHostStatus) where we can't kill the remote process and a floor is still the right shape.

Why / Context

Previously, tryAdopt accepted any local host-service satisfying >= MIN_HOST_SERVICE_VERSION — a manually-bumped floor. After auto-update, a stale host-service that cleared the floor stuck around indefinitely; non-breaking host-service changes never reached users until someone remembered to bump the floor.

Why "kill on Electron update" is OK here

Host-service has two deployment modes, and they want different things:

• Bundled with Electron (this PR's path). Host-service ships in the desktop binary. Co-deployed → freshness wins → killing on next-launch adoption is fine.
• Standalone CLI on a remote machine (consumed by the desktop via the renderer remote-host flow). Has its own update cadence independent of any one Electron build → lifecycle preservation matters there. Unchanged by this PR: the desktop never reads or writes that machine's manifest; the renderer-side useRemoteHostStatus floor gate is the only contract.

The detached/manifest/fd-handoff machinery exists primarily for the standalone case. Repurposing the bundled-local manifest for "always fresh" is deliberate now that the standalone case is structurally separated.

User-visible cost is small: pty-daemon (packages/host-service/src/daemon/DaemonSupervisor.ts) has its own manifest+adoption lifecycle, so killing host-service drops only tunnel-client WebSockets (auto-reconnect) and the in-memory terminal sessions Map (rebuilt on re-attach via daemon-client). Real PTY state stays in the daemon.

We still do not kill host-service in the auto-updater path itself (no stopBackendAndWaitForExit-style step before quitAndInstall). The kill happens on the next Electron launch via tryAdopt — single code path that handles auto-update, crash recovery, and manual restart uniformly.

How It Works

• HostServiceManifest gains spawnedByAppVersion: string. The host-service child writes it from a new SUPERSET_APP_VERSION env var. The coordinator sets that env from app.getVersion() when spawning.
• tryAdopt:

  if (manifest.spawnedByAppVersion !== app.getVersion()) {
      // SIGTERM the old PID, drop the manifest, fall through to spawn()
  }

• Pre-existing manifests (without the field) are coerced to "" by readManifest so the old PID is still found and killed — no orphan. Result: every existing user respawns host-service exactly once on first launch after this ships.

Why app-version, not host-service version

A host-service version pin was implemented and then removed. In our build flow host-service ships with the desktop, so the app-version pin strictly subsumes it for the auto-update use case — plus it catches the case where someone forgets to bump the host-service version on a host-service code change. The removed pin only added value for a hand-rolled binary in dev.

Side cleanup

• packages/host-service/package.json#version was previously stuck at 0.1.0 while host.info hard-coded "0.8.0". Reconciled: host.info now reads pkg.version via with { type: "json" } (mirrors EXPECTED_DAEMON_VERSION), and the package.json was bumped 0.1.0 → 0.8.1. Added "./package.json": "./package.json" to the exports map. The renderer-side remote-host gate still uses MIN_HOST_SERVICE_VERSION = "0.8.0" against this reported value.
• semver import dropped from the coordinator (no longer needed there).

Manual QA Checklist

App-version pin (the main behavior)

• Fresh launch with no manifest → host-service spawns, manifest written with spawnedByAppVersion: app.getVersion().
• Same Electron version restarts → adoption succeeds, no respawn (no "killing" log).
• Simulate auto-update: change apps/desktop/package.json version (or run a different packaged build), restart → coordinator logs Adopted service spawned by app X.X.X != current Y.Y.Y, killing, SIGTERMs the old PID, spawns fresh.
• Pre-existing manifest (no spawnedByAppVersion) → logs no recorded app version (pre-upgrade manifest), killing once, then settles.

Pty-daemon survives the swap

• Open a v2 workspace terminal, type some text.
• Trigger a host-service respawn (via the version-mismatch path above).
• After Electron relaunches, the terminal session re-attaches to the same daemon-side PTY and shows the prior buffer (no fresh shell).

Tunnel reconnect

• Brief tunnel reconnect on host-service respawn is acceptable (no permanent disconnect, no error toast loop).
• Trigger a respawn while a workspace is mid-render — renderer recovers cleanly without manual reload.

Remote-host gate untouched

• useRemoteHostStatus still uses MIN_HOST_SERVICE_VERSION; connecting to a remote host below the floor still surfaces the existing "host CLI too old" UI.
• Connecting to a remote on 0.8.0 works (floor = 0.8.0, satisfies). Connecting to a remote on 0.8.1 works (satisfies floor).

Testing

• bun run typecheck — pass.
• bun run lint — pass.
• bun turbo run build --filter=@superset/desktop --filter=@superset/host-service — pass. Verified packaged ASAR bundles host-service@0.8.1 and that SUPERSET_APP_VERSION = electron.app.getVersion(...) is wired through to manifest.spawnedByAppVersion.

Risks / Rollout

• One-time forced respawn for every existing user on first launch after this ships (their manifest lacks spawnedByAppVersion). In-flight tRPC requests during the kill window fail; renderer reconnect handles it. Pty-daemon is unaffected — terminal sessions survive.
• Hard SIGTERM, no drain. Same as before this PR. Respawn cadence is now "every desktop update" instead of "every host-service version bump." If users notice tunnel blips after auto-updates, drain-before-SIGTERM is the lever to revisit (deferred in the plan).
• Rollback: revert this PR. The previous >= MIN_HOST_SERVICE_VERSION floor returns; running host-services are again adopted as long as they clear it.

Follow-ups

• Drain-before-SIGTERM if respawn cadence becomes user-visible.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR pins desktop host-service adoption to the exact version bundled with the Electron build by importing the host-service package.json version into the coordinator, replaces semver floor logic with strict equality, exposes package.json via package exports, updates the host router to return the package.json version, and adds a rollout plan doc.

Changes

Version Pinning Strategy Implementation

Layer / File(s)	Summary
Strategy Plan and Scope apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md	Planning document specifies version pinning approach: coordinator uses a build-time BUNDLED_HOST_SERVICE_VERSION for exact equality checks and documents scope/out-of-scope items.
Coordinator Adoption Implementation apps/desktop/src/main/lib/host-service-coordinator.ts	Coordinator imports @superset/host-service/package.json version as BUNDLED_HOST_SERVICE_VERSION, removes semver-based floor check, and enforces strict equality (version === BUNDLED_HOST_SERVICE_VERSION) to decide adopt vs kill+respawn.
Host-Service Package Manifest packages/host-service/package.json	Package version bumped 0.1.0 → 0.8.0 and exports extended with ./package.json to allow direct JSON import of the version.
Host Router Version Source packages/host-service/src/trpc/router/host/host.ts	Replaces hardcoded version literal with import of @superset/host-service/package.json version and returns it unchanged from hostRouter.info.
Shared Host-Version Documentation packages/shared/src/host-version.ts	Clarifies comments about remote vs bundled host-service and updates the 0.8.0 history note concerning terminal/session changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I pin the version tight and snug,
No semver drift or stretchy rug.
If remote and bundled fail to match,
A hop, a respawn, a quick dispatch.
Bunny approves — exactness is snug.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feat(desktop): respawn host-service on every Electron auto-update' is partially related to the changeset but does not capture the main change. The core change is pinning host-service adoption to the bundled version (a strict equality check), not respawning on every auto-update. The actual respawn only occurs on version mismatch.	Consider a more precise title like 'feat(desktop): pin host-service adoption to bundled version' that clearly indicates the core mechanism (version pinning) rather than just the observable behavior.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description comprehensively covers the change's purpose, implementation, context, and testing requirements with detailed sections on why the change is safe and how it works.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync-service-electron-ver

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/desktop/plans/20260507-host-service-bundled-version-pin.md`:
- Around line 45-46: In the bullet under "**Strict equality vs `>=bundled`?**"
replace the phrase "hand-rolled newer daemon" with "newer host-service" so the
text reads that allowing `>=bundled` lets a hand-rolled newer host-service stick
around indefinitely; update any nearby mentions of "daemon" in that bullet to
"host-service" to avoid pty-daemon confusion (the lines containing the question
header and the offending phrase help locate the change).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1427c83c-62e4-4a3b-8a62-a4df46d36eec

📥 Commits

Reviewing files that changed from the base of the PR and between f4ae66e and dc00534.

📒 Files selected for processing (1)

• apps/desktop/plans/20260507-host-service-bundled-version-pin.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify “newer daemon” wording to avoid pty-daemon confusion.

At Line 45, “hand-rolled newer daemon” reads as pty-daemon, but this section is about host-service adoption. Please rename to “newer host-service” to prevent implementation ambiguity.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/desktop/plans/20260507-host-service-bundled-version-pin.md` around lines
45 - 46, In the bullet under "**Strict equality vs `>=bundled`?**" replace the
phrase "hand-rolled newer daemon" with "newer host-service" so the text reads
that allowing `>=bundled` lets a hand-rolled newer host-service stick around
indefinitely; update any nearby mentions of "daemon" in that bullet to
"host-service" to avoid pty-daemon confusion (the lines containing the question
header and the offending phrase help locate the change).

[Kitenite]

Section was removed when we committed to strict equality (the open-questions only retains the drain-before-SIGTERM bullet now). No-op.

[coderabbitai]

@Kitenite, understood — since the team committed to strict equality and the "Strict equality vs >=bundled?" bullet was dropped entirely, my concern is already moot. Thanks for the clarification!

[greptile-apps]

Greptile Summary

This docs-only PR adds an ExecPlan describing how to replace the >= MIN_HOST_SERVICE_VERSION floor check in host-service-coordinator.tryAdopt with a strict equality check against a build-time-injected BUNDLED_HOST_SERVICE_VERSION, so that auto-updated desktops always spawn the host-service binary that shipped with them.

• The plan accurately references the current code at host-service-coordinator.ts:289-308 (verified against source), correctly preserves MIN_HOST_SERVICE_VERSION for the renderer-side remote-host gate in useRemoteHostStatus.ts:91, and mirrors the EXPECTED_DAEMON_VERSION injection pattern from packages/host-service/src/daemon/expected-version.ts.
• The open questions section (strict equality vs >=bundled, drain-before-SIGTERM) are appropriate forward-looking notes; no behavior changes are included in this PR.

Confidence Score: 5/5

Docs-only plan file with no runtime changes; safe to merge.

The plan document accurately matches the current codebase — line numbers, logic, and existing patterns are all verified against live source files. No code is modified.

No files require special attention.

Important Files Changed

Filename	Overview
apps/desktop/plans/20260507-host-service-bundled-version-pin.md	New plan document for pinning host-service adoption to the bundled version; references accurate line numbers and existing patterns in the codebase.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Electron launch] --> B[tryAdopt reads manifest]
    B --> C[fetchHostVersion]
    C -->|version unknown| D[SIGTERM old pid + remove manifest]
    C -->|version returned| E{Current: version >= MIN_HOST_SERVICE_VERSION\nPlanned: version === BUNDLED_HOST_SERVICE_VERSION}
    E -->|check fails| D
    D --> F[Spawn fresh bundled host-service]
    E -->|check passes| G[Adopt running host-service]
    G --> H[startAdoptedLivenessCheck]

    subgraph "Unaffected by this change"
        I[Renderer remote-host gate\nuseRemoteHostStatus.ts:91\nstill uses MIN_HOST_SERVICE_VERSION]
        J[DaemonSupervisor\npty-daemon lifecycle\nunchanged]
    end

Loading

_{Reviews (1): Last reviewed commit: "docs(desktop): plan to pin host-service ..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 1 file

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md`:
- Around line 23-24: Update step 1 to reflect the actual implementation: state
that the desktop bundle uses a compile-time import of the shared constant
(HOST_SERVICE_VERSION from packages/shared/src/host-version.ts) rather than
build-time injection from packages/host-service/package.json; mention this
mirrors the EXPECTED_DAEMON_VERSION pattern only conceptually, and note that
BUNDLED_HOST_SERVICE_VERSION in the plan should be represented by the shared
HOST_SERVICE_VERSION and therefore must be bumped in packages/shared whenever
host-service is updated; also adjust the reference to
host-service-coordinator.ts (the code block around the HOST_SERVICE_VERSION
usage) so the plan and retrospective are consistent.

In `@apps/desktop/src/main/lib/host-service-coordinator.ts`:
- Line 8: Replace the brittle import of BUNDLED_HOST_SERVICE_VERSION from the
shared constant with a build-time JSON import of the actual host-service
package.json version (the EXPECTED_DAEMON_VERSION pattern): import the
package.json using TypeScript's with { type: "json" } syntax, read its "version"
as EXPECTED_DAEMON_VERSION (or similar), and then use that value in the existing
version equality check instead of BUNDLED_HOST_SERVICE_VERSION so the
coordinator compares the running host-service against the real package.json
version at build time.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 55e90b06-3da5-45ff-84eb-f93d99499932

📥 Commits

Reviewing files that changed from the base of the PR and between f83da66 and 416d2b8.

📒 Files selected for processing (4)

• apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md
• apps/desktop/src/main/lib/host-service-coordinator.ts
• packages/host-service/src/trpc/router/host/host.ts
• packages/shared/src/host-version.ts

✅ Files skipped from review due to trivial changes (2)

• packages/host-service/src/trpc/router/host/host.ts
• packages/shared/src/host-version.ts

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ✅ Neon database branch

Thank you for your contribution! 🎉

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md (1)

48-48: ⚡ Quick win

Avoid hard-coded source line references in a permanent done/ plan.

“Today line 304” will drift quickly and make this retrospective stale; referencing the coordinator behavior/function is more durable.

✏️ Suggested wording fix

-- **Drain before SIGTERM?** Today line 304 is a hard kill. If respawn cadence becomes user-visible (tunnel reconnect storms), add a short drain — stop accepting new connections, wait N seconds — before SIGTERM. Not needed in v1.
+- **Drain before SIGTERM?** Today the coordinator uses a hard kill in the mismatch path. If respawn cadence becomes user-visible (tunnel reconnect storms), add a short drain — stop accepting new connections, wait N seconds — before SIGTERM. Not needed in v1.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md` at line
48, Replace the hard-coded source line reference "Today line 304" with a durable
reference to the coordinator behavior or function that performs the hard kill
(e.g., mention the coordinator's respawn/termination handler or function name
that sends SIGTERM), so the note reads something like "Today the coordinator
issues a hard kill in its termination handler" or "the coordinator's respawn
logic currently performs a hard SIGTERM"; update the sentence to reference that
behavior instead of a line number to keep the plan accurate over time.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md`:
- Line 43: Update the sentence that currently reads “If you need to test against
a newer daemon in dev, point the desktop at a build that bundles it; don't
hand-roll the running process.” to use the term host-service instead of daemon;
i.e., change “newer daemon” to “newer host-service” so the line reads “If you
need to test against a newer host-service in dev, point the desktop at a build
that bundles it; don't hand-roll the running process.” This keeps terminology
consistent with the rest of the doc where pty-daemon is discussed separately.

---

Nitpick comments:
In `@apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md`:
- Line 48: Replace the hard-coded source line reference "Today line 304" with a
durable reference to the coordinator behavior or function that performs the hard
kill (e.g., mention the coordinator's respawn/termination handler or function
name that sends SIGTERM), so the note reads something like "Today the
coordinator issues a hard kill in its termination handler" or "the coordinator's
respawn logic currently performs a hard SIGTERM"; update the sentence to
reference that behavior instead of a line number to keep the plan accurate over
time.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0b384f46-ea59-4170-931b-4c62ebca01f1

📥 Commits

Reviewing files that changed from the base of the PR and between 6e2fea8 and beaa55b.

📒 Files selected for processing (5)

• apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md
• apps/desktop/src/main/lib/host-service-coordinator.ts
• packages/host-service/package.json
• packages/host-service/src/trpc/router/host/host.ts
• packages/shared/src/host-version.ts

✅ Files skipped from review due to trivial changes (3)

• packages/host-service/package.json
• packages/shared/src/host-version.ts
• packages/host-service/src/trpc/router/host/host.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/desktop/src/main/lib/host-service-coordinator.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use host-service wording instead of daemon here.

“newer daemon” is ambiguous in this doc because pty-daemon is discussed separately; this sentence is about host-service.

✏️ Suggested wording fix

-- **Dev: locally newer host-service** → killed and replaced with the bundled version. If you need to test against a newer daemon in dev, point the desktop at a build that bundles it; don't hand-roll the running process.
+- **Dev: locally newer host-service** → killed and replaced with the bundled version. If you need to test against a newer host-service in dev, point the desktop at a build that bundles it; don't hand-roll the running process.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- **Dev: locally newer host-service** → killed and replaced with the bundled version. If you need to test against a newer daemon in dev, point the desktop at a build that bundles it; don't hand-roll the running process.
	- **Dev: locally newer host-service** → killed and replaced with the bundled version. If you need to test against a newer host-service in dev, point the desktop at a build that bundles it; don't hand-roll the running process.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/desktop/plans/done/20260507-host-service-bundled-version-pin.md` at line
43, Update the sentence that currently reads “If you need to test against a
newer daemon in dev, point the desktop at a build that bundles it; don't
hand-roll the running process.” to use the term host-service instead of daemon;
i.e., change “newer daemon” to “newer host-service” so the line reads “If you
need to test against a newer host-service in dev, point the desktop at a build
that bundles it; don't hand-roll the running process.” This keeps terminology
consistent with the rest of the doc where pty-daemon is discussed separately.