@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

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");
-            await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
+            onWarmup?.("started");
+            await warmMaterializedRelease(candidate, environment);
+            onWarmup?.("completed");
+            const startup = await startSupervisor(candidate, environment);
+            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
         },
     };
 }
@@ -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);
-    await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000);
+    // 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.
+    const startup = await startSupervisor(release, environment);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000, startup);
     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,35 @@
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { releaseEnvironment } from "./bootstrap.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export async function warmMaterializedRelease(release, environment, timeoutMs = 30_000) {
+    const entry = resolve(release.releaseRoot, "bin", "warmup.js");
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [entry], {
+            env: { ...releaseEnvironment(environment, release), [PRODUCT_IDENTITY.environment.immutableWarmup]: "1" },
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        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}`}`)));
+        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[];

package/dist/foundation/startup/startup-runtime.js

@@ -0,0 +1,140 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
+import { constants as moduleConstants, enableCompileCache } from "node:module";
+import { dirname, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+import { performance } from "node:perf_hooks";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export function initializeStartupTrace(environment, profileId, startedAtMs = performance.timeOrigin + performance.now()) {
+    const configured = environment[PRODUCT_IDENTITY.environment.startupTrace];
+    if (!configured || parseContext(configured) !== null)
+        return;
+    const context = {
+        path: resolve(configured),
+        traceId: randomUUID(),
+        startedAtMs,
+        profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? null,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]),
+    };
+    environment[PRODUCT_IDENTITY.environment.startupTrace] = JSON.stringify(context);
+}
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export async function markStartupPhase(environment, phase) {
+    const context = parseContext(environment[PRODUCT_IDENTITY.environment.startupTrace]);
+    if (context === null)
+        return;
+    const event = {
+        schema: PRODUCT_IDENTITY.evidence.startupTraceSchema,
+        traceId: context.traceId,
+        phase,
+        elapsedMs: Math.max(0, performance.timeOrigin + performance.now() - context.startedAtMs),
+        processId: process.pid,
+        profileId: context.profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? context.releaseId,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]).length > 0
+            ? parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers])
+            : context.dependencyLayerIds,
+        nodeVersion: process.version,
+        fileReadOperations: process.resourceUsage().fsRead,
+    };
+    await mkdir(dirname(context.path), { recursive: true, mode: 0o700 });
+    await appendFile(context.path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export function assertImmutableWarmupEnvironment(environment) {
+    if (environment[PRODUCT_IDENTITY.environment.immutableWarmup] !== "1") {
+        throw new Error("warmup entry is private to verified update activation");
+    }
+}
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export function enableEnvironmentCompileCache(environment) {
+    const home = environment.HOME ?? environment.USERPROFILE ?? homedir();
+    const dataDir = resolve(environment[PRODUCT_IDENTITY.environment.dataDir]
+        ?? (platform() === "win32"
+            ? resolve(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : resolve(environment.XDG_DATA_HOME ?? resolve(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    return enableStartupCompileCache(dataDir, environment[PRODUCT_IDENTITY.environment.releaseId] ?? null, parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]));
+}
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export function enableStartupCompileCache(dataDir, releaseId, dependencyLayerIds) {
+    try {
+        const path = startupCompileCachePath(dataDir, releaseId, dependencyLayerIds);
+        const result = enableCompileCache(path);
+        return result.status === moduleConstants.compileCacheStatus.FAILED ? null : result.directory ?? path;
+    }
+    catch {
+        return null;
+    }
+}
+export function startupCompileCachePath(dataDir, releaseId, dependencyLayerIds) {
+    const layers = createHash("sha256").update(dependencyLayerIds.join("\0")).digest("hex").slice(0, 20);
+    const content = dependencyLayerIds.length > 0
+        ? `layers-${layers}`
+        : `release-${(releaseId ?? "mutable").replace(/[^0-9A-Za-z.+_-]/g, "_")}`;
+    // Performance: stable layer paths share compiled dependency entries across product releases;
+    // Node's own cache key still isolates each release-specific module path and source bytes.
+    return resolve(dataDir, "cache", "compile", `${process.versions.modules ?? "node"}-${process.version.replace(/[^0-9A-Za-z.-]/g, "_")}-${content}`);
+}
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export async function collectCompileCaches(dataDir, protectedPaths, keepRecent = 2) {
+    const root = resolve(dataDir, "cache", "compile");
+    const protectedSet = new Set(protectedPaths.map(path => resolve(path)));
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const candidates = await Promise.all(entries.filter(entry => entry.isDirectory()).map(async (entry) => {
+        const path = resolve(root, entry.name);
+        const metadata = await import("node:fs/promises").then(fs => fs.stat(path));
+        return { path, mtimeMs: metadata.mtimeMs };
+    }));
+    const retainedRecent = new Set(candidates.filter(item => !protectedSet.has(item.path))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, keepRecent)
+        .map(item => item.path));
+    for (const candidate of candidates) {
+        if (!protectedSet.has(candidate.path) && !retainedRecent.has(candidate.path))
+            await rm(candidate.path, { recursive: true, force: true });
+    }
+}
+export function assertStartupPerformanceBudget(evidence, budgets = { postUpdateMs: 5_000, warmMs: 3_000 }) {
+    const events = [...evidence.events].sort((left, right) => left.elapsedMs - right.elapsedMs);
+    const ready = events.findLast(event => event.phase === "first-input-ready-render");
+    if (!ready)
+        throw new Error(`startup budget failed for ${evidence.profileId}: first input-ready render was not recorded`);
+    const budget = evidence.launchKind === "warm" ? budgets.warmMs : budgets.postUpdateMs;
+    if (ready.elapsedMs <= budget)
+        return;
+    const intervals = events.map((event, index) => ({
+        phase: event.phase,
+        durationMs: event.elapsedMs - (events[index - 1]?.elapsedMs ?? 0),
+    })).sort((left, right) => right.durationMs - left.durationMs);
+    throw new Error(`startup budget failed for ${evidence.profileId} ${evidence.launchKind}: ${Math.round(ready.elapsedMs)}ms exceeds ${budget}ms; dominant phases: ${intervals.slice(0, 3).map(item => `${item.phase} ${Math.round(item.durationMs)}ms`).join(", ")}`);
+}
+export function parseStartupTrace(source) {
+    const events = source.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+    for (const event of events) {
+        if (event.schema !== PRODUCT_IDENTITY.evidence.startupTraceSchema || typeof event.traceId !== "string"
+            || typeof event.phase !== "string" || !Number.isFinite(event.elapsedMs) || !Array.isArray(event.dependencyLayerIds)) {
+            throw new Error("startup trace contains an invalid event");
+        }
+    }
+    return events.sort((left, right) => left.elapsedMs - right.elapsedMs);
+}
+function parseContext(value) {
+    if (!value?.startsWith("{"))
+        return null;
+    try {
+        const context = JSON.parse(value);
+        if (typeof context.path !== "string" || typeof context.traceId !== "string" || !Number.isFinite(context.startedAtMs)
+            || typeof context.profileId !== "string" || !Array.isArray(context.dependencyLayerIds))
+            return null;
+        return context;
+    }
+    catch {
+        return null;
+    }
+}
+function parseLayerIds(value) {
+    if (!value)
+        return [];
+    return [...new Set(value.split(",").filter(id => /^dependencies-[a-f0-9]{32}$/.test(id)))].sort();
+}

package/dist/{src/foundation → foundation}/storage/control-store.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
-import type { ManagedAgentDescriptor, PaneId, AgentRecoveryAuthority, RecoveryReferenceId, TerminalSessionLaunch, TerminalTopologySnapshot } from "../workspace-contracts/index.js";
+import type { ManagedAgentDescriptor, PaneId, AgentRecoveryAuthority, RecoveryReferenceId, TerminalSessionLaunch, TerminalTopologySnapshot } from "../../contracts/workspace/index.js";
 import type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
 export declare const DEFAULT_WORKSPACE_ID = "workspace-default";
 export interface WorkspaceAgentPresentation {
@@ -14,6 +14,7 @@ export interface StoredWorkspaceAgent {
     readonly agent: ManagedAgentDescriptor;
     readonly presentation: WorkspaceAgentPresentation;
 }
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
 export declare class ControlStore {
     #private;
     readonly bootNonce: string | null;