fix: enable systemd lingering for gateway

src/commands/configure.ts

@@ -53,6 +53,7 @@ import {
 import { setupProviders } from "./onboard-providers.js";
 import { promptRemoteGatewayConfig } from "./onboard-remote.js";
 import { setupSkills } from "./onboard-skills.js";
+import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 
 type WizardSection =
   | "model"
@@ -373,6 +374,8 @@ async function maybeInstallDaemon(params: {
 }) {
   const service = resolveGatewayService();
   const loaded = await service.isLoaded({ env: process.env });
+  let shouldCheckLinger = false;
+  let shouldInstall = true;
   if (loaded) {
     const action = guardCancel(
       await select({
@@ -387,7 +390,8 @@ async function maybeInstallDaemon(params: {
     );
     if (action === "restart") {
       await service.restart({ stdout: process.stdout });
-      return;
+      shouldCheckLinger = true;
+      shouldInstall = false;
     }
     if (action === "skip") return;
     if (action === "reinstall") {
@@ -395,24 +399,37 @@ async function maybeInstallDaemon(params: {
     }
   }
 
-  const devMode =
-    process.argv[1]?.includes(`${path.sep}src${path.sep}`) &&
-    process.argv[1]?.endsWith(".ts");
-  const { programArguments, workingDirectory } =
-    await resolveGatewayProgramArguments({ port: params.port, dev: devMode });
-  const environment: Record<string, string | undefined> = {
-    PATH: process.env.PATH,
-    CLAWDBOT_GATEWAY_TOKEN: params.gatewayToken,
-    CLAWDBOT_LAUNCHD_LABEL:
-      process.platform === "darwin" ? GATEWAY_LAUNCH_AGENT_LABEL : undefined,
-  };
-  await service.install({
-    env: process.env,
-    stdout: process.stdout,
-    programArguments,
-    workingDirectory,
-    environment,
-  });
+  if (shouldInstall) {
+    const devMode =
+      process.argv[1]?.includes(`${path.sep}src${path.sep}`) &&
+      process.argv[1]?.endsWith(".ts");
+    const { programArguments, workingDirectory } =
+      await resolveGatewayProgramArguments({ port: params.port, dev: devMode });
+    const environment: Record<string, string | undefined> = {
+      PATH: process.env.PATH,
+      CLAWDBOT_GATEWAY_TOKEN: params.gatewayToken,
+      CLAWDBOT_LAUNCHD_LABEL:
+        process.platform === "darwin" ? GATEWAY_LAUNCH_AGENT_LABEL : undefined,
+    };
+    await service.install({
+      env: process.env,
+      stdout: process.stdout,
+      programArguments,
+      workingDirectory,
+      environment,
+    });
+    shouldCheckLinger = true;
+  }
+
+  if (shouldCheckLinger) {
+    await ensureSystemdUserLingerInteractive({
+      runtime: params.runtime,
+      prompter: { confirm, note },
+      reason:
+        "Linux installs use a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.",
+      requireConfirm: true,
+    });
+  }
 }
 
 export async function runConfigureWizard(

src/commands/doctor.ts

@@ -31,6 +31,7 @@ import type { RuntimeEnv } from "../runtime.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveUserPath, sleep } from "../utils.js";
 import { healthCommand } from "./health.js";
+import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 import {
   applyWizardMetadata,
   DEFAULT_WORKSPACE,
@@ -599,6 +600,28 @@ export async function doctorCommand(runtime: RuntimeEnv = defaultRuntime) {
 
   await maybeMigrateLegacyGatewayService(cfg, runtime);
 
+  if (process.platform === "linux" && resolveMode(cfg) === "local") {
+    const service = resolveGatewayService();
+    let loaded = false;
+    try {
+      loaded = await service.isLoaded({ env: process.env });
+    } catch {
+      loaded = false;
+    }
+    if (loaded) {
+      await ensureSystemdUserLingerInteractive({
+        runtime,
+        prompter: {
+          confirm: (params) => guardCancel(confirm(params), runtime),
+          note,
+        },
+        reason:
+          "Gateway runs as a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.",
+        requireConfirm: true,
+      });
+    }
+  }
+
   const workspaceDir = resolveUserPath(
     cfg.agent?.workspace ?? DEFAULT_WORKSPACE,
   );

src/commands/onboard-non-interactive.ts

@@ -13,6 +13,7 @@ import { resolveGatewayService } from "../daemon/service.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveUserPath, sleep } from "../utils.js";
+import { ensureSystemdUserLingerNonInteractive } from "./systemd-linger.js";
 import { healthCommand } from "./health.js";
 import { applyMinimaxConfig, setAnthropicApiKey } from "./onboard-auth.js";
 import {
@@ -231,6 +232,7 @@ export async function runNonInteractiveOnboarding(
       workingDirectory,
       environment,
     });
+    await ensureSystemdUserLingerNonInteractive({ runtime });
   }
 
   if (!opts.skipHealth) {

src/commands/systemd-linger.ts

@@ -0,0 +1,109 @@
+import { note } from "@clack/prompts";
+
+import {
+  enableSystemdUserLinger,
+  readSystemdUserLingerStatus,
+} from "../daemon/systemd.js";
+import type { RuntimeEnv } from "../runtime.js";
+
+export type LingerPrompter = {
+  confirm?: (params: { message: string; initialValue?: boolean }) => Promise<
+    boolean
+  >;
+  note: (message: string, title?: string) => Promise<void> | void;
+};
+
+export async function ensureSystemdUserLingerInteractive(params: {
+  runtime: RuntimeEnv;
+  prompter?: LingerPrompter;
+  env?: NodeJS.ProcessEnv;
+  title?: string;
+  reason?: string;
+  prompt?: boolean;
+  requireConfirm?: boolean;
+}): Promise<void> {
+  if (process.platform !== "linux") return;
+  if (params.prompt === false) return;
+  const env = params.env ?? process.env;
+  const prompter = params.prompter ?? { note };
+  const title = params.title ?? "Systemd";
+  const status = await readSystemdUserLingerStatus(env);
+  if (!status) {
+    await prompter.note(
+      "Unable to read loginctl linger status. Ensure systemd + loginctl are available.",
+      title,
+    );
+    return;
+  }
+  if (status.linger === "yes") return;
+
+  const reason =
+    params.reason ??
+    "Systemd user services stop when you log out or go idle, which kills the Gateway.";
+  const actionNote = params.requireConfirm
+    ? "We can enable lingering now (needs sudo; writes /var/lib/systemd/linger)."
+    : "Enabling lingering now (needs sudo; writes /var/lib/systemd/linger).";
+  await prompter.note(
+    `${reason}\n${actionNote}`,
+    title,
+  );
+
+  if (params.requireConfirm && prompter.confirm) {
+    const ok = await prompter.confirm({
+      message: `Enable systemd lingering for ${status.user}?`,
+      initialValue: true,
+    });
+    if (!ok) {
+      await prompter.note(
+        "Without lingering, the Gateway will stop when you log out.",
+        title,
+      );
+      return;
+    }
+  }
+
+  const result = await enableSystemdUserLinger({
+    env,
+    user: status.user,
+    sudoMode: "prompt",
+  });
+  if (result.ok) {
+    await prompter.note(
+      `Enabled systemd lingering for ${status.user}.`,
+      title,
+    );
+    return;
+  }
+
+  params.runtime.error(
+    `Failed to enable lingering: ${result.stderr || result.stdout || "unknown error"}`,
+  );
+  await prompter.note(
+    `Run manually: sudo loginctl enable-linger ${status.user}`,
+    title,
+  );
+}
+
+export async function ensureSystemdUserLingerNonInteractive(params: {
+  runtime: RuntimeEnv;
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  if (process.platform !== "linux") return;
+  const env = params.env ?? process.env;
+  const status = await readSystemdUserLingerStatus(env);
+  if (!status || status.linger === "yes") return;
+
+  const result = await enableSystemdUserLinger({
+    env,
+    user: status.user,
+    sudoMode: "non-interactive",
+  });
+  if (result.ok) {
+    params.runtime.log(`Enabled systemd lingering for ${status.user}.`);
+    return;
+  }
+
+  params.runtime.log(
+    `Systemd lingering is disabled for ${status.user}. Run: sudo loginctl enable-linger ${status.user}`,
+  );
+}