@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/runtime/remoteDesktopAdapter.js

@@ -0,0 +1,186 @@
+import { DeviceAdmissionConnection } from '../desktopControl/deviceAdmission.js';
+import { DeviceSockets } from '../desktopControl/deviceSockets.js';
+import { DesktopSessionSupervisor } from '../desktopControl/supervisor.js';
+import { AutomationDeviceConnections } from '../desktopControl/automationDevice.js';
+import { randomBytes } from 'node:crypto';
+import { bounded, NativeCommandError } from '../desktopControl/helperProcess.js';
+export class ClosedRemoteDesktopAdapter {
+    report;
+    constructor(report) {
+        this.report = report;
+    }
+    async dispatch(frame, generation) {
+        if (frame.t === 'desktop_prepare')
+            this.report(generation, { t: 'desktop_prepare_result', commandId: frame.commandId, sessionId: frame.sessionId, state: 'failed', code: 'unavailable' });
+        else if (frame.t === 'desktop_lobby' || frame.t === 'desktop_background')
+            this.report(generation, { t: 'desktop_lobby_result', commandId: frame.commandId, lobbyId: frame.lobbyId, deviceGeneration: generation, plan: null, code: 'unavailable' });
+    }
+    async retire() {
+        throw new Error('Physical desktop isolation acknowledgement is unavailable until Computer Use integration');
+    }
+}
+export class RegistrationDesktopAdapter {
+    admission;
+    provider;
+    viewer;
+    automation;
+    paused = false;
+    newWorkPaused = false;
+    initialized = false;
+    unavailable;
+    observerGenerations = new Set();
+    viewerClosed = false;
+    automationClosed = false;
+    cleanupStarted = false;
+    finalizers = new Map();
+    original;
+    constructor(options) {
+        this.unavailable = new ClosedRemoteDesktopAdapter(options.report);
+        this.original = { registrationId: options.registrationId, host: options.provider?.deviceAdmission };
+        this.admission = new DeviceAdmissionConnection(options.registrationId, options.owner, options.provider?.deviceAdmission, frame => options.report(frame.deviceGeneration, frame));
+        const provider = options.provider, admission = this.admission, host = this.original.host;
+        const preparationCurrent = (binding) => {
+            const original = admission.grant(binding.sessionId);
+            let begun = false;
+            return (beginEffect = false) => {
+                if (!original || this.paused || !host?.current() || !admission.current(original))
+                    throw new NativeCommandError('control_lost');
+                if (!begun && this.newWorkPaused)
+                    return false;
+                if (beginEffect)
+                    begun = true;
+                return true;
+            };
+        };
+        if (provider && host)
+            this.provider = {
+                deviceAdmission: host, automaticDpi: provider.automaticDpi,
+                probe: async () => { if (this.paused)
+                    return null; const caps = await provider.probe(); return caps && !this.paused && host.current() ? { ...caps, deviceOwnershipProtocol: 1 } : null; },
+                prepare: async (selection, binding, operationCurrent) => {
+                    const deviceGrant = admission.grant(binding.sessionId);
+                    if (this.paused || !deviceGrant)
+                        throw new Error('control_lost');
+                    const originalCurrent = operationCurrent ?? preparationCurrent(binding);
+                    const current = (beginEffect = false) => {
+                        if (this.paused || !host.current() || !admission.current(deviceGrant))
+                            throw new NativeCommandError('control_lost');
+                        return originalCurrent(beginEffect);
+                    };
+                    if (!current())
+                        throw new NativeCommandError('busy');
+                    const backend = await provider.prepare(selection, { ...binding, deviceGrant }, current);
+                    try {
+                        if (!current())
+                            throw new NativeCommandError('busy');
+                    }
+                    catch (error) {
+                        await backend.stop();
+                        throw error;
+                    }
+                    return backend;
+                },
+                recoverDisplay: (binding, reserved) => {
+                    const deviceGrant = admission.grant(binding.sessionId);
+                    if (this.paused || !deviceGrant)
+                        return Promise.reject(new Error('control_lost'));
+                    return provider.recoverDisplay({ ...binding, deviceGrant }, reserved);
+                },
+                prepareAutomation: async (binding) => {
+                    if (this.paused || this.newWorkPaused || !host.current() || !provider.prepareAutomation || !this.automationCurrent(binding))
+                        throw new Error('unsupported');
+                    const deviceGrant = admission.grant(binding.route.consumerId);
+                    if (!deviceGrant) {
+                        if (!host.isolateRegistration)
+                            throw new Error('unsupported_observer_isolation');
+                        this.observerGenerations.add(binding.route.deviceGeneration);
+                    }
+                    return provider.prepareAutomation({ ...binding, registrationId: options.registrationId, deviceGrant });
+                },
+                wallpaper: provider.wallpaper?.bind(provider),
+            };
+        if (this.provider)
+            this.viewer = new DesktopSessionSupervisor({ provider: this.provider,
+                sockets: new DeviceSockets(options.server, options.allowInsecureWs), report: options.report,
+                newWorkAllowed: () => !this.paused && !this.newWorkPaused,
+                preparationCurrent,
+                controllerCurrent: binding => !this.paused && !!admission.grant(binding.sessionId) });
+        this.automation = new AutomationDeviceConnections(options.server, this.provider, options.allowInsecureWs, options.stateDirectory, { registrationId: options.registrationId, current: binding => !this.paused && this.automationCurrent(binding) });
+    }
+    automationCurrent(binding) {
+        const authorization = binding.preparation?.authorization;
+        return authorization?.control === true ? !!this.admission.grant(binding.route.consumerId) :
+            authorization?.control === false && !authorization.launch && !authorization.clipboard;
+    }
+    initializeAdmission(open, held) {
+        if (this.initialized)
+            throw Error('desktop_adapter_already_initialized');
+        this.paused = !open;
+        this.newWorkPaused = held;
+        if (!open)
+            this.admission.closeAdmission();
+        if (held)
+            this.admission.holdNewAdmission();
+        else
+            this.admission.resumeNewAdmission();
+    }
+    ready(generation) { this.initialized = true; this.admission.ready(generation); if (this.paused)
+        this.admission.closeAdmission(); this.viewer?.managementReady(generation); this.automation.ready(generation); }
+    closed(generation) { this.admission.closed(generation); this.viewer?.managementClosed(generation); this.automation.retired(generation); void this.admission.isolateOriginal().catch(() => { }); }
+    async dispatch(frame, generation) {
+        if (frame.t === 'desktop_ownership')
+            return this.admission.dispatch(frame);
+        if (this.paused && frame.t !== 'desktop_cancel')
+            return;
+        if (this.viewer)
+            return this.viewer.dispatch(frame, generation);
+        return this.unavailable.dispatch(frame, generation);
+    }
+    async prepareAutomation(frame, generation) {
+        if (this.paused || this.newWorkPaused)
+            throw new Error('control_lost');
+        await this.automation.prepare(frame.grant, frame.binding, generation);
+    }
+    async closeAdmission() { this.paused = true; this.admission.closeAdmission(); }
+    async holdNewAdmission() { this.newWorkPaused = true; this.admission.holdNewAdmission(); }
+    resumeNewAdmission() { this.newWorkPaused = false; this.admission.resumeNewAdmission(); }
+    async isolateOriginal() {
+        this.cleanupStarted = true;
+        const operations = [() => this.admission.isolateOriginal()];
+        const host = this.original.host;
+        for (const generation of [...this.observerGenerations])
+            operations.push(() => this.finalize(`observer:${generation}`, async () => {
+                if (!host?.isolateRegistration)
+                    throw new Error('observer_isolation_unconfirmed');
+                const commandId = randomBytes(16).toString('hex');
+                const receipt = await host.isolateRegistration(commandId, this.original.registrationId, generation);
+                if (receipt.commandId !== commandId || receipt.registrationId !== this.original.registrationId || receipt.deviceGeneration !== generation ||
+                    receipt.hostLifetimeId !== host.hostLifetimeId || receipt.physical !== 'completed' || receipt.admission !== 'revoked')
+                    throw new Error('observer_isolation_unconfirmed');
+                this.observerGenerations.delete(generation);
+            }));
+        if (!this.viewerClosed)
+            operations.push(() => this.finalize('viewer', async () => { await this.viewer?.close(); this.viewerClosed = true; }));
+        if (!this.automationClosed)
+            operations.push(() => this.finalize('automation', async () => { this.automation.close(); this.automationClosed = true; }));
+        const outcomes = await Promise.allSettled(operations.map(operation => Promise.resolve().then(operation)));
+        const failures = outcomes.flatMap(outcome => outcome.status === 'rejected' ? [outcome.reason] : []);
+        if (failures.length)
+            throw new AggregateError(failures, 'Original desktop cleanup remains unconfirmed');
+    }
+    finalize(key, operation) {
+        const pending = this.finalizers.get(key);
+        if (pending)
+            return bounded(pending, 15_000);
+        const result = operation().finally(() => { this.finalizers.delete(key); });
+        this.finalizers.set(key, result);
+        return bounded(result, 15_000);
+    }
+    resumeAdmission() { this.paused = false; this.admission.resumeAdmission(); }
+    activity() {
+        const admission = this.admission.activity();
+        const transports = this.cleanupStarted ? Number(!this.viewerClosed) + Number(!this.automationClosed) : 0;
+        return { known: admission.known && this.observerGenerations.size === 0 && transports === 0,
+            consumers: Math.max(admission.consumers, (this.viewer?.activeCount ?? 0) + this.automation.activeCount, this.observerGenerations.size, transports) };
+    }
+}

package/dist/workstation/runtime/removalActivity.js

@@ -0,0 +1,184 @@
+import { assertRemovalNamespace } from '../registrations/migration.js';
+import { LocalControlError } from '../control/protocol.js';
+const settlements = new WeakMap();
+/** Prevent new work during removal. Only --force terminates existing work. */
+export class TargetRemovalActivity {
+    options;
+    preparation = Object.freeze({});
+    phase = 'observing';
+    force = false;
+    desktopClosed = false;
+    settlement;
+    settlementNamespace;
+    operation;
+    constructor(options) {
+        this.options = options;
+    }
+    validate() {
+        this.options.validate();
+        if (this.phase === 'disposed' || this.phase === 'released')
+            throw new LocalControlError('BINDING_CONFLICT', 'Target preparation has finished');
+    }
+    namespace(namespace) {
+        assertRemovalNamespace(namespace);
+        const registration = this.options.registration;
+        if (namespace.registrationId !== registration.id || namespace.revision !== registration.revision || namespace.dataDirectory !== registration.dataDirectory || namespace.configDir !== registration.keeperConfigDirectory)
+            throw new LocalControlError('BINDING_CONFLICT', 'Target registration changed');
+    }
+    async exclusive(work) {
+        if (this.operation)
+            throw new LocalControlError('BUSY', 'Target removal is already running');
+        const operation = work();
+        this.operation = operation;
+        try {
+            return await operation;
+        }
+        finally {
+            this.operation = undefined;
+        }
+    }
+    async sample() {
+        this.validate();
+        const before = this.options.tasks.observeTargetPending();
+        const activity = await this.options.activity();
+        this.validate();
+        const after = this.options.tasks.observeTargetPending();
+        const background = this.options.background();
+        const desktop = this.options.desktopActivity?.() ?? { known: true, consumers: 0 };
+        const busy = before.pending + after.pending + activity.agents + activity.terminals + activity.commands + activity.transfers + activity.desktopConsumers + desktop.consumers + background.pending > 0;
+        const known = activity.known && before.known && after.known && background.known && desktop.known;
+        return { status: busy ? 'busy' : known ? 'candidate' : 'unknown', diagnostics: known ? [] : ['Target activity is not available yet'] };
+    }
+    observe() { return this.exclusive(() => this.sample()); }
+    seal(mode) {
+        return this.exclusive(async () => {
+            this.validate();
+            if (this.phase === 'sealed') {
+                if (mode === 'force')
+                    this.force = true;
+                if (!this.desktopClosed) {
+                    await this.options.closeDesktopAdmission?.();
+                    this.desktopClosed = true;
+                }
+                return;
+            }
+            if (this.phase !== 'observing')
+                throw new LocalControlError('BINDING_CONFLICT', 'Target is already being removed');
+            if (!mode) {
+                const observation = await this.sample();
+                if (observation.status !== 'candidate')
+                    throw new LocalControlError(observation.status === 'busy' ? 'BUSY' : 'OUTCOME_UNKNOWN', 'Target still has work; use --force to terminate it');
+            }
+            this.force = mode === 'force';
+            this.options.beginFinal();
+            this.phase = 'sealed';
+            await this.options.closeDesktopAdmission?.();
+            this.desktopClosed = true;
+        });
+    }
+    async prepareTermination() { if (this.phase === 'observing')
+        await this.seal('force');
+    else {
+        this.validate();
+        this.force = true;
+    } }
+    settle(namespace) {
+        return this.exclusive(async () => {
+            this.validate();
+            this.namespace(namespace);
+            if (this.phase !== 'sealed' && this.phase !== 'settled')
+                throw new LocalControlError('BINDING_CONFLICT', 'Target must stop accepting work before removal');
+            if (this.phase !== 'settled') {
+                if (!this.desktopClosed) {
+                    await this.options.closeDesktopAdmission?.();
+                    this.desktopClosed = true;
+                }
+                if (!this.force) {
+                    const observation = await this.sample();
+                    if (observation.status !== 'candidate')
+                        throw new LocalControlError(observation.status === 'busy' ? 'BUSY' : 'OUTCOME_UNKNOWN', 'Target work has not finished');
+                }
+                if (this.force) {
+                    this.options.tasks.closeAgentWorkLifetime();
+                    await Promise.all([this.options.tasks.stopAll(), this.options.localTransport.dispose(), this.options.isolateDesktop?.()]);
+                    this.validate();
+                    this.namespace(namespace);
+                }
+                // Stop existing keepers first so accepted prompts/opens can observe their process exit.
+                const stopKeepers = async () => {
+                    for (const launcher of this.options.launchers)
+                        for (const kind of ['acp', 'terminal']) {
+                            const generations = await launcher.liveGenerations(kind);
+                            this.validate();
+                            this.namespace(namespace);
+                            for (const generation of generations) {
+                                const result = await launcher.stop(kind, generation, this.force ? 'force' : 'graceful');
+                                this.validate();
+                                this.namespace(namespace);
+                                if (!result.stopped)
+                                    throw new LocalControlError('OUTCOME_UNKNOWN', result.reason ?? 'Target keeper has not stopped');
+                            }
+                        }
+                };
+                await stopKeepers();
+                if (this.force) {
+                    // Main closes an already-starting adapter when its open returns after stopAll. Wait for that
+                    // handler before completing removal, then stop any keeper its delayed startup launched.
+                    if (!await this.options.tasks.waitForAcceptedAgentWork(5_000))
+                        throw new LocalControlError('OUTCOME_UNKNOWN', 'Accepted agent work has not finished stopping');
+                    this.validate();
+                    this.namespace(namespace);
+                    await stopKeepers();
+                }
+                await this.options.filesHost.stop();
+                this.validate();
+                this.namespace(namespace);
+                this.phase = 'settled';
+            }
+            this.settlementNamespace = namespace;
+            const token = this.settlement ??= Object.freeze({});
+            settlements.set(token, this);
+            return token;
+        });
+    }
+    assertSettlement(token, lifetime, namespace) {
+        this.validate();
+        this.namespace(namespace);
+        if (settlements.get(token) !== this || token !== this.settlement || lifetime !== this.options.lifetime || this.phase !== 'settled' || namespace !== this.settlementNamespace)
+            throw new LocalControlError('BINDING_CONFLICT', 'Invalid target removal settlement');
+    }
+    consume(token, lifetime, namespace) { this.assertSettlement(token, lifetime, namespace); this.phase = 'disposing'; }
+    continueDisposition(token, lifetime, namespace) {
+        if (this.phase !== 'disposing')
+            return false;
+        this.namespace(namespace);
+        if (token !== this.settlement || settlements.get(token) !== this || lifetime !== this.options.lifetime)
+            throw new LocalControlError('BINDING_CONFLICT', 'Invalid target removal continuation');
+        this.settlementNamespace = namespace;
+        return true;
+    }
+    async prepareDisposition(lifetime, namespace) {
+        if (lifetime !== this.options.lifetime)
+            throw new LocalControlError('BINDING_CONFLICT', 'Target runtime changed');
+        if (this.settlement && this.continueDisposition(this.settlement, lifetime, namespace))
+            return this.settlement;
+        return this.settle(namespace);
+    }
+    disposed() { if (this.phase !== 'disposing')
+        throw new LocalControlError('BINDING_CONFLICT', 'Target removal was not prepared'); this.phase = 'disposed'; }
+    async release() {
+        if (this.phase === 'released')
+            return;
+        this.validate();
+        if (this.phase !== 'observing' || this.operation)
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Target removal has already started');
+        await this.options.restore();
+        this.phase = 'released';
+    }
+}
+export function consumeTargetResourceSettlement(token, lifetime, namespace) {
+    const activity = settlements.get(token);
+    if (!activity)
+        throw new LocalControlError('BINDING_CONFLICT', 'Target removal settlement is unavailable');
+    activity.consume(token, lifetime, namespace);
+}

package/dist/workstation/service/installer.js

@@ -5,6 +5,13 @@ import path from 'node:path';
 import { launchAgentPath, renderLaunchAgent } from './launchd.js';
 import { renderSystemdUnit, systemdUnitPath } from './systemd.js';
 import { assertSafeServiceContext, SERVICE_LABEL } from './types.js';
+import { assertDeviceUpdateTransitionSafe } from '../control/daemonIdentity.js';
+import { inspectRuntime, inspectDeviceRuntime } from '../control/runtimeClient.js';
+import { LocalControlError } from '../control/protocol.js';
+import { captureStartupPackageEvidence } from '../update/deviceHealth.js';
+import { readDeviceBootstrapRecovery, readPrivateUpdateBytes, updateTransactionKey } from '../update/recoveryPlan.js';
+import { launchWatchdogProcess } from '../update/watchdogProcess.js';
+import { ensureCompatibleWatchdog, needsWatchdogCompatibility } from '../update/deviceCompatibility.js';
 async function runProcess(command, args) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -58,6 +65,22 @@ async function assertWritable(directory) {
 }
 const defaultDeps = {
     run: runProcess,
+    readLaunchAgent: async (file) => {
+        const handle = await fs.open(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.size > 65536)
+                throw new Error('Invalid LaunchAgent');
+        }
+        finally {
+            await handle.close();
+        }
+        const result = await runProcess('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file]);
+        const value = JSON.parse(result.stdout);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('Invalid LaunchAgent');
+        return value;
+    },
     writeTemp,
     assertWritable,
     ensureDirectory: async (directory) => { await fs.mkdir(directory, { recursive: true }); },
@@ -102,6 +125,85 @@ export function createServiceManager(context, overrides = {}) {
     assertSafeServiceContext(context);
     const deps = { ...defaultDeps, ...overrides };
     const target = context.platform === 'darwin' ? launchAgentPath(context.homeDir) : systemdUnitPath(context.homeDir);
+    const deviceAdmission = async (install = false) => {
+        let device = false;
+        for (const name of ['device.json', 'legacy-migration.json'])
+            try {
+                await fs.lstat(path.join(context.configDir, name));
+                device = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        if (!device)
+            return;
+        let startup;
+        if (install) {
+            let transaction = false;
+            try {
+                await fs.lstat(path.join(context.configDir, 'update/device-transaction.json'));
+                transaction = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (transaction) {
+                const packageRoot = path.dirname(path.dirname(context.cliPath));
+                if (context.cliPath !== path.join(packageRoot, 'dist/cli.js'))
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'The update service must execute its exact installed dist/cli.js');
+                const metadata = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+                if (typeof metadata.version !== 'string')
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'The installed update package version cannot be verified');
+                startup = await captureStartupPackageEvidence(packageRoot, metadata.version);
+            }
+        }
+        // Revalidate the actual installed package here too: the controller's earlier admission must
+        // not become an unqualified legacy-state check when the OS service manager is reached.
+        await assertDeviceUpdateTransitionSafe(context.configDir, startup);
+        try {
+            await inspectDeviceRuntime(context.configDir);
+        }
+        catch {
+            if ((await inspectRuntime(context.configDir)).state !== 'stopped')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Verify and stop the predecessor daemon before changing the device service');
+        }
+        if (install && startup) {
+            const { deviceTransactionSchema } = await import('../update/deviceCoordinator.js');
+            const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(context.configDir, 'update/device-transaction.json'), 33_554_432)).toString()));
+            if (transaction.phase === 'RESTARTING' && !transaction.installedRollback) {
+                const recovery = await readDeviceBootstrapRecovery(context.configDir, startup);
+                if (recovery?.plan) {
+                    if (needsWatchdogCompatibility(recovery.plan))
+                        await ensureCompatibleWatchdog(context, recovery.plan, deps.run);
+                    else if (context.platform === 'linux')
+                        await launchWatchdogProcess({ nodePath: context.nodePath, program: recovery.plan.program.path, plan: path.join(context.configDir, 'update', `watchdog-${updateTransactionKey(recovery.plan.commandId)}.json`), lifecycle: 'managed', logPath: path.join(context.configDir, 'update/watchdog.log') }, { platform: context.platform, runSystemd: deps.run });
+                }
+            }
+        }
+        if (install || !await deps.pathExists(target))
+            return;
+        let compatible = false;
+        if (context.platform === 'darwin') {
+            const definition = await deps.readLaunchAgent(target);
+            compatible = definition.EnvironmentVariables !== undefined && definition.EnvironmentVariables.AXOM_WORKSTATION_RUNTIME === 'device-v2';
+        }
+        else {
+            const handle = await fs.open(target, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size > 65_536 || (process.getuid && stat.uid !== process.getuid()))
+                    throw Error('Unsafe device service definition');
+                compatible = (await handle.readFile('utf8')).split('\n').includes('Environment=AXOM_WORKSTATION_RUNTIME=device-v2');
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        if (!compatible)
+            throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Legacy workstation service definition: run axom workstation install with this compatible CLI before starting the device owner');
+    };
     const contents = context.platform === 'darwin' ? renderLaunchAgent(context) : renderSystemdUnit(context);
     const launchdDomain = `gui/${context.userId}/${SERVICE_LABEL}`;
     // `gui/<uid>` exists only while someone is logged into the GUI. Switching this agent to
@@ -219,24 +321,38 @@ export function createServiceManager(context, overrides = {}) {
         // durable LaunchAgent plist. This keeps explicit stop meaningful across both service managers.
         if (action === 'stop')
             return deps.run('launchctl', ['bootout', launchdDomain]);
-        if (action === 'restart') {
-            try {
-                await deps.run('launchctl', ['bootout', launchdDomain]);
-            }
-            catch (error) {
-                // `restart` after an explicit `stop` is a valid request: absence means there is nothing
-                // left to unload, and launchdStart will bootstrap the durable plist.
-                if (!launchdAbsent(error))
-                    throw error;
+        return launchdStart();
+    };
+    const enabled = async (plistDisabled = false) => {
+        if (context.platform === 'darwin') {
+            const result = await deps.run('launchctl', ['print-disabled', `gui/${context.userId}`]);
+            if (!result.stdout.includes('{') || !result.stdout.includes('}'))
+                throw new Error('Cannot determine launchd enablement');
+            const line = result.stdout.split('\n').find(line => line.includes(`"${SERVICE_LABEL}"`));
+            if (line) {
+                const override = /=>\s*(true|false|enabled|disabled)\b/.exec(line);
+                if (!override)
+                    throw new Error('Cannot determine launchd enablement');
+                return override[1] === 'true' || override[1] === 'disabled' ? false : true;
             }
-            return launchdStart();
+            return !plistDisabled;
+        }
+        try {
+            return (await deps.run('systemctl', ['--user', 'is-enabled', `${SERVICE_LABEL}.service`])).stdout.trim() === 'enabled';
+        }
+        catch (error) {
+            if (/disabled|not-found/.test(String(error)))
+                return false;
+            throw error;
         }
-        return launchdStart();
     };
     // Extracted so `start()` can reuse it: reinstalling is the same work whether triggered
     // explicitly (`axom workstation install`) or as `start()`'s self-heal for a missing definition
     // file. Both platform branches leave the service running, so callers need no separate start.
     const performInstall = async (_options = {}) => {
+        const present = await deps.pathExists(target);
+        const plistDisabled = context.platform === 'darwin' && present && (await deps.readLaunchAgent(target)).Disabled === true;
+        const preserveDisabled = (context.platform === 'darwin' || present) && !await enabled(plistDisabled);
         await deps.assertWritable(context.npmPrefix);
         await deps.ensureDirectory(path.dirname(target));
         const temp = await deps.writeTemp(contents);
@@ -246,7 +362,10 @@ export function createServiceManager(context, overrides = {}) {
             await deps.run('mv', [targetTemp, target]);
             if (context.platform === 'linux') {
                 await deps.run('systemctl', ['--user', 'daemon-reload']);
-                await deps.run('systemctl', ['--user', 'enable', '--now', `${SERVICE_LABEL}.service`]);
+                if (!preserveDisabled)
+                    await deps.run('systemctl', ['--user', 'enable', '--now', `${SERVICE_LABEL}.service`]);
+                if (!preserveDisabled && _options.restartRunning)
+                    await deps.run('systemctl', ['--user', 'restart', `${SERVICE_LABEL}.service`]);
             }
             else {
                 // Reload an existing service before bootstrapping the replacement into the GUI domain.
@@ -255,7 +374,8 @@ export function createServiceManager(context, overrides = {}) {
                 // bounded probe/bootstrap path so Bootstrap failed: 5 is confirmed then kickstarted, and
                 // so a launchd that never releases the job is reported instead of leaving the machine
                 // with the bootout applied and nothing bootstrapped in its place.
-                await launchdStart();
+                if (!preserveDisabled)
+                    await launchdStart();
             }
         }
         finally {
@@ -264,6 +384,7 @@ export function createServiceManager(context, overrides = {}) {
     };
     return {
         async install(options = {}) {
+            await deviceAdmission(true);
             await withGuiSessionHint(() => performInstall(options));
         },
         /**
@@ -302,14 +423,76 @@ export function createServiceManager(context, overrides = {}) {
          * longer on disk and surface launchd/systemd's raw error; reinstall first instead.
          */
         async start() {
+            await deviceAdmission();
             await withGuiSessionHint(async () => {
+                // An explicit Start is consent to re-enable; install/update alone preserves OFF.
+                if (context.platform === 'darwin')
+                    await deps.run('launchctl', ['enable', launchdDomain]);
+                else
+                    await deps.run('systemctl', ['--user', 'enable', `${SERVICE_LABEL}.service`]);
                 if (!(await deps.pathExists(target)))
                     await performInstall({});
                 await lifecycle('start');
             });
         },
         async stop() { await withGuiSessionHint(() => lifecycle('stop')); },
-        async restart() { await withGuiSessionHint(() => lifecycle('restart')); },
+        async restart() { await deviceAdmission(); await withGuiSessionHint(() => lifecycle('restart')); },
+        async setEnabled(value) {
+            if (value)
+                await deviceAdmission();
+            await withGuiSessionHint(async () => {
+                if (context.platform === 'darwin') {
+                    await deps.run('launchctl', [value ? 'enable' : 'disable', launchdDomain]);
+                    if (value) {
+                        if (!await deps.pathExists(target))
+                            await performInstall({});
+                        await launchdStart();
+                    }
+                    else {
+                        try {
+                            await lifecycle('stop');
+                        }
+                        catch (error) {
+                            if (!launchdAbsent(error))
+                                throw error;
+                        }
+                    }
+                }
+                else
+                    await deps.run('systemctl', ['--user', value ? 'enable' : 'disable', '--now', `${SERVICE_LABEL}.service`]);
+            });
+        },
+        async enablement() {
+            const installed = await deps.pathExists(target);
+            if (!installed)
+                return { installed: false, enabled: false, loaded: false, running: false };
+            let value;
+            try {
+                let disabled = false;
+                if (context.platform === 'darwin') {
+                    const plist = await deps.readLaunchAgent(target);
+                    const args = plist.ProgramArguments;
+                    const environment = plist.EnvironmentVariables;
+                    if (plist.Label !== SERVICE_LABEL || !Array.isArray(args) || args.length !== 3 || args[0] !== context.nodePath || args[1] !== context.cliPath || args[2] !== '__daemon' || environment?.AXOM_WORKSTATION_CONFIG_DIR !== context.configDir) {
+                        return { installed, enabled: null, loaded: false, running: false, reason: 'service_identity_mismatch' };
+                    }
+                    disabled = plist.Disabled === true;
+                }
+                value = await enabled(disabled);
+            }
+            catch {
+                return { installed, enabled: null, loaded: false, running: false, reason: 'service_state_unknown' };
+            }
+            try {
+                const result = await lifecycle('status');
+                return { installed, enabled: value, loaded: true, running: context.platform === 'darwin' ? launchdIsRunning(result.stdout) : true };
+            }
+            catch (error) {
+                if (launchdAbsent(error) || /inactive|not loaded|not-found/.test(String(error)))
+                    return { installed, enabled: value, loaded: false, running: false };
+                return { installed, enabled: value, loaded: false, running: false, reason: 'runtime_state_unknown' };
+            }
+        },
         async status() {
             try {
                 const result = await lifecycle('status');

package/dist/workstation/service/launchd.js

@@ -28,9 +28,11 @@ export function renderLaunchAgent(context) {
 \t<dict>
 ${keyValue('HOME', context.homeDir)}
 ${keyValue('AXOM_WORKSTATION_CONFIG_DIR', context.configDir)}
+${keyValue('AXOM_WORKSTATION_RUNTIME', 'device-v2')}
 ${keyValue('AXOM_WORKSTATION_NPM_PATH', context.npmPath)}
 ${keyValue('AXOM_WORKSTATION_NPM_PREFIX', context.npmPrefix)}
 ${keyValue('PATH', context.pathEnv)}
+${context.npmConfigPrefix ? keyValue('NPM_CONFIG_PREFIX', context.npmConfigPrefix) : ''}
 \t</dict>
 \t<key>StandardOutPath</key>
 \t<string>${xml(`${context.configDir}/daemon.log`)}</string>