@timurproko/a1 0.1.8-dev.260 → 0.1.8-dev.271

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

@@ -0,0 +1,352 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { processIsAlive } from "./process-cleanup.js";
+export const UPDATE_RECOVERY_SCHEMA = "a1-update-recovery-v1";
+const WORKER_TIMEOUT_MS = 15 * 60 * 1_000;
+const POLL_MS = 50;
+/** Resolve the complete public launcher set npm owns for the active platform. */
+export function updateLauncherPaths(globalRoot, platform = process.platform) {
+    const launcherRoot = platform === "win32" ? dirname(globalRoot) : resolve(globalRoot, "..", "..", "bin");
+    return platform === "win32"
+        ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
+        : [resolve(launcherRoot, "a1")];
+}
+/** Validate transaction-scoped recovery authority without trusting npm temporary names. */
+export async function readUpdateRecoveryCapsule(manifestPath, platform = process.platform) {
+    const capsule = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (capsule.schema !== UPDATE_RECOVERY_SCHEMA || !/^[0-9a-f-]{36}$/i.test(capsule.transactionId) || typeof capsule.targetVersion !== "string"
+        || capsule.packageName !== PRODUCT_TEXT.packageName || typeof capsule.packageRoot !== "string" || typeof capsule.globalRoot !== "string"
+        || typeof capsule.launcherRoot !== "string" || !Array.isArray(capsule.launchers) || typeof capsule.priorReleaseId !== "string"
+        || typeof capsule.priorReleaseRoot !== "string" || !/^[a-f0-9]{64}$/.test(capsule.priorContentDigest) || capsule.releaseManifestName !== PRODUCT_IDENTITY.manifest.releaseFilename || typeof capsule.recoveryEntry !== "string"
+        || !/^[a-f0-9]{64}$/.test(capsule.recoveryEntryDigest) || typeof capsule.nodeExecutable !== "string" || typeof capsule.npmCli !== "string" || !Array.isArray(capsule.npmArguments)
+        || typeof capsule.cancellationPath !== "string" || typeof capsule.resultPath !== "string" || typeof capsule.ownerPath !== "string") {
+        throw new Error("invalid A1 update recovery capsule");
+    }
+    const canonicalGlobal = await realpath(capsule.globalRoot);
+    const canonicalPackage = await realpath(capsule.packageRoot).catch(() => resolve(capsule.packageRoot));
+    const expectedPackage = resolve(canonicalGlobal, ...capsule.packageName.split("/"));
+    if (!samePath(canonicalPackage, expectedPackage) || !containedBy(canonicalGlobal, canonicalPackage))
+        throw new Error("recovery package root is outside npm global root");
+    const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${capsule.packageName}@${capsule.targetVersion}`];
+    if (JSON.stringify(capsule.npmArguments) !== JSON.stringify(expectedNpmArguments))
+        throw new Error("recovery npm arguments differ from the selected target");
+    const expectedLaunchers = updateLauncherPaths(canonicalGlobal, platform);
+    if (JSON.stringify(capsule.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers.map(path => resolve(path)))) {
+        throw new Error("recovery launcher set differs from the canonical npm launcher set");
+    }
+    for (const path of capsule.launchers)
+        assertDirectChild(resolve(capsule.launcherRoot), resolve(path));
+    const lexicalCapsuleRoot = dirname(resolve(manifestPath));
+    if (lexicalCapsuleRoot.split(sep).at(-1) !== capsule.transactionId)
+        throw new Error("recovery capsule path differs from its transaction identity");
+    const capsuleRoot = await realpath(lexicalCapsuleRoot);
+    const entry = await realpath(capsule.recoveryEntry);
+    assertDirectChild(capsuleRoot, entry);
+    if (!samePath(entry, resolve(capsuleRoot, "recovery.js")))
+        throw new Error("recovery entry path differs from the managed capsule");
+    const expectedSidecars = [resolve(lexicalCapsuleRoot, "cancel.json"), resolve(lexicalCapsuleRoot, "result.json"), resolve(lexicalCapsuleRoot, "owner.json")];
+    if (![capsule.cancellationPath, capsule.resultPath, capsule.ownerPath].every((path, index) => samePath(resolve(path), expectedSidecars[index]))) {
+        throw new Error("recovery sidecar paths differ from the managed capsule");
+    }
+    const dataDir = dirname(dirname(capsuleRoot));
+    const releasesRoot = await realpath(resolve(dataDir, "releases"));
+    const priorReleaseRoot = await realpath(capsule.priorReleaseRoot);
+    assertDirectChild(releasesRoot, priorReleaseRoot);
+    if (priorReleaseRoot.split(sep).at(-1) !== capsule.priorReleaseId)
+        throw new Error("recovery prior release identity is invalid");
+    const priorManifest = JSON.parse(await readFile(resolve(priorReleaseRoot, capsule.releaseManifestName), "utf8"));
+    if (priorManifest.releaseId !== capsule.priorReleaseId || priorManifest.contentDigest !== capsule.priorContentDigest) {
+        throw new Error("recovery prior release manifest differs from the capsule");
+    }
+    if (resolve(capsule.nodeExecutable) !== resolve(process.execPath))
+        throw new Error("recovery Node executable differs from the current runtime");
+    const npmMetadata = await lstat(capsule.npmCli);
+    if (!npmMetadata.isFile() || npmMetadata.isSymbolicLink())
+        throw new Error("recovery npm entry is invalid");
+    const digest = createHash("sha256").update(await readFile(entry)).digest("hex");
+    if (digest !== capsule.recoveryEntryDigest)
+        throw new Error("recovery entry digest differs from capsule");
+    return capsule;
+}
+/** Prepare durable recovery authority before npm can mutate the live launcher set. */
+export async function prepareUpdateRecoveryCapsule(options) {
+    const root = resolve(options.dataDir, "update-recovery");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const finalRoot = resolve(root, options.transaction.transactionId);
+    const existingManifest = resolve(finalRoot, "capsule.json");
+    if (await lstat(existingManifest).catch(() => null))
+        return { capsule: await readUpdateRecoveryCapsule(existingManifest, options.platform), manifestPath: existingManifest };
+    const candidate = resolve(root, `.candidate-${options.transaction.transactionId}-${randomUUID()}`);
+    await mkdir(candidate, { mode: 0o700 });
+    try {
+        const sourceEntry = fileURLToPath(new URL("../../../bin/update-recovery.js", import.meta.url));
+        const entryBytes = await readFile(sourceEntry);
+        const candidateEntry = resolve(candidate, "recovery.js");
+        const recoveryEntry = resolve(finalRoot, "recovery.js");
+        await writeFile(candidateEntry, entryBytes, { flag: "wx", mode: 0o500 });
+        await chmod(candidateEntry, 0o500);
+        const canonicalGlobal = await realpath(options.globalRoot);
+        const platform = options.platform ?? process.platform;
+        const launcherRoot = platform === "win32" ? dirname(canonicalGlobal) : resolve(canonicalGlobal, "..", "..", "bin");
+        const npmCli = await resolveNpmCli(canonicalGlobal, options.environment ?? process.env);
+        const capsule = {
+            schema: UPDATE_RECOVERY_SCHEMA,
+            transactionId: options.transaction.transactionId,
+            packageName: PRODUCT_TEXT.packageName,
+            targetVersion: options.transaction.targetVersion,
+            packageRoot: resolve(options.packageRoot),
+            globalRoot: canonicalGlobal,
+            launcherRoot,
+            launchers: updateLauncherPaths(canonicalGlobal, platform),
+            priorReleaseId: options.priorRelease.releaseId,
+            priorReleaseRoot: resolve(options.priorRelease.releaseRoot),
+            priorContentDigest: options.priorRelease.contentDigest,
+            releaseManifestName: PRODUCT_IDENTITY.manifest.releaseFilename,
+            recoveryEntry,
+            recoveryEntryDigest: createHash("sha256").update(entryBytes).digest("hex"),
+            nodeExecutable: process.execPath,
+            npmCli,
+            npmArguments: ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_TEXT.packageName}@${options.transaction.targetVersion}`],
+            cancellationPath: resolve(finalRoot, "cancel.json"),
+            resultPath: resolve(finalRoot, "result.json"),
+            ownerPath: resolve(finalRoot, "owner.json"),
+            createdAt: new Date().toISOString(),
+        };
+        await writeDurableJson(resolve(candidate, "capsule.json"), capsule);
+        try {
+            await rename(candidate, finalRoot);
+        }
+        catch (error) {
+            if (!await lstat(finalRoot).catch(() => null))
+                throw error;
+            await rm(candidate, { recursive: true, force: true });
+        }
+        const manifestPath = resolve(finalRoot, "capsule.json");
+        return { capsule: await readUpdateRecoveryCapsule(manifestPath, options.platform), manifestPath };
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Execute global replacement behind a detached owner and coordinate terminal cancellation. */
+export async function runProtectedPackageReplacement(options) {
+    const prepared = await prepareUpdateRecoveryCapsule(options);
+    const capsule = prepared.capsule;
+    await options.onRecoveryState?.({
+        capsulePath: prepared.manifestPath,
+        status: "prepared",
+        guardianPid: null,
+        guardianStartIdentity: null,
+        cancellationRequested: false,
+        launcherDisposition: "pending",
+    });
+    let owner = await readLiveRecoveryOwner(capsule.ownerPath, capsule.transactionId);
+    const ownerIsLive = owner !== null;
+    const priorResult = await readRecoveryResult(capsule.resultPath, capsule.transactionId).catch(() => null);
+    if (!ownerIsLive && priorResult?.outcome !== "installed") {
+        const startLease = resolve(dirname(prepared.manifestPath), "worker-starting.lock");
+        if (await acquireStartLease(startLease)) {
+            await Promise.all([rm(capsule.resultPath, { force: true }), rm(capsule.cancellationPath, { force: true }), rm(capsule.ownerPath, { force: true })]);
+            owner = null;
+            try {
+                await (options.workerSpawner ?? spawnRecoveryWorker)(capsule.recoveryEntry, prepared.manifestPath, options.environment ?? process.env);
+            }
+            catch (error) {
+                await rm(startLease, { force: true });
+                throw error;
+            }
+        }
+    }
+    let runningRecorded = false;
+    let cancellationReported = false;
+    let cancellationWrite = null;
+    const requestCancellation = (signal) => {
+        cancellationWrite ??= writeDurableJson(capsule.cancellationPath, { schema: UPDATE_RECOVERY_SCHEMA, transactionId: capsule.transactionId, signal, requestedAt: new Date().toISOString() });
+        if (!cancellationReported) {
+            cancellationReported = true;
+            options.output.stderr(`${PRODUCT_TEXT.diagnostic("cancellation requested; restoring a callable launcher before exiting.")}\n`);
+        }
+    };
+    const onSigint = () => requestCancellation("SIGINT");
+    const onSigterm = () => requestCancellation("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    try {
+        const deadline = Date.now() + (options.timeoutMs ?? WORKER_TIMEOUT_MS);
+        while (Date.now() < deadline) {
+            const result = await readRecoveryResult(capsule.resultPath, capsule.transactionId).catch(() => null);
+            if (result) {
+                const recovery = {
+                    capsulePath: prepared.manifestPath,
+                    status: result.outcome === "installed" ? "package-installed" : "recovery-launcher",
+                    guardianPid: typeof owner?.pid === "number" ? owner.pid : null,
+                    guardianStartIdentity: typeof owner?.startIdentity === "string" ? owner.startIdentity : null,
+                    cancellationRequested: result.cancelled,
+                    launcherDisposition: result.launcherDisposition,
+                };
+                if (cancellationWrite)
+                    await cancellationWrite;
+                await options.onRecoveryState?.(recovery);
+                return { ...result, recovery };
+            }
+            owner = await readLiveRecoveryOwner(capsule.ownerPath, capsule.transactionId) ?? owner;
+            if (!runningRecorded && owner?.transactionId === capsule.transactionId && typeof owner.pid === "number" && typeof owner.startIdentity === "string") {
+                runningRecorded = true;
+                await rm(resolve(dirname(prepared.manifestPath), "worker-starting.lock"), { force: true });
+                await options.onRecoveryState?.({
+                    capsulePath: prepared.manifestPath,
+                    status: "running",
+                    guardianPid: owner.pid,
+                    guardianStartIdentity: owner.startIdentity,
+                    cancellationRequested: false,
+                    launcherDisposition: "pending",
+                });
+            }
+            await new Promise(resolvePromise => setTimeout(resolvePromise, POLL_MS));
+        }
+        requestCancellation("SIGTERM");
+        if (cancellationWrite)
+            await cancellationWrite;
+        throw new Error("A1 update recovery guardian timed out before establishing a callable launcher");
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        try {
+            await cancellationWrite;
+        }
+        catch { }
+    }
+}
+export async function removeUpdateRecoveryCapsule(dataDir, transactionId) {
+    if (!/^[0-9a-f-]+$/i.test(transactionId))
+        throw new Error("invalid update recovery transaction identity");
+    await rm(resolve(dataDir, "update-recovery", transactionId), { recursive: true, force: true });
+}
+/** Classify a complete launcher set without following linked or mixed launcher files. */
+export async function inspectUpdateLauncherSet(capsule, platform = process.platform) {
+    let disposition = null;
+    const targetToken = `node_modules/${capsule.packageName}/bin/cli.js`;
+    for (const path of capsule.launchers) {
+        const metadata = await lstat(path).catch(() => null);
+        if (!metadata?.isFile() || metadata.isSymbolicLink() || (platform !== "win32" && (metadata.mode & 0o111) === 0))
+            return "unavailable";
+        const source = (await readFile(path, "utf8")).replaceAll("\\", "/");
+        const current = source.includes(capsule.recoveryEntry.replaceAll("\\", "/")) ? "recovery"
+            : source.includes(targetToken) ? "target" : null;
+        if (current === null || disposition !== null && disposition !== current)
+            return "unavailable";
+        disposition = current;
+    }
+    return disposition ?? "unavailable";
+}
+/** Remove terminal recovery capsules only after no canonical launcher references them. */
+export async function cleanupUpdateRecoveryCapsules(dataDir) {
+    const root = resolve(dataDir, "update-recovery");
+    for (const entry of await readdir(root, { withFileTypes: true }).catch(() => [])) {
+        if (!entry.isDirectory() || entry.name.startsWith(".candidate-"))
+            continue;
+        const capsuleRoot = resolve(root, entry.name);
+        const manifestPath = resolve(capsuleRoot, "capsule.json");
+        try {
+            const capsule = await readUpdateRecoveryCapsule(manifestPath);
+            if (await inspectUpdateLauncherSet(capsule) !== "recovery")
+                await rm(capsuleRoot, { recursive: true, force: true });
+        }
+        catch {
+            // Security: malformed recovery authority is retained for diagnostics rather than used as deletion authority.
+        }
+    }
+}
+async function spawnRecoveryWorker(entry, manifestPath, environment) {
+    const child = spawn(process.execPath, [entry, "--worker", manifestPath], { detached: true, stdio: "ignore", windowsHide: true, env: environment });
+    await new Promise((resolvePromise, rejectPromise) => {
+        child.once("spawn", resolvePromise);
+        child.once("error", rejectPromise);
+    });
+    child.unref();
+}
+async function resolveNpmCli(globalRoot, environment) {
+    const candidates = [environment.npm_execpath, resolve(globalRoot, "npm", "bin", "npm-cli.js")].filter((value) => typeof value === "string" && value.length > 0);
+    for (const candidate of candidates) {
+        const canonical = await realpath(candidate).catch(() => null);
+        if (canonical && await lstat(canonical).then(metadata => metadata.isFile()).catch(() => false))
+            return canonical;
+    }
+    throw new Error("could not resolve npm's JavaScript entry for protected package replacement");
+}
+async function readLiveRecoveryOwner(path, transactionId) {
+    const owner = await readJson(path).catch(() => null);
+    const metadata = await lstat(path).catch(() => null);
+    if (!owner || owner.transactionId !== transactionId || typeof owner.pid !== "number" || typeof owner.startIdentity !== "string"
+        || !metadata || Date.now() - metadata.mtimeMs > 2_000 || !processIsAlive(owner.pid))
+        return null;
+    return owner;
+}
+async function acquireStartLease(path) {
+    try {
+        const file = await open(path, "wx", 0o600);
+        await file.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        await file.close();
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            throw error;
+        const metadata = await lstat(path).catch(() => null);
+        if (metadata && Date.now() - metadata.mtimeMs > 5_000) {
+            await rm(path, { force: true });
+            return await acquireStartLease(path);
+        }
+        return false;
+    }
+}
+async function readRecoveryResult(path, transactionId) {
+    const value = await readJson(path).catch(error => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (value === null)
+        return null;
+    if (value.schema !== UPDATE_RECOVERY_SCHEMA || value.transactionId !== transactionId || !["installed", "recovery-launcher", "failed"].includes(value.outcome)
+        || !["target", "recovery", "unavailable"].includes(value.launcherDisposition) || typeof value.cancelled !== "boolean"
+        || typeof value.stdout !== "string" || typeof value.stderr !== "string")
+        throw new Error("invalid A1 update recovery result");
+    return value;
+}
+async function writeDurableJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const file = await open(temporary, "wx", 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value, null, 2));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+}
+async function readJson(path) { return JSON.parse(await readFile(path, "utf8")); }
+function samePath(left, right) {
+    return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
+function containedBy(parent, child) {
+    const fromParent = relative(parent, child);
+    return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);
+}
+function assertDirectChild(parent, child) {
+    const expectedParent = resolve(parent);
+    const actualParent = dirname(resolve(child));
+    const matches = process.platform === "win32"
+        ? actualParent.toLowerCase() === expectedParent.toLowerCase()
+        : actualParent === expectedParent;
+    if (!matches)
+        throw new Error(`update recovery path is outside its managed root: ${child}`);
+}

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

@@ -1,6 +1,14 @@
 export declare const UPDATE_JOURNAL_SCHEMA: string;
 import type { UpdateChannel } from "./update.js";
 export type UpdateTransactionPhase = "shutdown-intent" | "ownership-released" | "package-installed" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified";
+export interface UpdateRecoveryState {
+    readonly capsulePath: string;
+    readonly status: "prepared" | "running" | "package-installed" | "recovery-launcher";
+    readonly guardianPid: number | null;
+    readonly guardianStartIdentity: string | null;
+    readonly cancellationRequested: boolean;
+    readonly launcherDisposition: "pending" | "target" | "recovery" | "unavailable";
+}
 export interface UpdateTransaction {
     readonly schema: typeof UPDATE_JOURNAL_SCHEMA;
     readonly transactionId: string;
@@ -11,6 +19,7 @@ export interface UpdateTransaction {
     readonly phase: UpdateTransactionPhase;
     readonly status: "active" | "completed" | "rolled-back" | "failed";
     readonly error: string | null;
+    readonly recovery?: UpdateRecoveryState;
     readonly startedAt: string;
     readonly updatedAt: string;
 }
@@ -27,6 +36,7 @@ export declare class UpdateTransactionStore {
         priorActiveReleaseId: string | null;
     }): Promise<UpdateTransaction>;
     advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
+    setRecovery(recovery: UpdateRecoveryState): Promise<UpdateTransaction>;
     finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
     clearCompleted(): Promise<void>;
 }

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

@@ -45,6 +45,10 @@ export class UpdateTransactionStore {
             return current;
         return await this.#write({ ...current, phase, updatedAt: new Date().toISOString() });
     }
+    async setRecovery(recovery) {
+        const current = await this.#requiredActive();
+        return await this.#write({ ...current, recovery, updatedAt: new Date().toISOString() });
+    }
     async finish(status, error = null) {
         const current = await this.read();
         if (!current)
@@ -84,7 +88,14 @@ function phaseOrder(phase) {
 function validate(value) {
     if (value.schema !== UPDATE_JOURNAL_SCHEMA || typeof value.transactionId !== "string" || !["stable", "next"].includes(value.channel)
         || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.startedAt !== "string"
-        || typeof value.updatedAt !== "string" || phaseOrder(value.phase) < 0 || !["active", "completed", "rolled-back", "failed"].includes(value.status)) {
+        || typeof value.updatedAt !== "string" || phaseOrder(value.phase) < 0 || !["active", "completed", "rolled-back", "failed"].includes(value.status)
+        || (value.recovery !== undefined && !validRecovery(value.recovery))) {
         throw new Error(`invalid ${PRODUCT_TEXT.displayName} update transaction journal`);
     }
 }
+function validRecovery(value) {
+    return typeof value.capsulePath === "string" && ["prepared", "running", "package-installed", "recovery-launcher"].includes(value.status)
+        && (value.guardianPid === null || Number.isSafeInteger(value.guardianPid) && value.guardianPid > 0)
+        && (value.guardianStartIdentity === null || typeof value.guardianStartIdentity === "string")
+        && typeof value.cancellationRequested === "boolean" && ["pending", "target", "recovery", "unavailable"].includes(value.launcherDisposition);
+}

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

@@ -1,4 +1,5 @@
-import { type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
+import { type UpdateRecoveryState, type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
+import { type ProtectedPackageReplacementResult } from "./update-recovery.js";
 export declare const PRODUCT_PACKAGE: string;
 export type UpdateChannel = "stable" | "next";
 export interface ProcessRequest {
@@ -47,6 +48,8 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    /** Test seam for protected global package replacement. */
+    packageReplacement?: (input: UpdatePackageReplacementInput) => Promise<ProtectedPackageReplacementResult>;
     /** Test or embedding seam for post-activation release maintenance. */
     maintenance?: () => Promise<void>;
     progress?: boolean;
@@ -81,9 +84,24 @@ export interface UpdateTransactionJournal {
         priorActiveReleaseId: string | null;
     }): Promise<UpdateTransaction>;
     advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
+    setRecovery?(recovery: UpdateRecoveryState): Promise<UpdateTransaction>;
     finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
     clearCompleted(): Promise<void>;
 }
+export interface UpdatePackageReplacementInput {
+    readonly dataDir: string;
+    readonly globalRoot: string;
+    readonly packageRoot: string;
+    readonly transaction: UpdateTransaction;
+    readonly priorRelease: {
+        readonly releaseId: string;
+        readonly releaseRoot: string;
+        readonly contentDigest: string;
+    };
+    readonly output: UpdateOutput;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
+}
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
 /**

package/dist/foundation/release/update.js

@@ -14,6 +14,7 @@ import { materializeRelease, readMaterializedRelease } from "./release-store.js"
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { warmMaterializedRelease } from "./warmup.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
+import { removeUpdateRecoveryCapsule, runProtectedPackageReplacement } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
 const defaultFileSystem = {
@@ -386,12 +387,24 @@ export async function runSelfUpdate(options) {
         }
         // Rationale: the bar first appears here so a no-change run never flashes it.
         progress.set(3, 15);
-        const cohortState = await new CohortStateStore(paths.dataDir).read();
+        const cohortStore = new CohortStateStore(paths.dataDir);
+        let cohortState = await cohortStore.read();
+        let priorActiveReleaseId = cohortState.references.active;
+        if (options.runner === undefined && (priorActiveReleaseId === null || cohortState.releases[priorActiveReleaseId]?.approval !== "approved")) {
+            // Invariant: protected replacement needs an immutable launch authority that npm cannot rename.
+            const recoveryRelease = await materializeRelease(packageRoot, paths.dataDir);
+            await cohortStore.recordCandidate(recoveryRelease);
+            const diagnostics = await certifyMaterializedRelease(recoveryRelease, paths.dataDir);
+            await cohortStore.approve(recoveryRelease.releaseId, diagnostics);
+            await cohortStore.activate(recoveryRelease.releaseId);
+            cohortState = await cohortStore.read();
+            priorActiveReleaseId = recoveryRelease.releaseId;
+        }
         transaction = await transactionStore.begin({
             channel,
             targetVersion,
             packageRoot,
-            priorActiveReleaseId: cohortState.references.active,
+            priorActiveReleaseId,
         });
         if (phaseBefore(transaction.phase, "ownership-released")) {
             await measure("ownership-release", async () => {
@@ -402,15 +415,57 @@ export async function runSelfUpdate(options) {
         }
         progress.set(15, 70);
         if (phaseBefore(transaction.phase, "package-installed")) {
-            const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
-            if (installation.result === null)
-                throw new UpdateFailure(installation.exitCode, "npm process failed");
-            if (installation.result.code !== 0) {
-                if (installation.result.stdout.trim().length > 0)
-                    output.stderr(`${installation.result.stdout.trimEnd()}\n`);
-                throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
+            if (options.packageReplacement || options.runner === undefined) {
+                const priorReleaseId = transaction.priorActiveReleaseId ?? priorActiveReleaseId;
+                const recordedPrior = priorReleaseId === null ? undefined : cohortState.releases[priorReleaseId];
+                if ((!recordedPrior || recordedPrior.approval !== "approved") && !options.packageReplacement) {
+                    throw new Error(PRODUCT_TEXT.diagnostic("cannot protect package replacement because no approved prior release is available"));
+                }
+                const priorRelease = recordedPrior ?? {
+                    releaseId: priorReleaseId ?? "injected-prior-release",
+                    releaseRoot: packageRoot,
+                    contentDigest: "0".repeat(64),
+                };
+                const replacementTransaction = transaction;
+                const replacement = await measure("npm-install", async () => await (options.packageReplacement ?? runProtectedPackageReplacement)({
+                    dataDir: paths.dataDir,
+                    globalRoot,
+                    packageRoot,
+                    transaction: replacementTransaction,
+                    priorRelease,
+                    output,
+                    environment,
+                    onRecoveryState: async (recovery) => {
+                        if (transactionStore.setRecovery)
+                            transaction = await transactionStore.setRecovery(recovery) ?? transaction;
+                    },
+                }));
+                if (replacement.stdout.trim().length > 0 && replacement.outcome !== "installed")
+                    output.stderr(`${replacement.stdout.trimEnd()}\n`);
+                if (replacement.stderr.trim().length > 0)
+                    output.stderr(`${replacement.stderr.trimEnd()}\n`);
+                if (replacement.outcome === "installed")
+                    transaction = await transactionStore.advance("package-installed");
+                if (replacement.cancelled) {
+                    progress.clear();
+                    output.stderr(`${PRODUCT_TEXT.diagnostic("update cancelled safely; the A1 launcher is available and the transaction can be resumed.")}\n`);
+                    return 130;
+                }
+                if (replacement.outcome !== "installed") {
+                    throw new UpdateFailure(unsuccessfulCode(replacement.npmExitCode), `npm exited with status ${formatExitCode(replacement.npmExitCode)}`);
+                }
+            }
+            else {
+                const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
+                if (installation.result === null)
+                    throw new UpdateFailure(installation.exitCode, "npm process failed");
+                if (installation.result.code !== 0) {
+                    if (installation.result.stdout.trim().length > 0)
+                        output.stderr(`${installation.result.stdout.trimEnd()}\n`);
+                    throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
+                }
+                transaction = await transactionStore.advance("package-installed");
             }
-            transaction = await transactionStore.advance("package-installed");
         }
         // Compatibility: npm 12 blocks install scripts unless allowScripts covers the package, so
         // the postinstall that points the #pi-tui proxy at the tree npm just built
@@ -456,6 +511,8 @@ export async function runSelfUpdate(options) {
         const transactionStartedAt = now();
         await transactionStore.advance("supervisor-verified");
         await transactionStore.finish("completed");
+        if (transaction.recovery?.capsulePath)
+            await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId);
         // Invariant: successful output follows the durable cleanup disposition. Slow recursive
         // removal belongs to the detached worker started by this maintenance coordinator.
         await maintenance();