@timurproko/a1 0.2.6-dev.736 → 0.2.7-dev.1221

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

@@ -2,27 +2,25 @@ import { type SupervisorEndpointMetadata } from "./cohort-state.js";
 import { resolveProductPaths, type SessionSelection, type LaunchProfileId, type SupervisorStartupAttemptIdentity } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
 import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
+import { type EnsureTerminalHostOptions, type EnsureTerminalHostResult } from "../resident-tabs/index.js";
 export interface BootstrapOptions {
     readonly packageRoot: string;
     readonly launchIntent?: {
         readonly kind: "interactive";
         readonly profileId: LaunchProfileId;
+        readonly launchMode: "tabs" | "solo";
         readonly sessionSelection?: SessionSelection;
     };
     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>;
+    /** Test seam for resident launch routing before the guardian starts. */
+    readonly ensureTerminalHost?: (options: EnsureTerminalHostOptions) => Promise<EnsureTerminalHostResult>;
+    /** Test seam for whether this process's standard input and output are terminals; absent reads them. */
+    readonly interactiveTerminal?: boolean;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
 export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;

package/dist/foundation/release/bootstrap.js

@@ -1,10 +1,11 @@
 import { spawn } from "node:child_process";
-import { restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
+import { RESIDENT_DETACH_INTERVAL_MS, restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 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";
@@ -12,29 +13,67 @@ import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
 import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts, sweepDeadEndpoints } from "./endpoints.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { selectUpdateLaunchRelease } from "./update-launch.js";
-import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { assertCertifiedFilesPresent, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, repairMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
-import { PRODUCT_TEXT } from "../../product-identity.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
-import { 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) {
     return await runBootstrapAttempt(options, 1);
 }
 async function runBootstrapAttempt(options, retriesRemaining) {
-    const environment = withLaunchContext(options.environment ?? process.env, { launchProfile: options.launchIntent?.profileId ?? "a1" });
-    await markStartupPhase(environment, "bootstrap-start");
     const launchProfileId = options.launchIntent?.profileId ?? "a1";
+    const launchMode = options.launchIntent?.launchMode ?? (launchProfileId === "a1" ? "tabs" : "solo");
+    const environment = withLaunchContext(options.environment ?? process.env, { launchProfile: launchProfileId, launchMode });
+    await markStartupPhase(environment, "bootstrap-start");
     assertLaunchProfileId(launchProfileId);
     const sessionArgs = sessionSelectionArguments(options.launchIntent?.sessionSelection);
-    if (sessionArgs.length > 0 && launchProfileId !== "a1")
-        throw new Error("session selection requires the normal A1 profile");
+    if (sessionArgs.length > 0 && (launchProfileId !== "a1" || launchMode === "solo")) {
+        throw new Error("session selection requires the normal tabbed A1 launch");
+    }
     const output = options.output ?? process.stderr;
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const launchSelected = async (release) => {
-        const result = await launchUi(release, environment, sessionArgs);
+        let residentContext = {};
+        // Compatibility: public launch preparation supplies PI_CODING_AGENT_DIR; the fallback keeps
+        // direct SDK/bootstrap callers hermetic while retaining their former config-root read.
+        const agentProfileDir = environment.PI_CODING_AGENT_DIR ?? paths.configDir;
+        const residentLaunchSettings = launchProfileId === "a1"
+            ? readResidentTabLaunchSettings(agentProfileDir, PRODUCT_IDENTITY.commandName, paths.configDir, launchProfileId)
+            : null;
+        const resident = await selectResidentHost({
+            profileId: launchProfileId,
+            currentLaunchContract: isCurrentLaunchContract(release),
+            solo: launchMode === "solo",
+            interactive: options.interactiveTerminal ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+            ensureHost: async () => (options.ensureTerminalHost ?? ensureTerminalHost)({
+                releaseRoot: release.releaseRoot,
+                profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+                dataDir: paths.dataDir,
+                runtimeDir: paths.runtimeDir,
+                environment,
+                maxConcurrentStarts: (await residentLaunchSettings).maxConcurrentStarts,
+                unresponsiveRestartSeconds: (await residentLaunchSettings).unresponsiveRestartSeconds,
+            }),
+        });
+        if (resident !== null) {
+            residentContext = resident.status === "ready" ? {
+                residentRootExecutable: resident.executable.executable,
+                residentRootArguments: JSON.stringify([
+                    resident.executable.entry,
+                    "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(RESIDENT_DETACH_INTERVAL_MS),
+                    "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+                    "--settings-file", resolve(agentProfileDir, "settings.json"),
+                    "--data-dir", paths.dataDir, "--runtime-dir", paths.runtimeDir,
+                    "--release-root", release.releaseRoot, "--node-executable", process.execPath,
+                ]),
+            } : { residentFallback: resident.reason };
+        }
+        const result = await launchUi(release, environment, sessionArgs, residentContext);
         if (!result.releaseSuperseded)
             return result.code;
         if (retriesRemaining > 0)
@@ -86,9 +125,27 @@ 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];
-    const activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
+    let activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
+    let excludedRetainedReleaseId;
+    if (activeIsLaunchable && active?.approval === "approved" && active.packageVersion === installedVersion) {
+        try {
+            await assertCertifiedFilesPresent(active.releaseRoot);
+        }
+        catch {
+            try {
+                await repairApprovedRelease(options.packageRoot, active, paths.dataDir);
+            }
+            catch {
+                // Security: a damaged certified release is no longer a fallback when package bytes cannot restore it.
+                activeIsLaunchable = false;
+                excludedRetainedReleaseId = active.releaseId;
+            }
+        }
+    }
     if (activeIsLaunchable && active?.approval === "approved" && active.packageVersion === installedVersion) {
         const endpointMatches = endpoint?.releaseId === active.releaseId
             && endpoint.releaseRoot === active.releaseRoot
@@ -102,18 +159,27 @@ async function runBootstrapAttempt(options, retriesRemaining) {
                 await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
             await markStartupPhase(environment, "durable-validation-start");
             const retained = await readRestartCertifiedRelease(active, paths.dataDir).catch(async () => {
-                const verified = await readMaterializedRelease(active.releaseRoot, resolve(paths.dataDir, "releases"));
-                if (verified.releaseId !== active.releaseId || verified.contentDigest !== active.contentDigest || verified.packageVersion !== active.packageVersion) {
-                    throw new Error("completely verified release differs from the approved active record");
+                let verified;
+                try {
+                    verified = await readMaterializedRelease(active.releaseRoot, resolve(paths.dataDir, "releases"));
                 }
+                catch {
+                    verified = await repairApprovedRelease(options.packageRoot, active, paths.dataDir);
+                    return verified;
+                }
+                assertApprovedReleaseMatches(verified, active);
                 await certifyMaterializedRelease(verified, paths.dataDir);
                 return verified;
-            });
-            await markStartupPhase(environment, "durable-validation-complete");
-            await markStartupPhase(environment, "replacement-supervisor-start");
-            await ensureSupervisor(retained, environment);
-            await markStartupPhase(environment, "replacement-supervisor-ready");
-            return await launchSelected(retained);
+            }).catch(() => null);
+            if (retained !== null) {
+                await markStartupPhase(environment, "durable-validation-complete");
+                await markStartupPhase(environment, "replacement-supervisor-start");
+                await ensureSupervisor(retained, environment);
+                await markStartupPhase(environment, "replacement-supervisor-ready");
+                return await launchSelected(retained);
+            }
+            activeIsLaunchable = false;
+            excludedRetainedReleaseId = active.releaseId;
         }
     }
     // Concurrency: an installation being replaced is not a reason to refuse a launch. While
@@ -125,7 +191,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         candidate = await materializeRelease(options.packageRoot, paths.dataDir);
     }
     catch (error) {
-        const fallback = await launchRetainedActive(state, paths, environment, launchSelected);
+        const fallback = await launchRetainedActive(state, paths, environment, launchSelected, excludedRetainedReleaseId);
         if (fallback === null)
             throw error;
         return fallback;
@@ -252,10 +318,10 @@ async function runBootstrapAttempt(options, retriesRemaining) {
  * certifying anything new, and reports no selection when there is nothing safe
  * to fall back to.
  */
-async function launchRetainedActive(state, paths, environment, launch) {
+async function launchRetainedActive(state, paths, environment, launch, excludedReleaseId) {
     const activeId = state.references.active;
     const active = activeId === null ? undefined : state.releases[activeId];
-    if (!active || active.approval !== "approved")
+    if (!active || active.approval !== "approved" || active.releaseId === excludedReleaseId)
         return null;
     try {
         const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
@@ -266,6 +332,18 @@ async function launchRetainedActive(state, paths, environment, launch) {
         return null;
     }
 }
+async function repairApprovedRelease(packageRoot, active, dataDir) {
+    const repaired = await repairMaterializedRelease(packageRoot, active.releaseRoot);
+    assertApprovedReleaseMatches(repaired, active);
+    await recordParentCertifiedRelease(repaired, dataDir);
+    return repaired;
+}
+function assertApprovedReleaseMatches(release, active) {
+    if (release.releaseId !== active.releaseId || release.contentDigest !== active.contentDigest
+        || (active.packageVersion !== undefined && release.packageVersion !== active.packageVersion)) {
+        throw new Error("completely verified release differs from the approved active record");
+    }
+}
 async function readInstalledVersion(packageRoot) {
     const manifest = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
     if (typeof manifest.version !== "string" || manifest.version.length === 0) {
@@ -327,13 +405,15 @@ export async function startSupervisor(release, environment) {
     child.unref();
     return { ...attempt, childOutcome };
 }
-async function launchUi(release, environment, sessionArgs) {
+async function launchUi(release, environment, sessionArgs, residentContext = {}) {
     await markStartupPhase(environment, "bootstrap-selected");
     const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         let releaseSuperseded = false;
+        const releaseEnv = releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile);
+        const launchEnvironment = Object.keys(residentContext).length === 0 ? releaseEnv : withLaunchContext(releaseEnv, { ...readLaunchContext(releaseEnv), ...residentContext }, process.platform, launchContractTarget(release));
         const child = spawn(process.execPath, [entry, ...sessionArgs], {
-            env: releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile),
+            env: launchEnvironment,
             stdio: ["inherit", "inherit", "inherit", "ipc"],
             windowsHide: false,
         });
@@ -357,12 +437,15 @@ async function launchUi(release, environment, sessionArgs) {
  * version instead of failing while an installation is being replaced.
  */
 export function releaseEnvironment(environment, release, profile) {
+    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 }),
+        ...(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/cohort-state.d.ts

@@ -19,7 +19,7 @@ export interface ReleaseReferences {
     readonly rollback: string | null;
     readonly retention: readonly string[];
 }
-export type ExternalReleaseHoldAuthority = "agent" | "migration";
+export type ExternalReleaseHoldAuthority = "agent" | "migration" | "resident";
 /** A current hold supplied by an authority that must participate in every reconciliation. */
 export interface ExternalReleaseHold {
     readonly authority: ExternalReleaseHoldAuthority;

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

@@ -12,7 +12,7 @@ const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
 export function planProtectedReleases(state, inputs = {}) {
     const holds = inputs.externalHolds ?? [];
     for (const hold of holds) {
-        if (hold.authority !== "agent" && hold.authority !== "migration")
+        if (hold.authority !== "agent" && hold.authority !== "migration" && hold.authority !== "resident")
             throw new Error(`unknown release hold authority: ${String(hold.authority)}`);
         if (!state.releases[hold.releaseId] && !state.cleanup.pending[hold.releaseId]) {
             throw new Error(`external ${hold.authority} hold names unknown release ${hold.releaseId}`);
@@ -402,9 +402,12 @@ async function acquireLock(path) {
             return lock;
         }
         catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            const code = error instanceof Error && "code" in error ? error.code : undefined;
+            // Platform: Windows reports a lock file another holder is still deleting as EPERM or EACCES.
+            const releasing = process.platform === "win32" && (code === "EPERM" || code === "EACCES");
+            if (code !== "EEXIST" && !releasing)
                 throw error;
-            if (await reclaimAbandonedLock(path))
+            if (code === "EEXIST" && await reclaimAbandonedLock(path))
                 continue;
             if (Date.now() >= deadline)
                 throw error;