Skip to content

fix: warn when desktop finds a stale bundled gateway - #13664

Merged
bolichen97 merged 2 commits into
kirodotdev:mainfrom
pstarkgit:fix/restart-stale-local-gateway
Sep 29, 2026
Merged

bolichen97 merged 2 commits into
kirodotdev:mainfrom
pstarkgit:fix/restart-stale-local-gateway

Conversation

@pstarkgit

@pstarkgit pstarkgit commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Warn desktop users before reusing an older gateway from the currently installed app bundle.

After a desktop update, a detached gateway from the previous bundle can keep listening on the usual port. The updated desktop otherwise reuses that gateway, so chats continue running against code and prompts from the previous installation.

Why it matters

The dashboard can look connected while updated desktop features are unavailable or incompatible with the older gateway. Users need a clear warning and recovery instructions before choosing whether to continue.

Not a goal

  • Automatically restarting the stale gateway. Current token hardening intentionally refuses to issue a local token before this desktop instance has started and proven ownership of the gateway, so startup cannot authenticate a restart request safely.
  • Force-stopping the listener or adding a new backend restart-authentication path.
  • Changing behavior for remote tunnels, separate CLI installs, unknown owners, same or newer gateway versions, Windows, or moved AppImages.

What changed (motivation → approach → change)

A stale bundled gateway can survive an app replacement, but ownership and path checks must remain strict to avoid acting on a tunnel or separate installation. The Electron supervisor now detects the condition only when one local listener is positively attributed to Kiro Crew, its command path is beneath the current packaged backend-dist, and its same-family version is older than the desktop app.

When detected, the desktop shows a native Continue/Quit warning before reuse. It names both versions, explains that updated features may be unavailable, and gives the existing kirocrew stop --port <port> recovery command. Service-classified listeners get an additional conditional service-recovery hint. No restart request, token mint, polling loop, forced stop, or replacement spawn is added.

The desktop lifecycle documentation and focused regressions now describe and enforce detection-and-warning behavior.

Backwards compatibility

Compatible: gateways that do not satisfy every stale bundled-gateway check retain the existing reuse behavior, and Continue still adopts the detected gateway.

Tests

  • Full Electron suite: 2,253 passed, 3 skipped, 0 failed.
  • Focused stale detection, warning, and port-owner classification regressions passed.
  • ./scripts/docs-lint.sh, Node syntax checks, and git diff --check passed.

Manual verification

The refreshed macOS captures show the base and service-classified warning states produced by the current dialog strings. A release-signed update remains release validation, not a claim of this PR.

Screenshots / video

Native macOS warning for an older bundled gateway

Representative macOS service-owner warning for an older bundled gateway

Related Issues

No originating issue was filed; this PR follows a locally reproduced desktop update failure. #13826 explains the token-hardening boundary that makes automatic startup restart intentionally out of scope; this PR does not reopen or modify it.

Pattern harvest

Rule candidate: review-prompt
Pattern: Detect version-skewed companion processes using strict owner, path, product, and version evidence before warning; do not claim automatic recovery without a usable authenticated path.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

N/A — the repository template contains no final CLA text to acknowledge.

@pstarkgit
pstarkgit requested review from a team and iamwhatever September 25, 2026 03:23
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from a2c9d4f to bc55ca8 Compare September 25, 2026 03:23
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of e9897a84fd2b4f27e1fa82f734c380ff5784e3f8 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

Recovery command must be transcribed from a dismissable dialog, and both Enter and Esc take the degraded Continue path the copy warns against.

Watch

  • The fix the copy recommends ("To finish the update, quit Kiro Crew… kirocrew stop --port 5489") lives only in a native dialog with no copy/select affordance; clicking "Quit" — the very step instructed — dismisses it, so the user must memorize command and port first. Rare event × moderate friction × recurs each launch (which also mitigates it). Smallest fix: add "The warning will appear again if the old gateway is still running." to detail, or a third "Copy command and quit" button writing to the clipboard.
  • defaultId: 0, cancelId: 0 both map to "Continue with existing gateway", so Enter and Esc land a habituated user in exactly the degraded state the dialog exists to warn about, silently. Verify this fail-open default is intended; if so it's defensible, but Esc-as-Continue deserves a stated reason.
  • Attachment-01 (service-owner capture) renders "Run this command in Terminal: kirocrew stop --port 5489" on one line, but the committed string forces \n after "Terminal:" (attachment-02 shows the break). That capture likely predates the current string — refresh it so the committed evidence matches the shipped dialog.

Suggestions

  • In detail in gateway-supervisor.js, number the recovery steps ("1. Quit Kiro Crew 2. Run… 3. Reopen…") — four imperative prose lines in a row scan poorly in a native alert.

[UX-REVIEWED] e9897a8

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed e9897a84fd2b4f27e1fa82f734c380ff5784e3f8 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- website/electron/gateway-supervisor.js:737 -- "runLocalGateway" skips the promised warning in client-only mode when reusing a stale bundled gateway -> Fix: remove this gate from bundledGateway.
[GPT-REVIEWED] e9897a8

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of e9897a84fd2b4f27e1fa82f734c380ff5784e3f8 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify once on a real signed update that a detached old-bundle listener actually matches the backend-dist path predicate — the captures show dialog strings, not detection.

[DESIGN-REVIEWED] e9897a8

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of e9897a84fd2b4f27e1fa82f734c380ff5784e3f8 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify on one real macOS update that ps reports the listener's command under backend-dist — the detection premise is only exercised through mocked execFile in tests; a miss fails open to today's silent reuse.

What this change ships

Inventory (8 items) — 8 justified

Intent: warn desktop users before reusing an older gateway left behind by the previous app bundle — a FIX for a locally reproduced, base-code-verifiable silent reuse (base decideGatewayAction reuses any same-family gateway unconditionally, instance-guard.js:126).

  1. Desktop shows a Continue/Quit warning before reusing an older bundled gateway — justified
  2. Choosing Quit aborts startup instead of adopting the stale gateway — justified
  3. Service-owned listeners get one extra recovery line in the warning — justified
  4. Warning fires only for a sole local listener proven under the current bundle's backend-dist — justified
  5. warn-stale action and bundledGateway input on decideGatewayAction — justified
  6. Lifecycle docs describe the new warn-before-reuse step — justified
  7. Two macOS captures committed under temp-screenshots/ — justified
  8. localOwner doc union now names the existing service owner — justified

Notes checked: bundledGateway/warn-stale each have exactly 1 consumer (resolveGatewayConflict), singular forms; isNewerVersion already exported from auto-update.js; temp-screenshots/ is the repo's committed-evidence convention read by ux-review.yml; the deeper cause (restarting the stale gateway) is declared out of scope with a named constraint (token hardening, #13826), satisfying the symptom-level disclosure requirement; no pin deleted, no default changed — Continue (reuse) stays the default path.

[FIRST-PRINCIPLES-REVIEWED] e9897a8

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed e9897a84fd2b4f27e1fa82f734c380ff5784e3f8 via the fork AI-review pipeline; updated in place on each push.

Review details

Nothing blocks — but the new stale-gateway dialog gives instructions that are wrong for the installs that reach it.

FINDING — website/electron/gateway-supervisor.js:772 — const stopGateway = `Run this command in Terminal:\nkirocrew stop --port ${PORT}` makes a bare kirocrew the dialog's only remedy, yet warn-stale is reachable only when isCurrentBundleGateway() proved the listener's argv starts with <resourcesPath>/backend-dist/ — i.e. the gateway came from the app bundle, and the DMG plants no PATH shim while deb/rpm install /usr/bin/kirocrew-desktop (website/electron/package.json linux.executableName); only install.sh:632 creates ~/.local/bin/kirocrew, so an app-only user who quits as instructed gets command not found and cannot finish the update (the pre-existing port-conflict dialog at gateway-supervisor.js:1969 offers the same command only as an "also" beside a real Force-stop button) → Fix: name the bundled launcher absolutely — path.join(processObj.resourcesPath, "backend-dist", "kirocrew-backend", "bin", "kirocrew") — in the command text, since that is the path isCurrentBundleGateway just proved exists.

FINDING — website/electron/gateway-supervisor.js:779 — detail: `…To finish the update, quit Kiro Crew.\n${recovery}\nThen reopen Kiro Crew.` hardcodes the production display name, so on the KiroCrew Nightly install (build-desktop.sh:1332 sets productName=KiroCrew Nightly, CFBundleDisplayName=Kiro Crew Nightly) a nightly user whose own bundled gateway is older is told to quit and reopen "Kiro Crew" — the other, separately installed app that shares the bundle id, data home and port, which is exactly why FAMILY_META[...].displayName exists and why every dialog in runtime/gateway/family-takeover.js interpolates it → Fix: interpolate app.getName() (or FAMILY_META[identityFamily(app.getVersion())].displayName) in place of the two literal Kiro Crew occurrences.

[OPUS-REVIEWED] e9897a8

@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from bc55ca8 to 4ba6eb2 Compare September 25, 2026 04:56
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from 4ba6eb2 to 854a4f7 Compare September 25, 2026 05:17
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from 854a4f7 to a5b61fa Compare September 25, 2026 05:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from f658b25 to e2c1293 Compare September 25, 2026 18:34
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from e2c1293 to c2aeac3 Compare September 25, 2026 19:12
@pstarkgit

Copy link
Copy Markdown
Contributor Author

Maintainer action needed for commit c2aeac32b25ec0ce51dbae18a4221eaa7812ff4a: GitHub is holding the fork workflows in action_required. Please approve those workflows on the PR's Checks/Actions page so CI and the review lanes can run. The branch is rebased on current upstream main; the full local Electron suite passed (2,133 passed, 3 skipped), docs checks passed, and the PR body includes four native macOS captures. I will handle any findings once the checks run.

@pstarkgit

Copy link
Copy Markdown
Contributor Author

Current head c2aeac32b25ec0ce51dbae18a4221eaa7812ff4a needs an upstream maintainer rerun. The fork GPT, Opus, internal-content, and security-scope jobs failed before a verdict because GitHub returned API rate limit exceeded for installation while they resolved the PR. Resolve desktop matrix failed on the same installation rate limit. My targeted gh run rerun --failed was denied with Must have admin rights to Repository.

Please rerun the failed jobs after the installation rate limit resets:

  • Build run 36178248199 (Resolve desktop matrix)
  • Fork GPT run 36179350811
  • Fork Opus run 36179350956
  • Fork internal-content scan run 36179350944
  • Fork security-scope run 36179350997

CI run 36178248303 has one failed job, Backend Lint & Type Check (3.12): scripts/check_python_audit.py reports audit output carried a dependency without a name and version. The same error occurred on the previous PR head. This is outside the desktop files changed here; please advise whether a base-branch audit fix is already in flight or rerun that failed job after the audit environment is repaired.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 26, 2026
An app replacement can leave an older bundled gateway detached from the
Electron process. The next launch then adopts that same-family gateway
and keeps running old code against the new bundle.

Identify the exact local bundled listener before requesting its own
authenticated, graceful restart. Wait for the installed version and keep
remote, separately installed, and ambiguous gateways on the reuse path.
@pstarkgit pstarkgit changed the title fix: restart stale bundled gateway after desktop update fix: warn when desktop finds a stale bundled gateway Sep 28, 2026
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from c2aeac3 to 86aee83 Compare September 28, 2026 18:43
@pstarkgit
pstarkgit requested a review from a team as a code owner September 28, 2026 18:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 28, 2026
Detect a stale gateway from the current desktop bundle and warn before reuse. Remove the non-functional authenticated restart path so startup does not promise recovery it cannot perform.
@pstarkgit
pstarkgit force-pushed the fix/restart-stale-local-gateway branch from 86aee83 to e9897a8 Compare September 28, 2026 21:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed on behalf of the maintainers (readiness sweep 2026-09-29): readiness passed, the required PR Readiness check is green on this head, no live CHANGES_REQUESTED, no open blocking review threads; where the PR's files also moved on main since its merge-base, the PR's own tests were run on the main+PR merge tree and passed. Approving and squash-merging.

@bolichen97
bolichen97 merged commit 3ad829b into kirodotdev:main Sep 29, 2026
103 of 109 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants