[Bug]: Desktop backend outlives a crashed main process and keeps its port, so the relaunch silently moves to another port

[marcuscastelo]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/desktop

Steps to reproduce

1. On Linux, run the desktop app with its backend on the default port 3773 and pair another machine to http://<host>:3773 as a saved environment.
2. Make the desktop main process crash. [Bug]: Desktop main process SIGTRAPs when dragging a file with non-ASCII characters and a space in its name into the composer (Linux/Wayland) #13746 is a deterministic way to trigger this, but any abnormal exit works (for example kill -TRAP <main pid>).
3. Relaunch the desktop app.

Expected behavior

The embedded backend exits together with the main process, and the relaunched app gets 3773 again.

Actual behavior

The backend child (t3code --require …/resources/app.asar/…) survives the crash. It is reparented to systemd --user and keeps listening on 0.0.0.0:3773. The relaunched app scans past the busy port and silently moves:

selected backend port via sequential scan  port: 3777  startPort: 3773

Every client pinned to 3773 (paired remote environments, MCP/CLI clients using a saved URL) then talks to the orphaned backend or gets ECONNREFUSED once it goes away. The remote UI shows Reconnecting to <host> indefinitely. Repeated crashes walk the port forward one step each time (3773 → 3777 → 3778 → 3779 in my case), because each orphan holds its port for a while.

Killing the orphan and relaunching restores 3773. I reproduced this twice on purpose (ss -ltnp showed the orphan pid on 3773 and the new instance on 3777).

Related, not duplicates: #12641 (T3 Connect keeps the link-time origin after the port changes) and #6097 (scanning past 3773 when a service owns it). This issue is about why the port changes after a crash in the first place.

Possible fixes: have the backend exit when its parent dies (PR_SET_PDEATHSIG, or exit on EOF of a parent pipe/IPC channel), and/or detect a stale backend for the same profile on startup and reclaim its port instead of scanning past it.

Impact

Major degradation or frequent failure

Version or commit

0.0.43-nightly.20260926.2282 (also 0.0.43-nightly.20260925.2269)

Environment

Arch Linux, kernel 7.2.4, KDE Plasma (KWin 6.7.5) on Wayland, Electron 44.4.2. Remote client: macOS T3 Code Nightly over Tailscale.

Logs or stack traces

# after the main process (pid 695294) crashed with SIGTRAP and the app was relaunched:
$ ss -ltnp | grep -E ':377[3-9] '
LISTEN 0 511 0.0.0.0:3773 0.0.0.0:* users:(("t3code",pid=695427,fd=3))   # orphaned backend, ppid = systemd --user
LISTEN 0 511 0.0.0.0:3777 0.0.0.0:* users:(("t3code",pid=701542,fd=3))   # backend of the relaunched app

# remote client (macOS) keeps probing the old port:
http.client GET http://100.x.x.x:3773/.well-known/t3/environment  -> connection refused / wrong instance

Workaround

Kill the orphaned backend (ss -ltnp | grep 3773, then kill that pid) and relaunch the app. Pinning T3CODE_PORT=3773 (see #12641) keeps the port stable across normal restarts, but only helps after a crash once the orphan is gone.

[juliusmarminge]

Triage

Confirmed. This is a real desktop lifecycle bug, and it is not fixed on current main (ecd3237b18) or on the reported nightly (v0.0.43-nightly.20260926.2282, 6530de0339). Those files are unchanged between the two. The log line in the report is the one DesktopApp still writes.

Not a duplicate of #13746, #6097, #12641, or #7458. #13746 is one way to crash the main process. This issue is why the backend is still listening afterward.

What happens

A normal quit does stop the backend. before-quit, SIGINT, and SIGTERM run shutdown, and the app scope finalizer calls stopAllPoolInstances() (SIGTERM, then 5s). A native crash does not. The report’s SIGTRAP / code=dumped never enters those handlers. DesktopLifecycle only listens for SIGINT and SIGTERM:

    if (environment.platform !== "win32") {
      yield* addScopedListener(process, "SIGINT", () => {
        quitFromSignal("SIGINT", runEffect);
      });
      yield* addScopedListener(process, "SIGTERM", () => {
        quitFromSignal("SIGTERM", runEffect);
      });
    }

The packaged backend is process.execPath with ELECTRON_RUN_AS_NODE=1, --require <compile-cache>, the server entry, and --bootstrap-fd 3. That matches the orphan command line. Spawn does not set detached, and stdin is "ignore" on this path because bootstrap goes over fd 3:

  const command = ChildProcess.make(options.executablePath, options.args, {
    cwd: options.cwd,
    env: options.env,
    extendEnv: options.extendEnv,
    stdin: options.bootstrapDelivery === "stdin" ? bootstrapStream : "ignore",
    stdout: options.captureOutput ? "pipe" : "inherit",
    stderr: options.captureOutput ? "pipe" : "inherit",
    killSignal: "SIGTERM",
    forceKillAfter: DEFAULT_BACKEND_TERMINATE_GRACE,
    ...(options.bootstrapDelivery === "fd3" ? { additionalFds } : {}),
  });

On Linux and macOS, Effect’s Node spawner defaults detached to true when the option is omitted (detached = options.detached ?? platform !== "win32" in the vendored spawner). Node then setsid()s the child. scripts/dev-runner.ts already documents that default and opts out of it for the dev runner. The desktop backend does not. After the main process is dumped, systemd --user (the user subreaper) inherits the session leader, which is the ppid in the report. The child keeps 0.0.0.0:3773 when network exposure is on.

Nothing else notices the parent is gone. fd 3 is read once at startup and closed. fd 4 EOF only marks desktop telemetry "stopped" in DesktopTelemetryReceiver; it does not exit. fd 5 is written by the child, so parent death does not wake it. server-runtime.json is cleared only when that server process ends, so the orphan keeps the lease and the sqlite handle.

Relaunch then does what the log says. With no T3CODE_PORT, resolveDesktopBackendPort probes 127.0.0.1, 0.0.0.0, and :: from 3773 upward and takes the first port free on all three:

  for (let port = DEFAULT_DESKTOP_BACKEND_PORT; port <= MAX_TCP_PORT; port += 1) {
    let availableOnEveryHost = true;

    for (const host of DESKTOP_BACKEND_PORT_PROBE_HOSTS) {
      if (!(yield* net.canListenOnHost(port, host))) {
        availableOnEveryHost = false;
        break;
      }
    }

    if (availableOnEveryHost) {
      return {
        port,
        selectedByScan: true,
      } as const;
    }
  }

The scan steps by 1. 3773 → 3777 means 3774–3776 were also busy on at least one of those hosts (earlier orphans fit). Later 3777 → 3778 → 3779 is the same scan, one new orphan each time. Clients saved on http://<host>:3773 stay on the orphan, or get connection refused once it exits.

T3CODE_PORT=3773 skips the scan and tries that port only. It does not kill the occupant, so the pin helps only after the orphan is gone. That matches the workaround in the report.

While the orphan lives, the new instance is a second writer on the same T3 home. That is the #6097 split-brain, caused here by the leftover process rather than by t3 service.

Windows is not this report. There Effect defaults detached to false. This Linux path is the one the code and the ss output agree on. The same detached default exists on macOS; there is no macOS repro here.

Related, not the same

• [Bug]: Desktop main process SIGTRAPs when dragging a file with non-ASCII characters and a space in its name into the composer (Linux/Wayland) #13746 — Linux/Wayland composer drop crashes the main process with SIGTRAP. Trigger only.
• [Bug]: Desktop starts a second backend against the background service database #6097 — desktop scans past 3773 when a background service owns it, then opens the same database. Open. Same scan, different owner.
• [Bug]: Desktop-linked environment never re-registers its port after restart; stale relay ingress when 3773 is taken #12641 — T3 Connect keeps the link-time origin after the port changes. This report is a direct Tailscale probe of http://100.x.x.x:3773/.well-known/t3/environment, not the relay ingress. Connect users can hit both.
• [Bug]: Service update leaves T3 Connect relay targeting stale origin port #7458 — service update leaves the relay on a stale origin. Different path.
• fix(desktop): refuse same-home port fallback #9003 — open PR that would fail startup when 3773 is taken instead of scanning. It does not reap the orphan, so remote clients would still be on the old process and the new app would not start until that process is killed. It is not a fix for parent death, and it does not apply cleanly onto current DesktopApp.ts.

Direction

The backend has to die with the main process even when shutdown code never runs. A SIGTRAP handler is not enough. A native dump or SIGKILL will not run it.

• On Linux, PR_SET_PDEATHSIG in the backend child (or an equivalent lifetime fd that is not fd 4) so parent death exits the server. fd 4 already closes without exiting, and it can end without the app exiting.
• detached: false alone does not do this. It only keeps the process group. Parent death still does not signal the child.
• Keep the existing graceful path: stopAllPoolInstances() SIGTERM plus the 5s grace.
• Do not kill whatever is bound to 3773. A user t3 serve or service on that port is [Bug]: Desktop starts a second backend against the background service database #6097. Reap only the previous desktop-spawned backend for this profile.
• Refusing the scan (fix(desktop): refuse same-home port fallback #9003) stops the silent port walk. It still leaves the orphan on 3773. Parent death and the scan are both real; the crash leak is this issue.

Workaround. Find the listener on 3773 (ss -ltnp) and kill that pid, then relaunch so the new app can take 3773. T3CODE_PORT=3773 only stops the hop. It does not clear the orphan.

Severity: high. The local window comes back on a new port. Every saved remote, MCP, or CLI URL on 3773 keeps talking to the orphan, or reconnects forever once it exits. Each crash adds another listener.

[marcuscastelo]

#13749 implements the lifetime-fd direction from the triage above.

• The desktop passes the primary backend a dedicated pipe on fd 6 (desktopLifetimeFd in the bootstrap). It never writes to that pipe or closes it, so the OS closes it only when the desktop process exits, whether it quits normally or crashes.
• On EOF, the backend runs its SIGTERM shutdown handler. This uses process.emit, so it stays graceful on Windows.
• fd 4, port selection, and whatever owns 3773 are unchanged. Normal quit still goes through stopAllPoolInstances().

Verified with the real server on macOS and Linux: a SIGKILLed desktop now takes its backend with it in about 1 second, and the port is freed. On main, the backend is still listening with ppid=1.