@opentag/cli 0.3.3 → 0.3.5

package/dist/index.js

@@ -2667,6 +2667,28 @@ var serviceHardeningEnvKeys = [
   "OPENTAG_RATE_LIMIT_MAX_REQUESTS",
   "OPENTAG_RATE_LIMIT_DISABLED"
 ];
+var launchAgentCliPath = [
+  "/opt/homebrew/bin",
+  "/opt/homebrew/sbin",
+  "/usr/local/bin",
+  "/usr/bin",
+  "/bin",
+  "/usr/sbin",
+  "/sbin"
+].join(":");
+function linuxServiceCliPath(home) {
+  return [
+    join3(home, ".local", "bin"),
+    join3(home, ".npm-global", "bin"),
+    join3(home, ".bun", "bin"),
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/local/sbin",
+    "/usr/sbin",
+    "/sbin"
+  ].join(":");
+}
 function loggerFrom(dependencies) {
   return dependencies.logger ?? console;
 }
@@ -2679,6 +2701,14 @@ function homeFrom(dependencies) {
 function uidFrom(dependencies) {
   return dependencies.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
 }
+function serviceControllerForPlatform(platform = process.platform) {
+  if (platform === "darwin") return "launchd";
+  if (platform === "linux") return "systemd";
+  return "unsupported";
+}
+function serviceControllerFrom(dependencies) {
+  return serviceControllerForPlatform(platformFrom(dependencies));
+}
 function servicePaths(options = {}, dependencies = {}) {
   const home = homeFrom(dependencies);
   const env = dependencies.env ?? process.env;
@@ -2691,7 +2721,8 @@ function servicePaths(options = {}, dependencies = {}) {
     logsDir,
     plistPath: join3(home, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`),
     stdoutPath: join3(logsDir, "opentag.log"),
-    stderrPath: join3(logsDir, "opentag.err.log")
+    stderrPath: join3(logsDir, "opentag.err.log"),
+    unitPath: join3(home, ".config", "systemd", "user", `${SERVICE_LABEL}.service`)
   };
 }
 function escapeXml(value) {
@@ -2741,6 +2772,36 @@ function buildLaunchAgentPlist(input) {
     ""
   ].join("\n");
 }
+function systemdQuote(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("%", "%%")}"`;
+}
+function systemdPathValue(value) {
+  return value.replaceAll("%", "%%");
+}
+function buildSystemdUserService(input) {
+  const environment = Object.entries(input.environment ?? {}).map(
+    ([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`
+  );
+  return [
+    "[Unit]",
+    "Description=OpenTag local agent",
+    "After=network.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${systemdQuote(input.workingDirectory)}`,
+    ...environment,
+    `ExecStart=${input.execStart.map(systemdQuote).join(" ")}`,
+    "Restart=always",
+    "RestartSec=3",
+    `StandardOutput=append:${systemdPathValue(input.stdoutPath)}`,
+    `StandardError=append:${systemdPathValue(input.stderrPath)}`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    ""
+  ].join("\n");
+}
 function launchctlRunner(dependencies) {
   if (dependencies.launchctl) return dependencies.launchctl;
   return (args) => {
@@ -2752,6 +2813,17 @@ function launchctlRunner(dependencies) {
     };
   };
 }
+function systemctlRunner(dependencies) {
+  if (dependencies.systemctl) return dependencies.systemctl;
+  return (args) => {
+    const result = spawnSync("systemctl", ["--user", ...args], { encoding: "utf8" });
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? ""
+    };
+  };
+}
 function launchdDomain(dependencies) {
   return `gui/${uidFrom(dependencies)}`;
 }
@@ -2759,21 +2831,99 @@ function launchdServiceTarget(dependencies) {
   return `${launchdDomain(dependencies)}/${SERVICE_LABEL}`;
 }
 function unsupportedMessage() {
-  return "OpenTag service management is not supported yet on this platform. Use `opentag start` in the foreground for now.";
+  return "OpenTag service management is supported on macOS and Linux only. Use `opentag start` in the foreground on this platform.";
 }
-function assertMacOS(dependencies) {
-  if (platformFrom(dependencies) !== "darwin") {
+function assertSupportedServiceController(dependencies) {
+  const controller = serviceControllerFrom(dependencies);
+  if (controller === "unsupported") {
     throw new Error(unsupportedMessage());
   }
+  return controller;
 }
 function runLaunchctlOrThrow(dependencies, args, action) {
   const result = launchctlRunner(dependencies)(args);
   if (result.status !== 0) {
-    const detail = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
+    const detail = launchctlDetail(result);
+    throw new Error(`${action} failed${detail ? `: ${detail}` : "."}`);
+  }
+  return result;
+}
+function launchctlDetail(result) {
+  return [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
+}
+function systemctlDetail(result) {
+  return [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
+}
+function runSystemctlOrThrow(dependencies, args, action) {
+  const result = systemctlRunner(dependencies)(args);
+  if (result.status !== 0) {
+    const detail = systemctlDetail(result);
     throw new Error(`${action} failed${detail ? `: ${detail}` : "."}`);
   }
   return result;
 }
+function printLaunchdService(dependencies) {
+  return launchctlRunner(dependencies)(["print", launchdServiceTarget(dependencies)]);
+}
+function systemdUnitName() {
+  return `${SERVICE_LABEL}.service`;
+}
+function printSystemdService(dependencies) {
+  return systemctlRunner(dependencies)(["is-active", systemdUnitName()]);
+}
+function sleepFrom(dependencies) {
+  return dependencies.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+}
+async function waitForLaunchdLoaded(dependencies, input = {}) {
+  const intervalMs = input.intervalMs ?? 100;
+  const deadline = Date.now() + (input.timeoutMs ?? 1500);
+  while (true) {
+    if (printLaunchdService(dependencies).status === 0) return true;
+    if (Date.now() >= deadline) return false;
+    await sleepFrom(dependencies)(intervalMs);
+  }
+}
+async function waitForLaunchdUnloaded(dependencies, input = {}) {
+  const intervalMs = input.intervalMs ?? 100;
+  const deadline = Date.now() + (input.timeoutMs ?? 1500);
+  while (true) {
+    if (printLaunchdService(dependencies).status !== 0) return true;
+    if (Date.now() >= deadline) return false;
+    await sleepFrom(dependencies)(intervalMs);
+  }
+}
+async function waitForSystemdActive(dependencies, input = {}) {
+  const intervalMs = input.intervalMs ?? 100;
+  const deadline = Date.now() + (input.timeoutMs ?? 1500);
+  while (true) {
+    const result = printSystemdService(dependencies);
+    if (result.status === 0 && result.stdout.trim() === "active") return true;
+    if (Date.now() >= deadline) return false;
+    await sleepFrom(dependencies)(intervalMs);
+  }
+}
+async function waitForSystemdInactive(dependencies, input = {}) {
+  const intervalMs = input.intervalMs ?? 100;
+  const deadline = Date.now() + (input.timeoutMs ?? 1500);
+  while (true) {
+    const result = printSystemdService(dependencies);
+    if (result.status !== 0 || result.stdout.trim() !== "active") return true;
+    if (Date.now() >= deadline) return false;
+    await sleepFrom(dependencies)(intervalMs);
+  }
+}
+async function waitForServiceLoaded(dependencies, input = {}) {
+  const controller = serviceControllerFrom(dependencies);
+  if (controller === "launchd") return waitForLaunchdLoaded(dependencies, input);
+  if (controller === "systemd") return waitForSystemdActive(dependencies, input);
+  return false;
+}
+async function waitForServiceUnloaded(dependencies, input = {}) {
+  const controller = serviceControllerFrom(dependencies);
+  if (controller === "launchd") return waitForLaunchdUnloaded(dependencies, input);
+  if (controller === "systemd") return waitForSystemdInactive(dependencies, input);
+  return true;
+}
 function serviceWorkingDirectory(configPath) {
   const config = readCliConfig(configPath);
   return config.daemon.repositories[0]?.checkoutPath ?? dirname2(configPath);
@@ -2847,95 +2997,168 @@ function formatConnectorReadiness(config) {
   }
   return lines.length > 1 ? lines : [...lines, "  none configured"];
 }
-function launchAgentEnvironment(options, paths) {
+function serviceCliPath(dependencies) {
+  const controller = serviceControllerFrom(dependencies);
+  return controller === "systemd" ? linuxServiceCliPath(homeFrom(dependencies)) : launchAgentCliPath;
+}
+function serviceEnvironment(options, paths, dependencies) {
   return {
     OPENTAG_CONFIG_PATH: paths.configPath,
+    PATH: serviceCliPath(dependencies),
     ...serviceHardeningEnvironment(options)
   };
 }
 function installService(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
+  const controller = assertSupportedServiceController(dependencies);
   const paths = servicePaths(options, dependencies);
   const workingDirectory = serviceWorkingDirectory(paths.configPath);
-  mkdirSync2(dirname2(paths.plistPath), { recursive: true });
   ensurePrivateDirectory(paths.logsDir);
-  const plist = buildLaunchAgentPlist({
+  if (controller === "launchd") {
+    mkdirSync2(dirname2(paths.plistPath), { recursive: true });
+    const plist = buildLaunchAgentPlist({
+      label: paths.label,
+      programArguments: serviceProgramArguments(options, dependencies),
+      runAtLoad: true,
+      keepAlive: true,
+      stdoutPath: paths.stdoutPath,
+      stderrPath: paths.stderrPath,
+      workingDirectory,
+      environment: serviceEnvironment(options, paths, dependencies)
+    });
+    writeFileSync2(paths.plistPath, plist, { mode: 420 });
+    return paths;
+  }
+  mkdirSync2(dirname2(paths.unitPath), { recursive: true });
+  const unit = buildSystemdUserService({
     label: paths.label,
-    programArguments: serviceProgramArguments(options, dependencies),
-    runAtLoad: true,
-    keepAlive: true,
+    execStart: serviceProgramArguments(options, dependencies),
     stdoutPath: paths.stdoutPath,
     stderrPath: paths.stderrPath,
     workingDirectory,
-    environment: launchAgentEnvironment(options, paths)
+    environment: serviceEnvironment(options, paths, dependencies)
   });
-  writeFileSync2(paths.plistPath, plist, { mode: 420 });
+  writeFileSync2(paths.unitPath, unit, { mode: 420 });
+  runSystemctlOrThrow(dependencies, ["daemon-reload"], "systemctl --user daemon-reload");
+  runSystemctlOrThrow(dependencies, ["enable", systemdUnitName()], "systemctl --user enable");
   return paths;
 }
-function installed(paths) {
-  return existsSync2(paths.plistPath);
+function installed(paths, controller) {
+  if (controller === "launchd") return existsSync2(paths.plistPath);
+  if (controller === "systemd") return existsSync2(paths.unitPath);
+  return false;
 }
 function isNotLoaded(result) {
   const text2 = `${result.stderr}
 ${result.stdout}`.toLowerCase();
   return text2.includes("no such process") || text2.includes("could not find service") || text2.includes("service is not loaded");
 }
+function isSystemdNotLoaded(result) {
+  const text2 = `${result.stderr}
+${result.stdout}`.toLowerCase();
+  return text2.includes("could not be found") || text2.includes("not loaded") || text2.includes("not-found") || text2.includes("no such");
+}
 function startService(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
+  const controller = assertSupportedServiceController(dependencies);
   const paths = servicePaths(options, dependencies);
-  if (!installed(paths)) {
+  if (!installed(paths, controller)) {
     throw new Error(`OpenTag service is not installed. Run \`opentag service install --config ${paths.configPath}\` first.`);
   }
+  if (controller === "systemd") {
+    runSystemctlOrThrow(dependencies, ["daemon-reload"], "systemctl --user daemon-reload");
+    runSystemctlOrThrow(dependencies, ["start", systemdUnitName()], "systemctl --user start");
+    return paths;
+  }
   const launchctl = launchctlRunner(dependencies);
   const bootstrap = launchctl(["bootstrap", launchdDomain(dependencies), paths.plistPath]);
   if (bootstrap.status !== 0) {
-    const print = launchctl(["print", launchdServiceTarget(dependencies)]);
+    const print = printLaunchdService(dependencies);
     if (print.status !== 0) {
-      const detail = [bootstrap.stderr.trim(), bootstrap.stdout.trim()].filter(Boolean).join("\n");
+      const detail = launchctlDetail(bootstrap);
       throw new Error(`launchctl bootstrap failed${detail ? `: ${detail}` : "."}`);
     }
   }
-  runLaunchctlOrThrow(dependencies, ["kickstart", "-k", launchdServiceTarget(dependencies)], "launchctl kickstart");
+  const kickstart = launchctl(["kickstart", "-k", launchdServiceTarget(dependencies)]);
+  if (kickstart.status !== 0 && printLaunchdService(dependencies).status !== 0) {
+    const detail = launchctlDetail(kickstart);
+    throw new Error(`launchctl kickstart failed${detail ? `: ${detail}` : "."}`);
+  }
   return paths;
 }
 function stopService(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
+  const controller = assertSupportedServiceController(dependencies);
   const paths = servicePaths(options, dependencies);
-  if (!installed(paths)) return paths;
+  if (!installed(paths, controller)) return paths;
+  if (controller === "systemd") {
+    const result = systemctlRunner(dependencies)(["stop", systemdUnitName()]);
+    if (result.status !== 0 && !isSystemdNotLoaded(result)) {
+      const detail = systemctlDetail(result);
+      throw new Error(`systemctl --user stop failed${detail ? `: ${detail}` : "."}`);
+    }
+    return paths;
+  }
   const launchctl = launchctlRunner(dependencies);
   const first = launchctl(["bootout", launchdServiceTarget(dependencies)]);
-  if (first.status !== 0 && !isNotLoaded(first)) {
+  if (first.status !== 0) {
     const second = launchctl(["bootout", launchdDomain(dependencies), paths.plistPath]);
     if (second.status !== 0 && !isNotLoaded(second)) {
-      const detail = [second.stderr.trim(), first.stderr.trim(), second.stdout.trim(), first.stdout.trim()].filter(Boolean).join("\n");
+      const firstDetail = isNotLoaded(first) ? "" : launchctlDetail(first);
+      const detail = [launchctlDetail(second), firstDetail].filter(Boolean).join("\n");
       throw new Error(`launchctl bootout failed${detail ? `: ${detail}` : "."}`);
     }
   }
   return paths;
 }
 function uninstallService(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
+  const controller = assertSupportedServiceController(dependencies);
   const paths = stopService(options, dependencies);
-  rmSync2(paths.plistPath, { force: true });
+  if (controller === "launchd") {
+    rmSync2(paths.plistPath, { force: true });
+    return paths;
+  }
+  const disabled = systemctlRunner(dependencies)(["disable", systemdUnitName()]);
+  if (disabled.status !== 0 && !isSystemdNotLoaded(disabled)) {
+    const detail = systemctlDetail(disabled);
+    throw new Error(`systemctl --user disable failed${detail ? `: ${detail}` : "."}`);
+  }
+  rmSync2(paths.unitPath, { force: true });
+  runSystemctlOrThrow(dependencies, ["daemon-reload"], "systemctl --user daemon-reload");
   return paths;
 }
 function enableServiceAutostart(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
-  const paths = installed(servicePaths(options, dependencies)) ? servicePaths(options, dependencies) : installService(options, dependencies);
+  const controller = assertSupportedServiceController(dependencies);
+  const candidate = servicePaths(options, dependencies);
+  const paths = installed(candidate, controller) ? candidate : installService(options, dependencies);
+  if (controller === "systemd") {
+    runSystemctlOrThrow(dependencies, ["enable", systemdUnitName()], "systemctl --user enable");
+    return paths;
+  }
   runLaunchctlOrThrow(dependencies, ["enable", launchdServiceTarget(dependencies)], "launchctl enable");
   return paths;
 }
 function disableServiceAutostart(options = {}, dependencies = {}) {
-  assertMacOS(dependencies);
+  const controller = assertSupportedServiceController(dependencies);
   const paths = servicePaths(options, dependencies);
-  if (installed(paths)) {
+  if (installed(paths, controller)) {
+    if (controller === "systemd") {
+      runSystemctlOrThrow(dependencies, ["disable", systemdUnitName()], "systemctl --user disable");
+      return paths;
+    }
     runLaunchctlOrThrow(dependencies, ["disable", launchdServiceTarget(dependencies)], "launchctl disable");
   }
   return paths;
 }
 function serviceAutostart(paths, dependencies, isInstalled) {
   if (!isInstalled) return "disabled";
-  if (platformFrom(dependencies) !== "darwin") return "unknown";
+  const controller = serviceControllerFrom(dependencies);
+  if (controller === "systemd") {
+    const result2 = systemctlRunner(dependencies)(["is-enabled", systemdUnitName()]);
+    const text2 = `${result2.stdout}
+${result2.stderr}`.trim().toLowerCase();
+    if (result2.status === 0 && text2.includes("enabled")) return "enabled";
+    if (text2.includes("disabled") || text2.includes("not-found") || text2.includes("could not be found")) return "disabled";
+    return "unknown";
+  }
+  if (controller !== "launchd") return "unknown";
   const result = launchctlRunner(dependencies)(["print-disabled", launchdDomain(dependencies)]);
   if (result.status !== 0) return "unknown";
   const escapedLabel = SERVICE_LABEL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -2947,12 +3170,15 @@ function serviceAutostart(paths, dependencies, isInstalled) {
 }
 function getServiceStatus(options = {}, dependencies = {}) {
   const paths = servicePaths(options, dependencies);
-  const controller = platformFrom(dependencies) === "darwin" ? "launchd" : "unsupported";
-  const isInstalled = installed(paths);
+  const controller = serviceControllerFrom(dependencies);
+  const isInstalled = installed(paths, controller);
   let running = isInstalled ? "stopped" : "unknown";
   if (controller === "launchd" && isInstalled) {
     const result = launchctlRunner(dependencies)(["print", launchdServiceTarget(dependencies)]);
     running = result.status === 0 ? "running" : "stopped";
+  } else if (controller === "systemd" && isInstalled) {
+    const result = systemctlRunner(dependencies)(["is-active", systemdUnitName()]);
+    running = result.status === 0 && result.stdout.trim() === "active" ? "running" : "stopped";
   }
   let runtimeMode = "unknown";
   let relayUrl;
@@ -3003,10 +3229,34 @@ function readLaunchAgentEnvironment(paths) {
     })
   );
 }
+function unescapeSystemdQuotedValue(value) {
+  return value.replaceAll("%%", "%").replaceAll('\\"', '"').replaceAll("\\$", "$").replaceAll("\\\\", "\\");
+}
+function readSystemdEnvironment(paths) {
+  if (!existsSync2(paths.unitPath)) return {};
+  const unit = readFileSync2(paths.unitPath, "utf8");
+  return Object.fromEntries(
+    unit.split(/\r?\n/).flatMap((line) => {
+      const match = line.match(/^Environment=(?:"((?:\\.|[^"])*)"|(.+))$/);
+      const raw = match?.[1] ?? match?.[2];
+      if (!raw) return [];
+      const value = unescapeSystemdQuotedValue(raw);
+      const separator = value.indexOf("=");
+      if (separator <= 0) return [];
+      return [[value.slice(0, separator), value.slice(separator + 1)]];
+    })
+  );
+}
+function readServiceEnvironment(paths) {
+  return {
+    ...readLaunchAgentEnvironment(paths),
+    ...readSystemdEnvironment(paths)
+  };
+}
 function formatServiceHardening(paths) {
-  const environment = readLaunchAgentEnvironment(paths);
+  const environment = readServiceEnvironment(paths);
   const configured2 = serviceHardeningEnvKeys.filter((key) => environment[key]).map((key) => `  ${key}=${environment[key]}`);
-  return ["Service Hardening:", ...configured2.length ? configured2 : ["  dispatcher hardening env not configured in LaunchAgent"]];
+  return ["Service Hardening:", ...configured2.length ? configured2 : ["  dispatcher hardening env not configured in service definition"]];
 }
 function doctorCounts(checks) {
   return {
@@ -3096,6 +3346,7 @@ async function getServiceStatusWithRuntimeReadiness(options = {}, dependencies =
   }
 }
 function formatServiceStatus(summary) {
+  const definitionLine = summary.controller === "launchd" ? `LaunchAgent: ${summary.plistPath}` : summary.controller === "systemd" ? `Systemd unit: ${summary.unitPath}` : void 0;
   return [
     `Controller: ${summary.controller}`,
     `Installed: ${summary.installed ? "yes" : "no"}`,
@@ -3111,7 +3362,7 @@ function formatServiceStatus(summary) {
     ...summary.secrets,
     ...summary.capabilities,
     ...summary.serviceHardening,
-    `LaunchAgent: ${summary.plistPath}`,
+    ...definitionLine ? [definitionLine] : [],
     `Stdout log: ${summary.stdoutPath}`,
     `Stderr log: ${summary.stderrPath}`,
     ...summary.controller === "unsupported" ? [unsupportedMessage()] : []
@@ -3161,11 +3412,23 @@ function formatServiceLogs(options = {}, dependencies = {}) {
 }
 async function runServiceInstallCommand(options, dependencies = {}) {
   const paths = installService(options, dependencies);
-  loggerFrom(dependencies).log(`OpenTag service installed: ${paths.plistPath}`);
+  const controller = serviceControllerFrom(dependencies);
+  loggerFrom(dependencies).log(`OpenTag service installed: ${controller === "systemd" ? paths.unitPath : paths.plistPath}`);
   loggerFrom(dependencies).log("It will start at login. Run `opentag service start` to start it now.");
 }
+async function installAndStartService(options = {}, dependencies = {}) {
+  installService(options, dependencies);
+  const paths = startService(options, dependencies);
+  if (!await waitForServiceLoaded(dependencies)) {
+    throw new Error("OpenTag service start did not leave the service manager running. Run `opentag service status` and `opentag service logs` for details.");
+  }
+  return paths;
+}
 async function runServiceStartCommand(options, dependencies = {}) {
   const paths = startService(options, dependencies);
+  if (!await waitForServiceLoaded(dependencies)) {
+    throw new Error("OpenTag service start did not leave the service manager running. Run `opentag service status` and `opentag service logs` for details.");
+  }
   loggerFrom(dependencies).log(`OpenTag service started: ${paths.label}`);
 }
 async function runServiceStopCommand(options, dependencies = {}) {
@@ -3174,12 +3437,22 @@ async function runServiceStopCommand(options, dependencies = {}) {
 }
 async function runServiceRestartCommand(options, dependencies = {}) {
   stopService(options, dependencies);
-  const paths = startService(options, dependencies);
+  await waitForServiceUnloaded(dependencies, { timeoutMs: 1e3 });
+  let paths = startService(options, dependencies);
+  let loaded = await waitForServiceLoaded(dependencies, { timeoutMs: 500 });
+  if (!loaded) {
+    paths = startService(options, dependencies);
+    loaded = await waitForServiceLoaded(dependencies);
+  }
+  if (!loaded) {
+    throw new Error("OpenTag service restart did not leave the service manager running. Run `opentag service status` and `opentag service logs` for details.");
+  }
   loggerFrom(dependencies).log(`OpenTag service restarted: ${paths.label}`);
 }
 async function runServiceUninstallCommand(options, dependencies = {}) {
   const paths = uninstallService(options, dependencies);
-  loggerFrom(dependencies).log(`OpenTag service uninstalled: ${paths.plistPath}`);
+  const controller = serviceControllerFrom(dependencies);
+  loggerFrom(dependencies).log(`OpenTag service uninstalled: ${controller === "systemd" ? paths.unitPath : paths.plistPath}`);
 }
 async function runServiceStatusCommand(options, dependencies = {}) {
   const summary = await getServiceStatusWithRuntimeReadiness(options, dependencies);
@@ -4715,16 +4988,54 @@ async function scanLarkPersonalAgent(input = {}, dependencies = {}) {
 }
 
 // src/commands/setup.ts
-function startPromptMessage(language) {
-  return language === "zh-CN" ? "\u73B0\u5728\u542F\u52A8 OpenTag\uFF1F" : "Start OpenTag now?";
-}
 function setupCompleteMessage(language) {
   return language === "zh-CN" ? "OpenTag \u8BBE\u7F6E\u5B8C\u6210\u3002" : "OpenTag setup complete.";
 }
 function startingMessage(language) {
   return language === "zh-CN" ? "\u6B63\u5728\u542F\u52A8 OpenTag..." : "Starting OpenTag...";
 }
+function serviceStartingMessage(language) {
+  return language === "zh-CN" ? "\u6B63\u5728\u5B89\u88C5\u5E76\u542F\u52A8 OpenTag \u540E\u53F0\u670D\u52A1..." : "Installing and starting the OpenTag background service...";
+}
+function serviceStartedMessage(language) {
+  return language === "zh-CN" ? "OpenTag \u8BBE\u7F6E\u5B8C\u6210\uFF0C\u540E\u53F0\u670D\u52A1\u5DF2\u542F\u52A8\u3002" : "OpenTag setup complete. The background service is running.";
+}
+function runModePromptMessage(language) {
+  return language === "zh-CN" ? "OpenTag \u8981\u5982\u4F55\u8FD0\u884C\uFF1F" : "How should OpenTag run?";
+}
+function runModeOptions(language, serviceSupported) {
+  if (language === "zh-CN") {
+    return [
+      ...serviceSupported ? [{ value: "service", label: "\u5173\u95ED\u8FD9\u4E2A\u7EC8\u7AEF\u540E\u7EE7\u7EED\u8FD0\u884C\uFF08\u63A8\u8350\uFF09" }] : [],
+      { value: "terminal", label: "\u53EA\u5728\u5F53\u524D\u7EC8\u7AEF\u91CC\u8FD0\u884C" },
+      { value: "later", label: "\u6682\u65F6\u4E0D\u542F\u52A8" }
+    ];
+  }
+  return [
+    ...serviceSupported ? [{ value: "service", label: "Keep running after I close this terminal (recommended)" }] : [],
+    { value: "terminal", label: "Run only in this terminal" },
+    { value: "later", label: "Do not start now" }
+  ];
+}
+async function collectRunMode(options, prompts, language, platform) {
+  if (options.service) return "service";
+  if (options.start === true) return "terminal";
+  if (options.start === false || options.yes) return "later";
+  const serviceSupported = serviceControllerForPlatform(platform) !== "unsupported";
+  return prompts.select({
+    message: runModePromptMessage(language),
+    initialValue: serviceSupported ? "service" : "terminal",
+    options: runModeOptions(language, serviceSupported)
+  });
+}
 async function runSetupCommand(options, dependencies = {}) {
+  if (options.service && options.start !== void 0) {
+    throw new Error("--service cannot be combined with --start or --no-start.");
+  }
+  const platform = dependencies.platform ?? process.platform;
+  if (options.service && serviceControllerForPlatform(platform) === "unsupported") {
+    throw new Error("OpenTag background service is not supported on this platform. Use `opentag start` to run OpenTag in this terminal.");
+  }
   const env = dependencies.env ?? process.env;
   const configPath = options.config ?? defaultConfigPath(env);
   if (options.yes && existsSync6(configPath) && !options.force) {
@@ -4744,11 +5055,14 @@ async function runSetupCommand(options, dependencies = {}) {
   ensurePrivateDirectory(config.state.worktreeRoot);
   writeCliConfigAtomic(configPath, config);
   prompts.note(formatSetupComplete(config, configPath));
-  const shouldStart = options.start ?? (!options.yes ? await prompts.confirm({
-    message: startPromptMessage(config.preferences?.language),
-    initialValue: true
-  }) : false);
-  if (shouldStart) {
+  const runMode = await collectRunMode(options, prompts, config.preferences?.language, platform);
+  if (runMode === "service") {
+    prompts.note(serviceStartingMessage(config.preferences?.language));
+    await (dependencies.startOpenTagService ?? installAndStartService)({ config: configPath });
+    prompts.outro(serviceStartedMessage(config.preferences?.language));
+    return;
+  }
+  if (runMode === "terminal") {
     prompts.outro(startingMessage(config.preferences?.language));
     await (dependencies.startOpenTag ?? runStartCommand)({ config: configPath });
   } else {
@@ -4772,7 +5086,7 @@ function runCliAction(handler) {
   };
 }
 program.name(process.env.OPENTAG_CLI_NAME?.trim() || "opentag").description("OpenTag CLI");
-program.command("setup").description("Create a local OpenTag config").option("--platform <platform>", "Platform to configure").option("--config <path>", "Config file path").option("--project <path>", "Project checkout path").option("--language <language>", "Setup language: en or zh-CN").option("--executor <executor>", "Default executor: echo, codex, claude-code, or hermes").option("--hermes-command <command>", "Hermes CLI command").option("--hermes-profile <profile>", "Hermes profile").option("--hermes-profile-template <template>", "Hermes profile template").option("--agent-profile <profile>", "Executor-neutral agent session profile").option("--agent-profile-template <template>", "Executor-neutral agent session profile template").option("--lark-setup <method>", "Lark setup method: saved, scan, or manual").option("--lark-app-id <id>", "Lark app id").option("--lark-app-secret <secret>", "Lark app secret").option("--tenant <tenant>", "Manual Lark / Feishu tenant: feishu or lark").option("--lark-bot-open-id <openId>", "Lark bot open id for group mentions").option("--slack-mode <mode>", "Slack connection mode: socket_mode or events_api").option("--slack-app-token <token>", "Slack app-level token for Socket Mode").option("--slack-signing-secret <secret>", "Slack signing secret").option("--slack-bot-token <token>", "Slack bot user OAuth token").option("--slack-app-id <id>", "Slack app id").option("--slack-team-id <id>", "Slack team id").option("--slack-channel-id <id>", "Slack channel id").option("--slack-port <port>", "Local Slack Events API port").option("--github-token <token>", "GitHub token for comments and apply-1 pull requests").option("--github-webhook-secret <secret>", "GitHub webhook secret; generated when omitted").option("--github-repository <ownerRepo>", "GitHub repository as owner/repo").option("--github-webhook-path <path>", "GitHub webhook path").option("--github-port <port>", "Local GitHub webhook port").option("--github-auto-create-pr", "Create pull requests immediately after runs").option("--no-github-auto-create-pr", "Use the default apply-1 pull request flow").option("--binding <method>", "Binding method: default_project or bind_later").option("--force", "Overwrite an existing config").option("--start", "Start OpenTag immediately after setup").option("--no-start", "Do not ask to start OpenTag after setup").option("-y, --yes", "Skip setup confirmation").action(runCliAction(runSetupCommand));
+program.command("setup").description("Create a local OpenTag config").option("--platform <platform>", "Platform to configure").option("--config <path>", "Config file path").option("--project <path>", "Project checkout path").option("--language <language>", "Setup language: en or zh-CN").option("--executor <executor>", "Default executor: echo, codex, claude-code, or hermes").option("--hermes-command <command>", "Hermes CLI command").option("--hermes-profile <profile>", "Hermes profile").option("--hermes-profile-template <template>", "Hermes profile template").option("--agent-profile <profile>", "Executor-neutral agent session profile").option("--agent-profile-template <template>", "Executor-neutral agent session profile template").option("--lark-setup <method>", "Lark setup method: saved, scan, or manual").option("--lark-app-id <id>", "Lark app id").option("--lark-app-secret <secret>", "Lark app secret").option("--tenant <tenant>", "Manual Lark / Feishu tenant: feishu or lark").option("--lark-bot-open-id <openId>", "Lark bot open id for group mentions").option("--slack-mode <mode>", "Slack connection mode: socket_mode or events_api").option("--slack-app-token <token>", "Slack app-level token for Socket Mode").option("--slack-signing-secret <secret>", "Slack signing secret").option("--slack-bot-token <token>", "Slack bot user OAuth token").option("--slack-app-id <id>", "Slack app id").option("--slack-team-id <id>", "Slack team id").option("--slack-channel-id <id>", "Slack channel id").option("--slack-port <port>", "Local Slack Events API port").option("--github-token <token>", "GitHub token for comments and apply-1 pull requests").option("--github-webhook-secret <secret>", "GitHub webhook secret; generated when omitted").option("--github-repository <ownerRepo>", "GitHub repository as owner/repo").option("--github-webhook-path <path>", "GitHub webhook path").option("--github-port <port>", "Local GitHub webhook port").option("--github-auto-create-pr", "Create pull requests immediately after runs").option("--no-github-auto-create-pr", "Use the default apply-1 pull request flow").option("--binding <method>", "Binding method: default_project or bind_later").option("--force", "Overwrite an existing config").option("--start", "Start OpenTag immediately after setup").option("--no-start", "Do not ask to start OpenTag after setup").option("--service", "Install and start OpenTag as a background service after setup").option("-y, --yes", "Skip setup confirmation").action(runCliAction(runSetupCommand));
 program.command("pair").description("Pair this local runner with a remote relay").option("--config <path>", "Config file path").option("--relay <url>", "Remote relay dispatcher URL").option("--no-register", "Update config without registering runner and project targets").action(runCliAction(runPairCommand));
 program.command("start").description("Start the local OpenTag stack").option("--config <path>", "Config file path").action(runCliAction(runStartCommand));
 program.command("status").description("Show the local OpenTag status").option("--config <path>", "Config file path").option("--run <runId>", "Show audit details for one run").option("--channel <provider:account/conversation>", "Show active run and queued follow-ups for one source container").action(runCliAction(runStatusCommand));
@@ -4781,7 +5095,7 @@ program.command("doctor").description("Check dispatcher, bindings, checkouts, an
 program.command("ingest").description("Ingest a local external agent progress or completion event").option("--config <path>", "Config file path").requiredOption("--run <runId>", "OpenTag run id").requiredOption("--event <event>", "Event: progress, post_llm_call, before_agent_finalize, agent_end, failed, cancelled, timed_out, or interrupted").option("--source <source>", "External agent runtime source label").option("--message <message>", "Progress or completion summary").option("--type <type>", "Progress event type").option("--idempotency-key <key>", "Stable replay-protection key for retrying the same progress event").option("--result-json <json>", "Complete run with an OpenTagRunResult JSON object").option("--conclusion <conclusion>", "Completion conclusion when --result-json is omitted").option("--summary <summary>", "Completion summary when --result-json is omitted").action(runCliAction(runIngestCommand));
 program.command("ingest-template").description("Print a shell template or manifest for local external agent hook ingest").option("--source <source>", "External agent runtime source label").option("--command <command>", "OpenTag CLI command to use in the template").option("--format <format>", "Template format: shell or manifest").action(runCliAction(runIngestTemplateCommand));
 var serviceCommand = program.command("service").description("Install and control the OpenTag background service");
-serviceCommand.command("install").description("Install the OpenTag user LaunchAgent").option("--config <path>", "Config file path").option("--max-request-body-bytes <bytes>", "Persist dispatcher request body limit in the LaunchAgent").option("--rate-limit-window-ms <ms>", "Persist dispatcher rate-limit window in the LaunchAgent").option("--rate-limit-max-requests <n>", "Persist dispatcher rate-limit max requests in the LaunchAgent").option("--rate-limit-disabled", "Persist an explicit disabled dispatcher rate-limit state in the LaunchAgent").action(runCliAction(runServiceInstallCommand));
+serviceCommand.command("install").description("Install the OpenTag background service").option("--config <path>", "Config file path").option("--max-request-body-bytes <bytes>", "Persist dispatcher request body limit in the service definition").option("--rate-limit-window-ms <ms>", "Persist dispatcher rate-limit window in the service definition").option("--rate-limit-max-requests <n>", "Persist dispatcher rate-limit max requests in the service definition").option("--rate-limit-disabled", "Persist an explicit disabled dispatcher rate-limit state in the service definition").action(runCliAction(runServiceInstallCommand));
 serviceCommand.command("start").description("Start the OpenTag background service").option("--config <path>", "Config file path").action(runCliAction(runServiceStartCommand));
 serviceCommand.command("stop").description("Stop the OpenTag background service").option("--config <path>", "Config file path").action(runCliAction(runServiceStopCommand));
 serviceCommand.command("restart").description("Restart the OpenTag background service").option("--config <path>", "Config file path").action(runCliAction(runServiceRestartCommand));