@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/channels/management.js

@@ -1,15 +1,22 @@
 import { deriveSessionKey, randomBytes } from '../crypto.js';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { CLIENT_PACKAGE_NAME, CLIENT_VERSION } from '../version.js';
-import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
-import { bridgesForWire } from '../protocol/common.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, ManagementFrameAdmission, } from '../protocol/management.js';
+import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
 import { osInfo } from '../osinfo.js';
 import { workstationChannelUrl } from './url.js';
+import { DesktopCapabilityReporter } from '../desktopControl/capabilities.js';
 const protocols = {
     MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION },
-    COMPUTER: { min: 1, max: 4 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
+    // COMPUTER v5: durable exec frames (exec_started/attach/status/ack, offsets on exec_output; spec §4.3).
+    // COMPUTER v6: this client refuses credential storage to the agent file tools (files/credentials.ts); the server sends
+    // file frames only to v6 clients.
+    COMPUTER: { min: 1, max: 6 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
 };
+function toolchainField(toolchain) {
+    return toolchain ? { toolchain: { python: toolchain.python, node: toolchain.node } } : {};
+}
 /** Exported so tests can assert the wire frame's `clientPackage` without opening a socket. */
 export function buildHelloFrame(options, clientNonce) {
     return {
@@ -24,7 +31,7 @@ export function buildHelloFrame(options, clientNonce) {
  */
 function helloBridges(bridges) {
     const roster = bridges?.();
-    return roster === undefined ? undefined : bridgesForWire(roster, 'management_hello');
+    return roster === undefined ? undefined : bridgesForWire(helloRoster(roster), 'management_hello');
 }
 /** Exported so the roster this answer carries can be asserted without driving a whole channel. */
 export function buildScanResultFrame(commandId, bridges) {
@@ -57,6 +64,10 @@ export function metricsForManagementWire(metrics, serverManagementWire) {
     if (!metrics)
         return metrics;
     const selectedWire = serverManagementWire ?? 0;
+    if (selectedWire < MANAGEMENT_WIRE_GPU_VERSION && metrics.gpus !== undefined) {
+        const { gpus: _gpus, ...withoutGpus } = metrics;
+        return metricsForManagementWire(withoutGpus, selectedWire);
+    }
     if (selectedWire >= MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION) {
         const { cpuLoadNormalized: _cpuLoadNormalized, ...rawLoad } = metrics;
         return rawLoad;
@@ -98,6 +109,51 @@ export function dispatchUpdateCommand(channel, command, onUpdate, serverManageme
     })
         .catch(() => { });
 }
+/**
+ * The most a heartbeat waits for its `keepers` sample. The channel builds the next heartbeat only after this one went out, so a sample
+ * that hangs (a wedged `ps`, a stuck file read) must never hold the frame: past this it goes out with `keepers: null`.
+ */
+export const KEEPERS_SAMPLE_CAP_MS = 1500;
+/**
+ * Heartbeat `keepers` for the negotiated wire: absent below 8 (an older server does not know the field), the sampled list from 8 on,
+ * `null` when sampling failed or did not answer within `capMs`. Never rejects, never waits longer than `capMs`. Exported for tests.
+ */
+export async function keepersForManagementWire(sample, serverManagementWire, capMs = KEEPERS_SAMPLE_CAP_MS) {
+    if (!sample || (serverManagementWire ?? 0) < MANAGEMENT_WIRE_KEEPERS_VERSION)
+        return {};
+    let timer;
+    const capped = new Promise((resolve) => { timer = setTimeout(() => resolve(null), capMs); timer.unref?.(); });
+    try {
+        const sampled = Promise.resolve().then(sample);
+        sampled.catch(() => undefined); // a late rejection after the cap must not be unhandled
+        return { keepers: await Promise.race([sampled, capped]) };
+    }
+    catch {
+        return { keepers: null };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs one `keeper_control` and sends its result if the channel is still open. Detached from the frame loop (a replace-now stops
+ * keeper processes, which takes seconds). Exported for tests.
+ */
+export function dispatchKeeperControl(channel, frame, onKeeperControl) {
+    return onKeeperControl(frame)
+        .catch((error) => ({
+        t: 'keeper_control_result', commandId: frame.commandId, kind: frame.kind, action: frame.action, ok: false, affected: [],
+        error: error instanceof Error ? error.message : String(error),
+    }))
+        .then((result) => {
+        if (channel.state !== 'OPEN')
+            return;
+        try {
+            channel.send(result);
+        }
+        catch { /* the channel closed meanwhile; the server asks again with the same commandId */ }
+    });
+}
 /**
  * The server nonce to derive this session's key from.
  *
@@ -125,18 +181,65 @@ export class ManagementChannel {
     options;
     /** Undefined until this connection receives management_ready; reset for every reconnect. */
     serverManagementWire;
+    /** The open channel of the current connection, for frames this client sends unprompted ({@link pushRoster}). */
+    channel;
+    desktopReporter;
+    connectionAttempt = 0;
+    generation;
     constructor(options) {
         this.options = options;
     }
+    refreshDesktopCapabilities(generation) {
+        if (generation === undefined || generation === this.generation)
+            this.desktopReporter?.refresh();
+    }
+    /** T10 reports only on its authenticated current management socket. */
+    sendDesktopState(generation, frame) {
+        if (generation !== this.generation || (this.serverManagementWire ?? 0) < 9 || this.channel?.state !== 'OPEN')
+            return false;
+        try {
+            this.channel.send(frame);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Tell the server about a roster that changed without a scan asking (adapter builds moved by Axom,
+     * spec §6.1): the same `external_agents_scan_result` frame a scan answers with, under a client-made
+     * command id no scan is waiting on — the server records the roster and completes nothing. `false`
+     * when there is no open connection; the next `management_hello` carries {@link ManagementChannelOptions.bridges} then.
+     */
+    pushRoster(bridges) {
+        const channel = this.channel;
+        if (!channel || channel.state !== 'OPEN')
+            return false;
+        try {
+            channel.send(buildScanResultFrame(`roster-push-${randomBytes(8).toString('hex')}`, bridges));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async connect(signal) {
+        const attempt = ++this.connectionAttempt;
+        this.desktopReporter?.dispose();
+        this.desktopReporter = undefined;
+        this.generation = undefined;
+        this.channel = undefined;
         this.serverManagementWire = undefined;
         const nonce = randomBytes(16);
         let initialHeartbeat = true;
+        const admission = new ManagementFrameAdmission(() => attempt === this.connectionAttempt && !signal?.aborted);
         const channel = await connectEncryptedChannel({
             url: workstationChannelUrl(this.options.server, 'management', this.options.allowInsecureWs),
             signal,
             encode: encodeManagementFrame,
             decode: decodeManagementFrame,
+            decodeBytes: decodeManagementFrame,
+            admitFrame: frame => admission.admit(frame),
             heartbeat: (seq, sentAtEpochMs) => this.heartbeat(seq, sentAtEpochMs),
             initialFrame: () => {
                 initialHeartbeat = false;
@@ -156,10 +259,39 @@ export class ManagementChannel {
         if (initialHeartbeat)
             throw new Error('Management proof heartbeat was not sent');
         const ready = await this.nextReady(channel);
+        if (attempt !== this.connectionAttempt || channel.state !== 'OPEN') {
+            channel.close();
+            throw new Error('Management connection superseded');
+        }
         this.serverManagementWire = ready.protocols.MANAGEMENT;
+        this.generation = ready.generation;
+        this.channel = channel;
+        const reporter = new DesktopCapabilityReporter({ selectedWire: this.serverManagementWire, generation: ready.generation,
+            provider: this.options.desktopProvider, send: report => {
+                if (attempt === this.connectionAttempt && this.channel === channel && channel.state === 'OPEN')
+                    channel.send({ t: 'workstation_capabilities', ...report });
+            } });
+        this.desktopReporter = reporter;
+        // Starts before the existing awaited update hook; heartbeat and reporting never await discovery.
+        reporter.refresh();
+        const retire = () => {
+            admission.dispose();
+            reporter.dispose();
+            try {
+                this.options.onClosed?.(ready.generation);
+            }
+            catch { /* transport retirement must complete */ }
+            if (this.channel === channel) {
+                this.channel = undefined;
+                this.generation = undefined;
+                this.desktopReporter = undefined;
+                this.serverManagementWire = undefined;
+            }
+        };
+        void channel.closed.then(retire, retire);
         // A readiness record is evidence from this encrypted, proof-of-key management generation — it
         // is never driven by the local browser/device-authorization flow.
-        await this.options.onReady?.({ generation: ready.generation, release: ready.release });
+        await this.options.onReady?.({ generation: ready.generation, selectedWire: ready.protocols.MANAGEMENT, release: ready.release });
         const pending = new Map();
         void this.routeMessages(channel, pending);
         return {
@@ -181,9 +313,15 @@ export class ManagementChannel {
         };
     }
     async heartbeat(seq, sentAtEpochMs) {
+        const selectedWire = this.serverManagementWire;
+        // Availability may change without restarting the CLI (Desktop sharing is process-owned).
+        // Discovery stays bounded and never delays the heartbeat or creates a capture session.
+        this.desktopReporter?.refresh();
+        const revision = this.desktopReporter?.revision;
         const snapshot = await this.options.snapshot();
         return {
             t: 'heartbeat', seq, sentAtEpochMs, clientVersion: CLIENT_VERSION,
+            ...(this.options.playgroundCwd ? { playgroundCwd: this.options.playgroundCwd } : {}),
             channels: {
                 MANAGEMENT: snapshot.channels.management,
                 COMPUTER: snapshot.channels.computer,
@@ -191,10 +329,13 @@ export class ManagementChannel {
             },
             activeShellTasks: snapshot.activeShellTasks, activeAgentTasks: snapshot.activeAgentTasks,
             protocols, os: osInfo(),
-            ...(this.options.metrics && (this.serverManagementWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
-                ? { metrics: metricsForManagementWire(this.options.metrics(), this.serverManagementWire) }
+            ...toolchainField(this.options.toolchain?.() ?? null),
+            ...(this.options.metrics && (selectedWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
+                ? { metrics: metricsForManagementWire(this.options.metrics(), selectedWire) }
                 : {}),
-            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, this.serverManagementWire) } : {}),
+            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, selectedWire) } : {}),
+            ...await keepersForManagementWire(this.options.keepers, selectedWire, this.options.keepersCapMs),
+            ...((selectedWire ?? 0) >= 9 && revision !== undefined ? { capabilitiesRevision: revision } : {}),
         };
     }
     async nextReady(channel) {
@@ -206,6 +347,25 @@ export class ManagementChannel {
     async routeMessages(channel, pending) {
         try {
             for await (const frame of channel.messages) {
+                if (channel !== this.channel)
+                    break;
+                if (frame.t === 'workstation_capabilities_request') {
+                    if ((this.serverManagementWire ?? 0) >= 9 && frame.generation === this.generation)
+                        this.desktopReporter?.refresh();
+                    continue;
+                }
+                if ((frame.t === 'desktop_background' || frame.t === 'desktop_lobby' || frame.t === 'desktop_prepare' || frame.t === 'desktop_cancel') && (this.serverManagementWire ?? 0) >= 9) {
+                    if (frame.t !== 'desktop_cancel' && frame.deviceGeneration !== this.generation)
+                        continue;
+                    if (this.options.onDesktopCommand && this.generation) {
+                        // Capture the authenticated generation now: later callbacks cannot borrow a reconnect.
+                        try {
+                            void this.options.onDesktopCommand(frame, this.generation).catch(() => undefined);
+                        }
+                        catch { /* bounded desktop admission failure */ }
+                    }
+                    continue;
+                }
                 if (frame.t === 'channel_ticket') {
                     const queue = pending.get(frame.channel);
                     queue?.shift()?.resolve(frame.ticket);
@@ -217,6 +377,10 @@ export class ManagementChannel {
                     void dispatchUpdateCommand(channel, frame, this.options.onUpdate, this.serverManagementWire);
                     continue;
                 }
+                if (frame.t === 'keeper_control' && this.options.onKeeperControl) {
+                    void dispatchKeeperControl(channel, frame, this.options.onKeeperControl);
+                    continue;
+                }
                 if (frame.t === 'external_agents_scan' && this.options.onExternalAgentsScan) {
                     channel.send(buildScanResultFrame(frame.commandId, await this.options.onExternalAgentsScan()));
                 }

package/dist/workstation/channels/url.js

@@ -11,7 +11,7 @@ function ipv4Octets(hostname) {
     return octets.every((octet) => octet <= 255) ? octets : null;
 }
 /** Deliberately classifies literal names/IPs only: DNS answers must never downgrade transport security. */
-function isTrustedPlaintextHost(rawHostname) {
+export function isTrustedPlaintextHost(rawHostname) {
     const hostname = rawHostname.toLowerCase().replace(/^\[|\]$/g, '');
     if (TRUSTED_PLAINTEXT_NAMES.has(hostname) || hostname.endsWith('.localhost'))
         return true;

package/dist/workstation/config.js

@@ -1,20 +1,28 @@
+import { loadManagedCliInstallSync, npmExecutionContext } from './managedInstall.js';
 import { resolveBrowserBinding } from './desktop/binding.js';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
+import { z } from 'zod';
+const localPath = z.string().refine(p => path.isAbsolute(p) && !p.includes('\0'));
+const nativeConfig = z.strictObject({ kind: z.literal('linux-native'), helperPath: localPath, runtimeDir: localPath });
 export function updateServiceContext(configDir = clientDir(), overrides = {}) {
     // config.ts lives in dist/workstation/ after packaging, so two levels up is the installed package root.
     const packageRoot = overrides.packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-    const nodePath = overrides.nodePath ?? process.execPath;
+    const managed = loadManagedCliInstallSync(packageRoot);
+    const nodePath = managed?.nodePath ?? overrides.nodePath ?? process.execPath;
+    const npmPrefix = managed?.prefix ?? overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..');
     return {
         configDir,
+        ...(managed ? { managed } : {}),
+        env: npmExecutionContext({ prefix: npmPrefix, nodePath }, process.env),
         platform: overrides.platform ?? (process.platform === 'darwin' ? 'darwin' : 'linux'),
         nodePath,
-        npmPath: overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
+        npmPath: managed?.npmPath ?? overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
         // packageRoot is under lib/node_modules/@platless; climb to npm's global prefix.
-        npmPrefix: overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..'),
+        npmPrefix,
         packageRoot,
     };
 }
@@ -35,7 +43,11 @@ export async function loadClientConfig(dir) {
         throw new Error('Invalid workstation config: server and workstationId are required; run axom auth again');
     }
     const browserBinding = parsed.browserBinding ? resolveBrowserBinding(parsed.browserBinding, {}) : undefined;
-    return { ...(browserBinding ? { browserBinding } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
+    const desktopProvider = parsed.desktopProvider ? nativeConfig.parse({ ...parsed.desktopProvider,
+        helperPath: parsed.desktopProvider.helperPath === '/usr/local/bin/axom-desktop-helper' ? '/usr/local/bin/axom-desktop-keeper' : parsed.desktopProvider.helperPath,
+    }) : process.env.AXOM_DESKTOP_NATIVE_PROVIDER === '1' ?
+        nativeConfig.parse({ kind: 'linux-native', helperPath: '/usr/local/bin/axom-desktop-keeper', runtimeDir: '/run/axom-desktop' }) : undefined;
+    return { ...(browserBinding ? { browserBinding } : {}), ...(desktopProvider ? { desktopProvider } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(typeof parsed.ownerUserId === 'string' && parsed.ownerUserId ? { ownerUserId: parsed.ownerUserId } : {}), ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
 }
 export async function writeKeys(dir, clientKeyB64, serverPubB64) {
     await fs.mkdir(dir, { recursive: true });

package/dist/workstation/connection/encryptedChannel.js

@@ -279,7 +279,10 @@ export function connectEncryptedChannel(options) {
             if (!isBinary)
                 return;
             try {
-                const frame = options.decode(crypto.open(sessionKey, bytes).toString());
+                const plaintext = crypto.open(sessionKey, bytes);
+                const frame = options.decodeBytes ? options.decodeBytes(plaintext) : options.decode(plaintext.toString());
+                if (options.admitFrame && !options.admitFrame(frame))
+                    return;
                 const acknowledged = [...outstandingAcks].some((sequence) => options.isHeartbeatAck(frame, sequence));
                 // A correctly encrypted and decoded frame proves the peer is still reachable. Heartbeat
                 // acknowledgements are one such frame, but computer streaming/agent events may legitimately

package/dist/workstation/control/bindingStore.js

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