@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/tools/terminalRouter.js

@@ -1,188 +1,33 @@
 import { accessSync, constants, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { CREATE_KEYS, PTY_OPERATIONS } from '../keepers/terminal/pty.js';
-import { PTY_SESSION_LIMIT } from '../keepers/terminal/protocol.js';
-import { TERMINAL_NOT_FOUND } from '../keepers/legacy.js';
-import { identifier, integer, keys } from './validation.js';
-const LEGACY = 'legacy';
-/** The single-keeper form of {@link KitGenerations}: one generation named `kit`, running when it answers a hello. */
-function singleKit(kit) {
-    return {
-        servingGeneration: async () => ({ gen: 'kit', client: kit }),
-        running: async () => [{ gen: 'kit', client: kit }],
-    };
-}
+import { validateRequest } from './validation.js';
 export class TerminalRouter {
     deps;
-    owners = new Map();
-    kits;
-    /** Clients of the generations seen in the last listing, by generation. */
-    clients = new Map();
     constructor(deps) {
         this.deps = deps;
-        if (!deps.kits && !deps.kit)
-            throw new Error('TerminalRouter needs keeper-terminal');
-        this.kits = deps.kits ?? singleKit(deps.kit);
     }
-    /** The current owner map (tests and diagnostics): `legacy`, or a generation (`kit` with a single keeper-terminal). */
-    ownerOf(id) { return this.owners.get(id); }
     async request(method, params) {
-        const op = method.startsWith('terminal.') ? method.slice('terminal.'.length) : '';
-        if (op === 'list') {
-            keys(params, []);
-            return { sessions: await this.list() };
+        validateRequest(method, params);
+        const op = method.slice('terminal.'.length);
+        const kit = this.deps.kit;
+        if (op === 'list')
+            return { ...await this.list() };
+        if (op === 'create') {
+            const existing = (await this.list()).sessions.find(session => session.id === params.id);
+            if (existing)
+                return { ...existing };
+            const launch = await this.deps.launch(params.cwd);
+            return { ...await kit.create({ id: params.id, ...launch }) };
         }
-        if (op === 'create')
-            return { ...await this.create(params) };
-        if (!PTY_OPERATIONS.has(op))
+        if (!['attach', 'poll', 'resize', 'input', 'scroll', 'detach', 'close'].includes(op))
             throw new Error('Unsupported workstation tool');
-        const id = identifier(params, 'id');
-        const owner = await this.resolveOwner(id);
-        if (!owner)
-            throw new Error(TERMINAL_NOT_FOUND);
-        const kit = owner === LEGACY ? undefined : this.clients.get(owner);
-        if (owner !== LEGACY && !kit)
-            throw new Error(TERMINAL_NOT_FOUND);
-        try {
-            const result = owner === LEGACY
-                ? await this.deps.legacy.request(method, params)
-                : { ...await kit[op].call(kit, params) };
-            if (op === 'close')
-                this.owners.delete(id);
-            return result;
-        }
-        catch (error) {
-            // The owner no longer has it (closed elsewhere, keeper restarted): forget it; the next request looks it up again.
-            if (error instanceof Error && error.message === TERMINAL_NOT_FOUND)
-                this.owners.delete(id);
-            throw error;
-        }
+        const call = kit[op];
+        return { ...await call.call(kit, params) };
     }
     async list() {
-        const { legacy, kits } = await this.refresh();
-        const seen = new Set((legacy ?? []).map((session) => session.id));
-        const out = [...(legacy ?? [])];
-        for (const sessions of kits.values())
-            for (const session of sessions ?? [])
-                if (!seen.has(session.id)) {
-                    seen.add(session.id);
-                    out.push(session);
-                }
-        return out;
-    }
-    /** Lists every side once (keeper-terminal generations only if running) and refreshes the owners of every side that answered. */
-    async refresh() {
-        const [legacy, kits] = await Promise.all([this.legacySessions(), this.kitRefresh()]);
-        if (legacy)
-            this.replaceOwners(LEGACY, legacy);
-        else if (!this.deps.legacy?.live)
-            this.replaceOwners(LEGACY, []);
-        return { legacy, kits };
-    }
-    /**
-     * Lists every running keeper-terminal generation (never starts one) and refreshes their owners: a generation that answered gets
-     * exactly its sessions; one that did not answer keeps its owners; one that is no longer running loses them (its PTYs are gone).
-     */
-    async kitRefresh() {
-        const listed = new Map();
-        let running;
-        try {
-            running = await this.kits.running();
-        }
-        catch {
-            return listed;
-        }
-        await Promise.all(running.map(async ({ gen, client }) => {
-            this.clients.set(gen, client);
-            listed.set(gen, await this.sessionsOf(client));
-        }));
-        for (const [gen, sessions] of listed)
-            if (sessions)
-                this.replaceOwners(gen, sessions);
-        for (const [id, owner] of [...this.owners])
-            if (owner !== LEGACY && !listed.has(owner))
-                this.owners.delete(id);
-        for (const gen of [...this.clients.keys()])
-            if (!listed.has(gen))
-                this.clients.delete(gen);
-        return listed;
-    }
-    replaceOwners(side, sessions) {
-        for (const [id, owner] of this.owners)
-            if (owner === side)
-                this.owners.delete(id);
-        for (const session of sessions)
-            if (side === LEGACY || !this.owners.has(session.id))
-                this.owners.set(session.id, side);
-    }
-    /** The legacy keeper's sessions; `sessions()` probes it first (read-only), so a daemon that just started finds it too. */
-    async legacySessions() {
-        return this.deps.legacy ? this.deps.legacy.sessions() : null;
-    }
-    /** One generation's sessions if it is already running; null when it is not (or did not answer): nothing is started here. */
-    async sessionsOf(client) {
-        try {
-            if (!await client.runningHello())
-                return null;
-            return (await client.list()).sessions;
-        }
-        catch {
-            return null;
-        }
-    }
-    async resolveOwner(id) {
-        const known = this.owners.get(id);
-        if ((known !== undefined && known !== LEGACY && this.clients.has(known)) || (known === LEGACY && this.deps.legacy?.live))
-            return known;
-        await this.refresh();
-        return this.owners.get(id);
-    }
-    async create(params) {
-        // The legacy keeper's checks, wording and order (tools/terminal.ts at the merge-base: id, clientId, keys, cols, rows, name,
-        // then existing, limit, cwd), all before the cwd is resolved.
-        const id = identifier(params, 'id');
-        identifier(params, 'clientId');
-        keys(params, [...CREATE_KEYS]);
-        integer(params, 'cols', 20, 300, 100);
-        integer(params, 'rows', 5, 100, 30);
-        const name = params.name;
-        if (name !== undefined && (typeof name !== 'string' || !name.length || name.length > 128 || /[\x00-\x1f]/.test(name)))
-            throw new Error('Invalid terminal name');
-        const legacy = this.deps.legacy;
-        const knownOwner = this.owners.get(id);
-        if (legacy && (knownOwner === undefined || knownOwner === LEGACY)) {
-            // The legacy keeper never gains a session after the upgrade (creates go to keeper-terminal), so the ids of its first
-            // successful list answer "is this a retry of one of its sessions?" for good — even while it is busy or hung.
-            if (legacy.knownIds === null) {
-                const sessions = await legacy.sessions(); // bounded; null at once when it is busy or absent
-                if (sessions)
-                    this.replaceOwners(LEGACY, sessions);
-            }
-            if (legacy.live && legacy.knownIds?.has(id))
-                return legacy.request('terminal.create', params);
-        }
-        // Duplicate and limit first (the legacy order), against the keeper-terminal generations already running: an idempotent create
-        // (in whichever generation has the id) costs no files-host round trip. keeper-terminal re-checks both when it really creates.
-        const listed = await this.kitRefresh();
-        for (const [gen, sessions] of listed) {
-            const existing = sessions?.find((session) => session.id === id);
-            if (existing) {
-                this.owners.set(id, gen);
-                return existing;
-            }
-        }
-        const serving = await this.kits.servingGeneration();
-        const running = listed.get(serving.gen);
-        if (running && running.length >= PTY_SESSION_LIMIT)
-            throw new Error('Terminal session limit exceeded');
-        if (params.cwd !== undefined && typeof params.cwd !== 'string')
-            throw new Error('Invalid cwd');
-        const launch = await this.deps.launch(params.cwd);
-        const created = await serving.client.create({ ...params, ...launch });
-        this.clients.set(serving.gen, serving.client);
-        this.owners.set(id, serving.gen);
-        return created;
+        // The typed client is non-launching and distinguishes proven absence from an unreachable owner.
+        return this.deps.kit.list();
     }
 }
 /**

package/dist/workstation/tools/validation.js

@@ -5,7 +5,7 @@ export const CHUNK_BYTES = 64 * 1024;
 export const TOOL_METHODS = new Set([
     'browser.list', 'browser.create', 'browser.attach', 'browser.frame', 'browser.navigate', 'browser.input', 'browser.takeover', 'browser.detach', 'browser.close',
     'tools.info', 'terminal.list', 'terminal.create', 'terminal.attach', 'terminal.poll',
-    'terminal.write', 'terminal.resize', 'terminal.takeover', 'terminal.detach', 'terminal.close',
+    'terminal.input', 'terminal.resize', 'terminal.scroll', 'terminal.detach', 'terminal.close',
     'files.media.prepare', 'files.media.read', 'files.media.cancel',
     'files.media.open', 'files.media.status', 'files.media.seek', 'files.media.interest', 'files.media.object', 'files.media.release',
     'files.list', 'files.find', 'files.read', 'files.mkdir', 'files.rename', 'files.delete',
@@ -49,6 +49,8 @@ export function validateRequest(method, params) {
         throw new Error('Unsupported workstation tool');
     if (!object(params) || Buffer.byteLength(JSON.stringify(params)) > TOOL_REQUEST_BYTES)
         throw new Error('Invalid or oversized tool parameters');
+    if (method.startsWith('terminal.'))
+        validateTerminal(method, params);
     const shape = MEDIA_SHAPES[method];
     if (shape) {
         keys(params, [...shape, 'readOnly', 'filesystem']);
@@ -84,3 +86,55 @@ const MEDIA_SHAPES = {
     'files.media.object': ['path', 'version', 'consumerId', 'objectId', 'offset', 'length'],
     'files.media.release': ['path', 'version', 'consumerId'],
 };
+/** Native terminal kinds have exact flat shapes. Geometry freshness is checked against the keeper's live grid. */
+function validateTerminal(method, params) {
+    const ref = ['id', 'incarnation', 'clientId'];
+    const kinds = { key: ['usage', 'down', 'modifiers'], text: ['text'], paste: ['text'], pointer: ['x', 'y', 'geometry', 'modifiers'], button: ['x', 'y', 'geometry', 'button', 'down', 'modifiers'], release: [] };
+    const shapes = {
+        list: [], create: ['id', 'cwd'], attach: [...ref, 'cols', 'rows'], poll: [...ref, 'after'], resize: [...ref, 'cols', 'rows'],
+        scroll: [...ref, 'lines', 'x', 'y', 'modifiers', 'geometry'], detach: ref, close: ['id', 'incarnation'],
+    };
+    const op = method.slice('terminal.'.length);
+    let shape = shapes[op];
+    if (op === 'input') {
+        if (typeof params.kind !== 'string' || !Object.hasOwn(kinds, params.kind))
+            throw new Error('Invalid kind');
+        shape = [...ref, 'kind', ...kinds[params.kind]];
+    }
+    if (!shape)
+        throw new Error('Unsupported workstation tool');
+    keys(params, shape);
+    for (const name of shape) {
+        if (name === 'cwd') {
+            if (params.cwd !== undefined)
+                string(params, name);
+            continue;
+        }
+        if (!(name in params))
+            throw new Error(`Missing ${name}`);
+        if (['id', 'incarnation', 'clientId'].includes(name))
+            identifier(params, name);
+        else if (name === 'cols')
+            integer(params, name, 20, 300);
+        else if (name === 'rows')
+            integer(params, name, 5, 100);
+        else if (name === 'after' || name === 'geometry')
+            integer(params, name, name === 'geometry' ? 1 : 0, Number.MAX_SAFE_INTEGER);
+        else if (name === 'x')
+            integer(params, name, 0, 299);
+        else if (name === 'y')
+            integer(params, name, 0, 99);
+        else if (name === 'lines')
+            integer(params, name, -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+        else if (name === 'usage')
+            integer(params, name, 0, 65535);
+        else if (name === 'button')
+            integer(params, name, 0, 2);
+        else if (name === 'modifiers')
+            integer(params, name, 0, 15);
+        else if (name === 'down' && typeof params[name] !== 'boolean')
+            throw new Error('Invalid down');
+        else if (name === 'text' && (typeof params.text !== 'string' || Buffer.byteLength(params.text) > 65536))
+            throw new Error('Invalid text');
+    }
+}

package/dist/workstation/update/archiveEvidence.js

@@ -0,0 +1,206 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { z } from 'zod';
+export const rootReaderSchema = z.object({ schemaVersion: z.literal(1), rootFormat: z.literal(2), legacySourceMapping: z.literal(true), coverageEvidence: z.boolean().optional() }).strict();
+export const archiveEvidenceSchema = z.object({
+    name: z.literal('@platless/axom-cli'), version: z.string().min(1).max(128), size: z.number().int().positive().max(536_870_912), sha512: z.string().regex(/^[a-f0-9]{128}$/), reader: rootReaderSchema,
+    runtimeFiles: z.array(z.object({ path: z.string().min(1).max(4096).refine(value => (value === 'package.json' || value.startsWith('dist/')) && !/[^\x20-\x7e]|\\/.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..')), size: z.number().int().min(0).max(134_217_728), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict()).min(2).max(65_536),
+}).strict().refine(value => value.runtimeFiles.some(file => file.path === 'package.json') && value.runtimeFiles.some(file => file.path === 'dist/cli.js') && new Set(value.runtimeFiles.map(file => file.path.toLowerCase())).size === value.runtimeFiles.length);
+const archiveLimit = 536_870_912;
+const expandedLimit = 1_073_741_824;
+const memberLimit = 134_217_728;
+const metadataLimit = 1_048_576;
+const memberCountLimit = 65_536;
+const recovery = 'Compatible root-format-2 reader recovery required; preserve the archive and update evidence and install an explicitly compatible CLI';
+function invalid() { throw new Error(recovery); }
+function stringField(header, start, length) {
+    const field = header.subarray(start, start + length);
+    const end = field.indexOf(0);
+    const bytes = end < 0 ? field : field.subarray(0, end);
+    const value = bytes.toString('utf8');
+    if (!Buffer.from(value).equals(bytes))
+        invalid();
+    return value;
+}
+function octal(header, start, length) {
+    const value = stringField(header, start, length).trim();
+    if (!/^[0-7]+$/.test(value))
+        invalid();
+    const parsed = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        invalid();
+    return parsed;
+}
+function canonical(value, directory) {
+    if (directory && value.endsWith('/'))
+        value = value.slice(0, -1);
+    if (!value || value.length > 4096 || /[^\x20-\x7e]|\\/.test(value) || !value.startsWith('package/') && value !== 'package')
+        invalid();
+    if (value.split('/').length > 64 || value.split('/').some(part => !part || part === '.' || part === '..'))
+        invalid();
+    return value;
+}
+function paxFields(content) {
+    const fields = new Map();
+    let offset = 0;
+    while (offset < content.length) {
+        const space = content.indexOf(32, offset);
+        if (space < offset || space - offset > 10)
+            invalid();
+        const declared = content.subarray(offset, space).toString('ascii');
+        if (!/^[1-9][0-9]*$/.test(declared))
+            invalid();
+        const length = Number(declared);
+        if (!Number.isSafeInteger(length) || length <= space - offset + 2 || offset + length > content.length || content[offset + length - 1] !== 10)
+            invalid();
+        const field = content.subarray(space + 1, offset + length - 1);
+        const equals = field.indexOf(61);
+        if (equals < 1)
+            invalid();
+        const key = field.subarray(0, equals).toString('utf8');
+        const valueBytes = field.subarray(equals + 1);
+        const value = valueBytes.toString('utf8');
+        if (!Buffer.from(value).equals(valueBytes) || fields.has(key) || !['path', 'size', 'mtime', 'atime', 'ctime', 'uid', 'gid', 'uname', 'gname', 'SCHILY.dev', 'SCHILY.ino', 'SCHILY.nlink'].includes(key))
+            invalid();
+        fields.set(key, value);
+        offset += length;
+    }
+    return fields;
+}
+function decimal(value) {
+    if (!/^(0|[1-9][0-9]*)$/.test(value))
+        invalid();
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        invalid();
+    return parsed;
+}
+export async function readArchiveEvidence(archive) {
+    const handle = await fs.open(archive, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    let bytes;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size < 1 || stat.size > archiveLimit)
+            invalid();
+        bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (bytes.length !== stat.size || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs)
+            invalid();
+    }
+    finally {
+        await handle.close();
+    }
+    let tar;
+    try {
+        tar = gunzipSync(bytes, { maxOutputLength: expandedLimit });
+    }
+    catch {
+        invalid();
+    }
+    if (tar.length % 512)
+        invalid();
+    const seen = new Set();
+    const files = new Set();
+    const directories = new Set();
+    const spellings = new Map();
+    const runtimeFiles = [];
+    let metadata;
+    let pending;
+    let longName;
+    let offset = 0;
+    let ended = false;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every(value => value === 0)) {
+            if (pending || longName || offset + 1024 > tar.length || !tar.subarray(offset).every(value => value === 0))
+                invalid();
+            ended = true;
+            break;
+        }
+        let checksum = 0;
+        for (let index = 0; index < 512; index += 1)
+            checksum += index >= 148 && index < 156 ? 32 : header[index];
+        if (checksum !== octal(header, 148, 8))
+            invalid();
+        if (!['ustar', 'ustar '].includes(stringField(header, 257, 6)))
+            invalid();
+        const type = stringField(header, 156, 1);
+        if (!['', '0', '5', 'x', 'L'].includes(type))
+            invalid();
+        const rawSize = octal(header, 124, 12);
+        const contentSize = type === 'x' || type === 'L' ? rawSize : pending?.has('size') ? decimal(pending.get('size')) : rawSize;
+        if (contentSize > memberLimit || (type === 'x' || type === 'L') && contentSize > metadataLimit)
+            invalid();
+        const start = offset + 512;
+        const end = start + contentSize;
+        if (end > tar.length)
+            invalid();
+        const content = tar.subarray(start, end);
+        offset = start + Math.ceil(contentSize / 512) * 512;
+        if (type === 'x') {
+            if (pending || longName)
+                invalid();
+            pending = paxFields(content);
+            continue;
+        }
+        if (type === 'L') {
+            if (pending || longName || !content.length || content[content.length - 1] !== 0)
+                invalid();
+            longName = stringField(content, 0, content.length);
+            continue;
+        }
+        const prefix = stringField(header, 345, 155);
+        const name = canonical(pending?.get('path') ?? longName ?? `${prefix ? prefix + '/' : ''}${stringField(header, 0, 100)}`, type === '5');
+        pending = undefined;
+        longName = undefined;
+        if (seen.has(name) || seen.size >= memberCountLimit || type === '5' && contentSize !== 0 || name === 'package' && type !== '5')
+            invalid();
+        const parts = name.split('/');
+        for (let index = 1; index <= parts.length; index += 1) {
+            const prefixName = parts.slice(0, index).join('/');
+            const alias = prefixName.toLowerCase();
+            const previous = spellings.get(alias);
+            if (previous && previous !== prefixName || index < parts.length && files.has(alias))
+                invalid();
+            spellings.set(alias, prefixName);
+            if (index < parts.length)
+                directories.add(alias);
+        }
+        const alias = name.toLowerCase();
+        if (type === '5') {
+            if (files.has(alias))
+                invalid();
+            directories.add(alias);
+        }
+        else {
+            if (directories.has(alias))
+                invalid();
+            files.add(alias);
+        }
+        seen.add(name);
+        if (type === '5')
+            continue;
+        if (name === 'package/package.json') {
+            if (contentSize > metadataLimit)
+                invalid();
+            try {
+                metadata = JSON.parse(content.toString('utf8'));
+            }
+            catch {
+                invalid();
+            }
+        }
+        if (name === 'package/package.json' || name.startsWith('package/dist/'))
+            runtimeFiles.push({ path: name.slice(8), size: contentSize, sha256: createHash('sha256').update(content).digest('hex') });
+    }
+    if (!ended || typeof metadata !== 'object' || !metadata || Array.isArray(metadata))
+        invalid();
+    const value = metadata;
+    const reader = rootReaderSchema.safeParse(value.axomWorkstationRootReader);
+    if (value.name !== '@platless/axom-cli' || typeof value.version !== 'string' || !value.version || value.version.length > 128 || !reader.success)
+        invalid();
+    if (!value.bin || typeof value.bin !== 'object' || Array.isArray(value.bin) || value.bin.axom !== 'dist/cli.js' || !runtimeFiles.some(entry => entry.path === 'dist/cli.js'))
+        invalid();
+    return { name: value.name, version: value.version, size: bytes.length, sha512: createHash('sha512').update(bytes).digest('hex'), reader: reader.data, runtimeFiles: runtimeFiles.sort((left, right) => left.path.localeCompare(right.path)) };
+}

package/dist/workstation/update/artifact.js

@@ -1,3 +1,4 @@
+import { deploymentDownloadURL } from '../control/serverIdentity.js';
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { createWriteStream, promises as fs } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -16,7 +17,7 @@ function safeRelease(release, server) {
     if ((configured.protocol !== 'http:' && configured.protocol !== 'https:') || configured.username || configured.password) {
         throw new Error('Configured server URL must be an HTTP(S) origin without credentials');
     }
-    const url = new URL(release.url, configured);
+    const url = new URL(deploymentDownloadURL(server, release.url));
     // The release descriptor arrives over the authenticated management connection, but keeping the
     // download on that exact origin prevents an injected relative/absolute URL from turning the
     // client into a credentialed downloader. HTTP remains supported for private-network development

package/dist/workstation/update/coordinator.js

@@ -22,6 +22,11 @@ export class UpdateCoordinator {
     constructor(options) {
         this.options = options;
     }
+    legacyTasks() {
+        if (this.options.deviceAdmission || !this.options.tasks)
+            throw new Error('Legacy task admission is not available for a device update');
+        return this.options.tasks;
+    }
     snapshot() { return { ...this.status }; }
     async snapshotAsync() { await this.ensureInitialized(); return this.snapshot(); }
     async handle(command) {
@@ -70,6 +75,8 @@ export class UpdateCoordinator {
      */
     async managementReady(release, generation) {
         await this.ensureInitialized();
+        if (this.options.deviceAdmission)
+            return;
         const readiness = this.options.readiness;
         if (!release)
             return;
@@ -149,6 +156,7 @@ export class UpdateCoordinator {
     async transition(status) {
         this.status = status;
         await this.options.state.save(status);
+        await this.options.persistDevicePhase?.(status);
         // After the persist, and swallowed: a logger is a witness to the update, never a participant
         // that can fail one.
         try {
@@ -167,16 +175,23 @@ export class UpdateCoordinator {
         try {
             await this.transition(this.base(command, 'REQUESTED'));
             let drained = null;
-            if (command.force) {
-                await this.options.tasks.stopAll();
+            if (this.options.deviceAdmission) {
+                if (command.force)
+                    throw new Error('Destructive all-device force requires a separately confirmed local action');
+                await this.transition(this.base(command, 'DRAINING'));
+                if (!await this.options.deviceAdmission.observe())
+                    return this.transition(this.base(command, 'BUSY'));
+            }
+            else if (command.force) {
+                await this.legacyTasks().stopAll();
             }
             else {
                 // Close admission before the persisted transition can yield: no command may enter in the
                 // gap between announcing DRAINING and establishing the barrier it promises.
-                this.options.tasks.accepting = false;
+                this.legacyTasks().accepting = false;
                 await this.transition(this.base(command, 'DRAINING'));
                 drainCancellation = new AbortController();
-                drained = this.options.tasks.waitForIdle(this.options.drainTimeoutMs ?? DEFAULT_UPDATE_DRAIN_TIMEOUT_MS, drainCancellation.signal);
+                drained = this.legacyTasks().waitForIdle(this.options.drainTimeoutMs ?? DEFAULT_UPDATE_DRAIN_TIMEOUT_MS, drainCancellation.signal);
             }
             await this.transition(this.base(command, 'DOWNLOADING'));
             if (this.options.downloader)
@@ -187,10 +202,13 @@ export class UpdateCoordinator {
                 artifact = await downloadVerified(command.release, this.options.artifact);
             }
             await this.transition(this.base(command, 'VERIFYING'));
+            await this.options.verifyArtifact?.(artifact, command);
             if (drained && !await drained) {
-                this.options.tasks.accepting = true;
-                return this.transition({ ...this.base(command, 'BUSY'), ...this.options.tasks.snapshot() });
+                this.legacyTasks().accepting = true;
+                return this.transition({ ...this.base(command, 'BUSY'), ...this.legacyTasks().snapshot() });
             }
+            if (this.options.deviceAdmission && !await this.options.deviceAdmission.observe())
+                return this.transition(this.base(command, 'BUSY'));
             // This is intentionally after a verified new archive exists but before npm mutates the
             // installed package. A missing/invalid last-known-good archive must leave the client alone.
             rollback = await this.options.rollback?.prepare(command) ?? null;
@@ -214,6 +232,8 @@ export class UpdateCoordinator {
             // the successor loading INSTALLING and heartbeating a non-terminal phase forever, which the
             // server never resolves and which blocks every later update command.
             const restarting = await this.transition(this.base(command, 'RESTARTING'));
+            if (this.options.deviceAdmission && this.options.restart)
+                await this.options.deviceAdmission.handoff();
             // Deliberately not inside the try/catch that restores the package: a service definition we
             // failed to rewrite does not make the installed package wrong, and rolling npm back over a
             // provisioning failure would be a much bigger hammer than the problem.
@@ -228,8 +248,8 @@ export class UpdateCoordinator {
             }
             catch (provisionError) {
                 this.options.onProvisionFailure?.(provisionError);
-                if (!command.force)
-                    this.options.tasks.accepting = true;
+                if (!command.force && !this.options.deviceAdmission)
+                    this.legacyTasks().accepting = true;
                 return this.transition({ ...this.base(command, 'FAILED'), error: failure(provisionError) });
             }
             if (!this.options.restart) {
@@ -249,19 +269,20 @@ export class UpdateCoordinator {
                 // SUCCEEDED is the honest phase: the install did succeed. What has not happened is the
                 // restart, which the caller is the one positioned to say — `axom update` prints it, and
                 // the server-driven case sees the new version only after the operator restarts.
-                if (!command.force)
-                    this.options.tasks.accepting = true;
+                if (!command.force && !this.options.deviceAdmission)
+                    this.legacyTasks().accepting = true;
                 return this.transition(this.base(command, 'SUCCEEDED'));
             }
             // Keeper-hosted agent sessions outlive this process: detach them first (head checkpoint, adapter untouched — no
             // `session/cancel`, no failed turn), so the next daemon adopts them where they are (spec §5.5.5).
-            await this.options.tasks.detachDurableSessions();
+            if (!this.options.deviceAdmission)
+                await this.legacyTasks().detachDurableSessions();
             await this.options.restart();
             return restarting;
         }
         catch (error) {
-            if (!command.force)
-                this.options.tasks.accepting = true;
+            if (!command.force && !this.options.deviceAdmission)
+                this.legacyTasks().accepting = true;
             return this.transition({ ...this.base(command, 'FAILED'), error: failure(error) });
         }
         finally {