Skip to content

feat(desktop): run a managed marker's quitCommand as the app quits - #16307

Closed
buluoray wants to merge 3 commits into
mainfrom
feat/managed-quit-command
Closed

buluoray wants to merge 3 commits into
mainfrom
feat/managed-quit-command

Conversation

@buluoray

@buluoray buluoray commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let a packager that owns the desktop app's install run its own upkeep command once the app has quit, instead of while it is still running.

A packager that installs updates in the background and launches the app through a stable symlink has to move that symlink to the new version. If it does that while the app is open, the running app keeps resolving files through the moved symlink, loads the next version's files mid-session and crashes. The packager can defer the move, but the app gives it no signal for when it has exited, so the deferred move only happens on some later, unrelated trigger.

Why it matters

Every background update that lands while the app is open risks a crash on that packager's installs. Without an exit signal the packager has two bad choices: move the link under the running app (crash), or leave it on the old version until something else happens to run (stale version, and a dead launcher once the old version is cleaned up).

Not a goal

  • Changing what the default (self-updating) build does: no marker, no change.
  • Running the command when the app crashes or is force-killed.
  • Moving the launch-path logic into the app itself; the packager's command decides what to do.

What changed (motivation → approach → change)

  • Symptom: a packager's background update moves the launch symlink under the open app, which then crashes.
  • Approach: give the marker an exit hook rather than teaching the app about any one packager's layout. will-quit is the point where every window has closed and the quit can no longer be cancelled, so a vetoed quit never runs the command. The command is started detached and not awaited, so quit never waits on a package manager, and it gets the app's pid so it can wait for the exit itself.
  • Change:
    • website/electron/auto-update.js: the marker reader parses an optional quitCommand (trimmed, capped at 512 like the other commands, refused with the rest of the metadata when the marker is rewritable).
    • website/electron/runtime/update/managed-lane.js: on the managed lane, app.once("will-quit") (skipped while an update apply is in flight) spawns it with the pinned shell, cwd=/, the constructed environment plus KIROCREW_QUITTING_PID, detached, stdio: "ignore", then unref(). A quit that applies an update ends with app.exit(), which skips will-quit, so the two never both run.
    • packaging/build-desktop.sh: the baked-marker validator accepts quitCommand with the same cap.
    • docs/build/desktop-app.md: documents the field and when it does and does not run.

Backwards compatibility

Compatible: the field is optional; a marker without it behaves exactly as before, and a bare marker (no updateCommand) still runs nothing.

Removes nothing: the change only adds an optional field and an optional quit hook.

Tests

  • website/electron/test/auto-update.test.js
    • managed quitCommand: started detached on will-quit with the quitting pid: exactly one will-quit hook, nothing runs before quit, then the command runs detached with stdio: "ignore", cwd=/, the narrowed PATH, no HOME, KIROCREW_QUITTING_PID = the app pid, and is unref'd. Fails if the hook is not registered or detached is false.
    • managed quitCommand: not started while an apply is still running: an in-flight updateCommand suppresses the quit command. Fails without the managedInstalling guard.
    • managed quitCommand: absent -> no will-quit hook.
    • managed quitCommand: a marker with no updateCommand runs nothing at quit.
    • The reader tests now expect quitCommand in the parsed shape, the cap test covers it, and the rewritable-marker test shows an attacker's quitCommand is dropped with the rest.
  • test/test_build_desktop_managed_marker.py: the valid fixture carries quitCommand, an over-cap quitCommand fails the build, and the validator's cap literal is pinned to QUIT_COMMAND_MAX_CHARS.
  • npm test --prefix website/electron: 2401 passed. test_build_desktop_managed_marker.py: 19 passed.

Manual verification

Real Electron 43.2.0 on Linux (unpackaged, --ozone-platform=headless), driving initAutoUpdate with the real app and a managed marker whose quitCommand waits for KIROCREW_QUITTING_PID to exit and then writes a sentinel:

  • app.quit(): the sentinel appeared after Electron exited, naming the app's pid, with HOME unset. So will-quit fired, the detached child outlived the app, and it waited for the exit.
  • app.exit(0): no sentinel. The update-applying quit path does not run the command.

Not run: a packaged macOS or Windows build. The lane runs the same code unpackaged (the marker gate precedes the isPackaged check), so packaging should not change these results, but no packaged build has been checked.

Related Issues

N/A

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

A package manager that installs the next version in the background
cannot switch the app's launch path over while the running app still
resolves its own files through that path: the open app then loads the
next version's files and crashes. It has to defer the switch until the
app has exited, and nothing tells it when that is.

The EXTERNALLY-MANAGED marker gains an optional quitCommand. On the
managed lane it is started on will-quit, detached and never awaited,
under the same constructed environment as the other marker commands,
with the quitting app's pid in KIROCREW_QUITTING_PID so it can wait for
the exit. A cancelled quit, a quit that applies an update (app.exit)
and a crash do not run it. build-desktop.sh accepts the field with the
same 512-character cap as the other commands.
@buluoray
buluoray requested a review from a team October 2, 2026 23:16
@buluoray
buluoray requested a review from a team as a code owner October 2, 2026 23:16
@buluoray
buluoray requested a review from bolichen97 October 2, 2026 23:16
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 704dcfacc06245fb055efbafcc71671b613ab6a0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 704dcfa

Description read

[DESCRIPTION-READ] 5fe92ffa4af45a7eeeef2adb74163ec58856357f850a44672a0b638510e874e7

That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 704dcfacc06245fb055efbafcc71671b613ab6a0 — 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

No packaged macOS or Windows build has run the quit hook — the author verified unpackaged Linux only; confirm one packaged platform before relying on it.

Not justified as shipped

  • Item 4 — undeclared: a failed explicit apply now clears managedInstalling ("let the poll resume and the quit command run again"), resuming the background poll — a behavior change on existing managed installs the description's "What changed" and test list never mention (it ships as the branch's second commit, with its own test).

What this change ships

Inventory (6 items) — 5 justified

Intent: let a packager run its own upkeep command once the desktop app has quit, so a background update's launch-path switch never lands under the running app — an ADDITION. (The diff artifact also carries ~130 files of base-side commits already on main — #16190, #16207, #15731 among them — from a stale fork point; the inventory covers only the PR's own change.)

  1. A trusted marker can name a quitCommand the app starts detached on will-quit — justified
  2. That command receives the quitting app's pid as KIROCREW_QUITTING_PID — justified
  3. The quit command is skipped while an apply is in flight, and never runs on the apply-and-relaunch quit (app.exit) — justified
  4. A failed explicit apply no longer permanently stops the background update poll (or the quit command) — undeclared: not in the description
  5. build-desktop.sh accepts a baked quitCommand, same 512 cap, pinned to the reader's constant — justified
  6. desktop-app.md documents the field and the wait-for-pid contract the command must follow — justified

[FIRST-PRINCIPLES-REVIEWED] 704dcfa

Description read

[DESCRIPTION-READ] d0f25d6056e9cc7d5c424baf4693418aaa045a5050dac51951051c36b9980d45

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 704dcfacc06245fb055efbafcc71671b613ab6a0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify a packaged Windows/macOS build once: the detached child outliving the app was only exercised unpackaged on Linux, as the author discloses.

[DESIGN-REVIEWED] 704dcfa

Description read

[DESCRIPTION-READ] c2a03fa229d918090c2b96dd4fe57ee76b407654d798474ebd403dd615347bb5

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 704dcfacc06245fb055efbafcc71671b613ab6a0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 704dcfa

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 704dcfacc06245fb055efbafcc71671b613ab6a0: <one-sentence reason>

@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 Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 704dcfacc06245fb055efbafcc71671b613ab6a0 — this comment is updated in place on each push.

Review details

A timed-out apply is recorded as finished, releasing the in-flight interlock while the package manager may still be running.

FINDING — website/electron/runtime/update/managed-lane.js:420 — runUpdateCommand()'s timeout kill resolves {code: 1, failed: true} (close fires with code === null, signal === "SIGTERM"), and managedInstall destructures only { code }, so the new managedInstalling = false runs for an apply that was killed rather than completed — the SIGTERM reaches only the /bin/sh -c wrapper, so a compound or forking updateCommand keeps running while the poll resumes shelling checkCommand and the next will-quit starts the detached quitCommand past its only guard → Fix: const { code, failed } = await runUpdateCommand(); and clear the flag only when !failed, leaving a kill/timeout holding the interlock as before.

[OPUS-REVIEWED] 704dcfa

Verdict parsed from the review's SHA-scoped output markers for commit 704dcfacc06245fb055efbafcc71671b613ab6a0.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 704dcfacc06245fb055efbafcc71671b613ab6a0: <one-sentence reason>

will-quit can still be cancelled by another handler, fires for a
relaunching quit, and runs before the app's own children have exited,
so the earlier claim that a vetoed quit never runs the command was
wrong. The docs now make waiting on KIROCREW_QUITTING_PID a
requirement, and the lane skips the quit command while an update apply
is still in flight. The env test asserts the narrowed PATH by property
so it also holds on Windows.
@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 labels Oct 2, 2026
@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Dispositions for the reviews on c2c5615255, addressed in cb0cfb1a11.

Design Review (BLOCK)

  • will-quit "can no longer be cancelled": correct, that was wrong. Electron documents preventDefault() on will-quit. Nothing in this app cancels it (main.js only unregisters the hotkey there), but the comment and the doc no longer claim it. The doc now makes waiting for KIROCREW_QUITTING_PID a requirement (Watch item), and says the command must bound that wait and re-check that no instance is running before acting. That is what covers a cancelled will-quit, a relaunching quit and children still exiting.
  • Unverified at runtime: ran it on real Electron 43.2.0 (Linux, unpackaged, headless). With a quitCommand that waits for the pid and then writes a sentinel, app.quit() produced the sentinel after Electron exited (pid matched, HOME unset), and app.exit(0) produced none. The managed lane is chosen before the isPackaged gate, so this is the same code path a packaged build runs. A packaged macOS run has not been done; that is recorded in the PR description.

Opus findings

  1. Runs beside an in-flight apply: fixed. runQuitCommand returns early while managedInstalling, pinned by managed quitCommand: not started while an apply is still running. Gating on the gateway stop settling would need plumbing from main.js; the documented contract (wait for the app pid, re-check no instance is running) is what a command relies on instead.
  2. GPU-crash relaunch quits through will-quit: accepted as documented behaviour. The doc says it fires for a relaunching quit, and a correct command re-checks for a running instance before acting. No suppression flag added.
  3. POSIX-only PATH assertion: fixed. It now asserts the property (no home directory in PATH), as the sibling env test does.

CI on c2c5615255

  • Frontend Tests (1) failed in SessionActionsMenu.duplicate.test.tsx, the same failure as revert: transcript scrolls under the composer glass again (#15820) #16291, which does not touch it. Frontend Tests (2) failed in hoverVariantPolicy.test.ts (components/WelcomeView.tsx). Both are outside this diff, which only touches website/electron, packaging/ and docs/.
  • Build Windows Installer (x64) failed with "Windows installation exceeded the 120-second ceiling". The default build carries no marker, so this code path is not reached there.

@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 Oct 3, 2026
…ails

A non-zero updateCommand exit left managedInstalling set, which silently
suppressed both the background poll and the quit command for the rest of
the process. Reset it on the failure branch and pin it with a test.
@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 (BLOCKING) — failed installs permanently suppress the quit command: fixed in 704dcfacc0.

Confirmed in source: managedInstall() set managedInstalling = true and the non-zero-exit branch returned without clearing it, so both the poll (:434) and runQuitCommand (:254) stayed suppressed for the rest of the process. The failure branch now resets the flag. The quit-time apply path (managedInstallOnQuit) always ends in app.exit(0), so it does not need the same reset.

New test managed quitCommand: a FAILED apply does not suppress it at the next quit drives a code: 1 apply then will-quit and asserts the quit command runs. Mutation check: deleting the reset line turns that test red; restoring it turns it green.

@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 labels Oct 3, 2026
@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

Closing: the premise does not hold. A process launched through a symlinked bundle path resolves execPath/resourcesPath/getAppPath to the concrete version directory at startup, so repointing the link while the app runs does not hand it new files. The observed crash reproduces when the running version's directory is deleted, not when the link is repointed, so deferring work to will-quit does not address it. The fix belongs in the packager's retention of the running version.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant