@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/foundation/release/update.js

@@ -5,8 +5,9 @@ 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 { earlyAccentPalette, earlyTerminalAppearance, earlyTerminalColorMode, resolveEarlyAccentColor } from "./early-accent.js";
 import { SHARED_PROGRESS_ACCENT_ANSI } from "./progress-palette.generated.js";
-import { isNewerRelease, releaseChannelOf } from "./latest-release.js";
+import { createRegistryFetcher, invalidateReleaseCheckCache, isNewerRelease, queryPublishedVersions, releaseChannelOf, } from "./latest-release.js";
 import { certifyMaterializedRelease, ensureSupervisor, waitForProcessExit, } from "./bootstrap.js";
 import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts } from "./endpoints.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
@@ -17,6 +18,7 @@ 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 { acquireUpdateExecutionLease, reclaimDeadLease } from "./update-execution-lease.js";
 import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, resolveNpmCli, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
@@ -34,6 +36,9 @@ const defaultFileSystem = {
  * The update therefore keeps checking for this long before it calls the package locked.
  */
 export const PACKAGE_UNLOCK_PATIENCE_MS = 15_000;
+export const UPDATE_ALREADY_RUNNING_EXIT_CODE = 75;
+/** A named preview reads the registry's whole package document, which is larger than a dist-tag lookup. */
+const PREVIEW_LOOKUP_TIMEOUT_MS = 30_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
@@ -85,6 +90,21 @@ export function createNpmProcessRunner(platform = process.platform) {
  * 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.
  */
+async function verifyAutomaticUpdateSafety(paths, stateStore, environment) {
+    const state = await stateStore.read();
+    const owner = await readActiveEndpoint(paths, state.references.active, environment);
+    if (!owner)
+        return;
+    const ownership = await probeOwnership(owner.metadata);
+    if (ownership === "dead")
+        return;
+    if (ownership !== "live-verified") {
+        throw new UpdateAutomaticDeferred(PRODUCT_TEXT.diagnostic(`automatic update deferred because supervisor ownership is ${ownership}`));
+    }
+    if (!await canonicalImmutableRoot(paths.dataDir, owner.metadata.releaseRoot)) {
+        throw new UpdateAutomaticDeferred(PRODUCT_TEXT.diagnostic("automatic update deferred because the running session is not using a retained immutable release; run the update command manually"));
+    }
+}
 export function planUpdateOwnership(ownership, runsFromRetainedRelease) {
     if (ownership === "dead")
         return "clean-dead-record";
@@ -111,13 +131,13 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
     const stateStore = new CohortStateStore(paths.dataDir);
     return {
         async targetIsActive(targetVersion) {
-            const state = await stateStore.read();
-            const activeId = state.references.active;
+            const state = await stateStore.read(), 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 verifyAutomaticSafety() { await verifyAutomaticUpdateSafety(paths, stateStore, environment); },
         async shutdownVerifiedOwners(targetVersion) {
             const state = await stateStore.read();
             const activeId = state.references.active;
@@ -233,16 +253,19 @@ const ACTIVATION_PROGRESS = {
     "active-reference-committed": { at: 96, creepTo: 99 },
 };
 /** Renders the terminal-only update meter; the visual preview shares this exact frame. */
-export function renderUpdateProgressBar(percent) {
+export function renderUpdateProgressBar(percent, accent = SHARED_PROGRESS_ACCENT_ANSI) {
     const bounded = Math.min(100, Math.max(0, Math.round(percent)));
     const filled = Math.round((bounded / 100) * PROGRESS_BAR_WIDTH);
-    // Rationale: the completed run follows the pinned Pi controls' semantic accent,
-    // while the track and percentage retain the update meter's neutral treatment.
+    // Rationale: the completed run follows the A1 profile accent; the track and
+    // percentage retain the update meter's neutral treatment.
     const gray = "\u001b[38;2;128;128;128m";
     const track = "\u001b[38;2;102;102;102m";
-    return `${SHARED_PROGRESS_ACCENT_ANSI}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
+    return `${accent}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
+}
+function updateProgressAccent(environment) {
+    return earlyAccentPalette(resolveEarlyAccentColor(environment), earlyTerminalAppearance(environment), earlyTerminalColorMode(environment)).accent;
 }
-function createUpdateProgress(output, enabled) {
+function createUpdateProgress(output, enabled, accent = SHARED_PROGRESS_ACCENT_ANSI) {
     let visible = false;
     let current = 0;
     let shown = -1;
@@ -253,7 +276,7 @@ function createUpdateProgress(output, enabled) {
             return;
         shown = rounded;
         visible = true;
-        output.stdout(`\r${renderUpdateProgressBar(rounded)}`);
+        output.stdout(`\r${renderUpdateProgressBar(rounded, accent)}`);
     };
     const stopCreep = () => {
         if (timer !== null) {
@@ -320,35 +343,28 @@ async function resolveChannelHead(runner, distTag, output) {
 /**
  * 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.
+ * A decimal names the pull request a published preview records in its manifest, or the trailing
+ * number of a preview published as `<version>-dev.<pull-request>` before pull requests were
+ * recorded; a full version is accepted too. The registry's published manifests remain
+ * 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`);
+async function resolveRequestedPreview(fetcher, registry, requested, output) {
+    const published = await queryPublishedVersions(fetcher, registry);
+    if (published.error !== null) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not list the published versions: ${published.error}.`)}\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);
+    const exact = published.versions.find(entry => entry.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`);
+        if (!exact.version.includes("-dev.")) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`${exact.version} 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 };
+        return { version: exact.version, exitCode: 0 };
     }
-    const matches = versions.filter(version => version.endsWith(`-dev.${requested}`));
+    const matches = previewsNumbered(published.versions, requested);
     if (matches.length === 1)
         return { version: matches[0], exitCode: 0 };
     if (matches.length > 1) {
@@ -358,6 +374,13 @@ async function resolveRequestedPreview(runner, requested, output) {
     output.stderr(`${PRODUCT_TEXT.diagnostic(`published no preview for ${requested}.`)}\n`);
     return { version: null, exitCode: 1 };
 }
+/** The published versions a preview number names: by recorded pull request, or by trailing identifier. */
+function previewsNumbered(versions, requested) {
+    const number = Number(requested);
+    return versions
+        .filter(entry => entry.pullRequest === number || entry.version.endsWith(`-dev.${requested}`))
+        .map(entry => entry.version);
+}
 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)
@@ -455,9 +478,72 @@ async function launchersOwnPackage(globalRoot, fileSystem) {
         return false;
     }
 }
+async function resolveSelfUpdateTarget(input) {
+    if (input.exactTarget !== undefined && input.exactTarget.length > 0) {
+        return resolveExactAutomaticTarget(input.exactTarget, input.channel, input.output);
+    }
+    return input.requested === undefined || input.requested.length === 0
+        ? await resolveChannelHead(input.runner, input.distTag, input.output)
+        : await resolveRequestedPreview(input.fetcher ?? createRegistryFetcher(PREVIEW_LOOKUP_TIMEOUT_MS), input.registry?.trim() || undefined, input.requested, input.output);
+}
+function resolveExactAutomaticTarget(target, channel, output) {
+    const version = validSemver(target);
+    const expected = channel === "stable" ? "stable" : "development";
+    if (version === null || releaseChannelOf(version) !== expected) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`refused invalid automatic ${expected} update target ${JSON.stringify(target)}`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    return { version, exitCode: 0 };
+}
 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`);
 }
+async function withUpdateExecutionLease(input, options, output, operation) {
+    let lease = await acquireUpdateExecutionLease(input);
+    if (lease.status === "interrupted") {
+        // Rationale: the owner that targeted another version is gone. Its durable transaction is rolled
+        // back to the cohort that ran before it, so this request proceeds as an ordinary update of its
+        // own target instead of reporting a dead attempt as in progress.
+        const interrupted = lease.owner.targetVersion;
+        const rollback = await rollbackPriorCohort(input.dataDir, options.environment ?? process.env, lease.transaction.priorActiveReleaseId)
+            .catch(error => `rollback failed: ${errorMessage(error)}`);
+        const store = new UpdateTransactionStore(input.dataDir);
+        await store.finish("rolled-back", `interrupted ${interrupted} update settled by ${input.targetVersion}; ${rollback}`);
+        await store.clearCompleted().catch(() => undefined);
+        await reclaimDeadLease(input.dataDir, lease.owner);
+        output.stdout(`${PRODUCT_TEXT.commandName} rolled back the interrupted ${interrupted} update: ${rollback}\n`);
+        lease = await acquireUpdateExecutionLease(input);
+    }
+    if (lease.status !== "acquired") {
+        options.onLeaseBusy?.(lease.owner);
+        if ((options.mode ?? "manual") === "manual") {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`update already in progress for ${lease.owner.targetVersion}`)}\n`);
+        }
+        return UPDATE_ALREADY_RUNNING_EXIT_CODE;
+    }
+    try {
+        options.onLeaseAcquired?.(lease.owner);
+        return await operation();
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function readRunningPackageVersion(packageRoot, fileSystem, output) {
+    try {
+        const packageJson = JSON.parse(await fileSystem.readFile(resolve(packageRoot, "package.json")));
+        const version = typeof packageJson.version === "string" ? validSemver(packageJson.version) : null;
+        if (packageJson.name !== PRODUCT_PACKAGE)
+            throw new Error(`package.json does not identify ${PRODUCT_PACKAGE}`);
+        if (version === null)
+            throw new Error("package.json does not contain a valid semantic version");
+        return version;
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its running package version: ${errorMessage(error)}`)}\n`);
+        return null;
+    }
+}
 export async function runSelfUpdate(options) {
     const fileSystem = options.fileSystem ?? defaultFileSystem;
     const output = options.output ?? defaultOutput;
@@ -474,24 +560,15 @@ export async function runSelfUpdate(options) {
             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`);
+    const runningVersion = await measure("package-version", async () => await readRunningPackageVersion(options.packageRoot, fileSystem, output));
+    if (runningVersion === null)
         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));
+    const exactTarget = options.resolvedTarget?.trim();
+    const environment = options.environment ?? process.env;
+    const resolved = await measure("target-resolution", async () => await resolveSelfUpdateTarget({
+        runner, output, channel, distTag, requested, exactTarget, fetcher: options.fetcher, registry: environment.npm_config_registry,
+    }));
     if (resolved.version === null)
         return resolved.exitCode;
     const targetVersion = resolved.version;
@@ -506,178 +583,184 @@ export async function runSelfUpdate(options) {
     // 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 progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true), updateProgressAccent(environment));
     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 mode = options.mode ?? "manual";
     const maintenance = options.maintenance ?? (options.lifecycle
         ? async () => { }
         : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
-    let transaction = await transactionStore.read();
-    let npmCli;
-    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;
-        }
-        const preflightRequired = options.npmCliResolver !== undefined
-            || options.packageReplacement === undefined && options.runner === undefined;
-        if (preflightRequired) {
-            try {
-                npmCli = await (options.npmCliResolver ?? resolveNpmCli)(npmCliRoot, environment);
+    return await withUpdateExecutionLease({ dataDir: paths.dataDir, packageRoot, channel, targetVersion, mode }, options, output, async () => {
+        let transaction = await transactionStore.read();
+        let npmCli;
+        try {
+            if (mode === "automatic")
+                await lifecycle.verifyAutomaticSafety?.();
+            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;
             }
-            catch (error) {
-                throw new UpdatePreflightFailure(errorMessage(error));
+            const preflightRequired = options.npmCliResolver !== undefined
+                || options.packageReplacement === undefined && options.runner === undefined;
+            if (preflightRequired) {
+                try {
+                    npmCli = await (options.npmCliResolver ?? resolveNpmCli)(npmCliRoot, environment);
+                }
+                catch (error) {
+                    throw new UpdatePreflightFailure(errorMessage(error));
+                }
             }
-        }
-        // Rationale: the bar first appears only after every non-mutating replacement prerequisite passes.
-        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);
+            // Rationale: the bar first appears only after every non-mutating replacement prerequisite passes.
+            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,
             });
-            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"));
+            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,
+                        ...(npmCli === undefined ? {} : { npmCli }),
+                        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)}`);
+                    }
                 }
-                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,
-                    ...(npmCli === undefined ? {} : { npmCli }),
-                    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")
+                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");
-                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)}`);
+            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);
                 }
-                transaction = await transactionStore.advance("package-installed");
-            }
+                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 Promise.all([transactionStore.clearCompleted(), invalidateReleaseCheckCache(paths.configDir)]).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;
         }
-        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);
+        catch (error) {
+            progress.clear();
+            const message = errorMessage(error);
+            if (error instanceof UpdateAutomaticDeferred)
+                return 1;
+            if (error instanceof UpdatePreflightFailure) {
+                output.stderr(`${PRODUCT_TEXT.diagnostic(`update could not start safely: ${message}. Nothing was changed. Retry with npm x -y -- ${PRODUCT_PACKAGE}-install`)}\n`);
+                return 1;
             }
-        });
-        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);
-        if (error instanceof UpdatePreflightFailure) {
-            output.stderr(`${PRODUCT_TEXT.diagnostic(`update could not start safely: ${message}. Nothing was changed. Retry with npm x -y -- ${PRODUCT_PACKAGE}-install`)}\n`);
-            return 1;
+            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;
         }
-        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 = [];
@@ -777,6 +860,8 @@ class UpdateFailure extends Error {
 }
 class UpdatePreflightFailure extends Error {
 }
+class UpdateAutomaticDeferred extends Error {
+}
 async function canonicalImmutableRoot(dataDir, releaseRoot) {
     try {
         const [store, selected] = await Promise.all([realpath(resolve(dataDir, "releases")), realpath(releaseRoot)]);

package/dist/foundation/resident-tabs/bounded-host-command.d.ts

@@ -0,0 +1,18 @@
+import type { TerminalHostCommand } from "./ensure-terminal-host.js";
+export interface BoundedHostCommandResult {
+    readonly code: number;
+    readonly stdout: string;
+}
+export interface BoundedHostCommandLimits {
+    /** Output beyond this many bytes fails the exchange instead of being parsed. */
+    readonly maxStdoutBytes: number;
+    readonly timeoutMs: number;
+    /** Names the exchange in the timeout error. */
+    readonly label: string;
+    readonly environment?: NodeJS.ProcessEnv;
+}
+/**
+ * Runs one terminal-host command whose report is small. An oversized report kills the command and
+ * reports a failed exchange; a command that outlives its deadline is killed and rejected.
+ */
+export declare function runBoundedHostCommand(command: TerminalHostCommand, arguments_: readonly string[], limits: BoundedHostCommandLimits): Promise<BoundedHostCommandResult>;