@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/control/bindingStore.js

@@ -0,0 +1,200 @@
+import { assertLockOwnership } from './locks.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { loadClientConfig } from '../config.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { bindingSchema, operationRecordSchema, LocalControlError } from './protocol.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+const IDENTITY_FILES = ['client.key', 'server.pub', 'config.yml'];
+const missing = (error) => error.code === 'ENOENT';
+async function readPrivateFile(file) {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || stat.size > 1_048_576)
+        throw new Error('Unsafe workstation identity file');
+    return fs.readFile(file, 'utf8');
+}
+async function exists(file) {
+    try {
+        await fs.lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+async function atomicWrite(file, value) {
+    assertLockOwnership();
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await fs.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(value);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await fs.open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateKeys(keys) {
+    for (const value of [keys.clientKey, keys.serverPub]) {
+        if (!/^[A-Za-z0-9+/]{43}=$/.test(value) || Buffer.from(value, 'base64').length !== 32 || Buffer.from(value, 'base64').toString('base64') !== value) {
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Workstation connection keys are invalid');
+        }
+    }
+}
+function bindingOf(config) {
+    return bindingSchema.parse({ server: normalizeWorkstationServer(config.server), workstationId: config.workstationId, ...(config.ownerUserId ? { ownerUserId: config.ownerUserId } : {}) });
+}
+/** Caller holds the shared operation lock for every mutating method. */
+export class BindingStore {
+    directory;
+    pending;
+    constructor(directory) {
+        this.directory = directory;
+        this.pending = path.join(directory, 'identity.pending');
+    }
+    async inspect() {
+        const pending = await exists(this.pending);
+        const present = await Promise.all(IDENTITY_FILES.map(file => exists(path.join(this.directory, file))));
+        if (!present.some(Boolean))
+            return { binding: null, revision: 'unregistered', identityState: pending ? 'incomplete' : 'absent' };
+        let readableBinding = null;
+        let configDigest = 'corrupt';
+        try {
+            configDigest = createHash('sha256').update(await readPrivateFile(path.join(this.directory, 'config.yml'))).digest('hex');
+            await readPrivateFile(path.join(this.directory, 'config.yml'));
+            const binding = bindingOf(await loadClientConfig(this.directory));
+            readableBinding = binding;
+            const keys = { clientKey: (await readPrivateFile(path.join(this.directory, 'client.key'))).trim(), serverPub: (await readPrivateFile(path.join(this.directory, 'server.pub'))).trim() };
+            validateKeys(keys);
+            const revision = createHash('sha256').update(JSON.stringify(binding)).update('\0').update(keys.clientKey).update('\0').update(keys.serverPub).digest('hex');
+            return { binding, revision, identityState: pending ? 'incomplete' : 'ready' };
+        }
+        catch {
+            return { binding: readableBinding, revision: configDigest, identityState: pending ? 'incomplete' : 'corrupt' };
+        }
+    }
+    async history() {
+        try {
+            const data = JSON.parse(await readPrivateFile(path.join(this.directory, 'binding-history.json')));
+            if (!Array.isArray(data))
+                throw new Error('Invalid binding history');
+            return data.map(value => bindingSchema.parse(value));
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Workstation binding history is unreadable');
+        }
+    }
+    async recover() {
+        if (!await exists(this.pending))
+            return;
+        const stat = await fs.lstat(this.pending);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Unsafe pending workstation identity');
+        let marker;
+        try {
+            marker = await readPrivateFile(path.join(this.pending, 'ready'));
+        }
+        catch {
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration needs verification: incomplete local transaction');
+        }
+        if (marker === 'clear') {
+            await this.finishClear();
+            return;
+        }
+        if (marker !== '1')
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Unknown workstation identity transaction');
+        const configText = await readPrivateFile(path.join(this.pending, 'config.yml'));
+        const config = await loadClientConfig(this.pending);
+        bindingOf(config);
+        const keys = { clientKey: (await readPrivateFile(path.join(this.pending, 'client.key'))).trim(), serverPub: (await readPrivateFile(path.join(this.pending, 'server.pub'))).trim() };
+        validateKeys(keys);
+        const operation = operationRecordSchema.parse(JSON.parse(await readPrivateFile(path.join(this.pending, 'operation.json'))));
+        let history;
+        if (await exists(path.join(this.pending, 'binding-history.json'))) {
+            const staged = JSON.parse(await readPrivateFile(path.join(this.pending, 'binding-history.json')));
+            if (!Array.isArray(staged))
+                throw new LocalControlError('CORRUPT_IDENTITY', 'Invalid staged binding history');
+            history = staged.map(value => bindingSchema.parse(value));
+        }
+        // All staging is validated before any existing identity file changes.
+        for (const [name, value] of [['client.key', keys.clientKey], ['server.pub', keys.serverPub], ['config.yml', configText]])
+            await atomicWrite(path.join(this.directory, name), value);
+        if (history)
+            await atomicWrite(path.join(this.directory, 'binding-history.json'), JSON.stringify(history));
+        await atomicWrite(path.join(this.directory, 'operation.json'), JSON.stringify(operation));
+        await syncDirectory(this.directory);
+        await fs.rm(this.pending, { recursive: true });
+        await syncDirectory(this.directory);
+    }
+    async commit(config, keys, operation, repair = false) {
+        const binding = bindingOf(config);
+        validateKeys(keys);
+        const safeOperation = operationRecordSchema.parse(operation);
+        await privateDirectory(this.directory);
+        await this.recover();
+        const current = await this.inspect();
+        if (current.identityState === 'corrupt' && !(repair && current.binding && (!current.binding.ownerUserId || current.binding.ownerUserId === binding.ownerUserId) && current.binding.server === binding.server && current.binding.workstationId === binding.workstationId))
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Existing workstation identity needs repair');
+        const history = await this.history();
+        for (const previous of [current.binding, binding])
+            if (previous) {
+                const i = history.findIndex(item => item.server === previous.server && item.ownerUserId === previous.ownerUserId);
+                if (i >= 0)
+                    history.splice(i, 1);
+                history.push(previous);
+            }
+        await fs.mkdir(this.pending, { mode: 0o700 });
+        for (const [name, value] of Object.entries({
+            'config.yml': yaml.dump({ ...config, server: binding.server }), 'client.key': keys.clientKey, 'server.pub': keys.serverPub,
+            'operation.json': JSON.stringify(safeOperation), 'binding-history.json': JSON.stringify(history),
+        }))
+            await atomicWrite(path.join(this.pending, name), value);
+        await atomicWrite(path.join(this.pending, 'ready'), '1');
+        await syncDirectory(this.pending);
+        await syncDirectory(this.directory);
+        await this.recover();
+    }
+    async clear(expectedRevision) {
+        await this.recover();
+        const current = await this.inspect();
+        if (current.revision !== expectedRevision || current.identityState !== 'ready')
+            throw new LocalControlError('BINDING_CONFLICT', 'Workstation identity changed; check it again');
+        await fs.mkdir(this.pending, { mode: 0o700 });
+        await atomicWrite(path.join(this.pending, 'clear.json'), JSON.stringify(current.binding));
+        await atomicWrite(path.join(this.pending, 'ready'), 'clear');
+        await syncDirectory(this.pending);
+        await syncDirectory(this.directory);
+        await this.finishClear();
+    }
+    async finishClear() {
+        const removed = bindingSchema.parse(JSON.parse(await readPrivateFile(path.join(this.pending, 'clear.json'))));
+        const history = (await this.history()).filter(item => item.server !== removed.server || item.workstationId !== removed.workstationId);
+        await atomicWrite(path.join(this.directory, 'binding-history.json'), JSON.stringify(history));
+        for (const name of [...IDENTITY_FILES, 'operation.json'])
+            await fs.rm(path.join(this.directory, name), { force: true });
+        await syncDirectory(this.directory);
+        await fs.rm(this.pending, { recursive: true });
+        await syncDirectory(this.directory);
+    }
+}

package/dist/workstation/control/commands.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { assertIdentityCanStart } from './daemonIdentity.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+import { saveOperation } from './enrollment.js';
+import { clientDir, loadClientConfig, readKeys } from '../config.js';
+import { createDaemonController } from '../daemonctl.js';
+import { BindingStore } from './bindingStore.js';
+import { inspectWorkstation } from './inspect.js';
+import { enrollWorkstation, enrollmentFailure } from './enrollment.js';
+import { withWorkstationLock } from './locks.js';
+import { bindingGuardSchema, LocalControlError } from './protocol.js';
+const lifecycleRequest = z.object({ operationId: z.string().min(1).max(128), guard: bindingGuardSchema }).strict();
+export async function readLocalRequest(input) {
+    const chunks = [];
+    let size = 0;
+    for await (const part of input) {
+        const chunk = Buffer.from(part);
+        size += chunk.length;
+        if (size > 65_536)
+            throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local command input');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local command input');
+    }
+}
+export async function executeLocalCommand(action, input, directory, controllerFactory, inspect = inspectWorkstation) {
+    if (action === 'register')
+        return enrollWorkstation(input, directory);
+    try {
+        const request = action === 'adopt-owner' ? lifecycleRequest.extend({ server: z.string(), expectedOwnerUserId: z.string().min(1), workstationId: z.string().min(1) }).parse(input) : action === 'set-enabled' ? lifecycleRequest.extend({ enabled: z.boolean() }).parse(input) : lifecycleRequest.parse(input);
+        return await withWorkstationLock(directory, 'operation', async () => {
+            const before = await inspect(directory);
+            if (before.revision !== request.guard.revision || before.runtime.generation !== request.guard.runtimeGeneration)
+                throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+            if (action === 'recover') {
+                if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the workstation before recovering its identity');
+                await new BindingStore(directory).recover();
+                return { status: 'succeeded', inspection: await inspect(directory) };
+            }
+            if (before.pending?.kind === 'remove' && !['begin-remove', 'forget', 'stop'].includes(action))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Finish removing this workstation before continuing');
+            if (before.runtime.state === 'unknown')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify the running workstation');
+            if (action === 'adopt-owner') {
+                const ownerRequest = lifecycleRequest.extend({ server: z.string(), expectedOwnerUserId: z.string().min(1), workstationId: z.string().min(1) }).parse(input);
+                if (before.identityState !== 'ready' || !before.binding || before.binding.ownerUserId || before.binding.server !== normalizeWorkstationServer(ownerRequest.server) || before.binding.workstationId !== ownerRequest.workstationId)
+                    throw new LocalControlError('BINDING_CONFLICT', 'The local connection changed');
+                const config = await loadClientConfig(directory);
+                const keys = await readKeys(directory);
+                await new BindingStore(directory).commit({ ...config, ownerUserId: ownerRequest.expectedOwnerUserId }, { clientKey: keys.clientKey.toString('base64'), serverPub: keys.serverPub.toString('base64') }, { id: request.operationId, kind: 'register', phase: 'owner-confirmed', target: { server: before.binding.server, ownerUserId: ownerRequest.expectedOwnerUserId }, workstationId: before.binding.workstationId, outcome: 'succeeded' });
+            }
+            else if (action === 'forget') {
+                if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                    throw new LocalControlError('INSTANCE_OCCUPIED', 'Stop the workstation and its sessions before removing the connection');
+                await new BindingStore(directory).clear(request.guard.revision);
+            }
+            else {
+                if (before.identityState !== 'ready')
+                    throw new LocalControlError('CORRUPT_IDENTITY', 'The workstation needs registration or repair');
+                const controller = controllerFactory?.() ?? createDaemonController({ identity: () => new BindingStore(directory).inspect(), runtime: async () => (await inspect(directory)).runtime });
+                if (action === 'set-enabled') {
+                    const enabled = lifecycleRequest.extend({ enabled: z.boolean() }).parse(input).enabled;
+                    if (enabled)
+                        await assertIdentityCanStart(directory);
+                    if (!controller.setEnabled)
+                        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Update the CLI to manage service enablement');
+                    await controller.setEnabled(enabled, request);
+                }
+                else if (action === 'begin-remove') {
+                    if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                        await controller.stop(request);
+                    const stopped = await inspect(directory);
+                    if (stopped.runtime.state !== 'stopped' || stopped.keepers !== 'stopped')
+                        throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown could not be confirmed');
+                    await saveOperation(directory, { id: request.operationId, kind: 'remove', phase: 'removing', target: { server: before.binding.server, ownerUserId: before.binding.ownerUserId ?? null }, workstationId: before.binding.workstationId, outcome: 'pending' });
+                }
+                else if (action === 'install') {
+                    if (before.runtime.state !== 'stopped')
+                        throw new LocalControlError('INSTANCE_OCCUPIED', 'Stop the workstation before changing its service');
+                    await controller.install();
+                }
+                else {
+                    if (action === 'start' || action === 'restart')
+                        await assertIdentityCanStart(directory);
+                    await controller[action](request);
+                }
+            }
+            const after = await inspect(directory);
+            if (action === 'set-enabled') {
+                const expected = lifecycleRequest.extend({ enabled: z.boolean() }).parse(input).enabled;
+                if (!after.service || after.service.enabled !== expected || after.service.reason || (!expected && (after.runtime.state !== 'stopped' || after.keepers !== 'stopped'))) {
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Service enablement could not be confirmed');
+                }
+            }
+            if (action === 'stop' && (after.runtime.state !== 'stopped' || after.keepers !== 'stopped'))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown could not be confirmed');
+            return { status: 'succeeded', inspection: after };
+        });
+    }
+    catch (error) {
+        return enrollmentFailure(error, directory);
+    }
+}
+export async function runLocalJsonCommand(action, input = process.stdin, write = value => { process.stdout.write(value); }, directory = clientDir(), controllerFactory, inspect = inspectWorkstation) {
+    let operationId = randomUUID();
+    let result;
+    try {
+        const request = await readLocalRequest(input);
+        if (typeof request === 'object' && request && 'operationId' in request && typeof request.operationId === 'string' && /^[\w-]{1,128}$/.test(request.operationId))
+            operationId = request.operationId;
+        result = await executeLocalCommand(action, request, directory, controllerFactory, inspect);
+    }
+    catch (error) {
+        result = await enrollmentFailure(error, directory);
+    }
+    const event = { schemaVersion: 1, kind: 'result', operationId, result };
+    write(JSON.stringify(event) + '\n');
+}

package/dist/workstation/control/daemonIdentity.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { loadClientConfig, readKeys } from '../config.js';
+import { BindingStore } from './bindingStore.js';
+import { withWorkstationLock } from './locks.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { readControlFile } from './runtimeHost.js';
+import { LocalControlError, operationRecordSchema } from './protocol.js';
+export async function assertIdentityCanStart(directory) {
+    try {
+        const operation = operationRecordSchema.parse(JSON.parse(await readControlFile(path.join(directory, 'operation.json'))));
+        if (operation.outcome === 'pending' || operation.outcome === 'unknown')
+            throw new LocalControlError('OUTCOME_UNKNOWN', operation.kind === 'remove' ? 'Finish removing this workstation before starting it' : 'The workstation operation needs verification');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+export async function recoverStoppedIdentity(directory) {
+    const store = new BindingStore(directory);
+    if ((await store.inspect()).identityState === 'incomplete') {
+        const runtime = await inspectRuntime(directory);
+        const { inspectKeepers } = await import('./inspect.js');
+        if (runtime.state !== 'stopped' || await inspectKeepers(directory) !== 'stopped')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the existing workstation before recovering its identity');
+    }
+    await store.recover();
+}
+/** Publish runtime ownership under the same lock as identity writes; initialization uses this snapshot only. */
+export async function claimDaemonIdentity(directory, claim) {
+    const deadline = Date.now() + 10_000;
+    for (;;)
+        try {
+            return await withWorkstationLock(directory, 'operation', async () => {
+                const runtime = await inspectRuntime(directory);
+                if (runtime.state !== 'stopped')
+                    throw new LocalControlError(runtime.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'The existing workstation must be verified before startup');
+                const store = new BindingStore(directory);
+                await recoverStoppedIdentity(directory);
+                await assertIdentityCanStart(directory);
+                if ((await store.inspect()).identityState !== 'ready')
+                    throw new LocalControlError('CORRUPT_IDENTITY', 'The workstation identity needs registration or repair');
+                const config = await loadClientConfig(directory);
+                const keys = await readKeys(directory);
+                return claim({ config, ...keys });
+            });
+        }
+        catch (error) {
+            if (!(error instanceof LocalControlError) || error.code !== 'BUSY' || Date.now() >= deadline)
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+}

package/dist/workstation/control/enrollment.js

@@ -0,0 +1,106 @@
+import os from 'node:os';
+import { sanitizeName } from '../names.js';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { requestWorkstationRegistration } from '../register.js';
+import { BindingStore } from './bindingStore.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { inspectWorkstation } from './inspect.js';
+import { bindingGuardSchema, LocalControlError, operationRecordSchema } from './protocol.js';
+import { assertLockOwnership, withWorkstationLock } from './locks.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { KeeperLauncher } from '../keepers/kit/launcher.js';
+import { stopKeepers } from '../keepers/stop.js';
+export const registrationInputSchema = z.object({ operationId: z.string().min(1).max(128), server: z.string(), expectedOwnerUserId: z.string().min(1), name: z.string().min(1).max(200).optional(), workstationId: z.string().min(1).optional(), workspace: z.object({ name: z.string(), cwd: z.string(), shell: z.string() }).optional(), guard: bindingGuardSchema, switchConfirmed: z.boolean(), accessToken: z.string().min(1).max(32_768) }).strict();
+export async function saveOperation(directory, operation) {
+    assertLockOwnership();
+    await privateDirectory(directory);
+    const file = path.join(directory, 'operation.json');
+    const temporary = file + '.' + randomUUID();
+    const handle = await fs.open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(operationRecordSchema.parse(operation)));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    assertLockOwnership();
+    await fs.rename(temporary, file);
+}
+export async function enrollmentFailure(error, directory) {
+    const e = error instanceof LocalControlError ? error : new LocalControlError('SERVICE_FAILED', 'The local workstation operation failed. Check its status and try again.');
+    return { status: e.code === 'BUSY' ? 'busy' : e.code === 'OUTCOME_UNKNOWN' ? 'pending' : ['BINDING_CONFLICT', 'INSTANCE_OCCUPIED'].includes(e.code) ? 'conflict' : 'failed', inspection: await inspectWorkstation(directory).catch(() => null), error: { code: e.code, message: e.message } };
+}
+async function defaultShell() {
+    const candidates = [process.env.SHELL, os.userInfo().shell, process.platform === 'darwin' ? '/bin/zsh' : '/bin/sh'];
+    for (const shell of candidates)
+        if (shell && path.isAbsolute(shell) && !/[\x00-\x1f]/.test(shell)) {
+            try {
+                await fs.access(shell, fs.constants.X_OK);
+                if ((await fs.stat(shell)).isFile())
+                    return shell;
+            }
+            catch { /* Try the user's login shell, then the platform fallback. */ }
+        }
+    throw new LocalControlError('UNSUPPORTED_INSTALLATION', 'No executable login shell is available');
+}
+async function enroll(input, directory, deps) {
+    const server = normalizeWorkstationServer(input.server);
+    const store = new BindingStore(directory);
+    await store.recover();
+    const identity = await store.inspect();
+    const runtime = await deps.runtime();
+    if (runtime.state !== 'stopped')
+        throw new LocalControlError(runtime.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'Stop the existing workstation before registering this computer');
+    if (input.guard && (identity.revision !== input.guard.revision || runtime.generation !== input.guard.runtimeGeneration))
+        throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+    if (identity.identityState === 'corrupt' && (!identity.binding || !input.expectedOwnerUserId || (identity.binding.ownerUserId && identity.binding.ownerUserId !== input.expectedOwnerUserId) || identity.binding.server !== server))
+        throw new LocalControlError('CORRUPT_IDENTITY', 'The saved workstation identity needs verification');
+    const switching = identity.binding && (identity.binding.server !== server || (input.expectedOwnerUserId && identity.binding.ownerUserId !== input.expectedOwnerUserId));
+    if (switching && !input.switchConfirmed)
+        throw new LocalControlError('BINDING_CONFLICT', 'Confirm switching this computer to the selected server and account');
+    const inspection = await inspectWorkstation(directory);
+    if (inspection.pending && ['pending', 'unknown'].includes(inspection.pending.outcome))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'An earlier registration needs verification. Refresh the workstation list before retrying.');
+    if (identity.binding) {
+        const reports = await stopKeepers(new KeeperLauncher({ configDir: directory, ...identity.binding }));
+        if (reports.some(report => !report.result.stopped))
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Existing workstation sessions could not be stopped');
+    }
+    const history = await store.history();
+    const known = input.expectedOwnerUserId ? history.find(item => item.server === server && item.ownerUserId === input.expectedOwnerUserId) : undefined;
+    const same = identity.binding?.server === server && (!input.expectedOwnerUserId || identity.binding.ownerUserId === input.expectedOwnerUserId);
+    const workstationId = input.workstationId ?? known?.workstationId ?? (same ? identity.binding?.workstationId : undefined);
+    const operation = { id: input.operationId, kind: switching ? 'switch' : 'register', phase: 'registering', target: { server, ownerUserId: input.expectedOwnerUserId ?? null }, outcome: 'pending' };
+    await saveOperation(directory, operation);
+    try {
+        const workspace = input.workspace;
+        const shell = workspace?.shell ?? await defaultShell();
+        const response = await requestWorkstationRegistration(server, input.name ?? sanitizeName(os.hostname(), 'computer'), input.accessToken, workspace, workstationId, shell);
+        if (input.expectedOwnerUserId && response.ownerUserId !== input.expectedOwnerUserId)
+            throw new LocalControlError('OWNER_MISMATCH', 'The server returned a different workstation owner');
+        assertLockOwnership();
+        await store.commit({ server, workstationId: response.workstationId, ...(response.ownerUserId ? { ownerUserId: response.ownerUserId } : {}), workspaces: workspace ? [{ name: workspace.name, cwd: workspace.cwd }] : [] }, response, { ...operation, workstationId: response.workstationId, phase: 'registered', outcome: 'succeeded' }, identity.identityState === 'corrupt');
+        return { status: 'succeeded', inspection: await inspectWorkstation(directory) };
+    }
+    catch (error) {
+        await saveOperation(directory, { ...operation, outcome: error instanceof LocalControlError && error.code !== 'OUTCOME_UNKNOWN' ? 'failed' : 'unknown' });
+        throw error;
+    }
+}
+export async function enrollWorkstation(input, directory, deps = { runtime: () => inspectRuntime(directory) }) {
+    try {
+        const parsed = registrationInputSchema.parse(input);
+        return await withWorkstationLock(directory, 'operation', () => enroll(parsed, directory, deps));
+    }
+    catch (error) {
+        return enrollmentFailure(error, directory);
+    }
+}
+export async function enrollLegacyWorkstation(input, directory) {
+    await withWorkstationLock(directory, 'operation', () => enroll(input, directory, { runtime: () => inspectRuntime(directory) }));
+}

package/dist/workstation/control/inspect.js

@@ -0,0 +1,71 @@
+import os from 'node:os';
+import { createServiceManager } from '../service/installer.js';
+import { serviceContext } from '../daemonctl.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BindingStore } from './bindingStore.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { localInspectionSchema, operationRecordSchema } from './protocol.js';
+import { readControlFile } from './runtimeHost.js';
+import { updateServiceContext } from '../config.js';
+import { CLIENT_VERSION } from '../version.js';
+import { readPidManifest, manifestProcessLive } from '../keepers/kit/lock.js';
+export async function inspectKeepers(directory) {
+    try {
+        let running = false;
+        for (const kind of ['acp', 'terminal']) {
+            const root = path.join(directory, 'keepers', kind, 'run');
+            let entries;
+            try {
+                entries = await fs.readdir(root);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    continue;
+                throw e;
+            }
+            for (const entry of entries) {
+                const manifest = await readPidManifest(path.join(root, entry, 'keeper.pid.json'));
+                if (manifest && await manifestProcessLive(manifest))
+                    running = true;
+            }
+        }
+        return running ? 'running' : 'stopped';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export async function inspectWorkstation(directory, deps = {}) {
+    const identity = await new BindingStore(directory).inspect();
+    let pending = null;
+    try {
+        const operation = operationRecordSchema.parse(JSON.parse(await readControlFile(path.join(directory, 'operation.json'))));
+        if (operation.outcome !== 'succeeded')
+            pending = operation;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const cliPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../cli.js');
+    const context = updateServiceContext(directory);
+    let runtime = await inspectRuntime(directory);
+    const standardHome = os.userInfo().homedir;
+    const standardDirectory = path.join(standardHome, '.axom/workstation');
+    const probeLegacy = deps.legacyServiceRunning ?? (process.platform === 'darwin' && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? async () => (await createServiceManager(serviceContext()).status()).running : undefined);
+    if (runtime.state === 'stopped' && probeLegacy) {
+        try {
+            if (await probeLegacy())
+                runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+        catch {
+            runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+    }
+    const service = (process.platform === 'darwin' || process.platform === 'linux') && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? await createServiceManager(serviceContext()).enablement() : undefined;
+    return localInspectionSchema.parse({ schemaVersion: 1, ...identity, installation: { source: context.managed ? 'managed' : 'existing', version: CLIENT_VERSION, nodeVersion: process.versions.node, nodePath: context.nodePath, cliPath, npmPath: context.npmPath, npmPrefix: context.npmPrefix }, runtime, ...(service ? { service } : {}), keepers: await inspectKeepers(directory), pending });
+}

package/dist/workstation/control/locks.js

@@ -0,0 +1,63 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import lockfile from 'proper-lockfile';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { pidAlive, processCommand } from '../keepers/kit/lock.js';
+import { LocalControlError } from './protocol.js';
+const ownership = new AsyncLocalStorage();
+export function assertLockOwnership() {
+    if (ownership.getStore()?.valid === false)
+        throw new LocalControlError('BUSY', 'Workstation lock ownership was lost');
+}
+export async function withPrivateLock(stem, work) {
+    await privateDirectory(path.dirname(stem));
+    const ownerFile = stem + '.owner.json';
+    // proper-lockfile's time lease alone is insufficient: a suspended live app still owns its operation.
+    let lockPresent = false;
+    try {
+        const stat = await fs.lstat(stem + '.lock');
+        lockPresent = true;
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw Error('Unsafe lock');
+        if (Date.now() - stat.mtimeMs > 30_000) {
+            const owner = JSON.parse(await fs.readFile(ownerFile, 'utf8'));
+            if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.command !== 'string')
+                throw Error('Unknown owner');
+            if (pidAlive(owner.pid))
+                throw Error('Live or unverifiable owner');
+        }
+    }
+    catch (error) {
+        if (lockPresent || error.code !== 'ENOENT')
+            throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    const lease = { valid: true };
+    const nonce = randomUUID();
+    let release;
+    try {
+        release = await lockfile.lock(stem, { realpath: false, stale: 30_000, update: 2_000, retries: 0, onCompromised: () => { lease.valid = false; } });
+    }
+    catch {
+        throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    try {
+        await fs.writeFile(ownerFile, JSON.stringify({ schemaVersion: 1, pid: process.pid, command: await processCommand(process.pid), nonce }), { mode: 0o600 });
+        return await ownership.run(lease, async () => { const result = await work(); assertLockOwnership(); return result; });
+    }
+    finally {
+        if (lease.valid) {
+            try {
+                if (JSON.parse(await fs.readFile(ownerFile, 'utf8')).nonce === nonce)
+                    await fs.rm(ownerFile);
+            }
+            catch { /* release still required */ }
+            await release();
+        }
+    }
+}
+export function withWorkstationLock(directory, name, work) {
+    return withPrivateLock(name === 'operation' ? path.join(directory, 'control/operation') : path.join(os.homedir(), '.axom/locks/cli-install'), work);
+}