Sign up
View stargazers13Sign up

[Bug]: Quitting the desktop app leaves its server running, so the next launch cannot start one#22983

opened4d agobyVvifar

What happened

On macOS with the desktop app and Local environment enabled, quitting the app with Command-Q closes the window but leaves the desktop's own server running:

  • The surviving server has parent PID 1 (it was reparented to launchd).
  • It still holds ~/.t3/userdata/server-owner.sqlite open.
  • It has no listening TCP port.
  • Reopening T3 Code shows "This T3 home is unavailable" and quits again.
  • The background service was already uninstalled, so it was not the owner of the data directory.
  • One extra SIGTERM to the survivor released the ownership lock, and local startup worked again.

The result is that quitting and reopening the app does not work: the app's own leftover server holds the T3 home's single-writer lock, and the app has no way to reclaim it.

Expected behavior

  • Quitting the desktop app stops the server it started, and the server's managed child processes, before the app exits.
  • On startup the app checks who owns the T3 home before starting a server:
    • a healthy server for the same home is not started a second time: the app reports the owner and stays open, and that server is used through the documented pairing setup (turn off Settings > Connections > Local environment, then pair),
    • a server the app can verify is its own stranded leftover is recovered,
    • anything else is left alone and reported.
  • The data directory, projects, history, and the Local environment setting are preserved; nothing is reset.

Note added after review (2026-10-22)

The first bullet originally read "a healthy server for the same home is reused rather than started a second time". It is narrowed here because the desktop cannot take a running server over: the renderer's local-environment session is derived from the desktop's per-launch bootstrap secret, so a later launch cannot authenticate to a server an earlier launch started. Upstream closed the request for the desktop to connect to a running service on its own as a feature rather than a defect (#20250, closed as not planned), and the wording of the ownership dialog is tracked in #22820.

What the fix does deliver is the part that matters for this bug: the app never creates a second writer for the same home, it reports the owner instead of failing with "This T3 home is unavailable" and quitting, and it keeps the app open so the documented way out (turn off Settings > Connections > Local environment, then pair) is reachable.

Actual behavior

apps/desktop/src/app/DesktopApp.ts stops the pool with a 5 s budget, while the backend's own force-stop deadline in apps/desktop/src/backend/DesktopBackendManager.ts (DEFAULT_BACKEND_TERMINATE_GRACE) is also 5 s:

ts
1// apps/desktop/src/app/DesktopApp.ts
2(instance) => instance.stop({ timeout: Duration.seconds(5) }),
ts
1// apps/desktop/src/backend/DesktopBackendManager.ts
2const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(5);
3// used as the spawn command's `forceKillAfter`

The outer budget is not larger than the inner one, so the desktop can give up waiting before its own escalation to SIGKILL has run. When that happens the desktop exits while the server is still alive, and stop() never escalates itself: closeRun returns false on timeout and stop simply returns, leaving the run and the process in place.

Two more gaps make the leftover unrecoverable:

  1. stop() does not escalate. A backend that ignores or cannot act on SIGTERM (wedged in a provider call, stopped, or out of memory) survives the desktop's quit with no SIGKILL from the desktop's side.
  2. The desktop never checks who owns the T3 home before starting a server. DesktopBackendPool's onStateDirOwned handler reacts after the fact: the new server exits with code 78 (ServerAlreadyRunningError) and the app shows "This T3 home is unavailable" and quits. The stranded server is never identified as this app's own leftover, so it is never recovered.

The ownership lock itself is by design (apps/server/src/serverOwnership.ts holds an exclusive transaction on server-owner.sqlite for the server's lifetime, so one server owns one T3 home). The defect is that the desktop can leave a server behind without releasing that lock, and cannot recover one it left behind.

Steps to reproduce

  1. macOS, desktop app, Settings > Connections > Local environment enabled.
  2. Start a run that keeps the server busy, so the backend does not shut down promptly.
  3. Quit the app with Command-Q.
  4. Observe the server process still alive with parent PID 1, still holding ~/.t3/userdata/server-owner.sqlite, and with no listening port.
  5. Reopen the app: "This T3 home is unavailable" appears and the app quits.

Impact

Quitting and reopening the desktop app does not work on macOS with the Local environment enabled, and the failure is not self-healing: the user has to find and signal the leftover server by hand. Sessions in the app's own T3 home are unaffected — the data is intact — but the app cannot be used until the leftover is gone.

Version or commit

Desktop 0.1.1. Source read at upstream main commit 680152e27b.

Environment

macOS (arm64), desktop app with the Local environment enabled.

Logs or stack traces

The app's own log shows the backend exiting with the ownership exit code on the next launch:

1ServerAlreadyRunningError: A T3 Code server already owns ~/.t3/userdata.
2Stop that server, or use a separate T3 home and pair with it, then retry.
3No server was stopped. ... code=78

Workaround

Find the leftover server and signal it once, which releases the ownership lock:

sh
1lsof -nP ~/.t3/userdata/server-owner.sqlite # the pid holding the lock
2kill -TERM <pid>

Notes for a fix

  • The desktop's stop budget must be strictly larger than the backend's force-stop budget, so the escalation always runs before the desktop gives up.
  • The desktop's stop() should escalate to SIGKILL on the pid it captured at spawn, rather than returning and leaving the process running.
  • The startup path should read the T3 home's server-runtime.json before starting a server, and classify the owner as healthy, stranded, or foreign. A healthy server should be reused, a verified stranded desktop-owned server should be stopped so the lock is released, and a foreign owner should be left alone.
Rrealhasanshoaib3d ago
Synced from GitHub

Another way to reach this on macOS (nightly 0.1.2-nightly.20261021.3499): after an update restart, the backend never passed the readiness probe, so the desktop stayed headless for 8 minutes (filed separately as #23372). Quitting the app at that point left the backend running with PPID 1 and still holding server-owner.sqlite, and the next launch exited 78 with ServerAlreadyRunningError and showed "This T3 home is unavailable". One SIGTERM released it, though the process took about 60 s to exit, so it was well past the 5 s stop budget described above.

Filed by: claude (claude-opus-5-5) via Claude Code, following the t3 triage playbook

Oomar75501d ago
Synced from GitHub

Note

Posted by Claude Code (Opus 5.5) on behalf of @omar7550.

Another occurrence on T3 Code Nightly 0.1.3-nightly.20261024.3630 (macOS, no background service: t3 service status reports not installed), with the leftover created by a quit during a slow startup.

Setup. statev2.sqlite is 21.7 GB with a 1.3 GB WAL. The backend took about 4.5 minutes to become ready. During that time it answered /.well-known/t3/environment with 503 (rejectRequestsUntilServing), so it was alive the whole time.

Timeline (UTC, from desktop.trace.ndjson and server-child.log):

text
118:51:17 / 18:52:17 / 18:53:17 readiness timeout (60000 ms), same pid 46100; desktop keeps probing, no window
218:53:19 desktop.lifecycle.startWaitingForShutdown (quit)
318:53:30 relaunch; new backend pid 46738 on :3773 starts WAL recovery again
418:54:34 readiness timeout for pid 46738
518:54:34 startWaitingForShutdown (quit); pid 46738 survives with PPID 1, still owning the T3 home
618:55:10, 18:55:21, 18:55:35, 18:57:04, 19:00:30
7 each relaunch starts a backend on :3774 that exits 78:
8 ServerAlreadyRunningError: A T3 Code server already owns ~/.t3/userdata ...
9 The "This T3 home is unavailable" dialog appears each time (screenshot attached).

What this adds:

  • The readiness timeout itself does not orphan the child. probeReadiness repeats while the process is alive (apps/desktop/src/backend/DesktopBackendManager.ts:545-568, from #5526), and onReadinessFailure only logs (:934-943). The leftover appears only after a quit, consistent with the stop-budget overlap described above (not measured): on main (ea41701979), stopAllPoolInstances uses Duration.seconds(5) (apps/desktop/src/app/DesktopApp.ts:156), equal to DEFAULT_BACKEND_TERMINATE_GRACE (DesktopBackendManager.ts:42), and stop() returns without escalating when closeRun times out (:1064-1066).
  • After the first quit (18:53:19) the leftover released the lock in time. After the second (18:54:34), during WAL recovery, it did not.
  • Killing the leftover by hand made recovery slower: the next start redid WAL recovery from the beginning and timed out again. Leaving it running until it returned 200 let the app open normally. Later starts took about 15–18 s.

Note for #22984: while starting, the leftover answered /.well-known/t3/environment with 503 (rejectRequestsUntilServing), not "no answer". In #22984's ownership tests, an own-desktop owner returning 503 is classified stranded and gets stopped. Here that would have repeated what happened when I killed it by hand: the next backend restarts WAL recovery from the beginning. Treating a 503 "starting" owner as busy, and waiting, may be safer than recovering it.

Workaround that worked: don't kill the leftover. Wait until curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3773/.well-known/t3/environment returns 200, then reopen the app.

Image