@0xmaxma/claude-gateway 1.8.6 → 1.8.7

package/dist/cli/commands/service.js

@@ -46,31 +46,62 @@ const http_client_1 = require("../http-client");
 const prompt_1 = require("../prompt");
 const health_1 = require("../health");
 const output_1 = require("../output");
-const paths_1 = require("../../utils/paths");
 const output_2 = require("../output");
 /**
  * `service install|status|uninstall` — run the gateway under a process manager.
  *
- * systemd installs a *user* unit (`~/.config/systemd/user/`) so no privilege
- * escalation is needed and the service runs as the same user that owns
- * ~/.claude-gateway. PM2 is offered for hosts that already standardise on it.
+ * systemd defaults to installing a *user* unit (`~/.config/systemd/user/`) so no
+ * privilege escalation is needed and the service runs as the same user that owns
+ * ~/.claude-gateway. `--scope system` opts into a root-owned unit at
+ * `/etc/systemd/system/` for automated/infra provisioning that needs the gateway
+ * to run under a fixed system account — it never auto-escalates via sudo; the
+ * caller must already be root. PM2 is offered for hosts that already standardise
+ * on it (user scope only — `--scope system` is systemd-only).
  *
  * Everything the generated unit references is an absolute path resolved here
  * (node binary, entry point, config, working directory) — a unit that inherits
  * PATH or cwd from an interactive shell breaks the moment systemd starts it at
  * boot. Secrets are never written into the unit: the gateway reads
- * ~/.claude-gateway/.env itself.
+ * ~/.claude-gateway/.env itself. `--env` is for non-secret overrides only — use
+ * `--env-file` (EnvironmentFile=) to point at a file holding actual secrets.
  */
 const UNIT_NAME = 'claude-gateway.service';
 const PM2_NAME = 'gateway';
 const HEALTH_ATTEMPTS = 20;
 const HEALTH_INTERVAL_MS = 500;
-function gatewayHome() {
-    return path.join(os.homedir(), '.claude-gateway');
+/** `install`'s exit code when everything succeeded (unit written, enabled/
+ *  started) but `/health` never answered within the poll window — distinct
+ *  from `1` (install/enable itself failed, or a validation/confirmation gate
+ *  refused) so a caller checking the exit code alone, not just the JSON
+ *  result on stdout, can tell "didn't happen" apart from "happened, health
+ *  unconfirmed". */
+const EXIT_HEALTH_TIMEOUT = 2;
+/** Env var names the installer itself sets — `--env` may not override these. */
+const RESERVED_ENV_KEYS = new Set(['HOME', 'PATH', 'GATEWAY_CONFIG']);
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function gatewayHome(home = os.homedir()) {
+    return path.join(home, '.claude-gateway');
 }
-function configPath(flags) {
-    const explicit = typeof flags.config === 'string' ? flags.config : process.env.GATEWAY_CONFIG;
-    return path.resolve((0, paths_1.expandHome)(explicit ?? path.join(gatewayHome(), 'config.json')));
+/** Same `~`/`~/...` expansion as the shared `expandHome()` (src/utils/paths.ts),
+ *  but against an explicit `home` rather than always `os.homedir()`. That
+ *  shared helper is used by the server too and means "this process's own
+ *  home" everywhere else — for a `--scope system --run-as <user>` install,
+ *  this process's own home is root's, not the target user's, so a `~` in
+ *  `--config`/`--env-file` needs its own expansion here instead. */
+function expandHomeAs(p, home) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return path.join(home, p.slice(2));
+    return p;
+}
+/** `allowEnvFallback` is false for a `--scope system` install: `$GATEWAY_CONFIG`
+ *  belongs to the *installing* (root) process's environment, which has no
+ *  reliable relationship to `--run-as`'s intended config — inheriting it
+ *  would silently point the unit at a path the run-as user can't read. */
+function configPath(flags, home = os.homedir(), allowEnvFallback = true) {
+    const explicit = typeof flags.config === 'string' ? flags.config : allowEnvFallback ? process.env.GATEWAY_CONFIG : undefined;
+    return path.resolve(expandHomeAs(explicit ?? path.join(gatewayHome(home), 'config.json'), home));
 }
 /**
  * Build the PATH the service will run with.
@@ -81,13 +112,18 @@ function configPath(flags) {
  * directories the gateway actually needs — the node that will run it, the
  * `claude` binary it spawns, and the standard system paths — keeping only
  * those that exist.
+ *
+ * `home` defaults to the *installing* process's home (`os.homedir()`), but a
+ * `--scope system --run-as <user>` install passes the run-as user's home
+ * instead — a root-run install must not bake root's own `~/.local/bin` /
+ * `~/.bun/bin` into a unit that runs as someone else entirely.
  */
-function servicePath() {
+function servicePath(home = os.homedir()) {
     const candidates = [
         path.dirname(process.execPath),
         claudeBinDir(),
-        path.join(os.homedir(), '.local', 'bin'),
-        path.join(os.homedir(), '.bun', 'bin'),
+        path.join(home, '.local', 'bin'),
+        path.join(home, '.bun', 'bin'),
         '/usr/local/sbin',
         '/usr/local/bin',
         '/usr/sbin',
@@ -114,10 +150,39 @@ function claudeBinDir() {
         return null;
     }
 }
+/**
+ * `getent passwd <user>` → that user's uid/gid/home, or null if the user
+ * doesn't exist or `getent` itself isn't available. NSS-aware (works for
+ * LDAP/sssd-backed accounts, not just local `/etc/passwd` entries), which a
+ * naive `/etc/passwd` file parse would silently miss — the standard,
+ * distro-agnostic way to resolve this on Linux.
+ */
+function resolveRunAsUser(username) {
+    try {
+        const line = capture('getent', ['passwd', username]).trim();
+        // name:password:UID:GID:GECOS:directory:shell
+        const fields = line.split(':');
+        const uid = Number(fields[2]);
+        const gid = Number(fields[3]);
+        const home = fields[5];
+        if (!Number.isInteger(uid) || !Number.isInteger(gid) || !home || !path.isAbsolute(home))
+            return null;
+        return { uid, gid, home };
+    }
+    catch {
+        return null;
+    }
+}
 /** Resolve the absolute launch triple (node, entry, cwd) for a generated unit.
  *  Returns null — with a message — when the entry point can't be located, so a
- *  broken install never produces a unit that silently fails at boot. */
-function resolveLaunchSpec(flags) {
+ *  broken install never produces a unit that silently fails at boot.
+ *
+ *  `home` defaults to the installing process's own home. A `--scope system
+ *  --run-as <user>` install passes that user's real home instead — the unit
+ *  runs as them (`User=<user>`), so its WorkingDirectory/HOME/config path
+ *  must be theirs, not the root process that wrote the unit. `allowEnvConfig`
+ *  is false for that same case — see `configPath()`. */
+function resolveLaunchSpec(flags, home = os.homedir(), allowEnvConfig = true) {
     // dist/cli/commands/service.js → dist/entry.js, the thin dispatcher that
     // loads only the side it needs. index.js is still a working boot entry and is
     // used when a partially-updated install predates the split, so a unit is
@@ -134,10 +199,10 @@ function resolveLaunchSpec(flags) {
     return {
         node,
         entry,
-        cwd: gatewayHome(),
-        config: configPath(flags),
-        home: os.homedir(),
-        pathEnv: servicePath(),
+        cwd: gatewayHome(home),
+        config: configPath(flags, home, allowEnvConfig),
+        home,
+        pathEnv: servicePath(home),
     };
 }
 /** systemd unit values are double-quoted here, so backslashes and quotes must
@@ -145,31 +210,57 @@ function resolveLaunchSpec(flags) {
 function systemdQuote(value) {
     return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
+/** Default when a caller (or an existing test) passes no options — matches the
+ *  behavior this command had before --scope existed exactly, so `--scope user`
+ *  (or omitting it) is a strict no-op change. */
+const DEFAULT_SYSTEMD_UNIT_OPTIONS = { scope: 'user', after: [], extraEnv: {} };
 /** Pure renderer — exported so `--print` and the tests see the exact bytes that
  *  would be written to disk. */
-function renderSystemdUnit(spec) {
+function renderSystemdUnit(spec, opts = DEFAULT_SYSTEMD_UNIT_OPTIONS) {
     const q = systemdQuote;
+    const after = ['network-online.target', ...opts.after].join(' ');
+    const extraEnvLines = Object.entries(opts.extraEnv)
+        .map(([key, value]) => `Environment="${key}=${q(value)}"`)
+        .join('\n');
+    const userLine = opts.scope === 'system' && opts.runAs ? `User=${opts.runAs}\n` : '';
+    // Unquoted, like WorkingDirectory= above: EnvironmentFile= takes a single
+    // bare path (with an optional leading `-`), not a quoted value — wrapping it
+    // in quotes makes systemd read the quote character as part of the path and
+    // reject it as "not absolute" (verified with `systemd-analyze verify`).
+    const envFileLine = opts.envFile ? `EnvironmentFile=-${opts.envFile}\n` : '';
+    const wantedBy = opts.scope === 'system' ? 'multi-user.target' : 'default.target';
     return `[Unit]
 Description=Claude Gateway
 Documentation=https://github.com/0xMaxMa/claude-gateway
 Wants=network-online.target
-After=network-online.target
+After=${after}
 
 [Service]
-Type=simple
-# WorkingDirectory is deliberately unquoted, unlike every other value here:
+# exec (not simple): the unit is only considered "started" once the actual
+# execve() succeeds — simple would report started right after fork(), before
+# knowing whether ExecStart could even run at all, which reports a healthier
+# state than reality if the binary/entry can't be exec'd. No known downside
+# for a plain, long-running daemon like this.
+Type=exec
+${userLine}# WorkingDirectory is deliberately unquoted, unlike every other value here:
 # systemd takes the rest of the line as the path, and rejects a quoted one
 # ("path is not absolute"). Escaping is unnecessary for the same reason.
 WorkingDirectory=${spec.cwd}
 Environment="HOME=${q(spec.home)}"
 Environment="PATH=${q(spec.pathEnv)}"
 Environment="GATEWAY_CONFIG=${q(spec.config)}"
-ExecStart="${q(spec.node)}" "${q(spec.entry)}" gateway start --config "${q(spec.config)}"
+${extraEnvLines ? extraEnvLines + '\n' : ''}${envFileLine}ExecStart="${q(spec.node)}" "${q(spec.entry)}" gateway start --config "${q(spec.config)}"
 Restart=always
 RestartSec=5
+# Without this, systemd's default OOMPolicy=stop treats an OOM-killed
+# process ANYWHERE in this unit's cgroup (e.g. a dev server an agent spawned
+# on its own) as the whole unit failing, and Restart=always then restarts
+# the entire gateway — dropping every agent's session for an OOM kill that
+# had nothing to do with gateway health.
+OOMPolicy=continue
 
 [Install]
-WantedBy=default.target
+WantedBy=${wantedBy}
 `;
 }
 /** The exact argv `service install --manager pm2` would run. Exported for
@@ -190,8 +281,27 @@ function pm2StartArgs(spec) {
         spec.config,
     ];
 }
-function unitPath() {
-    return path.join(os.homedir(), '.config', 'systemd', 'user', UNIT_NAME);
+function unitPath(scope) {
+    return scope === 'system'
+        ? path.join('/etc', 'systemd', 'system', UNIT_NAME)
+        : path.join(os.homedir(), '.config', 'systemd', 'user', UNIT_NAME);
+}
+/** True when this process is already root. Systemd `--scope system` never
+ *  auto-escalates via sudo (unlike `gateway restart`/`stop`, which is driving
+ *  an *existing* unit rather than deciding what account a new one runs as) —
+ *  it fails fast instead, so the caller stays in control of the escalation. */
+function isRoot() {
+    return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+/** `systemctl`/`journalctl` args for the given scope. */
+function scopeCliArgs(scope) {
+    return scope === 'user' ? ['--user'] : [];
+}
+/** Same, rendered for a hint message — with a trailing space so `system`
+ *  scope (an empty args array) doesn't leave a double space before the next
+ *  word, e.g. "journalctl  -u ...". */
+function scopeHintPrefix(scope) {
+    return scope === 'user' ? '--user ' : '';
 }
 function run(file, args) {
     (0, child_process_1.execFileSync)(file, args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -240,13 +350,13 @@ async function waitForHealth(config, flags) {
     }
     return false;
 }
-// ─── systemd (user scope) ─────────────────────────────────────────────────────
+// ─── systemd ───────────────────────────────────────────────────────────────
 /** `is-enabled`/`is-active` for `UNIT_NAME` at the given scope — the query
- *  both `systemdState()` (user scope, for `service status`) and
- *  `systemScopeConflict()` (system scope, for the install-time check below)
- *  need, differing only in scope. A named boolean rather than a raw argv
- *  fragment (`['--user']`/`[]`) so a future call site passing the wrong array
- *  fails to compile instead of silently querying the wrong scope. */
+ *  both `systemdState()` (the install's own scope, for `service status`) and
+ *  `crossScopeConflict()` (the opposite scope, for the install-time check
+ *  below) need, differing only in scope. A named boolean rather than a raw
+ *  argv fragment (`['--user']`/`[]`) so a future call site passing the wrong
+ *  array fails to compile instead of silently querying the wrong scope. */
 function unitFlagState(userScope) {
     const scopeArgs = userScope ? ['--user'] : [];
     let enabled = false;
@@ -265,97 +375,372 @@ function unitFlagState(userScope) {
     }
     return { enabled, active };
 }
-function systemdState() {
-    return { installed: fs.existsSync(unitPath()), ...unitFlagState(true) };
+function systemdState(scope) {
+    return { installed: fs.existsSync(unitPath(scope)), ...unitFlagState(scope === 'user') };
 }
-function systemdStatus(flags) {
-    const state = systemdState();
-    (0, output_1.printJson)({ manager: 'systemd-user', unit: unitPath(), ...state }, flags);
+function systemdManagerLabel(scope) {
+    return scope === 'user' ? 'systemd-user' : 'systemd-system';
+}
+function systemdStatus(flags, scope) {
+    const state = systemdState(scope);
+    (0, output_1.printJson)({ manager: systemdManagerLabel(scope), unit: unitPath(scope), ...state }, flags);
     return state.active ? 0 : 1;
 }
 /**
- * True when a same-named unit already exists and is enabled or active at
- * *system* scope (`/etc/systemd/system/`) — e.g. from an externally
- * provisioned image. Installing the user-scope unit alongside it would leave
- * both `enabled`, racing for the port on the next reboot (see issue #450).
+ * True when a same-named unit already exists and is enabled or active at the
+ * scope OPPOSITE to the one being installed — e.g. installing user scope
+ * while an externally-provisioned system-scope unit is already enabled (the
+ * original case, issue #450), or installing system scope while a prior
+ * user-scope install is still active (issue #457 review — a system-scope
+ * install only ever self-checked, missing this direction entirely). Either
+ * way, two independent units end up racing for the same port on the next
+ * boot.
  *
- * Reading system scope needs no privileges: `systemctl is-enabled`/`is-active`
- * without `--user` queries it as any user, so this check costs nothing extra.
+ * Reading the opposite scope needs no privileges: `systemctl
+ * is-enabled`/`is-active` in either scope queries as any user, so this check
+ * costs nothing extra.
  */
-function systemScopeConflict() {
-    const { enabled, active } = unitFlagState(false);
+function crossScopeConflict(scope) {
+    const { enabled, active } = unitFlagState(scope === 'system');
     return enabled || active;
 }
-/** Written to stderr when `systemScopeConflict()` refuses an install — shared
+/** Written to stderr when `crossScopeConflict()` refuses an install — shared
  *  by both the pre-prompt check and the re-check right after `confirm()`
  *  below, so the two call sites can't drift into different wording. */
-function writeSystemScopeConflictRefusal() {
-    process.stderr.write(`A ${UNIT_NAME} unit already exists at system scope (/etc/systemd/system/${UNIT_NAME}) and is enabled or active.\n` +
-        `Installing a second, independent unit at user scope would race it for the port on the next reboot.\n` +
+function writeCrossScopeConflictRefusal(scope) {
+    const otherScope = scope === 'user' ? 'system' : 'user';
+    const disableHint = otherScope === 'system' ? `  sudo systemctl disable --now ${UNIT_NAME}\n` : `  systemctl --user disable --now ${UNIT_NAME}\n`;
+    process.stderr.write(`A ${UNIT_NAME} unit already exists at ${otherScope} scope (${unitPath(otherScope)}) and is enabled or active.\n` +
+        `Installing a second, independent unit at ${scope} scope would race it for the port on the next reboot.\n` +
         `Disable the existing one first, then re-run this command:\n` +
-        `  sudo systemctl disable --now ${UNIT_NAME}\n` +
+        disableHint +
         'Pass --force to install anyway.\n');
 }
-async function systemdInstall(flags, config) {
-    const spec = resolveLaunchSpec(flags);
+/** Every flag parsed below is spliced into a single line of the rendered unit
+ *  verbatim (target names, env values, the run-as user, the env-file path) —
+ *  a NUL or newline in any of them would let the caller inject an extra
+ *  directive, or a whole new `[Section]`, into unit text meant to hold one
+ *  value (NUL also throws downstream at spawn — same convention as the
+ *  settings.json value guard in src/session/process.ts). Reject outright
+ *  rather than encoding: this codebase never trusts external input without
+ *  validating it at the boundary. */
+function hasUnsafeUnitChars(value) {
+    return /[\0\r\n]/.test(value);
+}
+/** `--after <target1,target2,...>` — extra `After=` ordering targets, appended
+ *  to the unit's default `network-online.target`. Comma-separated rather than
+ *  a repeatable flag: the shared CLI parser (src/cli/args.ts) has no concept
+ *  of repeated flags accumulating into an array, and adding one there would
+ *  change every command's flag type, not just this one. */
+function parseAfterTargets(flags) {
+    const raw = flags.after;
+    if (raw === undefined)
+        return [];
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        process.stderr.write('--after requires a comma-separated list of systemd unit/target names.\n');
+        return null;
+    }
+    const targets = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    for (const target of targets) {
+        if (hasUnsafeUnitChars(target)) {
+            process.stderr.write(`Invalid --after target "${target}" — must not contain a NUL byte or line break.\n`);
+            return null;
+        }
+        // No valid systemd unit/target name contains whitespace — a space
+        // inside one comma-separated entry almost always means the caller meant
+        // two separate targets and used a space instead of a comma by mistake.
+        // Silently accepting it would splice an unintended second `After=`
+        // target in via renderSystemdUnit()'s space-join, rather than erroring
+        // on the typo.
+        if (/\s/.test(target)) {
+            process.stderr.write(`Invalid --after target "${target}" — systemd unit/target names cannot contain whitespace (use a comma to separate multiple targets).\n`);
+            return null;
+        }
+    }
+    return targets;
+}
+/** `--env KEY=VALUE[,KEY=VALUE...]` — extra `Environment=` lines. Rejects
+ *  malformed pairs and the three variable names the installer itself sets, so
+ *  a typo silently overriding HOME/PATH/GATEWAY_CONFIG fails loudly instead of
+ *  producing a unit that starts the wrong binary. Never for secrets — this
+ *  text is written straight into the unit file; point at --env-file instead. */
+function parseExtraEnv(flags) {
+    const raw = flags.env;
+    if (raw === undefined)
+        return {};
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        process.stderr.write('--env requires a comma-separated list of KEY=VALUE pairs.\n');
+        return null;
+    }
+    const out = {};
+    for (const pair of raw.split(',')) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0) {
+            process.stderr.write(`Invalid --env entry "${trimmed}" — expected KEY=VALUE.\n`);
+            return null;
+        }
+        const key = trimmed.slice(0, eq);
+        const value = trimmed.slice(eq + 1);
+        if (!ENV_KEY_RE.test(key)) {
+            process.stderr.write(`Invalid --env key "${key}" — must match [A-Za-z_][A-Za-z0-9_]*.\n`);
+            return null;
+        }
+        if (RESERVED_ENV_KEYS.has(key)) {
+            process.stderr.write(`--env cannot override "${key}" — it is set by the installer itself.\n`);
+            return null;
+        }
+        if (hasUnsafeUnitChars(value)) {
+            process.stderr.write(`Invalid --env value for "${key}" — must not contain a NUL byte or line break.\n`);
+            return null;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** `--env-file <path>` — adds `EnvironmentFile=-<path>` so a caller can feed
+ *  secrets to the unit without ever putting them in its text. `-` means
+ *  systemd tolerates the file being absent. Returns null (with a message
+ *  already on stderr) for a path containing a line break — everything else
+ *  reuses the null-on-invalid contract `resolveSystemdUnitOptions()` expects.
+ *  `home` expands a leading `~` — the --run-as user's home for a system-scope
+ *  install, not the installing (root) process's own. */
+function parseEnvFile(flags, home) {
+    const raw = flags['env-file'];
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        // Distinct from "not passed at all": the shared CLI parser (src/cli/args.ts)
+        // reads a flag with no following value (last token, or immediately
+        // followed by another flag) as boolean `true` — silently treating that as
+        // "omitted" would install with no EnvironmentFile= line while the caller
+        // believes their secrets file is wired in.
+        process.stderr.write('--env-file requires a path.\n');
+        return null;
+    }
+    const resolved = path.resolve(expandHomeAs(raw, home));
+    if (hasUnsafeUnitChars(resolved)) {
+        process.stderr.write('Invalid --env-file path — must not contain a NUL byte or line break.\n');
+        return null;
+    }
+    return resolved;
+}
+/** Validate/trim `--run-as`'s format and its combination with `scope` — not
+ *  whether the named user actually exists (that's `resolveRunAsUser()`, a
+ *  separate concern this function knows nothing about, since it also needs
+ *  no privilege but does need a subprocess call). Returns `undefined` when
+ *  `scope !== 'system'` and `--run-as` wasn't passed (the normal case), or
+ *  null (message already on stderr) on any invalid combination. Split out
+ *  from `resolveSystemdUnitOptions()` so the caller can resolve `--run-as`'s
+ *  home *before* parsing `--env-file`, which needs that home to expand a
+ *  leading `~` correctly. */
+function resolveRunAsFlag(flags, scope) {
+    if (scope !== 'system') {
+        if (flags['run-as'] !== undefined) {
+            // Loudly rejected rather than silently dropped, like every other
+            // nonsensical combination this function checks — --run-as only means
+            // anything for a unit that runs as a fixed system account.
+            process.stderr.write('--run-as only applies to --scope system.\n');
+            return null;
+        }
+        return undefined;
+    }
+    if (typeof flags['run-as'] !== 'string' || flags['run-as'].trim() === '') {
+        process.stderr.write('--scope system requires --run-as <user>.\n');
+        return null;
+    }
+    if (hasUnsafeUnitChars(flags['run-as'])) {
+        process.stderr.write('Invalid --run-as value — must not contain a NUL byte or line break.\n');
+        return null;
+    }
+    return flags['run-as'].trim();
+}
+/** Resolve and validate `--after`/`--env`/`--env-file` beyond the shared
+ *  LaunchSpec triple. Returns null (with a message already on stderr) on any
+ *  invalid input — install must never write a unit from a half-parsed flag
+ *  set. `runAs` and `home` are already resolved by the caller (see
+ *  `resolveRunAsFlag()`/`resolveRunAsUser()`). */
+function resolveSystemdUnitOptions(flags, scope, runAs, home) {
+    const after = parseAfterTargets(flags);
+    if (after === null)
+        return null;
+    const extraEnv = parseExtraEnv(flags);
+    if (extraEnv === null)
+        return null;
+    const envFile = parseEnvFile(flags, home);
+    if (envFile === null)
+        return null;
+    return { scope, runAs, after, envFile, extraEnv };
+}
+async function systemdInstall(flags, config, scope) {
+    const runAsFlag = resolveRunAsFlag(flags, scope);
+    if (runAsFlag === null)
+        return 1;
+    // A --scope system install runs this CLI as root, but the rendered unit
+    // runs the gateway as runAsFlag — WorkingDirectory/HOME/config must be
+    // *that* user's, not root's, or the process starts in the wrong place with
+    // the wrong HOME entirely (getent is a read-only NSS lookup, so this needs
+    // no privilege and can run even for a --print preview). Resolved before
+    // parsing --env-file/--config below, which need this home to expand a
+    // leading `~` against the right account.
+    let home = os.homedir();
+    let runAsIds = null;
+    if (scope === 'system' && runAsFlag) {
+        const resolved = resolveRunAsUser(runAsFlag);
+        if (!resolved) {
+            process.stderr.write(`Could not resolve --run-as ${runAsFlag} via \`getent passwd\` — does that user exist on this host?\n`);
+            return 1;
+        }
+        home = resolved.home;
+        runAsIds = { uid: resolved.uid, gid: resolved.gid };
+    }
+    const unitOpts = resolveSystemdUnitOptions(flags, scope, runAsFlag, home);
+    if (!unitOpts)
+        return 1;
+    // $GATEWAY_CONFIG belongs to the installing (root) process's own
+    // environment for a system-scope install — not reliably meaningful for
+    // runAsFlag, so it's not consulted there; only an explicit --config is.
+    const spec = resolveLaunchSpec(flags, home, scope !== 'system');
     if (!spec)
         return 1;
-    const unit = renderSystemdUnit(spec);
-    const file = unitPath();
+    const unit = renderSystemdUnit(spec, unitOpts);
+    const file = unitPath(scope);
+    const scopeArgs = scopeCliArgs(scope);
     // stderr, not stdout: stdout carries the JSON result (see printJson).
     (0, prompt_1.printFilePreview)(file, unit, (line) => process.stderr.write(line + '\n'));
     if (flags.print === true)
         return 0;
-    // Refuse by default rather than only warning: a warning a user proceeds
-    // past (or never reads) still ends up with two enabled units. Disabling the
-    // conflicting unit automatically would need sudo — deliberately outside
-    // this command's scope (see the file-level comment) — and it may belong to
-    // a provisioning system this installer has no context on, so this stops
-    // and hands back the exact command to resolve it instead.
-    if (flags.force !== true && systemScopeConflict()) {
-        writeSystemScopeConflictRefusal();
+    // The root check goes here, after the print short-circuit above, matching
+    // the crossScopeConflict() check below: both are STATE/PRIVILEGE gates
+    // unrelated to what the unit would contain, so `--print` — a pure read —
+    // must never need them just to render a preview. This is narrower than
+    // "print always succeeds": resolveSystemdUnitOptions() above (e.g. the
+    // --run-as requirement) still runs first, because without valid input
+    // there is no unit content to preview at all — print can't show bytes
+    // that could never be written.
+    if (scope === 'system' && !isRoot()) {
+        process.stderr.write(`--scope system must be run as root — it writes ${unitPath('system')} and can restart a system-wide unit.\n` +
+            'Re-run as root; this command never escalates via sudo on its own.\n');
+        return 1;
+    }
+    // Guards against installing alongside an already-enabled/active unit at the
+    // OTHER scope (either direction — see crossScopeConflict()'s doc comment).
+    // A scope's install only ever conflicts with the opposite scope, never with
+    // itself, so a repeated install of the same scope never trips this.
+    if (flags.force !== true && crossScopeConflict(scope)) {
+        writeCrossScopeConflictRefusal(scope);
         return 1;
     }
-    if (!(await confirm(flags, 'install', `Install and start ${UNIT_NAME} for user ${os.userInfo().username}?`))) {
+    const confirmQuestion = scope === 'system'
+        ? `Install and start ${UNIT_NAME} at system scope, running as ${unitOpts.runAs}?`
+        : `Install and start ${UNIT_NAME} for user ${os.userInfo().username}?`;
+    if (!(await confirm(flags, 'install', confirmQuestion))) {
         process.stderr.write('Aborted — nothing was written.\n');
         return 1;
     }
     // `confirm()` can block indefinitely on the y/N prompt — re-check right
     // before writing anything, in case a conflicting unit appeared while it
     // was waiting on the operator.
-    if (flags.force !== true && systemScopeConflict()) {
-        writeSystemScopeConflictRefusal();
+    if (flags.force !== true && crossScopeConflict(scope)) {
+        writeCrossScopeConflictRefusal(scope);
         return 1;
     }
+    // Read the state a repeated install needs to decide enable vs. restart,
+    // before anything is overwritten: whether the unit is already running, and
+    // whether its content is about to change. A `daemon-reload` alone reloads
+    // systemd's cached definition but does not restart an active unit, so a
+    // repeated install used to apply an updated unit silently kept the stale
+    // one running (issue #457) — restart explicitly when content changes under
+    // an active unit, and leave an unchanged active unit alone otherwise.
+    let previousContent;
+    try {
+        previousContent = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        // Distinct from "no prior unit" (ENOENT, the normal first-install case):
+        // any other error (e.g. EACCES) is surfaced rather than silently treated
+        // as a fresh install, matching the unlinkSync error handling below.
+        if (err.code !== 'ENOENT') {
+            process.stderr.write(`Could not read the existing unit at ${file}: ${err.message}\n`);
+            return 1;
+        }
+        previousContent = null;
+    }
+    const wasActive = unitFlagState(scope === 'user').active;
     try {
+        // A --scope system install creates this directory as root — if it didn't
+        // already exist, it comes out root-owned, and the gateway (running as
+        // runAsIds, not root) would be unable to write its pid file/logs into
+        // its own WorkingDirectory. Also reassert ownership when the directory
+        // already exists but belongs to someone other than the *current*
+        // --run-as target — e.g. a prior install used a different --run-as user
+        // and this one reassigns the service to another account — rather than
+        // only checking "did this install just create it", which missed that
+        // case entirely. A directory that already belongs to the right user is
+        // left alone (no redundant chown).
+        const cwdExisted = fs.existsSync(spec.cwd);
         fs.mkdirSync(spec.cwd, { recursive: true });
-        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-        fs.writeFileSync(file, unit, { encoding: 'utf8', mode: 0o600 });
-        run('systemctl', ['--user', 'daemon-reload']);
-        run('systemctl', ['--user', 'enable', '--now', UNIT_NAME]);
+        if (runAsIds && (!cwdExisted || fs.statSync(spec.cwd).uid !== runAsIds.uid)) {
+            fs.chownSync(spec.cwd, runAsIds.uid, runAsIds.gid);
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: scope === 'user' ? 0o700 : 0o755 });
+        fs.writeFileSync(file, unit, { encoding: 'utf8', mode: scope === 'user' ? 0o600 : 0o644 });
+        // writeFileSync's `mode` option only applies when the file is newly
+        // created — overwriting an existing one (e.g. adopting an
+        // externally-provisioned unit, or a repeated install) leaves its current
+        // permission bits untouched. chmod explicitly so the intended mode is
+        // guaranteed either way — this file can carry --env values, so its
+        // permissions are a real boundary, not cosmetic.
+        fs.chmodSync(file, scope === 'user' ? 0o600 : 0o644);
+        run('systemctl', [...scopeArgs, 'daemon-reload']);
+        if (wasActive && previousContent !== null && previousContent !== unit) {
+            // `restart` alone doesn't guarantee the unit is enabled — if it had
+            // drifted to active-but-disabled (started manually, or an
+            // externally-provisioned unit that was only ever started, not
+            // enabled), only restarting would leave it silently unable to survive
+            // the next reboot. The pre-#457 code always ran `enable --now`
+            // unconditionally on every install, which held that invariant
+            // regardless of prior state; this branch has to keep holding it too.
+            run('systemctl', [...scopeArgs, 'enable', UNIT_NAME]);
+            run('systemctl', [...scopeArgs, 'restart', UNIT_NAME]);
+        }
+        else {
+            run('systemctl', [...scopeArgs, 'enable', '--now', UNIT_NAME]);
+        }
     }
     catch (err) {
-        process.stderr.write(`Could not install or start the user service: ${err.message}\n` +
-            `Inspect it with: systemctl --user status ${UNIT_NAME} --no-pager\n`);
+        process.stderr.write(`Could not install or start the ${scope} service: ${err.message}\n` +
+            `Inspect it with: systemctl ${scopeHintPrefix(scope)}status ${UNIT_NAME} --no-pager\n`);
         return 1;
     }
     const healthy = await waitForHealth(config, flags);
-    (0, output_1.printJson)({ manager: 'systemd-user', unit: file, ...systemdState(), health: healthy ? 'up' : 'down' }, flags);
-    process.stderr.write(`Installed ${UNIT_NAME}.\n` +
-        `To keep it running after you log out: loginctl enable-linger ${os.userInfo().username}\n`);
+    (0, output_1.printJson)({ manager: systemdManagerLabel(scope), unit: file, ...systemdState(scope), health: healthy ? 'up' : 'down' }, flags);
+    process.stderr.write(scope === 'system'
+        ? `Installed ${UNIT_NAME} at system scope, running as ${unitOpts.runAs}.\n`
+        : `Installed ${UNIT_NAME}.\n` + `To keep it running after you log out: loginctl enable-linger ${os.userInfo().username}\n`);
     if (!healthy) {
-        process.stderr.write(`Service did not answer /health yet — check: journalctl --user -u ${UNIT_NAME} -n 50 --no-pager\n`);
-        return 1;
+        process.stderr.write(`Service did not answer /health yet — check: journalctl ${scopeHintPrefix(scope)}-u ${UNIT_NAME} -n 50 --no-pager\n`);
+        return EXIT_HEALTH_TIMEOUT;
     }
     return 0;
 }
-async function systemdUninstall(flags) {
-    const file = unitPath();
-    const before = systemdState();
+async function systemdUninstall(flags, scope) {
+    if (scope === 'system' && !isRoot()) {
+        process.stderr.write(`--scope system must be run as root — it removes ${unitPath('system')}.\n`);
+        return 1;
+    }
+    const file = unitPath(scope);
+    const scopeArgs = scopeCliArgs(scope);
+    const before = systemdState(scope);
     if (!before.installed && !before.enabled && !before.active) {
         // Nothing to stop — prompting to stop a service that isn't there only
         // teaches people to answer these prompts without reading them.
-        (0, output_1.printJson)({ manager: 'systemd-user', unit: file, ...before }, flags);
+        (0, output_1.printJson)({ manager: systemdManagerLabel(scope), unit: file, ...before }, flags);
         process.stderr.write(`${UNIT_NAME} is not installed — nothing to remove.\n`);
         return 0;
     }
@@ -365,7 +750,7 @@ async function systemdUninstall(flags) {
         return 1;
     }
     try {
-        run('systemctl', ['--user', 'disable', '--now', UNIT_NAME]);
+        run('systemctl', [...scopeArgs, 'disable', '--now', UNIT_NAME]);
     }
     catch {
         /* already stopped, or never installed */
@@ -380,7 +765,7 @@ async function systemdUninstall(flags) {
         }
     }
     try {
-        run('systemctl', ['--user', 'daemon-reload']);
+        run('systemctl', [...scopeArgs, 'daemon-reload']);
     }
     catch {
         /* nothing to reload without systemd */
@@ -388,10 +773,10 @@ async function systemdUninstall(flags) {
     // Report what systemd actually says, not what was intended: the disable above
     // is best-effort, and claiming a stopped service that is still running would
     // be exactly the silent failure this codebase forbids.
-    const state = systemdState();
-    (0, output_1.printJson)({ manager: 'systemd-user', unit: file, ...state }, flags);
+    const state = systemdState(scope);
+    (0, output_1.printJson)({ manager: systemdManagerLabel(scope), unit: file, ...state }, flags);
     if (state.active || state.installed) {
-        process.stderr.write(`${UNIT_NAME} is still present — check: systemctl --user status ${UNIT_NAME} --no-pager\n`);
+        process.stderr.write(`${UNIT_NAME} is still present — check: systemctl ${scopeHintPrefix(scope)}status ${UNIT_NAME} --no-pager\n`);
         return 1;
     }
     return 0;
@@ -450,7 +835,7 @@ async function pm2Install(flags, config) {
     process.stderr.write('PM2 process list saved. Run `pm2 startup` once if you also want start-on-boot.\n');
     if (!healthy) {
         process.stderr.write(`Service did not answer /health yet — check: pm2 logs ${PM2_NAME}\n`);
-        return 1;
+        return EXIT_HEALTH_TIMEOUT;
     }
     return 0;
 }
@@ -504,14 +889,15 @@ async function pm2Uninstall(flags) {
     return entry ? 1 : 0;
 }
 // ─── entry point ──────────────────────────────────────────────────────────────
-const USAGE_LINE = 'claude-gateway service <install|status|uninstall> [--manager systemd|pm2] [--config <path>] [--yes] [--print] [--force]';
+const USAGE_LINE = 'claude-gateway service <install|status|uninstall> [--manager systemd|pm2] [--scope user|system] [--run-as <user>] ' +
+    '[--after <target,...>] [--env-file <path>] [--env KEY=VALUE,...] [--config <path>] [--yes] [--print] [--force]';
 /** Pick the manager to act on when `--manager` is omitted. `status`/`uninstall`
  *  act on whatever is actually installed; `install` always defaults to systemd
  *  so it can't silently pick a different manager than the one documented. */
-function detectServiceManager(action) {
+function detectServiceManager(action, scope) {
     if (action === 'install')
         return 'systemd';
-    if (fs.existsSync(unitPath()))
+    if (fs.existsSync(unitPath(scope)))
         return 'systemd';
     try {
         if (pm2Entry())
@@ -522,23 +908,76 @@ function detectServiceManager(action) {
     }
     return 'systemd';
 }
-function parseManager(flags, action) {
+function parseManager(flags, action, scope) {
     const raw = flags.manager;
     if (raw === undefined)
-        return detectServiceManager(action);
+        return detectServiceManager(action, scope);
     if (raw === 'systemd' || raw === 'pm2')
         return raw;
     process.stderr.write('Unknown --manager. Expected systemd or pm2.\n');
     return null;
 }
+/** Pick the systemd scope to act on when `--scope` is omitted. `install`
+ *  always defaults to `user` — it must never silently write a root-owned
+ *  unit nobody explicitly asked for, no matter what already exists.
+ *  `status`/`uninstall` instead detect: prefer an installed user-scope unit,
+ *  fall back to system-scope. Without this, a bare `service status` after a
+ *  `--scope system` install silently checks the (nonexistent) user-scope path
+ *  and reports "not installed" — and `service uninstall` would report success
+ *  (exit 0) while the system-scope unit keeps running untouched (issue #457
+ *  review). Mirrors `detectServiceManager()`'s "detect what's actually there"
+ *  approach for --manager. */
+function detectServiceScope(action) {
+    if (action === 'install')
+        return 'user';
+    const userInstalled = fs.existsSync(unitPath('user'));
+    const systemInstalled = fs.existsSync(unitPath('system'));
+    // Both installed at once (e.g. a --force system-scope install alongside a
+    // still-enabled user-scope one) is exactly the state crossScopeConflict()
+    // exists to prevent — but --force means it can happen anyway. Silently
+    // picking one would leave the other's real state unreported by `status`,
+    // or untouched by `uninstall` while it reports success (issue #457
+    // review) — refuse and make the caller say which one explicitly instead.
+    if (userInstalled && systemInstalled)
+        return null;
+    if (userInstalled)
+        return 'user';
+    if (systemInstalled)
+        return 'system';
+    return 'user';
+}
+function parseScope(flags, action) {
+    const raw = flags.scope;
+    if (raw === undefined) {
+        // Scope is a systemd-only concept — skip probing for it entirely when
+        // the manager is explicitly pm2. Beyond being pointless work, treating
+        // unrelated systemd unit paths as ambiguous input to a decision pm2
+        // never uses could wrongly refuse a pm2 action over a conflict that
+        // doesn't apply to it at all.
+        if (flags.manager === 'pm2')
+            return 'user';
+        const detected = detectServiceScope(action);
+        if (detected === null) {
+            process.stderr.write(`Both a user-scope and a system-scope ${UNIT_NAME} unit are installed — pass --scope user or --scope system to say which one.\n`);
+        }
+        return detected;
+    }
+    if (raw === 'user' || raw === 'system')
+        return raw;
+    process.stderr.write('Unknown --scope. Expected user or system.\n');
+    return null;
+}
 async function runService(positionals, flags, config = {}) {
     const action = positionals[0];
     if (!action) {
         // `service --help` is a help request (0); a bare `service` is a usage error (1).
         (0, output_2.writeCommandHelp)(flags.help === true, 'service', 'run the gateway as a systemd-user or PM2 service', USAGE_LINE, [
-            '  systemd installs a user unit in ~/.config/systemd/user (no sudo).',
+            '  systemd installs a user unit in ~/.config/systemd/user (no sudo) by default.',
             '  install refuses if a claude-gateway unit already exists at system scope;',
             '  --force overrides that check.',
+            '  --scope system installs a root-owned unit in /etc/systemd/system instead —',
+            '  requires running as root already (never escalates via sudo) and --run-as <user>.',
+            '  --after, --env-file, and --env customize the generated unit further (systemd only).',
         ]);
         return flags.help === true ? 0 : 1;
     }
@@ -552,13 +991,30 @@ async function runService(positionals, flags, config = {}) {
         process.stderr.write(`--print only applies to \`service install\` (it previews what would be written).\n`);
         return 1;
     }
-    const manager = parseManager(flags, action);
+    const scope = parseScope(flags, action);
+    if (!scope)
+        return 1;
+    const manager = parseManager(flags, action, scope);
     if (!manager)
         return 1;
+    if (manager === 'pm2') {
+        if (scope === 'system') {
+            process.stderr.write('--scope system only applies to the systemd manager, not pm2.\n');
+            return 1;
+        }
+        // Every other systemd-only unit customization flag: reject rather than
+        // silently drop, so `--manager pm2 --env-file secrets.env` doesn't exit 0
+        // having wired in nothing the caller asked for.
+        const systemdOnlyFlag = ['after', 'env', 'env-file', 'run-as'].find((name) => flags[name] !== undefined);
+        if (systemdOnlyFlag) {
+            process.stderr.write(`--${systemdOnlyFlag} only applies to the systemd manager, not pm2.\n`);
+            return 1;
+        }
+    }
     if (manager === 'systemd') {
         if (action === 'install')
-            return systemdInstall(flags, config);
-        return action === 'status' ? systemdStatus(flags) : await systemdUninstall(flags);
+            return systemdInstall(flags, config, scope);
+        return action === 'status' ? systemdStatus(flags, scope) : await systemdUninstall(flags, scope);
     }
     if (action === 'install')
         return pm2Install(flags, config);