@hellcoder/companion 0.124.0 → 0.124.1

package/bin/cli.ts

@@ -110,9 +110,17 @@ switch (command) {
       } else if (result.running) {
         console.log(`The Companion is running (PID: ${result.pid})`);
         console.log(`  URL: http://localhost:${result.port}`);
+        if (result.scope === "system") {
+          console.log("  Managed by a system-wide systemd unit (use sudo systemctl).");
+        }
       } else {
         console.log("The Companion is installed but not running.");
-        console.log("Check logs at ~/.companion/logs/");
+        if (result.scope === "system") {
+          console.log("It is managed by a system-wide systemd unit:");
+          console.log("  sudo systemctl status the-companion.service");
+        } else {
+          console.log("Check logs at ~/.companion/logs/");
+        }
       }
     }
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.124.0",
+  "version": "0.124.1",
   "type": "module",
   "description": "Web UI for launching and interacting with Claude Code agents — Moritz Edition (fork of the-companion)",
   "license": "MIT",

package/server/index.ts

@@ -45,7 +45,7 @@ import { getSettings, updateSettings } from "./settings-manager.js";
 import { setCliIngressServer } from "./routes/system-routes.js";
 import { imagePullManager } from "./image-pull-manager.js";
 import { restoreIfNeeded as restoreTailscaleFunnel, cleanup as cleanupTailscaleFunnel } from "./tailscale-manager.js";
-import { isRunningAsService } from "./service.js";
+import { getDetectedServiceKind, isRunningAsService } from "./service.js";
 import { getToken, verifyToken } from "./auth-manager.js";
 import { getCookie } from "hono/cookie";
 import type { SocketData } from "./ws-bridge.js";
@@ -421,7 +421,7 @@ if (getSettings().claudeBridgeMode === "patched") {
 }
 if (isRunningAsService()) {
   setServiceMode(true);
-  console.log("[server] Running as background service (auto-update available)");
+  console.log(`[server] Running as background service (${getDetectedServiceKind()}, auto-update available)`);
 }
 
 // ── Runtime diagnostics ──────────────────────────────────────────────────────

package/server/routes/system-routes.test.ts

@@ -28,6 +28,15 @@ vi.mock("../update-checker.js", () => ({
 // ─── Mock service ──────────────────────────────────────────────────────────
 vi.mock("../service.js", () => ({
   refreshServiceDefinition: vi.fn(),
+  getDetectedServiceKind: vi.fn(() => "systemd-user"),
+  getUpdateRestartPlan: vi.fn((kind: string | null) =>
+    kind === "systemd-system" || kind === "external"
+      ? { exitCode: 75 }
+      : {
+          command: ["systemctl", "--user", "restart", "the-companion.service"],
+          env: { XDG_RUNTIME_DIR: "/run/user/1000" },
+          exitCode: 0,
+        }),
 }));
 
 // ─── Mock claude-compat checker ────────────────────────────────────────────
@@ -88,6 +97,7 @@ import {
   setUpdateInProgress,
 } from "../update-checker.js";
 import { registerSystemRoutes } from "./system-routes.js";
+import { getDetectedServiceKind } from "../service.js";
 import { checkCompat, getCompatState } from "../claude-compat-checker.js";
 import { pinToVersion, patchBinary, unpatch } from "../claude-patcher.js";
 import { getSettings, updateSettings } from "../settings-manager.js";
@@ -496,6 +506,53 @@ describe("POST /api/update", () => {
     // Advance past the 500ms exit timeout
     await vi.advanceTimersByTimeAsync(600);
 
+    // The user unit is restarted through systemctl --user, then we exit 0.
+    expect(mockSpawn).toHaveBeenCalledWith(
+      ["systemctl", "--user", "restart", "the-companion.service"],
+      expect.objectContaining({ env: expect.objectContaining({ XDG_RUNTIME_DIR: "/run/user/1000" }) }),
+    );
+    expect(exitSpy).toHaveBeenCalledWith(0);
+
+    vi.useRealTimers();
+    exitSpy.mockRestore();
+    // @ts-expect-error -- cleanup Bun global mock
+    delete globalThis.Bun;
+  });
+
+  // Under a system-wide unit (issue #139) the server can't restart itself via
+  // systemctl; it must exit non-zero so Restart=on-failure respawns it.
+  it("exits with the restart code and spawns nothing under a system unit", async () => {
+    vi.useFakeTimers();
+    vi.mocked(getDetectedServiceKind).mockReturnValueOnce("systemd-system");
+    vi.mocked(getUpdateState).mockReturnValue({
+      currentVersion: "1.0.0",
+      latestVersion: "2.0.0",
+      lastChecked: Date.now(),
+      isServiceMode: true,
+      checking: false,
+      updateInProgress: false,
+      channel: "stable",
+    });
+    vi.mocked(isUpdateAvailable).mockReturnValue(true);
+
+    const mockSpawn = vi.fn().mockReturnValueOnce({
+      exited: Promise.resolve(0),
+      stdout: new ReadableStream(),
+      stderr: new ReadableStream(),
+    });
+    // @ts-expect-error -- Bun global mock
+    globalThis.Bun = { spawn: mockSpawn };
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    const res = await app.request("/api/update", { method: "POST" });
+    expect(res.status).toBe(200);
+    await vi.advanceTimersByTimeAsync(150);
+    await vi.advanceTimersByTimeAsync(600);
+
+    // Only the install was spawned — no systemctl --user restart.
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+    expect(exitSpy).toHaveBeenCalledWith(75);
+
     vi.useRealTimers();
     exitSpy.mockRestore();
     // @ts-expect-error -- cleanup Bun global mock

package/server/routes/system-routes.ts

@@ -11,7 +11,11 @@ import {
   isUpdateAvailable,
   setUpdateInProgress,
 } from "../update-checker.js";
-import { refreshServiceDefinition } from "../service.js";
+import {
+  getDetectedServiceKind,
+  getUpdateRestartPlan,
+  refreshServiceDefinition,
+} from "../service.js";
 import { getSettings, updateSettings } from "../settings-manager.js";
 import { imagePullManager } from "../image-pull-manager.js";
 import { isSandboxEnabled } from "../feature-flags.js";
@@ -187,29 +191,21 @@ export function registerSystemRoutes(
 
         console.log("[update] Update successful, restarting service...");
 
-        const isLinux = process.platform === "linux";
-        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
-        const restartCmd = isLinux
-          ? ["systemctl", "--user", "restart", "the-companion.service"]
-          : uid !== undefined
-            ? ["launchctl", "kickstart", "-k", `gui/${uid}/sh.thecompanion.app`]
-            : ["launchctl", "kickstart", "-k", "sh.thecompanion.app"];
-
-        Bun.spawn(restartCmd, {
-          stdout: "ignore",
-          stderr: "ignore",
-          stdin: "ignore",
-          env: isLinux
-            ? {
-                ...process.env,
-                XDG_RUNTIME_DIR:
-                  process.env.XDG_RUNTIME_DIR ||
-                  `/run/user/${uid ?? 1000}`,
-              }
-            : undefined,
-        });
-
-        setTimeout(() => process.exit(0), 500);
+        const plan = getUpdateRestartPlan(getDetectedServiceKind());
+        if (plan.command) {
+          Bun.spawn(plan.command, {
+            stdout: "ignore",
+            stderr: "ignore",
+            stdin: "ignore",
+            env: plan.env ? { ...process.env, ...plan.env } : undefined,
+          });
+        } else {
+          console.log(
+            `[update] Exiting with code ${plan.exitCode} so the supervisor restarts the server.`,
+          );
+        }
+
+        setTimeout(() => process.exit(plan.exitCode), 500);
       } catch (err) {
         console.error("[update] Update failed:", err);
         setUpdateInProgress(false);

package/server/service.test.ts

@@ -50,6 +50,38 @@ vi.mock("node:child_process", async (importOriginal) => {
   };
 });
 
+// Mock node:net so isPortInUse() never binds a real port (the dev box may
+// well be running a Companion on the default port).
+const mockPortInUse = vi.hoisted(() => {
+  let inUse = false;
+  return { get: () => inUse, set: (v: boolean) => { inUse = v; } };
+});
+
+vi.mock("node:net", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:net")>();
+  const { EventEmitter } = await import("node:events");
+  return {
+    ...actual,
+    createServer: () => {
+      const server = new EventEmitter() as InstanceType<typeof EventEmitter> & {
+        listen: (port: number) => void;
+        close: (cb?: () => void) => void;
+      };
+      server.listen = () => {
+        queueMicrotask(() => {
+          if (mockPortInUse.get()) {
+            server.emit("error", Object.assign(new Error("in use"), { code: "EADDRINUSE" }));
+          } else {
+            server.emit("listening");
+          }
+        });
+      };
+      server.close = (cb) => cb?.();
+      return server;
+    },
+  };
+});
+
 // Mock path-resolver to return a deterministic enriched PATH
 const MOCK_SERVICE_PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/mock/.bun/bin:/mock/.local/bin";
 vi.mock("./path-resolver.js", () => ({
@@ -74,6 +106,9 @@ beforeEach(async () => {
   mockHomedir.set(tempDir);
   mockPlatform.set("darwin");
   mockExecSync.mockReset();
+  mockPortInUse.set(false);
+  delete process.env.COMPANION_SERVICE_MODE;
+  delete process.env.INVOCATION_ID;
 
   // Set process.platform AFTER resetting mockPlatform to "darwin"
   Object.defineProperty(process, "platform", {
@@ -1417,3 +1452,200 @@ describe("platform check", () => {
     expect(existsSync(unitPath())).toBe(true);
   });
 });
+
+// ===========================================================================
+// System-wide systemd unit support (issue #139)
+// ===========================================================================
+
+const SYSTEM_UNIT_SHOW = [
+  "LoadState=loaded",
+  "ActiveState=active",
+  "MainPID=4321",
+  "InvocationID=0123456789abcdef0123456789abcdef",
+  "FragmentPath=/etc/systemd/system/the-companion.service",
+  "Environment=NODE_ENV=production PORT=3999 HOST=0.0.0.0",
+].join("\n");
+
+/** True for system-scope `systemctl show the-companion.service` queries. */
+function isSystemShow(cmd: string): boolean {
+  return cmd.startsWith("systemctl show the-companion.service");
+}
+
+describe("system-wide systemd unit (linux)", () => {
+  beforeEach(async () => {
+    mockPlatform.set("linux");
+    Object.defineProperty(process, "platform", { value: "linux" });
+    vi.resetModules();
+    service = await import("./service.js");
+  });
+
+  describe("getSystemUnitInfo", () => {
+    it("parses state, pid, invocation id, path and port", () => {
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+      expect(service.getSystemUnitInfo()).toEqual({
+        activeState: "active",
+        mainPid: 4321,
+        invocationId: "0123456789abcdef0123456789abcdef",
+        fragmentPath: "/etc/systemd/system/the-companion.service",
+        port: 3999,
+      });
+    });
+
+    it("returns undefined for LoadState=not-found", () => {
+      mockExecSync.mockImplementation(() => "LoadState=not-found\nActiveState=inactive\n");
+      expect(service.getSystemUnitInfo()).toBeUndefined();
+    });
+
+    it("returns undefined when systemctl fails", () => {
+      mockExecSync.mockImplementation(() => { throw new Error("no systemd"); });
+      expect(service.getSystemUnitInfo()).toBeUndefined();
+    });
+  });
+
+  describe("detectServiceKind / isRunningAsService", () => {
+    it("detects the system unit when INVOCATION_ID matches", () => {
+      process.env.INVOCATION_ID = "0123456789abcdef0123456789abcdef";
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+      expect(service.isRunningAsService()).toBe(true);
+      expect(service.getDetectedServiceKind()).toBe("systemd-system");
+    });
+
+    it("ignores the system unit when this process is not its invocation", () => {
+      process.env.INVOCATION_ID = "ffffffffffffffffffffffffffffffff";
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+      expect(service.detectServiceKind()).toBeNull();
+    });
+
+    it("ignores the system unit when not started by systemd (no INVOCATION_ID)", () => {
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+      expect(service.detectServiceKind()).toBeNull();
+    });
+
+    it("ignores an inactive system unit", () => {
+      process.env.INVOCATION_ID = "0123456789abcdef0123456789abcdef";
+      mockExecSync.mockImplementation((cmd: string) =>
+        isSystemShow(cmd) ? SYSTEM_UNIT_SHOW.replace("ActiveState=active", "ActiveState=failed") : "");
+      expect(service.detectServiceKind()).toBeNull();
+    });
+
+    it("COMPANION_SERVICE_MODE=1 opts in without any unit", () => {
+      process.env.COMPANION_SERVICE_MODE = "1";
+      expect(service.isRunningAsService()).toBe(true);
+      expect(service.getDetectedServiceKind()).toBe("external");
+    });
+
+    it("COMPANION_SERVICE_MODE=0 forces service mode off", () => {
+      process.env.COMPANION_SERVICE_MODE = "0";
+      process.env.INVOCATION_ID = "0123456789abcdef0123456789abcdef";
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+      expect(service.isRunningAsService()).toBe(false);
+      expect(service.getDetectedServiceKind()).toBeNull();
+    });
+
+    it("still reports systemd-user for an active per-user unit", async () => {
+      mockExecSync.mockImplementation((cmd: string) =>
+        cmd.startsWith("which") ? "/usr/local/bin/the-companion\n" : "");
+      await service.install();
+      mockExecSync.mockReset();
+      mockExecSync.mockImplementation((cmd: string) => (cmd.includes("is-active") ? "active\n" : ""));
+      expect(service.detectServiceKind()).toBe("systemd-user");
+    });
+  });
+
+  describe("install", () => {
+    it("refuses when a system-wide unit exists", async () => {
+      mockExecSync.mockImplementation((cmd: string) => {
+        if (cmd.startsWith("which")) return "/usr/local/bin/the-companion\n";
+        if (isSystemShow(cmd)) return SYSTEM_UNIT_SHOW;
+        return "";
+      });
+      await expect(service.install()).rejects.toThrow("process.exit(1)");
+      expect(existsSync(unitPath())).toBe(false);
+      expect(mockExecSync).not.toHaveBeenCalledWith(
+        expect.stringContaining("enable --now"), expect.anything());
+    });
+
+    it("refuses when the port is already in use", async () => {
+      mockPortInUse.set(true);
+      mockExecSync.mockImplementation((cmd: string) =>
+        cmd.startsWith("which") ? "/usr/local/bin/the-companion\n" : "");
+      await expect(service.install()).rejects.toThrow("process.exit(1)");
+      expect(existsSync(unitPath())).toBe(false);
+    });
+  });
+
+  describe("start/stop/restart/status/uninstall with only a system unit", () => {
+    beforeEach(() => {
+      mockExecSync.mockImplementation((cmd: string) => (isSystemShow(cmd) ? SYSTEM_UNIT_SHOW : ""));
+    });
+
+    it("start does not install a user unit and prints the sudo hint when unprivileged", async () => {
+      vi.spyOn(process, "getuid").mockReturnValue(1000);
+      const log = vi.spyOn(console, "log").mockImplementation(() => {});
+      await expect(service.start()).rejects.toThrow("process.exit(1)");
+      expect(existsSync(unitPath())).toBe(false);
+      expect(log.mock.calls.flat().join("\n")).toContain("sudo systemctl start the-companion.service");
+    });
+
+    it("restart drives the system unit directly as root", async () => {
+      vi.spyOn(process, "getuid").mockReturnValue(0);
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      await service.restart();
+      expect(mockExecSync).toHaveBeenCalledWith(
+        "systemctl restart the-companion.service", expect.anything());
+      expect(mockExecSync).not.toHaveBeenCalledWith(
+        expect.stringContaining("--user restart"), expect.anything());
+    });
+
+    it("stop prints the sudo hint when unprivileged", async () => {
+      vi.spyOn(process, "getuid").mockReturnValue(1000);
+      const log = vi.spyOn(console, "log").mockImplementation(() => {});
+      await expect(service.stop()).rejects.toThrow("process.exit(1)");
+      expect(log.mock.calls.flat().join("\n")).toContain("sudo systemctl stop the-companion.service");
+    });
+
+    it("status reports the system unit", async () => {
+      expect(await service.status()).toEqual({
+        installed: true, running: true, pid: 4321, port: 3999, scope: "system",
+      });
+    });
+
+    it("uninstall leaves the system unit alone", async () => {
+      const log = vi.spyOn(console, "log").mockImplementation(() => {});
+      await service.uninstall();
+      expect(mockExecSync).not.toHaveBeenCalledWith(
+        expect.stringContaining("disable"), expect.anything());
+      expect(log.mock.calls.flat().join("\n")).toContain("sudo systemctl disable --now");
+    });
+  });
+});
+
+describe("getUpdateRestartPlan", () => {
+  it("exits non-zero without spawning for a system unit", () => {
+    expect(service.getUpdateRestartPlan("systemd-system")).toEqual({
+      exitCode: service.UPDATE_RESTART_EXIT_CODE,
+    });
+    expect(service.UPDATE_RESTART_EXIT_CODE).not.toBe(0);
+    // 42 is SuccessExitStatus in our own template; a "please restart" code must differ.
+    expect(service.UPDATE_RESTART_EXIT_CODE).not.toBe(42);
+  });
+
+  it("exits non-zero without spawning for COMPANION_SERVICE_MODE=1", () => {
+    expect(service.getUpdateRestartPlan("external").command).toBeUndefined();
+    expect(service.getUpdateRestartPlan("external").exitCode).toBe(service.UPDATE_RESTART_EXIT_CODE);
+  });
+
+  it("uses systemctl --user restart for the user unit", () => {
+    const plan = service.getUpdateRestartPlan("systemd-user");
+    expect(plan.command).toEqual(["systemctl", "--user", "restart", "the-companion.service"]);
+    expect(plan.env?.XDG_RUNTIME_DIR).toBeTruthy();
+    expect(plan.exitCode).toBe(0);
+  });
+
+  it("uses launchctl kickstart for launchd", () => {
+    const plan = service.getUpdateRestartPlan("launchd");
+    expect(plan.command?.slice(0, 3)).toEqual(["launchctl", "kickstart", "-k"]);
+    expect(plan.command?.[3]).toMatch(/sh\.thecompanion\.app$/);
+    expect(plan.exitCode).toBe(0);
+  });
+});

package/server/service.ts

@@ -8,6 +8,7 @@ import {
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
+import { createServer } from "node:net";
 import { DEFAULT_PORT_PROD } from "./constants.js";
 import { getServicePath } from "./path-resolver.js";
 import { COMPANION_HOME } from "./paths.js";
@@ -32,6 +33,16 @@ const SYSTEMD_DIR = join(homedir(), ".config", "systemd", "user");
 const UNIT_NAME = "the-companion.service";
 const UNIT_PATH = join(SYSTEMD_DIR, UNIT_NAME);
 
+/**
+ * Exit code the server uses to ask an external supervisor (a system-wide
+ * systemd unit, or anything configured via COMPANION_SERVICE_MODE=1) to
+ * restart it after an in-app update. It must be non-zero so that units with
+ * `Restart=on-failure` respawn the process, and it deliberately differs from
+ * 42, which our own user-unit template lists in `SuccessExitStatus=`.
+ * 75 is EX_TEMPFAIL from sysexits.h ("temporary failure, try again").
+ */
+export const UPDATE_RESTART_EXIT_CODE = 75;
+
 // ─── Platform check ─────────────────────────────────────────────────────────────
 
 function ensureSupportedPlatform(): void {
@@ -225,6 +236,114 @@ function systemctlUser(cmd: string): string {
   });
 }
 
+/**
+ * Run a command against the system-wide systemd instance (no `--user`).
+ * Read-only queries (show / is-active) work unprivileged; mutating commands
+ * need root or a polkit rule.
+ */
+function systemctlSystem(cmd: string): string {
+  return execSync(`systemctl ${cmd}`, {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+
+export interface SystemUnitInfo {
+  activeState: string;
+  mainPid?: number;
+  invocationId?: string;
+  fragmentPath?: string;
+  port?: number;
+}
+
+/**
+ * Look up a system-wide `the-companion.service` (e.g. one an admin placed in
+ * /etc/systemd/system with `User=...`). Returns undefined when no such unit
+ * is loaded or systemctl is unavailable. Never throws.
+ */
+export function getSystemUnitInfo(): SystemUnitInfo | undefined {
+  if (!isLinux()) return undefined;
+  let output: string;
+  try {
+    output = systemctlSystem(
+      `show ${UNIT_NAME} --property=LoadState,ActiveState,MainPID,InvocationID,FragmentPath,Environment --no-pager`,
+    );
+  } catch {
+    return undefined;
+  }
+  if (typeof output !== "string") return undefined;
+  const prop = (name: string): string | undefined => {
+    const m = output.match(new RegExp(`^${name}=(.*)$`, "m"));
+    return m ? m[1].trim() : undefined;
+  };
+  // LoadState=not-found is what systemd reports for units that don't exist.
+  if (prop("LoadState") !== "loaded") return undefined;
+
+  const pid = Number(prop("MainPID"));
+  const portMatch = prop("Environment")?.match(/(?:^|\s)PORT=(\d+)/);
+  return {
+    activeState: prop("ActiveState") || "unknown",
+    mainPid: Number.isFinite(pid) && pid > 0 ? pid : undefined,
+    invocationId: prop("InvocationID") || undefined,
+    fragmentPath: prop("FragmentPath") || undefined,
+    port: portMatch ? Number(portMatch[1]) : undefined,
+  };
+}
+
+/** Explains how to manage a system-wide unit, which we can't do for the user. */
+function printSystemUnitHint(action: string, info: SystemUnitInfo): void {
+  console.log("The Companion is managed by a system-wide systemd unit:");
+  console.log(`  Unit:   ${info.fragmentPath ?? UNIT_NAME}`);
+  console.log(`  State:  ${info.activeState}`);
+  console.log("");
+  console.log(`Use: sudo systemctl ${action} ${UNIT_NAME}`);
+}
+
+function isRoot(): boolean {
+  return typeof process.getuid === "function" && process.getuid() === 0;
+}
+
+/**
+ * Handle start/stop/restart when only a system-wide unit exists. As root we
+ * can drive it directly; otherwise print the sudo command and fail, rather
+ * than falling through to `systemctl --user` (misleading) or, for `start`,
+ * installing a second, conflicting user unit.
+ */
+function controlSystemUnit(action: "start" | "stop" | "restart", info: SystemUnitInfo): void {
+  if (isRoot()) {
+    try {
+      systemctlSystem(`${action} ${UNIT_NAME}`);
+    } catch (err: unknown) {
+      console.error(`Failed to ${action} the system service with systemctl:`);
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+    const past = action === "stop" ? "stopped" : action === "start" ? "started" : "restarted";
+    console.log(`The Companion system service has been ${past}.`);
+    return;
+  }
+  printSystemUnitHint(action, info);
+  process.exit(1);
+}
+
+/**
+ * Resolve true when something is already listening on `port`. Binding with
+ * no host uses the dual-stack wildcard, which conflicts with a listener on
+ * any address, so this also catches servers bound to 0.0.0.0 or 127.0.0.1.
+ */
+export function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      resolve(err.code === "EADDRINUSE");
+    });
+    server.once("listening", () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(port);
+  });
+}
+
 // ─── Install ────────────────────────────────────────────────────────────────────
 
 export async function install(opts?: { port?: number }): Promise<void> {
@@ -285,9 +404,31 @@ async function installLinux(opts?: { port?: number }): Promise<void> {
     process.exit(1);
   }
 
+  // A system-wide unit already supervises the Companion on this host. A
+  // second (user) unit would fight it for the port and crash-loop, or, if it
+  // ever won, start with the wrong environment and an empty session store.
+  const systemUnit = getSystemUnitInfo();
+  if (systemUnit) {
+    console.error("The Companion is already installed as a system-wide systemd unit:");
+    console.error(`  ${systemUnit.fragmentPath ?? UNIT_NAME} (${systemUnit.activeState})`);
+    console.error("");
+    console.error("Refusing to install a second, per-user unit.");
+    console.error(`Manage it with: sudo systemctl <start|stop|restart|status> ${UNIT_NAME}`);
+    console.error("In-app updates work there too (see COMPANION_SERVICE_MODE in the docs).");
+    process.exit(1);
+  }
+
   const binPath = resolveBinPath();
   const port = opts?.port ?? DEFAULT_PORT_PROD;
 
+  if (await isPortInUse(port)) {
+    console.error(`Port ${port} is already in use.`);
+    console.error("Another Companion (or something else) is listening there, so the");
+    console.error("service would crash-loop. Stop it first, or install on another port:");
+    console.error("  the-companion install --port <port>");
+    process.exit(1);
+  }
+
   // Create log directory
   mkdirSync(LOG_DIR, { recursive: true });
 
@@ -356,6 +497,16 @@ async function uninstallDarwin(): Promise<void> {
 
 async function uninstallLinux(): Promise<void> {
   if (!isSystemdUnitInstalled()) {
+    const systemUnit = getSystemUnitInfo();
+    if (systemUnit) {
+      // Never remove an admin-managed unit on the user's behalf.
+      console.log("The Companion is managed by a system-wide systemd unit, which");
+      console.log("'the-companion uninstall' does not remove. To remove it:");
+      console.log(`  sudo systemctl disable --now ${UNIT_NAME}`);
+      console.log(`  sudo rm ${systemUnit.fragmentPath ?? `/etc/systemd/system/${UNIT_NAME}`}`);
+      console.log("  sudo systemctl daemon-reload");
+      return;
+    }
     console.log("The Companion is not installed as a service.");
     return;
   }
@@ -428,6 +579,8 @@ async function startDarwin(): Promise<void> {
 
 async function startLinux(): Promise<void> {
   if (!isSystemdUnitInstalled()) {
+    const systemUnit = getSystemUnitInfo();
+    if (systemUnit) return controlSystemUnit("start", systemUnit);
     console.log("Service not yet installed. Installing now...");
     await installLinux();
     return; // installLinux uses enable --now which starts the service
@@ -484,6 +637,8 @@ async function stopDarwin(): Promise<void> {
 
 async function stopLinux(): Promise<void> {
   if (!isSystemdUnitInstalled()) {
+    const systemUnit = getSystemUnitInfo();
+    if (systemUnit) return controlSystemUnit("stop", systemUnit);
     console.log("The Companion is not installed as a service.");
     return;
   }
@@ -540,6 +695,8 @@ async function restartDarwin(): Promise<void> {
 
 async function restartLinux(): Promise<void> {
   if (!isSystemdUnitInstalled()) {
+    const systemUnit = getSystemUnitInfo();
+    if (systemUnit) return controlSystemUnit("restart", systemUnit);
     console.log("The Companion is not installed as a service.");
     return;
   }
@@ -565,38 +722,135 @@ export interface ServiceStatus {
   running: boolean;
   pid?: number;
   port?: number;
+  /** Linux only: "system" when managed by a system-wide unit. */
+  scope?: "user" | "system";
 }
 
 /**
- * Safe check for whether the current process is running as a managed service.
- * Unlike status(), this never calls process.exit() and works on all platforms.
+ * How the current process is supervised, which decides how an in-app update
+ * restarts it:
+ * - "launchd" / "systemd-user": our own `the-companion install` units; the
+ *   updater asks the service manager to restart us.
+ * - "systemd-system": a system-wide `the-companion.service` (typically with
+ *   `User=...`), which an unprivileged process can't restart, so the updater
+ *   exits with UPDATE_RESTART_EXIT_CODE and lets `Restart=` respawn it.
+ * - "external": COMPANION_SERVICE_MODE=1, i.e. the operator promises some
+ *   supervisor restarts the process on a non-zero exit. Same exit strategy.
  */
-export function isRunningAsService(): boolean {
+export type ServiceKind = "launchd" | "systemd-user" | "systemd-system" | "external";
+
+function serviceModeEnv(): "on" | "off" | undefined {
+  const raw = process.env.COMPANION_SERVICE_MODE?.trim().toLowerCase();
+  if (!raw) return undefined;
+  if (["1", "true", "yes", "on"].includes(raw)) return "on";
+  if (["0", "false", "no", "off"].includes(raw)) return "off";
+  return undefined;
+}
+
+/**
+ * Detect how (and whether) the current process runs as a managed service.
+ * Never calls process.exit() and never throws.
+ *
+ * COMPANION_SERVICE_MODE=0 forces service mode off; =1 forces it on when no
+ * known service manager is detected.
+ */
+export function detectServiceKind(): ServiceKind | null {
+  const envMode = serviceModeEnv();
+  if (envMode === "off") return null;
+
   if (isDarwin()) {
     const installedService = getInstalledLaunchdService();
-    if (!installedService) return false;
-    try {
-      const output = execSync(`launchctl list "${installedService.label}"`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-      return /"PID"\s*=\s*\d+/.test(output);
-    } catch {
-      return false;
+    if (installedService) {
+      try {
+        const output = execSync(`launchctl list "${installedService.label}"`, {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (/"PID"\s*=\s*\d+/.test(output)) return "launchd";
+      } catch { /* not loaded */ }
     }
-  }
-
-  if (isLinux()) {
-    if (!isSystemdUnitInstalled()) return false;
-    try {
-      const output = systemctlUser(`is-active ${UNIT_NAME}`);
-      return output.trim() === "active";
-    } catch {
-      return false;
+  } else if (isLinux()) {
+    if (isSystemdUnitInstalled()) {
+      try {
+        if (systemctlUser(`is-active ${UNIT_NAME}`).trim() === "active") {
+          return "systemd-user";
+        }
+      } catch { /* inactive or no user bus */ }
     }
+    if (envMode !== "on" && isUnderSystemUnit()) return "systemd-system";
   }
 
-  return false;
+  return envMode === "on" ? "external" : null;
+}
+
+/**
+ * True when this process was started by systemd as the system-wide
+ * the-companion.service. systemd exports INVOCATION_ID to every service it
+ * starts; matching it against the unit's InvocationID proves we are that
+ * unit's process rather than, say, a foreground run on a host that also has
+ * the unit installed.
+ */
+function isUnderSystemUnit(): boolean {
+  const invocationId = process.env.INVOCATION_ID?.trim();
+  if (!invocationId) return false;
+  const info = getSystemUnitInfo();
+  if (!info) return false;
+  if (info.activeState !== "active" && info.activeState !== "reloading") return false;
+  // Very old systemd versions don't expose InvocationID; fall back to the
+  // active state alone there.
+  return !info.invocationId || info.invocationId === invocationId.replace(/-/g, "");
+}
+
+let detectedServiceKind: ServiceKind | null = null;
+
+/**
+ * Safe check for whether the current process is running as a managed service.
+ * Unlike status(), this never calls process.exit() and works on all platforms.
+ * The detected kind is remembered for getDetectedServiceKind().
+ */
+export function isRunningAsService(): boolean {
+  detectedServiceKind = detectServiceKind();
+  return detectedServiceKind !== null;
+}
+
+/** The kind found by the last isRunningAsService() call (null if none). */
+export function getDetectedServiceKind(): ServiceKind | null {
+  return detectedServiceKind;
+}
+
+export interface UpdateRestartPlan {
+  /** Command to spawn (detached) before exiting, if any. */
+  command?: string[];
+  /** Extra environment for the command. */
+  env?: Record<string, string>;
+  /** Exit code for the current process once the command was spawned. */
+  exitCode: number;
+}
+
+/**
+ * How to get the new version running after `bun install -g` succeeded.
+ * A null/undefined kind keeps the historical platform-based behaviour.
+ */
+export function getUpdateRestartPlan(kind: ServiceKind | null | undefined): UpdateRestartPlan {
+  if (kind === "systemd-system" || kind === "external") {
+    // Nothing to spawn: an unprivileged process can't restart a system unit,
+    // and the non-zero exit makes Restart=on-failure (or always) respawn us.
+    return { exitCode: UPDATE_RESTART_EXIT_CODE };
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  if (kind === "systemd-user" || (!kind && process.platform === "linux")) {
+    return {
+      command: ["systemctl", "--user", "restart", UNIT_NAME],
+      env: { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR || `/run/user/${uid ?? 1000}` },
+      exitCode: 0,
+    };
+  }
+  return {
+    command: uid !== undefined
+      ? ["launchctl", "kickstart", "-k", `gui/${uid}/${LABEL}`]
+      : ["launchctl", "kickstart", "-k", LABEL],
+    exitCode: 0,
+  };
 }
 
 /**
@@ -687,7 +941,16 @@ async function statusDarwin(): Promise<ServiceStatus> {
 
 async function statusLinux(): Promise<ServiceStatus> {
   if (!isSystemdUnitInstalled()) {
-    return { installed: false, running: false };
+    const systemUnit = getSystemUnitInfo();
+    if (!systemUnit) return { installed: false, running: false };
+    const running = systemUnit.activeState === "active" && !!systemUnit.mainPid;
+    return {
+      installed: true,
+      running,
+      pid: running ? systemUnit.mainPid : undefined,
+      port: systemUnit.port ?? DEFAULT_PORT_PROD,
+      scope: "system",
+    };
   }
 
   // Read port from the unit file