@timurproko/a1 0.2.7-dev.1276 → 0.2.7-dev.1286

package/dist/foundation/release/release-state.d.ts

@@ -1,6 +1,18 @@
 import type { MaterializedRelease } from "./release-store.js";
+/**
+ * Protocol: the control-state family identifier. It is frozen: changing it locks every
+ * already-published release out of the state, which is what broke the 1276 → 1285 update.
+ * Evolve the format through {@link RELEASE_STATE_LEVEL} instead.
+ */
 export declare const RELEASE_STATE_SCHEMA: string;
-/** How long a release stays on disk after its approval, so processes started from it keep their files. */
+/**
+ * Protocol: the compatibility level this code reads and writes. State records the lowest
+ * level that may read it and the lowest that may write it; additive fields raise neither,
+ * because older code preserves fields it does not know. Raise `read` only when older code would
+ * misread the state, and `write` only when older writes would corrupt it.
+ */
+export declare const RELEASE_STATE_LEVEL = 1;
+/** Minimum age retention; live, uncertain, and legacy ownership independently overrides age. */
 export declare const RELEASE_RETENTION_MS: number;
 export type ReleaseApproval = "candidate" | "approved" | "rejected";
 export interface ReleaseRecord {
@@ -9,6 +21,8 @@ export interface ReleaseRecord {
     readonly packageVersion: string;
     readonly contentDigest: string;
     readonly launchContract?: string;
+    /** Only binaries implementing launch claims may become age-collectible. */
+    readonly lifetimeClaims?: true;
     readonly approval: ReleaseApproval;
     readonly materializedAt: string;
     /** When the release was approved; retention measures its age from this instant. */
@@ -66,12 +80,40 @@ export interface ReleaseCleanupState {
     readonly diagnostics: readonly ReleaseCleanupDiagnostic[];
     readonly workerRuns: readonly ReleaseCleanupWorkerRun[];
 }
+export interface ReleaseUseClaim {
+    readonly releaseId: string;
+    readonly pid: number;
+    /** An interrupted handoff is uncertain and must remain protected. */
+    readonly phase: "launching" | "running";
+}
 export interface ReleaseState {
     readonly schema: typeof RELEASE_STATE_SCHEMA;
     readonly revision: number;
     readonly releases: Readonly<Record<string, ReleaseRecord>>;
     readonly references: ReleaseReferences;
     readonly cleanup: ReleaseCleanupState;
+    readonly uses?: Readonly<Record<string, ReleaseUseClaim>>;
+    /** Lowest compatibility levels that may read and write this state; absent means level 1. */
+    readonly format?: ReleaseStateFormat;
+}
+export interface ReleaseStateFormat {
+    readonly read: number;
+    readonly write: number;
+}
+/**
+ * State written by a newer release that this code may not read or write. Callers doing
+ * housekeeping treat it as "a newer release owns this state" and skip their work.
+ */
+export declare class ReleaseStateNewerError extends Error {
+    readonly access: "read" | "write";
+    readonly required: number;
+    constructor(access: "read" | "write", required: number);
+}
+export declare function isReleaseStateNewerError(error: unknown): error is ReleaseStateNewerError;
+export interface ReleaseStateStoreOptions {
+    /** Replaces the atomic rename; tests inject transient sharing failures. */
+    readonly rename?: (from: string, to: string) => Promise<void>;
+    readonly platform?: NodeJS.Platform;
 }
 export interface ProtectedReleaseInputs {
     /** Releases the reconciling command itself runs from; they are never collected under it. */
@@ -101,8 +143,7 @@ export interface ReleaseRetentionReconciliation {
  * Age-based retention. A release stays while a selector names it (active, its rollback, or a
  * candidate still being certified), while an unfinished update may return to it, while the
  * reconciling command runs from it, or while its approval is younger than the retention window.
- * Nothing asks which processes are running: a session that outlives the window and two updates
- * can lose its release files, which is the documented trade-off.
+ * Process-lifetime claims override age; legacy approved binaries remain conservatively retained.
  */
 export declare function planProtectedReleases(state: ReleaseState, inputs?: ProtectedReleaseInputs): ProtectedReleasePlan;
 /**
@@ -113,8 +154,10 @@ export declare function planProtectedReleases(state: ReleaseState, inputs?: Prot
 export declare function withinRetention(release: ReleaseRecord, now: number, retentionMs?: number): boolean;
 /** Serializes validated release-state revisions under a lock and commits each update atomically. */
 export declare class ReleaseStateStore {
+    #private;
     readonly path: string;
-    constructor(dataDir: string);
+    constructor(dataDir: string, options?: ReleaseStateStoreOptions);
+    private renameWithRetry;
     read(): Promise<ReleaseState>;
     update(operation: (current: ReleaseState) => ReleaseState | Promise<ReleaseState>): Promise<ReleaseState>;
     recordCandidate(release: MaterializedRelease): Promise<ReleaseState>;
@@ -134,3 +177,4 @@ export declare class ReleaseStateStore {
     recordCleanupWorkerFinished(runId: string, status: Exclude<ReleaseCleanupWorkerStatus, "scheduled" | "running">, summary: ReleaseCleanupWorkerSummary, error?: unknown): Promise<ReleaseState>;
 }
 export declare function emptyState(): ReleaseState;
+export declare function releaseUseIsLive(claim: ReleaseUseClaim): boolean;

package/dist/foundation/release/release-state.js

@@ -1,21 +1,56 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { mkdir, open, readdir, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Protocol: the control-state family identifier. It is frozen: changing it locks every
+ * already-published release out of the state, which is what broke the 1276 → 1285 update.
+ * Evolve the format through {@link RELEASE_STATE_LEVEL} instead.
+ */
 export const RELEASE_STATE_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+/** Compatibility: earlier family identifier, normalized on read. */
+const LEGACY_RELEASE_STATE_SCHEMA = "a1-release-cohort-v1";
+/**
+ * Protocol: the compatibility level this code reads and writes. State records the lowest
+ * level that may read it and the lowest that may write it; additive fields raise neither,
+ * because older code preserves fields it does not know. Raise `read` only when older code would
+ * misread the state, and `write` only when older writes would corrupt it.
+ */
+export const RELEASE_STATE_LEVEL = 1;
+const RELEASE_STATE_TEMPORARY_PATTERN = /^release-state\.json\.(\d+)\.[0-9a-f-]{36}\.tmp$/;
+const RENAME_RETRY_MS = 2_000;
 const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
-/** How long a release stays on disk after its approval, so processes started from it keep their files. */
+/** Minimum age retention; live, uncertain, and legacy ownership independently overrides age. */
 export const RELEASE_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
+/**
+ * State written by a newer release that this code may not read or write. Callers doing
+ * housekeeping treat it as "a newer release owns this state" and skip their work.
+ */
+export class ReleaseStateNewerError extends Error {
+    access;
+    required;
+    constructor(access, required) {
+        super(`release state requires ${access} level ${required}; this release supports level ${RELEASE_STATE_LEVEL}. A newer release owns it`);
+        this.name = "ReleaseStateNewerError";
+        this.access = access;
+        this.required = required;
+    }
+}
+export function isReleaseStateNewerError(error) {
+    return error instanceof ReleaseStateNewerError;
+}
 /**
  * Age-based retention. A release stays while a selector names it (active, its rollback, or a
  * candidate still being certified), while an unfinished update may return to it, while the
  * reconciling command runs from it, or while its approval is younger than the retention window.
- * Nothing asks which processes are running: a session that outlives the window and two updates
- * can lose its release files, which is the documented trade-off.
+ * Process-lifetime claims override age; legacy approved binaries remain conservatively retained.
  */
 export function planProtectedReleases(state, inputs = {}) {
     const protectedIds = new Set();
+    for (const claim of Object.values(state.uses ?? {}))
+        if (releaseUseIsLive(claim))
+            protectedIds.add(claim.releaseId);
     for (const id of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
         if (id !== null)
             protectedIds.add(id);
@@ -28,7 +63,7 @@ export function planProtectedReleases(state, inputs = {}) {
     const now = inputs.now ?? Date.now();
     const window = inputs.retentionMs ?? RELEASE_RETENTION_MS;
     for (const release of Object.values(state.releases)) {
-        if (withinRetention(release, now, window))
+        if (withinRetention(release, now, window) || (release.approval === "approved" && release.lifetimeClaims !== true))
             protectedIds.add(release.releaseId);
     }
     const protectedReleaseIds = [...protectedIds].sort();
@@ -54,12 +89,37 @@ export function withinRetention(release, now, retentionMs = RELEASE_RETENTION_MS
 /** Serializes validated release-state revisions under a lock and commits each update atomically. */
 export class ReleaseStateStore {
     path;
-    constructor(dataDir) {
+    #rename;
+    #platform;
+    constructor(dataDir, options = {}) {
         this.path = resolve(dataDir, "release-state.json");
+        this.#rename = options.rename ?? rename;
+        this.#platform = options.platform ?? process.platform;
+    }
+    async renameWithRetry(temporary) {
+        const deadline = Date.now() + RENAME_RETRY_MS;
+        for (let delay = 10;; delay = Math.min(delay * 2, 200)) {
+            try {
+                await this.#rename(temporary, this.path);
+                return;
+            }
+            catch (error) {
+                const code = error instanceof Error && "code" in error ? error.code : undefined;
+                // Platform: Windows refuses to replace a file another process has open for reading.
+                // Readers hold it only briefly, so the replacement is retried rather than lost.
+                const transient = this.#platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+                if (!transient || Date.now() >= deadline)
+                    throw error;
+                await new Promise(resolvePromise => setTimeout(resolvePromise, delay));
+            }
+        }
     }
     async read() {
         try {
             const state = normalizeState(JSON.parse(await readFile(this.path, "utf8")));
+            const format = stateFormat(state);
+            if (format.read > RELEASE_STATE_LEVEL)
+                throw new ReleaseStateNewerError("read", format.read);
             validateState(state);
             return state;
         }
@@ -75,19 +135,30 @@ export class ReleaseStateStore {
         const lock = await acquireLock(lockPath);
         try {
             const current = await this.read();
+            const format = stateFormat(current);
+            if (format.write > RELEASE_STATE_LEVEL)
+                throw new ReleaseStateNewerError("write", format.write);
             const next = await operation(current);
             validateTransition(current, next);
-            const committed = { ...next, revision: current.revision + 1 };
+            // Invariant: levels only rise; an older writer never weakens what a newer one required.
+            const committed = { ...next, revision: current.revision + 1, format };
             const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
             const file = await open(temporary, "wx", 0o600);
             try {
-                await file.writeFile(JSON.stringify(committed, null, 2));
-                await file.sync();
+                try {
+                    await file.writeFile(JSON.stringify(committed, null, 2));
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await this.renameWithRetry(temporary);
             }
-            finally {
-                await file.close();
+            catch (error) {
+                await rm(temporary, { force: true }).catch(() => undefined);
+                throw error;
             }
-            await rename(temporary, this.path);
+            await reclaimOrphanedTemporaries(dirname(this.path));
             return committed;
         }
         finally {
@@ -104,6 +175,7 @@ export class ReleaseStateStore {
                 packageVersion: release.packageVersion,
                 contentDigest: release.contentDigest,
                 ...(release.launchContract === undefined ? {} : { launchContract: release.launchContract }),
+                ...(release.files.some(file => file.path === "dist/foundation/release/release-use.js") ? { lifetimeClaims: true } : {}),
                 approval: "candidate",
                 materializedAt: new Date().toISOString(),
                 certifiedAt: null,
@@ -363,7 +435,7 @@ async function acquireLock(path) {
     while (true) {
         try {
             const lock = await open(path, "wx", 0o600);
-            await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            await lock.writeFile(JSON.stringify({ pid: process.pid, token: randomUUID(), createdAt: new Date().toISOString() }));
             await lock.sync();
             return lock;
         }
@@ -382,31 +454,35 @@ async function acquireLock(path) {
     }
 }
 async function reclaimAbandonedLock(path) {
-    let abandoned = false;
+    let owner;
     try {
-        const value = JSON.parse(await readFile(path, "utf8"));
-        if (typeof value.pid === "number") {
-            try {
-                process.kill(value.pid, 0);
-            }
-            catch (error) {
-                abandoned = !(error instanceof Error && "code" in error && error.code === "EPERM");
-            }
+        owner = await readFile(path, "utf8");
+        const value = JSON.parse(owner);
+        if (!Number.isSafeInteger(value.pid) || value.pid <= 0)
+            return false;
+        try {
+            process.kill(value.pid, 0);
+            return false;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH"))
+                return false;
         }
     }
     catch {
-        const metadata = await stat(path).catch(() => null);
-        abandoned = metadata !== null && Date.now() - metadata.mtimeMs > 10_000;
+        return false;
+    } // Security: unknown ownership never becomes safe merely through age.
+    const gate = `${path}.reclaim`;
+    try {
+        await mkdir(gate);
     }
-    if (!abandoned)
+    catch {
         return false;
-    const quarantine = `${path}.abandoned`;
-    const oldQuarantine = await stat(quarantine).catch(() => null);
-    if (oldQuarantine && Date.now() - oldQuarantine.mtimeMs > 10_000)
-        await rm(quarantine, { force: true });
+    }
     try {
-        // Concurrency: the fixed destination lets exactly one waiter claim the stale lock;
-        // another waiter cannot accidentally rename a newly acquired replacement.
+        if (await readFile(path, "utf8") !== owner)
+            return false;
+        const quarantine = `${path}.abandoned-${randomUUID()}`;
         await rename(path, quarantine);
         await rm(quarantine, { force: true });
         return true;
@@ -414,6 +490,46 @@ async function reclaimAbandonedLock(path) {
     catch {
         return false;
     }
+    finally {
+        await rm(gate, { recursive: true, force: true });
+    }
+}
+function stateFormat(state) {
+    const format = state?.format;
+    if (format === undefined)
+        return { read: RELEASE_STATE_LEVEL, write: RELEASE_STATE_LEVEL };
+    const { read, write } = (format ?? {});
+    if (!Number.isSafeInteger(read) || !Number.isSafeInteger(write) || read < 1 || write < 1) {
+        throw new Error("invalid release state format");
+    }
+    return { read: read, write: write };
+}
+/**
+ * A write that died between creating and renaming its temporary file leaves it behind.
+ * Only files whose writer process is gone are removed; a running writer's file is never touched.
+ */
+async function reclaimOrphanedTemporaries(directory) {
+    const names = await readdir(directory).catch(() => []);
+    for (const name of names) {
+        const match = RELEASE_STATE_TEMPORARY_PATTERN.exec(name);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        if (pid === process.pid || processIsAlive(pid))
+            continue;
+        await rm(resolve(directory, name), { force: true }).catch(() => undefined);
+    }
+}
+function processIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+    }
 }
 function normalizeState(value) {
     if (!value || typeof value !== "object")
@@ -424,6 +540,8 @@ function normalizeState(value) {
     const cleanup = state.cleanup;
     return {
         ...state,
+        // Compatibility: one-way control-state upgrade fences pre-claim cleanup workers; session files are untouched.
+        ...(state.schema === LEGACY_RELEASE_STATE_SCHEMA ? { schema: RELEASE_STATE_SCHEMA } : {}),
         cleanup: cleanup
             ? { ...cleanup, workerRuns: cleanup.workerRuns ?? [] }
             : { pending: {}, diagnostics: [], workerRuns: [] },
@@ -436,6 +554,13 @@ function validateState(state) {
         || !Array.isArray(state.cleanup.workerRuns)) {
         throw new Error("invalid release state");
     }
+    if (state.uses !== undefined && (state.uses === null || typeof state.uses !== "object" || Array.isArray(state.uses)))
+        throw new Error("invalid release use claims");
+    for (const [token, claim] of Object.entries(state.uses ?? {})) {
+        if (!/^[a-f0-9-]{36}$/.test(token) || !claim || !RELEASE_ID_PATTERN.test(claim.releaseId)
+            || !Number.isSafeInteger(claim.pid) || claim.pid <= 0 || !["launching", "running"].includes(claim.phase))
+            throw new Error("invalid release use claim");
+    }
     for (const run of state.cleanup.workerRuns) {
         if (!run || typeof run.runId !== "string" || run.runId.length === 0
             || !["scheduled", "running", "completed", "blocked", "continued", "failed", "skipped"].includes(run.status)
@@ -473,6 +598,18 @@ function validateTransition(current, next) {
     if (next.revision !== current.revision)
         throw new Error("release revision is controlled by the state store");
 }
+export function releaseUseIsLive(claim) {
+    if (claim.phase === "launching")
+        return true;
+    // Security: PID reuse only over-retains: no live/uncertain process identity ever proves a claim dead.
+    try {
+        process.kill(claim.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+    }
+}
 function boundedError(error) {
     return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 1_000);
 }

package/dist/foundation/release/release-use.d.ts

@@ -0,0 +1,10 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+export declare function spawnReleaseEntry(entry: string, args: readonly string[], options: SpawnOptions): Promise<ChildProcess & {
+    releaseSettled: Promise<void>;
+}>;
+/** A durable launch reservation closes selection/collection and spawn/handoff races. */
+export declare function acquireReleaseUse(dataDir: string, releaseId: string): Promise<{
+    track(child: ChildProcess): Promise<void>;
+    started(pid: number): Promise<void>;
+    release(): Promise<void>;
+}>;

package/dist/foundation/release/release-use.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { basename, dirname, resolve } from "node:path";
+import { resolveProductPaths } from "../lifecycle/index.js";
+import { ReleaseStateStore, isReleaseStateNewerError, releaseUseIsLive } from "./release-state.js";
+/** Mutable installed entries are not GC-managed; immutable helper processes need their own claim. */
+async function claimReleaseEntry(entry, environment) {
+    const dataDir = resolveProductPaths(environment).dataDir;
+    const root = await realpath(dirname(dirname(resolve(entry))));
+    const storeRoot = await realpath(resolve(dataDir, "releases")).catch(() => undefined);
+    if (dirname(root) !== storeRoot)
+        return undefined;
+    try {
+        return await acquireReleaseUse(dataDir, basename(root));
+    }
+    catch (error) {
+        // Compatibility: a newer release owns state this code may not write. It retains releases it
+        // cannot prove unused, so the launch proceeds without a claim rather than failing.
+        if (isReleaseStateNewerError(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function spawnReleaseEntry(entry, args, options) {
+    const use = await claimReleaseEntry(entry, options.env ?? process.env);
+    try {
+        const child = spawn(process.execPath, [entry, ...args], options);
+        const releaseSettled = use?.track(child) ?? Promise.resolve();
+        // Concurrency: detached callers need no waiter; awaited callers still observe release failures.
+        void releaseSettled.catch(() => undefined);
+        return Object.assign(child, { releaseSettled });
+    }
+    catch (error) {
+        await use?.release();
+        throw error;
+    }
+}
+/** A durable launch reservation closes selection/collection and spawn/handoff races. */
+export async function acquireReleaseUse(dataDir, releaseId) {
+    const store = new ReleaseStateStore(dataDir);
+    const token = randomUUID();
+    await store.update(state => {
+        if (!state.releases[releaseId])
+            throw new Error("Selected release is no longer available for launch");
+        const uses = Object.fromEntries(Object.entries(state.uses ?? {}).filter(([, claim]) => releaseUseIsLive(claim)));
+        return { ...state, uses: { ...uses, [token]: { releaseId, pid: process.pid, phase: "launching" } } };
+    });
+    let released = false;
+    return {
+        track(child) {
+            let handoff = Promise.resolve();
+            child.once("spawn", () => { handoff = this.started(child.pid).catch(() => undefined); });
+            return new Promise((resolve, reject) => {
+                child.once("close", () => { void handoff.then(() => this.release()).then(resolve, reject); });
+            });
+        },
+        async started(pid) {
+            if (!Number.isSafeInteger(pid) || pid <= 0 || released)
+                throw new Error("Invalid release process handoff");
+            await store.update(state => {
+                if (!state.uses?.[token])
+                    throw new Error("Release launch reservation was lost");
+                const claim = { releaseId, pid, phase: "running" };
+                return { ...state, uses: { ...state.uses, [token]: claim } };
+            });
+        },
+        async release() {
+            if (released)
+                return;
+            try {
+                await store.update(state => {
+                    const uses = { ...state.uses };
+                    delete uses[token];
+                    return { ...state, uses };
+                });
+            }
+            catch (error) {
+                // Compatibility: once a newer release owns the state, it settles this claim by process liveness.
+                if (!isReleaseStateNewerError(error))
+                    throw error;
+            }
+            released = true;
+        },
+    };
+}

package/dist/foundation/release/update-activation.d.ts

@@ -1,3 +1,4 @@
+import { type ProductPaths } from "../lifecycle/index.js";
 /**
  * The one activation contract an installed tree can offer the updater that installed it.
  * The updater knows nothing else about the tree: the manifest names the contracts the tree
@@ -69,4 +70,5 @@ export declare function delegateActivation(request: UpdateActivationRequest, cal
  */
 export declare function runActivationEntry(argv: readonly string[], entryUrl: string, io?: {
     write(line: string): void;
-}, environment?: NodeJS.ProcessEnv): Promise<number>;
+    diagnostic?(line: string): void;
+}, environment?: NodeJS.ProcessEnv, maintenance?: (dataDir: string, paths: ProductPaths) => Promise<void>): Promise<number>;

package/dist/foundation/release/update-activation.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawnReleaseEntry } from "./release-use.js";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -6,6 +6,7 @@ import { PRODUCT_TEXT } from "../../product-identity.js";
 import { certifyMaterializedRelease } from "./bootstrap.js";
 import { ReleaseStateStore } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
 import { materializeRelease } from "./release-store.js";
 import { warmMaterializedRelease } from "./warmup.js";
 import { errorMessage } from "./managed-path.js";
@@ -77,7 +78,7 @@ export async function readActivationContracts(packageRoot, read = path => readFi
  */
 export async function delegateActivation(request, callbacks) {
     const entry = resolve(request.packageRoot, UPDATE_ACTIVATION_ENTRY);
-    const child = spawn(process.execPath, [entry, "--data-dir", request.dataDir, "--target-version", request.targetVersion], {
+    const child = await spawnReleaseEntry(entry, ["--data-dir", request.dataDir, "--target-version", request.targetVersion], {
         env: request.environment,
         stdio: ["ignore", "pipe", "pipe"],
         windowsHide: true,
@@ -113,6 +114,9 @@ export async function delegateActivation(request, callbacks) {
         for (const event of events) {
             relay = relay.then(async () => {
                 const parsed = parseActivationEvent(event);
+                // Compatibility: a newer tree may report events this updater does not know; they carry no verdict.
+                if (parsed === "unknown")
+                    return;
                 if (!parsed) {
                     failure ??= new Error(`unrecognized activation event ${JSON.stringify(event).slice(0, 200)}`);
                     return;
@@ -146,14 +150,19 @@ export async function delegateActivation(request, callbacks) {
  * Body of the installed tree's activation entry: activate the tree this code ships in,
  * writing one progress event per line so the updater that started it can follow along.
  */
-export async function runActivationEntry(argv, entryUrl, io = { write: line => process.stdout.write(line) }, environment = process.env) {
+export async function runActivationEntry(argv, entryUrl, io = {
+    write: line => process.stdout.write(line),
+    diagnostic: line => process.stderr.write(line),
+}, environment = process.env, maintenance = scheduleReleaseCleanup) {
     const emit = (event) => io.write(`${JSON.stringify(event)}\n`);
     try {
         const arguments_ = parseEntryArguments(argv);
         const packageRoot = resolve(fileURLToPath(new URL("..", entryUrl)));
+        const paths = resolveProductPaths(environment);
+        const dataDir = arguments_.dataDir ?? paths.dataDir;
         await activateInstalledRelease({
             packageRoot,
-            dataDir: arguments_.dataDir ?? resolveProductPaths(environment).dataDir,
+            dataDir,
             targetVersion: arguments_.targetVersion,
             environment,
         }, {
@@ -161,6 +170,12 @@ export async function runActivationEntry(argv, entryUrl, io = { write: line => p
             onMaterializing: progress => emit({ event: "materializing", ...progress }),
             onWarmup: state => emit({ event: "warmup", state }),
         });
+        // Invariant: the release that now owns the control state performs its own maintenance. The
+        // updater that started this entry may be older and must not interpret state this code wrote.
+        // The activation is committed, so a maintenance failure is a diagnostic, never a verdict.
+        await maintenance(dataDir, { ...paths, dataDir }).catch((error) => {
+            io.diagnostic?.(`release maintenance after activation failed: ${errorMessage(error)}\n`);
+        });
         emit({ event: "completed" });
         return 0;
     }
@@ -197,7 +212,9 @@ function parseActivationEvent(value) {
         case "materializing":
             return typeof record.completed === "number" && typeof record.total === "number" ? { event: "materializing", completed: record.completed, total: record.total } : null;
         case "phase":
-            return record.phase === "materialized" || record.phase === "certified" || record.phase === "active-reference-committed" ? { event: "phase", phase: record.phase } : null;
+            if (record.phase === "materialized" || record.phase === "certified" || record.phase === "active-reference-committed")
+                return { event: "phase", phase: record.phase };
+            return typeof record.phase === "string" && record.phase.length > 0 ? "unknown" : null;
         case "warmup":
             return record.state === "started" || record.state === "completed" ? { event: "warmup", state: record.state } : null;
         case "completed":
@@ -205,7 +222,7 @@ function parseActivationEvent(value) {
         case "failed":
             return typeof record.message === "string" ? { event: "failed", message: record.message } : null;
         default:
-            return null;
+            return typeof record.event === "string" && record.event.length > 0 ? "unknown" : null;
     }
 }
 function summarize(text) {

package/dist/foundation/release/update-recovery.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawnReleaseEntry } from "./release-use.js";
 import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -303,7 +303,7 @@ export async function cleanupUpdateRecoveryCapsules(dataDir) {
     }
 }
 async function spawnRecoveryWorker(entry, manifestPath, environment) {
-    const child = spawn(process.execPath, [entry, "--worker", manifestPath], { detached: true, stdio: "ignore", windowsHide: true, env: environment });
+    const child = await spawnReleaseEntry(entry, ["--worker", manifestPath], { detached: true, stdio: "ignore", windowsHide: true, env: environment });
     await new Promise((resolvePromise, rejectPromise) => {
         child.once("spawn", resolvePromise);
         child.once("error", rejectPromise);

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

@@ -87,8 +87,10 @@ export type { UpdateActivationPhase, UpdateMaterializationProgress } from "./upd
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<UpdateActivationMode | void>;
 }
+/** Whether the installed tree activated itself (and owns its maintenance) or this updater activated it. */
+export type UpdateActivationMode = "delegated" | "in-process";
 export interface UpdateTransactionJournal {
     readonly path: string;
     read(): Promise<UpdateTransaction | null>;