@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.224

package/dist/{src/foundation → foundation}/release/release-store.js

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, digestManifestFiles, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
+import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { mapWithConcurrency } from "./concurrency.js";
+import { dependencyReference, materializeDependencyLayer, readCertifiedDependencyLayer, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
@@ -13,15 +14,32 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
     });
     const storeRoot = resolve(dataDir, "releases");
     await mkdir(storeRoot, { recursive: true, mode: 0o700 });
-    options.onProgress?.({ phase: "copying", fileCount: payload.paths.length });
+    const dependencyPaths = payload.paths.filter(path => path.startsWith("node_modules/"));
+    const productPaths = payload.paths.filter(path => !path.startsWith("node_modules/"));
+    const selectedDependencies = await selectPublishedDependencyRuntimePayload(payload.packageRoot, dependencyPaths);
+    options.onRuntimeInventory?.(selectedDependencies.inventory);
+    const layerOperations = [];
+    const layer = await materializeDependencyLayer(payload.packageRoot, dataDir, selectedDependencies.paths, {
+        inventory: selectedDependencies.inventory,
+        cachedFiles: payload.cachedFiles,
+        onOperation: event => layerOperations.push(event),
+        ...(options.writeCandidateFile === undefined ? {} : { writeCandidateFile: options.writeCandidateFile }),
+    });
+    const layerReferences = layer === null ? [] : [dependencyReference(layer)];
+    options.onProgress?.({
+        phase: "copying",
+        fileCount: productPaths.length + (layer?.reused === false ? layer.files.length : 0),
+    });
+    for (const event of layerOperations)
+        options.onOperation?.(event);
     const candidate = resolveWithin(storeRoot, `.candidate-${randomUUID()}`);
     await mkdir(candidate, { recursive: false, mode: 0o700 });
     try {
-        const directories = [...new Set(payload.paths.map(path => dirname(resolveWithin(candidate, path))))];
+        const directories = [...new Set(productPaths.map(path => dirname(resolveWithin(candidate, path))))];
         await mapWithConcurrency(directories, RELEASE_FILE_IO_CONCURRENCY, async (directory) => {
             await mkdir(directory, { recursive: true, mode: 0o700 });
         });
-        const files = await mapWithConcurrency(payload.paths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+        const files = await mapWithConcurrency(productPaths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
             const source = resolveWithin(payload.packageRoot, path);
             const destination = resolveWithin(candidate, path);
             const metadata = await lstat(source);
@@ -41,7 +59,12 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             options.onOperation?.({ operation: "candidate-write", path, bytes: bytes.length });
             return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
         });
-        const identity = createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
+        const identity = createReleaseIdentity(payload.packageRoot, payload.packageVersion, files, layerReferences);
+        if (layer !== null) {
+            const binding = resolveWithin(candidate, "node_modules");
+            const target = resolveWithin(layer.layerRoot, "node_modules");
+            await symlink(target, binding, process.platform === "win32" ? "junction" : "dir");
+        }
         const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
         if (await lstat(releaseRoot).catch(() => null)) {
             await rm(candidate, { recursive: true, force: true });
@@ -84,7 +107,8 @@ export async function readMaterializedRelease(releaseRoot) {
  */
 export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
     const canonical = await realpath(record.releaseRoot);
-    assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
+    const canonicalStoreRoot = await realpath(selectedStoreRoot);
+    assertContained(canonicalStoreRoot, canonical, "release root is outside the selected release store");
     const manifest = JSON.parse(await readFile(resolveWithin(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     validateManifest(manifest);
     if (manifest.releaseId !== record.releaseId || manifest.contentDigest !== record.contentDigest
@@ -93,12 +117,13 @@ export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
     }
     if (canonical.split(sep).at(-1) !== manifest.releaseId)
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
+    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], false);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot, options = {}) {
     const canonical = await realpath(releaseRoot);
-    if (selectedStoreRoot)
-        assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
+    const canonicalStoreRoot = selectedStoreRoot ? await realpath(selectedStoreRoot) : await realpath(dirname(canonical));
+    assertContained(canonicalStoreRoot, canonical, "release root is outside the selected release store");
     const manifestPath = resolveWithin(canonical, RELEASE_MANIFEST_FILENAME);
     const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
     validateManifest(manifest);
@@ -111,9 +136,10 @@ export async function verifyMaterializedRelease(releaseRoot, expected, selectedS
     await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
         await verifyFile(canonical, file, options);
     });
-    const recomputed = digestManifestFiles(manifest.files);
+    const recomputed = createReleaseIdentity(manifest.packageRoot, manifest.packageVersion, manifest.files, manifest.dependencyLayers ?? []).contentDigest;
     if (recomputed !== manifest.contentDigest)
         throw new Error(`release content digest mismatch for ${manifest.releaseId}`);
+    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], true, options);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function assertImmutableExecutionRoot(release, dataDir) {
@@ -135,6 +161,25 @@ export async function resolveReleaseEntryPoint(release, entryPoint) {
     assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
     return canonical;
 }
+async function verifyReleaseDependencies(releaseRoot, storeRoot, references, fullVerification, options = {}) {
+    if (references.length === 0)
+        return;
+    if (references.length !== 1)
+        throw new Error("release currently supports exactly one dependency layer");
+    const dataDir = dirname(storeRoot);
+    const reference = references[0];
+    const layer = fullVerification
+        ? await verifyDependencyLayer(dataDir, reference, event => options.onOperation?.({ operation: event.operation, path: event.path, bytes: event.bytes }))
+        : await readCertifiedDependencyLayer(dataDir, reference.layerId, reference);
+    const binding = resolveWithin(releaseRoot, reference.binding);
+    const metadata = await lstat(binding);
+    if (!metadata.isSymbolicLink())
+        throw new Error(`release dependency binding is not managed: ${binding}`);
+    const target = await realpath(binding);
+    const expected = await realpath(resolveWithin(layer.layerRoot, "node_modules"));
+    if (target !== expected)
+        throw new Error(`release dependency binding targets unexpected content: ${target}`);
+}
 async function verifyFile(root, file, options) {
     const path = resolveWithin(root, file.path);
     const metadata = await lstat(path).catch(() => null);
@@ -159,6 +204,11 @@ function validateManifest(value) {
         throw new Error(PRODUCT_TEXT.diagnostic("release identity is invalid"));
     if (!Array.isArray(value.files) || value.files.length === 0)
         throw new Error("release manifest contains no files");
+    if (value.dependencyLayers !== undefined && (!Array.isArray(value.dependencyLayers) || value.dependencyLayers.length === 0
+        || value.dependencyLayers.some(layer => !/^dependencies-[a-f0-9]{32}$/.test(layer.layerId)
+            || !/^[a-f0-9]{64}$/.test(layer.contentDigest) || layer.binding !== "node_modules"))) {
+        throw new Error("release dependency-layer references are invalid");
+    }
     for (const file of value.files) {
         if (typeof file.path !== "string" || file.path.length === 0 || file.path.includes("\\") || file.path.startsWith("/") || file.path.split("/").includes("..")) {
             throw new Error(`invalid release manifest path: ${String(file.path)}`);

package/dist/{src/foundation → foundation}/release/release.d.ts

@@ -1,3 +1,4 @@
+import type { DependencyLayerReference } from "./dependency-layer.js";
 export declare const PRODUCT_PACKAGE_NAME: string;
 export interface ReleaseFileIdentity {
     readonly path: string;
@@ -12,6 +13,8 @@ export interface ReleaseIdentity {
     readonly releaseId: string;
     readonly packageRoot: string;
     readonly files: readonly ReleaseFileIdentity[];
+    /** Absent for legacy full-copy releases. */
+    readonly dependencyLayers?: readonly DependencyLayerReference[];
 }
 export interface DiscoveredReleasePayload {
     readonly packageRoot: string;
@@ -31,7 +34,7 @@ export declare function discoverReleasePayload(packageRoot: string, options?: Di
  * content.
  */
 export declare function deriveReleaseIdentity(packageRoot: string): Promise<ReleaseIdentity>;
-export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[]): ReleaseIdentity;
+export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[], dependencyLayers?: readonly DependencyLayerReference[]): ReleaseIdentity;
 export declare function releaseFileIdentity(path: string, bytes: Uint8Array, executable: boolean): ReleaseFileIdentity;
 export declare function digestManifestFiles(files: readonly ReleaseFileIdentity[]): string;
 export declare function resolveWithin(root: string, candidate: string): string;

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

@@ -51,8 +51,14 @@ export async function deriveReleaseIdentity(packageRoot) {
     });
     return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
 }
-export function createReleaseIdentity(packageRoot, packageVersion, files) {
-    const contentDigest = digestManifestFiles(files);
+export function createReleaseIdentity(packageRoot, packageVersion, files, dependencyLayers = []) {
+    const productDigest = digestManifestFiles(files);
+    const contentDigest = dependencyLayers.length === 0
+        ? productDigest
+        : createHash("sha256")
+            .update(`product\0${productDigest}\n`)
+            .update(dependencyLayers.map(layer => `${layer.layerId}\0${layer.contentDigest}\0${layer.binding}\n`).join(""))
+            .digest("hex");
     return {
         packageName: PRODUCT_PACKAGE_NAME,
         packageVersion,
@@ -60,6 +66,7 @@ export function createReleaseIdentity(packageRoot, packageVersion, files) {
         releaseId: `${packageVersion}-${contentDigest.slice(0, 20)}`,
         packageRoot,
         files: [...files].sort(compareReleaseFiles),
+        ...(dependencyLayers.length === 0 ? {} : { dependencyLayers: [...dependencyLayers] }),
     };
 }
 export function releaseFileIdentity(path, bytes, executable) {
@@ -143,7 +150,7 @@ async function findInstalledDependency(root, requesterRoot, name) {
             const metadata = await lstat(candidate).catch(() => null);
             if (metadata?.isDirectory() && !metadata.isSymbolicLink())
                 return candidate;
-            // A linked dependency directory is how this installation unifies a module
+            // Invariant: a linked dependency directory is how this installation unifies a module
             // that would otherwise be present twice, and the link is made by A1 itself
             // at install and at every launch. Follow it to the directory it names and
             // collect from there, so the payload still reads only real files — but

package/dist/{src/foundation → foundation}/release/update-transaction.d.ts

@@ -14,6 +14,7 @@ export interface UpdateTransaction {
     readonly startedAt: string;
     readonly updatedAt: string;
 }
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export declare class UpdateTransactionStore {
     #private;
     readonly path: string;

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

@@ -3,6 +3,7 @@ import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export const UPDATE_JOURNAL_SCHEMA = PRODUCT_IDENTITY.protocol.updateJournalSchema;
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export class UpdateTransactionStore {
     path;
     constructor(dataDir) { this.path = resolve(dataDir, "update-transaction.json"); }

package/dist/{src/foundation → foundation}/release/update.d.ts

@@ -18,7 +18,7 @@ export interface UpdateOutput {
     stdout(message: string): void;
     stderr(message: string): void;
 }
-export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified" | "transaction-complete";
+export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "warmup" | "supervisor-verified" | "transaction-complete";
 export interface UpdatePhaseTimingEvent {
     readonly phase: UpdateMeasuredPhase;
     readonly durationMs: number;
@@ -28,12 +28,18 @@ export interface UpdatePerformanceEvidence {
     readonly sourceReads: number;
     readonly candidateWrites: number;
     readonly verificationReads: number;
+    readonly layerWrites?: number;
+    readonly layerReusedFiles?: number;
+    readonly layerReusedBytes?: number;
+    readonly payloadExcludedFiles?: number;
+    readonly payloadExcludedBytes?: number;
+    readonly warmupDurationMs?: number;
     readonly postNpmDurationMs: number;
 }
 export interface SelfUpdateOptions {
     packageRoot: string;
     channel?: UpdateChannel;
-    /** A specific preview to install, named by its commit or its full version. */
+    /** A specific preview to install, named by its development number or full version. */
     target?: string;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
@@ -41,6 +47,8 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    /** Test or embedding seam for post-activation release maintenance. */
+    maintenance?: () => Promise<void>;
     progress?: boolean;
     onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
     now?: () => number;
@@ -61,7 +69,7 @@ export interface UpdateLifecycleCoordinator {
         priorActiveVersion: string | null;
     }>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<void>;
 }
 export interface UpdateTransactionJournal {
     readonly path: string;
@@ -77,6 +85,14 @@ export interface UpdateTransactionJournal {
     clearCompleted(): Promise<void>;
 }
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
+export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
+/**
+ * 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 declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

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

@@ -6,21 +6,16 @@ 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 { 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";
 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 +42,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 +78,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 +135,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 +149,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 });
@@ -136,8 +164,11 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             await phase("certified");
             await stateStore.activate(candidate.releaseId);
             await phase("active-reference-committed");
+            onWarmup?.("started");
+            await warmMaterializedRelease(candidate, environment);
+            onWarmup?.("completed");
             await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
+            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000);
         },
     };
 }
@@ -188,7 +219,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 +230,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 +254,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 +268,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 +288,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,9 +341,9 @@ export async function runSelfUpdate(options) {
     if (resolved.version === null)
         return resolved.exitCode;
     const targetVersion = resolved.version;
-    // No full stop after a version: it already ends in a dot-separated identifier,
+    // 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 (${UPDATE_CHANNEL_LABELS[channel]}): ${runningVersion} → ${targetVersion}\n`);
+    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)
@@ -342,6 +369,9 @@ 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)) {
@@ -349,11 +379,12 @@ export async function runSelfUpdate(options) {
                 await transactionStore.advance("supervisor-verified");
                 await transactionStore.finish("completed");
             }
+            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();
         transaction = await transactionStore.begin({
@@ -381,8 +412,21 @@ export async function runSelfUpdate(options) {
             }
             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); });
@@ -397,11 +441,24 @@ 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");
         await transactionStore.finish("completed");
+        // Invariant: successful output follows the durable cleanup disposition. Slow recursive
+        // removal belongs to the detached worker started by this maintenance coordinator.
+        await maintenance();
         await transactionStore.clearCompleted();
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         progress.finish();
@@ -426,8 +483,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)
@@ -495,8 +553,10 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
     const paths = resolveProductPaths(environment);
+    // Invariant: rollback re-points the active reference and starts the prior cohort on its own endpoint;
+    // a cohort that survived the update keeps serving the work it already had.
     await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000);
     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>;