Linux service: enable lingering on install so it survives reboot

Realistic VM testing surfaced two gaps in the systemd --user backend:

- The unit was enabled but lingering was never turned on, so after a reboot
  the daemon only came up once the user logged in (not at boot). install now
  runs `loginctl enable-linger`; uninstall disables it; status flags when
  lingering is off. Proven in an Ubuntu 24.04 VM: after a real reboot the
  service is active ~4s after boot (started by the user manager at boot, not
  by a login).
- `systemctl --user` needs XDG_RUNTIME_DIR to reach the user bus; supply it
  when the caller's environment lacks it so install is robust from any shell.

Author: RhysSullivan

apps/cli/src/service.ts

@@ -16,10 +16,9 @@ import { resolveExecutorDataDir } from "./local-server-manifest";
 // `<executor> daemon run --foreground --port <p>`, bind loopback, write
 // `server.json`, and get restarted on crash but not on a clean stop.
 //
-// macOS is the fully-built, e2e-proven path. Linux is implemented best-effort
-// (systemctl is usually present but unverified here). Windows is a guided
-// scaffold that prints the exact commands rather than claiming registration we
-// cannot yet verify.
+// macOS (launchd) and Linux (systemd --user + lingering) are both reboot-
+// survival verified in real VMs. Windows is a guided scaffold that prints the
+// exact commands rather than claiming registration we cannot yet verify.
 // ---------------------------------------------------------------------------
 
 export const SERVICE_LABEL = "sh.executor.daemon";
@@ -93,9 +92,11 @@ interface CommandResult {
 const runCommand = (
   cmd: string,
   args: ReadonlyArray<string>,
+  env?: Record<string, string | undefined>,
 ): Effect.Effect<CommandResult, Error> =>
   Effect.callback<CommandResult, Error>((resume) => {
-    execFile(cmd, [...args], { encoding: "utf8" }, (error, stdout, stderr) => {
+    const options = env ? { encoding: "utf8" as const, env: { ...process.env, ...env } } : { encoding: "utf8" as const };
+    execFile(cmd, [...args], options, (error, stdout, stderr) => {
       // A string `code` (ENOENT etc.) means the command could not be spawned.
       if (error && typeof (error as { code?: unknown }).code === "string") {
         resume(
@@ -321,7 +322,7 @@ const makeLaunchdBackend = (): ServiceBackend => {
 };
 
 // ---------------------------------------------------------------------------
-// Linux — systemd --user (best-effort, unverified on this machine)
+// Linux — systemd --user + lingering (reboot-survival verified in an Ubuntu VM)
 // ---------------------------------------------------------------------------
 
 const systemdUnitDir = (path: Path.Path): string =>
@@ -384,44 +385,75 @@ const makeSystemdBackend = (): ServiceBackend => {
           stderrPath: path.join(logs, "daemon.error.log"),
         });
         yield* fs.writeFileString(systemdUnitPath(path), unit, { mode: 0o600 });
-        yield* runCommand("systemctl", ["--user", "daemon-reload"]).pipe(Effect.ignore);
-        const enable = yield* runCommand("systemctl", ["--user", "enable", "--now", unitName]);
+        // `systemctl --user` needs XDG_RUNTIME_DIR to reach the user bus. Supply
+        // it if the caller's environment lacks it (e.g. a non-login shell) so
+        // install is robust regardless of how it was invoked.
+        const username = userInfo().username;
+        const sdEnv = { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${currentUid()}` };
+        yield* runCommand("systemctl", ["--user", "daemon-reload"], sdEnv).pipe(Effect.ignore);
+        const enable = yield* runCommand(
+          "systemctl",
+          ["--user", "enable", "--now", unitName],
+          sdEnv,
+        );
         if (enable.code !== 0) {
           return yield* Effect.fail(
-            new Error(
-              `systemctl --user enable failed (exit ${enable.code}): ${enable.stderr.trim()}\nNote: 'loginctl enable-linger ${userInfo().username}' may be required for the service to survive logout/reboot.`,
-            ),
+            new Error(`systemctl --user enable failed (exit ${enable.code}): ${enable.stderr.trim()}`),
           );
         }
+        // Enable lingering so the user manager — and this enabled service —
+        // starts at BOOT, not just on login, so the daemon survives a reboot
+        // unattended (verified in a real Ubuntu VM via loginctl). Best-effort:
+        // if the platform needs privilege, the service still works for the
+        // logged-in case and `service status` flags the missing linger.
+        yield* runCommand("loginctl", ["enable-linger", username], sdEnv).pipe(Effect.ignore);
       }),
     uninstall: () =>
       Effect.gen(function* () {
         const fs = yield* FileSystem.FileSystem;
         const path = yield* Path.Path;
-        yield* runCommand("systemctl", ["--user", "disable", "--now", unitName]).pipe(
+        const sdEnv = { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${currentUid()}` };
+        yield* runCommand("systemctl", ["--user", "disable", "--now", unitName], sdEnv).pipe(
           Effect.ignore,
         );
         yield* fs.remove(systemdUnitPath(path), { force: true });
-        yield* runCommand("systemctl", ["--user", "daemon-reload"]).pipe(Effect.ignore);
+        yield* runCommand("systemctl", ["--user", "daemon-reload"], sdEnv).pipe(Effect.ignore);
+        yield* runCommand("loginctl", ["disable-linger", userInfo().username], sdEnv).pipe(
+          Effect.ignore,
+        );
       }),
     status: () =>
       Effect.gen(function* () {
         const fs = yield* FileSystem.FileSystem;
         const path = yield* Path.Path;
+        const sdEnv = { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${currentUid()}` };
         const registered = yield* fs.exists(systemdUnitPath(path));
-        const active = yield* runCommand("systemctl", ["--user", "is-active", unitName]);
+        const active = yield* runCommand("systemctl", ["--user", "is-active", unitName], sdEnv);
         const running = active.stdout.trim() === "active";
+        const linger = yield* runCommand("loginctl", [
+          "show-user",
+          userInfo().username,
+          "-p",
+          "Linger",
+          "--value",
+        ]);
+        const lingerOn = linger.stdout.trim() === "yes";
         return {
           platform: "linux" as const,
           registered,
           running,
           pid: null,
-          detail: ["Linux support is best-effort and unverified; report issues."],
+          detail: lingerOn
+            ? []
+            : [
+                "Lingering is off — the daemon won't start until you log in. Run `loginctl enable-linger`.",
+              ],
         };
       }),
     restart: () =>
       Effect.gen(function* () {
-        const result = yield* runCommand("systemctl", ["--user", "restart", unitName]);
+        const sdEnv = { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${currentUid()}` };
+        const result = yield* runCommand("systemctl", ["--user", "restart", unitName], sdEnv);
         if (result.code !== 0) {
           return yield* Effect.fail(
             new Error(