@andorra-labs/code 0.1.4 → 0.1.5

package/dist/src/cli.js

@@ -299,7 +299,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     if (argv[0] === 'update') {
         if (argv.length > 2 || (argv.length === 2 && argv[1] !== '--break-lock'))
             throw new Error('Usage: andorra update [--break-lock]');
-        process.stdout.write('Updating Andorra from GitHub main...\n');
+        process.stdout.write('Checking npm for the latest Andorra release...\n');
         const notify = (message) => process.stdout.write(safeTerminal(message) + '\n');
         process.stdout.write(safeTerminal(await updateInstallation({ breakLock: argv[1] === '--break-lock', notify })) + '\n');
         return 0;

package/dist/src/update.d.ts

@@ -1,19 +1,25 @@
-export type UpdateRunner = (program: string, args: string[], cwd: string) => Promise<string>;
-/** Outcome of deciding whether the installed dependency tree can be replaced in place. */
+/** The package `andorra update` installs. */
+export declare const PACKAGE_NAME = "@andorra-labs/code";
+export interface RunOptions {
+    /** Show the command's output while it runs instead of only capturing it; npm install uses this. */
+    stream?: boolean;
+}
+export type UpdateRunner = (program: string, args: string[], cwd: string, options?: RunOptions) => Promise<string>;
+/** Outcome of deciding whether the installed package can be replaced in place. */
 export interface LockProbe {
     state: 'clear' | 'locked' | 'unknown';
-    /** The file or directory npm could not replace, when the probe identified one. */
+    /** The file or directory that could not be replaced, when the probe identified one. */
     path?: string;
     detail: string;
 }
-export type ReinstallProbe = (checkout: string) => Promise<LockProbe>;
+export type ReinstallProbe = (packageRoot: string) => Promise<LockProbe>;
 export interface UpdateOptions {
     /** Injectable only for embedding/tests; the CLI uses this module's installed location. */
     moduleUrl?: string | URL;
     run?: UpdateRunner;
-    /** Injectable only for tests; the CLI probes the real tree by renaming within it. */
+    /** Injectable only for tests; the CLI probes the real package by renaming within it. */
     probe?: ReinstallProbe;
-    /** Injectable only for tests; the CLI waits between bounded reinstall attempts. */
+    /** Injectable only for tests; the CLI waits between bounded install attempts. */
     sleep?: (ms: number) => Promise<void>;
     /** Replace an existing updater lock even when its recorded process still appears to run. */
     breakLock?: boolean;
@@ -21,16 +27,11 @@ export interface UpdateOptions {
     isRunning?: (pid: number) => boolean;
     /** Receives progress notes the caller should show, such as a reclaimed stale lock. */
     notify?: (message: string) => void;
+    /** Injectable only for tests; the CLI keeps its lock in the Andorra home directory. */
+    lockDirectory?: string;
+    /** Injectable only for tests; the CLI runs the npm that ships beside the Node.js running it. */
+    npm?: string;
 }
-/**
- * True when the installed tree is provably complete for the lockfile the checkout carries: both the
- * root lockfile and npm's own hidden lockfile parse, every package npm recorded still matches the
- * version and hash the root lockfile pins, and every direct dependency the package declares is
- * present. The hidden lockfile is written only by a completed install, and it omits the root entry,
- * so a legitimate tree has one fewer entry than the lockfile — it is never compared by count, and it
- * is never trusted on its own, because a failed install can leave a stale one behind.
- */
-export declare function dependenciesSatisfied(checkout: string): Promise<boolean>;
 export interface UpdateLockOptions {
     breakLock?: boolean;
     isRunning?: (pid: number) => boolean;
@@ -44,5 +45,14 @@ export interface UpdateLockOptions {
  * a process id can be reused.
  */
 export declare function acquireUpdateLock(lockPath: string, options?: UpdateLockOptions): Promise<string>;
-/** Update the linked installation checkout, never the caller's working directory. */
+/**
+ * Replace the global npm installation this command runs from with the latest npm release.
+ *
+ * Only a global npm installation is updated. A source checkout — one that `npm link` exposes as the
+ * global command, or one started directly — is refused without changing anything, and so is any
+ * other copy (a project's own dependency, the desktop client's engine): each is updated the way it
+ * was installed. The release is resolved from the `latest` dist-tag once and installed by its exact
+ * version, so a tag that moves mid-update cannot install something other than what was reported,
+ * and a tag that points below the installed version is never followed down.
+ */
 export declare function updateInstallation(options?: UpdateOptions): Promise<string>;

package/dist/src/update.js

@@ -1,15 +1,23 @@
 import { execFile, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { link, readFile, readdir, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
-import { delimiter, dirname, join, resolve } from 'node:path';
+import { link, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import semver from 'semver';
+import { configDirectory } from './config.js';
 const executeFile = promisify(execFile);
+/** The package `andorra update` installs. */
+export const PACKAGE_NAME = '@andorra-labs/code';
+/** The npm dist-tag the update follows. */
+const RELEASE_TAG = 'latest';
 /** Bounded install attempts; only a failure that still looks transient is retried. */
 const INSTALL_ATTEMPTS = 3;
 const INSTALL_RETRY_DELAY_MS = 1_500;
 /** npm reports a Windows sharing violation as EPERM, EBUSY or errno -4048. */
 const LOCK_FAILURE = /EPERM|EBUSY|resource busy or locked|-4048/;
+/** How much of npm's error output a failure keeps for its message. */
+const OUTPUT_TAIL = 6_000;
 /** Bounded walk: a Windows sharing violation matters on a native module or a launcher. */
 const LOCK_PROBE_SCAN_LIMIT = 10_000;
 /**
@@ -17,36 +25,42 @@ const LOCK_PROBE_SCAN_LIMIT = 10_000;
  * build/Release/*.node, so a shallow limit would miss exactly the file this guard exists for.
  */
 const LOCK_PROBE_DEPTH = 6;
-const runCommand = async (program, args, cwd) => {
-    try {
-        const pathKey = process.platform === 'win32' ? Object.keys(process.env).find(key => key.toLowerCase() === 'path') ?? 'PATH' : 'PATH';
-        const env = { ...process.env, [pathKey]: dirname(process.execPath) + delimiter + (process.env[pathKey] ?? '') };
-        if (program === process.execPath) {
-            // npm lifecycle scripts can outlive npm if a timeout kills only its parent.
-            // Stream their output and retain the updater lock until npm actually closes.
-            return await new Promise((resolve, reject) => {
-                const child = spawn(program, args, { cwd, env, windowsHide: true, stdio: 'inherit' });
-                child.once('error', reject);
-                child.once('close', (code, signal) => {
-                    if (code === 0 && !signal)
-                        resolve('');
-                    else
-                        reject(new Error(`npm exited with ${signal ?? `code ${code}`}; see the command output above.`));
-                });
+const runCommand = async (program, args, cwd, options = {}) => {
+    const pathKey = process.platform === 'win32' ? Object.keys(process.env).find(key => key.toLowerCase() === 'path') ?? 'PATH' : 'PATH';
+    const env = { ...process.env, [pathKey]: dirname(process.execPath) + delimiter + (process.env[pathKey] ?? '') };
+    const command = `${program} ${args.join(' ')}`;
+    if (options.stream) {
+        // npm lifecycle scripts can outlive npm if a timeout kills only its parent, so there is no
+        // timeout here: the updater lock is held until npm actually closes. Its error output is shown
+        // as it arrives and kept, so a failure can still name the file Windows refused to replace.
+        return new Promise((resolvePromise, reject) => {
+            const child = spawn(program, args, { cwd, env, windowsHide: true, stdio: ['inherit', 'inherit', 'pipe'] });
+            let errors = '';
+            child.stderr?.on('data', (chunk) => {
+                process.stderr.write(chunk);
+                errors = (errors + chunk.toString('utf8')).slice(-OUTPUT_TAIL);
             });
-        }
+            child.once('error', error => reject(new Error(`${command} could not start: ${error.message}`)));
+            child.once('close', (code, signal) => {
+                if (code === 0 && !signal) {
+                    resolvePromise('');
+                    return;
+                }
+                const detail = errors.trim();
+                reject(new Error(`${command} exited with ${signal ?? `code ${code}`}${detail ? `:\n${detail}` : '; see the npm output above.'}`));
+            });
+        });
+    }
+    try {
         const result = await executeFile(program, args, { cwd, env, windowsHide: true, timeout: 600_000, maxBuffer: 8_388_608 });
         return result.stdout;
     }
     catch (error) {
         const failure = error;
-        const detail = (failure.stderr || failure.stdout || failure.message).trim().slice(-6_000);
-        throw new Error(`${program} ${args.join(' ')} failed${detail ? `:\n${detail}` : ''}`);
+        const detail = (failure.stderr || failure.stdout || failure.message).trim().slice(-OUTPUT_TAIL);
+        throw new Error(`${command} failed${detail ? `:\n${detail}` : ''}`);
     }
 };
-function canonicalOrigin(origin) {
-    return /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)Andorra-Labs\/Andorra-Code(?:\.git)?\/?$/i.test(origin);
-}
 async function npmCli() {
     const nodeDirectory = dirname(await realpath(process.execPath));
     const candidates = [
@@ -68,119 +82,52 @@ function containsPath(text, path) {
     const target = resolve(path);
     return normalizePathText(text).includes(normalizePathText(target));
 }
-/**
- * The dependency fingerprint: everything an install materializes from. When the fetched revision
- * leaves both files byte-identical, the installed tree already satisfies this revision.
- */
-async function dependencyFingerprint(checkout) {
-    const parts = [];
-    for (const name of ['package.json', 'package-lock.json']) {
-        const value = normalizePathText(await readFile(join(checkout, name), 'utf8').then(text => text, () => ''));
-        parts.push(`${name}:${value.length}:${value}`);
-    }
-    return parts.join('\n');
+/** Paths compare case-insensitively on Windows, where the filesystem does. */
+function samePath(a, b) {
+    const left = resolve(a);
+    const right = resolve(b);
+    return process.platform === 'win32' ? normalizePathText(left) === normalizePathText(right) : left === right;
 }
-/** npm's hidden lockfile is written by npm itself, only after an install completed. */
-async function readLockfile(path) {
+const exists = (path) => stat(path).then(() => true, () => false);
+const isDirectory = (path) => stat(path).then(info => info.isDirectory(), () => false);
+/** The name and version a package directory declares, or undefined when it holds no readable manifest. */
+async function readManifest(directory) {
     try {
-        const value = JSON.parse(await readFile(path, 'utf8'));
-        if (!value || typeof value !== 'object')
-            return undefined;
-        const { lockfileVersion, packages } = value;
-        if (typeof lockfileVersion !== 'number' || lockfileVersion < 2)
-            return undefined;
-        if (!packages || typeof packages !== 'object')
-            return undefined;
-        return packages;
+        const value = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
+        return value && typeof value === 'object' ? value : undefined;
     }
     catch {
         return undefined;
     }
 }
-/**
- * True when the installed tree is provably complete for the lockfile the checkout carries: both the
- * root lockfile and npm's own hidden lockfile parse, every package npm recorded still matches the
- * version and hash the root lockfile pins, and every direct dependency the package declares is
- * present. The hidden lockfile is written only by a completed install, and it omits the root entry,
- * so a legitimate tree has one fewer entry than the lockfile — it is never compared by count, and it
- * is never trusted on its own, because a failed install can leave a stale one behind.
- */
-export async function dependenciesSatisfied(checkout) {
-    const modules = join(checkout, 'node_modules');
-    const topLevel = await readLockfile(join(checkout, 'package-lock.json'));
-    const installed = await readLockfile(join(modules, '.package-lock.json'));
-    if (!topLevel || !installed)
-        return false;
-    let packages = 0;
-    for (const [key, raw] of Object.entries(installed)) {
-        if (key === '')
-            continue;
-        if (!key.startsWith('node_modules/'))
-            return false;
-        if (!raw || typeof raw !== 'object')
-            return false;
-        const entry = raw;
-        if (typeof entry.link === 'boolean') {
-            const local = typeof entry.resolved === 'string' ? resolve(modules, entry.resolved) : undefined;
-            if (!local || !(await stat(local).then(info => info.isDirectory(), () => false)))
-                return false;
-        }
-        else {
-            if (typeof entry.version !== 'string')
-                return false;
-            const pinned = topLevel[key];
-            if (!pinned || typeof pinned !== 'object')
-                return false;
-            const expected = pinned;
-            if (typeof expected.version !== 'string' || expected.version !== entry.version)
-                return false;
-            if (typeof expected.integrity === 'string' && expected.integrity !== entry.integrity)
-                return false;
-        }
-        packages += 1;
-    }
-    if (packages === 0)
-        return false;
-    return directDependenciesInstalled(checkout, topLevel, installed);
+/** The installed release's version, when the directory holds this package. */
+async function installedVersion(directory) {
+    const manifest = await readManifest(directory);
+    return manifest?.name === PACKAGE_NAME && typeof manifest.version === 'string' ? manifest.version : undefined;
 }
-/**
- * Every dependency the package declares must be in the lockfile the hidden lockfile agreed with.
- * A package that declares none has nothing to check, which is not a reason to reinstall it.
- */
-async function directDependenciesInstalled(checkout, topLevel, installed) {
-    let manifest;
-    try {
-        manifest = JSON.parse(await readFile(join(checkout, 'package.json'), 'utf8'));
-    }
-    catch {
-        return false;
-    }
-    const fields = ['dependencies', 'devDependencies', 'optionalDependencies'];
-    for (const field of fields) {
-        const declared = manifest[field];
-        if (!declared || typeof declared !== 'object')
-            continue;
-        for (const [name, spec] of Object.entries(declared)) {
-            const key = `node_modules/${name}`;
-            if (!topLevel[key] || !installed[key])
-                return false;
-            // An aliased range pins a different package name, so only its presence can be checked.
-            if (typeof spec !== 'string' || spec.startsWith('npm:'))
-                continue;
-            const expected = topLevel[key];
-            const actual = installed[key];
-            if (typeof expected.version !== 'string' || expected.version !== actual.version)
-                return false;
-        }
-    }
-    return true;
+/** npm prints the answer to `root` and `view` on its last line; anything before it is a notice. */
+function lastLine(output) {
+    return output.split(/\r?\n/).map(line => line.trim()).filter(Boolean).at(-1) ?? '';
+}
+function checkoutRefusal(packageRoot) {
+    return new Error([
+        `andorra update installs releases from npm, but this andorra runs from a source checkout at ${packageRoot}, so nothing was changed.`,
+        `To switch to the npm release, run: npm install -g ${PACKAGE_NAME}@latest`,
+        'That replaces an andorra command linked with npm link, and leaves the checkout itself as it is.',
+        'To keep using the checkout, update it from the checkout instead: git pull --ff-only, then npm ci and npm run build.',
+    ].join('\n'));
+}
+function notGlobalRefusal(packageRoot, entry) {
+    return new Error([
+        `andorra update replaces the global npm installation of ${PACKAGE_NAME} (${entry}), but this andorra runs from ${packageRoot}, so nothing was changed.`,
+        `Update that copy the way it was installed, or install the CLI globally with: npm install -g ${PACKAGE_NAME}@latest`,
+    ].join('\n'));
 }
 /**
  * Walk each installed package directory — the top level and its scope directories — for the files
  * npm materializes wholesale and Windows can hold open: native modules, which a live process loads
- * as a DLL, and launchers, which a running build holds. A scope directory does not consume depth,
- * so a scoped package like @scope/pkg/... is reached. Symlinks are skipped so a link into a
- * workspace package is never probed twice.
+ * as a DLL. A scope directory does not consume depth, so a scoped package like @scope/pkg/... is
+ * reached. Symlinks are skipped so a linked package is never probed twice.
  */
 async function lockProbeTargets(modules) {
     const targets = [];
@@ -215,61 +162,87 @@ async function lockProbeTargets(modules) {
 /** Suffix of the same-directory rename the probe performs and then undoes. */
 const REPLACEABLE_SUFFIX = '.andorra-replaceable';
 /**
- * Decide whether the installed dependency tree can be replaced in place before an install touches
- * it. npm ci deletes the whole tree first, so a single file held open by a live process turns a
- * routine update into a broken installation. A same-directory rename is exactly the operation that
- * fails with EPERM or EBUSY while a file is in Windows' pending-delete state, and it changes nothing.
+ * Decide whether npm can replace the installed package before it tries. npm replaces a global
+ * package by moving its directory aside and deleting it afterwards. On Windows the move fails while
+ * something inside is open without delete sharing — a process whose working directory is inside the
+ * package, or a file already waiting to be deleted. A native module a live process has loaded does
+ * not stop the move, only the delete afterwards; sweepRetired deals with that copy. A same-directory
+ * rename is exactly the operation that fails, and it changes nothing. Each native module is tried
+ * first, so a refusal can name the file.
  */
-async function probeReinstall(checkout) {
-    const modules = join(checkout, 'node_modules');
-    if (!(await stat(modules).then(info => info.isDirectory(), () => false))) {
-        return { state: 'clear', detail: 'nothing is installed yet, so there is nothing to replace' };
-    }
-    for (const target of await lockProbeTargets(modules)) {
-        const probe = `${target}${REPLACEABLE_SUFFIX}`;
-        try {
-            await rename(target, probe);
-            await rename(probe, target);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                continue;
-            const held = await stat(target).then(() => true, () => false);
-            if (!held)
-                continue;
-            return { state: 'locked', path: target, detail: error.message };
+async function probeReplace(packageRoot) {
+    const modules = join(packageRoot, 'node_modules');
+    if (await isDirectory(modules)) {
+        for (const target of await lockProbeTargets(modules)) {
+            const probe = `${target}${REPLACEABLE_SUFFIX}`;
+            try {
+                await rename(target, probe);
+                await rename(probe, target);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                if (!(await exists(target)))
+                    continue;
+                return { state: 'locked', path: target, detail: error.message };
+            }
         }
     }
     try {
-        const probe = `${modules}${REPLACEABLE_SUFFIX}`;
-        await rename(modules, probe);
+        const probe = `${packageRoot}${REPLACEABLE_SUFFIX}`;
+        await rename(packageRoot, probe);
         try {
-            await rename(probe, modules);
+            await rename(probe, packageRoot);
         }
         catch (error) {
-            throw new Error(`this update moved ${modules} to ${probe} and could not move it back (${error.message}); rename the directory back to node_modules before retrying.`);
+            throw new Error(`this update moved ${packageRoot} to ${probe} and could not move it back (${error.message}); rename the directory back before retrying.`);
         }
     }
     catch (error) {
-        const stillThere = await stat(modules).then(() => true, () => false);
-        if (stillThere)
-            return { state: 'locked', path: modules, detail: error.message };
-        return { state: 'unknown', detail: error.message, path: modules };
+        if (await exists(packageRoot))
+            return { state: 'locked', path: packageRoot, detail: error.message };
+        return { state: 'unknown', detail: error.message, path: packageRoot };
     }
-    return { state: 'clear', detail: 'every installed native module and launcher could be replaced' };
+    return { state: 'clear', detail: 'the installed package and every native module in it could be replaced' };
 }
-function probeRefusal(checkout, probe) {
-    const target = probe.path ?? join(checkout, 'node_modules');
-    const where = normalizePathText(target) === normalizePathText(join(checkout, 'node_modules'))
-        ? `the installed dependency directory itself (${target})`
-        : `the installed file ${target}`;
+function probeRefusal(packageRoot, probe) {
+    const target = probe.path ?? packageRoot;
+    const where = samePath(target, packageRoot) ? `the installed package directory itself (${target})` : `the installed file ${target}`;
     const guidance = probe.state === 'locked'
-        ? `A running process holds it open, and Windows keeps it in a pending-delete state until that process exits or unloads the module. CodeGraph holds the codegraph-kernel native module that way. Stop that process — a plain retry cannot release the file — then run andorra update again.`
-        : `The installed tree could not be inspected or replaced in place. Close any process working in this checkout and check the permissions on ${target}, then run andorra update again.`;
-    return new Error(`Refusing to reinstall dependencies in ${checkout}: ${where} cannot be replaced.\n${guidance}\nNothing was changed: the existing installation is untouched and the source checkout has not been advanced.`);
+        ? 'Something has it open in a way Windows will not let it be moved: most often a terminal or program whose working directory is inside the package, or a file that is still waiting to be deleted while a process holds it. Close that program — a plain retry cannot release it — then run andorra update again.'
+        : `The installed package could not be inspected or moved. Close any process using it and check the permissions on ${target}, then run andorra update again.`;
+    return new Error(`Refusing to update ${packageRoot}: ${where} cannot be replaced.\n${guidance}\nNothing was changed: the installed Andorra is untouched.`);
+}
+/**
+ * npm moves the release it replaces aside, as `.<name>-<random>` beside the package, and deletes it
+ * once the new release is in place. On Windows a native module that a running process still has
+ * loaded — another Andorra session, CodeGraph — survives that delete, so the copy stays behind and npm
+ * only warns. Every update deletes whatever such copies it can, its own and earlier ones, and returns
+ * the ones a process still holds. Only directories, never links, and only that exact name pattern.
+ */
+async function sweepRetired(entry) {
+    const scope = dirname(entry);
+    const retired = new RegExp(`^\\.${basename(entry).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-[A-Za-z0-9_-]+$`);
+    const held = [];
+    for (const item of await readdir(scope, { withFileTypes: true }).catch(() => [])) {
+        if (!item.isDirectory() || !retired.test(item.name))
+            continue;
+        const path = join(scope, item.name);
+        try {
+            await rm(path, { recursive: true, force: true });
+        }
+        catch {
+            held.push(path);
+        }
+    }
+    return held;
+}
+function heldNote(held) {
+    const one = held.length === 1;
+    return `npm could not delete ${one ? 'a replaced copy' : `${held.length} replaced copies`} of Andorra because a running process still has a file in ${one ? 'it' : 'them'} loaded: ${held.join(', ')}. The andorra command no longer uses ${one ? 'it' : 'them'}; andorra update deletes ${one ? 'it' : 'them'} once that process has exited.`;
 }
 /** Recover the concrete locked path from the failure npm actually reported, when it named one. */
-function reportedLockedFile(message, checkout) {
+function reportedLockedFile(message, packageRoot) {
     const patterns = [
         /npm error syscall[^\n]*\n\s*npm error (?:path|dest)\s+(.+)/,
         /npm error path\s+(.+)/,
@@ -285,61 +258,47 @@ function reportedLockedFile(message, checkout) {
         candidates.push(match[0].trim().replace(/[.,;:)\]]+$/, ''));
     for (const candidate of candidates) {
         const normalized = candidate.replace(/[.,;:)\]]+$/, '');
-        if (normalized.includes('node_modules') && (containsPath(normalized, checkout) || !/^[A-Za-z]:[\\/]/.test(normalized)))
+        if (containsPath(normalized, packageRoot) || containsPath(normalized, dirname(packageRoot)))
             return normalized;
     }
     return undefined;
 }
 /**
- * Describe a failed dependency install from what is actually on disk afterwards. The wording must
- * not promise that a plain retry recovers the installation: a locked file stays locked until the
- * process holding it exits, and any part of the tree npm already removed is still missing.
+ * Describe a failed install from what is actually on disk afterwards. npm moves the previous
+ * release back when an install fails, so the old version usually still runs — but the message says
+ * so only after reading it, and never promises that a plain retry releases a locked file.
  */
-function installFailureMessage(checkout, outcome, cause) {
-    const front = `Source checkout was updated, but reconciling dependencies with npm install failed in ${checkout}; the update is incomplete.`;
+function installFailureMessage(entry, version, outcome, cause) {
+    const front = `npm install --global ${PACKAGE_NAME}@${version} failed, so the update did not complete.`;
     const blocked = outcome.locked
-        ? `\nThe locked path npm reported is ${outcome.locked}. A running process holds it open, and Windows keeps it in a pending-delete state until that process exits or unloads the module — CodeGraph holds the codegraph-kernel native module that way. Stop that process; a plain retry cannot release the file.`
+        ? `\nThe locked path npm reported is ${outcome.locked}. Windows refused to replace it while a process holds it open. Stop that process; a plain retry cannot release the file.`
         : '';
-    const damage = outcome.destroyed
-        ? `\nThe dependency directory is missing, so the andorra CLI will not run and dist/ may be missing too. Free the lock first, then run andorra update again to install dependencies and rebuild the CLI.`
-        : `\nThe installed dependency tree survived this attempt, so the existing andorra CLI still runs, but this checkout now needs a dependency installation that did not complete. Fix the reported problem and run andorra update again.`;
-    return `${front}${blocked}${damage}\n${cause.message}`;
+    const state = outcome.installed
+        ? `\nThe installed Andorra at ${entry} is still version ${outcome.installed}, so the andorra command still runs. Fix the reported problem and run andorra update again.`
+        : `\nThe installed Andorra at ${entry} is missing or unreadable, so the andorra command may not run. Fix the reported problem, then reinstall with npm install -g ${PACKAGE_NAME}@latest.`;
+    return `${front}${blocked}${state}\n${cause.message}`;
 }
 /**
- * Reconcile the installed dependencies with npm install, never npm ci.
- *
- * npm ci deletes node_modules in its first phase and installs afterwards, so one file it cannot
- * delete — on Windows a native module a live process has open — destroys the installation: the tree
- * is already gone when npm reports the error, and the CLI no longer runs. npm install reconciles the
- * tree in place instead, leaving a dependency that already satisfies package-lock.json untouched, so
- * a locked native module inside it is not fatal. Do not "simplify" this back to npm ci: the
- * destructive first phase is precisely what broke a working installation.
- *
- * The probe still runs first, so a tree that genuinely cannot be replaced is refused before npm
- * touches anything rather than failing half way through.
+ * Install one exact release globally. A failure that left the previous release in place and still
+ * looks like a transient Windows sharing violation is retried a bounded number of times, after
+ * checking that the package can be moved again; anything else is reported at once.
  */
-async function installDependencies(run, sleep, probe, npm, checkout) {
-    const before = await probe(checkout);
-    if (before.state !== 'clear')
-        throw probeRefusal(checkout, before);
+async function installRelease(run, sleep, probe, npm, cwd, packageRoot, entry, version, previous) {
     for (let attempt = 1; attempt <= INSTALL_ATTEMPTS; attempt += 1) {
         try {
-            await run(process.execPath, [npm, 'install', '--include=dev'], checkout);
+            await run(process.execPath, [npm, 'install', '--global', `${PACKAGE_NAME}@${version}`, '--prefer-online', '--no-audit', '--no-fund'], cwd, { stream: true });
             return { ok: true };
         }
         catch (error) {
             const cause = error;
-            const after = await probe(checkout);
-            const locked = after.state === 'clear'
-                ? undefined
-                : after.path ?? `the installed dependency directory ${join(checkout, 'node_modules')} itself`;
-            const named = reportedLockedFile(cause.message, checkout);
-            const destroyed = !(await stat(join(checkout, 'node_modules')).then(info => info.isDirectory(), () => false));
-            // Retry only a failure that left a complete tree behind: it is transient by definition, and a
-            // retry can no longer compound damage now that the install reconciles instead of deleting.
-            if (attempt === INSTALL_ATTEMPTS || destroyed || locked || !LOCK_FAILURE.test(cause.message)) {
-                return { ok: false, cause, locked: named ?? locked, destroyed };
+            const installed = await installedVersion(entry);
+            const named = reportedLockedFile(cause.message, packageRoot);
+            if (attempt === INSTALL_ATTEMPTS || installed !== previous || !LOCK_FAILURE.test(cause.message)) {
+                return { ok: false, cause, locked: named, installed };
             }
+            const again = await probe(packageRoot);
+            if (again.state !== 'clear')
+                return { ok: false, cause, locked: named ?? again.path, installed };
             await sleep(INSTALL_RETRY_DELAY_MS);
         }
     }
@@ -520,93 +479,91 @@ async function releaseUpdateLock(lockPath, record, sleep) {
         await unlink(guard).catch(() => { });
     }
 }
-/** Update the linked installation checkout, never the caller's working directory. */
+/**
+ * Replace the global npm installation this command runs from with the latest npm release.
+ *
+ * Only a global npm installation is updated. A source checkout — one that `npm link` exposes as the
+ * global command, or one started directly — is refused without changing anything, and so is any
+ * other copy (a project's own dependency, the desktop client's engine): each is updated the way it
+ * was installed. The release is resolved from the `latest` dist-tag once and installed by its exact
+ * version, so a tag that moves mid-update cannot install something other than what was reported,
+ * and a tag that points below the installed version is never followed down.
+ */
 export async function updateInstallation(options = {}) {
     const run = options.run ?? runCommand;
     const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
-    const probe = options.probe ?? probeReinstall;
+    const probe = options.probe ?? probeReplace;
     const modulePath = await realpath(fileURLToPath(options.moduleUrl ?? import.meta.url));
-    const checkout = await realpath(resolve(dirname(modulePath), '..', '..'));
-    let packageName;
+    const packageRoot = await realpath(resolve(dirname(modulePath), '..', '..'));
+    const manifest = await readManifest(packageRoot);
+    if (!manifest)
+        throw new Error(`This andorra does not run from an installed ${PACKAGE_NAME} package (no readable package.json in ${packageRoot}), so andorra update cannot update it.`);
+    if (manifest.name !== PACKAGE_NAME)
+        throw new Error(`Refusing to update an unrelated package: expected ${PACKAGE_NAME} in ${packageRoot}.`);
+    const current = typeof manifest.version === 'string' ? semver.valid(manifest.version) : null;
+    if (!current)
+        throw new Error(`The installed ${PACKAGE_NAME} at ${packageRoot} declares no valid version, so andorra update cannot compare it with npm's release. Reinstall it with npm install -g ${PACKAGE_NAME}@latest.`);
+    // A checkout is refused before npm is even located: nothing about it is this updater's to change.
+    if (await exists(join(packageRoot, '.git')))
+        throw checkoutRefusal(packageRoot);
+    const npm = options.npm ?? await npmCli();
+    const home = options.lockDirectory ?? configDirectory();
+    await mkdir(home, { recursive: true });
+    // npm runs outside the package it replaces: a working directory inside it would keep Windows from
+    // moving it, and a project's .npmrc in the caller's directory has no say over a global install.
+    const cwd = home;
+    let globalRoot;
     try {
-        packageName = JSON.parse(await readFile(join(checkout, 'package.json'), 'utf8')).name;
-    }
-    catch {
-        throw new Error('This installation is not an Andorra source checkout. Link a clone of Andorra-Labs/Andorra-Code to use andorra update.');
-    }
-    if (packageName !== '@andorra-labs/code')
-        throw new Error('Refusing to update an unrelated package: expected @andorra-labs/code.');
-    let gitRoot;
-    try {
-        gitRoot = await realpath((await run('git', ['rev-parse', '--show-toplevel'], checkout)).trim());
-    }
-    catch {
-        throw new Error('This installation is not a Git source checkout. Link a clone of Andorra-Labs/Andorra-Code to use andorra update.');
+        globalRoot = lastLine(await run(process.execPath, [npm, 'root', '--global'], cwd));
     }
-    if (gitRoot !== checkout)
-        throw new Error('Refusing to update: the installation package is not at its Git repository root.');
-    const lockPath = resolve(checkout, (await run('git', ['rev-parse', '--git-path', 'andorra-update.lock'], checkout)).trim());
+    catch (error) {
+        throw new Error(`Could not ask npm where global packages are installed, so nothing was changed.\n${error.message}`);
+    }
+    if (!globalRoot)
+        throw new Error('npm did not report where global packages are installed, so nothing was changed.');
+    const entry = join(globalRoot, ...PACKAGE_NAME.split('/'));
+    const linked = await lstat(entry).then(info => info.isSymbolicLink(), () => false);
+    const resolvedEntry = await realpath(entry).catch(() => undefined);
+    const isEntry = resolvedEntry !== undefined && samePath(resolvedEntry, packageRoot);
+    if (isEntry && linked)
+        throw checkoutRefusal(packageRoot);
+    if (!isEntry)
+        throw notGlobalRefusal(packageRoot, entry);
+    const lockPath = join(home, 'update.lock');
     const lock = await acquireUpdateLock(lockPath, { breakLock: options.breakLock, isRunning: options.isRunning, notify: options.notify, sleep });
     try {
-        const branch = (await run('git', ['branch', '--show-current'], checkout)).trim();
-        if (branch !== 'main')
-            throw new Error(`Refusing to update branch ${branch || '(detached HEAD)'}. Switch the installation checkout to main yourself, then retry: ${checkout}`);
-        if ((await run('git', ['status', '--porcelain', '--untracked-files=all'], checkout)).trim()) {
-            throw new Error(`Refusing to update a dirty installation checkout. Commit, stash, or move your changes first: ${checkout}`);
-        }
-        const origin = (await run('git', ['remote', 'get-url', 'origin'], checkout)).trim();
-        if (!canonicalOrigin(origin))
-            throw new Error('Refusing to update: origin must be the canonical GitHub HTTPS or SSH URL for Andorra-Labs/Andorra-Code.');
-        // Resolve prerequisites before advancing the checkout, avoiding a preventable partial update.
-        const npm = await npmCli();
-        // Record the dependency fingerprint before the merge: if the fetched revision leaves it
-        // identical, the installed tree already satisfies it and no install is needed.
-        const dependenciesBefore = await dependencyFingerprint(checkout);
-        // Before the checkout is advanced, refuse an installation whose dependency tree cannot be
-        // replaced at all. Nothing has changed yet at this point, so the refusal costs the user nothing.
-        const reinstall = await probe(checkout);
-        if (reinstall.state !== 'clear')
-            throw probeRefusal(checkout, reinstall);
-        await run('git', ['fetch', 'origin', 'main'], checkout);
-        const fetched = (await run('git', ['rev-parse', 'FETCH_HEAD'], checkout)).trim();
-        if (!/^[a-f0-9]{40,64}$/i.test(fetched))
-            throw new Error('Git did not return a valid fetched commit; update stopped.');
-        // A concurrent user edit during fetch must not be carried into the installation update.
-        if ((await run('git', ['branch', '--show-current'], checkout)).trim() !== 'main'
-            || (await run('git', ['status', '--porcelain', '--untracked-files=all'], checkout)).trim()) {
-            throw new Error('The installation branch or files changed during fetch; update stopped without merging.');
-        }
+        let reported;
         try {
-            await run('git', ['merge-base', '--is-ancestor', 'HEAD', fetched], checkout);
-            await run('git', ['merge', '--ff-only', fetched], checkout);
+            reported = lastLine(await run(process.execPath, [npm, 'view', `${PACKAGE_NAME}@${RELEASE_TAG}`, 'version', '--prefer-online'], cwd));
         }
         catch (error) {
-            throw new Error(`Cannot fast-forward the installation checkout. Resolve any local divergence on main yourself; no reset or branch switch was performed.\n${error.message}`);
+            throw new Error(`Could not look up the latest ${PACKAGE_NAME} release on npm, so nothing was changed. Check the network connection and npm registry settings, then run andorra update again.\n${error.message}`);
         }
-        if ((await run('git', ['rev-parse', 'HEAD'], checkout)).trim() !== fetched)
-            throw new Error('Installation HEAD changed during update; dependencies were not installed. Inspect the checkout before retrying.');
-        const dependenciesChanged = dependenciesBefore !== await dependencyFingerprint(checkout);
-        // When package.json and package-lock.json are byte-identical across the update, the installed
-        // tree already satisfies the fetched revision, so no install is needed at all. This is the case
-        // that broke: an ordinary source-only update reinstalled everything for no reason.
-        const reused = !dependenciesChanged && await dependenciesSatisfied(checkout);
-        if (!reused) {
-            // The pre-fetch probe proved the tree was replaceable then; re-check it now, because the
-            // fetch and merge are exactly the window in which a process can take a new lock on it.
-            const outcome = await installDependencies(run, sleep, probe, npm, checkout);
-            if (!outcome.ok) {
-                throw new Error(installFailureMessage(checkout, { locked: outcome.locked, destroyed: outcome.destroyed }, outcome.cause));
-            }
+        const latest = semver.valid(reported);
+        if (!latest)
+            throw new Error(`npm reported "${reported}" as the latest ${PACKAGE_NAME} release, which is not a version, so nothing was changed.`);
+        // Copies an earlier update could not delete are swept whenever the installation ends up current,
+        // so they go on the first run after the process holding them has exited.
+        const withSweep = async (summary) => {
+            const held = await sweepRetired(entry);
+            return held.length ? `${summary}\n${heldNote(held)}` : summary;
+        };
+        if (semver.eq(latest, current))
+            return withSweep(`Andorra ${current} is already the latest release on npm; nothing was installed.`);
+        if (semver.lt(latest, current)) {
+            return `The latest ${PACKAGE_NAME} release on npm is ${latest}, older than the installed ${current}. andorra update never downgrades, so nothing was changed.`;
         }
-        try {
-            await run(process.execPath, [npm, 'run', 'build'], checkout);
-        }
-        catch (error) {
-            const cause = error;
-            throw new Error(`Source checkout was updated but the CLI build failed. The update is incomplete; fix the reported problem and run andorra update again.\n${cause.message}`);
+        const replaceable = await probe(packageRoot);
+        if (replaceable.state !== 'clear')
+            throw probeRefusal(packageRoot, replaceable);
+        const outcome = await installRelease(run, sleep, probe, npm, cwd, packageRoot, entry, latest, current);
+        if (!outcome.ok)
+            throw new Error(installFailureMessage(entry, latest, { locked: outcome.locked, installed: outcome.installed }, outcome.cause));
+        const installed = await installedVersion(entry);
+        if (installed !== latest) {
+            throw new Error(`npm reported success, but ${entry} now holds ${installed ? `version ${installed}` : 'no readable release'} instead of ${latest}. Check it with andorra --version, then run andorra update again.`);
         }
-        const revision = (await run('git', ['rev-parse', '--short=12', 'HEAD'], checkout)).trim();
-        return `Updated Andorra at ${checkout}\nRevision: ${revision}\nDependencies ${reused ? 'already satisfied this revision, so nothing was installed' : 'reconciled with npm install'} and CLI build completed.`;
+        return withSweep(`Updated Andorra from ${current} to ${latest}.\nInstalled ${PACKAGE_NAME}@${latest} from npm into ${entry}.`);
     }
     finally {
         await releaseUpdateLock(lockPath, lock, sleep);

package/docs/agents/install-for-agents.md

@@ -2,33 +2,27 @@
 
 If you use another AI coding agent (Codex, Claude Code, and so on), paste the block below into it. The agent can then install Andorra Code on your machine, configure a provider, and verify the install without further decisions from you.
 
-Before pasting, fill in the two bracketed values: which provider to configure, and where to clone the repository. Everything else is deterministic.
+Before pasting, fill in the bracketed value: which provider to configure. Everything else is deterministic.
 
 ````markdown
 Install Andorra Code (a terminal-first coding agent) on this machine and verify it works.
 
 Prerequisites you must check first:
 - Node.js 22.19 or newer (`node --version`). If missing or older, install the current LTS
-  from nodejs.org (or via the system's package manager) before continuing.
-- git on PATH (`git --version`).
-- Network access to github.com and to the model provider endpoint below.
+  from nodejs.org (or via the system's package manager) before continuing. npm ships with it.
+- Network access to registry.npmjs.org and to the model provider endpoint below.
 - If the provider preset below is "Codex": the official OpenAI Codex CLI must already be
   installed and signed in with ChatGPT (install @openai/codex and run `codex login`), or
   ANDORRA_CODEX_PATH must point at its executable. Without it, configuring the Codex
-  provider fails — check this before step 7 when that preset is chosen.
+  provider fails — check this before step 3 when that preset is chosen.
 
 Steps (run verbatim, stopping to report if any step fails):
-1. git clone https://github.com/Andorra-Labs/Andorra-Code "<clone path, e.g. C:\dev\Andorra-Code>"
-2. cd "<clone path>"
-3. npm ci
-4. npm run build
-5. npm link
-6. Verify: `andorra --version` must print a version number (currently 0.1.0). If `andorra`
-   is not found, the npm global bin directory is not on PATH — report that; do not edit
-   shell profiles silently.
+1. npm install -g @andorra-labs/code
+2. Verify: `andorra --version` must print a version number. If `andorra` is not found, the
+   npm global bin directory is not on PATH — report that; do not edit shell profiles silently.
 
 Provider configuration (interactive, needs the human once):
-7. Tell the user to run `andorra` in any folder, type `/providers`, press Enter, choose
+3. Tell the user to run `andorra` in any folder, type `/providers`, press Enter, choose
    "Add provider", select the "<provider preset: DeepSeek | Kimi | Kimi For Coding | GLM Coding Plan | OpenAI | Anthropic | local | Codex>"
    preset, and provide credentials one of these two ways:
    - Paste their API key into the masked **API key** field (saved locally), or
@@ -38,18 +32,15 @@ Provider configuration (interactive, needs the human once):
    Settings save only after choosing "Save changes".
 
 Verification (optional, non-interactive):
-8. `andorra --version`
-9. `andorra auth status` — reports the Andorra account session (signed out is fine;
-    accounts are optional and only needed for hosted Jev and paid graph features).
+4. `andorra --version`
+5. `andorra auth status` — reports the Andorra account session (signed out is fine;
+   accounts are optional and only needed for hosted Jev and paid graph features).
 
 Notes:
-- The npm package @andorra-labs/code is not published to npm yet; source install is the
-  only supported path.
-- To update later: run `andorra update` from any directory (requires the checkout on
-  branch main with a clean tree).
+- To update later: run `andorra update` from any directory. It installs the latest npm
+  release of @andorra-labs/code and never downgrades.
 - Configuration lives in ~/.andorracode (override with ANDORRACODE_HOME). Saved API keys
   are plaintext in ~/.andorracode/config.json — never commit or share that file.
-- Do not modify anything under the clone's working tree other than what these commands do.
 ````
 
 ## What the human still has to do
@@ -59,6 +50,6 @@ Two things cannot be automated away:
 1. **The API key.** Provider keys are secrets; paste them yourself in the masked field, or export the environment variable yourself.
 2. **The optional account.** Run `andorra login` yourself if you want hosted Jev routing or paid graph features — the browser sign-in is interactive. See [Accounts](../getting-started/accounts.md).
 
-## Why source install
+## Installing from source instead
 
-`@andorra-labs/code` is not yet on the public npm registry, so `npm install -g` does not work. The clone-and-link procedure above is exactly what the human-facing [Getting started](../getting-started/README.md) describes. When the package is published, this page gains a one-line `npm install -g @andorra-labs/code` alternative.
+To run unreleased changes, clone and link the repository as [Getting started](../getting-started/README.md#install-from-source) describes. `andorra update` does not update a source checkout: pull and rebuild it yourself, or switch to the npm release with `npm install -g @andorra-labs/code@latest`.

package/docs/getting-started/README.md

@@ -1,6 +1,6 @@
 # Getting started
 
-This page installs Andorra Code from source, configures one model provider, and runs your first task. Total time is a few minutes on a machine that already has Node.js.
+This page installs Andorra Code from npm, configures one model provider, and runs your first task. Total time is a few minutes on a machine that already has Node.js.
 
 If you want another AI coding agent to do this for you, skip to [Give these instructions to an AI agent](../agents/install-for-agents.md).
 
@@ -10,12 +10,20 @@ If you want another AI coding agent to do this for you, skip to [Give these inst
 | --- | --- |
 | Node.js 22.19 or newer | The engine declares `node >=22.19.0`. Check with `node --version`. |
 | npm | Ships with Node.js. |
-| git | Used to clone the repository; Andorra also reads Git state for its status displays. |
+| git | Andorra reads Git state for its status displays; also needed to install from source. |
 | A model provider | An API key for an OpenAI-compatible or Anthropic endpoint, a ChatGPT subscription (Codex provider), or a local server such as LM Studio. See [Configure providers](configure-providers.md). |
 
-## Install from source
+## Install
 
-`@andorra-labs/code` is not yet published to npm. Install from the GitHub repository:
+```sh
+npm install -g @andorra-labs/code
+```
+
+This installs two global commands, `andorra` and the alias `andorracode`. Keep them current with `andorra update`, which installs the latest npm release; see [Update](../guides/update.md).
+
+### Install from source
+
+To run unreleased changes, build the GitHub repository instead:
 
 ```sh
 git clone https://github.com/Andorra-Labs/Andorra-Code
@@ -25,7 +33,7 @@ npm run build
 npm link
 ```
 
-This installs two global commands, `andorra` and the alias `andorracode`, both pointing at this checkout.
+`npm link` points `andorra` and `andorracode` at this checkout. `andorra update` does not update a checkout; pull and rebuild it yourself (`git pull --ff-only`, `npm ci`, `npm run build`), or switch to the npm release with `npm install -g @andorra-labs/code@latest`.
 
 Alternatives without linking:
 
@@ -71,4 +79,4 @@ An Andorra account is optional: signing in enables hosted Jev decision routing a
 - [Concepts](../concepts/README.md) — how the graph, agents, and context routing fit together.
 - [Guides](../guides/README.md) — the TUI in depth, the Graph Builder, headless automation, skills/MCP/plugins.
 - [Reference](../reference/README.md) — every CLI flag, slash command, and configuration file.
-- [Update an existing installation](../guides/update.md) — `andorra update`.
+- [Update an existing installation](../guides/update.md) — `andorra update` installs the latest npm release.

package/docs/guides/README.md

@@ -9,4 +9,4 @@ Task-oriented how-tos for every client and mode.
 - [Browser workspace](browser.md) — the `/browser` local web client.
 - [Desktop client](desktop-app.md) — the Tauri desktop application.
 - [Windows code signing](windows-code-signing.md) — Authenticode signing of the desktop bundles with Azure Artifact Signing, and how to verify a signature.
-- [Update](update.md) — keeping a source installation current with `andorra update`.
+- [Update](update.md) — keeping the npm installation current with `andorra update`.

package/docs/guides/desktop-app.md

@@ -10,7 +10,7 @@ records, and the door to the graph editor. It does not reimplement any of them:
 | Requirement | Notes |
 | --- | --- |
 | Node.js 22.19 or newer | Needed to build from source or use a custom engine. Installed releases include their own supported Node runtime. |
-| The Andorra CLI | Installed releases include the engine built for that desktop version, with production dependencies. Source development links `@andorra-labs/code` from the checkout. Explicit custom engines must support `app-server --stdio`. |
+| The Andorra CLI | Installed releases include the engine built for that desktop version, with production dependencies. Source development installs the latest npm release of `@andorra-labs/code` into `desktop/node_modules`. Explicit custom engines must support `app-server --stdio`. |
 | Rust 1.90+ and the Tauri CLI | Only to build the shell. The Tauri CLI is installed by `npm install` in `desktop/`. |
 | Platform webview | WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux. |
 
@@ -27,13 +27,42 @@ engine and remain your responsibility to update. The **Node executable** setting
 overrides the interpreter used for a JavaScript entry point, and `ANDORRA_NODE` applies when that
 field is empty.
 
-Source-development builds without a staged payload retain discovery of the checkout dependency,
-global npm installations, then `andorra` on `PATH`.
+Source-development builds without a staged payload start the client's own dependency,
+`desktop/node_modules/@andorra-labs/code`, then global npm installations, then `andorra` on `PATH`.
+That dependency is the latest npm release, not the checkout: every `npm install` or `npm ci` in
+`desktop/` ends by asking npm which release the `latest` tag names and, when it is newer than the
+installed one, installing it with `--no-save`, so `package.json` and `package-lock.json` stay as
+committed. The step never fails the install and never downgrades; offline, it keeps the installed
+engine and says so. Set `ANDORRA_DESKTOP_ENGINE_LATEST=0` to keep the lockfile's engine for a
+reproducible build. Installers are unaffected: `npm run desktop:build` still packages the
+checkout's own engine at the desktop's version.
+
+To drive this checkout's engine from a development window instead — to try engine changes in the
+window — build it in the repository root (`npm install`, `npm run build`) and select its
+`dist/src/cli.js` under **Settings → Appearance → Engine**, or set `ANDORRA_CLI` to that path.
 
 The engine the window resolved — interpreter and entry point — is shown as **Resolved command**
 under Settings → Appearance → Engine, which is how a window driving a checkout is told apart from
 one driving an installed CLI.
 
+### The terminal's `andorra`
+
+The desktop and a global npm installation of the CLI share `~/.andorracode`, but updating the
+desktop leaves the global installation where it was. When the global `andorra` is older than the
+engine this desktop version ships, **Settings → Appearance & engine** shows a note, **Terminal CLI
+is out of date**, with both versions and a copyable command to run in a terminal: `andorra update`
+(see [Update](update.md)) for 0.1.5 and later, or `npm install -g @andorra-labs/code@latest` for an
+older release, whose `andorra update` only updates a Git checkout and refuses an npm installation.
+The window never runs npm or the global CLI itself: it reads the version from the installation's
+`package.json`.
+
+The note compares the first global installation found, in the order a source build searches them
+(`%APPDATA%\npm`, `%LOCALAPPDATA%\npm`, `NPM_CONFIG_PREFIX`, `/usr/local`, `/usr/lib`,
+`/opt/homebrew`, then nvm's default Node version and the rest newest first). It shows nothing when
+there is no global installation, when that installation is the same version or newer, or when it
+is a source checkout linked with `npm link`, whose `package.json` says nothing about the code that
+was last built. The check runs each time the page opens.
+
 A checkout's own `cli.js` is never executed unless you select it: the launch directory is not
 searched, so starting the window from an untrusted checkout cannot run that checkout's engine. Set
 the **Entry point** setting, or `ANDORRA_CLI`, to point at a build you trust.
@@ -45,13 +74,13 @@ installation.
 ## Run it
 
 ```bash
-npm install               # in the repository root: the engine's own dependencies
-npm run build             # in the repository root: the built CLI, the client's engine
 cd desktop
-npm install               # links @andorra-labs/code -> the checkout root, and the shell toolchain
+npm install               # the shell toolchain, and the latest npm release of @andorra-labs/code as the client's engine
 npm run desktop:dev       # builds the shell and opens the window with the dev server
 ```
 
+Run `npm install` in `desktop/` again to move the client's engine to a newer npm release.
+
 Other scripts:
 
 ```bash

package/docs/guides/update.md

@@ -10,18 +10,46 @@ Run from any directory:
 andorra update
 ```
 
-This fetches GitHub `main`, fast-forwards the installation checkout, installs locked dependencies, and rebuilds the CLI. It updates the checkout that provides the command, regardless of your current project directory.
+This asks npm which release the `latest` tag of `@andorra-labs/code` names and, when it is newer than the installed version, installs exactly that version globally with `npm install -g @andorra-labs/code@<version>`. It uses the npm that ships with the Node.js running Andorra, and it updates the global installation that provides the command, regardless of your current project directory.
+
+- When the installed version is already the latest, nothing is installed: `Andorra 0.1.4 is already the latest release on npm; nothing was installed.`
+- It never downgrades. If the `latest` tag points at an older release than the one installed, nothing changes and the message says so.
+- If npm cannot be reached, nothing changes; fix the network or registry settings and run it again.
 
 Requirements:
 
-- The installation checkout must be on `main` with no local changes.
-- If installation or compilation fails, fix the reported problem and rerun `andorra update`; it also rebuilds when the source is already current.
+- The `andorra` command must be the global npm installation, `npm install -g @andorra-labs/code`.
+- It refuses, without changing anything, when `andorra` runs from a source checkout — one linked with `npm link`, or started as `node dist/src/cli.js` — and when it runs from any other copy, such as a project's own dependency or the desktop client's engine. The message names the path and the command to use instead.
+
+### Switching from a source checkout
+
+An installation made by cloning the repository and running `npm link` is not updated by `andorra update`. To move it to the npm release:
+
+```sh
+npm install -g @andorra-labs/code@latest
+```
+
+That replaces the linked global command with the published package. The checkout itself is left as it is. To keep running the checkout instead, update it yourself from the checkout:
+
+```sh
+git pull --ff-only
+npm ci
+npm run build
+```
+
+## A failed or blocked update
+
+Before npm touches anything, the update checks that the installed package can be moved, because npm replaces it by moving it aside. On Windows a terminal or program whose working directory is inside the package keeps it in place; the update then refuses, names the path, and changes nothing. Close that program and run `andorra update` again.
+
+Another Andorra session or CodeGraph that has a native module of the old release loaded does not block the update: npm installs the new release, but cannot delete the old copy it moved aside (`@andorra-labs/.code-<random>` beside the package) while that process runs, and warns about it. The update names that copy. It is no longer used by the `andorra` command, and the next `andorra update` deletes it once the process holding it has exited.
+
+When `npm install` itself fails, npm moves the previous release back, and the message says which version is still installed. A failure that looks like a brief Windows sharing violation is retried a few times first.
 
 ## An interrupted update
 
-While it runs, `andorra update` holds a lock file, `.git/andorra-update.lock` in the installation checkout, so two updates cannot run at once. The lock records the updater's process id. If an update is cancelled with Ctrl+C, its terminal is closed, or it crashes, the lock stays behind.
+While it runs, `andorra update` holds a lock file, `update.lock` in the Andorra home directory (`~/.andorracode`, or `ANDORRACODE_HOME` when set), so two updates cannot run at once. The lock records the updater's process id. If an update is cancelled with Ctrl+C, its terminal is closed, or it crashes, the lock stays behind.
 
-Run `andorra update` again. When the process the lock names has exited, the update removes the stale lock, prints `Removed a stale update lock left by process …`, and continues. Rerunning also finishes whatever the interrupted update left half done, because it rebuilds even when the source is already current.
+Run `andorra update` again. When the process the lock names has exited, the update removes the stale lock, prints `Removed a stale update lock left by process …`, and continues.
 
 The update refuses to start when the lock names a process that is still running, or when the lock is empty or unreadable. If you are sure no update is running (a process id can be reused by an unrelated program), break the lock:
 
@@ -29,19 +57,12 @@ The update refuses to start when the lock names a process that is still running,
 andorra update --break-lock
 ```
 
-## Older installations
-
-For an installation without the update command, run once from the installation checkout:
+## The desktop client's engine
 
-```sh
-git pull --ff-only
-npm ci
-npm run build
-npm link
-```
+A source build of the desktop client has an engine of its own, `desktop/node_modules/@andorra-labs/code`, which `andorra update` does not touch. Every `npm install` or `npm ci` in `desktop/` moves it to the latest npm release; see [Desktop client](desktop-app.md#which-engine-the-window-starts).
 
-If you previously linked a checkout, run `npm link` again after major changes to refresh the global command.
+The reverse holds too: updating the desktop app does not update the global `andorra`. When the global installation is older than the desktop's engine, the desktop says so under **Settings → Appearance & engine** and offers `andorra update` to copy, or `npm install -g @andorra-labs/code@latest` for a release before 0.1.5, whose updater predates npm releases; see [Desktop client](desktop-app.md#the-terminals-andorra).
 
 ## Version
 
-`andorra --version` prints the installed version, read from the package manifest of the checkout that provides the command.
+`andorra --version` prints the installed version, read from the package manifest of the installation that provides the command.

package/docs/reference/cli.md

@@ -54,7 +54,7 @@ andorra auth status
 | `andorra mcp-server --stdio` | Run the local stdio MCP server: the supported surface for an agent to author and edit graphs, plus session monitoring. See [Agent MCP server](../agents/mcp-server.md). |
 | `andorra app-server --stdio` | Run the JSON-lines app server that drives the desktop client. Not for humans; see [Desktop client](../guides/desktop-app.md). |
 | `andorra remote <subcommand>` | Remote workspace pairing and sharing — `serve`, `status`, `code`, `devices`, `revoke <device-id>`, `share <path>`, `unshare <share-id>`, `pair <pairing-code>`, `workspaces`, `unpair <workspace-id>`, `rotate-cert`, with the flags shown in the usage above. See [Remote workspace](../guides/desktop-app.md#remote-workspace). |
-| `andorra update [--break-lock]` | Update the linked source installation from GitHub `main`. `--break-lock` replaces a leftover updater lock; see [Update](../guides/update.md#an-interrupted-update). |
+| `andorra update [--break-lock]` | Install the latest npm release of `@andorra-labs/code` into the global npm installation; a source checkout is refused. `--break-lock` replaces a leftover updater lock; see [Update](../guides/update.md#an-interrupted-update). |
 | `andorra login` | Open the browser to sign in to (or create) an Andorra account. |
 | `andorra logout` | Remove this machine's saved Andorra account session and revoke its refresh token. |
 | `andorra auth status` | Show the saved Andorra account session and membership. |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andorra-labs/code",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "description": "Terminal-first coding agent with a ReAct graph runtime",
     "license": "SEE LICENSE IN LICENSE.md",
     "type": "module",