@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/update/deviceCompatibility.js

@@ -0,0 +1,119 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import semver from 'semver';
+import { withPrivateLock } from '../control/locks.js';
+import { processCommand, pidAlive } from '../keepers/kit/lock.js';
+import { processStartTime, sameProcess } from '../keepers/kit/orphanSweep.js';
+import { captureStartupPackageEvidence } from './deviceHealth.js';
+import { readDeviceBootstrapRecovery, readDeviceWatchdogPlan, readPrivateUpdateBytes, updateTransactionKey, deviceRollbackCompleted } from './recoveryPlan.js';
+import { persistDeviceRollbackPhase } from './deviceRollback.js';
+import { writeDurablePrivateUpdate, syncPrivateRecoveryFile } from './privateDurability.js';
+import { launchWatchdogProcess } from './watchdogProcess.js';
+import { UpdateStateStore } from './stateStore.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function needsWatchdogCompatibility(plan) { return !!semver.valid(plan.deviceRecovery.rollback.version) && semver.lt(plan.deviceRecovery.rollback.version, '0.6.50'); }
+export async function ensureCompatibleWatchdog(context, original, runSystemd) {
+    const key = updateTransactionKey(original.commandId), root = context.configDir, update = path.join(root, 'update'), originalPlan = path.join(update, `watchdog-${key}.json`);
+    await readDeviceWatchdogPlan(originalPlan, root);
+    const program = path.join(update, `compat-recovery-${key}.mjs`), metadata = path.join(update, `compat-recovery-${key}.json`);
+    const source = path.join(path.dirname(path.dirname(context.cliPath)), 'dist/workstation/update/watchdog.js'), bytes = await fs.readFile(source);
+    try {
+        await fs.writeFile(program, bytes, { mode: 0o700, flag: 'wx' });
+        await syncPrivateRecoveryFile(program);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST' || digest(await fs.readFile(program)) !== digest(bytes))
+            throw error;
+    }
+    const plan = { schemaVersion: 4, root, program, programHash: digest(bytes), originalPlan, originalPlanHash: digest(await readPrivateUpdateBytes(originalPlan, 1_048_576)), context };
+    await writeDurablePrivateUpdate(metadata, JSON.stringify(plan));
+    await launchWatchdogProcess({ nodePath: context.nodePath, program, plan: metadata, lifecycle: 'managed', logPath: path.join(update, 'compat-recovery.log') }, { platform: context.platform, runSystemd });
+}
+export function rollbackServiceContext(plan, nodePath = process.execPath) {
+    if (process.platform !== 'linux' && process.platform !== 'darwin')
+        throw Error('Managed rollback requires a supported user service');
+    const user = os.userInfo();
+    return { platform: process.platform, username: user.username, userId: process.getuid?.() ?? user.uid, homeDir: os.homedir(), nodePath, cliPath: plan.cliPath, npmPath: plan.npmPath, npmPrefix: plan.npmPrefix, configDir: plan.deviceRecovery.root, pathEnv: plan.npmEnvironment?.PATH ?? process.env.PATH ?? '/usr/bin:/bin', npmConfigPrefix: plan.npmPrefix };
+}
+export async function provisionVerifiedRollback(context, osDeps = {}) {
+    const pkg = path.dirname(path.dirname(context.cliPath)), metadata = JSON.parse(await fs.readFile(path.join(pkg, 'package.json'), 'utf8'));
+    const startup = await captureStartupPackageEvidence(pkg, metadata.version), recovery = await readDeviceBootstrapRecovery(context.configDir, startup);
+    if (!recovery?.transaction.installedRollback || !recovery.transaction.recoveryRequired)
+        throw Error('Service repair requires the original exact installed rollback receipt');
+    const { createServiceManager } = await import('../service/installer.js');
+    await createServiceManager(context, osDeps).install({ interactive: false, restartRunning: true });
+}
+async function transaction(root) { const { deviceTransactionSchema } = await import('./deviceCoordinator.js'); return deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/device-transaction.json'), 33_554_432)).toString())); }
+async function originalPlan(metadata) { const bytes = await readPrivateUpdateBytes(metadata.originalPlan, 1_048_576); if (digest(bytes) !== metadata.originalPlanHash)
+    throw Error('Original compatibility watchdog plan changed'); return readDeviceWatchdogPlan(metadata.originalPlan, metadata.root); }
+async function originalAlive(context, plan, planPath) {
+    const expected = `${context.nodePath} ${plan.program.path} ${planPath}`;
+    const listing = await promisify(execFile)('ps', ['-ww', '-axo', 'pid=,command='], { maxBuffer: 8_388_608 });
+    for (const line of listing.stdout.split('\n')) {
+        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!match || match[2] !== expected)
+            continue;
+        const pid = Number(match[1]), start = await processStartTime(pid);
+        if (start && pidAlive(pid) && await processCommand(pid) === expected && await sameProcess(pid, start))
+            return true;
+    }
+    return false;
+}
+async function executeOriginal(metadata, plan) { await new Promise((resolve, reject) => { const child = spawn(metadata.context.nodePath, [plan.program.path, metadata.originalPlan], { stdio: 'inherit', env: { ...process.env, AXOM_WORKSTATION_CONFIG_DIR: metadata.root } }); child.once('error', reject); child.once('close', () => resolve()); }); }
+async function retireOriginal(metadata) { const plan = await originalPlan(metadata); await fs.unlink(metadata.originalPlan); await fs.unlink(plan.program.path); }
+/** A destination-owned compatibility process leaves the original program/plan byte-for-byte
+ * intact, waits for any existing owner, and repairs only a positively installed rollback. */
+export async function runCompatibleWatchdog(metadata, deps = {}) {
+    if (metadata.schemaVersion !== 4 || metadata.context.configDir !== metadata.root || path.dirname(metadata.program) !== path.join(metadata.root, 'update') || digest(await fs.readFile(metadata.program)) !== metadata.programHash)
+        throw Error('Compatibility recovery program binding changed');
+    await withPrivateLock(path.join(metadata.root, 'update', path.basename(metadata.program, '.mjs')), async () => {
+        let state = await transaction(metadata.root);
+        try {
+            await fs.lstat(metadata.originalPlan);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && !state.recoveryRequired && ['SUCCEEDED', 'ROLLED_BACK'].includes(state.phase))
+                return;
+            throw error;
+        }
+        const plan = await originalPlan(metadata);
+        const pause = deps.wait ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+        while (await (deps.alive ?? (() => originalAlive(metadata.context, plan, metadata.originalPlan)))())
+            await pause(250);
+        state = await transaction(metadata.root);
+        try {
+            await fs.lstat(metadata.originalPlan);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && !state.recoveryRequired && ['SUCCEEDED', 'ROLLED_BACK'].includes(state.phase))
+                return;
+            throw error;
+        }
+        if (!state.installedRollback && ['RESTARTING', 'SUCCEEDED'].includes(state.phase)) {
+            await (deps.runOriginal ?? (() => executeOriginal(metadata, plan)))();
+            state = await transaction(metadata.root);
+        }
+        if (state.installedRollback && state.recoveryRequired && ['FAILED', 'RESTARTING'].includes(state.phase)) {
+            await (deps.provision ?? provisionVerifiedRollback)(metadata.context);
+            await persistDeviceRollbackPhase(metadata.root, plan.deviceRecovery.expectation, 'ROLLED_BACK');
+            await new UpdateStateStore(metadata.root).save({ phase: 'ROLLED_BACK', commandId: state.transactionId, version: state.release.version, releaseSha512: state.release.sha512, remoteForcePolicy: 'drain-only' });
+            state = await transaction(metadata.root);
+        }
+        if (state.installedRollback && state.phase === 'ROLLED_BACK' && !state.recoveryRequired) {
+            const pkg = path.dirname(path.dirname(metadata.context.cliPath)), version = JSON.parse(await fs.readFile(path.join(pkg, 'package.json'), 'utf8')).version;
+            if (!await deviceRollbackCompleted(metadata.root, await captureStartupPackageEvidence(pkg, version), state.transactionId))
+                throw Error('Compatible rollback completion no longer matches its frozen archive');
+            try {
+                await retireOriginal(metadata);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    });
+}

package/dist/workstation/update/deviceCoordinator.js

@@ -0,0 +1,369 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { LocalControlError } from '../control/protocol.js';
+import { deploymentDownloadURL, normalizeWorkstationServer } from '../control/serverIdentity.js';
+import { archiveEvidenceSchema } from './archiveEvidence.js';
+import { captureStartupPackageEvidence, deviceHealthMatches, queryDeviceHealth, deviceHealthRequestSchema, deviceHealthWitnessSchema, deviceInstalledRollbackSchema, deviceUpdateOriginSchema, runtimeFilesDigest } from './deviceHealth.js';
+import { writeDurablePrivateUpdate } from './privateDurability.js';
+const identity = z.string().min(1).max(128).refine(value => !/[\u0000-\u001f\u007f]/.test(value));
+const releaseSchema = z.object({ version: identity, url: z.string().min(1).max(4096), size: z.number().int().positive().max(536_870_912), sha512: z.string().regex(/^[a-f0-9]{128}$/i).transform(value => value.toLowerCase()) }).strict();
+export const deviceTransactionSchema = z.object({
+    schemaVersion: z.literal(1), transactionId: z.string().uuid(), challenge: z.string().regex(/^[a-f0-9]{64}$/),
+    initiatingDaemonGeneration: identity,
+    origin: deviceUpdateOriginSchema,
+    release: releaseSchema, resolvedSource: z.string().min(1).max(4096),
+    waiters: z.array(z.object({ registrationId: identity.nullable(), commandId: identity, managementGeneration: identity.nullable(), registrationRevision: identity.optional() }).strict().refine(value => (value.registrationId === null) === (value.managementGeneration === null))).min(1).max(128),
+    phase: z.enum(['REQUESTED', 'DRAINING', 'BUSY', 'DOWNLOADING', 'VERIFYING', 'INSTALLING', 'RESTARTING', 'SUCCEEDED', 'FAILED', 'ROLLED_BACK']),
+    recoveryRequired: z.boolean().optional(),
+    lifecycle: z.enum(['none', 'container', 'provision-and-arm']),
+    installation: z.enum(['not-started', 'started']).optional(),
+    restartPolicy: z.object({ schemaVersion: z.literal(1), mode: z.enum(['manual', 'external']), predecessor: z.object({ generation: identity, prepared: z.literal(true) }).strict().optional() }).strict().optional(),
+    targetEvidence: archiveEvidenceSchema.optional(),
+    installedRollback: deviceInstalledRollbackSchema.optional(),
+}).strict();
+export class DeviceUpdateCoordinator {
+    options;
+    active;
+    privateWrites = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+    }
+    get transactionPath() { return path.join(this.options.directory, 'update/device-transaction.json'); }
+    serializeWrite(operation) {
+        const writing = this.privateWrites.then(operation);
+        this.privateWrites = writing.catch(() => { });
+        return writing;
+    }
+    async save(transaction) {
+        const parsed = deviceTransactionSchema.parse(transaction);
+        const serialized = JSON.stringify(parsed) + '\n';
+        if (Buffer.byteLength(serialized) > 33_554_432)
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Complete private target inventory exceeds the supported transaction bound');
+        await writeDurablePrivateUpdate(this.transactionPath, serialized);
+    }
+    async previous() {
+        let handle;
+        try {
+            handle = await fs.open(this.transactionPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 33_554_432 || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+                throw new Error('Unsafe device update evidence');
+            return deviceTransactionSchema.parse(JSON.parse(await handle.readFile('utf8')));
+        }
+        catch {
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Preserve corrupt device update evidence and recover with a compatible CLI');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async snapshot(origin) {
+        const idle = { phase: 'SUCCEEDED', remoteForcePolicy: 'drain-only' };
+        const member = this.options.device.registrationIdentity(origin.registrationId);
+        if (!member || member.server !== origin.server)
+            return idle;
+        let transaction = this.active?.transaction ?? await this.previous();
+        if (!transaction)
+            return idle;
+        const waiter = [...transaction.waiters].reverse().find(waiter => waiter.registrationId === origin.registrationId);
+        const revision = waiter?.registrationRevision ?? (transaction.origin.kind === 'registration' && transaction.origin.registrationId === origin.registrationId ? transaction.origin.registrationRevision : undefined);
+        if (!waiter || revision !== member.revision)
+            return idle;
+        let healthPending = false;
+        if (['RESTARTING', 'SUCCEEDED'].includes(transaction.phase) && !transaction.recoveryRequired && transaction.targetEvidence && transaction.origin.kind === 'registration' && this.options.generation !== transaction.initiatingDaemonGeneration) {
+            const expected = { transactionId: transaction.transactionId, challenge: transaction.challenge, initiatingDaemonGeneration: transaction.initiatingDaemonGeneration, origin: transaction.origin, release: transaction.release, resolvedSource: transaction.resolvedSource, runtimeDigest: runtimeFilesDigest(transaction.targetEvidence.runtimeFiles) };
+            try {
+                const witness = await (this.options.health ?? queryDeviceHealth)(this.options.directory, expected);
+                if (deviceHealthMatches(expected, witness)) {
+                    const latest = await this.previous(), parsed = deviceHealthWitnessSchema.parse(witness);
+                    const current = this.options.management?.(origin.registrationId), currentMember = this.options.device.registrationIdentity(origin.registrationId);
+                    const initiating = expected.origin.kind === 'registration' ? this.options.management?.(expected.origin.registrationId) : undefined;
+                    const correlated = latest && latest.transactionId === transaction.transactionId && latest.challenge === transaction.challenge && JSON.stringify([latest.initiatingDaemonGeneration, latest.origin, latest.release, latest.resolvedSource, latest.targetEvidence]) === JSON.stringify([transaction.initiatingDaemonGeneration, transaction.origin, transaction.release, transaction.resolvedSource, transaction.targetEvidence]) && latest.waiters.some(value => JSON.stringify(value) === JSON.stringify(waiter));
+                    if (correlated && parsed.daemonGeneration === this.options.generation && current?.origin.managementGeneration === origin.managementGeneration && currentMember?.revision === member.revision && currentMember.server === member.server && initiating?.origin.managementGeneration === parsed.registration?.managementGeneration)
+                        transaction = latest;
+                    else
+                        healthPending = true;
+                }
+                else
+                    healthPending = true;
+            }
+            catch {
+                healthPending = true;
+            }
+        }
+        return { phase: healthPending ? 'RESTARTING' : transaction.phase, commandId: waiter.commandId, version: transaction.release.version, releaseSha512: transaction.release.sha512, remoteForcePolicy: 'drain-only', ...(transaction.recoveryRequired ? { phase: 'FAILED', error: 'Original device recovery remains unresolved' } : {}) };
+    }
+    persist(active) {
+        const snapshot = deviceTransactionSchema.parse(active.transaction);
+        active.writes = active.writes.catch(() => { }).then(() => active.prerequisite).then(async () => {
+            try {
+                await this.serializeWrite(() => this.save(snapshot));
+                active.owned = true;
+                active.persistenceUncertain = false;
+            }
+            catch (error) {
+                active.persistenceUncertain = true;
+                throw error;
+            }
+        });
+        return active.writes;
+    }
+    request(origin, command) {
+        if (this.options.lifecycle === 'none')
+            return Promise.resolve({ phase: 'FAILED', commandId: command.commandId, remoteForcePolicy: 'drain-only', error: 'managed_restart_required: remote device updates require an explicitly managed or container restart' });
+        if (this.options.initialized && !this.options.initialized())
+            return Promise.resolve({ phase: 'BUSY', commandId: command.commandId, remoteForcePolicy: 'drain-only', error: 'Original device initialization must complete before update admission' });
+        const registration = this.options.device.registrationIdentity(origin.registrationId);
+        if (!registration || registration.server !== normalizeWorkstationServer(origin.server))
+            throw new LocalControlError('BINDING_CONFLICT', 'Original update registration changed');
+        return this.accept({ kind: 'registration', registrationId: registration.id, registrationRevision: registration.revision, managementGeneration: origin.managementGeneration, server: registration.server }, command);
+    }
+    local(operationId, release, source) {
+        if (this.options.lifecycle === 'none')
+            return Promise.resolve({ phase: 'FAILED', commandId: operationId, remoteForcePolicy: 'drain-only', error: 'stop_first: the foreground owner cannot safely hand off this update; stop and verify it, then use an explicitly managed workstation or compatible local recovery and explicitly restart to verify the installed package' });
+        if (this.options.initialized && !this.options.initialized())
+            return Promise.resolve({ phase: 'BUSY', commandId: operationId, remoteForcePolicy: 'drain-only', error: 'Original device initialization must complete before update admission' });
+        return this.accept({ kind: 'local', server: normalizeWorkstationServer(source) }, { commandId: operationId, release, force: false });
+    }
+    accept(origin, command) {
+        const release = releaseSchema.parse(command.release);
+        const commandId = identity.parse(command.commandId);
+        const source = normalizeWorkstationServer(origin.server);
+        const resolvedSource = deploymentDownloadURL(source, release.url);
+        const registrationId = origin.kind === 'registration' ? origin.registrationId : null;
+        const managementGeneration = origin.kind === 'registration' ? origin.managementGeneration : null;
+        const registrationRevision = origin.kind === 'registration' ? origin.registrationRevision : undefined;
+        if (this.active) {
+            const active = this.active;
+            const target = active.transaction.release;
+            if (target.version !== release.version || target.sha512 !== release.sha512 || target.size !== release.size || target.url !== release.url)
+                return Promise.resolve({ phase: 'UPDATE_IN_PROGRESS', commandId, version: release.version, remoteForcePolicy: 'drain-only', error: 'A different declared release already owns the device update transaction' });
+            const waiter = active.transaction.waiters.find(value => value.registrationId === registrationId && value.commandId === commandId);
+            if (waiter)
+                waiter.managementGeneration = managementGeneration;
+            else {
+                if (active.transaction.waiters.length >= 128)
+                    return Promise.resolve({ phase: 'BUSY', commandId, remoteForcePolicy: 'drain-only', error: 'The device update waiter limit is reached' });
+                active.transaction.waiters.push({ registrationId, commandId, managementGeneration, registrationRevision });
+            }
+            const accepted = this.persist(active);
+            if (active.restorationPending) {
+                active.restorationPending = false;
+                active.done = this.restore(active);
+                void active.done.catch(() => { });
+            }
+            return accepted.then(() => active.done).then(status => ({ ...status, commandId, remoteForcePolicy: 'drain-only' }));
+        }
+        const transaction = {
+            schemaVersion: 1, transactionId: randomUUID(), challenge: randomBytes(32).toString('hex'), initiatingDaemonGeneration: this.options.generation,
+            origin: { ...origin, server: source },
+            release, resolvedSource, waiters: [{ registrationId, commandId, managementGeneration, registrationRevision }], phase: 'REQUESTED', lifecycle: this.options.lifecycle ?? 'none', installation: 'not-started',
+            ...(this.options.lifecycle === 'container' ? { restartPolicy: { schemaVersion: 1, mode: 'external' } } : {}),
+        };
+        const lease = this.options.device.acquireMaintenance({ transactionId: transaction.transactionId, ...(origin.kind === 'registration' ? { origin: { registrationId: origin.registrationId, revision: origin.registrationRevision } } : {}) });
+        const previous = this.previous().then(async (prior) => {
+            if (prior && (prior.recoveryRequired || !['SUCCEEDED', 'FAILED', 'BUSY', 'ROLLED_BACK'].includes(prior.phase)))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'An original device update still requires authenticated completion or recovery');
+            if (prior && ['FAILED', 'BUSY'].includes(prior.phase) && prior.installation !== 'not-started')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original package mutation cannot be excluded');
+            try {
+                if ((await fs.readdir(path.dirname(this.transactionPath))).some(name => /^watchdog-.*\.json(?:\..*)?$/.test(name)))
+                    throw new LocalControlError('BUSY', 'The original armed watchdog must finish its own transaction cleanup before another update');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        });
+        void previous.catch(() => { });
+        const active = { transaction, lease, prerequisite: previous, owned: false, writes: Promise.resolve(), done: Promise.resolve({ phase: 'REQUESTED' }) };
+        this.active = active;
+        active.done = this.run(active);
+        void active.done.catch(() => { });
+        return active.done.then(status => ({ ...status, commandId, remoteForcePolicy: 'drain-only' }));
+    }
+    async run(active) {
+        const { transaction, lease } = active;
+        let status = { phase: 'FAILED', commandId: transaction.transactionId, version: transaction.release.version, remoteForcePolicy: 'drain-only' };
+        let persisted = false;
+        try {
+            await this.persist(active);
+            persisted = true;
+            await lease.ready;
+            const observed = await lease.observe();
+            if (observed.status !== 'candidate')
+                status = { ...status, phase: 'BUSY', error: 'Existing device work or unknown original obligations prevent update; retry after they settle' };
+            else
+                status = { ...await this.options.execute({ commandId: transaction.transactionId, release: { ...transaction.release }, force: false }, {
+                        source: transaction.origin.server, transaction: deviceTransactionSchema.parse(transaction),
+                        currentTransaction: () => deviceTransactionSchema.parse(transaction),
+                        recordPhase: async (status) => {
+                            if (status.phase === 'SUCCEEDED')
+                                return;
+                            if (status.phase === 'INSTALLING')
+                                transaction.installation = 'started';
+                            if (status.phase === 'FAILED' && transaction.installation === 'started')
+                                transaction.recoveryRequired = true;
+                            transaction.phase = status.phase === 'UPDATE_IN_PROGRESS' ? 'FAILED' : status.phase;
+                            await this.persist(active);
+                        },
+                        recordTarget: async (raw) => {
+                            const evidence = archiveEvidenceSchema.parse(raw);
+                            if (evidence.version !== transaction.release.version || evidence.sha512 !== transaction.release.sha512 || evidence.size !== transaction.release.size)
+                                throw new LocalControlError('BINDING_CONFLICT', 'Verified target archive does not match the pinned release');
+                            if (transaction.targetEvidence && JSON.stringify(transaction.targetEvidence) !== JSON.stringify(evidence))
+                                throw new LocalControlError('BINDING_CONFLICT', 'The original target archive evidence is immutable');
+                            transaction.targetEvidence = evidence;
+                            transaction.phase = 'VERIFYING';
+                            await this.persist(active);
+                        },
+                        observe: async () => (await lease.observe()).status === 'candidate',
+                        handoff: async () => {
+                            if (transaction.restartPolicy && !transaction.targetEvidence)
+                                throw new LocalControlError('OUTCOME_UNKNOWN', 'Exact verified target inventory is required before original restart handoff');
+                            await lease.handoff();
+                            if (transaction.restartPolicy) {
+                                transaction.restartPolicy.predecessor = { generation: this.options.generation, prepared: true };
+                                await this.persist(active);
+                            }
+                        },
+                    }), remoteForcePolicy: 'drain-only' };
+            active.outcome = status;
+            return status;
+        }
+        finally {
+            if (active.persistenceUncertain) {
+                transaction.recoveryRequired = true;
+                active.restorationPending = true;
+                active.outcome ??= status;
+                await this.persist(active);
+            }
+            else if (status.phase !== 'RESTARTING' && !transaction.recoveryRequired) {
+                active.outcome ??= status;
+                await this.release(active);
+            }
+            else if (status.phase === 'RESTARTING' && persisted) {
+                transaction.phase = 'RESTARTING';
+                await this.persist(active);
+            }
+            let pending;
+            do {
+                pending = active.writes;
+                await pending.catch(() => { });
+            } while (pending !== active.writes);
+            if (status.phase !== 'RESTARTING' && !transaction.recoveryRequired && !active.restorationPending && this.active === active)
+                this.active = undefined;
+        }
+    }
+    async release(active) {
+        if (!active.owned) {
+            try {
+                await active.lease.release();
+                active.restorationPending = false;
+            }
+            catch {
+                active.restorationPending = true;
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original admission restoration remains pending; prior private evidence was preserved');
+            }
+            return;
+        }
+        try {
+            await active.lease.release(async () => {
+                const status = active.outcome ?? { phase: 'FAILED' };
+                active.transaction.phase = status.phase === 'UPDATE_IN_PROGRESS' ? 'FAILED' : status.phase;
+                active.transaction.recoveryRequired = false;
+                await this.persist(active);
+                let pending;
+                do {
+                    pending = active.writes;
+                    await pending;
+                } while (pending !== active.writes);
+            });
+        }
+        catch {
+            active.restorationPending = true;
+            active.transaction.phase = 'FAILED';
+            active.transaction.recoveryRequired = true;
+            await this.persist(active);
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Original maintenance restoration remains pending; preserve the update transaction and retry its exact operation');
+        }
+    }
+    async restore(active) {
+        await this.release(active);
+        const status = active.outcome ?? { phase: 'FAILED', error: 'Original update failed before a confirmed outcome' };
+        let pending;
+        do {
+            pending = active.writes;
+            if (active.owned)
+                await pending;
+            else
+                await pending.catch(() => { });
+        } while (pending !== active.writes);
+        if (this.active === active)
+            this.active = undefined;
+        return status;
+    }
+    async health(raw, generation) {
+        const request = deviceHealthRequestSchema.parse(raw);
+        const transaction = await this.previous();
+        const startup = this.options.startupPackage;
+        if (!transaction || !startup || !this.options.packageRoot || this.options.initialized?.() !== true || transaction.recoveryRequired || !['RESTARTING', 'SUCCEEDED'].includes(transaction.phase) || !transaction.targetEvidence || request.transactionId !== transaction.transactionId || request.challenge !== transaction.challenge || generation !== this.options.generation || generation === transaction.initiatingDaemonGeneration)
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Exact initialized successor health is not yet available');
+        if (startup.version !== transaction.release.version || runtimeFilesDigest(transaction.targetEvidence.runtimeFiles) !== startup.runtimeDigest || transaction.targetEvidence.sha512 !== transaction.release.sha512 || transaction.targetEvidence.size !== transaction.release.size || transaction.targetEvidence.version !== transaction.release.version || deploymentDownloadURL(transaction.origin.server, transaction.release.url) !== transaction.resolvedSource)
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'The original startup package does not match the exact pinned installed target');
+        try {
+            const current = await captureStartupPackageEvidence(this.options.packageRoot, startup.version);
+            if (current.runtimeDigest !== startup.runtimeDigest)
+                throw new Error('Installed runtime changed');
+        }
+        catch {
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Installed target bytes no longer match the original startup capture');
+        }
+        const currentRegistration = () => {
+            if (transaction.origin.kind !== 'registration')
+                return null;
+            const origin = transaction.origin;
+            const current = this.options.management?.(origin.registrationId);
+            const member = this.options.device.registrationIdentity(origin.registrationId);
+            const release = current?.release;
+            if (!current || !member || member.revision !== origin.registrationRevision || member.server !== origin.server || current.origin.server !== origin.server || current.origin.registrationId !== origin.registrationId || current.origin.managementGeneration === origin.managementGeneration || !release || release.version !== transaction.release.version || release.url !== transaction.release.url || release.size !== transaction.release.size || release.sha512.toLowerCase() !== transaction.release.sha512)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The initiating registration has not authenticated its exact fresh successor connection');
+            return { registrationId: origin.registrationId, registrationRevision: member.revision, server: member.server, managementGeneration: current.origin.managementGeneration };
+        };
+        const registration = currentRegistration();
+        const assertCurrent = () => { if (JSON.stringify(currentRegistration()) !== JSON.stringify(registration) || this.options.initialized?.() !== true)
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'The exact initiating successor connection changed during recovery'); };
+        const expectedTransaction = JSON.stringify(transaction);
+        const complete = () => this.serializeWrite(async () => {
+            if (JSON.stringify(await this.previous()) !== expectedTransaction)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The exact successor transaction changed before durable completion');
+            assertCurrent();
+            transaction.phase = 'SUCCEEDED';
+            await this.save(transaction);
+            try {
+                assertCurrent();
+            }
+            catch (error) {
+                transaction.phase = 'RESTARTING';
+                await this.save(transaction);
+                throw error;
+            }
+        });
+        if (this.options.completeRecovery)
+            await this.options.completeRecovery(complete);
+        else
+            await complete();
+        assertCurrent();
+        const witness = deviceHealthWitnessSchema.parse({ schemaVersion: 1, transactionId: transaction.transactionId, challenge: transaction.challenge, daemonGeneration: generation, startupVersion: startup.version, release: { ...transaction.release }, resolvedSource: transaction.resolvedSource, runtimeDigest: startup.runtimeDigest, registration });
+        return witness;
+    }
+}

package/dist/workstation/update/deviceHealth.js

@@ -0,0 +1,104 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { rootReaderSchema } from './archiveEvidence.js';
+import { runtimeRequest } from '../control/runtimeClient.js';
+import { deviceHealthRequestSchema, deviceHealthWitnessSchema, runtimeFilesDigest } from './deviceHealthProtocol.js';
+export * from './deviceHealthProtocol.js';
+export function deviceHealthMatches(expected, raw) {
+    const parsed = deviceHealthWitnessSchema.safeParse(raw);
+    if (!parsed.success)
+        return false;
+    const witness = parsed.data;
+    if (witness.transactionId !== expected.transactionId || witness.challenge !== expected.challenge || witness.daemonGeneration === expected.initiatingDaemonGeneration || witness.startupVersion !== expected.release.version || witness.runtimeDigest !== expected.runtimeDigest || witness.resolvedSource !== expected.resolvedSource)
+        return false;
+    if (witness.release.version !== expected.release.version || witness.release.url !== expected.release.url || witness.release.size !== expected.release.size || witness.release.sha512 !== expected.release.sha512)
+        return false;
+    if (expected.origin.kind === 'local')
+        return witness.registration === null;
+    const registration = witness.registration;
+    return !!registration && registration.registrationId === expected.origin.registrationId && registration.registrationRevision === expected.origin.registrationRevision && registration.server === expected.origin.server && registration.managementGeneration !== expected.origin.managementGeneration;
+}
+export async function queryDeviceHealth(root, expected) {
+    return runtimeRequest(root, 'update-health', undefined, { request: deviceHealthRequestSchema.parse({ transactionId: expected.transactionId, challenge: expected.challenge }) });
+}
+export async function captureStartupPackageEvidence(packageRoot, runningVersion) {
+    const paths = ['package.json'];
+    const names = new Map();
+    const walk = async (relative, depth) => {
+        if (depth > 64)
+            throw Error('Unsupported runtime inventory depth');
+        const directory = await fs.lstat(path.join(packageRoot, relative));
+        if (!directory.isDirectory() || directory.isSymbolicLink())
+            throw Error('Unsafe installed runtime directory');
+        for (const entry of await fs.readdir(path.join(packageRoot, relative), { withFileTypes: true })) {
+            const name = `${relative}/${entry.name}`;
+            if (/[^\x20-\x7e]|\\/.test(name) || name.length > 4096 || entry.name === '.' || entry.name === '..')
+                throw Error('Unsupported runtime inventory name');
+            const alias = name.toLowerCase();
+            if (names.has(alias))
+                throw Error('Ambiguous runtime inventory alias');
+            names.set(alias, name);
+            if (names.size > 65_536)
+                throw Error('Runtime inventory member limit exceeded');
+            if (entry.isDirectory())
+                await walk(name, depth + 1);
+            else if (entry.isFile())
+                paths.push(name);
+            else
+                throw Error('Unsupported installed runtime member');
+        }
+    };
+    await walk('dist', 0);
+    if (!paths.includes('dist/cli.js'))
+        throw Error('The installed executable entrypoint is missing');
+    const runtimeFiles = [];
+    let metadata;
+    let total = 0;
+    for (const relative of paths.sort()) {
+        const handle = await fs.open(path.join(packageRoot, relative), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await handle.stat();
+            if (!before.isFile() || before.nlink !== 1 || before.size > (relative === 'package.json' ? 1_048_576 : 134_217_728))
+                throw Error('Unsafe installed runtime file');
+            total += before.size;
+            if (total > 1_073_741_824)
+                throw Error('Installed runtime inventory size limit exceeded');
+            const bytes = await handle.readFile();
+            const after = await handle.stat();
+            if (bytes.length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+                throw Error('Installed runtime file changed during startup capture');
+            runtimeFiles.push({ path: relative, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') });
+            if (relative === 'package.json')
+                metadata = JSON.parse(bytes.toString('utf8'));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+        throw Error('Installed package identity is unavailable');
+    const value = metadata;
+    if (value.name !== '@platless/axom-cli' || value.version !== runningVersion || !rootReaderSchema.safeParse(value.axomWorkstationRootReader).success || !value.bin || typeof value.bin !== 'object' || value.bin.axom !== 'dist/cli.js')
+        throw Error('Installed package lacks a compatible root-format-2 reader identity');
+    const finalPaths = ['package.json'];
+    let finalCount = 0;
+    const collect = async (relative, depth = 0) => {
+        if (depth > 64 || ++finalCount > 65_536)
+            throw Error('Runtime inventory changed beyond supported limits');
+        for (const entry of await fs.readdir(path.join(packageRoot, relative), { withFileTypes: true })) {
+            if (++finalCount > 65_536)
+                throw Error('Runtime inventory changed beyond supported limits');
+            if (entry.isDirectory())
+                await collect(`${relative}/${entry.name}`, depth + 1);
+            else if (entry.isFile())
+                finalPaths.push(`${relative}/${entry.name}`);
+            else
+                throw Error('Runtime inventory changed during startup capture');
+        }
+    };
+    await collect('dist');
+    if (JSON.stringify(finalPaths.sort()) !== JSON.stringify(paths.sort()))
+        throw Error('Runtime inventory changed during startup capture');
+    return Object.freeze({ version: runningVersion, runtimeDigest: runtimeFilesDigest(runtimeFiles), runtimeFiles: Object.freeze(runtimeFiles.map(file => Object.freeze(file))) });
+}

package/dist/workstation/update/deviceHealthProtocol.js

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { archiveEvidenceSchema, rootReaderSchema } from './archiveEvidence.js';
+const bounded = z.string().min(1).max(128).refine(value => !/[\u0000-\u001f\u007f]/.test(value));
+const url = z.string().min(1).max(4096);
+export const deviceReleaseSchema = z.object({ version: bounded, url, size: z.number().int().positive().max(536_870_912), sha512: z.string().regex(/^[a-f0-9]{128}$/) }).strict();
+export const deviceUpdateOriginSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('registration'), registrationId: bounded, registrationRevision: bounded, managementGeneration: bounded, server: url }).strict(),
+    z.object({ kind: z.literal('local'), server: url }).strict(),
+]);
+export const deviceHealthRequestSchema = z.object({ transactionId: z.string().uuid(), challenge: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const deviceHealthExpectationSchema = deviceHealthRequestSchema.extend({ initiatingDaemonGeneration: bounded, origin: deviceUpdateOriginSchema, release: deviceReleaseSchema, resolvedSource: url, runtimeDigest: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const deviceHealthWitnessSchema = deviceHealthRequestSchema.extend({
+    schemaVersion: z.literal(1), daemonGeneration: bounded, startupVersion: bounded, release: deviceReleaseSchema, resolvedSource: url, runtimeDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    registration: z.object({ registrationId: bounded, registrationRevision: bounded, server: url, managementGeneration: bounded }).strict().nullable(),
+}).strict();
+export const deviceRollbackSourceSchema = z.discriminatedUnion('kind', [z.object({ kind: z.literal('local-pack'), packageRoot: url.optional() }).strict(), z.object({ kind: z.literal('authenticated-release'), server: url, release: deviceReleaseSchema }).strict()]);
+export const deviceWatchdogRecoverySchema = z.object({
+    schemaVersion: z.literal(2), root: url, expectation: deviceHealthExpectationSchema,
+    rollback: z.object({ archive: url, name: z.literal('@platless/axom-cli'), version: bounded, size: z.number().int().positive().max(536_870_912), sha512: z.string().regex(/^[a-f0-9]{128}$/), reader: rootReaderSchema, source: deviceRollbackSourceSchema }).strict(),
+}).strict();
+export const deviceRollbackReceiptSchema = deviceHealthExpectationSchema.extend({ schemaVersion: z.literal(1), prepared: z.literal(true), daemonGeneration: bounded }).strict();
+export const deviceInstalledRollbackSchema = z.object({ schemaVersion: z.literal(1), transactionId: z.string().uuid(), archive: archiveEvidenceSchema, handoff: deviceRollbackReceiptSchema }).strict();
+export function runtimeFilesDigest(files) {
+    return createHash('sha256').update(JSON.stringify([...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0))).digest('hex');
+}