@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/update/deviceRecoveryLifecycle.js

@@ -0,0 +1,46 @@
+import { deviceHealthExpectationSchema, deviceHealthMatches, deviceHealthWitnessSchema, queryDeviceHealth, runtimeFilesDigest } from './deviceHealth.js';
+import { deviceRollbackCompleted, readDeviceBootstrapRecovery } from './recoveryPlan.js';
+export function createDeviceRecoveryTick(options) {
+    let running = false, attempts = 0;
+    const binding = options.bootstrap?.transaction;
+    const expectation = binding?.targetEvidence ? deviceHealthExpectationSchema.parse({ transactionId: binding.transactionId, challenge: binding.challenge,
+        initiatingDaemonGeneration: binding.initiatingDaemonGeneration, origin: binding.origin, release: binding.release, resolvedSource: binding.resolvedSource,
+        runtimeDigest: runtimeFilesDigest(binding.targetEvidence.runtimeFiles),
+    }) : undefined;
+    return async () => {
+        if (running || options.signal.aborted || !options.initialized())
+            return;
+        running = true;
+        try {
+            const original = options.lease();
+            if (original && options.bootstrap?.transaction.installedRollback) {
+                if (await deviceRollbackCompleted(options.root, options.startup, options.bootstrap.transaction.transactionId)) {
+                    await original.release(async () => {
+                        if (!await deviceRollbackCompleted(options.root, options.startup, options.bootstrap.transaction.transactionId))
+                            throw Error('Original rollback completion changed during admission restoration');
+                    });
+                    options.released(original);
+                }
+                return;
+            }
+            if (original) {
+                if (!binding || !expectation || binding.origin.kind !== 'local' || options.bootstrap?.plan || binding.lifecycle === 'provision-and-arm' || binding.initiatingDaemonGeneration === options.generation || original.transactionId !== binding.transactionId || attempts >= 5)
+                    return;
+                attempts += 1;
+                const current = await readDeviceBootstrapRecovery(options.root, options.startup);
+                if (!current || current.plan || current.transaction.installedRollback || current.transaction.transactionId !== binding.transactionId || current.transaction.challenge !== binding.challenge || JSON.stringify(current.transaction.origin) !== JSON.stringify(binding.origin) || JSON.stringify(current.transaction.release) !== JSON.stringify(binding.release) || current.transaction.resolvedSource !== binding.resolvedSource || current.transaction.initiatingDaemonGeneration !== binding.initiatingDaemonGeneration)
+                    throw Error('Original local successor recovery binding changed');
+                if (options.signal.aborted || !options.initialized() || options.lease() !== original)
+                    return;
+                const witness = deviceHealthWitnessSchema.parse(await queryDeviceHealth(options.root, expectation));
+                if (!deviceHealthMatches(expectation, witness) || witness.daemonGeneration !== options.generation)
+                    throw Error('Private control did not confirm the exact original successor');
+                return;
+            }
+            await options.reconcile();
+        }
+        finally {
+            running = false;
+        }
+    };
+}

package/dist/workstation/update/deviceRollback.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { deviceHealthExpectationSchema, deviceInstalledRollbackSchema, deviceRollbackReceiptSchema, runtimeFilesDigest } from './deviceHealthProtocol.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
+import { readPrivateUpdateBytes, updateTransactionKey } from './recoveryPlan.js';
+import { runtimeRequest } from '../control/runtimeClient.js';
+import { LocalControlError } from '../control/protocol.js';
+import { writeDurablePrivateUpdate } from './privateDurability.js';
+export { deviceRollbackReceiptSchema } from './deviceHealthProtocol.js';
+export function rollbackHandoffPath(root, transactionId) { return path.join(root, 'update', `rollback-handoff-${updateTransactionKey(transactionId)}.json`); }
+export async function writePrivateDeviceEvidence(file, value) {
+    await writeDurablePrivateUpdate(file, JSON.stringify(value) + '\n');
+}
+function receiptMatches(expected, raw) {
+    const receipt = deviceRollbackReceiptSchema.parse(raw);
+    const { schemaVersion: _schemaVersion, prepared: _prepared, daemonGeneration: _generation, ...binding } = receipt;
+    if (receipt.daemonGeneration === expected.initiatingDaemonGeneration || JSON.stringify(deviceHealthExpectationSchema.parse(binding)) !== JSON.stringify(expected))
+        throw Error('Original target cleanup receipt changed its private recovery binding');
+    return receipt;
+}
+export async function assertDeviceRollbackReceipt(root, expected, raw) {
+    const receipt = receiptMatches(expected, raw);
+    const durable = receiptMatches(expected, JSON.parse((await readPrivateUpdateBytes(rollbackHandoffPath(root, expected.transactionId), 65536)).toString('utf8')));
+    if (JSON.stringify(receipt) !== JSON.stringify(durable))
+        throw Error('Original target cleanup receipt was not durably confirmed');
+}
+export async function queryDeviceRollbackHandoff(root, expected) {
+    return runtimeRequest(root, 'prepare-update-rollback', undefined, { request: expected }, 20_000);
+}
+export async function prepareDeviceRollbackHandoff(options, raw) {
+    const expected = deviceHealthExpectationSchema.parse(raw);
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(options.root, 'update/device-transaction.json'), 33_554_432)).toString('utf8')));
+    const actual = deviceHealthExpectationSchema.parse({ transactionId: transaction.transactionId, challenge: transaction.challenge, initiatingDaemonGeneration: transaction.initiatingDaemonGeneration, origin: transaction.origin, release: transaction.release, resolvedSource: transaction.resolvedSource, runtimeDigest: transaction.targetEvidence ? runtimeFilesDigest(transaction.targetEvidence.runtimeFiles) : '' });
+    if (JSON.stringify(expected) !== JSON.stringify(actual) || options.generation === expected.initiatingDaemonGeneration || options.startup.version !== expected.release.version || options.startup.runtimeDigest !== expected.runtimeDigest || !['RESTARTING', 'SUCCEEDED', 'FAILED'].includes(transaction.phase))
+        throw new LocalControlError('BINDING_CONFLICT', 'Only the exact original target daemon can prepare this rollback');
+    try {
+        const receipt = receiptMatches(expected, JSON.parse((await readPrivateUpdateBytes(rollbackHandoffPath(options.root, expected.transactionId), 65536)).toString('utf8')));
+        if (receipt.daemonGeneration !== options.generation)
+            throw Error('A replacement daemon cannot reuse another original cleanup receipt');
+        await writePrivateDeviceEvidence(rollbackHandoffPath(options.root, expected.transactionId), receipt);
+        return receipt;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lease = options.lease();
+    if (lease.transactionId !== transaction.transactionId)
+        throw new LocalControlError('BINDING_CONFLICT', 'Original maintenance transaction changed');
+    await lease.ready;
+    if ((await lease.observe()).status !== 'candidate')
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original target work or unknown obligations prevent automatic rollback');
+    await lease.handoff();
+    const receipt = deviceRollbackReceiptSchema.parse({ ...actual, schemaVersion: 1, prepared: true, daemonGeneration: options.generation });
+    await writePrivateDeviceEvidence(rollbackHandoffPath(options.root, expected.transactionId), receipt);
+    return receipt;
+}
+export async function persistDeviceRollbackPhase(root, expected, phase) {
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const file = path.join(root, 'update/device-transaction.json');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(file, 33_554_432)).toString('utf8')));
+    if (transaction.transactionId !== expected.transactionId || transaction.challenge !== expected.challenge || transaction.release.sha512 !== expected.release.sha512 || transaction.resolvedSource !== expected.resolvedSource)
+        throw Error('Original private rollback transaction changed');
+    await writePrivateDeviceEvidence(file, deviceTransactionSchema.parse({ ...transaction, phase, recoveryRequired: phase === 'FAILED' }));
+}
+export async function persistDeviceInstalledRollback(recovery, rawHandoff) {
+    await assertDeviceRollbackReceipt(recovery.root, recovery.expectation, rawHandoff);
+    const archive = await readArchiveEvidence(recovery.rollback.archive);
+    if (archive.sha512 !== recovery.rollback.sha512 || archive.size !== recovery.rollback.size || archive.version !== recovery.rollback.version)
+        throw Error('Frozen rollback package changed before installed evidence persistence');
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const file = path.join(recovery.root, 'update/device-transaction.json');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(file, 33_554_432)).toString('utf8')));
+    if (transaction.transactionId !== recovery.expectation.transactionId || transaction.challenge !== recovery.expectation.challenge || transaction.resolvedSource !== recovery.expectation.resolvedSource)
+        throw Error('Original installed rollback transaction changed');
+    const installedRollback = deviceInstalledRollbackSchema.parse({ schemaVersion: 1, transactionId: transaction.transactionId, archive, handoff: rawHandoff });
+    await writePrivateDeviceEvidence(file, deviceTransactionSchema.parse({ ...transaction, phase: 'RESTARTING', recoveryRequired: true, installedRollback }));
+}

package/dist/workstation/update/globalInstall.js

@@ -30,14 +30,72 @@ export async function attemptGlobalInstallFallback(npmPath, npmPrefix, archive,
         throw new Error('Archive package.json has no usable "name"');
     const bin = manifest.bin;
     const target = path.join(npmPrefix, 'lib/node_modules', name);
-    await fs.rm(target, { recursive: true, force: true });
-    await fs.mkdir(target, { recursive: true });
-    await run(spawn, 'tar', ['-xzf', archive, '-C', target, '--strip-components=1'], {});
-    const installEnv = { ...process.env, ...env };
-    delete installEnv.NPM_CONFIG_PREFIX;
-    delete installEnv.npm_config_prefix;
-    await run(spawn, npmPath, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: target, env: installEnv });
-    await relinkBinaries(npmPrefix, target, name, bin);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    // Finish extraction and dependency resolution before changing the installed package. Keep the
+    // previous tree and command entries until every replacement succeeds, including bin linking.
+    const staging = await fs.mkdtemp(path.join(path.dirname(target), '.axom-install-'));
+    const candidate = path.join(staging, 'candidate');
+    const previous = path.join(staging, 'previous');
+    let retired = false;
+    let replaced = false;
+    let retainRecovery = false;
+    const commands = [];
+    try {
+        await fs.mkdir(candidate);
+        await run(spawn, 'tar', ['-xzf', archive, '-C', candidate, '--strip-components=1'], {});
+        const installEnv = { ...process.env, ...env };
+        delete installEnv.NPM_CONFIG_PREFIX;
+        delete installEnv.npm_config_prefix;
+        await run(spawn, npmPath, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: candidate, env: installEnv });
+        try {
+            await fs.rename(target, previous);
+            retired = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await fs.rename(candidate, target);
+        replaced = true;
+        await relinkBinaries(npmPrefix, target, name, bin, staging, commands);
+    }
+    catch (error) {
+        const restoreErrors = [];
+        for (const { link, backup } of commands.reverse()) {
+            try {
+                await fs.rm(link, { force: true });
+                if (backup)
+                    await fs.rename(backup, link);
+            }
+            catch (restoreError) {
+                restoreErrors.push(restoreError);
+            }
+        }
+        // A command restoration failure must not prevent restoring the package itself.
+        try {
+            if (replaced)
+                await fs.rm(target, { recursive: true, force: true });
+        }
+        catch (restoreError) {
+            restoreErrors.push(restoreError);
+        }
+        try {
+            if (retired)
+                await fs.rename(previous, target);
+        }
+        catch (restoreError) {
+            restoreErrors.push(restoreError);
+        }
+        if (restoreErrors.length) {
+            retainRecovery = true;
+            throw new AggregateError([error, ...restoreErrors], `Global install fallback failed and its previous installation could not be restored; recovery files retained at ${staging}`);
+        }
+        throw error;
+    }
+    finally {
+        if (!retainRecovery)
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+    }
 }
 async function readArchivePackageJson(archive, spawn) {
     const raw = await capture(spawn, 'tar', ['-xzf', archive, '-O', 'package/package.json'], {});
@@ -49,7 +107,7 @@ async function readArchivePackageJson(archive, spawn) {
     }
 }
 /** Reproduces npm's own `bin` linking: a relative symlink from `<prefix>/bin/<name>` to the script. */
-async function relinkBinaries(npmPrefix, target, packageName, bin) {
+async function relinkBinaries(npmPrefix, target, packageName, bin, staging, commands) {
     const entries = binEntries(packageName, bin);
     if (entries.length === 0)
         return;
@@ -58,7 +116,19 @@ async function relinkBinaries(npmPrefix, target, packageName, bin) {
     for (const [command, relativeScript] of entries) {
         const script = path.join(target, relativeScript);
         const link = path.join(binDir, command);
-        await fs.rm(link, { force: true });
+        let backup;
+        try {
+            const existing = await fs.lstat(link);
+            if (existing.isDirectory())
+                throw new Error('Refusing to replace a directory with an npm command');
+            backup = path.join(staging, `bin-${commands.length}`);
+            await fs.rename(link, backup);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        commands.push({ link, backup });
         await fs.symlink(path.relative(binDir, script), link);
         await fs.chmod(script, 0o755).catch(() => undefined);
     }

package/dist/workstation/update/legacyBridge.js

@@ -0,0 +1,414 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import semver from 'semver';
+import { BindingStore } from '../control/bindingStore.js';
+import { inspectRuntime, inspectDeviceRuntime } from '../control/runtimeClient.js';
+import { normalizeWorkstationServer, workstationEndpoint } from '../control/serverIdentity.js';
+import { loadClientConfig, readKeys } from '../config.js';
+import yaml from 'js-yaml';
+import { captureStartupPackageEvidence } from './deviceHealth.js';
+import { runtimeFilesDigest } from './deviceHealthProtocol.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
+import { downloadVerified } from './artifact.js';
+import { readPrivateUpdateBytes, updateTransactionKey } from './recoveryPlan.js';
+import { writeDurablePrivateUpdate, syncPrivateRecoveryFile, ensureDurablePrivateDirectory } from './privateDurability.js';
+import { UpdateStateStore } from './stateStore.js';
+import { withPrivateLock, withWorkstationLock } from '../control/locks.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { LocalControlError } from '../control/protocol.js';
+import { pidAlive, processCommand } from '../keepers/kit/lock.js';
+import { launchWatchdogProcess } from './watchdogProcess.js';
+import { recoverAuthenticatedLegacyOwner } from './legacyOwner.js';
+const hash = (bytes) => createHash('sha512').update(bytes).digest('hex');
+const metadata = ['config.yml', 'client.key', 'server.pub', 'operation.json', 'binding-history.json', 'rd/state.json', 'desktop-provider.json', 'registrations.json', 'registration-tombstones.json', 'registrations.pending.json'];
+const planName = 'legacy-bridge.json';
+const legacyPlanSchema = z.object({ commandId: z.string().uuid(), targetVersion: z.string(), archive: z.string(), marker: z.string(), state: z.string(), npmPath: z.string(), npmPrefix: z.string(), cliPath: z.string() }).passthrough();
+const bridgeSchema = z.object({
+    schemaVersion: z.literal(3), lifecycle: z.enum(['managed', 'container']).default('managed'), root: z.string(), commandId: z.string().uuid(), version: z.string(), releaseSha512: z.string(),
+    predecessor: z.string(), server: z.string(), workstationId: z.string(), ownerUserId: z.string().nullable(),
+    runtimeDigest: z.string(), rollback: z.string(), rollbackSha512: z.string(), rollbackVersion: z.string(),
+    program: z.string(), context: z.object({ platform: z.enum(['linux', 'darwin']), username: z.string(), userId: z.number(), homeDir: z.string(), nodePath: z.string(), cliPath: z.string(), npmPath: z.string(), npmPrefix: z.string(), configDir: z.string(), pathEnv: z.string(), npmConfigPrefix: z.string().optional() }).passthrough(),
+    originals: z.record(z.string(), z.string()),
+});
+const bridgePath = (root) => path.join(root, 'update', planName);
+const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const migrationScope = new AsyncLocalStorage();
+export function withLegacyBridgeMigration(root, task) { return migrationScope.run(path.resolve(root), task); }
+export async function assertLegacyBridgeMutationAllowed(root, startup) {
+    const bridge = await readLegacyBridge(root, startup);
+    if (bridge && migrationScope.getStore() !== path.resolve(root) && !startup)
+        throw new LocalControlError('BUSY', 'The original legacy update still owns registration admission until recovery completes');
+}
+async function confirmedBridgeReady(plan) {
+    try {
+        const ready = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/legacy-bridge-ready.json'), 4096)).toString());
+        return ready.commandId === plan.commandId && ready.runtimeDigest === plan.runtimeDigest && typeof ready.generation === 'string' && ready.generation.length > 0 && ready.generation !== plan.predecessor;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function finalizeConfirmedBridge(plan) {
+    await new UpdateStateStore(plan.root).save({ phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 });
+    await fs.rename(bridgePath(plan.root), path.join(plan.root, 'update/legacy-bridge-completed.json'));
+}
+async function snapshotMetadata(root, name) {
+    if (name !== 'server.pub')
+        return readPrivateUpdateBytes(path.join(root, name), 1_048_576);
+    const handle = await fs.open(path.join(root, name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1_048_576 || stat.mode & 0o022 || process.getuid && stat.uid !== process.getuid())
+            throw Error('Unsafe legacy public key');
+        return handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function legacyDesktopContinuity(root) {
+    if (await readLegacyBridge(root))
+        return true;
+    try {
+        const plan = bridgeSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/legacy-bridge-completed.json'), 8_388_608)).toString()));
+        return plan.root === path.resolve(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function assertLegacyBridgeTransferred(plan) {
+    const marker = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/restart-ready.json'), 4096)).toString());
+    if (marker.commandId !== plan.commandId || marker.version !== plan.version || typeof marker.generation !== 'string' || !marker.generation.startsWith('legacy-bridge:'))
+        throw Error('Legacy watchdog recovery ownership has not transferred');
+    if ((await fs.readdir(path.join(plan.root, 'update'))).some(name => /^watchdog-.*\.json$/.test(name)))
+        throw Error('Legacy watchdog plans have not been archived after recovery transfer');
+}
+export async function readLegacyBridge(root, startup) {
+    let bytes;
+    try {
+        bytes = await readPrivateUpdateBytes(bridgePath(root), 8_388_608);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const plan = bridgeSchema.parse(JSON.parse(bytes.toString()));
+    if (plan.root !== path.resolve(root) || plan.context.configDir !== plan.root || plan.rollback !== path.join(root, 'update', `legacy-rollback-${updateTransactionKey(plan.commandId)}.tgz`) || plan.program !== path.join(root, 'update', `legacy-bridge-${updateTransactionKey(plan.commandId)}.mjs`))
+        throw Error('Legacy update bridge paths changed');
+    if (startup && (startup.version !== plan.version || startup.runtimeDigest !== plan.runtimeDigest))
+        throw Error('Legacy update bridge installed target inventory changed');
+    if (Object.keys(plan.originals).some(name => !metadata.includes(name)))
+        throw Error('Legacy update bridge metadata scope changed');
+    return plan;
+}
+/** The predecessor already authenticated this release; bind its private update receipt and plan
+ * to the actual installed bytes before replacing its format1-only rollback authority. */
+export async function prepareLegacyBridge(root, context, options = {}) {
+    root = path.resolve(root);
+    const installedVersion = JSON.parse(await fs.readFile(path.join(path.dirname(path.dirname(context.cliPath)), 'package.json'), 'utf8')).version;
+    const predecessor = await inspectRuntime(root);
+    const identity = await new BindingStore(root).inspect();
+    if (identity.identityState !== 'ready' || !identity.binding)
+        throw Error('The original legacy workstation owner must confirm the update');
+    if (options.container ? predecessor.state !== 'stopped' : predecessor.state !== 'running' || !predecessor.generation || !predecessor.binding || normalizeWorkstationServer(predecessor.binding.server) !== normalizeWorkstationServer(identity.binding.server) || predecessor.binding.workstationId !== identity.binding.workstationId)
+        throw Error('The original legacy workstation owner must confirm the update');
+    for (const name of ['device.json', 'legacy-migration.json', 'registrations', 'registrations.json', 'registration-tombstones.json', 'registrations.pending.json']) {
+        try {
+            await fs.lstat(path.join(root, name));
+            throw Error('Legacy bridge requires the original unmigrated root');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString());
+    if (state.phase !== 'RESTARTING' || state.version !== installedVersion || typeof state.releaseSha512 !== 'string')
+        throw Error('Legacy automatic migration requires the exact restarting release receipt');
+    const update = path.join(root, 'update');
+    const oldPlanPath = path.join(update, `watchdog-${updateTransactionKey(state.commandId)}.json`);
+    let old;
+    if (options.container) {
+        try {
+            await fs.lstat(oldPlanPath);
+            throw Error('Container update unexpectedly has an active service watchdog');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        old = { commandId: state.commandId, targetVersion: state.version, archive: path.join(update, 'last-known-good/last-known-good.tgz'), marker: path.join(update, 'restart-ready.json'), state: path.join(root, 'update-state.json'), npmPath: context.npmPath, npmPrefix: context.npmPrefix, cliPath: context.cliPath };
+    }
+    else
+        old = legacyPlanSchema.parse(JSON.parse((await readPrivateUpdateBytes(oldPlanPath, 1_048_576)).toString()));
+    if (old.commandId !== state.commandId || old.targetVersion !== state.version || old.cliPath !== context.cliPath || old.npmPath !== context.npmPath || old.npmPrefix !== context.npmPrefix || old.archive !== path.join(update, 'last-known-good/last-known-good.tgz') || old.marker !== path.join(update, 'restart-ready.json') || old.state !== path.join(root, 'update-state.json'))
+        throw Error('Legacy watchdog does not identify the exact predecessor update');
+    const config = await loadClientConfig(root);
+    const fetchImpl = options.fetch ?? fetch;
+    const response = await fetchImpl(workstationEndpoint(config.server, '/download/client/manifest.json'), { redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw Error('Cannot confirm the original release manifest');
+    const descriptor = z.object({ version: z.string(), url: z.string(), size: z.number().int().positive(), sha512: z.string().regex(/^[a-f0-9]{128}$/) });
+    const release = descriptor.extend({ legacyBridgeRollback: descriptor.optional() }).parse(await response.json());
+    if (release.version !== state.version || release.sha512 !== state.releaseSha512)
+        throw Error('The original authenticated legacy release changed');
+    const artifact = await downloadVerified(release, { server: config.server, fetch: fetchImpl });
+    let runtimeDigest;
+    try {
+        const archive = await readArchiveEvidence(artifact.path);
+        const startup = await captureStartupPackageEvidence(path.dirname(path.dirname(context.cliPath)), installedVersion);
+        runtimeDigest = runtimeFilesDigest(archive.runtimeFiles);
+        if (startup.runtimeDigest !== runtimeDigest)
+            throw Error('Installed legacy update differs from the authenticated target archive');
+    }
+    finally {
+        await artifact.cleanup();
+    }
+    try {
+        await fs.access(old.archive);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || !options.container || !release.legacyBridgeRollback)
+            throw Error('Legacy container rollback archive is unavailable; publish a verified legacyBridgeRollback descriptor');
+        const fallback = await downloadVerified(release.legacyBridgeRollback, { server: config.server, fetch: fetchImpl });
+        try {
+            await ensureDurablePrivateDirectory(path.join(update, 'last-known-good'));
+            await fs.copyFile(fallback.path, old.archive);
+            await fs.chmod(old.archive, 0o600);
+            await syncPrivateRecoveryFile(old.archive);
+            await writeDurablePrivateUpdate(path.join(update, 'last-known-good/last-known-good.json'), JSON.stringify({ name: '@platless/axom-cli', version: release.legacyBridgeRollback.version, sha512: release.legacyBridgeRollback.sha512 }));
+        }
+        finally {
+            await fallback.cleanup();
+        }
+    }
+    const rollbackBytes = await fs.readFile(old.archive);
+    const rollbackMetadata = JSON.parse((await promisify(execFile)('/usr/bin/tar', ['-xOf', old.archive, 'package/package.json'], { maxBuffer: 1_048_576 })).stdout);
+    if (rollbackMetadata.name !== '@platless/axom-cli' || !semver.valid(rollbackMetadata.version) || !semver.lt(rollbackMetadata.version, installedVersion) || rollbackMetadata.axomWorkstationRootReader?.rootFormat === 2)
+        throw Error('Legacy rollback package must identify the original earlier format1 CLI');
+    const cached = JSON.parse((await readPrivateUpdateBytes(path.join(update, 'last-known-good/last-known-good.json'), 65536)).toString());
+    if (cached.name !== rollbackMetadata.name || cached.version !== rollbackMetadata.version || cached.sha512 !== hash(rollbackBytes))
+        throw Error('Original last-known-good rollback digest changed');
+    const originals = {};
+    for (const name of metadata)
+        try {
+            originals[name] = (await snapshotMetadata(root, name)).toString('base64');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    const key = updateTransactionKey(state.commandId);
+    const plan = { schemaVersion: 3, lifecycle: options.container ? 'container' : 'managed', root, commandId: state.commandId, version: state.version, releaseSha512: state.releaseSha512, predecessor: predecessor.generation ?? `stopped-container:${state.commandId}`, server: config.server, workstationId: identity.binding.workstationId, ownerUserId: identity.binding.ownerUserId ?? null, runtimeDigest, rollback: path.join(update, `legacy-rollback-${key}.tgz`), rollbackSha512: hash(rollbackBytes), rollbackVersion: rollbackMetadata.version, program: path.join(update, `legacy-bridge-${key}.mjs`), context: { ...context }, originals };
+    await fs.writeFile(plan.rollback, rollbackBytes, { mode: 0o600, flag: 'wx' });
+    await syncPrivateRecoveryFile(plan.rollback);
+    await fs.copyFile(options.programSource ?? path.join(path.dirname(fileURLToPath(import.meta.url)), 'watchdog.js'), plan.program);
+    await fs.chmod(plan.program, 0o700);
+    await syncPrivateRecoveryFile(plan.program);
+    await writeDurablePrivateUpdate(bridgePath(root), JSON.stringify(plan));
+    await (options.arm ?? armLegacyBridge)(plan);
+    // This marker transfers rollback responsibility, not update success. Public state remains
+    // RESTARTING until an authenticated, initialized migrated successor confirms it below.
+    await writeDurablePrivateUpdate(old.marker, JSON.stringify({ commandId: plan.commandId, version: plan.version, generation: `legacy-bridge:${randomUUID()}`, readyAt: new Date().toISOString() }));
+    const history = path.join(update, 'legacy-watchdog-history');
+    await ensureDurablePrivateDirectory(history);
+    for (const name of await fs.readdir(update))
+        if (/^watchdog-.*\.json$/.test(name))
+            await fs.rename(path.join(update, name), path.join(history, name));
+    const current = await inspectRuntime(root);
+    if (options.container ? current.state !== 'stopped' : current.state !== 'running' || current.generation !== plan.predecessor)
+        throw Error('The original legacy updater changed before service handoff');
+    if (!plan.ownerUserId) {
+        // Recovery is already frozen and independently armed before any network/account recovery.
+        const owner = await (options.ownerLookup ?? recoverAuthenticatedLegacyOwner)({ server: config.server, workstationId: config.workstationId, ...await readKeys(root), version: plan.rollbackVersion, update: { ...state, remoteForcePolicy: 'drain-only' } });
+        if (!owner.trim() || owner.length > 1024 || /[\u0000-\u001f\u007f]/.test(owner))
+            throw Error('Authenticated legacy owner is invalid');
+        await withWorkstationLock(root, 'operation', async () => {
+            const bytes = await snapshotMetadata(root, 'config.yml');
+            if (bytes.toString('base64') !== plan.originals['config.yml'])
+                throw Error('Legacy configuration changed during owner verification');
+            const configuration = yaml.load(bytes.toString());
+            await writeDurablePrivateUpdate(path.join(root, 'config.yml'), yaml.dump({ ...configuration, ownerUserId: owner }));
+            plan.ownerUserId = owner;
+            await writeDurablePrivateUpdate(bridgePath(root), JSON.stringify(plan));
+        });
+    }
+    return plan;
+}
+async function armLegacyBridge(plan) {
+    const managedLinux = plan.lifecycle === 'managed' && plan.context.platform === 'linux';
+    if (!managedLinux)
+        try {
+            const previous = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/legacy-bridge-armed.json'), 4096)).toString());
+            if (previous.commandId === plan.commandId && pidAlive(previous.pid) && (await processCommand(previous.pid))?.includes(plan.program))
+                return;
+        }
+        catch { }
+    const logPath = path.join(plan.root, 'update/legacy-bridge.log'), log = await fs.open(logPath, 'a', 0o600);
+    let owner;
+    try {
+        owner = await launchWatchdogProcess({ nodePath: plan.context.nodePath, program: plan.program, plan: bridgePath(plan.root), lifecycle: managedLinux ? 'managed' : plan.lifecycle === 'container' ? 'container' : 'foreground', logPath }, { platform: plan.context.platform, spawn: (exe, args, options) => spawn(exe, args, { ...options, stdio: ['ignore', log.fd, log.fd] }) });
+    }
+    finally {
+        await log.close();
+    }
+    const armed = path.join(plan.root, 'update/legacy-bridge-armed.json');
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        try {
+            const acknowledgement = JSON.parse((await readPrivateUpdateBytes(armed, 4096)).toString());
+            if (acknowledgement.commandId === plan.commandId && acknowledgement.pid === owner.pid)
+                return;
+        }
+        catch { }
+        if (!pidAlive(owner.pid))
+            break;
+        await wait(50);
+    }
+    throw Error('Independent legacy bridge watchdog did not acknowledge recovery ownership: ' + (await fs.readFile(logPath, 'utf8')).slice(-2000));
+}
+export async function resumeLegacyManagedBridge(root, startup, options = {}) {
+    const plan = await readLegacyBridge(root, startup);
+    if (plan?.lifecycle === 'managed')
+        await (options.arm ?? armLegacyBridge)(plan);
+}
+/** Container updates replace npm then exit directly, without invoking workstation install. */
+export async function prepareLegacyContainerBridge(root, context, options = {}) {
+    const existing = await readLegacyBridge(root);
+    if (existing) {
+        if (existing.lifecycle !== 'container')
+            throw Error('Container successor cannot adopt an OS service update');
+        await (options.arm ?? armLegacyBridge)(existing);
+        return existing;
+    }
+    try {
+        await fs.lstat(path.join(root, 'device.json'));
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let state;
+    try {
+        state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString());
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (state.phase !== 'RESTARTING')
+        return;
+    return prepareLegacyBridge(root, context, { ...options, container: true });
+}
+/** Keep the original command and drain-only policy visible through recovery completion. */
+export async function legacyBridgeUpdateSnapshot(root) {
+    try {
+        await fs.lstat(path.join(root, 'update/device-transaction.json'));
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let plan = await readLegacyBridge(root);
+    if (!plan)
+        try {
+            plan = bridgeSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/legacy-bridge-completed.json'), 8_388_608)).toString()));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    const state = await new UpdateStateStore(root).load();
+    return { ...(state?.commandId === plan.commandId ? state : { phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 }), remoteForcePolicy: 'drain-only' };
+}
+/** A failed container startup keeps its process alive until the independent bundle has restored
+ * both root metadata and npm. Only then may the external supervisor restart the process. */
+export async function recoverLegacyContainer(plan) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(plan.context.nodePath, [plan.program, bridgePath(plan.root), '--rollback-now'], { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', code => code === 0 ? resolve() : reject(Error(`Independent container rollback failed (${code})`)));
+    });
+}
+export async function legacyBridgeReady(root, startup, generation) {
+    const plan = await readLegacyBridge(root, startup);
+    if (!plan)
+        return true;
+    const inspection = await inspectDeviceRuntime(root);
+    const registration = inspection.registrations.find(entry => entry.workstationId === plan.workstationId && entry.ownerUserId === plan.ownerUserId && normalizeWorkstationServer(entry.server) === normalizeWorkstationServer(plan.server));
+    return inspection.runtime.generation === generation && generation !== plan.predecessor && !!registration && registration.connection === 'online' && registration.identityState === 'ready';
+}
+export async function completeLegacyBridge(root, startup, generation) {
+    await withPrivateLock(path.join(root, 'update/legacy-bridge-recovery'), async () => {
+        const plan = await readLegacyBridge(root, startup);
+        if (!plan)
+            return;
+        if (!await legacyBridgeReady(root, startup, generation))
+            throw Error('Original migrated successor readiness changed before recovery completion');
+        await writeDurablePrivateUpdate(path.join(root, 'update/legacy-bridge-ready.json'), JSON.stringify({ commandId: plan.commandId, generation, runtimeDigest: startup.runtimeDigest }));
+        await new UpdateStateStore(root).save({ phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 });
+        // The daemon can finish recovery after an OS reboot even when the original copied watcher
+        // no longer exists. This uses the same lock as the watcher's last rollback decision.
+        await fs.rename(bridgePath(root), path.join(root, 'update/legacy-bridge-completed.json'));
+    });
+}
+export async function releaseLegacyBridge(root, startup, generation, release) {
+    if (!await legacyBridgeReady(root, startup, generation))
+        return false;
+    await release(() => completeLegacyBridge(root, startup, generation));
+    return true;
+}
+export async function runLegacyBridge(plan, deps) {
+    await writeDurablePrivateUpdate(path.join(plan.root, 'update/legacy-bridge-armed.json'), JSON.stringify({ commandId: plan.commandId, pid: process.pid }));
+    const now = deps.now ?? Date.now, pause = deps.wait ?? wait, deadline = now() + (deps.timeoutMs ?? 120_000);
+    while (now() < deadline) {
+        if (!await readLegacyBridge(plan.root))
+            return;
+        if (await confirmedBridgeReady(plan)) {
+            await withPrivateLock(path.join(plan.root, 'update/legacy-bridge-recovery'), async () => { if (await readLegacyBridge(plan.root) && await confirmedBridgeReady(plan))
+                await finalizeConfirmedBridge(plan); });
+            return;
+        }
+        await pause(250);
+    }
+    await withPrivateLock(path.join(plan.root, 'update/legacy-bridge-recovery'), async () => {
+        if (!await readLegacyBridge(plan.root))
+            return;
+        // Readiness can arrive during the final sleep, or before a rollback-now recovery invocation.
+        if (await confirmedBridgeReady(plan)) {
+            await finalizeConfirmedBridge(plan);
+            return;
+        }
+        // Stop only the daemon/service; keeper namespaces and their journals remain untouched.
+        await deps.stop();
+        if (hash(await fs.readFile(plan.rollback)) !== plan.rollbackSha512)
+            throw Error('Frozen legacy rollback archive changed');
+        for (const name of ['device.json', 'legacy-migration.json', 'registrations'])
+            await fs.rm(path.join(plan.root, name), { recursive: true, force: true });
+        for (const name of metadata) {
+            if (plan.originals[name])
+                await writeDurablePrivateUpdate(path.join(plan.root, name), Buffer.from(plan.originals[name], 'base64').toString());
+            else
+                await fs.rm(path.join(plan.root, name), { force: true });
+        }
+        await deps.install(plan.rollback);
+        await new UpdateStateStore(plan.root).save({ phase: 'ROLLED_BACK', commandId: plan.commandId, version: plan.version, error: 'Automatic legacy migration did not confirm authenticated successor readiness; restored the original CLI and registration' });
+        await fs.rename(bridgePath(plan.root), path.join(plan.root, 'update/legacy-bridge-rolled-back.json'));
+        await deps.restart();
+    });
+}