@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/control/daemonIdentity.js

@@ -5,6 +5,94 @@ 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'))));
@@ -17,6 +105,7 @@ export async function assertIdentityCanStart(directory) {
     }
 }
 export async function recoverStoppedIdentity(directory) {
+    await assertLegacyRoot(directory);
     const store = new BindingStore(directory);
     if ((await store.inspect()).identityState === 'incomplete') {
         const runtime = await inspectRuntime(directory);
@@ -32,6 +121,7 @@ export async function claimDaemonIdentity(directory, claim) {
     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');

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/locks.js

@@ -9,8 +9,52 @@ 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');
+    let lease = ownership.getStore();
+    while (lease) {
+        if (!lease.valid || !lease.active)
+            throw new LocalControlError('BUSY', 'Workstation lock ownership was lost or released');
+        lease = lease.parent;
+    }
+}
+function operationLease(directory) {
+    const expected = path.join(path.resolve(directory), 'control/operation');
+    let lease = ownership.getStore();
+    let held;
+    while (lease) {
+        if (!lease.valid || !lease.active)
+            throw new LocalControlError('BUSY', 'Workstation operation lock ownership was lost or released');
+        if (lease.stem === expected)
+            held = lease;
+        lease = lease.parent;
+    }
+    if (!held)
+        throw new LocalControlError('BUSY', 'The workstation operation lock is required');
+    return held;
+}
+export function assertWorkstationOperationLock(directory) { return operationLease(directory); }
+export function assertOutsideOperationLease() {
+    let lease = ownership.getStore();
+    while (lease) {
+        if (path.basename(lease.stem) === 'operation')
+            throw new LocalControlError('BUSY', 'Owner control requires an outside-operation context');
+        lease = lease.parent;
+    }
+}
+export function registerOperationLeaseFinalizer(directory, finalizer) {
+    operationLease(directory).finalizers.add(finalizer);
+}
+function finalize(lease) {
+    lease.active = false;
+    const callbacks = [...lease.finalizers];
+    lease.finalizers.clear();
+    for (const callback of callbacks) {
+        try {
+            callback();
+        }
+        catch (error) {
+            lease.finalizerErrors.push(error);
+        }
+    }
 }
 export async function withPrivateLock(stem, work) {
     await privateDirectory(path.dirname(stem));
@@ -34,11 +78,11 @@ export async function withPrivateLock(stem, work) {
         if (lockPresent || error.code !== 'ENOENT')
             throw new LocalControlError('BUSY', 'Another workstation operation is active');
     }
-    const lease = { valid: true };
+    const lease = { valid: true, active: true, stem: path.resolve(stem), parent: ownership.getStore(), finalizers: new Set(), finalizerErrors: [] };
     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; } });
+        release = await lockfile.lock(stem, { realpath: false, stale: 30_000, update: 2_000, retries: 0, onCompromised: () => { lease.valid = false; finalize(lease); } });
     }
     catch {
         throw new LocalControlError('BUSY', 'Another workstation operation is active');
@@ -48,6 +92,7 @@ export async function withPrivateLock(stem, work) {
         return await ownership.run(lease, async () => { const result = await work(); assertLockOwnership(); return result; });
     }
     finally {
+        finalize(lease);
         if (lease.valid) {
             try {
                 if (JSON.parse(await fs.readFile(ownerFile, 'utf8')).nonce === nonce)
@@ -56,6 +101,8 @@ export async function withPrivateLock(stem, work) {
             catch { /* release still required */ }
             await release();
         }
+        if (lease.finalizerErrors.length)
+            throw new AggregateError(lease.finalizerErrors, 'Workstation lease finalizers failed');
     }
 }
 export function withWorkstationLock(directory, name, work) {

package/dist/workstation/control/rootFormat.js

@@ -0,0 +1,16 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { LocalControlError } from './protocol.js';
+export async function assertLegacyRoot(directory) {
+    for (const name of ['device.json', 'legacy-migration.json']) {
+        try {
+            await fs.lstat(path.join(directory, name));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        throw new LocalControlError('CORRUPT_IDENTITY', 'This workstation uses registrations; legacy identity writes and startup are unsupported');
+    }
+}

package/dist/workstation/control/runtimeClient.js

@@ -1,8 +1,52 @@
 import net from 'node:net';
 import { runtimePaths, readControlFile, runtimeOwnerLive } from './runtimeHost.js';
-import { runtimeSnapshotSchema, stoppedRuntime, LocalControlError } from './protocol.js';
+import { runtimeSnapshotSchema, stoppedRuntime, LocalControlError, localErrorCodeSchema } from './protocol.js';
 import { pidAlive } from '../keepers/kit/lock.js';
-export async function runtimeRequest(directory, action, expectedGeneration, extra = {}) {
+import { parseDeviceInspection, deviceResultSchema, deviceRuntimeUpdateRequestSchema, removeRegistrationRequestSchema } from './deviceProtocol.js';
+export async function removeDeviceRuntimeRegistration(directory, value) {
+    const request = removeRegistrationRequestSchema.parse(value);
+    let response;
+    try {
+        response = await runtimeRequest(directory, 'remove-registration', request.guard.runtimeGeneration, { request }, 15_000);
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original running owner could not confirm removal');
+    }
+    const result = deviceResultSchema.parse(response);
+    if (result.operationId !== request.operationId || result.registrationId !== request.guard.registrationId)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original removal reply does not match');
+    return result;
+}
+export async function inspectDeviceRuntime(directory) {
+    return parseDeviceInspection(await runtimeRequest(directory, 'inspect'));
+}
+export async function prepareDeviceRuntimeStop(directory, generation, stopMode, operationId) {
+    const receipt = await runtimeRequest(directory, 'prepare-stop', generation, { stopMode, operationId }, 15_000);
+    if (receipt.prepared !== true || receipt.generation !== generation || receipt.stopMode !== stopMode)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Device shutdown preparation was not confirmed');
+}
+export async function stopDeviceRuntime(directory, generation, stopMode) {
+    await runtimeRequest(directory, 'stop', generation, { stopMode });
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        try {
+            const current = await inspectDeviceRuntime(directory);
+            if (current.runtime.generation !== generation)
+                throw new LocalControlError('BINDING_CONFLICT', 'A new device daemon started');
+        }
+        catch (error) {
+            if (error instanceof LocalControlError && error.code === 'BINDING_CONFLICT')
+                throw error;
+            if ((await inspectRuntime(directory)).state === 'stopped')
+                return;
+        }
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    throw new LocalControlError('OUTCOME_UNKNOWN', 'Device shutdown has not been confirmed');
+}
+export async function runtimeRequest(directory, action, expectedGeneration, extra = {}, timeoutMs = 3000) {
     const paths = runtimePaths(directory);
     const owner = JSON.parse(await readControlFile(paths.ownerFile));
     if (typeof owner.generation !== 'string' || !pidAlive(owner.pid))
@@ -19,7 +63,7 @@ export async function runtimeRequest(directory, action, expectedGeneration, extr
             socket.destroy();
             reject(error);
         } };
-        socket.setTimeout(3000, () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Runtime did not respond')));
+        socket.setTimeout(timeoutMs, () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Runtime did not respond')));
         socket.on('error', () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Cannot contact runtime')));
         socket.on('end', () => { if (!done)
             fail(new LocalControlError('OUTCOME_UNKNOWN', 'Incomplete runtime response')); });
@@ -34,8 +78,10 @@ export async function runtimeRequest(directory, action, expectedGeneration, extr
                 return;
             try {
                 const result = JSON.parse(data.split('\n')[0]);
-                if (!result.ok)
-                    throw new LocalControlError(result.code === 'BINDING_CONFLICT' ? result.code : 'SERVICE_FAILED', 'Runtime rejected the request');
+                if (!result.ok) {
+                    const code = localErrorCodeSchema.safeParse(result.code);
+                    throw new LocalControlError(code.success ? code.data : 'SERVICE_FAILED', 'Runtime rejected the request');
+                }
                 done = true;
                 socket.destroy();
                 resolve(result.value);
@@ -95,3 +141,12 @@ export async function stopRuntime(directory, expectedGeneration) {
 export async function requestRuntimeUpdate(directory, release, operationId) {
     return await runtimeRequest(directory, 'update', undefined, { release, operationId });
 }
+export async function requestDeviceRuntimeUpdate(directory, raw) {
+    const request = deviceRuntimeUpdateRequestSchema.parse(raw);
+    if (!request.guard.runtimeGeneration)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'An original live device owner is required for update admission');
+    const status = await runtimeRequest(directory, 'update', request.guard.runtimeGeneration, { request }, 30_000);
+    if (!status || status.commandId !== request.operationId || !['REQUESTED', 'DRAINING', 'BUSY', 'DOWNLOADING', 'VERIFYING', 'INSTALLING', 'RESTARTING', 'SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'UPDATE_IN_PROGRESS'].includes(status.phase))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original device update reply does not match its operation');
+    return status;
+}