@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/foundation/release/update.js

@@ -0,0 +1,773 @@
+import { spawn } from "node:child_process";
+import { access, lstat, readFile, realpath, rename } from "node:fs/promises";
+import { connect } from "node:net";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import crossSpawn from "cross-spawn";
+import { valid as validSemver } from "semver";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { certifyMaterializedRelease, ensureSupervisor, waitForProcessExit, } from "./bootstrap.js";
+import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts } from "./endpoints.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
+import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { CohortStateStore } from "./cohort-state.js";
+import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
+import { materializeRelease, readMaterializedRelease } from "./release-store.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
+import { UPDATE_ACTIVATION_CONTRACT, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
+export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
+const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
+const defaultFileSystem = {
+    async readFile(path) { return await readFile(path, "utf8"); },
+    realpath,
+    lstat,
+    access,
+    rename,
+};
+/**
+ * The package tree is checked for holders by renaming it and renaming it back, because on
+ * Windows that is the one operation that fails while any file under it is open. A holder is
+ * usually brief: a scanner, an indexer, a file browser, or a session still shutting down.
+ * The update therefore keeps checking for this long before it calls the package locked.
+ */
+export const PACKAGE_UNLOCK_PATIENCE_MS = 15_000;
+const PACKAGE_UNLOCK_INITIAL_DELAY_MS = 100;
+const PACKAGE_UNLOCK_MAX_DELAY_MS = 1_000;
+// Platform: Windows reports a held directory as EPERM or EBUSY; EACCES and ENOTEMPTY are the other
+// spellings a rename gives to a tree something is using. Anything else is not a lock.
+const PACKAGE_LOCK_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY"]);
+const defaultSleep = async (durationMs) => await new Promise(resolvePromise => setTimeout(resolvePromise, durationMs));
+/** Whether a rename failure means something holds the tree, as opposed to the tree being wrong. */
+export function isPackageLockError(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" && PACKAGE_LOCK_CODES.has(error.code);
+}
+/** What the user reads when the package stayed held for the whole patience window. */
+export function lockedPackageDiagnostic(packageRoot, waitedMs, attempts, error) {
+    const seconds = Math.max(1, Math.round(waitedMs / 1_000));
+    return PRODUCT_TEXT.diagnostic(`package remained locked for ${seconds}s after verified shutdown (${attempts} checks): ${errorMessage(error)}. `
+        + `Another program is holding a file under ${packageRoot}: an antivirus scan, a file browser or terminal open inside it, `
+        + `or a session still shutting down. Close it and run the update again; nothing was changed.`);
+}
+const defaultOutput = {
+    stdout(message) { process.stdout.write(message); },
+    stderr(message) { process.stderr.write(message); },
+};
+/** Bound on the child diagnostics an update keeps: enough for npm's failure reason, never a log. */
+export const CHILD_DIAGNOSTIC_LIMIT = 8_000;
+export function createNpmProcessRunner(platform = process.platform) {
+    return async (command, arguments_, request) => await new Promise((resolvePromise, rejectPromise) => {
+        // Invariant: no child of the updater shares the terminal. The progress bar is the only
+        // live output; a child's own text is kept, bounded, and shown with a failure or not at all.
+        const stdio = ["ignore", request.captureStdout ? "pipe" : "ignore", "pipe"];
+        const child = platform === "win32" ? crossSpawn(command, [...arguments_], { stdio }) : spawn(command, [...arguments_], { stdio });
+        const stdout = [];
+        let stderr = "";
+        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", chunk => { stderr = `${stderr}${chunk}`.slice(-CHILD_DIAGNOSTIC_LIMIT); });
+        let settled = false;
+        child.once("error", error => { if (!settled) {
+            settled = true;
+            rejectPromise(error);
+        } });
+        child.once("close", code => { if (!settled) {
+            settled = true;
+            resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8"), stderr });
+        } });
+    });
+}
+/**
+ * What an update does about the owner it found. A cohort running from retained immutable
+ * content keeps its work: the installation replaces files it does not read, and it listens on
+ * its own endpoint. A cohort running from the mutable installation is the one exception,
+ * because that installation is exactly what is about to be replaced under it.
+ */
+export function planUpdateOwnership(ownership, runsFromRetainedRelease) {
+    if (ownership === "dead")
+        return "clean-dead-record";
+    return runsFromRetainedRelease ? "leave-running" : "end-session";
+}
+/**
+ * The endpoint of the active cohort, together with where it is recorded, so a caller that
+ * finds it can also clean it up. A release that predates cohort-scoped endpoints published
+ * one endpoint for the runtime directory, and that one is recognized too.
+ */
+async function readActiveEndpoint(paths, activeReleaseId, environment) {
+    if (activeReleaseId !== null) {
+        const cohort = resolveCohortEndpoint(paths, activeReleaseId, environment);
+        const metadata = await readEndpointMetadata(cohort.endpointMetadataPath);
+        if (metadata)
+            return { metadata, paths: cohort };
+    }
+    const legacyPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+    const legacy = await readEndpointMetadata(legacyPaths.endpointMetadataPath);
+    return legacy ? { metadata: legacy, paths: legacyPaths } : null;
+}
+export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, output = defaultOutput, patience = {}) {
+    const paths = resolveProductPaths(environment);
+    const stateStore = new CohortStateStore(paths.dataDir);
+    return {
+        async targetIsActive(targetVersion) {
+            const state = await stateStore.read();
+            const activeId = state.references.active;
+            if (!activeId || state.releases[activeId]?.packageVersion !== targetVersion)
+                return false;
+            const endpoint = await readActiveEndpoint(paths, activeId, environment);
+            return endpoint?.metadata.releaseId === activeId && await probeOwnership(endpoint.metadata) === "live-verified";
+        },
+        async shutdownVerifiedOwners(targetVersion) {
+            const state = await stateStore.read();
+            const activeId = state.references.active;
+            const priorActiveVersion = activeId ? state.releases[activeId]?.packageVersion ?? null : null;
+            const owner = await readActiveEndpoint(paths, activeId, environment);
+            if (!owner)
+                return { priorActiveVersion };
+            const endpoint = owner.metadata;
+            const ownership = await probeOwnership(endpoint);
+            if (ownership !== "live-verified" && ownership !== "dead") {
+                throw new Error(PRODUCT_TEXT.diagnostic(`refused update shutdown because supervisor ownership is ${ownership}`));
+            }
+            const plan = planUpdateOwnership(ownership, await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot));
+            if (plan === "clean-dead-record") {
+                await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
+                return { priorActiveVersion };
+            }
+            // Rationale: leaving sessions alone is the expected outcome, and saying so mid-update tears
+            // the progress bar; only ending a session (below) is worth interrupting it for.
+            if (plan === "leave-running")
+                return { priorActiveVersion };
+            // Rationale: say whose work is ending before it ends.
+            const live = endpoint.ownership.liveInstanceIds.length;
+            if (live > 0) {
+                output.stderr(`${PRODUCT_TEXT.diagnostic(`ending ${live === 1 ? "one session" : `${live} sessions`} that run from the installation being replaced; a session started by an installed release would have been left alone.`)}\n`);
+            }
+            const identity = await requestUpdateShutdown(endpoint, targetVersion, 2_000);
+            if (!identity.accepted && processIsAlive(endpoint.pid)) {
+                // Security: explicit update consent permits bounded cleanup of an authenticated
+                // older owner that predates the update-shutdown message.
+                const cleanup = await cleanupVerifiedOwner(endpoint, { allowLiveInstances: true, reason: "legacy-mutable-install" });
+                if (!cleanup.terminated)
+                    throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} rejected shutdown and could not be terminated: ${identity.reason}`);
+            }
+            else if (identity.accepted) {
+                await waitForProcessExit(endpoint.pid, 3_000).catch(async () => {
+                    const cleanup = await cleanupVerifiedOwner(endpoint, { allowLiveInstances: true, reason: "legacy-mutable-install" });
+                    if (!cleanup.terminated)
+                        throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} did not terminate`);
+                });
+            }
+            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
+            return { priorActiveVersion };
+        },
+        async verifyPackageUnlocked(packageRoot) {
+            if (fileSystem.access)
+                await fileSystem.access(packageRoot);
+            const probe = `${packageRoot}.${PRODUCT_IDENTITY.filesystem.slug}-unlock-probe`;
+            const renameTree = fileSystem.rename ?? rename;
+            const windowMs = patience.windowMs ?? PACKAGE_UNLOCK_PATIENCE_MS;
+            const now = patience.now ?? Date.now;
+            const sleep = patience.sleep ?? defaultSleep;
+            const startedAt = now();
+            let delay = PACKAGE_UNLOCK_INITIAL_DELAY_MS;
+            let attempts = 0;
+            // Rationale: a holder found right after ownership was released is almost always transient,
+            // so one failed rename is a reason to look again, not to abandon an update that has not
+            // yet changed anything. The wait is bounded so a genuine lock still fails clearly.
+            const withPatience = async (from, to, describeFailure) => {
+                while (true) {
+                    attempts += 1;
+                    try {
+                        await renameTree(from, to);
+                        return;
+                    }
+                    catch (error) {
+                        const elapsed = now() - startedAt;
+                        if (!isPackageLockError(error) || elapsed >= windowMs)
+                            throw describeFailure(error);
+                        // Rationale: the last pause is cut to the window's edge so the wait ends when promised.
+                        await sleep(Math.min(delay, windowMs - elapsed));
+                        delay = Math.min(PACKAGE_UNLOCK_MAX_DELAY_MS, delay * 2);
+                    }
+                }
+            };
+            await withPatience(packageRoot, probe, error => isPackageLockError(error)
+                ? new Error(lockedPackageDiagnostic(packageRoot, now() - startedAt, attempts, error))
+                : new Error(PRODUCT_TEXT.diagnostic(`could not verify that the package is unlocked: ${errorMessage(error)}`)));
+            // Invariant: the package tree is put back under its own name before this returns; a holder
+            // that appears while it wears the probe name is waited out the same way, and if it never
+            // lets go the diagnostic names where the tree is so the user can restore it.
+            await withPatience(probe, packageRoot, error => new Error(PRODUCT_TEXT.diagnostic(`could not restore the package after checking it was unlocked: ${errorMessage(error)}. The package is at ${probe}; rename it back to ${packageRoot} before running the update again.`)));
+        },
+        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing, onWarmup) {
+            const request = { packageRoot, dataDir: paths.dataDir, targetVersion, environment };
+            const callbacks = {
+                phase,
+                ...(onMaterializing ? { onMaterializing } : {}),
+                ...(onWarmup ? { onWarmup } : {}),
+            };
+            // Compatibility: the tree npm just installed is newer than this updater, so its layout is
+            // its own to know. A tree that serves the contract activates itself with its own code;
+            // a tree from before the contract is activated here, with the layout it had then.
+            const contracts = await readActivationContracts(packageRoot, fileSystem.readFile);
+            if (contracts.includes(UPDATE_ACTIVATION_CONTRACT))
+                await delegateActivation(request, callbacks);
+            else
+                await activateInstalledRelease(request, callbacks);
+        },
+    };
+}
+const PROGRESS_BAR_WIDTH = 40;
+const PROGRESS_TICK_MS = 200;
+/**
+ * Copying the release owns 78–92 and is reported file by file, so the bar crosses
+ * that span with the work rather than parking at its start. What follows is short,
+ * which is why the remaining milestones sit close together.
+ */
+const MATERIALIZE_PROGRESS = Object.freeze({ from: 78, to: 92 });
+const ACTIVATION_PROGRESS = {
+    materialized: { at: 92, creepTo: 94 },
+    certified: { at: 94, creepTo: 96 },
+    "active-reference-committed": { at: 96, creepTo: 99 },
+};
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export function renderUpdateProgressBar(percent) {
+    const bounded = Math.min(100, Math.max(0, Math.round(percent)));
+    const filled = Math.round((bounded / 100) * PROGRESS_BAR_WIDTH);
+    // Rationale: the completed run uses A1's scrollbar-aligned teal, followed by a
+    // darker gray track and one gray space before the percentage. Explicit RGB
+    // keeps each color stable even when the terminal remaps its ANSI palette.
+    const completed = "\u001b[38;2;138;190;183m";
+    const gray = "\u001b[38;2;128;128;128m";
+    const track = "\u001b[38;2;102;102;102m";
+    return `${completed}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
+}
+function createUpdateProgress(output, enabled) {
+    let visible = false;
+    let current = 0;
+    let shown = -1;
+    let timer = null;
+    const draw = () => {
+        const rounded = Math.round(current);
+        if (rounded === shown)
+            return;
+        shown = rounded;
+        visible = true;
+        output.stdout(`\r${renderUpdateProgressBar(rounded)}`);
+    };
+    const stopCreep = () => {
+        if (timer !== null) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+    return {
+        set(percent, creepTo = percent) {
+            if (!enabled)
+                return;
+            stopCreep();
+            current = Math.max(current, percent);
+            shown = -1;
+            draw();
+            if (creepTo <= current)
+                return;
+            // Rationale: creep asymptotically toward (but never reach) the next milestone so
+            // long opaque phases such as npm install still show visible motion. The
+            // ceiling stays a whole point below the milestone: settling on `creepTo`
+            // itself would render as that milestone and make arriving at it invisible,
+            // which is what a stalled bar looks like.
+            timer = setInterval(() => {
+                current = Math.min(creepTo - 1, current + (creepTo - current) * 0.04);
+                draw();
+            }, PROGRESS_TICK_MS);
+            timer.unref?.();
+        },
+        // Rationale: the bar exists to say the update is still moving. Once it has finished
+        // there is a better line to occupy that row — the one naming what is now
+        // installed — so the bar gives the row back rather than leaving a full
+        // meter above a message that already implies it.
+        finish() {
+            stopCreep();
+            if (!visible)
+                return;
+            output.stdout(`\r${" ".repeat(PROGRESS_BAR_WIDTH + 6)}\r`);
+            visible = false;
+            shown = -1;
+        },
+        clear() {
+            stopCreep();
+            if (!visible)
+                return;
+            output.stdout(`\r${" ".repeat(PROGRESS_BAR_WIDTH + 6)}\r`);
+            visible = false;
+            shown = -1;
+        },
+    };
+}
+/** The newest version the channel points at, which is what an unqualified update takes. */
+async function resolveChannelHead(runner, distTag, output) {
+    const publicChannel = distTag === "next" ? "development" : "release";
+    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${publicChannel} channel`);
+    if (lookup.result === null)
+        return { version: null, exitCode: lookup.exitCode };
+    const version = validSemver(lookup.result.stdout.trim());
+    if (version === null) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${publicChannel} channel version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    return { version, exitCode: 0 };
+}
+/**
+ * Resolve a preview the caller named.
+ *
+ * A preview is published as `<version>-dev.<pull-request-number>`, so its decimal
+ * development number is enough to identify it. A full version is accepted too.
+ * The published list remains authoritative: nothing is constructed from the
+ * installed package's base version.
+ */
+async function resolveRequestedPreview(runner, requested, output) {
+    const lookup = await runNpm(runner, ["view", PRODUCT_PACKAGE, "versions", "--json"], true, output, "list the published versions");
+    if (lookup.result === null)
+        return { version: null, exitCode: lookup.exitCode };
+    let published;
+    try {
+        published = JSON.parse(lookup.result.stdout.trim() || "[]");
+    }
+    catch {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed version list from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    const versions = (Array.isArray(published) ? published : [published]).filter((value) => typeof value === "string");
+    const exact = versions.find(version => version === requested);
+    if (exact !== undefined) {
+        // Rationale: naming a release here would install it through the preview path, which is a
+        // different command with a different meaning.
+        if (!exact.includes("-dev.")) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`${exact} is a release, not a preview; run ${PRODUCT_TEXT.commandName} update to move to the current release.`)}\n`);
+            return { version: null, exitCode: 1 };
+        }
+        return { version: exact, exitCode: 0 };
+    }
+    const matches = versions.filter(version => version.endsWith(`-dev.${requested}`));
+    if (matches.length === 1)
+        return { version: matches[0], exitCode: 0 };
+    if (matches.length > 1) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`found more than one preview for ${requested}: ${matches.join(", ")}. Name the version instead.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    output.stderr(`${PRODUCT_TEXT.diagnostic(`published no preview for ${requested}.`)}\n`);
+    return { version: null, exitCode: 1 };
+}
+async function resolveManagedNpmInstallation(requestedPackageRoot, fileSystem, runner, output) {
+    const rootLookup = await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root");
+    if (rootLookup.result === null)
+        return { installation: null, exitCode: rootLookup.exitCode };
+    const activeRootText = rootLookup.result.stdout.trim();
+    if (activeRootText.length === 0) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root.")}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    let packageRoot;
+    let activeGlobalRoot;
+    try {
+        [packageRoot, activeGlobalRoot] = await Promise.all([fileSystem.realpath(requestedPackageRoot), fileSystem.realpath(activeRootText)]);
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize the running and global npm paths: ${errorMessage(error)}`)}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    const expectedActivePackage = resolve(activeGlobalRoot, ...PRODUCT_PACKAGE.split("/"));
+    if (samePath(packageRoot, expectedActivePackage)) {
+        try {
+            npmPrefixForGlobalRoot(activeGlobalRoot);
+            return {
+                installation: {
+                    packageRoot,
+                    globalRoot: activeGlobalRoot,
+                    npmCliRoot: activeGlobalRoot,
+                },
+                exitCode: 0,
+            };
+        }
+        catch (error) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`could not verify npm's active global package layout: ${errorMessage(error)}`)}\n`);
+            return { installation: null, exitCode: 1 };
+        }
+    }
+    let candidateGlobalRoot = packageRoot;
+    for (const _segment of PRODUCT_PACKAGE.split("/"))
+        candidateGlobalRoot = dirname(candidateGlobalRoot);
+    let candidatePrefix;
+    try {
+        candidatePrefix = npmPrefixForGlobalRoot(candidateGlobalRoot);
+    }
+    catch {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    if (!samePath(packageRoot, resolve(candidateGlobalRoot, ...PRODUCT_PACKAGE.split("/")))) {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    const confirmation = await runNpm(runner, ["root", "--global", "--prefix", candidatePrefix], true, output, "confirm npm ownership of the running installation");
+    if (confirmation.result === null)
+        return { installation: null, exitCode: confirmation.exitCode };
+    const confirmedRootText = confirmation.result.stdout.trim();
+    if (confirmedRootText.length === 0) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root for the inferred prefix.")}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    let confirmedRoot;
+    try {
+        confirmedRoot = await fileSystem.realpath(confirmedRootText);
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize npm's confirmed global package root: ${errorMessage(error)}`)}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    if (!samePath(confirmedRoot, candidateGlobalRoot)
+        || !await launchersOwnPackage(candidateGlobalRoot, fileSystem)) {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    return {
+        installation: {
+            packageRoot,
+            globalRoot: candidateGlobalRoot,
+            npmCliRoot: activeGlobalRoot,
+        },
+        exitCode: 0,
+    };
+}
+async function launchersOwnPackage(globalRoot, fileSystem) {
+    const token = `node_modules/${PRODUCT_PACKAGE}/bin/cli.js`;
+    try {
+        for (const launcher of updateLauncherPaths(globalRoot)) {
+            const metadata = await (fileSystem.lstat ?? lstat)(launcher);
+            if (!metadata.isFile() || metadata.isSymbolicLink() || (process.platform !== "win32" && (metadata.mode & 0o111) === 0))
+                return false;
+            if (!(await fileSystem.readFile(launcher)).replaceAll("\\", "/").includes(token))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot) {
+    output.stderr(`${PRODUCT_TEXT.diagnostic(`refused to update automatically because ${packageRoot} could not be verified as an npm-managed ${PRODUCT_PACKAGE} installation; npm's active global package root is ${activeGlobalRoot}. Run npm install --global ${PRODUCT_PACKAGE} to install it manually.`)}\n`);
+}
+export async function runSelfUpdate(options) {
+    const fileSystem = options.fileSystem ?? defaultFileSystem;
+    const output = options.output ?? defaultOutput;
+    const runner = options.runner ?? createNpmProcessRunner();
+    const channel = options.channel ?? "stable";
+    const distTag = UPDATE_DIST_TAGS[channel];
+    const now = options.now ?? (() => performance.now());
+    const measure = async (phase, operation) => {
+        const startedAt = now();
+        try {
+            return await operation();
+        }
+        finally {
+            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - startedAt) });
+        }
+    };
+    let runningVersion;
+    try {
+        const packageJson = JSON.parse(await measure("package-version", async () => await fileSystem.readFile(resolve(options.packageRoot, "package.json"))));
+        const parsedVersion = typeof packageJson.version === "string" ? validSemver(packageJson.version) : null;
+        if (packageJson.name !== PRODUCT_PACKAGE)
+            throw new Error(`package.json does not identify ${PRODUCT_PACKAGE}`);
+        if (parsedVersion === null)
+            throw new Error("package.json does not contain a valid semantic version");
+        runningVersion = parsedVersion;
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its running package version: ${errorMessage(error)}`)}\n`);
+        return 1;
+    }
+    const requested = options.target?.trim();
+    const resolved = await measure("target-resolution", async () => requested === undefined || requested.length === 0
+        ? await resolveChannelHead(runner, distTag, output)
+        : await resolveRequestedPreview(runner, requested, output));
+    if (resolved.version === null)
+        return resolved.exitCode;
+    const targetVersion = resolved.version;
+    // Rationale: no full stop after a version: it already ends in a dot-separated identifier,
+    // and a trailing one reads as part of the version rather than as punctuation.
+    output.stdout(`${PRODUCT_TEXT.commandName} update: ${runningVersion} → ${targetVersion}\n`);
+    const progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true));
+    const managed = await measure("global-root", async () => await resolveManagedNpmInstallation(options.packageRoot, fileSystem, runner, output));
+    if (managed.installation === null)
+        return managed.exitCode;
+    const { packageRoot, globalRoot, npmCliRoot } = managed.installation;
+    const environment = options.environment ?? process.env;
+    const paths = resolveProductPaths(environment);
+    const lifecycle = options.lifecycle ?? createUpdateLifecycleCoordinator(environment, fileSystem, output);
+    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(paths.dataDir);
+    const maintenance = options.maintenance ?? (options.lifecycle
+        ? async () => { }
+        : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
+    let transaction = await transactionStore.read();
+    try {
+        if ((!transaction || transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
+            await maintenance();
+            await transactionStore.clearCompleted();
+            output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
+            return 0;
+        }
+        // Rationale: the bar first appears here so a no-change run never flashes it.
+        progress.set(3, 15);
+        const cohortStore = new CohortStateStore(paths.dataDir);
+        let cohortState = await cohortStore.read();
+        let priorActiveReleaseId = cohortState.references.active;
+        if (options.runner === undefined && (priorActiveReleaseId === null || cohortState.releases[priorActiveReleaseId]?.approval !== "approved")) {
+            // Invariant: protected replacement needs an immutable launch authority that npm cannot rename.
+            const recoveryRelease = await materializeRelease(packageRoot, paths.dataDir);
+            await cohortStore.recordCandidate(recoveryRelease);
+            const diagnostics = await certifyMaterializedRelease(recoveryRelease, paths.dataDir);
+            await cohortStore.approve(recoveryRelease.releaseId, diagnostics);
+            await cohortStore.activate(recoveryRelease.releaseId);
+            cohortState = await cohortStore.read();
+            priorActiveReleaseId = recoveryRelease.releaseId;
+        }
+        transaction = await transactionStore.begin({
+            channel,
+            targetVersion,
+            packageRoot,
+            priorActiveReleaseId,
+        });
+        if (phaseBefore(transaction.phase, "ownership-released")) {
+            await measure("ownership-release", async () => {
+                await lifecycle.shutdownVerifiedOwners(targetVersion);
+                await lifecycle.verifyPackageUnlocked(packageRoot);
+            });
+            transaction = await transactionStore.advance("ownership-released");
+        }
+        progress.set(15, 70);
+        if (phaseBefore(transaction.phase, "package-installed")) {
+            if (options.packageReplacement || options.runner === undefined) {
+                const priorReleaseId = transaction.priorActiveReleaseId ?? priorActiveReleaseId;
+                const recordedPrior = priorReleaseId === null ? undefined : cohortState.releases[priorReleaseId];
+                if ((!recordedPrior || recordedPrior.approval !== "approved") && !options.packageReplacement) {
+                    throw new Error(PRODUCT_TEXT.diagnostic("cannot protect package replacement because no approved prior release is available"));
+                }
+                const priorRelease = recordedPrior ?? {
+                    releaseId: priorReleaseId ?? "injected-prior-release",
+                    releaseRoot: packageRoot,
+                    contentDigest: "0".repeat(64),
+                };
+                const replacementTransaction = transaction;
+                const replacement = await measure("npm-install", async () => await (options.packageReplacement ?? runProtectedPackageReplacement)({
+                    dataDir: paths.dataDir,
+                    globalRoot,
+                    npmCliRoot,
+                    packageRoot,
+                    transaction: replacementTransaction,
+                    priorRelease,
+                    output,
+                    environment,
+                    onRecoveryState: async (recovery) => {
+                        if (transactionStore.setRecovery)
+                            transaction = await transactionStore.setRecovery(recovery) ?? transaction;
+                    },
+                }));
+                // Rationale: npm's own text explains a failed replacement and says nothing about a
+                // successful one, so it reaches the terminal only when the installation did not happen.
+                if (replacement.outcome !== "installed")
+                    reportChildDiagnostics(output, replacement);
+                if (replacement.outcome === "installed")
+                    transaction = await transactionStore.advance("package-installed");
+                if (replacement.cancelled) {
+                    progress.clear();
+                    output.stderr(`${PRODUCT_TEXT.diagnostic("update cancelled safely; the launcher is available and the transaction can be resumed.")}\n`);
+                    return 130;
+                }
+                if (replacement.outcome !== "installed") {
+                    throw new UpdateFailure(unsuccessfulCode(replacement.npmExitCode), `npm exited with status ${formatExitCode(replacement.npmExitCode)}`);
+                }
+            }
+            else {
+                const installation = await measure("npm-install", async () => await runNpm(runner, updateNpmInstallArguments(globalRoot, targetVersion), true, output, "start the global npm installation", false));
+                if (installation.result === null)
+                    throw new UpdateFailure(installation.exitCode, "npm process failed");
+                if (installation.result.code !== 0) {
+                    reportChildDiagnostics(output, installation.result);
+                    throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
+                }
+                transaction = await transactionStore.advance("package-installed");
+            }
+        }
+        progress.set(70, 75);
+        // Concurrency: ownership can be reacquired after an interrupted installation (for
+        // example, if bare A1 is launched before the update is resumed). Recheck
+        // immediately before activation so recovery cannot start a second cohort.
+        await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
+        progress.set(75, MATERIALIZE_PROGRESS.from);
+        let activationPhaseStartedAt = now();
+        await lifecycle.activateInstalled(packageRoot, targetVersion, async (phase) => {
+            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+            transaction = await transactionStore.advance(phase);
+            progress.set(ACTIVATION_PROGRESS[phase].at, ACTIVATION_PROGRESS[phase].creepTo);
+            activationPhaseStartedAt = now();
+        }, ({ completed, total }) => {
+            const span = MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from;
+            const done = total > 0 ? Math.min(1, completed / total) : 0;
+            progress.set(MATERIALIZE_PROGRESS.from + span * done);
+        }, state => {
+            if (state === "started") {
+                activationPhaseStartedAt = now();
+                progress.set(98, 99);
+            }
+            else {
+                options.onPhaseTiming?.({ phase: "warmup", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+                activationPhaseStartedAt = now();
+                progress.set(99);
+            }
+        });
+        options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+        const transactionStartedAt = now();
+        await transactionStore.advance("supervisor-verified");
+        if (transaction.recovery?.capsulePath)
+            await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId);
+        // Invariant: successful output follows the durable cleanup disposition. Slow recursive
+        // removal belongs to the detached worker started by this maintenance coordinator.
+        await maintenance();
+        // Concurrency: this is the launch cutover. No failure-prone update work follows success.
+        await transactionStore.finish("completed");
+        await transactionStore.clearCompleted().catch(() => undefined);
+        options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
+        progress.finish();
+        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully to ${targetVersion}\n`);
+        return 0;
+    }
+    catch (error) {
+        progress.clear();
+        const message = errorMessage(error);
+        const rollback = options.lifecycle
+            ? "previous test lifecycle retained"
+            : await rollbackPriorCohort(paths.dataDir, environment, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
+        if (transaction)
+            await transactionStore.finish(rollback === "rolled back" ? "rolled-back" : "failed", `${message}; ${rollback}`);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`update failed: ${message}. ${rollback}. Diagnostics: ${transactionStore.path}`)}\n`);
+        return error instanceof UpdateFailure ? error.exitCode : 1;
+    }
+}
+export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs = 30_000) {
+    const failures = [];
+    if (evidence.fileCount < 1)
+        failures.push("fixture contains no payload files");
+    if (evidence.sourceReads !== evidence.fileCount)
+        failures.push(`source payload read count is ${evidence.sourceReads} for ${evidence.fileCount} files`);
+    const totalWrites = evidence.candidateWrites + (evidence.layerWrites ?? 0);
+    if (totalWrites !== evidence.fileCount)
+        failures.push(`runtime payload write count is ${totalWrites} for ${evidence.fileCount} files`);
+    if (evidence.verificationReads > 0)
+        failures.push(`fresh certification reread ${evidence.verificationReads} candidate files`);
+    if (evidence.postNpmDurationMs > maximumPostNpmDurationMs)
+        failures.push(`post-npm activation took ${Math.round(evidence.postNpmDurationMs)}ms; budget is ${maximumPostNpmDurationMs}ms`);
+    if (failures.length > 0)
+        throw new Error(`update performance budget failed: ${failures.join("; ")}`);
+}
+async function requestUpdateShutdown(metadata, targetVersion, timeoutMs) {
+    if (!processIsAlive(metadata.pid))
+        return { accepted: false, reason: "recorded owner is dead" };
+    return await new Promise(resolvePromise => {
+        const socket = connect(metadata.endpoint);
+        const decoder = new LineFrameDecoder();
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolvePromise(value);
+        };
+        socket.once("error", () => finish({ accepted: false, reason: "verified endpoint did not respond" }));
+        socket.once("connect", () => socket.write(encodeFrame({ type: "release-update-ownership", bootNonce: metadata.bootNonce, targetVersion })));
+        socket.on("data", chunk => {
+            try {
+                const message = decoder.push(chunk)[0];
+                if (message?.type === "release-update-result")
+                    finish({ accepted: message.accepted === true, reason: String(message.reason ?? "shutdown rejected") });
+            }
+            catch {
+                finish({ accepted: false, reason: "invalid shutdown response" });
+            }
+        });
+        setTimeout(() => finish({ accepted: false, reason: "verified endpoint shutdown timed out" }), timeoutMs).unref();
+    });
+}
+async function runNpm(runner, arguments_, captureStdout, output, action, reportNonzero = true) {
+    let result;
+    try {
+        result = await runner("npm", arguments_, { captureStdout });
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not execute npm to ${action}: ${errorMessage(error)}`)}\n`);
+        return { result: null, exitCode: 1 };
+    }
+    if (result.code !== 0 && reportNonzero) {
+        const explained = reportChildDiagnostics(output, result);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not ${action}; npm exited with status ${formatExitCode(result.code)}.${explained ? " Review npm's diagnostics above." : ""}`)}\n`);
+        return { result: null, exitCode: unsuccessfulCode(result.code) };
+    }
+    return { result, exitCode: 0 };
+}
+/** Prints what a failed child said, bounded, and reports whether there was anything to print. */
+function reportChildDiagnostics(output, result) {
+    const text = [result.stdout, result.stderr ?? ""].map(part => part.trim()).filter(part => part.length > 0).join("\n").slice(-CHILD_DIAGNOSTIC_LIMIT);
+    if (text.length === 0)
+        return false;
+    output.stderr(`${text}\n`);
+    return true;
+}
+async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
+    if (!priorReleaseId)
+        return "no prior cohort was available for rollback";
+    const stateStore = new CohortStateStore(dataDir);
+    const state = await stateStore.read();
+    const prior = state.releases[priorReleaseId];
+    if (!prior || prior.approval !== "approved")
+        return "prior cohort is not a verified rollback candidate";
+    if (state.references.active !== priorReleaseId) {
+        if (state.references.rollback === priorReleaseId)
+            await stateStore.rollback(true);
+        else
+            throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
+    }
+    const release = await readMaterializedRelease(prior.releaseRoot);
+    // Invariant: rollback reuses a surviving prior cohort rather than racing its occupied endpoint.
+    await ensureSupervisor(release, environment);
+    return "rolled back";
+}
+function phaseBefore(current, target) {
+    const phases = ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed", "supervisor-verified"];
+    return phases.indexOf(current) < phases.indexOf(target);
+}
+class UpdateFailure extends Error {
+    exitCode;
+    constructor(exitCode, message) { super(message); this.exitCode = exitCode; }
+}
+async function canonicalImmutableRoot(dataDir, releaseRoot) {
+    try {
+        const [store, selected] = await Promise.all([realpath(resolve(dataDir, "releases")), realpath(releaseRoot)]);
+        const fromStore = relative(store, selected);
+        return fromStore.length > 0 && fromStore !== ".." && !fromStore.startsWith(`..${sep}`) && !isAbsolute(fromStore);
+    }
+    catch {
+        return false;
+    }
+}
+function samePath(left, right) {
+    return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
+function isContainedBy(parent, child) {
+    const pathFromParent = relative(parent, child);
+    return pathFromParent.length > 0 && pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
+}
+function unsuccessfulCode(code) { return code === null || code === 0 ? 1 : code; }
+function formatExitCode(code) { return code === null ? "unknown" : String(code); }
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }