Skip to content

fix(desktop): AppImage t3 serve stops cleanly under systemd - #40624

Merged
juliusmarminge merged 1 commit into
pingdotgg:mainfrom
RibatTRW:fm/t3code-shim-systemd-stop
Nov 22, 2026
Merged

juliusmarminge merged 1 commit into
pingdotgg:mainfrom
RibatTRW:fm/t3code-shim-systemd-stop

Conversation

@RibatTRW

@RibatTRW RibatTRW commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Stopping a systemd unit that runs the Linux AppImage's generated t3 serve can unmount the executable during shutdown and crash the server with SIGBUS. With KillMode=mixed, the launcher alone gets the initial SIGTERM and the stop instead reaches the timeout.

Change

Keep the AppImage mount alive through SIGTERM. The launcher forwards TERM and HUP to the CLI, waits for its exit, then unmounts the AppImage and returns the CLI's exit status. The mounter keeps its separate session for process-group signals.

Scope

Closes #40623. This covers the generated Linux AppImage CLI launcher and its tests. The process-group fix in #24421 is related.

Verification

Regenerated the launcher from the base and the fix and ran both against the released 0.1.11 AppImage on Linux x86_64, systemd 262 (262.1-1-arch), using isolated user units and scratch state.

Stop mode Before After
control-group SIGBUS core, 1.5 s 0.1 s, no core or leftover mount
mixed SIGKILL at the 30 s timeout, 30.2 s measured 0.1 s, no core or leftover mount

The server's shutdown status is 130 in these after runs. systemd reports result=exit-code with the test units' default exit-status settings. The after runs show that the process exits without a core or timeout and the mount is removed.

The launcher tests passed all 9 cases with Bash and dash. With the generated fix and released AppImage, terminal Ctrl-C and process-group SIGTERM each returned 130 in 0.1 s, with no core dump or mount left. t3 --version returned 0 and printed t3 v0.1.11. The scoped vp run check:changed checks passed. A rebuilt AppImage and other distributions or platforms were outside the runtime checks.

Terminal captures

Before, default control group

Before, mixed

After, default control group

After, mixed

Terminal recording

Idle gaps are shortened. The displayed stop times are measured.

05-stop-before-after.mp4

Signal order

Signal delivery and mount teardown before and after

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 4 of 4 scenarios run against a simulated AppImage in real systemd units
Scenario Result Live Evidence
Base launcher, systemd KillMode=control-group: stop reproduces the crash (mount vanishes while server shuts down) ✅ pass live systemd-stop-comparison.txt: 'mounter-got-signal-unmounts' then 'SIGBUS-mount-gone'
Base launcher, KillMode=mixed: stop hangs until systemd SIGKILLs ✅ pass live systemd-stop-comparison.txt: the server never received TERM; journal shows "stop-sigterm timed out. Killing."
Fixed launcher, KillMode=control-group: server gets TERM and exits with the mount still present ✅ pass live systemd-stop-comparison.txt: 'server-got-TERM' then 'server-exits-mount-still-present'; the mounter unmounts only after that; no SIGBUS and no timeout
Fixed launcher, KillMode=mixed: TERM is forwarded to the server, so the stop is prompt ✅ pass live systemd-stop-comparison.txt: 'server-got-TERM' then 'server-exits-mount-still-present'; no 'stop-sigterm timed out' in the journal
  • systemd-run --user --collect -p KillMode=control-group, base launcher
  • systemd-run --user --collect -p KillMode=mixed, base launcher
  • systemd-run --user --collect -p KillMode=control-group, target launcher
  • systemd-run --user --collect -p KillMode=mixed, target launcher
✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 info
  • ℹ️ apps/desktop/src/app/DesktopCliShim.ts - Lint and format checks were not run. vp is not on PATH and node_modules has no oxlint or oxfmt binaries (dependencies likely not installed in this worktree). I did not search the machine for the tool.
✅ **Push** - passed

✅ No issues found.

Produced by AI agents on behalf of the account owner. Claude Fable 5.2 in Claude Code implemented the fix and captured the runtime evidence. GPT-6.2 Sol in Codex verified and prepared the submission. Both ran through T3 Code.

The AppImage t3 launcher could not be stopped as a systemd service.
With the default KillMode=control-group, the stop signal reached the
AppImage mount helper with the server, the mount went away while the
server was still shutting down, and the server died with SIGBUS. With
KillMode=mixed, the launcher shell never passed SIGTERM on, so the stop
timed out and everything was SIGKILLed, leaving a dead mount.

The launcher now starts the mount helper with SIGTERM ignored and
unmounts it itself once the server has exited, and it runs the server
in the background so it can forward TERM and HUP, keeping stdin and the
server's exit status.
@github-actions github-actions Bot added vouch:unvouched Author is not yet trusted in the VOUCHED list. size:S 10-29 changed lines (additions + deletions). labels Nov 21, 2026
@juliusmarminge juliusmarminge added the takeover:in-progress A takeover lead is working on this PR label Nov 21, 2026
@coderabbitai

coderabbitai Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The AppImage launcher now forwards termination signals to the CLI, waits for its exit status, and updates mount cleanup. Tests cover signal targets, server shutdown and unmount order, and invocation with stdin closed.

Changes: AppImage launcher signal handling

Layer / File(s) Summary
Signal forwarding, cleanup, and validation
apps/desktop/src/app/DesktopCliShim.ts, apps/desktop/src/app/DesktopCliShim.test.ts
The launcher’s mounter ignores TERM. Its exit trap lazily unmounts before signaling the mounter and removing the temporary directory. The shell starts the CLI with inherited stdin, forwards TERM and HUP, ignores INT, retries interrupted waits, and exits with the CLI’s status. Tests cover signal targets, server exit status, unmount timing, and closed-stdin status.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant systemd
  participant Launcher as AppImage launcher shell
  participant CLI as CLI process
  participant Mounter as AppImage mounter
  systemd->>Launcher: Send SIGTERM
  Launcher->>CLI: Forward SIGTERM
  CLI-->>Launcher: Exit with status
  Launcher->>Mounter: Lazily unmount, then signal mounter
Loading

Suggested reviewers: juliusmarminge

Merge Risk: Minimal · up to e4536

The AppImage t3 launcher now forwards stop signals to the server, waits for it to exit, then unmounts, which fixes the crash or timeout under systemd. No concrete merge-blocking defect was established. The remaining unknown is how the real FUSE runtime handles an ignored TERM, which the fake mounter in the PR's tests did not exercise.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the AppImage t3 serve shutdown fix under systemd, which matches the changeset: the shim ignores TERM while the mounter runs, unmounts on EXIT, and forwards TERM/HUP to the CLI so the s…
Linked Issues check Passed Issue #40623 requires that the AppImage launcher let the server shut down while the mount exists, and release the mount after the server exits, under both KillMode=control-group and KillMode=mixed.

C…
Out of Scope Changes check Passed The PR changes the generated AppImage shell shim in DesktopCliShim.ts and its test file DesktopCliShim.test.ts. The shim changes (TERM ignore for the mounter, EXIT-trap unmount, background CLI with fo…
Description check Passed The description follows the repository template closely. It has the Problem, Change, Scope, and Verification sections, and the title-style context matches the template. The Problem section states the …
Full details: Title check

Explanation

The title names the AppImage t3 serve shutdown fix under systemd, which matches the changeset: the shim ignores TERM while the mounter runs, unmounts on EXIT, and forwards TERM/HUP to the CLI so the server stops cleanly. It follows the conventional commit format and is specific, though it omits the unmount and signal-forwarding details.

Full details: Linked Issues check

Explanation

Issue #40623 requires that the AppImage launcher let the server shut down while the mount exists, and release the mount after the server exits, under both KillMode=control-group and KillMode=mixed.

Code at head (apps/desktop/src/app/DesktopCliShim.ts, renderCliShim, appimage branch):

  • The shell runs trap '' TERM before starting the mounter with setsid. The mounter inherits the ignored TERM, so a control-group stop does not unmount it under the server.
  • The CLI is started as a background child, not with exec. The shell traps TERM and forwards it with kill -TERM "$cli". This covers KillMode=mixed, where systemd signals only the launcher.
  • The shell forwards HUP and ignores INT. It waits for the CLI in a loop, so an interrupted wait does not end the launcher early.
  • The EXIT trap runs fusermount3 -uz or fusermount -uz on the mount, then sends HUP to the mounter and removes the temp dir. The unmount runs only after the CLI exits.

The author's live systemd runs (summary of systemd-stop-comparison.txt) show the base launcher failing and the target launcher stopping cleanly under both modes. The fake mounter did not model FUSE, so the unmount step was not exercised. The static code path is consistent with the requirement, but the unmount behavior itself is not verified by the evidence. The issue does not request automated tests. The PR updates DesktopCliShim.test.ts for the new output, but the Vitest suite was not run.

Full details: Out of Scope Changes check

Explanation

The PR changes the generated AppImage shell shim in DesktopCliShim.ts and its test file DesktopCliShim.test.ts. The shim changes (TERM ignore for the mounter, EXIT-trap unmount, background CLI with forwarded TERM/HUP, INT ignore, wait loop, exit-status passthrough, stdin on fd 9) each map to the stop behavior described in #40623. The test changes update assertions for the new shim output and cover the signal targets. The Windows and direct branches of renderCliShim are unchanged by the diff summary. No unrelated change was found in the reviewed evidence.

Full details: Description check

Explanation

The description follows the repository template closely. It has the Problem, Change, Scope, and Verification sections, and the title-style context matches the template. The Problem section states the systemd KillMode interaction that causes SIGBUS and timeouts. The Change section explains the TERM and HUP forwarding, the wait for CLI exit, and the unmount order. The Scope section links issue #40623 and names the affected launcher and tests. The Verification section gives specific runtime results for the base and fixed launchers under both KillMode settings, a test pass count for Bash and dash, and lists what was not checked, including a rebuilt AppImage and other distributions. Terminal captures and a recording are embedded, and the agent and model are named at the end, as the template asks. Minor gaps: the description does not restate a conventional commit title in the body, and the Verification section reports that the Vitest suite and lint were not run in the sense of the repo-wide checks, which is acceptable under the template. The 'Pipeline' attestation block is extra material from the tooling and does not affect compliance.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 63fa4c8 and e4536ca.

Files selected for processing: 2

  • apps/desktop/src/app/DesktopCliShim.test.ts
  • apps/desktop/src/app/DesktopCliShim.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@juliusmarminge

Copy link
Copy Markdown
Member

Evidence

Built and opened each real AppImage on Linux x86_64 with systemd 255 and FUSE. Started its generated launcher in isolated user units with fresh T3 homes; waited for server readiness, then stopped it under control-group and mixed kill modes with TimeoutStopSec=30s.

Before After
63fa4c8 e4536ca
Shutdown recording Shutdown recording
control-group: Bus error (core dumped). mixed: 30.19s stop, Result=timeout, SIGKILL, one remaining mount. control-group: 2.05s. mixed: 1.05s. Neither logged a core dump or stop timeout; both left zero mounts.
Transcript Transcript

Reproduction driver · Recording driver · Packaged desktop launcher installation

Caveat: head still exits with status 130, so systemd reports Result=exit-code and a failed unit. Mixed mode also logs immediate SIGKILL cleanup of residual helpers after server shutdown reconciliation. The demonstrated improvement is removal of the SIGBUS, 30-second timeout, and leftover mount.

Not shown:

  • A fully successful systemd unit result and graceful exit of every helper were not demonstrated: head returned status 130 in both modes, and mixed mode still logged residual-helper SIGKILL cleanup.

@juliusmarminge juliusmarminge added takeover:ready Takeover done; auto-lands when gates pass and removed takeover:in-progress A takeover lead is working on this PR labels Nov 22, 2026
@juliusmarminge
juliusmarminge merged commit 67bf1e6 into pingdotgg:main Nov 22, 2026
28 checks passed
@juliusmarminge juliusmarminge removed the takeover:ready Takeover done; auto-lands when gates pass label Nov 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:S 10-29 changed lines (additions + deletions). vouch:unvouched Author is not yet trusted in the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Linux AppImage t3 serve crashes or times out on systemctl stop

2 participants