@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/runtime/registrationRuntime.js

@@ -0,0 +1,575 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { replaceDesktopBinding, holdDesktopForTargetProbe } from './desktopBinding.js';
+import { AgentSessionManager } from '../agentSessions.js';
+import { AcpAgents } from '../acp/acpAgents.js';
+import { ConnectionSupervisor } from '../connection/supervisor.js';
+import { ManagementChannel } from '../channels/management.js';
+import { ComputerChannel } from '../channels/computer.js';
+import { AgentChannel } from '../channels/agent.js';
+import { TaskRegistry } from '../update/taskRegistry.js';
+import { FilesHostClient } from '../files/client.js';
+import { WorkstationTools } from '../tools/router.js';
+import { aggregateToolsInfo, computeFilesInfo } from '../tools/info.js';
+import { defaultDistDir, KeeperLauncher } from '../keepers/kit/launcher.js';
+import { readKeeperManifest } from '../keepers/kit/bundle.js';
+import { KEEPER_POLICY_TICK_MS, KeeperPolicy, oneShotDrain, oneShotProbe } from '../keepers/policy.js';
+import { TerminalGenerations } from '../keepers/terminal/generations.js';
+import { AcpKeeperClient } from '../keepers/acp/client.js';
+import { KeeperTransport } from '../acp/processor/transport/keeper.js';
+import { keeperGenerations } from '../acp/processor/transport/generations.js';
+import { ExecPolicy } from '../exec/policy.js';
+import { TerminalRouter, terminalEnv, terminalShell } from '../tools/terminalRouter.js';
+import { LocalTransport } from '../acp/processor/transport/local.js';
+import { RegistrationDesktopAdapter } from './remoteDesktopAdapter.js';
+import { resolveRegistrationOwnership } from './ownership.js';
+import { randomUUID } from 'node:crypto';
+import { assertRemovalNamespace } from '../registrations/migration.js';
+import { TargetRemovalActivity } from './removalActivity.js';
+import { LocalControlError } from '../control/protocol.js';
+import { withWorkstationLock } from '../control/locks.js';
+import { resolveRemovalNamespaceLocked } from '../registrations/migration.js';
+import { buildKeeperStatuses, existingDirectories, workspaceRoots, startExclusivePoll, startIdleSweep, maintainAdapterBuilds, FILES_ROOTS_POLL_MS, SWITCH_POLL_INTERVAL_MS } from '../daemon.js';
+export function createRegistrationRuntime(input) {
+    const shutdown = new AbortController();
+    const admission = { open: true, external: 0, final: false, background: 0, backgroundKnown: true };
+    const lifetime = {};
+    let admissionRevision = 0;
+    const holds = new WeakMap();
+    let removal;
+    const removalFor = (preparation) => {
+        if (!removal || removal.preparation !== preparation)
+            throw new LocalControlError('BINDING_CONFLICT', 'Original target resource preparation is unavailable');
+        return removal;
+    };
+    const originalHold = (hold) => {
+        const state = holds.get(hold);
+        if (!state || state.lifetime !== lifetime || shutdown.signal.aborted)
+            throw new Error('Invalid or stale target admission hold');
+        return state;
+    };
+    const cleanup = [];
+    let initialized;
+    let stopped;
+    let terminationSettled = false;
+    let terminationPreparation;
+    let deviceAdmissionHold;
+    const release = async () => {
+        let failure;
+        const retry = [];
+        for (const close of cleanup.splice(0).reverse())
+            try {
+                await close();
+            }
+            catch (error) {
+                failure ??= error;
+                retry.push(close);
+            }
+        cleanup.push(...retry.reverse());
+        if (failure)
+            throw failure;
+    };
+    const runtime = {
+        async start() {
+            if (shutdown.signal.aborted)
+                throw new Error('Registration is stopped');
+            initialized ??= initializeRegistration(input, shutdown, cleanup, admission).catch(async (error) => {
+                shutdown.abort();
+                try {
+                    await release();
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], 'Registration initialization and retained cleanup failed');
+                }
+                throw error;
+            });
+            await initialized;
+        },
+        async releaseStartupAdmission() {
+            const original = admission.startup;
+            if (!original)
+                return;
+            admission.tasks.releaseExternalAdmission(original.tasks);
+            admission.external -= 1;
+            admission.startup = undefined;
+            if (!admission.external && !admission.final && !shutdown.signal.aborted)
+                admission.desktop?.resumeNewAdmission();
+        },
+        async prepareTargetAdmission(target) {
+            if (removal)
+                throw new LocalControlError('BUSY', 'Original target resource preparation is already active');
+            if (admission.final || target.id !== input.registration.id || target.expectedRevision !== input.registration.revision || !target.operationId || shutdown.signal.aborted || stopped || !admission.tasks)
+                throw new Error('Target runtime is unavailable or changed');
+            if (!Number.isSafeInteger(admission.external + 1))
+                throw new Error('Target admission accounting is uncertain');
+            const taskHold = admission.tasks.holdExternalAdmission();
+            admission.external += 1;
+            const hold = Object.freeze({});
+            holds.set(hold, { lifetime, active: true, operationId: target.operationId, tasks: admission.tasks, taskHold });
+            try {
+                await holdDesktopForTargetProbe(admission.desktop);
+            }
+            catch (error) {
+                admission.tasks.releaseExternalAdmission(taskHold);
+                admission.external -= 1;
+                holds.delete(hold);
+                if (!admission.external && !admission.final)
+                    admission.desktop?.resumeNewAdmission();
+                throw error;
+            }
+            return hold;
+        },
+        observeTargetAdmission(hold) {
+            const state = originalHold(hold);
+            if (!state.active)
+                throw new Error('Target admission hold is released');
+            const observed = state.tasks.observeTargetPending();
+            return { status: observed.pending > 0 || observed.registered > 0 ? 'busy' : 'unknown', pending: observed.pending, registered: observed.registered,
+                diagnostics: [...(!observed.known ? ['Agent accounting is uncertain'] : []), 'Files, native and legacy membership remains unresolved'] };
+        },
+        async holdTargetEvidenceAdmission(hold) {
+            const state = originalHold(hold);
+            if (!state.active)
+                throw new LocalControlError('BINDING_CONFLICT', 'Target admission hold is released');
+        },
+        async releaseTargetAdmission(hold) {
+            const state = originalHold(hold);
+            if (!state.active)
+                return;
+            state.tasks.releaseExternalAdmission(state.taskHold);
+            state.active = false;
+            admission.external -= 1;
+            if (!admission.external && !admission.final && !shutdown.signal.aborted)
+                admission.desktop?.resumeNewAdmission();
+        },
+        async prepareTargetResources(hold, restoreAdmission) {
+            const state = originalHold(hold);
+            if (removal)
+                throw new LocalControlError('BUSY', 'Original target resource preparation is already active');
+            if (!state.active || !admission.resources)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Target resources are unavailable');
+            removal = new TargetRemovalActivity({ ...admission.resources, registration: input.registration, lifetime, operationId: state.operationId,
+                validate: () => { if (originalHold(hold) !== state || !state.active)
+                    throw new LocalControlError('BINDING_CONFLICT', 'Original target hold changed'); },
+                background: () => ({ pending: admission.background, known: admission.backgroundKnown }),
+                desktopActivity: admission.desktop ? () => admission.desktop.activity() : undefined,
+                beginFinal: () => { admission.final = true; admission.open = false; admission.set?.(false); },
+                closeDesktopAdmission: admission.desktop || input.remoteDesktopLifecycle ? async () => {
+                    const results = await Promise.allSettled([admission.desktop?.closeAdmission(), input.remoteDesktopLifecycle?.closeAdmission()]);
+                    for (const result of results)
+                        if (result.status === 'rejected')
+                            throw result.reason;
+                } : undefined,
+                isolateDesktop: admission.desktop || input.remoteDesktopLifecycle ? async () => {
+                    const results = await Promise.allSettled([admission.desktop?.isolateOriginal(), input.remoteDesktopLifecycle?.isolateOriginal()]);
+                    for (const result of results)
+                        if (result.status === 'rejected')
+                            throw result.reason;
+                } : undefined,
+                restore: async () => {
+                    if (restoreAdmission)
+                        await restoreAdmission();
+                    else
+                        await runtime.releaseTargetAdmission(hold);
+                    if (state.active)
+                        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original target admission restoration is incomplete');
+                } });
+            return removal.preparation;
+        },
+        observeTargetResources: async (preparation) => removalFor(preparation).observe(),
+        sealTargetResources: async (preparation, mode) => removalFor(preparation).seal(mode),
+        settleTargetResources: async (preparation, namespace) => removalFor(preparation).settle(namespace),
+        prepareTargetDisposition: async (preparation, namespace) => removalFor(preparation).prepareDisposition(lifetime, namespace),
+        async disposeTargetResources(settlement, namespace) {
+            if (!removal)
+                throw new LocalControlError('BINDING_CONFLICT', 'Original target settlement is unavailable');
+            if (!removal.continueDisposition(settlement, lifetime, namespace)) {
+                removal.assertSettlement(settlement, lifetime, namespace);
+                removal.consume(settlement, lifetime, namespace);
+            }
+            terminationSettled = true;
+            await runtime.stop('detach');
+            assertRemovalNamespace(namespace);
+            removal.disposed();
+        },
+        async releaseTargetResources(preparation) { const original = removalFor(preparation); await original.release(); if (removal === original)
+            removal = undefined; },
+        async pauseAdmission() {
+            admissionRevision += 1;
+            admission.open = false;
+            admission.set?.(false);
+            if (admission.tasks)
+                deviceAdmissionHold ??= admission.tasks.holdExternalAdmission();
+            const outcomes = await Promise.allSettled([admission.desktop?.closeAdmission(), input.remoteDesktopLifecycle?.closeAdmission()]);
+            const failures = outcomes.flatMap(outcome => outcome.status === 'rejected' ? [outcome.reason] : []);
+            if (failures.length)
+                throw new AggregateError(failures, 'Original registration admission remains pending');
+        },
+        resumeAdmission() {
+            if (admission.final)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original final resource settlement cannot reopen admission');
+            admissionRevision += 1;
+            const revision = admissionRevision;
+            const reopen = () => {
+                if (!shutdown.signal.aborted && revision === admissionRevision) {
+                    if (deviceAdmissionHold) {
+                        admission.tasks.releaseExternalAdmission(deviceAdmissionHold);
+                        deviceAdmissionHold = undefined;
+                    }
+                    admission.open = true;
+                    admission.set?.(true);
+                    admission.desktop?.resumeAdmission();
+                }
+            };
+            reopen();
+        },
+        async activity() { return initialized ? (await initialized).activity() : { known: false, agents: 0, terminals: 0, commands: 0, transfers: 0, desktopConsumers: 0 }; },
+        async connection() { return initialized ? (await initialized).connection?.() ?? 'unknown' : 'offline'; },
+        stop(mode) {
+            admissionRevision += 1;
+            admission.open = false;
+            admission.set?.(false);
+            if (admission.tasks)
+                deviceAdmissionHold ??= admission.tasks.holdExternalAdmission();
+            stopped ??= (async () => {
+                if (mode === 'terminate' && !terminationSettled && admission.resources && input.registrationRoot) {
+                    if (!removal) {
+                        terminationPreparation ??= (async () => {
+                            const hold = await runtime.prepareTargetAdmission({ id: input.registration.id, expectedRevision: input.registration.revision, operationId: randomUUID() });
+                            return runtime.prepareTargetResources(hold);
+                        })();
+                        await terminationPreparation;
+                    }
+                    await removal.prepareTermination();
+                    await withWorkstationLock(input.registrationRoot, 'operation', async () => {
+                        const namespace = await resolveRemovalNamespaceLocked(input.registrationRoot, input.registration.id, input.registration.revision);
+                        const settlement = await removal.prepareDisposition(lifetime, namespace);
+                        if (!removal.continueDisposition(settlement, lifetime, namespace))
+                            removal.consume(settlement, lifetime, namespace);
+                        terminationSettled = true;
+                    });
+                }
+                shutdown.abort();
+                let failure;
+                try {
+                    await (await initialized?.catch(() => undefined))?.stop(terminationSettled ? 'detach' : mode);
+                }
+                catch (error) {
+                    failure = error;
+                }
+                try {
+                    await release();
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+                if (failure)
+                    throw failure;
+            })().catch(error => { stopped = undefined; throw error; });
+            return stopped;
+        },
+    };
+    return runtime;
+}
+async function initializeRegistration(input, shutdown, cleanup, admission) {
+    const { registration, clientKey, serverPub, paths, deviceServices } = input;
+    const dir = registration.dataDirectory;
+    const cfg = input.configuration ?? { server: registration.server, workstationId: registration.workstationId, ownerUserId: registration.ownerUserId };
+    const keeperServer = paths.legacySources?.keeperServer ?? registration.server;
+    const ownership = await resolveRegistrationOwnership(registration, paths.legacySources);
+    const tasks = new TaskRegistry();
+    admission.tasks = tasks;
+    shutdown.signal.addEventListener('abort', () => tasks.closeAgentWorkLifetime(), { once: true });
+    tasks.accepting = admission.open;
+    admission.set = open => { tasks.accepting = open; };
+    const background = async (work) => {
+        if (admission.final)
+            return;
+        admission.background += 1;
+        if (!Number.isSafeInteger(admission.background)) {
+            admission.backgroundKnown = false;
+            throw new Error('Background accounting is uncertain');
+        }
+        try {
+            await work();
+        }
+        catch (error) {
+            admission.backgroundKnown = false;
+            throw error;
+        }
+        finally {
+            admission.background -= 1;
+        }
+    };
+    deviceServices.register(registration.id, cfg);
+    cleanup.push(async () => deviceServices.unregister(registration.id));
+    const acpLauncher = new KeeperLauncher({ configDir: registration.keeperConfigDirectory, workstationId: cfg.workstationId, server: keeperServer, ownership });
+    const acpTransport = new KeeperTransport(new AcpKeeperClient({ launcher: acpLauncher }));
+    const acpGenerations = keeperGenerations({ launcher: acpLauncher, current: acpTransport });
+    const localTransport = new LocalTransport({ configDir: dir, outboxDirectory: paths.legacySources?.localOutboxDirectory, ownership });
+    const acp = new AcpAgents({ cacheDir: dir, adapterCacheDirectory: paths.legacySources?.adapterCacheDirectory, ownership, serverOrigin: cfg.server, transports: { keeper: acpTransport, local: localTransport }, keeperGenerations: acpGenerations });
+    const agents = new AgentSessionManager(acp, null, paths.legacySources ? path.dirname(paths.legacySources.journalDirectory) : path.join(dir, 'agents'), tasks, () => admission.open, ownership);
+    cleanup.push(async () => { await agents.detachAll(); await acp.closeTransports(); });
+    await agents.adoptSessions();
+    let bridges = await acp.roster();
+    const scanRoster = () => acp.roster({ sessions: (session) => agents.rosterSessionState(session) });
+    let supervisor;
+    const allowInsecureWs = input.allowInsecureWs ?? process.env.AXOM_WORKSTATION_ALLOW_INSECURE_WS === '1';
+    const home = input.homeDirectory ?? os.homedir();
+    const playgroundCwd = path.join(home, '.axom', 'playground');
+    await fs.mkdir(playgroundCwd, { recursive: true });
+    let roots = workspaceRoots(cfg, home);
+    let hostRoots = [];
+    const filesHost = new FilesHostClient({
+        configDir: dir,
+        options: async () => { hostRoots = await existingDirectories(roots); return { home, roots: hostRoots, mediaCache: path.join(dir, 'media-cache') }; },
+        onActivityChanged: () => tasks.externalActivityChanged(),
+        log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+    });
+    tasks.externalActivity = () => filesHost.activity();
+    cleanup.push(() => filesHost.stop());
+    filesHost.start();
+    const stopRootsPoll = startExclusivePoll(async () => {
+        if (admission.external || admission.final)
+            return;
+        await background(async () => {
+            try {
+                roots = workspaceRoots(cfg, home);
+                const current = await existingDirectories(roots);
+                if (!admission.final && !admission.external && JSON.stringify(current) !== JSON.stringify(hostRoots))
+                    filesHost.reconfigure();
+            }
+            catch { }
+        });
+    }, FILES_ROOTS_POLL_MS);
+    cleanup.push(async () => stopRootsPoll());
+    const toolsConfig = { configDir: registration.keeperConfigDirectory, workstationId: cfg.workstationId, server: keeperServer, roots };
+    const terminalLauncher = new KeeperLauncher({ configDir: registration.keeperConfigDirectory, workstationId: cfg.workstationId, server: keeperServer, ownership });
+    admission.resources = { tasks, filesHost, localTransport, launchers: [acpLauncher, terminalLauncher], activity: () => activity() };
+    const terminalKeepers = new TerminalGenerations({ launcher: terminalLauncher });
+    cleanup.push(async () => terminalKeepers.disconnect());
+    const terminals = new TerminalRouter({
+        kit: terminalKeepers.primary,
+        launch: async (cwd) => ({ cwd: await filesHost.terminalCwd(cwd), shell: terminalShell(), env: terminalEnv() }),
+    });
+    const workstationTools = new WorkstationTools({
+        files: filesHost,
+        terminal: (method, params) => terminals.request(method, params),
+        browser: async () => { throw new Error('Device desktop control is unavailable until physical isolation is integrated'); },
+        info: () => aggregateToolsInfo({
+            files: async () => filesHost.info() ?? computeFilesInfo(home, roots),
+            terminal: () => terminalKeepers.primary.terminalStatus(() => ({ terminal: false })),
+            browser: async () => ({ browser: false, browserError: 'Device desktop control is unavailable until physical isolation is integrated' }),
+        }),
+    });
+    const rawDrainKeeper = oneShotDrain((kind, gen) => (kind === 'acp' ? acpLauncher : terminalLauncher).pathsFor(kind, gen));
+    const drainKeeper = async (kind, gen) => {
+        await (kind === 'acp' ? acpLauncher : terminalLauncher).assertKeeperResources(kind, gen);
+        await rawDrainKeeper(kind, gen);
+    };
+    const probeKeeper = oneShotProbe((kind, gen) => (kind === 'acp' ? acpLauncher : terminalLauncher).pathsFor(kind, gen));
+    const keeperPolicy = new KeeperPolicy({
+        dir: path.join(registration.keeperConfigDirectory, 'keepers'),
+        probe: async (kind, gen, timeoutMs) => {
+            await (kind === 'acp' ? acpLauncher : terminalLauncher).assertKeeperResources(kind, gen, timeoutMs);
+            return probeKeeper(kind, gen, timeoutMs);
+        },
+        terminal: {
+            currentGen: () => terminalKeepers.currentGen(),
+            live: async () => (await terminalKeepers.running()).map((generation) => generation.gen),
+            manifest: () => terminalKeepers.manifest(),
+            stop: async (gen, mode) => {
+                const result = await terminalLauncher.stop('terminal', gen, mode);
+                if (result.stopped)
+                    terminalKeepers.forget(gen);
+                return result;
+            },
+            reachable: async (gen) => (await terminalKeepers.client(gen)).runningHello(),
+            drain: (gen) => drainKeeper('terminal', gen),
+        },
+        acp: {
+            currentGen: () => acpGenerations.current(),
+            live: () => acpGenerations.live(),
+            manifest: () => readKeeperManifest(path.join(defaultDistDir(), 'acp')),
+            stop: (gen, mode) => acpLauncher.stop('acp', gen, mode),
+            moveOff: (gens) => agents.moveOffOlderKeeperGenerations(undefined, gens),
+            cancelMoves: async (refs) => { for (const sessionRef of refs)
+                await agents.cancelSwitch({ sessionRef }); },
+            retireIdle: () => acp.retireIdleGenerations(),
+            session: (ref) => agents.sessionView(ref),
+        },
+        agentName: (agentId) => bridges.find((bridge) => bridge.type === agentId)?.displayName || agentId,
+        log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+    });
+    terminalKeepers.picker = (current, older) => keeperPolicy.terminalServing(current, older);
+    const stopKeeperPolicy = startExclusivePoll(async () => { if (admission.open && admission.external === 0)
+        await background(() => keeperPolicy.tick()); }, KEEPER_POLICY_TICK_MS);
+    cleanup.push(async () => stopKeeperPolicy());
+    const stopSocketTouch = startExclusivePoll(async () => {
+        await acpLauncher.touchSockets('acp');
+        await terminalLauncher.touchSockets('terminal');
+    }, KEEPER_POLICY_TICK_MS);
+    cleanup.push(async () => stopSocketTouch());
+    if (admission.open && admission.external === 0)
+        void background(() => keeperPolicy.tick());
+    const execPolicy = new ExecPolicy({ generations: terminalKeepers, log: (line) => console.error(`${new Date().toISOString()} ${line}`) });
+    void background(() => execPolicy.recover());
+    const computer = new ComputerChannel({ server: cfg.server, allowInsecureWs, taskRegistry: tasks, desktopEnabled: false,
+        registrationId: registration.id,
+        admission: () => admission.open && admission.external === 0,
+        runExec: (request, onOutput, signal, hooks) => execPolicy.run(request, onOutput, signal, hooks),
+        execs: execPolicy, log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+        tools: (method, params) => { if ((!admission.open || admission.external > 0) && method !== 'tools.info')
+            return Promise.reject(new Error('Registration admission is paused')); return workstationTools.request(method, params); },
+        runFrame: (request, signal) => workstationTools.runFrame(request, signal),
+    });
+    let boundDesktopProvider = deviceServices.desktopProvider;
+    let desktopManagementGeneration;
+    const createDesktop = (provider) => deviceServices.desktopOwnership ? new RegistrationDesktopAdapter({ registrationId: registration.id,
+        owner: deviceServices.desktopOwnership, provider, server: cfg.server, stateDirectory: dir, allowInsecureWs,
+        report: (generation, frame) => management.sendDesktopState(generation, frame) }) : undefined;
+    let remoteDesktop = createDesktop(boundDesktopProvider);
+    if (!admission.open || admission.final)
+        await remoteDesktop?.closeAdmission();
+    if (admission.external)
+        await remoteDesktop?.holdNewAdmission();
+    admission.desktop = remoteDesktop;
+    if (remoteDesktop)
+        cleanup.push(async () => { const original = remoteDesktop; if (original) {
+            await original.closeAdmission();
+            await original.isolateOriginal();
+            original.admission.dispose();
+        } });
+    const management = new ManagementChannel({
+        server: cfg.server, workstationId: cfg.workstationId, workstation: cfg.workstationId, clientKey, serverPub,
+        bridges: () => bridges,
+        workspaces: cfg.workspaces,
+        playgroundCwd,
+        metrics: () => deviceServices.metrics(registration.id),
+        toolchain: () => deviceServices.toolchain(),
+        allowInsecureWs,
+        desktopProvider: {
+            probe: () => admission.open && !admission.final ? remoteDesktop?.provider?.probe() ?? Promise.resolve(null) : Promise.resolve(null),
+            prepare: (selection, binding) => { const provider = remoteDesktop?.provider; if (!provider)
+                throw new Error('unavailable'); return provider.prepare(selection, binding); },
+            recoverDisplay: (binding, reserved) => { const provider = remoteDesktop?.provider; if (!provider)
+                throw new Error('unavailable'); return provider.recoverDisplay(binding, reserved); },
+        },
+        onDesktopCommand: (frame, generation) => remoteDesktop?.dispatch(frame, generation) ?? Promise.resolve(),
+        onAutomationPrepare: (frame, generation) => remoteDesktop?.prepareAutomation(frame, generation) ?? Promise.resolve(),
+        onReady: ready => { desktopManagementGeneration = ready.selectedWire >= 10 ? ready.generation : undefined; if (ready.selectedWire >= 10)
+            remoteDesktop?.ready(ready.generation); return deviceServices.updates.ready({ registrationId: registration.id, managementGeneration: ready.generation, server: registration.server }, ready.release); },
+        onClosed: generation => { if (desktopManagementGeneration === generation)
+            desktopManagementGeneration = undefined; remoteDesktop?.closed(generation); deviceServices.updates.closed({ registrationId: registration.id, managementGeneration: generation, server: registration.server }); },
+        onUpdate: (command, generation) => deviceServices.updates.handle({ registrationId: registration.id, managementGeneration: generation, server: registration.server }, command),
+        requiredRemoteUpdatePolicy: 'drain-only',
+        onExternalAgentsScan: async () => {
+            bridges = await scanRoster();
+            return bridges;
+        },
+        snapshot: async () => ({ channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: await deviceServices.updates.snapshot(registration.id) }),
+        keepers: () => buildKeeperStatuses(keeperPolicy, () => tasks.countedKeeperExecs),
+        onKeeperControl: frame => admission.open && admission.external === 0 ? keeperPolicy.control(frame) : Promise.resolve({ t: 'keeper_control_result', commandId: frame.commandId, kind: frame.kind, action: frame.action, ok: false, affected: [], error: 'Registration admission is paused' }),
+    });
+    const unwatchDesktop = await deviceServices.watchDesktop?.(registration.id, {
+        activity: () => remoteDesktop?.activity() ?? { known: true, consumers: 0 },
+        bind: async (provider) => {
+            if (provider === boundDesktopProvider)
+                return;
+            let next = await replaceDesktopBinding({ original: remoteDesktop, create: () => createDesktop(provider),
+                allowed: () => admission.open && !admission.final && !shutdown.signal.aborted, held: () => admission.external > 0,
+                final: () => admission.final || shutdown.signal.aborted });
+            if (admission.final || shutdown.signal.aborted) {
+                await next?.closeAdmission();
+                await next?.isolateOriginal();
+                next?.admission.dispose();
+                next = undefined;
+            }
+            next?.initializeAdmission(admission.open, admission.external > 0);
+            remoteDesktop = next;
+            boundDesktopProvider = provider;
+            admission.desktop = remoteDesktop;
+            if (desktopManagementGeneration)
+                remoteDesktop?.ready(desktopManagementGeneration);
+            management.refreshDesktopCapabilities();
+        },
+    });
+    if (unwatchDesktop)
+        cleanup.push(async () => unwatchDesktop());
+    const agent = new AgentChannel({ server: cfg.server, agents, bridges: () => bridges, allowInsecureWs, registrationId: registration.id });
+    const unwatchFacts = deviceServices.watchFacts?.(registration.id, event => { void management.receiveDeviceFact(event).catch(() => console.warn('[registration] Device fact refresh failed')); });
+    if (unwatchFacts)
+        cleanup.push(async () => unwatchFacts());
+    void deviceServices.maintainAdapters(async () => {
+        if (admission.external || admission.final)
+            return;
+        await background(() => maintainAdapterBuilds(acp, async () => {
+            bridges = await scanRoster();
+            management.pushRoster(bridges);
+        }));
+    });
+    let rosterPushQueued = false;
+    acp.onRosterChanged(() => {
+        if (admission.final)
+            return;
+        deviceServices.publishToolState?.();
+        if (rosterPushQueued)
+            return;
+        rosterPushQueued = true;
+        void Promise.resolve().then(async () => {
+            rosterPushQueued = false;
+            if (admission.final)
+                return;
+            await background(async () => {
+                bridges = await scanRoster();
+                management.pushRoster(bridges);
+            });
+        }).catch((error) => {
+            console.warn(`[acp-builds] roster push after capability change failed: ${String(error)}`);
+        });
+    });
+    supervisor = new ConnectionSupervisor({
+        management, computer, agent,
+        log: (message) => console.log(`${new Date().toISOString()} ${message}`),
+    });
+    const stopIdleSweep = startIdleSweep(agents);
+    const stopSwitchUpkeep = startExclusivePoll(async () => { if (!admission.final)
+        await background(() => agents.pollSwitches()); }, SWITCH_POLL_INTERVAL_MS);
+    cleanup.push(async () => { stopIdleSweep(); stopSwitchUpkeep(); });
+    const activity = async () => {
+        const active = tasks.snapshot();
+        const keepers = await buildKeeperStatuses(keeperPolicy, () => tasks.countedKeeperExecs);
+        const sum = (key) => keepers?.reduce((total, keeper) => total + (keeper.metrics[key] ?? 0), 0) ?? 0;
+        const files = filesHost.activitySnapshot();
+        const desktop = remoteDesktop?.activity() ?? { known: true, consumers: 0 };
+        return { known: keepers !== null && files.known && desktop.known, commands: Math.max(0, active.activeShellTasks + sum('execRunning') - sum('execCounted')), terminals: sum('ptyOpen'), agents: active.activeAgentTasks + sum('sessions'), transfers: files.transfers, desktopConsumers: desktop.consumers };
+    };
+    if (input.startupHeld) {
+        admission.external += 1;
+        admission.startup = { tasks: tasks.holdExternalAdmission() };
+        await holdDesktopForTargetProbe(admission.desktop);
+    }
+    const loop = supervisor.run(shutdown.signal).catch(error => { if (!shutdown.signal.aborted)
+        console.error('[registration] connection loop failed', registration.id, error instanceof Error ? error.message : 'unknown'); });
+    cleanup.push(async () => { shutdown.abort(); supervisor.stop(); await loop; });
+    return {
+        activity,
+        connection: async () => { const state = supervisor.channelSnapshot().management; return state === 'CONNECTED' ? 'online' : state === 'CONNECTING' ? 'connecting' : state === 'RECONNECTING' ? 'reconnecting' : 'offline'; },
+        pauseAdmission: async () => { admission.open = false; tasks.accepting = false; },
+        resumeAdmission: () => { if (!shutdown.signal.aborted) {
+            admission.open = true;
+            tasks.accepting = true;
+        } },
+        async stop(mode) {
+            admission.open = false;
+            tasks.accepting = false;
+            shutdown.abort();
+            supervisor.stop();
+            await loop;
+            if (mode === 'terminate') {
+                await tasks.stopAll();
+            }
+        },
+    };
+}