@platless/axom-cli 0.6.36 → 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'] });
@@ -118,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
@@ -278,6 +364,8 @@ export function createServiceManager(context, overrides = {}) {
                 await deps.run('systemctl', ['--user', 'daemon-reload']);
                 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.
@@ -296,6 +384,7 @@ export function createServiceManager(context, overrides = {}) {
     };
     return {
         async install(options = {}) {
+            await deviceAdmission(true);
             await withGuiSessionHint(() => performInstall(options));
         },
         /**
@@ -334,6 +423,7 @@ 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')
@@ -346,8 +436,10 @@ export function createServiceManager(context, overrides = {}) {
             });
         },
         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]);

package/dist/workstation/service/launchd.js

@@ -28,6 +28,7 @@ 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)}

package/dist/workstation/service/systemd.js

@@ -35,6 +35,7 @@ Type=simple
 WorkingDirectory=${systemdToken(context.homeDir)}
 ${environment('HOME', context.homeDir)}
 ${environment('AXOM_WORKSTATION_CONFIG_DIR', context.configDir)}
+${environment('AXOM_WORKSTATION_RUNTIME', 'device-v2')}
 ${environment('AXOM_WORKSTATION_NPM_PATH', context.npmPath)}
 ${environment('AXOM_WORKSTATION_NPM_PREFIX', context.npmPrefix)}
 ${environment('PATH', context.pathEnv)}

package/dist/workstation/systemMetrics.js

@@ -195,6 +195,9 @@ export class SystemMetricsSampler {
             clearInterval(this.refreshTimer);
         this.refreshTimer = null;
     }
+    refreshWorkspaces() {
+        this.refreshTopologyInBackground();
+    }
     snapshot() {
         try {
             this.refreshDarwinMemoryInBackground();

package/dist/workstation/tools/client.js

@@ -8,16 +8,13 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { object, TOOL_REQUEST_BYTES, TOOL_RESULT_BYTES, validateRequest } from './validation.js';
 /** Unix socket paths must remain below macOS/Linux's ~104-byte sockaddr_un limit. */
-export function keeperPaths(options, temporaryDirectory = os.tmpdir(), platform = process.platform, kind = 'terminal') {
-    const identity = createHash('sha256').update(JSON.stringify([path.resolve(options.configDir), options.workstationId, options.server, ...(kind === 'browser' ? ['browser'] : [])])).digest('hex').slice(0, 32);
-    const namespace = `axom-${kind === 'browser' ? 'browser' : 'tools'}-${process.getuid?.() ?? 'user'}`;
-    // macOS /var/folders/.../T often exhausts sockaddr_un before adding a private namespace. Honor
-    // TMPDIR where it fits on Linux; the short system temporary root is checked for private ownership.
+export function keeperPaths(options, temporaryDirectory = os.tmpdir(), platform = process.platform, kind = 'browser') {
+    const identity = createHash('sha256').update(JSON.stringify([path.resolve(options.configDir), options.workstationId, options.server, 'browser'])).digest('hex').slice(0, 32);
+    const namespace = `axom-browser-${process.getuid?.() ?? 'user'}`;
     let dir = path.join(platform === 'darwin' ? '/tmp' : temporaryDirectory, namespace, identity);
     if (Buffer.byteLength(path.join(dir, 'keeper.sock')) > 100)
         dir = path.join('/tmp', namespace, identity);
-    // Browser ports are disjoint from terminal startup and the normal Linux ephemeral range.
-    return { dir, socket: path.join(dir, 'keeper.sock'), lock: path.join(dir, 'startup.lock'), pidFile: path.join(dir, 'keeper.pid.json'), lockPort: kind === 'browser' ? 10000 + Number.parseInt(identity.slice(0, 8), 16) % 8000 : 20000 + Number.parseInt(identity.slice(0, 8), 16) % 40000, unit: `axom-${kind === 'browser' ? 'browser' : 'tools'}-keeper-${identity}` };
+    return { dir, socket: path.join(dir, 'keeper.sock'), lock: path.join(dir, 'startup.lock'), pidFile: path.join(dir, 'keeper.pid.json'), lockPort: 10000 + Number.parseInt(identity.slice(0, 8), 16) % 8000, unit: `axom-browser-keeper-${identity}` };
 }
 export async function privateDirectory(dir) {
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });
@@ -84,22 +81,16 @@ function pidAlive(pid) {
         return error.code === 'EPERM';
     }
 }
-/**
- * A tools keeper client. The daemon only ever makes the browser kind (`browser`). The kind is required — no default — so nothing can
- * start the retired terminal-kind tools keeper by accident (spec §9; terminals run in keeper-terminal, files in the daemon's files
- * host); an explicit `terminal` client exists only for the tests that pin how the retired keeper's startup and tools.info behave.
- * (`keeperPaths` keeps its terminal default: `keepers/legacy.ts` finds a legacy tools keeper an older CLI left running by it.)
- */
+/** Browser supervisor client. Native terminals use TerminalKeeperClient exclusively. */
 export class ToolsClient {
     options;
     kind;
     paths;
     starting;
-    browser;
     constructor(options, kind) {
         this.options = options;
         this.kind = kind;
-        if (kind !== 'terminal' && kind !== 'browser')
+        if (kind !== 'browser')
             throw new Error('ToolsClient needs an explicit kind (browser)');
         this.paths = keeperPaths(options, undefined, undefined, kind);
     }
@@ -121,26 +112,16 @@ export class ToolsClient {
             // Desktop sharing is optional. Checking terminal/files must not start a
             // separate browser or require its dependencies when no VNC was configured.
             const metadata = { browser: false, browserMode: 'shared', browserBinding: browserCapability(undefined) };
-            return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+            return metadata;
         }
         if (binding && (method.startsWith('browser.') || method === 'tools.info')) {
             const metadata = { browser: true, browserMode: 'shared', browserBinding: browserCapability(binding) };
             if (method === 'browser.list')
                 return { ...metadata, sessions: [] };
             if (method === 'tools.info')
-                return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+                return metadata;
             throw new Error('Shared browser uses the live desktop viewer; legacy browser session operations are unavailable');
         }
-        if (this.kind === 'terminal' && (method.startsWith('browser.') || method === 'tools.info')) {
-            this.browser ??= new ToolsClient(this.options, 'browser');
-            if (method.startsWith('browser.'))
-                return this.browser.request(method, params);
-            const [terminal, browser] = await Promise.all([this.localRequest(method, params), this.browser.request(method, params).catch(error => ({ browser: false, browserError: error.message }))]);
-            const result = { ...terminal, ...browser, browserMode: 'legacy', browserBinding: browserCapability(undefined) };
-            if (result.browser)
-                delete result.browserError;
-            return result;
-        }
         return this.localRequest(method, params);
     }
     async localRequest(method, params) {

package/dist/workstation/tools/info.js

@@ -1,19 +1,10 @@
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-/*
- * `tools.info`, aggregated by the daemon. Consumers (analysis C §3.6): Workbench app.mjs (version), CoworkService
- * (files / mediaPreviewVersion / fileFindVersion / home / userName), files.mjs (roots / downloads / terminal),
- * terminal.mjs (home, terminal / terminalError), browser.mjs (browser* fields). Every field keeps the value and meaning
- * the legacy tools keeper gave it (tools/core.ts at the merge-base, since deleted, + tools/client.ts), and answering it never
- * starts any keeper:
- *   - file fields come from the files host's last `ready` (or are computed here before the first one); `files: true`
- *     is reported even while the host restarts, so a probe never mistakes the machine for an old CLI;
- *   - terminal fields come from keeper-terminal's hello capabilities when that keeper is already running (connecting to it,
- *     never starting it: keepers/terminal/client.ts `terminalStatus`), otherwise from a cached node-pty load check
- *     (update/ptyPreflight.ts);
- *   - browser fields come from the browser-kind ToolsClient, whose `tools.info` only returns metadata.
- */
+import { TERMINAL_GRID_SCHEMA, TERMINAL_GRID_CAPABILITY } from '../keepers/terminal/gridProtocol.js';
+/* tools.info is read-only discovery. Schema/capability describe the native contract; terminal availability
+ * comes from a current running keeper hello. The daemon's absent-keeper source is false, never a load probe
+ * promising that a future keeper will start. Files/browser discovery retain their independent metadata. */
 /** The legacy keeper always sent this (tools/core.ts at the merge-base); the browser metadata never removed it. */
 export const BROWSER_DISABLED_ERROR = 'Browser tools are not enabled in this release';
 export async function aggregateToolsInfo(sources) {
@@ -21,6 +12,8 @@ export async function aggregateToolsInfo(sources) {
     return {
         version: 1,
         terminal: terminal.terminal,
+        terminalSchema: TERMINAL_GRID_SCHEMA,
+        terminalCapability: TERMINAL_GRID_CAPABILITY,
         browser: false,
         ...files,
         ...(terminal.terminalError ? { terminalError: terminal.terminalError } : {}),