@agent-link/agent 0.1.287 → 0.1.288

package/dist/service.js

@@ -1,20 +1,55 @@
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'fs';
+import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-import { CONFIG_DIR, getLogDir, loadRuntimeState, clearRuntimeState, killProcess, isProcessAlive, } from './config.js';
-import { getCachedPathEnvVars, warmExecPaths } from './sdk.js';
+import { CONFIG_DIR, clearRuntimeState, getLogDir, isProcessAlive, killProcess, loadRuntimeState, saveConfig, saveRuntimeState, } from './config.js';
+import { computeLaunchSpecDigest, createLaunchSpec, createServiceLaunchSpec, getServiceLaunchSpecPath, saveLaunchSpec, saveLaunchSpecSnapshot, loadLaunchSpec, } from './launch-spec.js';
+import { getCachedPathEnvVars, getResolvedExecPaths, warmExecPaths } from './sdk.js';
 const SERVICE_NAME = 'agentlink';
 const LAUNCHD_LABEL = 'com.agentlink.agent';
-export function getServiceEnvironment() {
+function getCliPath() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), 'cli.js');
+}
+function getServiceRoot() {
+    return process.env.AGENTLINK_SERVICE_ROOT
+        ? resolve(process.env.AGENTLINK_SERVICE_ROOT)
+        : null;
+}
+function isSimulation() {
+    return getServiceRoot() !== null;
+}
+export function getServiceArtifactPath(platform = process.platform) {
+    const root = getServiceRoot();
+    if (root) {
+        if (platform === 'linux')
+            return join(root, `${SERVICE_NAME}.service`);
+        if (platform === 'darwin')
+            return join(root, `${LAUNCHD_LABEL}.plist`);
+        if (platform === 'win32')
+            return join(root, `${SERVICE_NAME}.bat`);
+    }
+    if (platform === 'linux') {
+        return join(homedir(), '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
+    }
+    if (platform === 'darwin') {
+        return join(homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+    }
+    if (platform === 'win32') {
+        const startupDir = join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+        return join(startupDir, `${SERVICE_NAME}.bat`);
+    }
+    throw new Error(`Unsupported platform: ${platform}`);
+}
+export function getServiceEnvironment(hostType) {
     return {
         AGENTLINK_SERVICE: '1',
         AGENTLINK_HOME: CONFIG_DIR,
         ...getCachedPathEnvVars(),
+        ...(hostType ? { AGENTLINK_HOST_TYPE: hostType } : {}),
     };
 }
-function escapeSystemdEnvironment(value) {
+function escapeSystemd(value) {
     return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
 }
 function escapeXml(value) {
@@ -25,154 +60,54 @@ function escapeXml(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
-function getCliPath() {
-    const __filename = fileURLToPath(import.meta.url);
-    return resolve(dirname(__filename), 'cli.js');
-}
-function getNodePath() {
-    return process.execPath;
+function quoteSystemd(value) {
+    return `"${escapeSystemd(value)}"`;
 }
-/** Build extra CLI args string for password (used in systemd/bat templates). */
-function buildExtraArgs(config) {
-    let args = '';
-    if (config.password)
-        args += ` --password "${config.password}"`;
-    if (config.msentra)
-        args += ' --msentra';
-    else if (config.entra)
-        args += ' --entra';
-    return args;
-}
-/** Build extra plist <string> entries for password (used in launchd template). */
-function buildPlistExtraArgs(config) {
-    let entries = '';
-    if (config.password) {
-        entries += `        <string>--password</string>\n        <string>${config.password}</string>\n`;
-    }
-    if (config.msentra) {
-        entries += `        <string>--msentra</string>\n`;
-    }
-    else if (config.entra) {
-        entries += `        <string>--entra</string>\n`;
+function renderEnvironment(environment, format) {
+    if (format === 'systemd') {
+        return Object.entries(environment)
+            .map(([name, value]) => `Environment="${name}=${escapeSystemd(value)}"`)
+            .join('\n');
     }
-    return entries;
-}
-// ── Linux (systemd) ──
-function isRoot() {
-    return process.getuid?.() === 0;
-}
-function getSystemdUnitPath() {
-    if (isRoot()) {
-        return join('/etc/systemd/system', `${SERVICE_NAME}.service`);
+    if (format === 'xml') {
+        return Object.entries(environment)
+            .map(([name, value]) => `        <key>${escapeXml(name)}</key>\n        <string>${escapeXml(value)}</string>`)
+            .join('\n');
     }
-    return join(homedir(), '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
-}
-function systemctl(...args) {
-    const cmd = isRoot()
-        ? `systemctl ${args.join(' ')}`
-        : `systemctl --user ${args.join(' ')}`;
-    execSync(cmd);
+    return Object.entries(environment)
+        .map(([name, value]) => `set "${name}=${value.replace(/%/g, '%%')}"`)
+        .join('\r\n');
 }
-function generateSystemdUnit(config) {
-    const nodePath = getNodePath();
+export function renderServiceArtifact(spec, specPath, platform = process.platform) {
+    const nodePath = process.execPath;
     const cliPath = getCliPath();
     const logDir = getLogDir();
-    const nodeBinDir = dirname(nodePath);
-    const extraArgs = buildExtraArgs(config);
-    const userSection = isRoot()
-        ? ''
-        : `Environment=PATH=${nodeBinDir}:${homedir()}/.local/bin:${homedir()}/.npm-global/bin:/usr/local/bin:/usr/bin:/bin\n`;
-    const environment = {
-        ...getServiceEnvironment(),
-        AGENTLINK_HOST_TYPE: 'systemd',
-    };
-    const environmentSection = Object.entries(environment)
-        .map(([name, value]) => `Environment="${name}=${escapeSystemdEnvironment(value)}"`)
-        .join('\n');
-    return `[Unit]
+    const environment = getServiceEnvironment(spec.host.type);
+    if (platform === 'linux') {
+        return `[Unit]
 Description=AgentLink Agent
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${nodePath} ${cliPath} start --server "${config.server}" --dir "${config.dir}" --name "${config.name}"${extraArgs}
-WorkingDirectory=${config.dir}
+ExecStart=${quoteSystemd(nodePath)} ${quoteSystemd(cliPath)} start --launch-spec ${quoteSystemd(specPath)}
+WorkingDirectory=${quoteSystemd(spec.config.dir)}
 Restart=on-failure
 RestartSec=10
-${environmentSection}
-${userSection}StandardOutput=append:${logDir}/agent.log
+${renderEnvironment(environment, 'systemd')}
+StandardOutput=append:${logDir}/agent.log
 StandardError=append:${logDir}/agent.err
 
 [Install]
-WantedBy=${isRoot() ? 'multi-user.target' : 'default.target'}
+WantedBy=default.target
 `;
-}
-function linuxInstall(config) {
-    const unitPath = getSystemdUnitPath();
-    mkdirSync(dirname(unitPath), { recursive: true });
-    mkdirSync(getLogDir(), { recursive: true });
-    writeFileSync(unitPath, generateSystemdUnit(config));
-    systemctl('daemon-reload');
-    systemctl('enable', SERVICE_NAME);
-    // Only start via systemd if no agent is already running
-    const state = loadRuntimeState();
-    if (state?.pid && isProcessAlive(state.pid)) {
-        console.log(`Agent is already running (PID ${state.pid}). Skipping start.`);
-        console.log(`Service will manage the agent on next boot.`);
     }
-    else {
-        systemctl('start', SERVICE_NAME);
-    }
-    const scope = isRoot() ? 'system' : 'user';
-    const ctl = isRoot() ? 'systemctl' : 'systemctl --user';
-    const jctl = isRoot() ? 'journalctl' : 'journalctl --user';
-    console.log(`Service installed and started (${scope}-level).`);
-    console.log(`\nUnit file: ${unitPath}`);
-    console.log('\nUseful commands:');
-    console.log(`  ${ctl} status ${SERVICE_NAME}`);
-    console.log(`  ${jctl} -u ${SERVICE_NAME} -f`);
-    if (!isRoot()) {
-        console.log('\nTo run when not logged in:');
-        console.log('  sudo loginctl enable-linger $(whoami)');
-    }
-}
-function linuxUninstall() {
-    try {
-        systemctl('stop', `${SERVICE_NAME} 2>/dev/null`);
-    }
-    catch { }
-    try {
-        systemctl('disable', `${SERVICE_NAME} 2>/dev/null`);
-    }
-    catch { }
-    const unitPath = getSystemdUnitPath();
-    if (existsSync(unitPath)) {
-        unlinkSync(unitPath);
-    }
-    try {
-        systemctl('daemon-reload');
-    }
-    catch { }
-    console.log('Service uninstalled.');
-}
-// ── macOS (launchd plist) ──
-function getLaunchdPlistPath() {
-    return join(homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
-}
-function generateLaunchdPlist(config) {
-    const nodePath = getNodePath();
-    const cliPath = getCliPath();
-    const logDir = getLogDir();
-    const extraEntries = buildPlistExtraArgs(config);
-    const environment = {
-        ...getServiceEnvironment(),
-        AGENTLINK_HOST_TYPE: 'launchd',
-    };
-    const environmentEntries = Object.entries(environment)
-        .map(([name, value]) => `        <key>${name}</key>\n        <string>${escapeXml(value)}</string>`)
-        .join('\n');
-    return `<?xml version="1.0" encoding="UTF-8"?>
+    if (platform === 'darwin') {
+        const args = [nodePath, cliPath, 'start', '--launch-spec', specPath]
+            .map(value => `        <string>${escapeXml(value)}</string>`)
+            .join('\n');
+        return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
@@ -180,21 +115,13 @@ function generateLaunchdPlist(config) {
     <string>${LAUNCHD_LABEL}</string>
     <key>ProgramArguments</key>
     <array>
-        <string>${nodePath}</string>
-        <string>${cliPath}</string>
-        <string>start</string>
-        <string>--server</string>
-        <string>${config.server}</string>
-        <string>--dir</string>
-        <string>${config.dir}</string>
-        <string>--name</string>
-        <string>${config.name}</string>
-${extraEntries}    </array>
+${args}
+    </array>
     <key>WorkingDirectory</key>
-    <string>${config.dir}</string>
+    <string>${escapeXml(spec.config.dir)}</string>
     <key>EnvironmentVariables</key>
     <dict>
-${environmentEntries}
+${renderEnvironment(environment, 'xml')}
     </dict>
     <key>RunAtLoad</key>
     <true/>
@@ -206,151 +133,324 @@ ${environmentEntries}
     <key>ThrottleInterval</key>
     <integer>10</integer>
     <key>StandardOutPath</key>
-    <string>${logDir}/agent.log</string>
+    <string>${escapeXml(join(logDir, 'agent.log'))}</string>
     <key>StandardErrorPath</key>
-    <string>${logDir}/agent.err</string>
+    <string>${escapeXml(join(logDir, 'agent.err'))}</string>
 </dict>
 </plist>
 `;
+    }
+    if (platform === 'win32') {
+        return `@echo off\r\n${renderEnvironment(environment, 'bat')}\r\n"${nodePath}" "${cliPath}" start --launch-spec "${specPath}"\r\n`;
+    }
+    throw new Error(`Unsupported platform: ${platform}`);
 }
-function macInstall(config) {
-    const plistPath = getLaunchdPlistPath();
-    mkdirSync(dirname(plistPath), { recursive: true });
-    mkdirSync(getLogDir(), { recursive: true });
-    if (existsSync(plistPath)) {
-        try {
-            execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+function writeTextAtomic(filePath, content) {
+    const previous = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null;
+    if (previous === content)
+        return false;
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    writeFileSync(tempPath, content, { encoding: 'utf8', mode: 0o600 });
+    try {
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+    return true;
+}
+function runSystemctl(args) {
+    execFileSync('systemctl', ['--user', ...args], { stdio: 'ignore' });
+}
+function getLaunchdTarget() {
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        throw new Error('launchd user id is unavailable');
+    return `gui/${uid}/${LAUNCHD_LABEL}`;
+}
+function getLegacySystemdUnitPath() {
+    return process.env.AGENTLINK_LEGACY_SYSTEMD_UNIT
+        ? resolve(process.env.AGENTLINK_LEGACY_SYSTEMD_UNIT)
+        : join('/etc', 'systemd', 'system', `${SERVICE_NAME}.service`);
+}
+function removeLegacySystemdService(stopAgent) {
+    const legacyPath = getLegacySystemdUnitPath();
+    if (!existsSync(legacyPath))
+        return;
+    try {
+        if (stopAgent) {
+            execFileSync('systemctl', ['stop', SERVICE_NAME], { stdio: 'ignore' });
         }
-        catch { }
+        execFileSync('systemctl', ['disable', SERVICE_NAME], { stdio: 'ignore' });
+        unlinkSync(legacyPath);
+        execFileSync('systemctl', ['daemon-reload'], { stdio: 'ignore' });
     }
-    writeFileSync(plistPath, generateLaunchdPlist(config));
-    // Only load/start via launchd if no agent is already running
-    const state = loadRuntimeState();
-    if (state?.pid && isProcessAlive(state.pid)) {
-        console.log('Service installed. Agent is already running — skipping start.');
-        console.log(`Service will manage the agent on next boot.`);
+    catch {
+        throw new Error(`Cannot disable legacy system-level service at ${legacyPath}; `
+            + 'run the service uninstall command with administrator privileges');
     }
-    else {
-        execSync(`launchctl load "${plistPath}"`);
-        console.log('Service installed and started.');
+}
+function startFromServiceLaunchSpec(specPath) {
+    execFileSync(process.execPath, [getCliPath(), 'start', '--launch-spec', specPath], {
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+}
+function preserveRuntimeServiceSpecBeforeReplace(nextSpec) {
+    const state = loadRuntimeState();
+    const serviceSpecPath = getServiceLaunchSpecPath();
+    if (!state?.launchSpecPath
+        || resolve(state.launchSpecPath) !== resolve(serviceSpecPath)
+        || !existsSync(serviceSpecPath)) {
+        return;
     }
-    console.log(`\nPlist file: ${plistPath}`);
-    console.log('\nUseful commands:');
-    console.log(`  launchctl list | grep ${LAUNCHD_LABEL}`);
+    const currentSpec = loadLaunchSpec(serviceSpecPath);
+    if (JSON.stringify(currentSpec) === JSON.stringify(nextSpec))
+        return;
+    const launchSpecPath = saveLaunchSpecSnapshot(currentSpec);
+    saveRuntimeState({
+        ...state,
+        launchSpecPath,
+        launchSpecDigest: computeLaunchSpecDigest(currentSpec),
+    });
 }
-function macUninstall() {
-    const plistPath = getLaunchdPlistPath();
-    if (existsSync(plistPath)) {
-        try {
-            execSync(`launchctl unload "${plistPath}"`);
+export function installServiceLaunchSpec(source, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === 'linux' && !isSimulation() && existsSync(getLegacySystemdUnitPath())) {
+        throw new Error(`Legacy system-level service detected at ${getLegacySystemdUnitPath()}; `
+            + 'remove it explicitly before enabling user-level auto-start');
+    }
+    const specPath = getServiceLaunchSpecPath();
+    const spec = createServiceLaunchSpec(source, platform);
+    const artifactPath = getServiceArtifactPath(platform);
+    const previousContent = existsSync(artifactPath) ? readFileSync(artifactPath, 'utf8') : null;
+    const existed = previousContent !== null;
+    const content = renderServiceArtifact(spec, specPath, platform);
+    preserveRuntimeServiceSpecBeforeReplace(spec);
+    const changed = writeTextAtomic(artifactPath, content);
+    // Write the referenced LaunchSpec only after the host entry is safely staged.
+    // If this fails, the host entry still resolves to the previous valid spec.
+    saveLaunchSpec(spec, specPath);
+    const state = loadRuntimeState();
+    const running = !!state?.pid && isProcessAlive(state.pid);
+    let pendingReload = platform === 'darwin'
+        && running
+        && existed
+        && (changed || !previousContent.includes('--launch-spec'));
+    if (!isSimulation()) {
+        if (platform === 'linux') {
+            try {
+                runSystemctl(['unmask', SERVICE_NAME]);
+            }
+            catch { /* not masked */ }
+            runSystemctl(['daemon-reload']);
+            runSystemctl(['enable', SERVICE_NAME]);
+            if (options.startIfStopped !== false && !running)
+                runSystemctl(['start', SERVICE_NAME]);
+        }
+        else if (platform === 'darwin') {
+            execFileSync('launchctl', ['enable', getLaunchdTarget()], { stdio: 'ignore' });
+            if (!running) {
+                if (existed) {
+                    try {
+                        execFileSync('launchctl', ['unload', artifactPath], { stdio: 'ignore' });
+                    }
+                    catch { /* stale/unloaded plist */ }
+                }
+                if (options.startIfStopped !== false) {
+                    execFileSync('launchctl', ['load', artifactPath], { stdio: 'ignore' });
+                }
+            }
+            else if (pendingReload) {
+                // launchd keeps the loaded job definition independently from the file.
+                // Replacing it live would terminate this agent before it could reload
+                // the job, so defer the one-time legacy migration to the next login.
+            }
+        }
+        else if (platform === 'win32') {
+            if (options.startIfStopped !== false && !running)
+                startFromServiceLaunchSpec(specPath);
+        }
+        else {
+            throw new Error(`Unsupported platform: ${platform}`);
         }
-        catch { }
-        unlinkSync(plistPath);
     }
-    console.log('Service uninstalled.');
+    if (options.persistPolicy !== false)
+        saveConfig({ autoStart: true });
+    return { artifactPath, specPath, changed, spec, pendingReload };
 }
-// ── Windows (Startup folder .bat) ──
-function getStartupBatPath() {
-    const startupDir = join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
-    return join(startupDir, `${SERVICE_NAME}.bat`);
+export function isServiceInstalled(platform = process.platform) {
+    try {
+        if (platform === 'linux' && !isSimulation() && existsSync(getLegacySystemdUnitPath())) {
+            return true;
+        }
+        return existsSync(getServiceArtifactPath(platform));
+    }
+    catch {
+        return false;
+    }
 }
-function generateStartupBat(config) {
-    const nodePath = getNodePath();
-    const cliPath = getCliPath();
-    const extraArgs = buildExtraArgs(config);
-    const environment = {
-        ...getServiceEnvironment(),
-        AGENTLINK_HOST_TYPE: 'windows-startup',
-    };
-    const environmentLines = Object.entries(environment)
-        .map(([name, value]) => `set "${name}=${value.replace(/%/g, '%%')}"`)
-        .join('\r\n');
-    return `@echo off\r\n${environmentLines}\r\n"${nodePath}" "${cliPath}" start --daemon --server "${config.server}" --dir "${config.dir}" --name "${config.name}"${extraArgs}\r\n`;
+export function serviceInstall(config) {
+    warmExecPaths();
+    const source = createLaunchSpec(config, {
+        mode: 'daemon',
+        hostType: 'standalone',
+        resolvedExecPaths: getResolvedExecPaths(),
+    });
+    const result = installServiceLaunchSpec(source, {
+        startIfStopped: true,
+        persistPolicy: true,
+    });
+    console.log('AgentLink auto-start installed.');
+    console.log(`  LaunchSpec: ${result.specPath}`);
+    console.log(`  Host entry: ${result.artifactPath}`);
 }
-function winInstall(config) {
-    mkdirSync(getLogDir(), { recursive: true });
-    const batPath = getStartupBatPath();
-    writeFileSync(batPath, generateStartupBat(config));
-    console.log('Startup script installed.');
-    console.log(`\nStartup file: ${batPath}`);
-    // Only start the agent if one isn't already running
+export function serviceUninstall(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const artifactPath = getServiceArtifactPath(platform);
+    const stopAgent = options.stopAgent !== false;
     const state = loadRuntimeState();
-    if (state?.pid && isProcessAlive(state.pid)) {
-        console.log(`\nAgent is already running (PID ${state.pid}). Skipping start.`);
-        console.log(`  URL: ${state.sessionUrl}`);
+    const running = !!state?.pid && isProcessAlive(state.pid);
+    const serviceSpecPath = getServiceLaunchSpecPath();
+    const runtimeUsesServiceSpec = !!state?.launchSpecPath
+        && resolve(state.launchSpecPath) === resolve(serviceSpecPath)
+        && existsSync(serviceSpecPath);
+    let pendingReload = platform === 'darwin'
+        && !stopAgent
+        && running
+        && runtimeUsesServiceSpec
+        && existsSync(artifactPath);
+    const preserveRunningHostEntry = !stopAgent
+        && running
+        && runtimeUsesServiceSpec
+        && (platform === 'linux' || platform === 'darwin');
+    if (!isSimulation()) {
+        if (platform === 'linux') {
+            removeLegacySystemdService(stopAgent);
+            if (stopAgent) {
+                try {
+                    runSystemctl(['stop', SERVICE_NAME]);
+                }
+                catch { /* not active */ }
+            }
+            if (!stopAgent && running) {
+                // The unit file is intentionally retained for the current process and
+                // future upgrade diagnostics, so both controls must succeed before the
+                // opt-out can be recorded.
+                runSystemctl(['disable', SERVICE_NAME]);
+                runSystemctl(['mask', '--runtime', SERVICE_NAME]);
+            }
+            else {
+                try {
+                    runSystemctl(['disable', SERVICE_NAME]);
+                }
+                catch { /* not enabled */ }
+            }
+        }
+        else if (platform === 'darwin') {
+            if (stopAgent && existsSync(artifactPath)) {
+                try {
+                    execFileSync('launchctl', ['unload', artifactPath], { stdio: 'ignore' });
+                }
+                catch { /* not loaded */ }
+            }
+            else if (pendingReload) {
+                // The loaded job may continue until logout; removing the plist prevents
+                // it from loading in the next login session without killing this agent.
+            }
+            if (!stopAgent && running) {
+                execFileSync('launchctl', ['disable', getLaunchdTarget()], { stdio: 'ignore' });
+            }
+        }
+        else if (platform !== 'win32') {
+            throw new Error(`Unsupported platform: ${platform}`);
+        }
     }
-    else {
-        console.log('\nStarting agent now...');
+    if (runtimeUsesServiceSpec) {
+        const runningSpec = loadLaunchSpec(serviceSpecPath);
+        const standaloneSpec = {
+            ...runningSpec,
+            mode: 'daemon',
+            host: { type: 'standalone' },
+            config: { ...runningSpec.config },
+            runtime: {
+                ...runningSpec.runtime,
+                nodeArgs: [...runningSpec.runtime.nodeArgs],
+                resolvedExecPaths: { ...runningSpec.runtime.resolvedExecPaths },
+            },
+        };
+        const launchSpecPath = saveLaunchSpecSnapshot(standaloneSpec);
+        saveLaunchSpec(standaloneSpec);
+        saveRuntimeState({
+            ...state,
+            launchSpecPath,
+            launchSpecDigest: computeLaunchSpecDigest(standaloneSpec),
+        });
+    }
+    if (!preserveRunningHostEntry) {
+        if (existsSync(artifactPath))
+            unlinkSync(artifactPath);
+        if (existsSync(serviceSpecPath))
+            unlinkSync(serviceSpecPath);
+    }
+    if (!isSimulation() && platform === 'linux') {
         try {
-            execSync(`"${getNodePath()}" "${getCliPath()}" start --daemon --server "${config.server}" --dir "${config.dir}" --name "${config.name}"${buildExtraArgs(config)}`, { stdio: 'inherit', windowsHide: true });
+            runSystemctl(['daemon-reload']);
         }
-        catch {
-            console.error('Failed to start agent. Check logs in ~/.agentlink/logs/');
+        catch { /* unit already gone */ }
+    }
+    if (stopAgent) {
+        if (state?.pid && isProcessAlive(state.pid)) {
+            killProcess(state.pid);
+            clearRuntimeState();
         }
     }
-}
-function winUninstall() {
-    const batPath = getStartupBatPath();
-    if (existsSync(batPath)) {
-        unlinkSync(batPath);
-        console.log(`Removed startup file: ${batPath}`);
+    if (options.persistPolicy !== false) {
+        saveConfig({ autoStart: false, autoStartPendingReload: pendingReload || undefined });
     }
-    // Stop running agent if any
-    const state = loadRuntimeState();
-    if (state?.pid && isProcessAlive(state.pid)) {
-        console.log(`Stopping agent (PID ${state.pid})...`);
-        killProcess(state.pid);
-        clearRuntimeState();
-    }
-    console.log('Service uninstalled.');
+    console.log(pendingReload
+        ? 'AgentLink auto-start disabled for the next login.'
+        : 'AgentLink auto-start uninstalled.');
+    return { pendingReload };
 }
-// ── Platform dispatch ──
-/** Check whether the auto-start service is already installed on this platform. */
-export function isServiceInstalled() {
-    const p = process.platform;
-    try {
-        if (p === 'linux')
-            return existsSync(getSystemdUnitPath());
-        if (p === 'darwin')
-            return existsSync(getLaunchdPlistPath());
-        if (p === 'win32')
-            return existsSync(getStartupBatPath());
+export function stopServiceForUpgrade(spec) {
+    if (isSimulation())
+        return spec.host.type === 'systemd' || spec.host.type === 'launchd';
+    if (spec.host.type === 'systemd') {
+        if (existsSync(getLegacySystemdUnitPath())) {
+            throw new Error(`Cannot upgrade legacy system-level service at ${getLegacySystemdUnitPath()}; `
+                + 'migrate it to user-level auto-start first');
+        }
+        runSystemctl(['stop', SERVICE_NAME]);
+        return true;
+    }
+    if (spec.host.type === 'launchd') {
+        const artifactPath = getServiceArtifactPath('darwin');
+        if (!existsSync(artifactPath)) {
+            throw new Error(`launchd plist not found: ${artifactPath}`);
+        }
+        execFileSync('launchctl', ['unload', artifactPath], { stdio: 'ignore' });
+        return true;
     }
-    catch { /* swallow */ }
     return false;
 }
-export function serviceInstall(config) {
-    const p = process.platform;
-    warmExecPaths();
-    console.log('Installing AgentLink service...');
-    console.log(`  Server:    ${config.server}`);
-    console.log(`  Directory: ${config.dir}`);
-    console.log(`  Name:      ${config.name}`);
-    console.log('');
-    if (p === 'linux')
-        linuxInstall(config);
-    else if (p === 'darwin')
-        macInstall(config);
-    else if (p === 'win32')
-        winInstall(config);
-    else {
-        console.error(`Unsupported platform: ${p}`);
-        console.error('Run the agent directly: agentlink-client start --daemon');
-        process.exit(1);
+export function restartServiceAfterUpgrade(spec) {
+    if (isSimulation())
+        return spec.host.type === 'systemd' || spec.host.type === 'launchd';
+    if (spec.host.type === 'systemd') {
+        if (existsSync(getLegacySystemdUnitPath())) {
+            throw new Error(`Cannot restart legacy system-level service at ${getLegacySystemdUnitPath()}; `
+                + 'migrate it to user-level auto-start first');
+        }
+        runSystemctl(['start', SERVICE_NAME]);
+        return true;
     }
-}
-export function serviceUninstall() {
-    const p = process.platform;
-    console.log('Uninstalling AgentLink service...');
-    if (p === 'linux')
-        linuxUninstall();
-    else if (p === 'darwin')
-        macUninstall();
-    else if (p === 'win32')
-        winUninstall();
-    else {
-        console.error(`Unsupported platform: ${p}`);
-        process.exit(1);
+    if (spec.host.type === 'launchd') {
+        execFileSync('launchctl', ['load', getServiceArtifactPath('darwin')], { stdio: 'ignore' });
+        return true;
     }
+    return false;
 }
 //# sourceMappingURL=service.js.map