@aglit-ai/cli 0.1.1 → 0.1.4

package/src/updates.cjs

@@ -0,0 +1,530 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { createRequire } = require('node:module');
+const { spawn, spawnSync, execFileSync } = require('node:child_process');
+const installation = require('./installation.cjs');
+const { control } = require('./control.cjs');
+const ownPackage = path.resolve(__dirname, '..');
+const identity = JSON.parse(fs.readFileSync(path.join(ownPackage, 'package.json'), 'utf8'));
+const channels = ['latest', 'canary', 'embedded'];
+const registry = 'https://registry.npmjs.org/';
+const stateFile = path.join(installation.root, 'cli-installation.json');
+const settingsFile = path.join(installation.root, 'cli-update-settings.json');
+const need = (value, message) => { if (!value) throw Error(message); };
+const sha = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+function compareVersions(left, right) {
+  const parse = value => {
+    need(typeof value === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?$/.test(value), 'Invalid npm version');
+    const [core, ...suffix] = value.split('-'); const numbers = core.split('.').map(Number);
+    need(numbers.every(Number.isSafeInteger), 'Invalid npm version'); return { numbers, suffix: suffix.join('-') };
+  };
+  const a = parse(left), b = parse(right);
+  for (let index = 0; index < 3; index++) if (a.numbers[index] !== b.numbers[index]) return Math.sign(a.numbers[index] - b.numbers[index]);
+  if (!a.suffix || !b.suffix) return a.suffix === b.suffix ? 0 : a.suffix ? -1 : 1;
+  const x = a.suffix.split('.'), y = b.suffix.split('.');
+  for (let index = 0; index < Math.max(x.length, y.length); index++) {
+    if (x[index] === y[index]) continue;
+    if (x[index] === undefined || y[index] === undefined) return x[index] === undefined ? -1 : 1;
+    const xn = /^\d+$/.test(x[index]), yn = /^\d+$/.test(y[index]);
+    if (xn && yn) return BigInt(x[index]) > BigInt(y[index]) ? 1 : -1;
+    if (xn !== yn) return xn ? -1 : 1;
+    return x[index] > y[index] ? 1 : -1;
+  }
+  return 0;
+}
+function privateJson(file) {
+  installation.canonical(file); const stat = fs.statSync(file);
+  need(stat.isFile() && stat.nlink === 1 && stat.size <= 65536 &&
+    (process.platform === 'win32' || stat.uid === process.getuid() && !(stat.mode & 0o077)), 'Private updater record required');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function writeJson(file, value) {
+  const stage = file + '.' + crypto.randomUUID();
+  fs.writeFileSync(stage, JSON.stringify(value) + '\n', {flag: 'wx', mode: 0o600});
+  try { fs.renameSync(stage, file); } finally { if (fs.existsSync(stage)) fs.unlinkSync(stage); }
+}
+function packageDirectory(prefix) { return path.join(prefix, 'node_modules', '@aglit-ai', 'cli'); }
+function pointer(prefix, manifest, integrity = null) {
+  const entry = path.join(packageDirectory(prefix), 'bin/aglit.cjs'); installation.canonical(entry);
+  return { directory: prefix, version: manifest.version, integrity, sha256: sha(fs.readFileSync(entry)) };
+}
+function validatePointer(value) {
+  need(value && Object.keys(value).sort().join(',') === 'directory,integrity,sha256,version' &&
+    value.directory.startsWith(path.join(installation.root, 'cli') + path.sep) && /^[a-f0-9]{64}$/.test(value.sha256) &&
+    (value.integrity === null || /^sha512-[A-Za-z0-9+/]{86}==$/.test(value.integrity)), 'Invalid private CLI installation');
+  compareVersions(value.version, value.version);
+  const entry = path.join(packageDirectory(value.directory), 'bin/aglit.cjs'); installation.canonical(entry);
+  need(sha(fs.readFileSync(entry)) === value.sha256, 'Installed CLI entry changed'); return value;
+}
+function settings() {
+  if (!fs.existsSync(settingsFile)) return {channel: 'latest', automatic: true, revision: 0};
+  const value = privateJson(settingsFile);
+  need(value.kind === 'aglit-cli-update-settings-v1' && Object.keys(value).sort().join(',') === 'automatic,channel,kind,revision' && channels.includes(value.channel) &&
+    typeof value.automatic === 'boolean' && Number.isSafeInteger(value.revision) && value.revision >= 0, 'Invalid CLI update settings');
+  return {channel: value.channel, automatic: value.automatic, revision: value.revision};
+}
+function saveSettings(patch) {
+  const unlock = lock(path.join(installation.root, 'updater-settings.lock')); need(unlock, 'Update settings are busy; retry the command');
+  try { const value = {...settings(), ...patch}; writeJson(settingsFile, {kind: 'aglit-cli-update-settings-v1', ...value, revision: value.revision + 1}); }
+  finally { unlock(); }
+}
+function savePointer(value) { writeJson(stateFile, {kind: 'aglit-cli-installation-v1', current: value.current, previous: value.previous}); }
+function state() {
+  const policy = settings();
+  if (!fs.existsSync(stateFile)) return {kind: 'aglit-cli-installation-v1', ...policy, current: null, previous: null};
+  installation.privateRoot(); const value = privateJson(stateFile);
+  need(value && Object.keys(value).sort().join(',') === 'current,kind,previous' && value.kind === 'aglit-cli-installation-v1', 'Invalid private CLI state');
+  if (value.current) validatePointer(value.current);
+  if (value.previous) validatePointer(value.previous);
+  return {...value, ...policy};
+}
+function resolvePackage(name, from) {
+  const requireFrom = createRequire(path.join(from, 'package.json')); let entry;
+  try { return path.dirname(requireFrom.resolve(name + '/package.json')); } catch (error) { if (!['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) throw error; }
+  entry = requireFrom.resolve(name);
+  for (let directory = path.dirname(entry), count = 0; count < 20; directory = path.dirname(directory), count++) {
+    const file = path.join(directory, 'package.json');
+    if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file)).name === name) return directory;
+    if (path.dirname(directory) === directory) break;
+  }
+  throw Error('Installed CLI dependency is unavailable');
+}
+function copyPackage(source, target, cli = false, ancestors = []) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(source, 'package.json')));
+  const key = manifest.name + '@' + manifest.version;
+  need(!ancestors.includes(key) && ancestors.length < 16, 'CLI dependency graph cannot be copied safely');
+  fs.mkdirSync(target, {recursive: true, mode: 0o700});
+  const names = cli ? ['package.json', 'README.md', 'bin', 'src'] : fs.readdirSync(source).filter(name => name !== 'node_modules');
+  for (const name of names) fs.cpSync(path.join(source, name), path.join(target, name), {recursive: true, dereference: false, errorOnExist: true, force: false});
+  for (const name of Object.keys(manifest.dependencies || {})) {
+    need(/^(@[a-z0-9-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name), 'Invalid CLI dependency');
+    copyPackage(resolvePackage(name, source), path.join(target, 'node_modules', name), false, [...ancestors, key]);
+  }
+}
+function writeStartup() {
+  const launcher = path.join(installation.root, 'cli-launcher.cjs');
+  const source = fs.readFileSync(path.join(__dirname, 'launcher.cjs'));
+  const staged = launcher + '.' + crypto.randomUUID(); fs.writeFileSync(staged, source, {flag: 'wx', mode: 0o600}); fs.renameSync(staged, launcher);
+  writeJson(path.join(installation.root, 'cli-startup.json'), {kind: 'aglit-computer-use-cli-startup-v1', nodeExecutable: fs.realpathSync(process.execPath), launcher});
+}
+function initialize(channel) {
+  need(channel === undefined || channels.includes(channel), 'Invalid update channel');
+  installation.readInstallation(); let value = state();
+  if (channel && channel !== value.channel) { saveSettings({channel}); value = state(); }
+  const updating = path.join(installation.root, 'updating.lock');
+  if (fs.existsSync(updating)) { const owner = privateJson(updating); if (owner.pid !== process.pid && live(owner.pid)) return value; }
+  if (!value.current || compareVersions(identity.version, value.current.version) > 0) {
+    const parent = path.join(installation.root, 'cli'); fs.mkdirSync(parent, {recursive: true, mode: 0o700});
+    const prefix = path.join(parent, identity.version + '-' + crypto.randomUUID());
+    copyPackage(ownPackage, packageDirectory(prefix), true);
+    const current = pointer(prefix, identity); value = {...value, previous: value.current, current}; savePointer(value);
+  }
+  writeStartup(); return value;
+}
+function delegate(entry) {
+  if (!fs.existsSync(stateFile)) return null;
+  const current = state().current;
+  if (!current || compareVersions(current.version, identity.version) <= 0) return null;
+  const target = path.join(packageDirectory(current.directory), 'bin/aglit.cjs');
+  if (fs.realpathSync(entry) === fs.realpathSync(target)) return null;
+  const result = spawnSync(process.execPath, [target, ...process.argv.slice(2)], {stdio: 'inherit', windowsHide: true});
+  if (result.error) throw Error('Updated CLI could not start'); return result.status ?? 1;
+}
+async function manifest(name, selector) {
+  need(/^@aglit-ai\/(?:cli|desktop-runtime-(?:darwin-arm64|win32-x64)(?:-part-\d{2})?)$/.test(name), 'Unexpected npm package');
+  if (!channels.includes(selector) && !/^runtime-(?:darwin-arm64|win32-x64)-(?:latest|canary|embedded)$/.test(selector)) compareVersions(selector, selector);
+  const url = new URL(encodeURIComponent(name) + '/' + encodeURIComponent(selector), registry);
+  const response = await fetch(url, {redirect: 'error', signal: AbortSignal.timeout(30000)});
+  if (response.status === 404) {
+    if (/^runtime-(?:darwin-arm64|win32-x64)-/.test(selector)) throw Error('No published signed Desktop runtime is available for ' + process.platform + ' ' + process.arch + ' in npm channel ' + selector);
+    if (name === '@aglit-ai/cli') throw Error('The Aglit CLI npm release ' + selector + ' has not been published yet');
+    if (name === runtimePackage()) throw Error('No published signed Desktop runtime is available for ' + process.platform + ' ' + process.arch + ' in npm channel/version ' + selector);
+    throw Error('A required verified Desktop runtime part is not published yet');
+  }
+  need(response.ok && response.body, 'Published npm release is unavailable');
+  let size = 0; const chunks = [];
+  for await (const chunk of response.body) { size += chunk.length; need(size <= 2 * 1024 ** 2, 'npm metadata is too large'); chunks.push(chunk); }
+  const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  need(value.name === name && value._npmUser?.name === 'aglit-ai-dev' && value._npmUser?.email === 'developers@aglit.ai' &&
+    /^sha512-[A-Za-z0-9+/]{86}==$/.test(value.dist?.integrity), 'Company npm publisher and integrity required');
+  compareVersions(value.version, value.version);
+  const tarball = new URL(value.dist.tarball); need(tarball.protocol === 'https:' && tarball.hostname === 'registry.npmjs.org' && !tarball.username && !tarball.password, 'Untrusted npm archive');
+  return value;
+}
+function runtimePackage() {
+  need(process.platform === 'darwin' && process.arch === 'arm64' || process.platform === 'win32' && process.arch === 'x64', 'Published runtime does not support this platform');
+  return '@aglit-ai/desktop-runtime-' + process.platform + '-' + process.arch;
+}
+function runtimeVersion(value) {
+  if (value.name === runtimePackage()) { compareVersions(value.version, value.version); return value.version; }
+  const expected = process.platform + '-' + process.arch;
+  const match = /^(\d+\.\d+\.\d+)-runtime\.(darwin-arm64|win32-x64)$/.exec(value.version);
+  need(value.name === '@aglit-ai/cli' && match && match[2] === expected, 'Runtime npm version does not match this platform');
+  return match[1];
+}
+function runtimeTag(channel) { runtimePackage(); need(channels.includes(channel), 'Invalid update channel'); return 'runtime-' + process.platform + '-' + process.arch + '-' + channel; }
+async function releaseManifests(cli, offeredRuntime) {
+  const result = [{...cli, installName: '@aglit-ai/cli'}], name = runtimePackage();
+  const pin = cli.optionalDependencies?.[name];
+  let runtime = offeredRuntime;
+  if (!runtime) {
+    need(typeof pin === 'string', 'Published CLI has no runtime for this platform');
+    const alias = /^npm:@aglit-ai\/cli@(\d+\.\d+\.\d+-runtime\.(?:darwin-arm64|win32-x64))$/.exec(pin);
+    if (alias) runtime = await manifest('@aglit-ai/cli', alias[1]);
+    else { need(/^\d+\.\d+\.\d+$/.test(pin), 'Runtime bootstrap pin differs'); runtime = await manifest(name, pin); }
+  }
+  const nativeVersion = runtimeVersion(runtime), aliased = runtime.name === '@aglit-ai/cli';
+  result.push({...runtime, installName: name});
+  const entries = Object.entries(runtime.dependencies || {});
+  need(entries.length > 0 && entries.length <= 64, 'Runtime part dependencies are unavailable');
+  for (let index = 0; index < entries.length; index++) {
+    const installName = name + '-part-' + String(index).padStart(2, '0');
+    const version = aliased ? runtime.version + '.part-' + String(index).padStart(2, '0') : nativeVersion;
+    need(runtime.dependencies[installName] === (aliased ? 'npm:@aglit-ai/cli@' : '') + version, 'Runtime part alias or pin differs');
+    const part = await manifest(aliased ? '@aglit-ai/cli' : installName, version);
+    need(part.version === version && !Object.keys(part.dependencies || {}).length, 'Runtime part package differs');
+    result.push({...part, installName});
+  }
+  return result;
+}
+function npmEntry() {
+  const node = fs.realpathSync(process.execPath), directory = path.dirname(node);
+  const candidates = [path.join(directory, 'node_modules/npm/bin/npm-cli.js'), path.resolve(directory, '../lib/node_modules/npm/bin/npm-cli.js')];
+  for (const file of candidates) if (fs.existsSync(file)) return fs.realpathSync(file);
+  const nearby = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  if (process.platform !== 'win32' && fs.existsSync(nearby)) return fs.realpathSync(nearby);
+  throw Error('npm must be installed with Node.js to update Aglit');
+}
+async function stage(cli, parent, offeredRuntime, cliOnly = false) {
+  need(cli.name === '@aglit-ai/cli' && cli.bin?.aglit === 'bin/aglit.cjs' && !/-runtime\.(?:darwin-arm64|win32-x64)/.test(cli.version), 'Selected npm version is not the Aglit CLI launcher');
+  const manifests = cliOnly ? [{...cli, installName: '@aglit-ai/cli'}] : await releaseManifests(cli, offeredRuntime);
+  const runtime = manifests[1];
+  const directory = fs.mkdtempSync(path.join(parent, 'aglit-cli-')); fs.chmodSync(directory, 0o700);
+  fs.writeFileSync(path.join(directory, 'package.json'), '{"private":true}\n', {mode: 0o600});
+  const config = path.join(directory, 'npmrc'); fs.writeFileSync(config, 'registry=' + registry + '\n@aglit-ai:registry=' + registry + '\n', {mode: 0o600});
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^npm_config_|^node_auth_token$|^npm_token$|^node_options$|^node_path$/i.test(key)));
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [npmEntry(), 'install', '--ignore-scripts', '--omit=optional', '--no-audit', '--no-fund', '--save-exact', '--package-lock=true', '--registry=' + registry,
+      '--userconfig=' + config, '--globalconfig=' + (process.platform === 'win32' ? 'NUL' : '/dev/null'), cli.name + '@' + cli.version, ...(runtime ? [runtime.installName + '@' + (runtime.name === runtime.installName ? runtime.version : 'npm:' + runtime.name + '@' + runtime.version)] : [])], {cwd: directory, env, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore']});
+    const timeout = setTimeout(() => { child.kill(); reject(Error('npm update download timed out; current runtime preserved')); }, 30 * 60000);
+    const cancellation = setInterval(() => { if (fs.existsSync(path.join(installation.root, 'updater-stop.json'))) child.kill(); }, 1000);
+    child.on('error', () => { clearInterval(cancellation); clearTimeout(timeout); reject(Error('npm update could not start')); });
+    child.on('exit', code => { clearInterval(cancellation); clearTimeout(timeout); code === 0 ? resolve() : reject(Error('npm update download failed; current runtime preserved')); });
+  });
+  validateInstalledGraph(directory, manifests);
+  fs.unlinkSync(config); return {directory, packageDirectory: packageDirectory(directory), runtimeDirectory: runtime ? path.join(directory, 'node_modules', runtime.installName) : null, cli};
+}
+function validateInstalledGraph(directory, manifests) {
+  const lock = JSON.parse(fs.readFileSync(path.join(directory, 'package-lock.json'), 'utf8'));
+  for (const expected of manifests) {
+    const entry = lock.packages?.['node_modules/' + expected.installName];
+    need(entry?.version === expected.version && entry.integrity === expected.dist.integrity, 'Downloaded npm package integrity differs');
+    const installed = JSON.parse(fs.readFileSync(path.join(directory, 'node_modules', expected.installName, 'package.json')));
+    need(installed.name === expected.name && installed.version === expected.version, 'Installed npm package identity differs');
+  }
+  return true;
+}
+async function bootstrap(channel) { const selected = channel || state().channel; need(channels.includes(selected), 'Invalid update channel'); return {...await stage(await manifest('@aglit-ai/cli', selected), os.tmpdir()), channel: selected}; }
+function adoptBootstrap(value) {
+  const parent = path.join(installation.root, 'cli'); fs.mkdirSync(parent, {recursive: true, mode: 0o700});
+  const target = path.join(parent, value.cli.version + '-' + crypto.randomUUID());
+  try { fs.renameSync(value.directory, target); } catch (error) { if (error.code !== 'EXDEV') throw error; fs.cpSync(value.directory, target, {recursive: true}); fs.rmSync(value.directory, {recursive: true}); }
+  const prior = state(); saveSettings({channel: value.channel}); savePointer({...prior, current: pointer(target, value.cli, value.cli.dist.integrity), previous: prior.current}); writeStartup();
+}
+function live(pid) { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; throw error; } }
+function lock(file) {
+  if (fs.existsSync(file)) {
+    const value = privateJson(file); need(Number.isSafeInteger(value.pid) && value.pid > 0, 'Invalid updater lock');
+    if (live(value.pid)) return null; fs.unlinkSync(file);
+  }
+  const nonce = crypto.randomUUID();
+  try { fs.writeFileSync(file, JSON.stringify({pid: process.pid, nonce}) + '\n', {flag: 'wx', mode: 0o600}); }
+  catch (error) { if (error.code === 'EEXIST') return null; throw error; }
+  return () => { if (fs.existsSync(file) && privateJson(file).nonce === nonce) fs.unlinkSync(file); };
+}
+async function offers(selected) {
+  const cli = await manifest('@aglit-ai/cli', selected);
+  need(cli.bin?.aglit === 'bin/aglit.cjs' && !/-runtime\.(?:darwin-arm64|win32-x64)/.test(cli.version), 'Selected channel does not identify the CLI launcher');
+  const runtime = await manifest('@aglit-ai/cli', runtimeTag(selected));
+  runtimeVersion(runtime);
+  return {cli, runtime};
+}
+async function status() {
+  const value = state(), latest = await offers(value.channel);
+  const version = value.current?.version || identity.version;
+  const installedRuntimeVersion = fs.existsSync(path.join(installation.root, 'installation.json')) ? installation.readInstallation().version : null;
+  return {channel: value.channel, automatic: value.automatic, version, availableVersion: latest.cli.version,
+    runtimeVersion: installedRuntimeVersion, availableRuntimeVersion: runtimeVersion(latest.runtime),
+    updateAvailable: compareVersions(latest.cli.version, version) > 0 || installedRuntimeVersion !== null && compareVersions(runtimeVersion(latest.runtime), installedRuntimeVersion) > 0};
+}
+function runtimeStopped(installed) {
+  installation.canonical(installed.executable);
+  if (process.platform === 'darwin') {
+    const output = execFileSync('/bin/ps', ['-axo', 'pid=,uid=,comm='], {encoding: 'utf8', timeout: 15000, maxBuffer: 8 * 1024 ** 2});
+    const lines = output.trim().split('\n'); need(lines.length > 1, 'Native process inventory unavailable');
+    return !lines.some(line => {
+      const found = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line); need(found, 'Native process inventory is incomplete');
+      return found[3].trim() === installed.executable;
+    });
+  }
+  if (process.platform === 'win32') {
+    const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+    const script = '$ErrorActionPreference="Stop";$rows=@(Get-CimInstance Win32_Process -Filter "Name=\'Aglit AI.exe\'");$unknown=@($rows|Where-Object{![bool]$_.ExecutablePath});$matches=@($rows|Where-Object{$_.ExecutablePath -eq $env:AGLIT_EXPECTED_RUNTIME});@{stopped=($unknown.Count -eq 0 -and $matches.Count -eq 0)}|ConvertTo-Json -Compress';
+    const output = execFileSync(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], {encoding: 'utf8', timeout: 15000, maxBuffer: 65536, windowsHide: true, env: {...process.env, AGLIT_EXPECTED_RUNTIME: installed.executable}});
+    return JSON.parse(output).stopped === true;
+  }
+  throw Error('Native process ownership proof unavailable');
+}
+function rememberStatus(value) {
+  need(value?.running && Number.isSafeInteger(value.pid) && typeof value.deviceId === 'string' && value.deviceId.length > 0 &&
+    (value.email === null || typeof value.email === 'string') && typeof value.enabled === 'boolean', 'Current runtime identity is incomplete');
+  const saved = {kind: 'aglit-cli-runtime-status-v1', version: value.version, deviceId: value.deviceId, email: value.email,
+    enabled: value.enabled, provider: value.provider, mode: value.mode, pid: value.pid};
+  writeJson(path.join(installation.root, 'last-runtime-status.json'), saved); return saved;
+}
+function offlineStatus(installed) {
+  const previous = path.join(installation.root, 'last-runtime-status.json');
+  if (fs.existsSync(previous)) { const value = privateJson(previous); need(value.kind === 'aglit-cli-runtime-status-v1' && value.version === installed.version, 'Previous runtime identity is unavailable'); return value; }
+  // A never-enrolled legacy installation can migrate without reading any auth
+  // files. Existing registered profiles require an authenticated prior status.
+  const file = path.join(installation.profile, 'system-settings.json');
+  const value = privateJson(file).settings;
+  need(value && value.enableAnywhereAccess === false && typeof value.remoteAccessDeviceId === 'string' && !value.providerSettings?.chatProvider,
+    'Start the existing Desktop and run aglit status, then quit it normally before the first npm update');
+  return {deviceId: value.remoteAccessDeviceId, email: null, enabled: false, provider: null, mode: 'headless'};
+}
+function continuity(value, original, runtime) {
+  return value?.running && value.version === runtime.version && value.deviceId === original.deviceId && value.email === original.email &&
+    value.enabled === original.enabled && value.provider === original.provider;
+}
+function activationHold(runtime, original) {
+  return {kind: 'aglit-computer-use-update-activation-v1', root: installation.root, profile: installation.profile,
+    ...runtime, deviceId: original.deviceId, email: original.email, enabled: original.enabled, provider: original.provider};
+}
+function removeHold(runtime) {
+  const file = path.join(installation.root, 'update-activation.json'); if (!fs.existsSync(file)) return;
+  const hold = privateJson(file);
+  need(hold.kind === 'aglit-computer-use-update-activation-v1' && hold.executable === runtime.executable && hold.version === runtime.version &&
+    hold.sha256 === runtime.sha256 && hold.sourceCommit === runtime.sourceCommit && hold.root === installation.root && hold.profile === installation.profile, 'Candidate activation hold changed');
+  fs.unlinkSync(file);
+}
+async function acceptCandidate(config, pid, version) {
+  // The native contract makes this action idempotent for one running occurrence.
+  // Retry only this explicit acknowledgement, never general mutation commands.
+  let result;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try { result = await control(config, 'update-accept'); break; }
+    catch (error) { if (attempt === 1) throw error; await delay(250); }
+  }
+  need(result?.accepted === true && result.pid === pid && result.version === version, 'Updated runtime did not accept its continuity hold');
+  return result;
+}
+async function recoverActivation(ownedLock = false) {
+  const file = path.join(installation.root, 'update-transaction.json'); if (!fs.existsSync(file)) return {recovered: false};
+  const unlock = ownedLock ? () => {} : lock(path.join(installation.root, 'updating.lock')); if (!unlock) return {recovered: false, updating: true};
+  try {
+    const tx = privateJson(file), current = installation.readInstallation();
+    need(tx.kind === 'aglit-cli-activation-recovery-v1' && tx.previous.root === installation.root && tx.previous.profile === installation.profile &&
+      tx.runtime.executable.startsWith(path.join(installation.root, 'runtimes') + path.sep), 'Interrupted update recovery binding differs');
+    validatePointer(tx.candidate); if (tx.previousCli.current) validatePointer(tx.previousCli.current);
+    const holdFile = path.join(installation.root, 'update-activation.json');
+    if (current.sha256 === tx.runtime.sha256 && current.executable === tx.runtime.executable) {
+      const policy = settings();
+      const cancelled = tx.policy && (policy.channel !== tx.policy.channel || policy.revision !== tx.policy.revision && !policy.automatic);
+      let launched = null, measured = null;
+      if (!cancelled && runtimeStopped(current)) { writeJson(holdFile, activationHold(tx.runtime, tx.original)); launched = installation.start(); }
+      const deadline = Date.now() + 120000, config = path.join(installation.profile, 'ipc/sdk-ipc.json');
+      if (!cancelled) do {
+        try { const value = await control(config, 'status'); if (continuity(value, tx.original, tx.runtime) && (!launched || value.pid === launched.pid)) { measured = value; break; } }
+        catch { /* Account/provider restore may still be in flight. */ }
+        await delay(1000);
+      } while (Date.now() < deadline && !runtimeStopped(current));
+      if (measured) {
+        if (fs.existsSync(holdFile)) { await acceptCandidate(config, measured.pid, tx.runtime.version); }
+        fs.unlinkSync(file); const pending = path.join(installation.root, 'pending-update.json'); if (fs.existsSync(pending)) fs.unlinkSync(pending);
+        return {recovered: true, accepted: true, runtimePid: measured.pid};
+      }
+      if (!runtimeStopped(current)) {
+        const result = await control(config, 'update-prepare'); need(result.quitting && Number.isSafeInteger(result.pid), 'Candidate cannot safely retire for recovery');
+        const deadline = Date.now() + 30000; while (live(result.pid) && Date.now() < deadline) await delay(250);
+      }
+      need(runtimeStopped(current), 'Candidate process remains active; recovery preserved');
+    } else {
+      need(current.sha256 === tx.previous.sha256 && current.executable === tx.previous.executable, 'Installation changed outside interrupted update');
+      if (!fs.existsSync(holdFile)) {
+        if (tx.retirementRequested) {
+          if (!runtimeStopped(tx.previous)) {
+            try { await control(path.join(installation.profile, 'ipc/sdk-ipc.json'), 'status'); }
+            catch {
+              const deadline = Date.now() + 30000; while (!runtimeStopped(tx.previous) && Date.now() < deadline) await delay(500);
+              need(runtimeStopped(tx.previous), 'Previous runtime is still retiring; profile preserved');
+            }
+          }
+          if (runtimeStopped(tx.previous)) installation.start();
+        }
+        fs.unlinkSync(file); return {recovered: true, activated: false};
+      }
+      need(runtimeStopped({...current, ...tx.runtime}), 'Interrupted candidate process is still active');
+    }
+    removeHold(tx.runtime);
+    writeJson(path.join(installation.root, 'installation.json'), tx.previous); savePointer(tx.previousCli); writeStartup();
+    if (runtimeStopped(tx.previous)) installation.start(); fs.unlinkSync(file);
+    return {recovered: true, rolledBack: true};
+  } finally { unlock(); }
+}
+async function update({check = false, channel} = {}) {
+  need(channel === undefined || channels.includes(channel), 'Update channel must be latest, canary or embedded');
+  if (check) {
+    const current = state(), latest = await offers(channel || current.channel);
+    const installed = fs.existsSync(path.join(installation.root, 'installation.json')) ? installation.readInstallation() : null;
+    return {channel: channel || current.channel, version: current.current?.version || identity.version, availableVersion: latest.cli.version,
+      runtimeVersion: installed?.version || null, availableRuntimeVersion: runtimeVersion(latest.runtime),
+      updateAvailable: compareVersions(latest.cli.version, current.current?.version || identity.version) > 0 || Boolean(installed && compareVersions(runtimeVersion(latest.runtime), installed.version) > 0), automatic: current.automatic};
+  }
+  installation.readInstallation();
+  const unlock = lock(path.join(installation.root, 'updating.lock')); if (!unlock) return {updated: false, updating: true};
+  try {
+    await recoverActivation(true);
+    initialize(channel);
+    const value = state(), policy = settings(), installed = installation.readInstallation();
+    const selected = value.channel, latest = await offers(selected), currentVersion = value.current?.version || identity.version;
+    const cancelled = () => {
+      const current = settings();
+      need(!fs.existsSync(path.join(installation.root, 'updater-stop.json')) && current.channel === selected &&
+        !(current.revision !== policy.revision && !current.automatic), 'Update cancelled before activation; current profile preserved');
+    };
+    cancelled();
+    const cliAvailable = compareVersions(latest.cli.version, currentVersion) > 0;
+    const runtimeAvailable = compareVersions(runtimeVersion(latest.runtime), installed.version) > 0;
+    if (!cliAvailable && !runtimeAvailable) return {updated: false, version: currentVersion, runtimeVersion: installed.version};
+    const cli = cliAvailable || latest.cli.version === currentVersion ? latest.cli : await manifest('@aglit-ai/cli', currentVersion);
+    if (!runtimeAvailable) {
+      const pending = await stage(cli, path.join(installation.root, 'cli'), null, true); cancelled();
+      savePointer({...state(), current: pointer(pending.directory, cli, cli.dist.integrity), previous: state().current}); writeStartup();
+      return {updated: true, version: cli.version, runtimeUpdated: false};
+    }
+    const pendingFile = path.join(installation.root, 'pending-update.json');
+    let prepared = fs.existsSync(pendingFile) ? privateJson(pendingFile) : null;
+    if (prepared && (prepared.kind !== 'aglit-cli-pending-update-v1' || prepared.cliVersion !== cli.version || prepared.runtimeVersion !== runtimeVersion(latest.runtime) || prepared.previousArchive !== installed.sha256)) prepared = null;
+    if (!prepared) {
+      const pending = await stage(cli, path.join(installation.root, 'cli'), latest.runtime); cancelled();
+      const candidate = pointer(pending.directory, cli, cli.dist.integrity);
+      const bundle = installation.embeddedRelease(process.platform === 'darwin' ? 'mac' : 'win', pending.packageDirectory, pending.runtimeDirectory);
+      need(bundle && compareVersions(bundle.release.version, installed.version) > 0, 'Desktop update would not advance this computer');
+      const generations = path.join(installation.root, 'runtimes'); fs.mkdirSync(generations, {recursive: true, mode: 0o700});
+      const generation = fs.mkdtempSync(path.join(generations, bundle.release.version + '-')); fs.chmodSync(generation, 0o700);
+      const runtime = await installation.stageRuntime(bundle, path.join(generation, 'runtime')); cancelled();
+      prepared = {kind: 'aglit-cli-pending-update-v1', cliVersion: cli.version, runtimeVersion: runtime.version, previousArchive: installed.sha256, candidate, runtime};
+      writeJson(pendingFile, prepared);
+    }
+    const {candidate, runtime} = prepared; validatePointer(candidate);
+    need(runtime.executable.startsWith(path.join(installation.root, 'runtimes') + path.sep), 'Invalid staged Desktop generation');
+    installation.canonical(runtime.executable); installation.verifyRuntime(runtime.executable, runtime); cancelled();
+    const config = path.join(installation.profile, 'ipc/sdk-ipc.json');
+    let original, retiring = null;
+    try { original = rememberStatus(await control(config, 'status')); }
+    catch { need(runtimeStopped(installed), 'Desktop is running but unavailable; stop it normally before updating'); original = offlineStatus(installed); }
+    if (original.enabled) need(original.email, 'Restore the current Desktop sign-in before applying an update');
+    const transaction = path.join(installation.root, 'update-transaction.json');
+    const activation = path.join(installation.root, 'update-activation.json');
+    const before = {kind: 'aglit-cli-activation-recovery-v1', previous: installed, previousCli: {current: state().current, previous: state().previous}, candidate, runtime, original, policy: {channel: selected, revision: policy.revision, automatic: policy.automatic}};
+    writeJson(transaction, before);
+    let launched = null, switched = false, oldRetired = false, accepted = false;
+    try {
+      cancelled();
+      if (!runtimeStopped(installed)) {
+        let ready; try { ready = await control(config, 'update-status'); }
+        catch { return {updated: false, deferred: true, reason: 'legacy-runtime-needs-normal-exit', availableVersion: cli.version}; }
+        if (!ready?.supported || ready.busy) return {updated: false, deferred: true, reason: 'active-work', availableVersion: cli.version};
+        cancelled(); writeJson(transaction, {...before, retirementRequested: true}); retiring = await control(config, 'update-prepare');
+        if (!retiring?.quitting || retiring.busy) return {updated: false, deferred: true, reason: 'active-work', availableVersion: cli.version};
+        need(Number.isSafeInteger(retiring.pid) && retiring.pid > 0 && retiring.pid === original.pid, 'Runtime retirement acknowledgement required');
+        const deadline = Date.now() + 30000;
+        while (live(retiring.pid) && Date.now() < deadline) await delay(250);
+        need(!live(retiring.pid), 'Runtime is still closing; update remains staged');
+      }
+      oldRetired = true; cancelled();
+      need(runtimeStopped(installed), 'A legacy Desktop started during activation; update remains staged');
+      const authoritative = installation.readInstallation(); need(authoritative.sha256 === installed.sha256 && authoritative.executable === installed.executable, 'Installation changed during update');
+      writeJson(path.join(installation.root, 'installation.previous.json'), installed);
+      writeJson(activation, activationHold(runtime, original));
+      writeJson(path.join(installation.root, 'installation.json'), {...installed, ...runtime}); switched = true;
+      savePointer({...state(), current: candidate, previous: before.previousCli.current}); writeStartup();
+      cancelled(); launched = installation.start();
+      let replacement; const deadline = Date.now() + 120000;
+      do {
+        await delay(1000);
+        try { const current = await control(config, 'status');
+          if (current.pid === launched.pid && continuity(current, original, runtime)) { replacement = current; break; }
+        } catch { /* Allow the replacement account/provider settings to restore. */ }
+      } while (live(launched.pid) && Date.now() < deadline);
+      need(replacement, 'Updated Desktop continuity did not match before its readiness deadline'); cancelled();
+      await acceptCandidate(config, launched.pid, runtime.version);
+      accepted = true;
+      let windowRestored = true;
+      if ((retiring?.mode || original.mode) === 'headed') { try { await control(config, 'window', {mode: 'headed'}); } catch { windowRestored = false; } }
+      try { fs.unlinkSync(pendingFile); fs.unlinkSync(transaction); } catch { /* Accepted runtime stays active; next start settles only metadata. */ }
+      return {updated: true, version: cli.version, runtimeUpdated: true, runtimeVersion: runtime.version, runtimePid: replacement.pid, windowRestored};
+    } catch (error) {
+      if (accepted) return {updated: true, version: cli.version, runtimeUpdated: true, runtimeVersion: runtime.version, runtimePid: launched.pid, recoveryMetadataPending: true};
+      // A candidate can be retired only through its own authenticated idle
+      // handoff. Never kill an unproven process or start two profile owners.
+      let candidateStopped = !launched || !live(launched.pid);
+      if (launched && !candidateStopped) {
+        try { const closing = await control(config, 'update-prepare'); if (closing.quitting && closing.pid === launched.pid) {
+          const deadline = Date.now() + 30000; while (live(launched.pid) && Date.now() < deadline) await delay(250); candidateStopped = !live(launched.pid);
+        } } catch { /* Preserve any busy or uncertain candidate for recovery. */ }
+      }
+      let restored = false;
+      if (candidateStopped && (oldRetired || switched || retiring?.quitting)) {
+        try {
+          removeHold(runtime);
+          writeJson(path.join(installation.root, 'installation.json'), installed); savePointer(before.previousCli); writeStartup();
+          if (runtimeStopped(installed)) installation.start();
+          restored = true; if (fs.existsSync(transaction)) fs.unlinkSync(transaction);
+        } catch { /* Durable recovery record retains original receipt and CLI. */ }
+      }
+      writeJson(path.join(installation.root, 'update-recovery.json'), {...before, rolledBack: restored});
+      throw Error(restored ? 'Updated Desktop failed; previous runtime restored with the original profile' : 'Update stopped; previous runtime and recovery receipt preserved');
+    }
+  } finally { unlock(); }
+}
+async function stopWorker() {
+  if (!fs.existsSync(installation.root)) return;
+  installation.privateRoot(); const marker = path.join(installation.root, 'updater-stop.json');
+  writeJson(marker, {kind: 'aglit-cli-updater-stop-v1'});
+  const file = path.join(installation.root, 'updater-worker.json');
+  const deadline = Date.now() + 30000;
+  while (fs.existsSync(file) && Date.now() < deadline) {
+    const worker = privateJson(file);
+    if (!Number.isSafeInteger(worker.pid) || !live(worker.pid)) { fs.unlinkSync(file); break; }
+    await delay(250);
+  }
+  need(!fs.existsSync(file), 'Updater is closing; installation preserved. Retry aglit uninstall.');
+  if (fs.existsSync(marker)) fs.unlinkSync(marker);
+}
+async function automatic(enabled) {
+  need(typeof enabled === 'boolean', 'Automatic update setting required'); installation.readInstallation(); saveSettings({automatic: enabled});
+  if (!enabled) await stopWorker();
+  else { try { const running = await control(path.join(installation.profile, 'ipc/sdk-ipc.json'), 'status'); if (running.running) ensureWorker(running.pid); } catch { /* Next start resumes automatic updates. */ } }
+  return {automatic: enabled, channel: state().channel};
+}
+async function prepareUninstall() {
+  await stopWorker(); const unlock = lock(path.join(installation.root, 'updating.lock'));
+  need(unlock, 'An update is still active; installation preserved. Retry uninstall after it finishes.'); return unlock;
+}
+function ensureWorker(runtimePid) {
+  const value = initialize(); if (!value.automatic) return;
+  const stop = path.join(installation.root, 'updater-stop.json'); if (fs.existsSync(stop)) { privateJson(stop); fs.unlinkSync(stop); }
+  const file = path.join(installation.root, 'updater-worker.json');
+  if (fs.existsSync(file)) { const previous = privateJson(file); if (Number.isSafeInteger(previous.pid) && live(previous.pid)) return; fs.unlinkSync(file); }
+  const script = path.join(packageDirectory(value.current.directory), 'src/update-worker.cjs'); installation.canonical(script);
+  const log = fs.openSync(path.join(installation.root, 'updater.log'), 'a', 0o600);
+  const env = {...process.env}; for (const key of Object.keys(env)) if (/^AGLIT_|^VITE_|^NODE_OPTIONS$|^NODE_PATH$|^ELECTRON_RUN_AS_NODE$/.test(key)) delete env[key];
+  const child = spawn(process.execPath, [script, String(runtimePid)], {detached: true, windowsHide: true, env, stdio: ['ignore', log, log]}); child.on('error', () => {}); child.unref(); fs.closeSync(log);
+}
+module.exports = {compareVersions, state, initialize, delegate, manifest, bootstrap, adoptBootstrap, status, update, automatic, ensureWorker, stopWorker, prepareUninstall, lock, writeJson, privateJson, live, stage, settings, runtimeStopped, rememberStatus, recoverActivation, runtimeVersion, runtimeTag, releaseManifests, validateInstalledGraph};