@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/dist/{src/foundation → foundation}/release/update.js

@@ -5,22 +5,18 @@ import { 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, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, startSupervisor, waitForProcessExit, waitForVerifiedEndpoint, } from "./bootstrap.js";
-import { resolveProductPaths } from "../lifecycle/index.js";
+import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, ensureSupervisor, waitForProcessExit, } from "./bootstrap.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 { warmMaterializedRelease } from "./warmup.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
+import { removeUpdateRecoveryCapsule, runProtectedPackageReplacement } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
-/**
- * What each channel is called when A1 says it out loud. The internal name stays
- * `stable` because that is what the channel is, but what a reader is moving to is
- * a release, and that is the word the repository, its tags, and its GitHub
- * releases all use.
- */
-const UPDATE_CHANNEL_LABELS = { stable: "release", next: "next" };
 const defaultFileSystem = {
     async readFile(path) { return await readFile(path, "utf8"); },
     realpath,
@@ -47,6 +43,33 @@ export function createNpmProcessRunner(platform = process.platform) {
         } });
     });
 }
+/**
+ * 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) {
     const paths = resolveProductPaths(environment);
     const stateStore = new CohortStateStore(paths.dataDir);
@@ -56,45 +79,51 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const activeId = state.references.active;
             if (!activeId || state.releases[activeId]?.packageVersion !== targetVersion)
                 return false;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            return endpoint?.releaseId === activeId && await probeOwnership(endpoint) === "live-verified";
+            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 priorActiveVersion = state.references.active ? state.releases[state.references.active]?.packageVersion ?? null : null;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            if (!endpoint)
+            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 immutableRoot = await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot);
-            const legacyMutableInstall = ownership === "live-verified" && !immutableRoot;
-            const identity = ownership === "dead"
-                ? { accepted: false, reason: "recorded owner is dead" }
-                : await requestUpdateShutdown(endpoint, targetVersion, 2_000);
+            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)) {
-                // Explicit update consent permits bounded cleanup of an authenticated
+                // 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: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                });
+                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: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                    });
+                    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(paths.endpointMetadataPath, paths.endpoint);
+            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
             return { priorActiveVersion };
         },
         async verifyPackageUnlocked(packageRoot) {
@@ -107,12 +136,12 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 await rename(probe, packageRoot);
             }
             catch (error) {
-                // Best-effort rollback if the first rename succeeded and the second did not.
+                // Invariant: best-effort rollback runs if the first rename succeeded and the second did not.
                 await rename(probe, packageRoot).catch(() => { });
                 throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
             }
         },
-        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing) {
+        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing, onWarmup) {
             let total = 0;
             let completed = 0;
             const candidate = await materializeRelease(packageRoot, paths.dataDir, {
@@ -121,7 +150,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                     onMaterializing?.({ completed, total });
                 },
                 onOperation: event => {
-                    if (event.operation !== "candidate-write")
+                    if (event.operation !== "candidate-write" && event.operation !== "layer-write")
                         return;
                     completed += 1;
                     onMaterializing?.({ completed, total });
@@ -134,14 +163,17 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const diagnostics = await certifyMaterializedRelease(candidate, paths.dataDir);
             await stateStore.approve(candidate.releaseId, diagnostics);
             await phase("certified");
+            onWarmup?.("started");
+            await warmMaterializedRelease(candidate, environment);
+            onWarmup?.("completed");
+            await ensureSupervisor(candidate, environment);
+            // Invariant: warmup and authenticated readiness precede changing the active reference.
             await stateStore.activate(candidate.releaseId);
             await phase("active-reference-committed");
-            await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
         },
     };
 }
-const PROGRESS_BAR_WIDTH = 39;
+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
@@ -154,10 +186,15 @@ const ACTIVATION_PROGRESS = {
     certified: { at: 94, creepTo: 96 },
     "active-reference-committed": { at: 96, creepTo: 99 },
 };
-function renderProgressBar(percent) {
+/** 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);
-    return `${"█".repeat(filled)}${"░".repeat(PROGRESS_BAR_WIDTH - filled)} ${bounded}%`;
+    // Rationale: a gray line, a darker gray track, and one space before the percentage.
+    // Explicit RGB keeps both grays neutral even when the terminal remaps its ANSI palette.
+    const gray = "\u001b[38;2;128;128;128m";
+    const track = "\u001b[38;2;102;102;102m";
+    return `${gray}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
 }
 function createUpdateProgress(output, enabled) {
     let visible = false;
@@ -170,7 +207,7 @@ function createUpdateProgress(output, enabled) {
             return;
         shown = rounded;
         visible = true;
-        output.stdout(`\r${renderProgressBar(rounded)}`);
+        output.stdout(`\r${renderUpdateProgressBar(rounded)}`);
     };
     const stopCreep = () => {
         if (timer !== null) {
@@ -188,7 +225,7 @@ function createUpdateProgress(output, enabled) {
             draw();
             if (creepTo <= current)
                 return;
-            // Creep asymptotically toward (but never reach) the next milestone so
+            // 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,
@@ -199,7 +236,7 @@ function createUpdateProgress(output, enabled) {
             }, PROGRESS_TICK_MS);
             timer.unref?.();
         },
-        // The bar exists to say the update is still moving. Once it has finished
+        // 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.
@@ -223,12 +260,13 @@ function createUpdateProgress(output, enabled) {
 }
 /** The newest version the channel points at, which is what an unqualified update takes. */
 async function resolveChannelHead(runner, distTag, output) {
-    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`);
+    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 ${distTag} version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        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 };
@@ -236,14 +274,10 @@ async function resolveChannelHead(runner, distTag, output) {
 /**
  * Resolve a preview the caller named.
  *
- * A preview is published as `<version>-dev.<commit>`, so its commit is enough to
- * say which one is wanted — the version in front of it is not something anyone
- * should have to remember. A full version is accepted too, for anyone reading one
- * back from `a1 version` or a changelog.
- *
- * The published list is the authority: naming a commit that was never published,
- * or one published more than once under different versions, is an error rather
- * than a guess.
+ * 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");
@@ -260,9 +294,8 @@ async function resolveRequestedPreview(runner, requested, output) {
     const versions = (Array.isArray(published) ? published : [published]).filter((value) => typeof value === "string");
     const exact = versions.find(version => version === requested);
     if (exact !== undefined) {
-        // Naming a release here would install it through the preview path, which is a
-        // different command with a different meaning. The commit form cannot express
-        // one, so only the fuller spelling of a preview reaches this.
+        // 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 };
@@ -314,7 +347,9 @@ export async function runSelfUpdate(options) {
     if (resolved.version === null)
         return resolved.exitCode;
     const targetVersion = resolved.version;
-    output.stdout(`${PRODUCT_TEXT.commandName} update (${UPDATE_CHANNEL_LABELS[channel]}): ${runningVersion} → ${targetVersion}.\n`);
+    // 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 rootLookup = await measure("global-root", async () => await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root"));
     if (rootLookup.result === null)
@@ -340,25 +375,37 @@ export async function runSelfUpdate(options) {
     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 (await lifecycle.targetIsActive(targetVersion)) {
-            if (transaction?.status === "active") {
-                await transactionStore.advance("supervisor-verified");
-                await transactionStore.finish("completed");
-            }
+        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;
         }
-        // The bar first appears here so a no-change run never flashes it.
+        // Rationale: the bar first appears here so a no-change run never flashes it.
         progress.set(3, 15);
-        const cohortState = await new CohortStateStore(paths.dataDir).read();
+        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: cohortState.references.active,
+            priorActiveReleaseId,
         });
         if (phaseBefore(transaction.phase, "ownership-released")) {
             await measure("ownership-release", async () => {
@@ -369,18 +416,73 @@ export async function runSelfUpdate(options) {
         }
         progress.set(15, 70);
         if (phaseBefore(transaction.phase, "package-installed")) {
-            const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${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) {
-                if (installation.result.stdout.trim().length > 0)
-                    output.stderr(`${installation.result.stdout.trimEnd()}\n`);
-                throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
+            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,
+                    packageRoot,
+                    transaction: replacementTransaction,
+                    priorRelease,
+                    output,
+                    environment,
+                    onRecoveryState: async (recovery) => {
+                        if (transactionStore.setRecovery)
+                            transaction = await transactionStore.setRecovery(recovery) ?? transaction;
+                    },
+                }));
+                if (replacement.stdout.trim().length > 0 && replacement.outcome !== "installed")
+                    output.stderr(`${replacement.stdout.trimEnd()}\n`);
+                if (replacement.stderr.trim().length > 0)
+                    output.stderr(`${replacement.stderr.trimEnd()}\n`);
+                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, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${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) {
+                    if (installation.result.stdout.trim().length > 0)
+                        output.stderr(`${installation.result.stdout.trimEnd()}\n`);
+                    throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
+                }
+                transaction = await transactionStore.advance("package-installed");
             }
-            transaction = await transactionStore.advance("package-installed");
+        }
+        // Compatibility: npm 12 blocks install scripts unless allowScripts covers the package, so
+        // the postinstall that points the #pi-tui proxy at the tree npm just built
+        // may never have run. Run the shipped script directly: the proxy must be
+        // correct before the release store copies this tree. A failure is reported
+        // and left to the launch-time self-heal rather than failing the update.
+        try {
+            const proxySync = await runner(process.execPath, [resolve(packageRoot, "bin", "sync-pi-tui-proxy.js")], { captureStdout: true });
+            if (proxySync.code !== 0)
+                output.stderr(`${PRODUCT_TEXT.diagnostic(`could not point the #pi-tui proxy at the installed tree (exited ${formatExitCode(proxySync.code)}).`)}\n`);
+        }
+        catch (error) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`could not point the #pi-tui proxy at the installed tree: ${errorMessage(error)}`)}\n`);
         }
         progress.set(70, 75);
-        // Ownership can be reacquired after an interrupted installation (for
+        // 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); });
@@ -395,15 +497,31 @@ export async function runSelfUpdate(options) {
             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();
+        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: ${targetVersion}.\n`);
+        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion}\n`);
         return 0;
     }
     catch (error) {
@@ -424,8 +542,9 @@ export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs
         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`);
-    if (evidence.candidateWrites !== evidence.fileCount)
-        failures.push(`candidate payload write count is ${evidence.candidateWrites} 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)
@@ -492,9 +611,8 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
             throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
-    const paths = resolveProductPaths(environment);
-    await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000);
+    // Invariant: rollback reuses a surviving prior cohort rather than racing its occupied endpoint.
+    await ensureSupervisor(release, environment);
     return "rolled back";
 }
 function phaseBefore(current, target) {

package/dist/foundation/release/warmup.d.ts

@@ -0,0 +1,3 @@
+import { type MaterializedRelease } from "./release-store.js";
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export declare function warmMaterializedRelease(release: MaterializedRelease, environment: NodeJS.ProcessEnv, timeoutMs?: number): Promise<void>;

package/dist/foundation/release/warmup.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+import { resolveReleaseEntryPoint } from "./release-store.js";
+import { releaseEnvironment } from "./bootstrap.js";
+import { launchContractTarget, launchEnvironmentKeys } from "../launch-context/index.js";
+const WARMUP_DIAGNOSTIC_LIMIT = 2_000;
+/** Summarize the child's own failure text without letting an unbounded graph error escape. */
+function warmupDiagnostics(text) {
+    const lines = text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+    return lines.length === 0 ? "" : `: ${lines.slice(0, 4).join(" | ").slice(0, WARMUP_DIAGNOSTIC_LIMIT)}`;
+}
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export async function warmMaterializedRelease(release, environment, timeoutMs = 30_000) {
+    const entry = await resolveReleaseEntryPoint(release, "bin/warmup.js");
+    await new Promise((resolvePromise, rejectPromise) => {
+        // Rationale: the child still gets no terminal, but a discarded failure reason leaves an
+        // update reporting only an exit status. Its own diagnostics are read and bounded so the
+        // transaction journal records why the graph could not be imported.
+        const child = spawn(process.execPath, [entry], {
+            env: { ...releaseEnvironment(environment, release), [launchEnvironmentKeys(launchContractTarget(release)).immutableWarmup]: "1" },
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+        });
+        let diagnostics = "";
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", chunk => { diagnostics = `${diagnostics}${chunk}`.slice(-WARMUP_DIAGNOSTIC_LIMIT); });
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        child.once("error", error => finish(error));
+        child.once("close", (code, signal) => finish(code === 0
+            ? undefined
+            : new Error(`immutable startup warmup exited with ${code === null ? signal ?? "unknown status" : `status ${code}`}${warmupDiagnostics(diagnostics)}`)));
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(new Error(`immutable startup warmup exceeded ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+}

package/dist/foundation/startup/index.d.ts

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

package/dist/foundation/startup/index.js

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

package/dist/foundation/startup/startup-runtime.d.ts

@@ -0,0 +1,36 @@
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "durable-validation-start" | "durable-validation-complete" | "replacement-supervisor-start" | "replacement-supervisor-ready" | "guardian-start" | "guardian-connected" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
+export interface StartupPerformanceEvidence {
+    readonly profileId: "a1" | "pi";
+    readonly launchKind: "post-update" | "no-live-supervisor" | "warm";
+    readonly events: readonly StartupTraceEvent[];
+}
+export interface StartupTraceEvent {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.startupTraceSchema;
+    readonly traceId: string;
+    readonly phase: StartupPhase;
+    readonly elapsedMs: number;
+    readonly processId: number;
+    readonly profileId: string;
+    readonly releaseId: string | null;
+    readonly dependencyLayerIds: readonly string[];
+    readonly nodeVersion: string;
+    readonly fileReadOperations: number;
+}
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export declare function initializeStartupTrace(environment: NodeJS.ProcessEnv, profileId: string, startedAtMs?: number): void;
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export declare function markStartupPhase(environment: NodeJS.ProcessEnv, phase: StartupPhase): Promise<void>;
+export declare function assertImmutableWarmupEnvironment(environment: NodeJS.ProcessEnv): void;
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export declare function enableEnvironmentCompileCache(environment: NodeJS.ProcessEnv): string | null;
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export declare function enableStartupCompileCache(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string | null;
+export declare function startupCompileCachePath(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string;
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export declare function collectCompileCaches(dataDir: string, protectedPaths: readonly string[], keepRecent?: number): Promise<void>;
+export declare function assertStartupPerformanceBudget(evidence: StartupPerformanceEvidence, budgets?: {
+    readonly postUpdateMs: number;
+    readonly warmMs: number;
+}): void;
+export declare function parseStartupTrace(source: string): readonly StartupTraceEvent[];