@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/update.js

@@ -0,0 +1,614 @@
+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 { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const executeFile = promisify(execFile);
+/** 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/;
+/** Bounded walk: a Windows sharing violation matters on a native module or a launcher. */
+const LOCK_PROBE_SCAN_LIMIT = 10_000;
+/**
+ * How deep inside one package to look. Real prebuilt modules sit at lib/kernel/*.node or
+ * 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 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}` : ''}`);
+    }
+};
+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 = [
+        join(nodeDirectory, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        resolve(nodeDirectory, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        resolve(nodeDirectory, '..', 'share', 'nodejs', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    for (const candidate of candidates) {
+        if (await stat(candidate).then(info => info.isFile(), () => false))
+            return candidate;
+    }
+    throw new Error('Cannot find npm beside the Node.js installation running Andorra. Install Node.js with npm, then run andorra update again.');
+}
+/** Keep the opaque, escaped shapes Windows error text can carry when matching it. */
+function normalizePathText(text) {
+    return text.replace(/\\{2,}/g, '\\').replace(/\\/g, '/').toLowerCase();
+}
+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');
+}
+/** npm's hidden lockfile is written by npm itself, only after an install completed. */
+async function readLockfile(path) {
+    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;
+    }
+    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);
+}
+/**
+ * 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;
+}
+/**
+ * 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.
+ */
+async function lockProbeTargets(modules) {
+    const targets = [];
+    let visited = 0;
+    const walk = async (directory, depth) => {
+        if (visited >= LOCK_PROBE_SCAN_LIMIT)
+            return;
+        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            visited += 1;
+            if (visited > LOCK_PROBE_SCAN_LIMIT)
+                return;
+            if (entry.name === '.bin' || entry.isSymbolicLink())
+                continue;
+            const full = join(directory, entry.name);
+            if (!entry.isDirectory()) {
+                if (entry.name.endsWith('.node'))
+                    targets.push(full);
+                continue;
+            }
+            if (entry.name.startsWith('@') && depth === 0) {
+                await walk(full, 0);
+                continue;
+            }
+            if (depth < LOCK_PROBE_DEPTH)
+                await walk(full, depth + 1);
+        }
+    };
+    await walk(modules, 0);
+    return targets;
+}
+/** 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.
+ */
+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 };
+        }
+    }
+    try {
+        const probe = `${modules}${REPLACEABLE_SUFFIX}`;
+        await rename(modules, probe);
+        try {
+            await rename(probe, modules);
+        }
+        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.`);
+        }
+    }
+    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 };
+    }
+    return { state: 'clear', detail: 'every installed native module and launcher 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}`;
+    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.`);
+}
+/** Recover the concrete locked path from the failure npm actually reported, when it named one. */
+function reportedLockedFile(message, checkout) {
+    const patterns = [
+        /npm error syscall[^\n]*\n\s*npm error (?:path|dest)\s+(.+)/,
+        /npm error path\s+(.+)/,
+        /\b(?:path|dest)\s*[:=]\s*['"]?([A-Za-z]:[\\/][^\n'"]+|\/[^\n'"]+)/,
+    ];
+    const candidates = [];
+    for (const pattern of patterns) {
+        const match = pattern.exec(message);
+        if (match?.[1])
+            candidates.push(match[1].trim());
+    }
+    for (const match of message.matchAll(/[A-Za-z]:[\\/][^\n'"<>|?*]+/g))
+        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)))
+            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.
+ */
+function installFailureMessage(checkout, outcome, cause) {
+    const front = `Source checkout was updated, but reconciling dependencies with npm install failed in ${checkout}; the update is incomplete.`;
+    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.`
+        : '';
+    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}`;
+}
+/**
+ * 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.
+ */
+async function installDependencies(run, sleep, probe, npm, checkout) {
+    const before = await probe(checkout);
+    if (before.state !== 'clear')
+        throw probeRefusal(checkout, before);
+    for (let attempt = 1; attempt <= INSTALL_ATTEMPTS; attempt += 1) {
+        try {
+            await run(process.execPath, [npm, 'install', '--include=dev'], checkout);
+            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 };
+            }
+            await sleep(INSTALL_RETRY_DELAY_MS);
+        }
+    }
+    /* c8 ignore next */
+    throw new Error('unreachable: the bounded npm install loop always returns');
+}
+/** True while the process exists; EPERM means it exists but belongs to another account. */
+function processRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function lockOwner(recorded) {
+    try {
+        const { pid, startedAt } = JSON.parse(recorded);
+        if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0)
+            return undefined;
+        return { pid, startedAt: typeof startedAt === 'string' ? startedAt : undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Polls while another updater holds the short-lived reclaim guard; reclaiming takes milliseconds. */
+const RECLAIM_GUARD_ATTEMPTS = 30;
+const RECLAIM_GUARD_DELAY_MS = 100;
+/** Codes a filesystem without hard links (FAT, exFAT) reports for link(). */
+const NO_HARD_LINKS = new Set(['EPERM', 'ENOTSUP', 'ENOSYS', 'EOPNOTSUPP']);
+/** Write the record beside the lock, so the lock never exists without the record in it. */
+async function stageRecord(lockPath, record) {
+    const staged = `${lockPath}.${randomUUID()}.tmp`;
+    await writeFile(staged, record, { flag: 'wx', mode: 0o600 });
+    return staged;
+}
+/** Create the lock with its record already inside; false when a lock already exists. */
+async function createLock(lockPath, record) {
+    const staged = await stageRecord(lockPath, record);
+    try {
+        await link(staged, lockPath);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST')
+            return false;
+        if (!code || !NO_HARD_LINKS.has(code))
+            throw error;
+        // Without hard links fall back to an exclusive create, which leaves the lock empty for the
+        // moment between creating and writing it.
+        try {
+            await writeFile(lockPath, record, { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+        catch (fallback) {
+            if (fallback.code === 'EEXIST')
+                return false;
+            throw fallback;
+        }
+    }
+    finally {
+        await unlink(staged).catch(() => { });
+    }
+}
+/** One reclaimer at a time, so a lock another updater just took over is never judged stale again. */
+async function takeReclaimGuard(guard, lockPath, breakLock, sleep) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            await writeFile(guard, JSON.stringify({ pid: process.pid }) + '\n', { flag: 'wx', mode: 0o600 });
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        if (attempt < RECLAIM_GUARD_ATTEMPTS) {
+            await sleep(RECLAIM_GUARD_DELAY_MS);
+            continue;
+        }
+        // A guard that outlives every poll was left by an updater killed while reclaiming.
+        if (!breakLock)
+            throw new Error(`Another update is recovering the lock at ${lockPath} (guard file ${guard}). Wait for it to finish. If no update is running, rerun with andorra update --break-lock.`);
+        await unlink(guard).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+        breakLock = false;
+        attempt = 0;
+    }
+}
+/**
+ * Take the updater lock and return the record written into it. A lock whose recorded process is
+ * gone was left by an interrupted update (Ctrl+C, a closed terminal, a crash) and is reclaimed; one
+ * whose process still runs, or that does not name a process, is only broken with breakLock, because
+ * a process id can be reused.
+ */
+export async function acquireUpdateLock(lockPath, options = {}) {
+    const breakLock = options.breakLock === true;
+    const isRunning = options.isRunning ?? processRunning;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const record = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString(), id: randomUUID() }) + '\n';
+    if (await createLock(lockPath, record))
+        return record;
+    const guard = `${lockPath}.reclaim`;
+    await takeReclaimGuard(guard, lockPath, breakLock, sleep);
+    try {
+        // Read the lock only once the guard is held: an updater that reclaimed it first has already
+        // replaced it with its own record, which then names a live process.
+        let recorded;
+        try {
+            recorded = await readFile(lockPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (recorded === undefined) {
+            if (await createLock(lockPath, record))
+                return record;
+            throw new Error(`Another update took the lock at ${lockPath} while this one was checking it. Wait for it to finish.`);
+        }
+        const owner = lockOwner(recorded);
+        const holder = owner ? `process ${owner.pid}${owner.startedAt ? `, started ${owner.startedAt}` : ''}` : undefined;
+        const stale = owner !== undefined && owner.pid !== process.pid && !isRunning(owner.pid);
+        if (!stale && !breakLock) {
+            throw new Error(holder
+                ? `Another update (${holder}) is running and holds ${lockPath}. Wait for it to finish. If that process is not an Andorra update, rerun with andorra update --break-lock.`
+                : `An update lock at ${lockPath} does not record which process holds it, so it cannot be checked. If no update is running, rerun with andorra update --break-lock.`);
+        }
+        // Replace the lock in one rename, so the path never disappears and a new updater's exclusive
+        // create keeps failing throughout.
+        const staged = await stageRecord(lockPath, record);
+        try {
+            await rename(staged, lockPath);
+        }
+        catch (error) {
+            await unlink(staged).catch(() => { });
+            throw error;
+        }
+        options.notify?.(stale
+            ? `Removed a stale update lock left by ${holder}, which is no longer running.`
+            : `Broke the update lock at ${lockPath}${holder ? ` held by ${holder}` : ''}.`);
+        return record;
+    }
+    finally {
+        await unlink(guard).catch(() => { });
+    }
+}
+/**
+ * Remove the lock only while it still holds this updater's record; --break-lock may have replaced
+ * it. The reclaim guard is held across the read and the unlink, because a replacement lands only
+ * under that guard and must not arrive in between.
+ */
+async function releaseUpdateLock(lockPath, record, sleep) {
+    const guard = `${lockPath}.reclaim`;
+    // A guard that is never released leaves this lock behind instead of failing the update: it
+    // names this process, which is about to exit, so the next update reclaims it as stale.
+    try {
+        await takeReclaimGuard(guard, lockPath, false, sleep);
+    }
+    catch {
+        return;
+    }
+    try {
+        let current;
+        try {
+            current = await readFile(lockPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (current === record)
+            await unlink(lockPath);
+    }
+    finally {
+        await unlink(guard).catch(() => { });
+    }
+}
+/** Update the linked installation checkout, never the caller's working directory. */
+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 modulePath = await realpath(fileURLToPath(options.moduleUrl ?? import.meta.url));
+    const checkout = await realpath(resolve(dirname(modulePath), '..', '..'));
+    let packageName;
+    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.');
+    }
+    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());
+    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.');
+        }
+        try {
+            await run('git', ['merge-base', '--is-ancestor', 'HEAD', fetched], checkout);
+            await run('git', ['merge', '--ff-only', fetched], checkout);
+        }
+        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}`);
+        }
+        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));
+            }
+        }
+        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 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.`;
+    }
+    finally {
+        await releaseUpdateLock(lockPath, lock, sleep);
+    }
+}

package/dist/src/usage-analytics.d.ts

@@ -0,0 +1,48 @@
+export interface UsageModelRow {
+    /** The raw provider id the calls were journaled under; the aggregation identity. */
+    providerId: string;
+    /** The display name the configuration resolves the id to; `providerId` when it cannot. */
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+}
+export interface UsageDayRow {
+    date: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+    models: UsageModelRow[];
+}
+export interface UsageAnalytics {
+    days: UsageDayRow[];
+    models: UsageModelRow[];
+    totals: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheRead: number;
+        savedInputEstimate: number;
+        bypassedTurns: number;
+        unestimatedTurns: number;
+    };
+    incomplete: boolean;
+    filesScanned: number;
+    windowDays: number;
+}
+/** A streaming collector, also usable with synthetic records in regression tests. */
+export declare function createUsageCollector(windowDays: number, now?: Date, resolveProvider?: (providerId: string) => string): {
+    add(record: unknown): void;
+    finish(filesScanned?: number, incomplete?: boolean): UsageAnalytics;
+};
+/**
+ * Local-only read, bounded by modified time, file count and record size, served from a per-file
+ * cache of the records the collector consumes. The replay visits the captured records in the same
+ * order a full read would — files sorted by name, lines in file order — so the answer is the one
+ * the equivalent full scan produces, whatever the cache happened to hold.
+ */
+export declare function readUsageAnalytics(directory: string, windowDays: number): Promise<UsageAnalytics>;