@opentag/cli 0.3.4 → 0.3.5

package/dist/commands/setup.d.ts

@@ -1,11 +1,14 @@
 import { type SetupCommandOptions, type SetupFlowDependencies } from "../setup/flow.js";
 import { type StartCommandOptions } from "../start.js";
+import { type ServiceCommandOptions } from "../service.js";
 export type { SetupCommandOptions };
 export type SetupCommandDependencies = Partial<Omit<SetupFlowDependencies, "prompts" | "scanLarkPersonalAgent">> & {
+    platform?: NodeJS.Platform;
     prompts?: SetupFlowDependencies["prompts"];
     scanLarkPersonalAgent?: SetupFlowDependencies["scanLarkPersonalAgent"];
     validateLarkCredentials?: SetupFlowDependencies["validateLarkCredentials"];
     startOpenTag?(options: StartCommandOptions): Promise<void>;
+    startOpenTagService?(options: ServiceCommandOptions): Promise<void>;
 };
 export declare function runSetupCommand(options: SetupCommandOptions, dependencies?: SetupCommandDependencies): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAI3G,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAExE,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,uBAAuB,CAAC,CAAC,GAAG;IACjH,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC3C,qBAAqB,CAAC,EAAE,qBAAqB,CAAC,uBAAuB,CAAC,CAAC;IACvE,uBAAuB,CAAC,EAAE,qBAAqB,CAAC,yBAAyB,CAAC,CAAC;IAC3E,YAAY,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D,CAAC;AAcF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,YAAY,GAAE,wBAA6B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC9H"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAI3G,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAwD,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEjH,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,uBAAuB,CAAC,CAAC,GAAG;IACjH,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC3C,qBAAqB,CAAC,EAAE,qBAAqB,CAAC,uBAAuB,CAAC,CAAC;IACvE,uBAAuB,CAAC,EAAE,qBAAqB,CAAC,yBAAyB,CAAC,CAAC;IAC3E,YAAY,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,mBAAmB,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE,CAAC;AAwDF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,YAAY,GAAE,wBAA6B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8C9H"}

package/dist/index.js

@@ -2676,6 +2676,19 @@ var launchAgentCliPath = [
   "/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;
 }
@@ -2688,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;
@@ -2700,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) {
@@ -2750,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) => {
@@ -2761,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)}`;
 }
@@ -2768,12 +2831,14 @@ 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);
@@ -2786,9 +2851,26 @@ function runLaunchctlOrThrow(dependencies, args, action) {
 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)));
 }
@@ -2810,6 +2892,38 @@ async function waitForLaunchdUnloaded(dependencies, input = {}) {
     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);
@@ -2883,46 +2997,77 @@ 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: launchAgentCliPath,
+    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) {
@@ -2940,9 +3085,17 @@ function startService(options = {}, dependencies = {}) {
   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) {
@@ -2956,28 +3109,56 @@ function stopService(options = {}, dependencies = {}) {
   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, "\\$&");
@@ -2989,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;
@@ -3045,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 {
@@ -3138,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"}`,
@@ -3153,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()] : []
@@ -3203,13 +3412,22 @@ 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 waitForLaunchdLoaded(dependencies)) {
-    throw new Error("OpenTag service start did not leave launchd loaded. Run `opentag service status` and `opentag service logs` for details.");
+  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}`);
 }
@@ -3219,21 +3437,22 @@ async function runServiceStopCommand(options, dependencies = {}) {
 }
 async function runServiceRestartCommand(options, dependencies = {}) {
   stopService(options, dependencies);
-  await waitForLaunchdUnloaded(dependencies, { timeoutMs: 1e3 });
+  await waitForServiceUnloaded(dependencies, { timeoutMs: 1e3 });
   let paths = startService(options, dependencies);
-  let loaded = await waitForLaunchdLoaded(dependencies, { timeoutMs: 500 });
+  let loaded = await waitForServiceLoaded(dependencies, { timeoutMs: 500 });
   if (!loaded) {
     paths = startService(options, dependencies);
-    loaded = await waitForLaunchdLoaded(dependencies);
+    loaded = await waitForServiceLoaded(dependencies);
   }
   if (!loaded) {
-    throw new Error("OpenTag service restart did not leave launchd loaded. Run `opentag service status` and `opentag service logs` for details.");
+    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);
@@ -4769,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) {
@@ -4798,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 {
@@ -4826,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));
@@ -4835,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));