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

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

@@ -0,0 +1,265 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { valid as validSemver } from "semver";
+import { readLaunchContext } from "../launch-context/index.js";
+import { resolveProductPaths } from "../lifecycle/index.js";
+import { CohortStateStore } from "./cohort-state.js";
+import { processIsAlive } from "./process-cleanup.js";
+import { isNewerRelease, releaseChannelOf } from "./latest-release.js";
+import { readCertifiedReleaseManifest, resolveReleaseEntryPoint } from "./release-store.js";
+import { readUpdateExecutionOwner } from "./update-execution-lease.js";
+import { runSelfUpdate, UPDATE_ALREADY_RUNNING_EXIT_CODE } from "./update.js";
+export const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
+export const AUTOMATIC_UPDATE_RETRY_MS = 24 * 60 * 60_000;
+const AUTOMATIC_UPDATE_STATE_FILENAME = "automatic-update.json";
+const MAX_STATE_BYTES = 16_384;
+const OBSERVER_POLL_MS = 250;
+const WORKER_START_GRACE_MS = 5_000;
+export class AutomaticUpdateStateStore {
+    path;
+    constructor(dataDir) { this.path = resolve(dataDir, AUTOMATIC_UPDATE_STATE_FILENAME); }
+    async read() {
+        let source;
+        try {
+            source = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+        if (Buffer.byteLength(source, "utf8") > MAX_STATE_BYTES)
+            throw new Error("automatic update state is oversized");
+        const value = JSON.parse(source);
+        validateState(value);
+        return value;
+    }
+    async write(value) {
+        validateState(value);
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(`${JSON.stringify(value)}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        try {
+            await rename(temporary, this.path);
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+    }
+}
+/** Start or observe one silent update and resolve with the active newer version once restart is useful. */
+export async function requestAutomaticUpdate(options) {
+    if (options.signal?.aborted)
+        return null;
+    const environment = options.environment ?? process.env;
+    const paths = resolveProductPaths(environment);
+    const now = options.now ?? Date.now;
+    const store = new AutomaticUpdateStateStore(paths.dataDir);
+    let existing;
+    try {
+        existing = await store.read();
+    }
+    catch {
+        return null;
+    }
+    const readActiveVersion = options.activeVersion ?? (async () => await activeNewerVersion(paths.dataDir, options.runningVersion));
+    const active = await readActiveVersion();
+    if (active !== null)
+        return active;
+    if (existing?.status === "failed" && existing.channel === options.release.channel && now() - existing.attemptedAt >= 0
+        && now() - existing.attemptedAt < AUTOMATIC_UPDATE_RETRY_MS
+        && !isNewerRelease(options.release.version, existing.targetVersion))
+        return null;
+    let worker = options.worker;
+    if (worker === undefined) {
+        const launch = readLaunchContext(environment, "release");
+        const cohort = await new CohortStateStore(paths.dataDir).read();
+        const record = launch.releaseId === undefined ? undefined : cohort.releases[launch.releaseId];
+        if (!record || record.approval !== "approved" || record.releaseRoot !== launch.releaseRoot
+            || record.contentDigest !== launch.releaseDigest)
+            return null;
+        const selected = await readCertifiedReleaseManifest(record, resolve(paths.dataDir, "releases"));
+        worker = {
+            entry: await resolveReleaseEntryPoint(selected, "bin/automatic-update.js"),
+            packageRoot: selected.packageRoot,
+        };
+    }
+    const arguments_ = [
+        "--package-root", worker.packageRoot,
+        "--channel", options.release.channel,
+        "--target-version", options.release.version,
+        "--data-dir", paths.dataDir,
+    ];
+    let owner;
+    try {
+        owner = await readUpdateExecutionOwner(paths.dataDir);
+    }
+    catch {
+        return null;
+    }
+    if (owner === null || !processIsAlive(owner.pid)) {
+        await (options.spawnWorker ?? spawnAutomaticUpdateWorker)(worker.entry, arguments_, environment).catch(() => undefined);
+    }
+    const startedAt = now();
+    const sleep = options.sleep ?? (async (durationMs) => await new Promise(resolvePromise => {
+        const timer = setTimeout(resolvePromise, durationMs);
+        timer.unref?.();
+    }));
+    while (!options.signal?.aborted) {
+        const installed = await readActiveVersion();
+        if (installed !== null)
+            return installed;
+        const state = await store.read().catch(() => null);
+        if (state?.targetVersion === options.release.version && state.status === "failed" && state.attemptedAt >= startedAt)
+            return null;
+        const owner = await readUpdateExecutionOwner(paths.dataDir).catch(() => null);
+        if ((owner === null || !processIsAlive(owner.pid)) && now() - startedAt >= WORKER_START_GRACE_MS)
+            return null;
+        await sleep(OBSERVER_POLL_MS);
+    }
+    return null;
+}
+export async function runAutomaticUpdateWorker(argv, environment = process.env) {
+    const parsed = parseWorkerArguments(argv);
+    const paths = resolveProductPaths(environment);
+    if (!samePath(parsed.dataDir, paths.dataDir))
+        return 1;
+    const launch = readLaunchContext(environment, "release");
+    const cohort = await new CohortStateStore(paths.dataDir).read();
+    const record = launch.releaseId === undefined ? undefined : cohort.releases[launch.releaseId];
+    if (!record || record.approval !== "approved" || !samePath(record.releaseRoot, launch.releaseRoot ?? "")
+        || record.contentDigest !== launch.releaseDigest)
+        return 1;
+    const selected = await readCertifiedReleaseManifest(record, resolve(paths.dataDir, "releases"));
+    if (!samePath(selected.packageRoot, parsed.packageRoot))
+        return 1;
+    const store = new AutomaticUpdateStateStore(paths.dataDir);
+    const attemptedAt = Date.now();
+    const output = { stdout() { }, stderr() { } };
+    let acquired = false;
+    let runningWrite = Promise.resolve();
+    try {
+        const code = await runSelfUpdate({
+            packageRoot: parsed.packageRoot,
+            channel: parsed.channel === "stable" ? "stable" : "next",
+            resolvedTarget: parsed.targetVersion,
+            mode: "automatic",
+            environment,
+            output,
+            progress: false,
+            onLeaseAcquired: () => {
+                acquired = true;
+                runningWrite = store.write(state(parsed, "running", attemptedAt, null, null));
+            },
+        });
+        if (code === UPDATE_ALREADY_RUNNING_EXIT_CODE)
+            return 0;
+        if (code !== 0) {
+            await runningWrite;
+            await store.write(state(parsed, "failed", attemptedAt, null, `exit-${code}`));
+            return code;
+        }
+        const active = await activeRelease(paths.dataDir);
+        if (active === null || releaseChannelOf(active.packageVersion) !== parsed.channel
+            || (active.packageVersion !== parsed.targetVersion && !isNewerRelease(active.packageVersion, parsed.targetVersion))) {
+            if (acquired) {
+                await runningWrite;
+                await store.write(state(parsed, "failed", attemptedAt, null, "target-not-active"));
+            }
+            return 1;
+        }
+        await runningWrite;
+        await store.write(state(parsed, "installed", attemptedAt, active.packageVersion, null));
+        return 0;
+    }
+    catch (error) {
+        await runningWrite.catch(() => undefined);
+        await store.write(state(parsed, "failed", attemptedAt, null, errorMessage(error).slice(0, 512))).catch(() => undefined);
+        return 1;
+    }
+}
+async function spawnAutomaticUpdateWorker(entry, arguments_, environment) {
+    const child = spawn(process.execPath, [entry, ...arguments_], {
+        detached: true,
+        env: environment,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        child.once("spawn", resolvePromise);
+        child.once("error", rejectPromise);
+    });
+    child.unref();
+}
+async function activeNewerVersion(dataDir, runningVersion) {
+    const active = await activeRelease(dataDir);
+    return active !== null && isNewerRelease(active.packageVersion, runningVersion) ? active.packageVersion : null;
+}
+async function activeRelease(dataDir) {
+    const cohort = await new CohortStateStore(dataDir).read();
+    const activeId = cohort.references.active;
+    if (activeId === null)
+        return null;
+    const active = cohort.releases[activeId];
+    return active?.approval === "approved" ? active : null;
+}
+function state(parsed, status, attemptedAt, installedVersion, failure) {
+    return {
+        schema: AUTOMATIC_UPDATE_STATE_SCHEMA,
+        channel: parsed.channel,
+        targetVersion: parsed.targetVersion,
+        status,
+        attemptedAt,
+        updatedAt: Date.now(),
+        installedVersion,
+        failure,
+    };
+}
+function parseWorkerArguments(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 2) {
+        const key = argv[index];
+        const value = argv[index + 1];
+        if (!key?.startsWith("--") || value === undefined || values.has(key))
+            throw new Error("invalid automatic update worker arguments");
+        values.set(key, value);
+    }
+    const packageRoot = values.get("--package-root");
+    const channel = values.get("--channel");
+    const targetVersion = values.get("--target-version");
+    const dataDir = values.get("--data-dir");
+    if (!packageRoot || (channel !== "stable" && channel !== "development") || !targetVersion || !dataDir
+        || validSemver(targetVersion) === null)
+        throw new Error("incomplete automatic update worker arguments");
+    return { packageRoot, channel, targetVersion, dataDir };
+}
+function validateState(value) {
+    if (value.schema !== AUTOMATIC_UPDATE_STATE_SCHEMA || (value.channel !== "stable" && value.channel !== "development")
+        || validSemver(value.targetVersion) === null || !["running", "installed", "failed"].includes(value.status)
+        || !Number.isFinite(value.attemptedAt) || !Number.isFinite(value.updatedAt)
+        || (value.installedVersion !== null && validSemver(value.installedVersion) === null)
+        || (value.failure !== null && (typeof value.failure !== "string" || value.failure.length > 512))) {
+        throw new Error("invalid automatic update state");
+    }
+}
+function samePath(left, right) {
+    const canonicalLeft = resolve(left);
+    const canonicalRight = resolve(right);
+    return process.platform === "win32"
+        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
+        : canonicalLeft === canonicalRight;
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

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

@@ -13,15 +13,7 @@ export interface BootstrapOptions {
     };
     readonly environment?: NodeJS.ProcessEnv;
     readonly output?: Pick<NodeJS.WriteStream, "write">;
-    /**
-     * Whether a materialized release copy is fit to launch. The active release
-     * is normally reused while its version matches the installation, but a copy
-     * can be broken in ways a version cannot see — materialized from a tree a
-     * blocked postinstall never finished repairing. The probe is injected from
-     * the bin entry because deciding it requires inspecting dependency
-     * resolution, which stays out of production code. Absent means every
-     * release is fit.
-     */
+    /** Optional package-resolution probe that excludes a damaged retained release. */
     readonly releaseIsLaunchable?: (releaseRoot: string) => boolean;
     /** Test seam for bounded maintenance scheduled after stale endpoint sweeping. */
     readonly scheduleMaintenance?: (dataDir: string, paths: ReturnType<typeof resolveProductPaths>) => Promise<void>;

package/dist/foundation/release/bootstrap.js

@@ -5,6 +5,7 @@ import { connect } from "node:net";
 import { resolve } from "node:path";
 import { selectCohortLaunch } from "./cohort-selection.js";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
+import { releaseChannelOf } from "./latest-release.js";
 import { CohortStateStore } from "./cohort-state.js";
 import { assertLaunchProfileId, createSupervisorStartupAttempt, readSupervisorStartupResult, resolveCohortEndpoint, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
@@ -17,7 +18,7 @@ import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
-import { isCurrentLaunchContract, launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
+import { PRIVATE_ENVIRONMENT, isCurrentLaunchContract, launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
 import { ensureTerminalHost, readResidentTabLaunchSettings, selectResidentHost } from "../resident-tabs/index.js";
 const RELEASE_RESELECTION_MESSAGE = "a1-release-reselection";
 export async function runBootstrap(options) {
@@ -124,6 +125,8 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     }
     let probe = endpoint ? await probeOwnership(endpoint) : "dead";
     const installedVersion = await readInstalledVersion(options.packageRoot);
+    if (releaseChannelOf(installedVersion) !== null)
+        environment[PRIVATE_ENVIRONMENT.updateVersion] = installedVersion;
     const activeId = state.references.active;
     const active = activeId === null ? undefined : state.releases[activeId];
     let activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
@@ -434,14 +437,15 @@ async function launchUi(release, environment, sessionArgs, residentContext = {})
  * version instead of failing while an installation is being replaced.
  */
 export function releaseEnvironment(environment, release, profile) {
-    const launchMode = readLaunchContext(environment).launchMode;
+    const context = readLaunchContext(environment);
     return withLaunchContext(environment, {
         releaseId: release.releaseId,
         releaseLayers: (release.dependencyLayers ?? []).map(layer => layer.layerId).join(","),
         releaseRoot: release.releaseRoot,
         releaseDigest: release.contentDigest,
         ...(profile === undefined ? {} : { launchProfile: profile }),
-        ...(launchMode === undefined ? {} : { launchMode }),
+        ...(context.launchMode === undefined ? {} : { launchMode: context.launchMode }),
+        ...(context.updateVersion === undefined ? {} : { updateVersion: context.updateVersion }),
     }, process.platform, launchContractTarget(release));
 }
 export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup) {

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

@@ -21,7 +21,7 @@ export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDoc
 export type { RestartSeal, RestartValidationEvent } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
 export type { StableRegistryState, StableRegistryVerificationOptions, StableReleaseEvidence, StableReleaseEvidenceInput } from "./stable-release.js";
-export { PACKAGE_UNLOCK_PATIENCE_MS, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export { PACKAGE_UNLOCK_PATIENCE_MS, UPDATE_ALREADY_RUNNING_EXIT_CODE, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileMetadata, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, UpdateUnlockPatience, } from "./update.js";
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export type { UpdateActivationCallbacks, UpdateActivationEvent, UpdateActivationRequest } from "./update-activation.js";

package/dist/foundation/release/index.js

@@ -10,7 +10,7 @@ export { collectRelease, prepareReleaseCleanup, runBoundedReleaseCleanup, runRel
 export { RELEASE_MANIFEST_FILENAME, ReleaseRepairUnavailableError, assertCertifiedFilesPresent, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, repairMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
-export { PACKAGE_UNLOCK_PATIENCE_MS, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export { PACKAGE_UNLOCK_PATIENCE_MS, UPDATE_ALREADY_RUNNING_EXIT_CODE, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
 export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";

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

@@ -1,5 +1,6 @@
 /** Published release channels: stable `X.Y.Z` on dist-tag `latest`, development `X.Y.Z-dev.N` on `next`. */
 export type ReleaseChannel = "stable" | "development";
+export type StartupUpdateMode = "auto" | "notify" | "no";
 export interface DistTagVersions {
     readonly release: string | null;
     readonly develop: string | null;
@@ -39,8 +40,8 @@ export interface StartupReleaseCheckOptions {
     readonly environment?: NodeJS.ProcessEnv;
     /** Whether standard output is an interactive terminal. */
     readonly interactive: boolean;
-    /** The bare-A1 `updateCheck` setting; comparison profiles omit it. */
-    readonly settingEnabled?: boolean;
+    /** The bare-A1 `updateCheck` setting; comparison profiles omit it and use auto. */
+    readonly settingMode?: StartupUpdateMode;
     readonly fetcher?: RegistryFetcher;
     readonly now?: () => number;
 }

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

@@ -74,7 +74,7 @@ export function startupReleaseCheckSkipReason(options) {
         return "ci";
     if (!options.interactive)
         return "not-interactive";
-    if (options.settingEnabled === false)
+    if (options.settingMode === "no")
         return "disabled-by-setting";
     if (releaseChannelOf(options.runningVersion) === null)
         return "unpublished-version";

package/dist/foundation/release/update-execution-lease.d.ts

@@ -0,0 +1,36 @@
+import type { UpdateChannel } from "./types.js";
+export declare const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
+declare const LEASE_SCHEMA = 1;
+export type UpdateExecutionMode = "manual" | "automatic";
+export interface UpdateExecutionOwner {
+    readonly schema: typeof LEASE_SCHEMA;
+    readonly ownerId: string;
+    readonly pid: number;
+    readonly pidStartIdentity: string;
+    readonly packageRoot: string;
+    readonly channel: UpdateChannel;
+    readonly targetVersion: string;
+    readonly mode: UpdateExecutionMode;
+    readonly acquiredAt: string;
+}
+export type UpdateExecutionLeaseResult = {
+    readonly status: "acquired";
+    readonly owner: UpdateExecutionOwner;
+    release(): Promise<void>;
+} | {
+    readonly status: "busy";
+    readonly owner: UpdateExecutionOwner;
+};
+/**
+ * Serializes every package replacement for one A1 data root. A dead owner is moved aside before a
+ * new exclusive create, so concurrent recovery attempts cannot both acquire the installation.
+ */
+export declare function acquireUpdateExecutionLease(input: {
+    readonly dataDir: string;
+    readonly packageRoot: string;
+    readonly channel: UpdateChannel;
+    readonly targetVersion: string;
+    readonly mode: UpdateExecutionMode;
+}): Promise<UpdateExecutionLeaseResult>;
+export declare function readUpdateExecutionOwner(dataDir: string): Promise<UpdateExecutionOwner | null>;
+export {};

package/dist/foundation/release/update-execution-lease.js

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import { processIsAlive } from "./process-cleanup.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+export const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
+const LEASE_SCHEMA = 1;
+const MAX_LEASE_BYTES = 8_192;
+/**
+ * Serializes every package replacement for one A1 data root. A dead owner is moved aside before a
+ * new exclusive create, so concurrent recovery attempts cannot both acquire the installation.
+ */
+export async function acquireUpdateExecutionLease(input) {
+    const path = resolve(input.dataDir, UPDATE_EXECUTION_LEASE_FILENAME);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const releaseAcquisition = await lockfile.lock(path, {
+        realpath: false,
+        stale: 60_000,
+        update: 20_000,
+        retries: { retries: 20, factor: 1.2, minTimeout: 20, maxTimeout: 100, randomize: true },
+    });
+    const owner = {
+        schema: LEASE_SCHEMA,
+        ownerId: randomUUID(),
+        pid: process.pid,
+        pidStartIdentity: currentProcessStartIdentity(),
+        packageRoot: resolve(input.packageRoot),
+        channel: input.channel,
+        targetVersion: input.targetVersion,
+        mode: input.mode,
+        acquiredAt: new Date().toISOString(),
+    };
+    try {
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            try {
+                const file = await open(path, "wx", 0o600);
+                try {
+                    await file.writeFile(`${JSON.stringify(owner)}\n`);
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                return {
+                    status: "acquired",
+                    owner,
+                    release: async () => await releaseLease(path, owner),
+                };
+            }
+            catch (error) {
+                if (!hasCode(error, "EEXIST"))
+                    throw error;
+            }
+            const existing = await readUpdateExecutionOwner(input.dataDir);
+            if (existing === null)
+                continue;
+            // Security: an uninspectable or reused pid stays conservative. A process known to be absent is
+            // reclaimed only when its durable transaction agrees with both owners.
+            if (processIsAlive(existing.pid))
+                return { status: "busy", owner: existing };
+            if (!await staleLeaseMatchesTransaction(input.dataDir, existing, input))
+                return { status: "busy", owner: existing };
+            const stale = `${path}.stale-${existing.ownerId}-${randomUUID()}`;
+            try {
+                await rename(path, stale);
+                await rm(stale, { force: true });
+            }
+            catch (error) {
+                if (!hasCode(error, "ENOENT"))
+                    throw error;
+            }
+        }
+        const existing = await readUpdateExecutionOwner(input.dataDir);
+        if (existing !== null)
+            return { status: "busy", owner: existing };
+        throw new Error("could not acquire update execution lease");
+    }
+    finally {
+        await releaseAcquisition();
+    }
+}
+export async function readUpdateExecutionOwner(dataDir) {
+    const path = resolve(dataDir, UPDATE_EXECUTION_LEASE_FILENAME);
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+    if (Buffer.byteLength(source, "utf8") > MAX_LEASE_BYTES)
+        throw new Error("update execution lease is oversized");
+    const value = JSON.parse(source);
+    validateOwner(value);
+    return value;
+}
+async function releaseLease(path, owner) {
+    const current = await readUpdateExecutionOwner(dirname(path));
+    if (current === null || current.ownerId !== owner.ownerId || current.pid !== owner.pid
+        || current.pidStartIdentity !== owner.pidStartIdentity)
+        return;
+    const released = `${path}.released-${owner.ownerId}-${randomUUID()}`;
+    try {
+        await rename(path, released);
+        await rm(released, { force: true });
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+function validateOwner(value) {
+    if (value.schema !== LEASE_SCHEMA || typeof value.ownerId !== "string" || value.ownerId.length === 0
+        || !Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.pidStartIdentity !== "string"
+        || typeof value.packageRoot !== "string" || !["stable", "next"].includes(value.channel)
+        || typeof value.targetVersion !== "string" || !["manual", "automatic"].includes(value.mode)
+        || typeof value.acquiredAt !== "string") {
+        throw new Error("invalid update execution lease");
+    }
+}
+async function staleLeaseMatchesTransaction(dataDir, owner, requested) {
+    const transaction = await new UpdateTransactionStore(dataDir).read();
+    if (transaction?.status !== "active")
+        return true;
+    return transaction.channel === owner.channel && transaction.targetVersion === owner.targetVersion
+        && samePath(transaction.packageRoot, owner.packageRoot)
+        && requested.channel === owner.channel && requested.targetVersion === owner.targetVersion
+        && samePath(requested.packageRoot, owner.packageRoot);
+}
+function samePath(left, right) {
+    const canonicalLeft = resolve(left);
+    const canonicalRight = resolve(right);
+    return process.platform === "win32"
+        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
+        : canonicalLeft === canonicalRight;
+}
+function currentProcessStartIdentity() {
+    return `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

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

@@ -1,6 +1,7 @@
 import type { UpdateChannel } from "./types.js";
 import { type UpdateActivationPhase, type UpdateMaterializationProgress } from "./update-activation.js";
 import { type UpdateRecoveryState, type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
+import { type UpdateExecutionOwner } from "./update-execution-lease.js";
 import { resolveNpmCli, type ProtectedPackageReplacementResult } from "./update-recovery.js";
 export declare const PRODUCT_PACKAGE: string;
 export type { UpdateChannel } from "./types.js";
@@ -61,6 +62,11 @@ export interface SelfUpdateOptions {
     channel?: UpdateChannel;
     /** A specific preview to install, named by its development number or full version. */
     target?: string;
+    /** Internal exact channel target selected by the automatic update probe. */
+    resolvedTarget?: string;
+    mode?: "manual" | "automatic";
+    onLeaseAcquired?: (owner: UpdateExecutionOwner) => void;
+    onLeaseBusy?: (owner: UpdateExecutionOwner) => void;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
     output?: UpdateOutput;
@@ -80,6 +86,7 @@ export interface SelfUpdateOptions {
 export type { UpdateActivationPhase, UpdateMaterializationProgress } from "./update-activation.js";
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
+    verifyAutomaticSafety?(): Promise<void>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
         priorActiveVersion: string | null;
     }>;
@@ -123,6 +130,7 @@ export interface UpdatePackageReplacementInput {
  * The update therefore keeps checking for this long before it calls the package locked.
  */
 export declare const PACKAGE_UNLOCK_PATIENCE_MS = 15000;
+export declare const UPDATE_ALREADY_RUNNING_EXIT_CODE = 75;
 /** Whether a rename failure means something holds the tree, as opposed to the tree being wrong. */
 export declare function isPackageLockError(error: unknown): boolean;
 /** What the user reads when the package stayed held for the whole patience window. */
@@ -131,12 +139,6 @@ export declare function lockedPackageDiagnostic(packageRoot: string, waitedMs: n
 export declare const CHILD_DIAGNOSTIC_LIMIT = 8000;
 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, patience?: UpdateUnlockPatience): UpdateLifecycleCoordinator;
 /** Renders the terminal-only update meter; the visual preview shares this exact frame. */