@timurproko/a1 0.2.7-dev.820 → 0.2.7-dev.828

package/dist/foundation/release/update.js

@@ -5,6 +5,7 @@ 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 { certifyMaterializedRelease, ensureSupervisor, waitForProcessExit, } from "./bootstrap.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 } 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,7 @@ 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;
 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 +88,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 +129,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 +251,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 +274,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) {
@@ -455,9 +476,58 @@ 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.runner, 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) {
+    const lease = await acquireUpdateExecutionLease(input);
+    if (lease.status === "busy") {
+        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 +544,14 @@ 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 resolved = await measure("target-resolution", async () => await resolveSelfUpdateTarget({
+        runner, output, channel, distTag, requested, exactTarget,
+    }));
     if (resolved.version === null)
         return resolved.exitCode;
     const targetVersion = resolved.version;
@@ -506,178 +566,185 @@ 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 environment = options.environment ?? process.env;
+    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 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;
         }
-        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 +844,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/bridge-client.d.ts

@@ -1,8 +1,11 @@
+import { type ResidentTabRoute } from "./routes.js";
 export type ResidentTabStatus = "starting" | "working" | "needs-input" | "done-unseen" | "done" | "aborted" | "error" | "idle" | "unresponsive" | "crashed" | "restarting" | "failed";
+export { residentUtilityRoute, type ResidentTabRoute } from "./routes.js";
 export interface TabBridgeCredentials {
     readonly tabId: string;
     readonly token: string;
     readonly endpoint: string;
+    readonly releaseId?: string;
 }
 export interface TabAttachment {
     readonly clientId: string;
@@ -17,7 +20,7 @@ export type TabBridgeCommand = {
     readonly nameSource: "default" | "user" | "auto";
 } | {
     readonly type: "route";
-    readonly route: "settings";
+    readonly route: ResidentTabRoute;
 } | {
     readonly type: "stop";
     readonly deadlineMs: number;
@@ -59,5 +62,9 @@ export declare class TabBridgeClient {
     requestClose(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
     consumeControllerBoundaryInput(data: string): string;
     close(): void;
+    /**
+     * Asks the server to act for the client that controls this tab, as `origin`: leave it, restart or close the tab,
+     * or open the tab bar's Plus Menu dialog (`configure-plus`).
+     */
+    requestAction(action: "detach" | "restart" | "close" | "configure-plus", origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
 }
-export {};

package/dist/foundation/resident-tabs/bridge-client.js

@@ -1,5 +1,8 @@
 import { connect } from "node:net";
 import { encodeResidentFrame, ResidentFrameDecoder } from "./protocol.js";
+import { RESIDENT_TAB_ROUTES } from "./routes.js";
+export { residentUtilityRoute } from "./routes.js";
+const RESIDENT_TAB_ROUTE_SET = new Set(RESIDENT_TAB_ROUTES);
 /** Metadata-only advisory bridge. Terminal input and transcript bytes have no API here. */
 export class TabBridgeClient {
     #options;
@@ -67,7 +70,7 @@ export class TabBridgeClient {
             this.#startWaiter = finish;
             transport.once("connect", () => {
                 this.#send("hello", {
-                    role: "bridge", generation: 1, build: this.#options.build ?? "a1",
+                    role: "bridge", generation: 1, build: this.#options.build ?? "a1", releaseId: this.#options.credentials.releaseId,
                     features: ["bridge-status", "bridge-detach", "bridge-heartbeat", "bridge-restart", "bridge-visibility", "bridge-rename", "bridge-route", "bridge-stop", "bridge-shortcuts", "controller-boundary", "recovery-journal"],
                     token: [...Buffer.from(this.#options.credentials.token, "base64")], tabId: this.#options.credentials.tabId,
                     pid: this.#options.pid ?? process.pid, startIdentity: this.#options.startIdentity ?? `${process.pid}:node`,
@@ -118,13 +121,13 @@ export class TabBridgeClient {
         this.#send("bridge.shortcuts", { assignments: this.#latestShortcuts.map(([action, key]) => [action, key]) });
     }
     requestDetach(origin = this.captureAttachment(), timeoutMs = 1_000) {
-        return this.#requestAction("detach", origin, timeoutMs);
+        return this.requestAction("detach", origin, timeoutMs);
     }
     requestRestart(origin = this.captureAttachment(), timeoutMs = 1_000) {
-        return this.#requestAction("restart", origin, timeoutMs);
+        return this.requestAction("restart", origin, timeoutMs);
     }
     requestClose(origin = this.captureAttachment(), timeoutMs = 1_000) {
-        return this.#requestAction("close", origin, timeoutMs);
+        return this.requestAction("close", origin, timeoutMs);
     }
     consumeControllerBoundaryInput(data) {
         const prefix = "\x1bP+a1;controller=";
@@ -205,6 +208,11 @@ export class TabBridgeClient {
     }
     #receive(message) {
         if (message.type === "welcome" && message.body["generation"] === 1) {
+            const id = this.#options.credentials.releaseId;
+            if (id !== undefined && message.body["releaseId"] !== id) {
+                this.#fail(false);
+                return;
+            }
             const advertised = message.body["features"];
             this.#features = new Set(Array.isArray(advertised) ? advertised.filter((feature) => typeof feature === "string") : []);
             this.#connected = true;
@@ -232,8 +240,8 @@ export class TabBridgeClient {
             this.#emitCommand({ type: "rename", name: message.body["name"], nameSource: source === "auto" || source === "default" ? source : "user" });
             return;
         }
-        if (message.type === "bridge.route" && message.body["route"] === "settings") {
-            this.#emitCommand({ type: "route", route: "settings" });
+        if (message.type === "bridge.route" && RESIDENT_TAB_ROUTE_SET.has(message.body["route"])) {
+            this.#emitCommand({ type: "route", route: message.body["route"] });
             return;
         }
         if (message.type === "bridge.stop" && typeof message.body["deadlineMs"] === "number") {
@@ -255,7 +263,11 @@ export class TabBridgeClient {
             }
         }
     }
-    async #requestAction(action, origin, timeoutMs) {
+    /**
+     * Asks the server to act for the client that controls this tab, as `origin`: leave it, restart or close the tab,
+     * or open the tab bar's Plus Menu dialog (`configure-plus`).
+     */
+    async requestAction(action, origin = this.captureAttachment(), timeoutMs = 1_000) {
         if (!this.available || origin === null || (action === "restart" && !this.#supports("bridge-restart")))
             return false;
         const requestId = ++this.#request;