metaharness 0.4.4 → 0.4.6

package/dist/meta-proxy-service.js

@@ -21,12 +21,17 @@
 // without touching launchctl/systemctl/schtasks. That mirrors `installFromSource`
 // in meta-proxy.ts, which already takes an injected `run`.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { metaProxyBinaryPath, metaProxyDataDir } from './meta-proxy.js';
 /** Reverse-DNS label, shared by the launchd job and the scheduled task. */
 export const SERVICE_LABEL = 'one.cognitum.meta-proxy';
+function assertServiceLabel(label) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9.-]{0,127}$/.test(label)) {
+        throw new Error('Invalid service label.');
+    }
+}
 function defaultRunner(invocation) {
     const result = spawnSync(invocation.command, invocation.args, {
         encoding: 'utf8',
@@ -35,27 +40,30 @@ function defaultRunner(invocation) {
     });
     const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
     if (result.error)
-        return { ok: false, output: result.error.message };
+        return { ok: false, output: result.error.message, error: result.error.message };
     return { ok: result.status === 0, output };
 }
 // --- unit file locations ----------------------------------------------------
-export function launchAgentPath(home = homedir()) {
-    return join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+export function launchAgentPath(home = homedir(), label = SERVICE_LABEL) {
+    assertServiceLabel(label);
+    return join(home, 'Library', 'LaunchAgents', `${label}.plist`);
 }
 export function systemdUnitPath(home = homedir()) {
     return join(home, '.config', 'systemd', 'user', 'meta-proxy.service');
 }
 /** The XML definition handed to `schtasks /create /xml`. */
-export function scheduledTaskPath(home = homedir()) {
-    return join(metaProxyDataDir(home), 'meta-proxy-task.xml');
+export function scheduledTaskPath(home = homedir(), label = SERVICE_LABEL) {
+    assertServiceLabel(label);
+    const filename = label === SERVICE_LABEL ? 'meta-proxy-task.xml' : `${label}-task.xml`;
+    return join(metaProxyDataDir(home), filename);
 }
-export function serviceUnitPath(platform, home = homedir()) {
+export function serviceUnitPath(platform, home = homedir(), label = SERVICE_LABEL) {
     if (platform === 'darwin')
-        return launchAgentPath(home);
+        return launchAgentPath(home, label);
     if (platform === 'linux')
         return systemdUnitPath(home);
     if (platform === 'win32')
-        return scheduledTaskPath(home);
+        return scheduledTaskPath(home, label);
     return null;
 }
 // --- pure renderers ---------------------------------------------------------
@@ -74,16 +82,17 @@ function escapeXml(value) {
  * `proxy stop` (SIGTERM, exit 0) stay stopped — a plain `KeepAlive: true` would
  * fight the user's own stop command forever.
  */
-export function renderLaunchAgent(binaryPath, logPath) {
+export function renderLaunchAgent(binaryPath, logPath, label = SERVICE_LABEL) {
     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>
   <key>Label</key>
-  <string>${SERVICE_LABEL}</string>
+  <string>${escapeXml(label)}</string>
   <key>ProgramArguments</key>
   <array>
     <string>${escapeXml(binaryPath)}</string>
+    <string>--supervised</string>
   </array>
   <key>RunAtLoad</key>
   <true/>
@@ -118,7 +127,7 @@ After=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${binaryPath}
+ExecStart=${binaryPath} --supervised
 Restart=on-failure
 RestartSec=10
 
@@ -128,11 +137,19 @@ WantedBy=default.target
 }
 /** Task Scheduler definition — Windows has no launchd/systemd equivalent. */
 export function renderScheduledTask(binaryPath) {
-    return `<?xml version="1.0" encoding="UTF-16"?>
+    // Task Scheduler's XML importer requires its canonical BOM-marked UTF-16
+    // representation; enableMetaProxyService persists this string as utf16le.
+    return `\uFEFF<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
     <Description>Cognitum Meta-Proxy sidecar</Description>
   </RegistrationInfo>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
   <Triggers>
     <LogonTrigger>
       <Enabled>true</Enabled>
@@ -152,19 +169,20 @@ export function renderScheduledTask(binaryPath) {
   <Actions Context="Author">
     <Exec>
       <Command>${escapeXml(binaryPath)}</Command>
+      <Arguments>--supervised</Arguments>
     </Exec>
   </Actions>
 </Task>
 `;
 }
 // --- the OS commands, as data so they can be asserted -----------------------
-export function enableCommands(platform, unitPath) {
+export function enableCommands(platform, unitPath, label = SERVICE_LABEL) {
     if (platform === 'darwin') {
         // `bootstrap` is the modern replacement for `load -w`; `kickstart` starts it
         // now so the user does not have to log out and back in to get a daemon.
         return [
             { command: 'launchctl', args: ['bootstrap', `gui/${process.getuid?.() ?? 0}`, unitPath] },
-            { command: 'launchctl', args: ['kickstart', `gui/${process.getuid?.() ?? 0}/${SERVICE_LABEL}`] },
+            { command: 'launchctl', args: ['kickstart', `gui/${process.getuid?.() ?? 0}/${label}`] },
         ];
     }
     if (platform === 'linux') {
@@ -175,15 +193,15 @@ export function enableCommands(platform, unitPath) {
     }
     if (platform === 'win32') {
         return [
-            { command: 'schtasks', args: ['/create', '/tn', SERVICE_LABEL, '/xml', unitPath, '/f'] },
-            { command: 'schtasks', args: ['/run', '/tn', SERVICE_LABEL] },
+            { command: 'schtasks', args: ['/create', '/tn', label, '/xml', unitPath, '/f'] },
+            { command: 'schtasks', args: ['/run', '/tn', label] },
         ];
     }
     return [];
 }
-export function disableCommands(platform, unitPath) {
+export function disableCommands(platform, unitPath, label = SERVICE_LABEL) {
     if (platform === 'darwin') {
-        return [{ command: 'launchctl', args: ['bootout', `gui/${process.getuid?.() ?? 0}`, unitPath] }];
+        return [{ command: 'launchctl', args: ['bootout', `gui/${process.getuid?.() ?? 0}/${label}`] }];
     }
     if (platform === 'linux') {
         return [
@@ -192,22 +210,117 @@ export function disableCommands(platform, unitPath) {
         ];
     }
     if (platform === 'win32') {
-        return [{ command: 'schtasks', args: ['/delete', '/tn', SERVICE_LABEL, '/f'] }];
+        return [{ command: 'schtasks', args: ['/delete', '/tn', label, '/f'] }];
     }
     return [];
 }
+export function serviceStateCommand(platform, label = SERVICE_LABEL) {
+    if (platform === 'darwin') {
+        return { command: 'launchctl', args: ['print', `gui/${process.getuid?.() ?? 0}/${label}`] };
+    }
+    if (platform === 'linux') {
+        return {
+            command: 'systemctl',
+            args: ['--user', 'show', 'meta-proxy.service', '--property=LoadState,UnitFileState,ActiveState,MainPID'],
+        };
+    }
+    if (platform === 'win32') {
+        // schtasks renders both headings and states in the user's UI language.
+        // Query the ScheduledTasks API and serialize numeric enum/bool values so
+        // state and login enablement are authoritative and locale-neutral.
+        const script = `$task = Get-ScheduledTask -ErrorAction Stop | Where-Object { $_.TaskName -ceq '${label}' -and $_.TaskPath -eq '\\' } | Select-Object -First 1; if ($null -eq $task) { Write-Output 'TaskState=Missing'; exit 0 }; Write-Output ('TaskState=' + [int]$task.State)`;
+        return { command: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-Command', script] };
+    }
+    return null;
+}
+function knownMissingService(platform, output) {
+    const text = output.toLowerCase();
+    if (platform === 'darwin') {
+        return text.includes('could not find service') || text.includes('service not found');
+    }
+    if (platform === 'linux') {
+        return text.includes('loadstate=not-found') || text.includes('unit meta-proxy.service could not be found');
+    }
+    if (platform === 'win32') {
+        return /^taskstate=missing$/m.test(text);
+    }
+    return false;
+}
+function parseManagerState(platform, outcome, definitionPresent) {
+    if (outcome.error)
+        return { managerState: 'unknown', loaded: null, enabledAtLogin: false, running: null, pid: null };
+    if (!outcome.ok) {
+        return knownMissingService(platform, outcome.output)
+            ? { managerState: 'disabled', loaded: false, enabledAtLogin: platform === 'darwin' && definitionPresent, running: false, pid: null }
+            : { managerState: 'unknown', loaded: null, enabledAtLogin: false, running: null, pid: null };
+    }
+    if (platform === 'darwin') {
+        const pid = outcome.output.match(/\bpid\s*=\s*(\d+)/)?.[1];
+        return {
+            managerState: 'enabled',
+            loaded: true,
+            enabledAtLogin: definitionPresent,
+            running: /\bstate\s*=\s*running\b/.test(outcome.output) || pid !== undefined,
+            pid: pid ? Number.parseInt(pid, 10) : null,
+        };
+    }
+    if (platform === 'linux') {
+        if (/^LoadState=not-found$/m.test(outcome.output)) {
+            return { managerState: 'disabled', loaded: false, enabledAtLogin: false, running: false, pid: null };
+        }
+        const enabled = /^UnitFileState=(?:enabled|enabled-runtime|linked|linked-runtime)$/m.test(outcome.output);
+        const loaded = /^LoadState=loaded$/m.test(outcome.output);
+        const pidText = outcome.output.match(/^MainPID=(\d+)$/m)?.[1];
+        const pid = pidText && pidText !== '0' ? Number.parseInt(pidText, 10) : null;
+        return {
+            managerState: loaded ? 'enabled' : 'disabled',
+            loaded,
+            enabledAtLogin: enabled,
+            running: /^ActiveState=active$/m.test(outcome.output),
+            pid,
+        };
+    }
+    if (platform === 'win32') {
+        if (/^TaskState=Missing$/m.test(outcome.output)) {
+            return { managerState: 'disabled', loaded: false, enabledAtLogin: false, running: false, pid: null };
+        }
+        const state = outcome.output.match(/^TaskState=(\d+)$/m)?.[1];
+        if (state === undefined || !['0', '1', '2', '3', '4'].includes(state)) {
+            return { managerState: 'unknown', loaded: null, enabledAtLogin: false, running: null, pid: null };
+        }
+        return {
+            managerState: 'enabled',
+            loaded: true,
+            // TASK_STATE_DISABLED is the authoritative registered-but-disabled state;
+            // all other known registered states remain enabled for their triggers.
+            enabledAtLogin: state !== '1',
+            running: state === '4' ? true : state === '1' || state === '3' ? false : null,
+            pid: null,
+        };
+    }
+    return { managerState: 'unknown', loaded: null, enabledAtLogin: false, running: null, pid: null };
+}
 // --- public API -------------------------------------------------------------
-export function metaProxyServiceState(platform = process.platform, home = homedir()) {
-    const unitPath = serviceUnitPath(platform, home);
+export function metaProxyServiceState(platform = process.platform, home = homedir(), run = defaultRunner, label = SERVICE_LABEL) {
+    const unitPath = serviceUnitPath(platform, home, label);
     if (!unitPath)
-        return { supported: false, installed: false, unitPath: null };
-    return { supported: true, installed: existsSync(unitPath), unitPath };
+        return { supported: false, installed: false, unitPath: null, managerState: 'unknown', definitionPresent: false, loaded: null, enabledAtLogin: false, running: null, pid: null };
+    const definitionPresent = existsSync(unitPath);
+    const command = serviceStateCommand(platform, label);
+    const outcome = command ? run(command) : { ok: false, output: '', error: 'unsupported' };
+    const manager = parseManagerState(platform, outcome, definitionPresent);
+    return { supported: true, installed: manager.loaded === true, unitPath, definitionPresent, ...manager };
+}
+function defaultWait(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
 export function enableMetaProxyService(options = {}) {
     const home = options.home ?? homedir();
     const platform = options.platform ?? process.platform;
     const run = options.run ?? defaultRunner;
-    const unitPath = serviceUnitPath(platform, home);
+    const label = options.label ?? SERVICE_LABEL;
+    const wait = options.wait ?? defaultWait;
+    const unitPath = serviceUnitPath(platform, home, label);
     if (!unitPath) {
         return { ok: false, message: `Start-at-login is not supported on ${platform}.` };
     }
@@ -220,17 +333,193 @@ export function enableMetaProxyService(options = {}) {
     }
     const logPath = join(metaProxyDataDir(home), 'meta-proxy.log');
     const definition = platform === 'darwin'
-        ? renderLaunchAgent(binaryPath, logPath)
+        ? renderLaunchAgent(binaryPath, logPath, label)
         : platform === 'linux'
             ? renderSystemdUnit(binaryPath)
             : renderScheduledTask(binaryPath);
+    const before = metaProxyServiceState(platform, home, run, label);
+    if (before.managerState === 'unknown') {
+        return { ok: false, message: `Could not determine service-manager state; preserved ${unitPath}.`, unitPath };
+    }
+    if (before.loaded === true && !before.definitionPresent) {
+        // Something answers to our label but no owned definition exists — another
+        // installer's job, or a unit shadowing ours from a different path. On
+        // darwin/linux a failed enable from this state would be "compensated" by
+        // booting out that foreign service, so refuse up front on every platform.
+        return {
+            ok: false,
+            message: `A Meta-Proxy ${platform === 'win32' ? 'task' : 'service'} is registered without the owned definition at ${unitPath}. Inspect and remove it manually before replacement.`,
+            unitPath,
+        };
+    }
+    const persistedEncoding = platform === 'win32' ? 'utf16le' : 'utf8';
+    if (before.definitionPresent && readFileSync(unitPath, persistedEncoding) !== definition) {
+        return {
+            ok: false,
+            message: `A different Meta-Proxy service definition already exists at ${unitPath}. Disable it before replacement.`,
+            unitPath,
+        };
+    }
+    if (before.managerState === 'enabled' && before.enabledAtLogin) {
+        if (before.definitionPresent) {
+            return { ok: true, message: `Meta-Proxy is already set to start at login. Definition: ${unitPath}`, unitPath };
+        }
+        return {
+            ok: false,
+            message: `A Meta-Proxy service is already registered with a different or missing definition. Disable it before replacing ${unitPath}.`,
+            unitPath,
+        };
+    }
     mkdirSync(dirname(unitPath), { recursive: true, mode: 0o700 });
-    writeFileSync(unitPath, definition, { encoding: 'utf8', mode: 0o600 });
-    for (const invocation of enableCommands(platform, unitPath)) {
+    writeFileSync(unitPath, definition, { encoding: persistedEncoding, mode: 0o600 });
+    for (const invocation of enableCommands(platform, unitPath, label)) {
         const outcome = run(invocation);
         if (!outcome.ok) {
-            // Leave nothing half-installed: a unit file present but never loaded
-            // would make `proxy status` claim start-at-login is on when it is not.
+            const state = metaProxyServiceState(platform, home, run, label);
+            if (before.definitionPresent) {
+                // This enable started from an existing owned definition. Never erase it
+                // or stop a pre-existing active service while compensating a failed
+                // attempt to change only its login-start state.
+                if (platform === 'linux') {
+                    const restore = [];
+                    if (!before.enabledAtLogin && state.enabledAtLogin) {
+                        // Deliberately omit --now: a service that was already active must
+                        // remain active while only its prior login-enable bit is restored.
+                        restore.push({ command: 'systemctl', args: ['--user', 'disable', 'meta-proxy.service'] });
+                    }
+                    if (before.running === false && state.running === true) {
+                        restore.push({ command: 'systemctl', args: ['--user', 'stop', 'meta-proxy.service'] });
+                    }
+                    const restoreFailure = restore.map((command) => run(command)).find((result) => !result.ok);
+                    if (restoreFailure) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and restoring the prior service state failed: ${restoreFailure.output || 'command failed'}. Definition preserved at ${unitPath}.`,
+                            unitPath,
+                        };
+                    }
+                    const restored = metaProxyServiceState(platform, home, run, label);
+                    if (restored.managerState === 'unknown'
+                        || restored.enabledAtLogin !== before.enabledAtLogin
+                        || restored.running !== before.running) {
+                        return {
+                            ok: false,
+                            message: `Could not prove the prior service state was restored. Definition preserved at ${unitPath}.`,
+                            unitPath,
+                        };
+                    }
+                }
+                if (platform === 'win32' && before.loaded === false && state.loaded === true) {
+                    const cleanup = stopAndDeleteWindowsTask(home, unitPath, label, run, wait, false);
+                    if (!cleanup.ok) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and restoring the prior absent task failed: ${cleanup.message}`,
+                            unitPath,
+                        };
+                    }
+                    return {
+                        ok: false,
+                        message: `Could not enable start-at-login (${invocation.command} ${invocation.args.join(' ')}): ${outcome.output || 'command failed'}. Prior definition preserved at ${unitPath}.`,
+                        unitPath,
+                    };
+                }
+                if (platform === 'win32' && before.loaded === true && !before.enabledAtLogin) {
+                    if (state.managerState === 'unknown') {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and manager state is unknown. Prior definition preserved at ${unitPath}.`,
+                            unitPath,
+                        };
+                    }
+                    if (state.loaded === false) {
+                        const recreate = enableCommands('win32', unitPath, label)[0];
+                        const recreated = recreate ? run(recreate) : { ok: false, output: 'create command unavailable' };
+                        // `/create /f` can apply and still lose its response. Its exit
+                        // status is not authoritative; re-read before deciding whether
+                        // the prior task is still absent or available for restoration.
+                        const afterRecreate = metaProxyServiceState('win32', home, run, label);
+                        if (afterRecreate.managerState === 'unknown' || afterRecreate.loaded !== true) {
+                            return {
+                                ok: false,
+                                message: `Could not enable start-at-login and could not prove the prior disabled task was recreated: ${recreated.output || 'state mismatch'}. Definition preserved at ${unitPath}.`,
+                                unitPath,
+                            };
+                        }
+                    }
+                    const stopped = confirmWindowsTaskStopped(home, unitPath, label, run, wait);
+                    if (!stopped.ok) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and restoring the prior disabled task failed: ${stopped.message}`,
+                            unitPath,
+                        };
+                    }
+                    const disabled = run({ command: 'schtasks', args: ['/change', '/tn', label, '/disable'] });
+                    const restored = disabled.ok ? metaProxyServiceState('win32', home, run, label) : null;
+                    if (!disabled.ok || restored?.loaded !== true || restored.enabledAtLogin || restored.running !== false) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and restoring the prior disabled task failed: ${disabled.output || 'state mismatch'}. Definition preserved at ${unitPath}.`,
+                            unitPath,
+                        };
+                    }
+                    return {
+                        ok: false,
+                        message: `Could not enable start-at-login (${invocation.command} ${invocation.args.join(' ')}): ${outcome.output || 'command failed'}. Prior disabled task and definition restored at ${unitPath}.`,
+                        unitPath,
+                    };
+                }
+                if (before.loaded === false && state.managerState === 'enabled') {
+                    const cleanup = disableCommands(platform, unitPath, label)[0];
+                    const cleanupOutcome = cleanup ? run(cleanup) : { ok: false, output: 'cleanup command unavailable' };
+                    if (!cleanupOutcome.ok) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and compensating cleanup failed: ${cleanupOutcome.output || 'command failed'}. Definition preserved at ${unitPath}.`,
+                            unitPath,
+                        };
+                    }
+                }
+                return {
+                    ok: false,
+                    message: `Could not enable start-at-login (${invocation.command} ${invocation.args.join(' ')}): ${outcome.output || 'command failed'}. Definition preserved at ${unitPath}.`,
+                    unitPath,
+                };
+            }
+            if (state.managerState === 'enabled') {
+                if (platform === 'win32') {
+                    const cleanup = stopAndDeleteWindowsTask(home, unitPath, label, run, wait);
+                    if (!cleanup.ok) {
+                        return {
+                            ok: false,
+                            message: `Could not enable start-at-login and compensating cleanup failed: ${cleanup.message}`,
+                            unitPath,
+                        };
+                    }
+                    return {
+                        ok: false,
+                        message: `Could not enable start-at-login (${invocation.command} ${invocation.args.join(' ')}): ${outcome.output || 'command failed'}`,
+                    };
+                }
+                const cleanupFailures = disableCommands(platform, unitPath, label)
+                    .map((cleanup) => run(cleanup))
+                    .filter((cleanup) => !cleanup.ok);
+                if (cleanupFailures.length > 0) {
+                    return {
+                        ok: false,
+                        message: `Could not enable start-at-login and compensating cleanup failed: ${cleanupFailures.map((failure) => failure.output || 'command failed').join('; ')}. Definition preserved at ${unitPath}.`,
+                        unitPath,
+                    };
+                }
+            }
+            else if (state.managerState === 'unknown') {
+                return {
+                    ok: false,
+                    message: `Could not enable start-at-login and manager state is unknown. Definition preserved at ${unitPath}.`,
+                    unitPath,
+                };
+            }
             rmSync(unitPath, { force: true });
             return {
                 ok: false,
@@ -244,34 +533,221 @@ export function enableMetaProxyService(options = {}) {
         unitPath,
     };
 }
+function startCommand(platform, label = SERVICE_LABEL) {
+    if (platform === 'darwin')
+        return { command: 'launchctl', args: ['kickstart', `gui/${process.getuid?.() ?? 0}/${label}`] };
+    if (platform === 'linux')
+        return { command: 'systemctl', args: ['--user', 'start', 'meta-proxy.service'] };
+    if (platform === 'win32')
+        return { command: 'schtasks', args: ['/run', '/tn', label] };
+    return null;
+}
+function stopCommand(platform, label = SERVICE_LABEL) {
+    // `launchctl kill SIGTERM` may still be classified by launchd as an
+    // unsuccessful termination and restarted under KeepAlive. Bootout unloads
+    // the current job but deliberately leaves the plist in LaunchAgents, so the
+    // explicit stop stays stopped now and remains configured for next login.
+    if (platform === 'darwin')
+        return { command: 'launchctl', args: ['bootout', `gui/${process.getuid?.() ?? 0}/${label}`] };
+    if (platform === 'linux')
+        return { command: 'systemctl', args: ['--user', 'stop', 'meta-proxy.service'] };
+    if (platform === 'win32')
+        return { command: 'schtasks', args: ['/end', '/tn', label] };
+    return null;
+}
+export function startMetaProxyService(options = {}) {
+    const home = options.home ?? homedir();
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? defaultRunner;
+    const label = options.label ?? SERVICE_LABEL;
+    const state = metaProxyServiceState(platform, home, run, label);
+    if (state.managerState === 'unknown')
+        return { ok: false, message: 'Could not determine service-manager state.' };
+    if (state.managerState !== 'enabled' && !(platform === 'darwin' && state.definitionPresent)) {
+        return { ok: false, message: 'Meta-Proxy is not enabled at login.' };
+    }
+    if (state.running)
+        return { ok: true, message: `Meta-Proxy is already running${state.pid ? ` (pid ${state.pid})` : ''}.` };
+    const commands = platform === 'darwin' && state.managerState === 'disabled' && state.unitPath
+        ? enableCommands(platform, state.unitPath, label)
+        : [startCommand(platform, label)].filter((command) => command !== null);
+    if (commands.length === 0)
+        return { ok: false, message: `Managed start is not supported on ${platform}.` };
+    for (const command of commands) {
+        const outcome = run(command);
+        if (!outcome.ok)
+            return { ok: false, message: `Could not start Meta-Proxy: ${outcome.output || 'command failed'}` };
+    }
+    return { ok: true, message: 'Meta-Proxy managed start requested.' };
+}
+export function stopMetaProxyService(options = {}) {
+    const home = options.home ?? homedir();
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? defaultRunner;
+    const label = options.label ?? SERVICE_LABEL;
+    const state = metaProxyServiceState(platform, home, run, label);
+    if (state.managerState === 'unknown')
+        return { ok: false, message: 'Could not determine service-manager state.' };
+    if (state.managerState !== 'enabled') {
+        return state.enabledAtLogin
+            ? { ok: true, message: 'Meta-Proxy managed service is already stopped.' }
+            : { ok: false, message: 'Meta-Proxy is not enabled at login.' };
+    }
+    if (state.running === false)
+        return { ok: true, message: 'Meta-Proxy managed service is already stopped.' };
+    const command = stopCommand(platform, label);
+    if (!command)
+        return { ok: false, message: `Managed stop is not supported on ${platform}.` };
+    const outcome = run(command);
+    return outcome.ok
+        ? { ok: true, message: 'Meta-Proxy managed stop requested.' }
+        : { ok: false, message: `Could not stop Meta-Proxy: ${outcome.output || 'command failed'}` };
+}
 export function disableMetaProxyService(options = {}) {
     const home = options.home ?? homedir();
     const platform = options.platform ?? process.platform;
     const run = options.run ?? defaultRunner;
-    const unitPath = serviceUnitPath(platform, home);
+    const label = options.label ?? SERVICE_LABEL;
+    const wait = options.wait ?? defaultWait;
+    const unitPath = serviceUnitPath(platform, home, label);
     if (!unitPath) {
         return { ok: true, message: `Start-at-login is not supported on ${platform}; nothing to disable.` };
     }
-    if (!existsSync(unitPath)) {
-        return { ok: true, message: 'Meta-Proxy is not set to start at login.' };
+    const state = metaProxyServiceState(platform, home, run, label);
+    if (state.managerState === 'unknown') {
+        return { ok: false, message: `Could not determine service-manager state; preserved ${unitPath}.`, unitPath };
     }
-    // Best-effort: the unit file is removed even if the OS command complains,
-    // because a stale definition left behind is the state that lies to
-    // `proxy status`. The daemon binary is untouched — disabling supervision is
-    // not uninstalling the proxy.
-    const failures = [];
-    for (const invocation of disableCommands(platform, unitPath)) {
-        const outcome = run(invocation);
-        if (!outcome.ok)
-            failures.push(outcome.output || `${invocation.command} failed`);
+    if (state.managerState === 'disabled' && !state.definitionPresent) {
+        return { ok: true, message: 'Meta-Proxy is not set to start at login.' };
     }
-    rmSync(unitPath, { force: true });
-    if (failures.length > 0) {
+    if (state.loaded === true && !state.definitionPresent) {
+        // Same ownership rule as enable: without the owned definition on disk we
+        // cannot prove the registered job is ours, and unregistering by label
+        // alone would stop another installer's service.
         return {
-            ok: true,
-            message: `Removed ${unitPath}, but the service manager reported: ${failures.join('; ')}. The Meta-Proxy binary is untouched.`,
+            ok: false,
+            message: `A Meta-Proxy ${platform === 'win32' ? 'task' : 'service'} is registered without the owned definition at ${unitPath}; refusing to stop or delete it by label alone.`,
+            unitPath,
         };
     }
+    if (platform === 'win32' && state.managerState === 'enabled') {
+        return stopAndDeleteWindowsTask(home, unitPath, label, run, wait);
+    }
+    const unregister = state.managerState === 'enabled'
+        ? disableCommands(platform, unitPath, label)[0]
+        : undefined;
+    if (unregister) {
+        const outcome = run(unregister);
+        if (!outcome.ok) {
+            if (platform === 'linux') {
+                const after = metaProxyServiceState(platform, home, run, label);
+                if (after.managerState === 'unknown') {
+                    return {
+                        ok: false,
+                        message: `Could not disable start-at-login and could not determine whether it partially changed state: ${outcome.output || `${unregister.command} failed`}. Definition preserved at ${unitPath}.`,
+                        unitPath,
+                    };
+                }
+                const restore = [];
+                if (state.enabledAtLogin !== after.enabledAtLogin) {
+                    restore.push({ command: 'systemctl', args: ['--user', state.enabledAtLogin ? 'enable' : 'disable', 'meta-proxy.service'] });
+                }
+                if (state.running !== after.running) {
+                    restore.push({ command: 'systemctl', args: ['--user', state.running ? 'start' : 'stop', 'meta-proxy.service'] });
+                }
+                const restoreFailure = restore.map((command) => run(command)).find((result) => !result.ok);
+                const restored = restoreFailure ? null : metaProxyServiceState(platform, home, run, label);
+                if (restoreFailure
+                    || restored?.managerState === 'unknown'
+                    || restored?.loaded !== state.loaded
+                    || restored?.enabledAtLogin !== state.enabledAtLogin
+                    || restored?.running !== state.running) {
+                    return {
+                        ok: false,
+                        message: `Could not disable start-at-login and restoring its possible partial changes failed: ${restoreFailure?.output || 'state mismatch'}. Definition preserved at ${unitPath}.`,
+                        unitPath,
+                    };
+                }
+                return {
+                    ok: false,
+                    message: `Could not disable start-at-login (${outcome.output || `${unregister.command} failed`}); prior login enablement and running state were restored. Definition preserved at ${unitPath}.`,
+                    unitPath,
+                };
+            }
+            return {
+                ok: false,
+                message: `Could not disable start-at-login: ${outcome.output || `${unregister.command} failed`}. Definition preserved at ${unitPath}.`,
+                unitPath,
+            };
+        }
+    }
+    const definition = state.definitionPresent ? readFileSync(unitPath, 'utf8') : null;
+    rmSync(unitPath, { force: true });
+    if (platform === 'linux') {
+        const refresh = disableCommands(platform, unitPath, label)[1];
+        const outcome = refresh ? run(refresh) : { ok: false, output: 'daemon-reload command unavailable' };
+        if (!outcome.ok) {
+            if (definition !== null) {
+                mkdirSync(dirname(unitPath), { recursive: true, mode: 0o700 });
+                writeFileSync(unitPath, definition, { encoding: 'utf8', mode: 0o600 });
+            }
+            const restoreReload = refresh ? run(refresh) : { ok: false, output: 'daemon-reload command unavailable' };
+            const restoreCommands = [];
+            if (state.enabledAtLogin)
+                restoreCommands.push({ command: 'systemctl', args: ['--user', 'enable', 'meta-proxy.service'] });
+            if (state.running)
+                restoreCommands.push({ command: 'systemctl', args: ['--user', 'start', 'meta-proxy.service'] });
+            const restoreFailure = !restoreReload.ok
+                ? restoreReload
+                : restoreCommands.map((command) => run(command)).find((result) => !result.ok);
+            const restored = restoreFailure ? null : metaProxyServiceState(platform, home, run, label);
+            if (restoreFailure
+                || restored?.managerState === 'unknown'
+                || restored?.enabledAtLogin !== state.enabledAtLogin
+                || restored?.running !== state.running) {
+                return {
+                    ok: false,
+                    message: `Disabled service and daemon-reload failed; restoring the prior manager state also failed: ${restoreFailure?.output || 'state mismatch'}. Definition preserved at ${unitPath}.`,
+                    unitPath,
+                };
+            }
+            return {
+                ok: false,
+                message: `Disable rolled back after daemon-reload failed: ${outcome.output || 'command failed'}. Prior definition, login enablement, and running state restored at ${unitPath}.`,
+                unitPath,
+            };
+        }
+    }
     return { ok: true, message: `Meta-Proxy will no longer start at login. Removed ${unitPath}.` };
 }
+function stopAndDeleteWindowsTask(home, unitPath, label, run, wait, removeDefinition = true) {
+    const stopped = confirmWindowsTaskStopped(home, unitPath, label, run, wait);
+    if (!stopped.ok)
+        return stopped;
+    const removeTask = disableCommands('win32', unitPath, label)[0];
+    const removed = removeTask ? run(removeTask) : { ok: false, output: 'delete command unavailable' };
+    if (!removed.ok) {
+        return { ok: false, message: `Could not delete the stopped Meta-Proxy task: ${removed.output || 'command failed'}. Definition preserved at ${unitPath}.`, unitPath };
+    }
+    if (removeDefinition)
+        rmSync(unitPath, { force: true });
+    return { ok: true, message: removeDefinition ? `Meta-Proxy will no longer start at login. Removed ${unitPath}.` : 'Newly-created Meta-Proxy task removed; prior definition preserved.', unitPath };
+}
+function confirmWindowsTaskStopped(home, unitPath, label, run, wait) {
+    const end = stopCommand('win32', label);
+    if (!end)
+        return { ok: false, message: 'Could not construct the Windows stop command.', unitPath };
+    run(end);
+    let stopped = metaProxyServiceState('win32', home, run, label);
+    let consecutiveStopped = stopped.running === false ? 1 : 0;
+    for (let attempt = 0; attempt < 20 && stopped.managerState !== 'unknown' && consecutiveStopped < 2; attempt++) {
+        wait(100);
+        stopped = metaProxyServiceState('win32', home, run, label);
+        consecutiveStopped = stopped.running === false ? consecutiveStopped + 1 : 0;
+    }
+    if (stopped.managerState === 'unknown' || consecutiveStopped < 2) {
+        return { ok: false, message: `Could not confirm the Meta-Proxy task stopped; preserved task and ${unitPath}.`, unitPath };
+    }
+    return { ok: true, message: 'Meta-Proxy task is stably stopped.', unitPath };
+}
 //# sourceMappingURL=meta-proxy-service.js.map