@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/control/commands.js

@@ -0,0 +1,125 @@
+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';
+export { executeDeviceCommand } from './deviceCommands.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,143 @@
+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';
+import { assertLegacyRoot } from './rootFormat.js';
+import { constants, promises as fs } from 'node:fs';
+import { load as loadYaml } from 'js-yaml';
+import { RegistrationStore } from '../registrations/store.js';
+import { assertRegistrationEnrollmentAdmission, migrateLegacyRegistration } from '../registrations/migration.js';
+import { assertDeviceUpdateTransitionSafe } from './updateTransition.js';
+import { legacyDesktopContinuity } from '../update/legacyBridge.js';
+export { assertDeviceUpdateTransitionSafe } from './updateTransition.js';
+async function assertDeviceDesktopTransitionSafe(directory) {
+    if (await legacyDesktopContinuity(directory))
+        return;
+    const uncertain = () => new LocalControlError('OUTCOME_UNKNOWN', 'Previous desktop authority requires a verified physical retirement acknowledgement from Computer Use before device startup; preserve the provider/configuration evidence and finish that retirement with the compatible desktop application');
+    for (const name of ['desktop-provider.json', 'rd/state.json'])
+        try {
+            await fs.lstat(path.join(directory, name));
+            throw uncertain();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw uncertain();
+        }
+    let handle;
+    try {
+        handle = await fs.open(path.join(directory, 'config.yml'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw uncertain();
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1_048_576 || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()))
+            throw uncertain();
+        const config = loadYaml(await handle.readFile('utf8'));
+        if (config?.desktopProvider || config?.browserBinding)
+            throw uncertain();
+    }
+    catch {
+        throw uncertain();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function claimDeviceDaemonIdentity(directory, claim, startup) {
+    directory = path.resolve(directory);
+    await assertDeviceUpdateTransitionSafe(directory, startup);
+    await assertDeviceDesktopTransitionSafe(directory);
+    const runtime = await inspectRuntime(directory);
+    if (runtime.state !== 'stopped')
+        throw new LocalControlError(runtime.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'Verify and stop the predecessor daemon before starting the device owner');
+    let legacy = false;
+    for (const name of ['config.yml', 'client.key', 'server.pub', 'legacy-migration.json'])
+        try {
+            await fs.lstat(path.join(directory, name));
+            legacy = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    if (legacy) {
+        const migration = await migrateLegacyRegistration(directory, { startupPackage: startup });
+        if (migration.kind === 'needs-verification')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Legacy registration requires verified handoff before device startup');
+    }
+    return withWorkstationLock(directory, 'operation', async () => {
+        await assertDeviceUpdateTransitionSafe(directory, startup);
+        await assertDeviceDesktopTransitionSafe(directory);
+        const current = await inspectRuntime(directory);
+        if (current.state !== 'stopped')
+            throw new LocalControlError(current.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'Cannot verify the predecessor workstation owner');
+        await assertIdentityCanStart(directory);
+        await assertRegistrationEnrollmentAdmission(directory, { startupPackage: startup });
+        const store = new RegistrationStore(directory);
+        const inspection = await store.inspect();
+        if (!inspection.known)
+            throw new LocalControlError('CORRUPT_IDENTITY', 'Registration collection needs verification');
+        for (const entry of inspection.entries)
+            if (entry.state === 'ready' && entry.registration.keeperConfigDirectory === directory) {
+                const config = (await store.read(entry.id)).configuration;
+                if ((config?.desktopProvider || config?.browserBinding) && !await legacyDesktopContinuity(directory))
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Migrated desktop authority requires a verified physical retirement acknowledgement before device startup');
+            }
+        return claim({ store });
+    });
+}
+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) {
+    await assertLegacyRoot(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 () => {
+                await assertLegacyRoot(directory);
+                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/deviceCommands.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { addRegistrationRequestSchema, assertDeviceGuard, deviceInspectionSchema, deviceLifecycleRequestSchema, deviceResultSchema, parseDeviceInspection, removeRegistrationRequestSchema } from './deviceProtocol.js';
+import { LocalControlError } from './protocol.js';
+import { inspectDeviceRuntime, inspectRuntime, removeDeviceRuntimeRegistration, runtimeRequest } from './runtimeClient.js';
+import { RegistrationStore } from '../registrations/store.js';
+import { enrollRegistration } from '../registrations/enrollment.js';
+import { withWorkstationLock } from './locks.js';
+import { createDeviceDaemonController } from '../daemonctl.js';
+import { inspectPendingEnrollments } from '../registrations/enrollmentPending.js';
+import { assertRegistrationEnrollmentAdmission } from '../registrations/migration.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { prepareLegacyBridge } from '../update/legacyBridge.js';
+import { serviceContext } from '../daemonctl.js';
+import { createServiceManager } from '../service/installer.js';
+const removalResponses = new WeakMap();
+export async function inspectDeviceState(options) {
+    const intents = (await options.store.removalIntents()).filter(intent => !['completed', 'cancelled'].includes(intent.phase));
+    const inspection = await options.store.inspect();
+    if (!inspection.known)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration collection needs verification');
+    const aggregate = await options.device?.activitySnapshot();
+    const activities = aggregate?.registrations;
+    const connections = await options.device?.connections();
+    const members = options.device?.snapshot().registrations ?? [];
+    return deviceInspectionSchema.parse({
+        schemaVersion: 2, deviceRevision: createHash('sha256').update(JSON.stringify(inspection.entries.map(entry => [entry.id, entry.state === 'ready' ? entry.registration.revision : entry.target.revision]))).digest('hex'),
+        runtime: { state: 'running', generation: options.generation, mode: options.mode },
+        ...(aggregate ? { desktopActivity: aggregate.desktop } : {}),
+        registrations: inspection.entries.map(entry => {
+            const registration = entry.state === 'ready' ? entry.registration : { id: entry.id, ...entry.target };
+            const member = members.find(candidate => candidate.id === entry.id);
+            const intent = intents.find(candidate => candidate.registration.id === entry.id);
+            return { id: registration.id, server: registration.server, ownerUserId: registration.ownerUserId, workstationId: registration.workstationId, revision: registration.revision,
+                connection: connections?.get(entry.id) ?? 'unknown', identityState: entry.state === 'ready' ? 'ready' : 'corrupt',
+                removalState: intent ? intent.phase === 'restoring' ? 'cleanup-pending' : 'removing' : member?.cleanupPending ? 'cleanup-pending' : 'active',
+                activity: activities?.get(entry.id) ?? { known: false, agents: 0, terminals: 0, commands: 0, transfers: 0, desktopConsumers: 0 } };
+        }),
+        pending: [...intents.map(intent => ({ id: intent.operationId, kind: 'remove', phase: intent.phase, registrationId: intent.registration.id, target: { server: intent.registration.server, ownerUserId: intent.registration.ownerUserId }, outcome: 'pending' })), ...(await inspectPendingEnrollments(options.store.root)).map(enrollment => ({ id: enrollment.operationId, kind: 'register', phase: 'enrollment-needs-verification', registrationId: enrollment.registrationId, target: enrollment.target, outcome: 'unknown' }))],
+    });
+}
+export async function applyDeviceRemoval(value, options) {
+    const parsed = removeRegistrationRequestSchema.safeParse(value);
+    if (!parsed.success)
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local device removal request');
+    const request = parsed.data;
+    let responses = removalResponses.get(options.controller);
+    if (!responses) {
+        responses = new Map();
+        removalResponses.set(options.controller, responses);
+    }
+    const binding = JSON.stringify([request.guard.registrationId, request.guard.registrationRevision, request.guard.runtimeGeneration, request.force]);
+    const existing = responses.get(request.operationId);
+    if (existing) {
+        if (existing.binding !== binding)
+            throw new LocalControlError('BINDING_CONFLICT', 'Original removal response binding changed');
+        return existing.response;
+    }
+    if (responses.size >= 128)
+        throw new LocalControlError('BUSY', 'Too many in-flight removal responses');
+    const response = (async () => {
+        const result = await options.controller.removeRegistration({ id: request.guard.registrationId, expectedRevision: request.guard.registrationRevision, runtimeGeneration: request.guard.runtimeGeneration, operationId: request.operationId, force: request.force });
+        return deviceResultSchema.parse({ operationId: request.operationId, registrationId: request.guard.registrationId, status: result.status === 'removed' ? 'succeeded' : result.status, activity: result.activity, inspection: await options.snapshot() });
+    })().finally(() => { responses.delete(request.operationId); });
+    responses.set(request.operationId, { binding, response });
+    return response;
+}
+export async function executeDeviceCommand(value, directory) {
+    const lifecycle = deviceLifecycleRequestSchema.safeParse(value);
+    if (lifecycle.success) {
+        const request = lifecycle.data;
+        await executeDeviceLifecycle(request.action, directory, { guard: request.guard, operationId: request.operationId });
+        return deviceResultSchema.parse({ operationId: request.operationId, registrationId: null, status: 'succeeded', inspection: await inspectLocalDevice(directory) });
+    }
+    const addition = addRegistrationRequestSchema.safeParse(value);
+    if (addition.success) {
+        const request = addition.data;
+        if (request.guard.runtimeGeneration !== null) {
+            try {
+                const result = deviceResultSchema.parse(await runtimeRequest(directory, 'add-registration', request.guard.runtimeGeneration, { request }, 30_000));
+                if (result.operationId !== request.operationId)
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Original enrollment reply does not match');
+                return result;
+            }
+            catch (error) {
+                if (error instanceof LocalControlError)
+                    throw error;
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original device owner could not confirm enrollment');
+            }
+        }
+        return applyDeviceEnrollment(request, directory, async () => {
+            const runtime = await inspectRuntime(directory);
+            if (runtime.state !== 'stopped')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The workstation owner is not verified stopped');
+            await assertRegistrationEnrollmentAdmission(directory);
+            const current = await inspectDeviceState({ store: new RegistrationStore(directory), generation: 'stopped', mode: 'foreground' });
+            current.runtime = { state: 'stopped', generation: null, mode: 'unknown' };
+            return current;
+        });
+    }
+    const parsed = removeRegistrationRequestSchema.safeParse(value);
+    if (!parsed.success)
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local device removal request');
+    const request = parsed.data;
+    try {
+        return await removeDeviceRuntimeRegistration(directory, request);
+    }
+    catch (error) {
+        if (!(error instanceof LocalControlError) || error.code !== 'OUTCOME_UNKNOWN')
+            throw error;
+        return { operationId: request.operationId, registrationId: request.guard.registrationId, status: 'pending', inspection: null, error: { code: 'OUTCOME_UNKNOWN', message: 'Original owner removal remains unconfirmed; retry the same operation' } };
+    }
+}
+export async function executeDeviceLifecycle(action, directory, request) {
+    if (action === 'install' && !request) {
+        const legacy = await inspectRuntime(directory);
+        if (legacy.state === 'running' && legacy.binding) {
+            const context = { ...serviceContext(), configDir: directory };
+            await prepareLegacyBridge(directory, context);
+            await createServiceManager(context).install({ interactive: true });
+            return;
+        }
+    }
+    const before = await inspectLocalDevice(directory);
+    if (request)
+        assertDeviceGuard(request.guard, before);
+    const controller = createDeviceDaemonController(directory);
+    if (before.runtime.state === 'running') {
+        if (action === 'install') {
+            // Existing updaters invoke the public install command while their original owner is
+            // still alive. Only the exact private recovery transaction can admit that handoff.
+            if (!request) {
+                let pendingUpdate = false;
+                try {
+                    await fs.lstat(path.join(directory, 'update/device-transaction.json'));
+                    pendingUpdate = true;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                if (pendingUpdate) {
+                    await controller.install({ updateGeneration: before.runtime.generation });
+                    return;
+                }
+            }
+            throw new LocalControlError('INSTANCE_OCCUPIED', 'Stop the whole device before reinstalling its service');
+        }
+        await controller[action]({ guard: { deviceRevision: before.deviceRevision, runtimeGeneration: before.runtime.generation }, operationId: request?.operationId ?? randomUUID() });
+        return;
+    }
+    await withWorkstationLock(directory, 'operation', async () => {
+        if ((await inspectRuntime(directory)).state !== 'stopped')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'The workstation owner changed before the service action');
+        const current = await inspectDeviceState({ store: new RegistrationStore(directory), generation: 'stopped', mode: 'foreground' });
+        current.runtime = { state: 'stopped', generation: null, mode: 'unknown' };
+        assertDeviceGuard(request?.guard ?? { deviceRevision: before.deviceRevision, runtimeGeneration: null }, current);
+        await controller[action]();
+    });
+}
+export async function applyDeviceEnrollment(value, directory, snapshot, assertAdmission) {
+    assertAdmission?.();
+    const parsed = addRegistrationRequestSchema.safeParse(value);
+    if (!parsed.success)
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local device enrollment request');
+    const request = parsed.data;
+    const result = await enrollRegistration(request.input, directory, { beforeEnrollment: async () => { assertAdmission?.(); assertDeviceGuard(request.guard, await snapshot()); assertAdmission?.(); } });
+    return deviceResultSchema.parse({ operationId: request.operationId, registrationId: result.registration.id, status: 'succeeded', inspection: await snapshot() });
+}
+export async function inspectLocalDevice(directory) {
+    try {
+        return parseDeviceInspection(await inspectDeviceRuntime(directory));
+    }
+    catch (error) {
+        const runtime = await inspectRuntime(directory);
+        if (runtime.state !== 'stopped') {
+            if (runtime.state === 'running' && runtime.binding)
+                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'A legacy single-registration owner is still running. Automatic migration requires its verified active update handoff. Allow the original update to finish and preserve the workstation data and update evidence.');
+            if (error instanceof LocalControlError && error.code === 'UNSUPPORTED_PROTOCOL')
+                throw error;
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'The workstation owner is unavailable or unknown; verify it before continuing');
+        }
+        return withWorkstationLock(directory, 'operation', async () => {
+            if ((await inspectRuntime(directory)).state !== 'stopped')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The workstation owner changed during inspection');
+            await assertRegistrationEnrollmentAdmission(directory);
+            const inspection = await inspectDeviceState({ store: new RegistrationStore(directory), generation: 'stopped', mode: 'foreground' });
+            return deviceInspectionSchema.parse({ ...inspection, runtime: { state: 'stopped', generation: null, mode: 'unknown' }, registrations: inspection.registrations.map(registration => ({ ...registration, connection: 'offline' })) });
+        });
+    }
+}

package/dist/workstation/control/deviceProtocol.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { registrationActivitySchema, registrationIdentitySchema, registrationIdSchema, registrationKey, registrationServerSchema } from '../registrations/model.js';
+import { LocalControlError, localErrorCodeSchema } from './protocol.js';
+import { operationIdSchema, registrationEnrollmentInputSchema } from '../registrations/enrollmentPending.js';
+import { deviceReleaseSchema } from '../update/deviceHealthProtocol.js';
+export const deviceGuardSchema = z.object({ deviceRevision: z.string().min(1), runtimeGeneration: z.string().min(1).nullable() }).strict();
+export const registrationGuardSchema = deviceGuardSchema.extend({ registrationId: registrationIdSchema, registrationRevision: z.string().min(1) }).strict();
+export const removeRegistrationRequestSchema = z.object({ schemaVersion: z.literal(2), action: z.literal('remove-registration'), operationId: operationIdSchema, guard: registrationGuardSchema.extend({ runtimeGeneration: z.string().min(1).max(128) }).strict(), force: z.boolean() }).strict();
+export const addRegistrationRequestSchema = z.object({ schemaVersion: z.literal(2), action: z.literal('add-registration'), operationId: operationIdSchema, guard: deviceGuardSchema, input: registrationEnrollmentInputSchema }).strict().refine(value => value.operationId === value.input.operationId, 'Enrollment operation IDs must match');
+export const deviceLifecycleRequestSchema = z.object({ schemaVersion: z.literal(2), action: z.enum(['start', 'stop', 'restart', 'install', 'uninstall']), operationId: operationIdSchema, guard: deviceGuardSchema }).strict();
+export const deviceRuntimeUpdateRequestSchema = z.object({ schemaVersion: z.literal(2), action: z.literal('update'), operationId: operationIdSchema, server: registrationServerSchema, guard: deviceGuardSchema, release: deviceReleaseSchema }).strict();
+export const registrationSnapshotSchema = registrationIdentitySchema.extend({
+    connection: z.enum(['offline', 'connecting', 'online', 'reconnecting', 'rejected', 'unknown']),
+    identityState: z.enum(['absent', 'ready', 'incomplete', 'corrupt']),
+    removalState: z.enum(['active', 'removing', 'cleanup-pending']),
+    activity: registrationActivitySchema,
+}).strict();
+export const deviceOperationKindSchema = z.enum(['register', 'start', 'stop', 'remove', 'update']);
+export const deviceOperationRecordSchema = z.object({
+    id: z.string().min(1), kind: deviceOperationKindSchema, phase: z.string().min(1).max(80),
+    registrationId: registrationIdSchema.nullable(),
+    target: z.object({ server: registrationServerSchema, ownerUserId: z.string().min(1) }).strict().nullable(),
+    outcome: z.enum(['pending', 'succeeded', 'failed', 'unknown']),
+}).strict();
+export const deviceInspectionSchema = z.object({
+    schemaVersion: z.literal(2), deviceRevision: z.string().min(1),
+    runtime: z.object({
+        state: z.enum(['stopped', 'running', 'unknown']), generation: z.string().min(1).nullable(),
+        mode: z.enum(['launchd', 'foreground', 'unknown']),
+    }).strict(),
+    registrations: z.array(registrationSnapshotSchema),
+    pending: z.array(deviceOperationRecordSchema),
+    desktopActivity: z.strictObject({ known: z.boolean(), consumers: z.number().int().min(0).max(65536) }).optional(),
+    desktop: z.strictObject({ deviceEpoch: z.string().min(1).max(128), hostLifetimeId: z.string().min(1).max(128).nullable(), hostRetired: z.boolean() })
+        .refine(value => !value.hostRetired || value.hostLifetimeId !== null).optional(),
+}).strict().refine(value => {
+    const ids = new Set(value.registrations.map(registration => registration.id));
+    const keys = new Set(value.registrations.map(registration => registrationKey(registration.server, registration.ownerUserId)));
+    return ids.size === value.registrations.length && keys.size === value.registrations.length;
+}, 'Registrations require unique IDs and server/account identities');
+export const deviceResultSchema = z.object({
+    operationId: z.string().min(1), registrationId: registrationIdSchema.nullable(),
+    status: z.enum(['succeeded', 'busy', 'pending', 'failed', 'conflict']),
+    inspection: deviceInspectionSchema.nullable(),
+    activity: registrationActivitySchema.nullable().optional(),
+    error: z.object({ code: localErrorCodeSchema, message: z.string().max(1024) }).strict().optional(),
+}).strict().refine(value => value.status !== 'succeeded' || value.inspection !== null, 'Successful operations require inspection');
+export const deviceEventSchema = z.discriminatedUnion('kind', [
+    z.object({ schemaVersion: z.literal(2), kind: z.literal('progress'), operationId: z.string().min(1), registrationId: registrationIdSchema.nullable(), phase: z.string().min(1).max(80) }).strict(),
+    z.object({ schemaVersion: z.literal(2), kind: z.literal('result'), operationId: z.string().min(1), result: deviceResultSchema }).strict(),
+]).refine(value => value.kind !== 'result' || value.operationId === value.result.operationId, 'Result operation IDs must match');
+export function parseDeviceInspection(value) {
+    if (typeof value === 'object' && value !== null && 'schemaVersion' in value && value.schemaVersion !== 2) {
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Unsupported workstation device protocol');
+    }
+    return deviceInspectionSchema.parse(value);
+}
+export function assertDeviceGuard(guard, inspection) {
+    if (guard.deviceRevision !== inspection.deviceRevision || guard.runtimeGeneration !== inspection.runtime.generation) {
+        throw new LocalControlError('BINDING_CONFLICT', 'The local device changed');
+    }
+}
+export function assertRegistrationGuard(guard, inspection) {
+    const registration = inspection.registrations.find(candidate => candidate.id === guard.registrationId);
+    if (!registration || registration.revision !== guard.registrationRevision || guard.runtimeGeneration !== inspection.runtime.generation) {
+        throw new LocalControlError('BINDING_CONFLICT', 'The local registration changed');
+    }
+}

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) }));
+}