@karmaniverous/jeeves 0.6.0-6 → 0.6.0-7

package/README.md

@@ -201,6 +201,13 @@ Pre-defined marker sets: `SOUL_MARKERS`, `AGENTS_MARKERS`, and `LEGACY_TOOLS_MAR
 
 - **`getServiceUrl(serviceName, consumerName?)`** — resolves a service URL via: consumer config → core config → default port constants.
 
+## Service Management
+
+`createServiceManager(descriptor)` backs each component's `service` CLI and `{name}_service` tool (install, uninstall, start, stop, restart, status). It uses NSSM on Windows and a launchd agent on macOS. On Linux it first looks for a system unit named `<service>.service` (for example `/etc/systemd/system/jeeves-watcher.service`, the way jeeves-tools provisions managed instances):
+
+- **System unit exists:** `install` changes nothing and reports the unit (`{ existing: true, message }`). `status` reads the system unit (`systemctl is-active`). `start`, `stop` and `restart` run `sudo -n systemctl <verb> <unit>` (no sudo as root), which needs a passwordless sudoers rule for `/usr/bin/systemctl <verb> *`. When sudo refuses, the error names that rule. `uninstall` refuses, because core never removes, reloads or enables a system unit, and never creates a user unit next to one.
+- **No system unit:** core manages a user unit in `~/.config/systemd/user` with `systemctl --user`. First it checks that a user bus exists. When `XDG_RUNTIME_DIR` is unset, or `systemctl --user` cannot connect, the error gives the cause and both fixes: provision a system unit, or run `sudo loginctl enable-linger <user>`. You don't get the raw "Failed to connect to bus" error.
+
 ## Prerequisites
 
 - **Node.js >= 22** — the CLI enforces this at startup.

package/dist/cli/jeeves/index.js

@@ -140,14 +140,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.6.0-5` placeholder is replaced by
+ * The `0.6.0-7` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.6.0-5';
+const CORE_VERSION = '0.6.0-7';
 
 /**
  * Shared internal utility functions.

package/dist/cli/service/index.js

@@ -215,12 +215,130 @@ async function postJson(url, body) {
     });
 }
 
+/**
+ * Linux systemd unit detection and state queries.
+ *
+ * @remarks
+ * A service can be provisioned either as a system unit
+ * (`/etc/systemd/system/<name>.service`, as jeeves-tools does on managed
+ * instances) or as a user unit (`~/.config/systemd/user`, as
+ * `createServiceManager` does elsewhere). An existing system unit always
+ * wins: status reads it and core never creates a competing user unit.
+ *
+ * Every query here is unprivileged. Commands run through an injectable
+ * `CommandExec` so the logic can be unit tested without systemd.
+ */
+/** Default `CommandExec`: `execSync` with piped stdio and a timeout. */
+const defaultExec = (cmd) => execSync(cmd, {
+    encoding: 'utf-8',
+    timeout: 30_000,
+    stdio: ['pipe', 'pipe', 'pipe'],
+}).trim();
+/**
+ * Extract the most useful text from a failed command.
+ *
+ * @param err - Error thrown by a `CommandExec`.
+ * @returns The command's stderr when present, else the error message.
+ */
+function execErrorDetail(err) {
+    if (typeof err === 'object' && err !== null) {
+        if ('stderr' in err) {
+            const stderr = String(err.stderr).trim();
+            if (stderr)
+                return stderr;
+        }
+        if (err instanceof Error)
+            return err.message;
+    }
+    return String(err);
+}
+/**
+ * The systemd unit name for a service.
+ *
+ * @param serviceName - Service name, e.g. `jeeves-watcher`.
+ * @returns The unit name, e.g. `jeeves-watcher.service`.
+ */
+function systemdUnitName(serviceName) {
+    return `${serviceName}.service`;
+}
+/**
+ * LoadStates meaning a system unit exists. A masked unit still counts: an
+ * administrator disabled it, and a user unit must not replace it.
+ */
+const SYSTEM_UNIT_PRESENT = new Set(['loaded', 'masked']);
+/**
+ * Whether a system-level systemd unit exists for the service.
+ *
+ * @remarks
+ * Queries the system manager (no `--user`, no sudo):
+ * `systemctl show <unit> --property=LoadState --value` prints `loaded`
+ * (or `masked`) for an existing unit and `not-found` otherwise. Any failure (no
+ * systemd, no system bus) means no usable system unit.
+ *
+ * @param serviceName - Service name.
+ * @param exec - Command runner.
+ * @returns True when a system unit is loaded.
+ */
+function hasSystemUnit(serviceName, exec = defaultExec) {
+    try {
+        const loadState = exec(`systemctl show ${systemdUnitName(serviceName)} --property=LoadState --value`);
+        return SYSTEM_UNIT_PRESENT.has(loadState.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a unit's active state and map it to a `ServiceState`.
+ *
+ * @param scopeFlag - `''` for the system manager, `'--user '` for the user manager.
+ * @param unit - Unit name.
+ * @param exec - Command runner.
+ * @returns `running` when active, else `stopped`.
+ */
+function activeState(scopeFlag, unit, exec) {
+    try {
+        return exec(`systemctl ${scopeFlag}is-active ${unit}`) === 'active'
+            ? 'running'
+            : 'stopped';
+    }
+    catch {
+        // is-active exits non-zero for inactive/failed units.
+        return 'stopped';
+    }
+}
+/**
+ * Detect the state of a Linux systemd service.
+ *
+ * @remarks
+ * System unit first (`systemctl is-active <unit>`), then the user unit
+ * (`systemctl --user is-enabled` / `is-active`).
+ *
+ * @param serviceName - Service name.
+ * @param exec - Command runner.
+ * @returns The detected service state.
+ */
+function getSystemdServiceState(serviceName, exec = defaultExec) {
+    const unit = systemdUnitName(serviceName);
+    if (hasSystemUnit(serviceName, exec))
+        return activeState('', unit, exec);
+    try {
+        exec(`systemctl --user is-enabled ${unit}`);
+    }
+    catch {
+        return 'not_installed';
+    }
+    return activeState('--user ', unit, exec);
+}
+
 /**
  * Platform-aware service state detection.
  *
  * @remarks
  * Detects whether a system service is installed and running.
  * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ * On Linux an existing system unit takes precedence over a user unit
+ * (see `getSystemdServiceState`).
  */
 /**
  * Detect the state of a system service by name.
@@ -235,7 +353,7 @@ function getServiceState(serviceName) {
         case 'darwin':
             return getServiceStateMacOS(serviceName);
         default:
-            return getServiceStateLinux(serviceName);
+            return getSystemdServiceState(serviceName);
     }
 }
 /**
@@ -263,36 +381,6 @@ function getServiceStateWindows(serviceName) {
         return 'not_installed';
     }
 }
-/**
- * Linux: detect via systemd user services.
- * - `systemctl --user is-enabled {name}.service` exits non-zero = not installed
- * - `systemctl --user is-active {name}.service` returns "active" = running
- */
-function getServiceStateLinux(serviceName) {
-    try {
-        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
-            encoding: 'utf-8',
-            timeout: 5000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-    }
-    catch {
-        return 'not_installed';
-    }
-    try {
-        const output = execSync(`systemctl --user is-active ${serviceName}.service`, {
-            encoding: 'utf-8',
-            timeout: 5000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        if (output === 'active')
-            return 'running';
-        return 'stopped';
-    }
-    catch {
-        return 'stopped';
-    }
-}
 /**
  * macOS: detect via launchctl.
  * - `launchctl list {name}` exits non-zero = not installed
@@ -336,35 +424,12 @@ function isExecError(err) {
 }
 
 /**
- * Factory for platform-aware service lifecycle management.
+ * Service manager contract and shared option resolution.
  *
  * @remarks
- * Produces a `ServiceManager` that handles install, uninstall, start,
- * stop, restart, and status for system services. Delegates to NSSM
- * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * Shared by the per-platform managers built in `createServiceManager`
+ * and `createLinuxManager`.
  */
-/** Exec helper that returns stdout. */
-function run(cmd) {
-    return execSync(cmd, {
-        encoding: 'utf-8',
-        timeout: 30_000,
-        stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
-}
-/** Exec helper that suppresses errors and returns success boolean. */
-function runQuiet(cmd) {
-    try {
-        execSync(cmd, {
-            encoding: 'utf-8',
-            timeout: 30_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Resolve the effective service name from options and descriptor.
  *
@@ -388,47 +453,101 @@ function resolveConfigFilePath(descriptor, options) {
     const configDir = getComponentConfigDir(descriptor.name);
     return join(configDir, descriptor.configFileName);
 }
-/** Build a Windows NSSM service manager. */
-function createWindowsManager(descriptor) {
-    return {
-        install(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            const cfgPath = resolveConfigFilePath(descriptor, options);
-            const cmdArgs = descriptor.startCommand(cfgPath);
-            const appPath = cmdArgs[0];
-            const appArgs = cmdArgs.slice(1).join(' ');
-            run(`nssm install ${svcName} ${appPath}`);
-            if (appArgs) {
-                run(`nssm set ${svcName} AppParameters ${appArgs}`);
-            }
-            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppRotateFiles 1`);
-            run(`nssm set ${svcName} AppRotateBytes 1048576`);
-        },
-        uninstall(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`nssm stop ${svcName}`);
-            run(`nssm remove ${svcName} confirm`);
-        },
-        start(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run(`nssm start ${svcName}`);
-        },
-        stop(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run(`nssm stop ${svcName}`);
-        },
-        restart(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run(`nssm restart ${svcName}`);
-        },
-        status(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            return getServiceState(svcName);
-        },
-    };
+/**
+ * The default install result for a freshly installed service.
+ *
+ * @param svcName - Service name.
+ * @returns A non-existing install result.
+ */
+function installedResult(svcName) {
+    return { existing: false, message: `Service "${svcName}" installed.` };
+}
+
+/**
+ * Guarded access to the systemd user and system managers.
+ *
+ * @remarks
+ * - User scope: fail early with an actionable message when there is no user
+ *   bus (typical for `useradd --system` accounts without linger), instead of
+ *   surfacing systemctl's raw "Failed to connect to bus" error.
+ * - System scope: run only `systemctl start|stop|restart <unit>` through
+ *   non-interactive sudo, which is exactly what the jeeves-tools sudoers rule
+ *   for the `jeeves` user allows (`/usr/bin/systemctl stop|start|restart|status *`).
+ *   Core never writes system units, reloads or enables them.
+ */
+/** Output patterns sudo prints when a non-interactive command is refused. */
+const SUDO_REFUSED = /password is required|not allowed to execute|may not run sudo|not in the sudoers/i;
+function userLabel(env) {
+    return env.USER ?? env.LOGNAME ?? 'this user';
+}
+/**
+ * Ensure a systemd user bus is reachable before any `systemctl --user` call.
+ *
+ * @param unit - Unit being managed (for the message).
+ * @param deps - Host dependencies.
+ * @throws Error with the cause and remedies when no user bus is available.
+ */
+function assertUserBus(unit, deps) {
+    const user = userLabel(deps.env);
+    const noBus = (reason, cause) => new Error([
+        `Cannot manage ${unit} as a systemd user unit: ${reason}.`,
+        `No system unit named ${unit} exists either.`,
+        'Fix one of:',
+        `(1) have an administrator provision ${unit} as a system unit in /etc/systemd/system; it is then detected and managed with "sudo -n systemctl";`,
+        `(2) enable a user manager with "sudo loginctl enable-linger ${user}" and retry from a session where XDG_RUNTIME_DIR is set.`,
+    ].join(' '), { cause });
+    if (!deps.env.XDG_RUNTIME_DIR && !deps.env.DBUS_SESSION_BUS_ADDRESS) {
+        throw noBus(`there is no systemd user bus for "${user}" (XDG_RUNTIME_DIR is not set)`);
+    }
+    try {
+        deps.exec('systemctl --user show-environment');
+    }
+    catch (err) {
+        throw noBus(`the systemd user bus for "${user}" is unreachable (${execErrorDetail(err)})`, err);
+    }
+}
+/**
+ * Run a lifecycle verb against an existing system unit.
+ *
+ * @remarks
+ * Uses `sudo -n systemctl <verb> <unit>` (plain `systemctl` when root).
+ * `-n` makes sudo fail instead of prompting for a password.
+ *
+ * @param verb - `start`, `stop` or `restart`.
+ * @param unit - System unit name.
+ * @param deps - Host dependencies.
+ * @throws Error naming the missing sudoers rule when sudo refuses.
+ */
+function runSystemVerb(verb, unit, deps) {
+    const root = deps.isRoot();
+    const cmd = root
+        ? `systemctl ${verb} ${unit}`
+        : `sudo -n systemctl ${verb} ${unit}`;
+    try {
+        deps.exec(cmd);
+    }
+    catch (err) {
+        const detail = execErrorDetail(err);
+        if (!root && SUDO_REFUSED.test(detail)) {
+            throw new Error(`${unit} is a system unit and "${cmd}" was refused: passwordless sudo for "/usr/bin/systemctl ${verb} *" is not granted to "${userLabel(deps.env)}" (${detail}). Ask an administrator to run "sudo systemctl ${verb} ${unit}" or to grant that sudoers rule.`, { cause: err });
+        }
+        throw new Error(`"${cmd}" failed: ${detail}`, { cause: err });
+    }
 }
+
+/**
+ * Linux systemd service manager.
+ *
+ * @remarks
+ * Two scopes:
+ * - **System unit present** (e.g. `/etc/systemd/system/jeeves-watcher.service`
+ *   provisioned by jeeves-tools): install is a no-op that reports the unit,
+ *   uninstall refuses, status reads the system unit, and start/stop/restart
+ *   run `sudo -n systemctl <verb> <unit>`. Core never creates a competing
+ *   user unit.
+ * - **Otherwise**: a user unit in `~/.config/systemd/user` managed with
+ *   `systemctl --user`, after checking that a user bus exists.
+ */
 /**
  * Generate a systemd user unit file.
  *
@@ -437,7 +556,6 @@ function createWindowsManager(descriptor) {
  * @returns Unit file content.
  */
 function buildSystemdUnit(svcName, cmdArgs) {
-    const execStart = cmdArgs.join(' ');
     return [
         '[Unit]',
         `Description=${svcName}`,
@@ -445,7 +563,7 @@ function buildSystemdUnit(svcName, cmdArgs) {
         '',
         '[Service]',
         'Type=simple',
-        `ExecStart=${execStart}`,
+        `ExecStart=${cmdArgs.join(' ')}`,
         'Restart=on-failure',
         'RestartSec=5',
         '',
@@ -453,42 +571,160 @@ function buildSystemdUnit(svcName, cmdArgs) {
         'WantedBy=default.target',
     ].join('\n');
 }
-/** Build a Linux systemd service manager. */
-function createLinuxManager(descriptor) {
-    const unitDir = join(homedir(), '.config', 'systemd', 'user');
+/** Default host dependencies. */
+function defaultDeps() {
+    return {
+        exec: defaultExec,
+        env: process.env,
+        isRoot: () => process.getuid?.() === 0,
+    };
+}
+/**
+ * Build a Linux systemd service manager.
+ *
+ * @param descriptor - Component descriptor.
+ * @param deps - Host dependencies (defaults to the real host).
+ * @param unitDir - User unit directory (defaults to `~/.config/systemd/user`).
+ * @returns A `ServiceManager` for Linux.
+ */
+function createLinuxManager(descriptor, deps = defaultDeps(), unitDir = join(homedir(), '.config', 'systemd', 'user')) {
+    const exec = deps.exec;
     function unitPath(svcName) {
-        return join(unitDir, `${svcName}.service`);
+        return join(unitDir, systemdUnitName(svcName));
+    }
+    /** Run a lifecycle verb in whichever scope owns the unit. */
+    function lifecycle(verb, options) {
+        const svcName = resolveServiceName(descriptor, options);
+        const unit = systemdUnitName(svcName);
+        if (hasSystemUnit(svcName, exec)) {
+            runSystemVerb(verb, unit, deps);
+            return;
+        }
+        assertUserBus(unit, deps);
+        exec(`systemctl --user ${verb} ${unit}`);
     }
     return {
         install(options) {
             const svcName = resolveServiceName(descriptor, options);
-            const cfgPath = resolveConfigFilePath(descriptor, options);
-            const cmdArgs = descriptor.startCommand(cfgPath);
+            const unit = systemdUnitName(svcName);
+            if (hasSystemUnit(svcName, exec)) {
+                return {
+                    existing: true,
+                    message: `Service "${svcName}" is already installed as system unit ${unit}; nothing to do. Manage it with start/stop/restart (sudo -n systemctl).`,
+                };
+            }
+            assertUserBus(unit, deps);
+            const cmdArgs = descriptor.startCommand(resolveConfigFilePath(descriptor, options));
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
-            run('systemctl --user daemon-reload');
-            run(`systemctl --user enable ${svcName}.service`);
+            exec('systemctl --user daemon-reload');
+            exec(`systemctl --user enable ${unit}`);
+            return installedResult(svcName);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`systemctl --user stop ${svcName}.service`);
-            runQuiet(`systemctl --user disable ${svcName}.service`);
+            const unit = systemdUnitName(svcName);
+            if (hasSystemUnit(svcName, exec)) {
+                throw new Error(`${unit} is a system unit provisioned outside core; core will not remove it. Ask an administrator to disable and delete it.`);
+            }
+            assertUserBus(unit, deps);
+            const quiet = (cmd) => {
+                try {
+                    exec(cmd);
+                }
+                catch {
+                    // Best effort: the unit may already be stopped or disabled.
+                }
+            };
+            quiet(`systemctl --user stop ${unit}`);
+            quiet(`systemctl --user disable ${unit}`);
             const path = unitPath(svcName);
             if (existsSync(path))
                 unlinkSync(path);
-            runQuiet('systemctl --user daemon-reload');
+            quiet('systemctl --user daemon-reload');
         },
         start(options) {
+            lifecycle('start', options);
+        },
+        stop(options) {
+            lifecycle('stop', options);
+        },
+        restart(options) {
+            lifecycle('restart', options);
+        },
+        status(options) {
+            return getSystemdServiceState(resolveServiceName(descriptor, options), exec);
+        },
+    };
+}
+
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * On Linux an existing system unit is detected and managed in place
+ * (see `createLinuxManager`).
+ */
+/** Exec helper that returns stdout. */
+function run(cmd) {
+    return execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+/** Exec helper that suppresses errors and returns success boolean. */
+function runQuiet(cmd) {
+    try {
+        execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build a Windows NSSM service manager. */
+function createWindowsManager(descriptor) {
+    return {
+        install(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user start ${svcName}.service`);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            const appPath = cmdArgs[0];
+            const appArgs = cmdArgs.slice(1).join(' ');
+            run(`nssm install ${svcName} ${appPath}`);
+            if (appArgs) {
+                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+            }
+            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppRotateFiles 1`);
+            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+            return installedResult(svcName);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`nssm stop ${svcName}`);
+            run(`nssm remove ${svcName} confirm`);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm start ${svcName}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user stop ${svcName}.service`);
+            run(`nssm stop ${svcName}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user restart ${svcName}.service`);
+            run(`nssm restart ${svcName}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -542,6 +778,7 @@ function createMacOSManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             mkdirSync(agentsDir, { recursive: true });
             writeFileSync(plistPath(svcName), buildLaunchdPlist(svcName, cmdArgs));
+            return installedResult(svcName);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -848,8 +1085,11 @@ function createServiceCli(descriptor) {
         .option('-n, --name <name>', 'Service name', defaultServiceName)
         .action((opts) => {
         try {
-            svcManager.install({ name: opts.name, configPath: opts.config });
-            console.log(`Service "${opts.name}" installed.`);
+            const result = svcManager.install({
+                name: opts.name,
+                configPath: opts.config,
+            });
+            console.log(result.message);
         }
         catch (err) {
             handleCommandError('Install', err);

package/dist/index.d.ts

@@ -741,6 +741,8 @@ declare function getBindAddress(componentName?: string): string;
  * @remarks
  * Detects whether a system service is installed and running.
  * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ * On Linux an existing system unit takes precedence over a user unit
+ * (see `getSystemdServiceState`).
  */
 /** Service states returned by getServiceState. */
 type ServiceState = 'not_installed' | 'stopped' | 'running';
@@ -1582,12 +1584,11 @@ declare function saveCache(): void;
 declare function getChannelWorkspace(channelId: string, token: string, options: SlackWorkspaceOptions): Promise<string>;
 
 /**
- * Factory for platform-aware service lifecycle management.
+ * Service manager contract and shared option resolution.
  *
  * @remarks
- * Produces a `ServiceManager` that handles install, uninstall, start,
- * stop, restart, and status for system services. Delegates to NSSM
- * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * Shared by the per-platform managers built in `createServiceManager`
+ * and `createLinuxManager`.
  */
 
 /** Options for service manager commands that accept a service name override. */
@@ -1597,10 +1598,20 @@ interface ServiceManagerOptions {
     /** Override config path for install. */
     configPath?: string;
 }
+/** Outcome of {@link ServiceManager.install}. */
+interface ServiceInstallResult {
+    /**
+     * True when the service was already provisioned outside core (a Linux
+     * system unit) and install was a no-op.
+     */
+    existing: boolean;
+    /** Human-readable summary of what install did. */
+    message: string;
+}
 /** Service lifecycle manager produced by the factory. */
 interface ServiceManager {
     /** Install the service with the system service manager. */
-    install(options?: ServiceManagerOptions): void;
+    install(options?: ServiceManagerOptions): ServiceInstallResult;
     /** Uninstall the service from the system service manager. */
     uninstall(options?: ServiceManagerOptions): void;
     /** Start the service. */
@@ -1612,6 +1623,18 @@ interface ServiceManager {
     /** Query the service state. */
     status(options?: ServiceManagerOptions): ServiceState;
 }
+
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * On Linux an existing system unit is detected and managed in place
+ * (see `createLinuxManager`).
+ */
+
 /**
  * Create a platform-aware service manager from a component descriptor.
  *
@@ -1646,4 +1669,4 @@ declare function getErrorMessage(err: unknown): string;
 declare function isTransientError(err: unknown): boolean;
 
 export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, pluginToolsetOptionsSchema, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };
-export type { AccountConfig, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateStatusHandlerOptions, GoogleAuthOptions, HookRegistrationOptions, InitOptions, JeevesComponentDescriptor, ManagedBlockStampOptions, ManagedMarkers, MemoryHygieneOptions, MemoryHygieneResult, ParseManagedResult, PlatformComponent, PluginApi, PluginApiUrlResolver, PluginLifecycleApi, PluginToolsetOptions, PromptBuildContext, PromptBuildEvent, PromptBuildHandler, PromptBuildResult, PromptContextOptions, PromptContextProvider, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SkillFrontmatter, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, VersionStamp, WorkspaceConfig, WorkspaceOptions };
+export type { AccountConfig, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateStatusHandlerOptions, GoogleAuthOptions, HookRegistrationOptions, InitOptions, JeevesComponentDescriptor, ManagedBlockStampOptions, ManagedMarkers, MemoryHygieneOptions, MemoryHygieneResult, ParseManagedResult, PlatformComponent, PluginApi, PluginApiUrlResolver, PluginLifecycleApi, PluginToolsetOptions, PromptBuildContext, PromptBuildEvent, PromptBuildHandler, PromptBuildResult, PromptContextOptions, PromptContextProvider, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, ServiceAccountFileConfig, ServiceInstallResult, ServiceManager, ServiceManagerOptions, ServiceState, SkillFrontmatter, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, VersionStamp, WorkspaceConfig, WorkspaceOptions };

package/dist/index.js

@@ -142,14 +142,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.6.0-5` placeholder is replaced by
+ * The `0.6.0-7` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.6.0-5';
+const CORE_VERSION = '0.6.0-7';
 
 /**
  * Workspace and config root initialization.
@@ -1081,12 +1081,130 @@ async function postJson(url, body) {
     });
 }
 
+/**
+ * Linux systemd unit detection and state queries.
+ *
+ * @remarks
+ * A service can be provisioned either as a system unit
+ * (`/etc/systemd/system/<name>.service`, as jeeves-tools does on managed
+ * instances) or as a user unit (`~/.config/systemd/user`, as
+ * `createServiceManager` does elsewhere). An existing system unit always
+ * wins: status reads it and core never creates a competing user unit.
+ *
+ * Every query here is unprivileged. Commands run through an injectable
+ * `CommandExec` so the logic can be unit tested without systemd.
+ */
+/** Default `CommandExec`: `execSync` with piped stdio and a timeout. */
+const defaultExec = (cmd) => execSync(cmd, {
+    encoding: 'utf-8',
+    timeout: 30_000,
+    stdio: ['pipe', 'pipe', 'pipe'],
+}).trim();
+/**
+ * Extract the most useful text from a failed command.
+ *
+ * @param err - Error thrown by a `CommandExec`.
+ * @returns The command's stderr when present, else the error message.
+ */
+function execErrorDetail(err) {
+    if (typeof err === 'object' && err !== null) {
+        if ('stderr' in err) {
+            const stderr = String(err.stderr).trim();
+            if (stderr)
+                return stderr;
+        }
+        if (err instanceof Error)
+            return err.message;
+    }
+    return String(err);
+}
+/**
+ * The systemd unit name for a service.
+ *
+ * @param serviceName - Service name, e.g. `jeeves-watcher`.
+ * @returns The unit name, e.g. `jeeves-watcher.service`.
+ */
+function systemdUnitName(serviceName) {
+    return `${serviceName}.service`;
+}
+/**
+ * LoadStates meaning a system unit exists. A masked unit still counts: an
+ * administrator disabled it, and a user unit must not replace it.
+ */
+const SYSTEM_UNIT_PRESENT = new Set(['loaded', 'masked']);
+/**
+ * Whether a system-level systemd unit exists for the service.
+ *
+ * @remarks
+ * Queries the system manager (no `--user`, no sudo):
+ * `systemctl show <unit> --property=LoadState --value` prints `loaded`
+ * (or `masked`) for an existing unit and `not-found` otherwise. Any failure (no
+ * systemd, no system bus) means no usable system unit.
+ *
+ * @param serviceName - Service name.
+ * @param exec - Command runner.
+ * @returns True when a system unit is loaded.
+ */
+function hasSystemUnit(serviceName, exec = defaultExec) {
+    try {
+        const loadState = exec(`systemctl show ${systemdUnitName(serviceName)} --property=LoadState --value`);
+        return SYSTEM_UNIT_PRESENT.has(loadState.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a unit's active state and map it to a `ServiceState`.
+ *
+ * @param scopeFlag - `''` for the system manager, `'--user '` for the user manager.
+ * @param unit - Unit name.
+ * @param exec - Command runner.
+ * @returns `running` when active, else `stopped`.
+ */
+function activeState(scopeFlag, unit, exec) {
+    try {
+        return exec(`systemctl ${scopeFlag}is-active ${unit}`) === 'active'
+            ? 'running'
+            : 'stopped';
+    }
+    catch {
+        // is-active exits non-zero for inactive/failed units.
+        return 'stopped';
+    }
+}
+/**
+ * Detect the state of a Linux systemd service.
+ *
+ * @remarks
+ * System unit first (`systemctl is-active <unit>`), then the user unit
+ * (`systemctl --user is-enabled` / `is-active`).
+ *
+ * @param serviceName - Service name.
+ * @param exec - Command runner.
+ * @returns The detected service state.
+ */
+function getSystemdServiceState(serviceName, exec = defaultExec) {
+    const unit = systemdUnitName(serviceName);
+    if (hasSystemUnit(serviceName, exec))
+        return activeState('', unit, exec);
+    try {
+        exec(`systemctl --user is-enabled ${unit}`);
+    }
+    catch {
+        return 'not_installed';
+    }
+    return activeState('--user ', unit, exec);
+}
+
 /**
  * Platform-aware service state detection.
  *
  * @remarks
  * Detects whether a system service is installed and running.
  * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ * On Linux an existing system unit takes precedence over a user unit
+ * (see `getSystemdServiceState`).
  */
 /**
  * Detect the state of a system service by name.
@@ -1101,7 +1219,7 @@ function getServiceState(serviceName) {
         case 'darwin':
             return getServiceStateMacOS(serviceName);
         default:
-            return getServiceStateLinux(serviceName);
+            return getSystemdServiceState(serviceName);
     }
 }
 /**
@@ -1129,36 +1247,6 @@ function getServiceStateWindows(serviceName) {
         return 'not_installed';
     }
 }
-/**
- * Linux: detect via systemd user services.
- * - `systemctl --user is-enabled {name}.service` exits non-zero = not installed
- * - `systemctl --user is-active {name}.service` returns "active" = running
- */
-function getServiceStateLinux(serviceName) {
-    try {
-        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
-            encoding: 'utf-8',
-            timeout: 5000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-    }
-    catch {
-        return 'not_installed';
-    }
-    try {
-        const output = execSync(`systemctl --user is-active ${serviceName}.service`, {
-            encoding: 'utf-8',
-            timeout: 5000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        if (output === 'active')
-            return 'running';
-        return 'stopped';
-    }
-    catch {
-        return 'stopped';
-    }
-}
 /**
  * macOS: detect via launchctl.
  * - `launchctl list {name}` exits non-zero = not installed
@@ -1202,35 +1290,12 @@ function isExecError(err) {
 }
 
 /**
- * Factory for platform-aware service lifecycle management.
+ * Service manager contract and shared option resolution.
  *
  * @remarks
- * Produces a `ServiceManager` that handles install, uninstall, start,
- * stop, restart, and status for system services. Delegates to NSSM
- * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * Shared by the per-platform managers built in `createServiceManager`
+ * and `createLinuxManager`.
  */
-/** Exec helper that returns stdout. */
-function run$1(cmd) {
-    return execSync(cmd, {
-        encoding: 'utf-8',
-        timeout: 30_000,
-        stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
-}
-/** Exec helper that suppresses errors and returns success boolean. */
-function runQuiet(cmd) {
-    try {
-        execSync(cmd, {
-            encoding: 'utf-8',
-            timeout: 30_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Resolve the effective service name from options and descriptor.
  *
@@ -1254,47 +1319,101 @@ function resolveConfigFilePath(descriptor, options) {
     const configDir = getComponentConfigDir(descriptor.name);
     return join(configDir, descriptor.configFileName);
 }
-/** Build a Windows NSSM service manager. */
-function createWindowsManager(descriptor) {
-    return {
-        install(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            const cfgPath = resolveConfigFilePath(descriptor, options);
-            const cmdArgs = descriptor.startCommand(cfgPath);
-            const appPath = cmdArgs[0];
-            const appArgs = cmdArgs.slice(1).join(' ');
-            run$1(`nssm install ${svcName} ${appPath}`);
-            if (appArgs) {
-                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
-            }
-            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run$1(`nssm set ${svcName} AppRotateFiles 1`);
-            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
-        },
-        uninstall(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`nssm stop ${svcName}`);
-            run$1(`nssm remove ${svcName} confirm`);
-        },
-        start(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm start ${svcName}`);
-        },
-        stop(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm stop ${svcName}`);
-        },
-        restart(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm restart ${svcName}`);
-        },
-        status(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            return getServiceState(svcName);
-        },
-    };
+/**
+ * The default install result for a freshly installed service.
+ *
+ * @param svcName - Service name.
+ * @returns A non-existing install result.
+ */
+function installedResult(svcName) {
+    return { existing: false, message: `Service "${svcName}" installed.` };
+}
+
+/**
+ * Guarded access to the systemd user and system managers.
+ *
+ * @remarks
+ * - User scope: fail early with an actionable message when there is no user
+ *   bus (typical for `useradd --system` accounts without linger), instead of
+ *   surfacing systemctl's raw "Failed to connect to bus" error.
+ * - System scope: run only `systemctl start|stop|restart <unit>` through
+ *   non-interactive sudo, which is exactly what the jeeves-tools sudoers rule
+ *   for the `jeeves` user allows (`/usr/bin/systemctl stop|start|restart|status *`).
+ *   Core never writes system units, reloads or enables them.
+ */
+/** Output patterns sudo prints when a non-interactive command is refused. */
+const SUDO_REFUSED = /password is required|not allowed to execute|may not run sudo|not in the sudoers/i;
+function userLabel(env) {
+    return env.USER ?? env.LOGNAME ?? 'this user';
+}
+/**
+ * Ensure a systemd user bus is reachable before any `systemctl --user` call.
+ *
+ * @param unit - Unit being managed (for the message).
+ * @param deps - Host dependencies.
+ * @throws Error with the cause and remedies when no user bus is available.
+ */
+function assertUserBus(unit, deps) {
+    const user = userLabel(deps.env);
+    const noBus = (reason, cause) => new Error([
+        `Cannot manage ${unit} as a systemd user unit: ${reason}.`,
+        `No system unit named ${unit} exists either.`,
+        'Fix one of:',
+        `(1) have an administrator provision ${unit} as a system unit in /etc/systemd/system; it is then detected and managed with "sudo -n systemctl";`,
+        `(2) enable a user manager with "sudo loginctl enable-linger ${user}" and retry from a session where XDG_RUNTIME_DIR is set.`,
+    ].join(' '), { cause });
+    if (!deps.env.XDG_RUNTIME_DIR && !deps.env.DBUS_SESSION_BUS_ADDRESS) {
+        throw noBus(`there is no systemd user bus for "${user}" (XDG_RUNTIME_DIR is not set)`);
+    }
+    try {
+        deps.exec('systemctl --user show-environment');
+    }
+    catch (err) {
+        throw noBus(`the systemd user bus for "${user}" is unreachable (${execErrorDetail(err)})`, err);
+    }
+}
+/**
+ * Run a lifecycle verb against an existing system unit.
+ *
+ * @remarks
+ * Uses `sudo -n systemctl <verb> <unit>` (plain `systemctl` when root).
+ * `-n` makes sudo fail instead of prompting for a password.
+ *
+ * @param verb - `start`, `stop` or `restart`.
+ * @param unit - System unit name.
+ * @param deps - Host dependencies.
+ * @throws Error naming the missing sudoers rule when sudo refuses.
+ */
+function runSystemVerb(verb, unit, deps) {
+    const root = deps.isRoot();
+    const cmd = root
+        ? `systemctl ${verb} ${unit}`
+        : `sudo -n systemctl ${verb} ${unit}`;
+    try {
+        deps.exec(cmd);
+    }
+    catch (err) {
+        const detail = execErrorDetail(err);
+        if (!root && SUDO_REFUSED.test(detail)) {
+            throw new Error(`${unit} is a system unit and "${cmd}" was refused: passwordless sudo for "/usr/bin/systemctl ${verb} *" is not granted to "${userLabel(deps.env)}" (${detail}). Ask an administrator to run "sudo systemctl ${verb} ${unit}" or to grant that sudoers rule.`, { cause: err });
+        }
+        throw new Error(`"${cmd}" failed: ${detail}`, { cause: err });
+    }
 }
+
+/**
+ * Linux systemd service manager.
+ *
+ * @remarks
+ * Two scopes:
+ * - **System unit present** (e.g. `/etc/systemd/system/jeeves-watcher.service`
+ *   provisioned by jeeves-tools): install is a no-op that reports the unit,
+ *   uninstall refuses, status reads the system unit, and start/stop/restart
+ *   run `sudo -n systemctl <verb> <unit>`. Core never creates a competing
+ *   user unit.
+ * - **Otherwise**: a user unit in `~/.config/systemd/user` managed with
+ *   `systemctl --user`, after checking that a user bus exists.
+ */
 /**
  * Generate a systemd user unit file.
  *
@@ -1303,7 +1422,6 @@ function createWindowsManager(descriptor) {
  * @returns Unit file content.
  */
 function buildSystemdUnit(svcName, cmdArgs) {
-    const execStart = cmdArgs.join(' ');
     return [
         '[Unit]',
         `Description=${svcName}`,
@@ -1311,7 +1429,7 @@ function buildSystemdUnit(svcName, cmdArgs) {
         '',
         '[Service]',
         'Type=simple',
-        `ExecStart=${execStart}`,
+        `ExecStart=${cmdArgs.join(' ')}`,
         'Restart=on-failure',
         'RestartSec=5',
         '',
@@ -1319,42 +1437,160 @@ function buildSystemdUnit(svcName, cmdArgs) {
         'WantedBy=default.target',
     ].join('\n');
 }
-/** Build a Linux systemd service manager. */
-function createLinuxManager(descriptor) {
-    const unitDir = join(homedir(), '.config', 'systemd', 'user');
+/** Default host dependencies. */
+function defaultDeps() {
+    return {
+        exec: defaultExec,
+        env: process.env,
+        isRoot: () => process.getuid?.() === 0,
+    };
+}
+/**
+ * Build a Linux systemd service manager.
+ *
+ * @param descriptor - Component descriptor.
+ * @param deps - Host dependencies (defaults to the real host).
+ * @param unitDir - User unit directory (defaults to `~/.config/systemd/user`).
+ * @returns A `ServiceManager` for Linux.
+ */
+function createLinuxManager(descriptor, deps = defaultDeps(), unitDir = join(homedir(), '.config', 'systemd', 'user')) {
+    const exec = deps.exec;
     function unitPath(svcName) {
-        return join(unitDir, `${svcName}.service`);
+        return join(unitDir, systemdUnitName(svcName));
+    }
+    /** Run a lifecycle verb in whichever scope owns the unit. */
+    function lifecycle(verb, options) {
+        const svcName = resolveServiceName(descriptor, options);
+        const unit = systemdUnitName(svcName);
+        if (hasSystemUnit(svcName, exec)) {
+            runSystemVerb(verb, unit, deps);
+            return;
+        }
+        assertUserBus(unit, deps);
+        exec(`systemctl --user ${verb} ${unit}`);
     }
     return {
         install(options) {
             const svcName = resolveServiceName(descriptor, options);
-            const cfgPath = resolveConfigFilePath(descriptor, options);
-            const cmdArgs = descriptor.startCommand(cfgPath);
+            const unit = systemdUnitName(svcName);
+            if (hasSystemUnit(svcName, exec)) {
+                return {
+                    existing: true,
+                    message: `Service "${svcName}" is already installed as system unit ${unit}; nothing to do. Manage it with start/stop/restart (sudo -n systemctl).`,
+                };
+            }
+            assertUserBus(unit, deps);
+            const cmdArgs = descriptor.startCommand(resolveConfigFilePath(descriptor, options));
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
-            run$1('systemctl --user daemon-reload');
-            run$1(`systemctl --user enable ${svcName}.service`);
+            exec('systemctl --user daemon-reload');
+            exec(`systemctl --user enable ${unit}`);
+            return installedResult(svcName);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`systemctl --user stop ${svcName}.service`);
-            runQuiet(`systemctl --user disable ${svcName}.service`);
+            const unit = systemdUnitName(svcName);
+            if (hasSystemUnit(svcName, exec)) {
+                throw new Error(`${unit} is a system unit provisioned outside core; core will not remove it. Ask an administrator to disable and delete it.`);
+            }
+            assertUserBus(unit, deps);
+            const quiet = (cmd) => {
+                try {
+                    exec(cmd);
+                }
+                catch {
+                    // Best effort: the unit may already be stopped or disabled.
+                }
+            };
+            quiet(`systemctl --user stop ${unit}`);
+            quiet(`systemctl --user disable ${unit}`);
             const path = unitPath(svcName);
             if (existsSync(path))
                 unlinkSync(path);
-            runQuiet('systemctl --user daemon-reload');
+            quiet('systemctl --user daemon-reload');
+        },
+        start(options) {
+            lifecycle('start', options);
+        },
+        stop(options) {
+            lifecycle('stop', options);
+        },
+        restart(options) {
+            lifecycle('restart', options);
+        },
+        status(options) {
+            return getSystemdServiceState(resolveServiceName(descriptor, options), exec);
+        },
+    };
+}
+
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ * On Linux an existing system unit is detected and managed in place
+ * (see `createLinuxManager`).
+ */
+/** Exec helper that returns stdout. */
+function run$1(cmd) {
+    return execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+/** Exec helper that suppresses errors and returns success boolean. */
+function runQuiet(cmd) {
+    try {
+        execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build a Windows NSSM service manager. */
+function createWindowsManager(descriptor) {
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            const appPath = cmdArgs[0];
+            const appArgs = cmdArgs.slice(1).join(' ');
+            run$1(`nssm install ${svcName} ${appPath}`);
+            if (appArgs) {
+                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
+            }
+            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppRotateFiles 1`);
+            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
+            return installedResult(svcName);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`nssm stop ${svcName}`);
+            run$1(`nssm remove ${svcName} confirm`);
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run$1(`systemctl --user start ${svcName}.service`);
+            run$1(`nssm start ${svcName}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run$1(`systemctl --user stop ${svcName}.service`);
+            run$1(`nssm stop ${svcName}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run$1(`systemctl --user restart ${svcName}.service`);
+            run$1(`nssm restart ${svcName}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1408,6 +1644,7 @@ function createMacOSManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             mkdirSync(agentsDir, { recursive: true });
             writeFileSync(plistPath(svcName), buildLaunchdPlist(svcName, cmdArgs));
+            return installedResult(svcName);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1624,8 +1861,11 @@ function createServiceCli(descriptor) {
         .option('-n, --name <name>', 'Service name', defaultServiceName)
         .action((opts) => {
         try {
-            svcManager.install({ name: opts.name, configPath: opts.config });
-            console.log(`Service "${opts.name}" installed.`);
+            const result = svcManager.install({
+                name: opts.name,
+                configPath: opts.config,
+            });
+            console.log(result.message);
         }
         catch (err) {
             handleCommandError('Install', err);
@@ -2595,11 +2835,12 @@ function createPluginToolset(descriptor, options) {
                     const state = svcManager.status();
                     return Promise.resolve(ok({ service: name, state }));
                 }
+                if (action === 'install') {
+                    const { existing, message } = svcManager.install();
+                    return Promise.resolve(ok({ service: name, action, success: true, existing, message }));
+                }
                 // Call the appropriate method
                 const methodMap = {
-                    install: () => {
-                        svcManager.install();
-                    },
                     uninstall: () => {
                         svcManager.uninstall();
                     },

package/package.json

@@ -96,8 +96,7 @@
       "after:init": [
         "npm run lint",
         "npm run test",
-        "npm run knip",
-        "npm run build"
+        "npm run knip"
       ],
       "after:release": [
         "git switch -c release/${version}",
@@ -105,6 +104,7 @@
         "git switch ${branchName}"
       ],
       "after:bump": [
+        "npm run build",
         "npx git-cliff -o CHANGELOG.md",
         "npm run docs",
         "git add CHANGELOG.md"
@@ -133,7 +133,7 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.6.0-6",
+  "version": "0.6.0-7",
   "allowScripts": {
     "lefthook": true
   }