@astralyn/sash 0.1.0

package/dist/core-config-validation.js

@@ -0,0 +1,72 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWriteFileSync } from "./fs-atomic.js";
+import { buildSanitizedEnv } from "./process.js";
+function defaultRunner(executable, args) {
+    return new Promise((resolve, reject) => {
+        execFile(executable, args, {
+            encoding: "utf8",
+            env: buildSanitizedEnv(),
+            maxBuffer: 1024 * 1024,
+            timeout: 20_000,
+            windowsHide: true,
+        }, (err, stdout, stderr) => {
+            if (!err) {
+                resolve();
+                return;
+            }
+            reject(Object.assign(err, { stdout, stderr }));
+        });
+    });
+}
+function errorOutput(err) {
+    if (typeof err !== "object" || err === null)
+        return String(err);
+    const record = err;
+    for (const value of [record.stderr, record.stdout, record.message]) {
+        const text = Buffer.isBuffer(value)
+            ? value.toString("utf8").trim()
+            : String(value ?? "").trim();
+        if (text)
+            return text.slice(0, 1000);
+    }
+    return "unknown validation error";
+}
+export async function validateCoreConfigFile(executable, configFile, layout, runner = defaultRunner) {
+    if (!fs.existsSync(executable)) {
+        throw new Error(`Core executable is missing: ${executable}`);
+    }
+    if (!fs.existsSync(configFile)) {
+        throw new Error(`Core configuration is missing: ${configFile}`);
+    }
+    try {
+        await runner(executable, ["-t", "-d", layout.root, "-f", configFile]);
+    }
+    catch (err) {
+        throw new Error(`Core rejected generated configuration: ${errorOutput(err)}`);
+    }
+}
+export async function validateCoreConfigTextWithExecutable(executable, yaml, layout, runner = defaultRunner) {
+    if (!fs.existsSync(executable)) {
+        throw new Error(`Core executable is missing: ${executable}`);
+    }
+    fs.mkdirSync(layout.tempDir, { recursive: true });
+    const candidate = path.join(layout.tempDir, `config-validate-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.yaml`);
+    try {
+        atomicWriteFileSync(candidate, yaml);
+        await validateCoreConfigFile(executable, candidate, layout, runner);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Core rejected generated configuration:")) {
+            throw err;
+        }
+        throw new Error(`Core rejected generated configuration: ${errorOutput(err)}`);
+    }
+    finally {
+        fs.rmSync(candidate, { force: true });
+    }
+}
+export function validateCoreConfigText(yaml, layout, runner = defaultRunner) {
+    return validateCoreConfigTextWithExecutable(layout.coreExe, yaml, layout, runner);
+}

package/dist/core-install-record.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import { atomicWriteFileSync } from "./fs-atomic.js";
+import { hasExactOwnKeys, isCanonicalIsoTimestamp, isPlainObject } from "./json-shape.js";
+import { sashLayout } from "./paths.js";
+const INSTALL_RECORD_SIZE_LIMIT = 16 * 1024;
+export function validateCoreReleaseTag(tag) {
+    const normalized = tag.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(normalized)) {
+        throw new Error(`Invalid Core release tag: ${tag}`);
+    }
+    return normalized;
+}
+export function parseInstallRecord(value) {
+    if (!isPlainObject(value) || !hasExactOwnKeys(value, ["coreVersion", "installedAt"])) {
+        return undefined;
+    }
+    if (typeof value.coreVersion !== "string" || !isCanonicalIsoTimestamp(value.installedAt)) {
+        return undefined;
+    }
+    try {
+        return {
+            coreVersion: validateCoreReleaseTag(value.coreVersion),
+            installedAt: value.installedAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readInstallRecord(layout = sashLayout()) {
+    try {
+        const stat = fs.lstatSync(layout.installFile);
+        if (!stat.isFile() || stat.size > INSTALL_RECORD_SIZE_LIMIT)
+            return undefined;
+        return parseInstallRecord(JSON.parse(fs.readFileSync(layout.installFile, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeInstallRecord(record, layout = sashLayout()) {
+    const coreVersion = validateCoreReleaseTag(record.coreVersion);
+    if (!isCanonicalIsoTimestamp(record.installedAt)) {
+        throw new Error(`Invalid Core install timestamp: ${record.installedAt}`);
+    }
+    atomicWriteFileSync(layout.installFile, `${JSON.stringify({ coreVersion, installedAt: record.installedAt }, null, 2)}\n`);
+}
+export function currentCoreVersion(layout = sashLayout()) {
+    return readInstallRecord(layout)?.coreVersion ?? "";
+}
+export function installRecordsEqual(left, right) {
+    if (!left || !right)
+        return left === undefined && right === null;
+    return left.coreVersion === right.coreVersion && left.installedAt === right.installedAt;
+}

package/dist/core-install-transaction.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import { atomicWriteFileSync, durableRemoveFileSync, pathEntryExists } from "./fs-atomic.js";
+import { hasExactOwnKeys, isCanonicalIsoTimestamp, isPlainObject } from "./json-shape.js";
+const TRANSACTION_VERSION = 1;
+const TRANSACTION_SIZE_LIMIT = 16 * 1024;
+function isCanonicalReleaseTag(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
+}
+function parseTransaction(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    if (!hasExactOwnKeys(value, [
+        "binaryExisted",
+        "createdAt",
+        "installRecordExisted",
+        "phase",
+        "targetVersion",
+        "version",
+    ]) ||
+        value.version !== TRANSACTION_VERSION ||
+        (value.phase !== "publishing" && value.phase !== "committed") ||
+        !isCanonicalIsoTimestamp(value.createdAt) ||
+        !isCanonicalReleaseTag(value.targetVersion) ||
+        value.binaryExisted !== false ||
+        value.installRecordExisted !== false) {
+        return undefined;
+    }
+    return {
+        version: 1,
+        phase: value.phase,
+        createdAt: value.createdAt,
+        targetVersion: value.targetVersion,
+        binaryExisted: false,
+        installRecordExisted: false,
+    };
+}
+function readTransaction(layout) {
+    let stat;
+    try {
+        stat = fs.lstatSync(layout.coreInstallTransactionFile);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw new Error(`Cannot inspect Core install transaction ${layout.coreInstallTransactionFile}: ${err.message}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`Core install transaction is not a regular file: ${layout.coreInstallTransactionFile}`);
+    }
+    if (stat.size > TRANSACTION_SIZE_LIMIT) {
+        throw new Error(`Core install transaction exceeds ${TRANSACTION_SIZE_LIMIT} bytes: ${layout.coreInstallTransactionFile}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(layout.coreInstallTransactionFile, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Core install transaction is not valid JSON: ${layout.coreInstallTransactionFile} (${err.message})`);
+    }
+    const transaction = parseTransaction(parsed);
+    if (!transaction) {
+        throw new Error(`Core install transaction has an invalid version, phase, timestamp, tag, or shape: ${layout.coreInstallTransactionFile}`);
+    }
+    return transaction;
+}
+function writeTransaction(transaction, layout) {
+    atomicWriteFileSync(layout.coreInstallTransactionFile, `${JSON.stringify(transaction, null, 2)}\n`);
+}
+export function beginCoreInstallTransaction(targetVersion, layout, createdAt = new Date().toISOString()) {
+    if (!isCanonicalReleaseTag(targetVersion)) {
+        throw new Error(`Invalid Core release tag: ${targetVersion}`);
+    }
+    if (!isCanonicalIsoTimestamp(createdAt)) {
+        throw new Error(`Invalid Core install timestamp: ${createdAt}`);
+    }
+    if (readTransaction(layout)) {
+        throw new Error(`A Core install transaction is already pending: ${layout.coreInstallTransactionFile}`);
+    }
+    if (pathEntryExists(layout.coreExe) || pathEntryExists(layout.installFile)) {
+        throw new Error("Cannot begin a first-install transaction over existing Core state");
+    }
+    const transaction = {
+        version: 1,
+        phase: "publishing",
+        createdAt,
+        targetVersion,
+        binaryExisted: false,
+        installRecordExisted: false,
+    };
+    writeTransaction(transaction, layout);
+    return transaction;
+}
+export function markCoreInstallTransactionCommitted(transaction, layout) {
+    const current = readTransaction(layout);
+    if (current?.phase !== "publishing" ||
+        current.createdAt !== transaction.createdAt ||
+        current.targetVersion !== transaction.targetVersion) {
+        throw new Error("Core install transaction changed before commit");
+    }
+    writeTransaction({ ...current, phase: "committed" }, layout);
+}
+export function clearCoreInstallTransaction(layout) {
+    durableRemoveFileSync(layout.coreInstallTransactionFile);
+}
+export function recoverCoreInstallTransaction(layout) {
+    const transaction = readTransaction(layout);
+    if (!transaction)
+        return;
+    if (transaction.phase === "publishing") {
+        durableRemoveFileSync(layout.coreExe);
+        durableRemoveFileSync(layout.installFile);
+    }
+    clearCoreInstallTransaction(layout);
+}

package/dist/core-update-coordination.js

@@ -0,0 +1,105 @@
+import { completePendingCoreUpdateAfterStart, finalizeCoreUpdateTransaction, readCoreUpdateTransaction, recoverCoreUpdateTransaction, rollbackCoreUpdateTransaction, } from "./core-update.js";
+import { clearCommittedManagedStateTransaction, markRetainedManagedStateTransactionCommitted, readManagedStateTransactionStatus, recoverManagedStateTransaction, rollbackRetainedManagedStateTransaction, } from "./managed-state-transaction.js";
+function rollbackRequired(transaction) {
+    return (transaction.phase === "repair-prepared" ||
+        transaction.phase === "repair-restoring" ||
+        transaction.phase === "prepared" ||
+        (!transaction.deferredHealth && transaction.phase === "swapped"));
+}
+export function rollbackCoordinatedCoreUpdate(layout, verifier) {
+    const errors = [];
+    let previous;
+    const managed = readManagedStateTransactionStatus(layout);
+    if (managed?.coordination === "core-update") {
+        if (managed.phase === "committed") {
+            errors.push("managed-state commit decision is already durable");
+        }
+        else {
+            try {
+                rollbackRetainedManagedStateTransaction(layout);
+            }
+            catch (err) {
+                errors.push(`managed state: ${err.message}`);
+            }
+        }
+    }
+    try {
+        previous = rollbackCoreUpdateTransaction(layout, verifier);
+    }
+    catch (err) {
+        errors.push(`Core binary: ${err.message}`);
+    }
+    if (errors.length) {
+        throw new Error(`Coordinated Core update rollback failed: ${errors.join("; ")}`);
+    }
+    return previous;
+}
+export function recoverCoordinatedCoreUpdate(layout, verifier) {
+    const managed = readManagedStateTransactionStatus(layout);
+    if (managed?.coordination !== "core-update") {
+        recoverManagedStateTransaction(layout);
+        return recoverCoreUpdateTransaction(layout, verifier);
+    }
+    const core = readCoreUpdateTransaction(layout);
+    if (managed.phase === "committed") {
+        if (!core) {
+            clearCommittedManagedStateTransaction(layout);
+            return undefined;
+        }
+        if (core.phase === "health-verified") {
+            finalizeCoreUpdateTransaction(layout, verifier);
+        }
+        else if (core.phase === "swapped" && core.deferredHealth) {
+            completePendingCoreUpdateAfterStart(layout, verifier);
+        }
+        else {
+            throw new Error("Committed managed-state Core update has no durable Core health decision");
+        }
+        clearCommittedManagedStateTransaction(layout);
+        return undefined;
+    }
+    if (managed.phase === "publishing") {
+        if (core) {
+            throw new Error("Publishing managed-state Core update unexpectedly overlaps a Core update journal");
+        }
+        rollbackRetainedManagedStateTransaction(layout);
+        return recoverCoreUpdateTransaction(layout, verifier);
+    }
+    if (!core) {
+        rollbackRetainedManagedStateTransaction(layout);
+        return recoverCoreUpdateTransaction(layout, verifier);
+    }
+    if (rollbackRequired(core)) {
+        rollbackCoordinatedCoreUpdate(layout, verifier);
+        return undefined;
+    }
+    return recoverCoreUpdateTransaction(layout, verifier);
+}
+function markManagedCommitDecision(layout) {
+    const managed = readManagedStateTransactionStatus(layout);
+    if (managed?.coordination !== "core-update")
+        return false;
+    if (managed.phase === "retained") {
+        markRetainedManagedStateTransactionCommitted(layout);
+        return true;
+    }
+    if (managed.phase !== "committed") {
+        throw new Error("Coordinated managed-state publication is not ready to commit");
+    }
+    return true;
+}
+function clearManagedCommitDecision(layout, coordinated) {
+    if (coordinated)
+        clearCommittedManagedStateTransaction(layout);
+}
+export function completeCoordinatedCoreUpdateAfterStart(layout, verifier) {
+    const coordinated = markManagedCommitDecision(layout);
+    const version = completePendingCoreUpdateAfterStart(layout, verifier);
+    clearManagedCommitDecision(layout, coordinated);
+    return version;
+}
+export function finalizeCoordinatedCoreUpdate(layout, verifier) {
+    const coordinated = markManagedCommitDecision(layout);
+    finalizeCoreUpdateTransaction(layout, verifier);
+    clearManagedCommitDecision(layout, coordinated);
+}

package/dist/core-update-service.js

@@ -0,0 +1,245 @@
+import fs from "node:fs";
+import { assertCoreInstallationConsistent, coreInstalled, currentCoreVersion, stageCore, verifyCoreExecutable, } from "./core.js";
+import { validateCoreConfigFile, validateCoreConfigTextWithExecutable, } from "./core-config-validation.js";
+import { commitCoreUpdate, readCoreUpdateTransaction, } from "./core-update.js";
+import { finalizeCoordinatedCoreUpdate } from "./core-update-coordination.js";
+import { SashDaemonClient } from "./daemon-client.js";
+import { ensureDaemon, evaluateDaemon, prepareDaemonMaintenance, } from "./daemon-lifecycle.js";
+import { MIHOMO_REPO, resolveLatestTag } from "./github.js";
+import { log } from "./log.js";
+import { readManagedStateTransactionStatus, retainManagedStateTransaction, rollbackRetainedManagedStateTransaction, } from "./managed-state-transaction.js";
+import { runOfflineMutation } from "./offline-mutation.js";
+import { ProfileConflictError, ProfileService } from "./profile-service.js";
+import { assertCoreControllerVacant } from "./runtime-recovery.js";
+import { loadSettings } from "./settings.js";
+import { withStateLock } from "./state-lock.js";
+import { CoreSupervisor } from "./supervisor.js";
+export function prepareUpdateMaintenance(ctx, deps = {}) {
+    return prepareDaemonMaintenance(ctx.layout, ctx.settings, "Core update", deps);
+}
+function defaultCoreVerifier(exe, expectedVersion) {
+    verifyCoreExecutable(exe, 5000, expectedVersion);
+}
+function installedTargetIsVerified(ctx, target, verifier) {
+    if (currentCoreVersion(ctx.layout) !== target ||
+        !coreInstalled(ctx.layout) ||
+        fs.existsSync(ctx.layout.coreInstallTransactionFile) ||
+        fs.existsSync(ctx.layout.coreUpdateTransactionFile) ||
+        readManagedStateTransactionStatus(ctx.layout) ||
+        fs.existsSync(`${ctx.layout.coreExe}.bak`) ||
+        fs.existsSync(`${ctx.layout.coreExe}.repair.bak`) ||
+        fs.existsSync(`${ctx.layout.installFile}.repair.bak`)) {
+        return false;
+    }
+    try {
+        verifier(ctx.layout.coreExe, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runCoreUpdate(ctx, opts = {}, deps = {}) {
+    const target = opts.version ?? (await (deps.resolveLatestTag ?? resolveLatestTag)(MIHOMO_REPO));
+    const current = currentCoreVersion(ctx.layout);
+    const verifier = deps.verifyExecutable ?? defaultCoreVerifier;
+    if (!opts.force) {
+        const verified = await withStateLock(ctx.layout.runtimeOperationLockFile, { purpose: "verify installed Core", timeoutMs: 30_000 }, () => installedTargetIsVerified(ctx, target, verifier));
+        if (verified) {
+            log.ok(`core is already up to date (${target})`);
+            return;
+        }
+    }
+    log.info(`updating core: ${current || "(none)"} → ${target}`);
+    log.info("downloading and validating the replacement binary...");
+    const staged = await (deps.stageCore ?? stageCore)({ layout: ctx.layout, tag: target });
+    try {
+        await withStateLock(ctx.layout.runtimeOperationLockFile, { purpose: "update Core runtime", timeoutMs: 180_000 }, async () => {
+            if (!opts.force && installedTargetIsVerified(ctx, target, verifier)) {
+                log.ok(`core is already up to date (${target})`);
+                return;
+            }
+            ctx.settings = loadSettings(ctx.layout);
+            const maintenance = await prepareUpdateMaintenance(ctx, deps);
+            await commitStagedCoreUpdate(ctx, staged, maintenance, deps, opts.force === true, verifier);
+        });
+    }
+    finally {
+        fs.rmSync(staged.exe, { force: true });
+    }
+}
+async function commitStagedCoreUpdate(ctx, staged, maintenance, deps, forceRepair, verifier) {
+    let updateError;
+    let resultVersion;
+    let pendingStartupValidation = false;
+    try {
+        await runOfflineMutation(ctx, "prepare Core update profile", () => {
+            if (!forceRepair)
+                assertCoreInstallationConsistent(ctx.layout);
+        }, {
+            reconcileRuntime: {
+                ...(maintenance.legacyDaemon ? { legacyDaemon: true } : {}),
+                verifyControllerVacant: true,
+                ...(deps.runtimeRecovery ? { deps: deps.runtimeRecovery } : {}),
+            },
+            migrateProfiles: true,
+        });
+        const profileService = new ProfileService({
+            layout: ctx.layout,
+            settings: () => ctx.settings,
+            validateConfig: (generated) => (deps.validateConfigText ?? validateCoreConfigTextWithExecutable)(staged.exe, generated.yaml, ctx.layout),
+        });
+        const commitPreparedUpdate = async (attempt = 0) => {
+            const preparedProfile = await profileService.prepareActiveReload();
+            let callbackEntered = false;
+            try {
+                return await runOfflineMutation(ctx, "commit Core update", () => profileService.withPreparedActiveReloadPublication(preparedProfile, async (publication) => {
+                    await assertCoreControllerVacant(ctx.settings, deps.runtimeRecovery?.controllerReachable);
+                    callbackEntered = true;
+                    await retainManagedStateTransaction(ctx.layout, {
+                        index: publication.index,
+                        ...(publication.profile
+                            ? {
+                                profile: {
+                                    id: publication.profile.id,
+                                    yamlText: publication.profile.yamlText,
+                                },
+                            }
+                            : {}),
+                        config: publication.config,
+                        reloadRuntime: false,
+                    });
+                    let coreCommitStarted = false;
+                    try {
+                        await (deps.validateConfigFile ?? validateCoreConfigFile)(staged.exe, ctx.layout.configFile, ctx.layout);
+                        let activeVerifier;
+                        const runtime = maintenance.coreWasRunning
+                            ? {
+                                verifyRuntime: true,
+                                stop: async () => {
+                                    await activeVerifier?.stop();
+                                    activeVerifier = undefined;
+                                },
+                                startAndVerify: async (expectedVersion) => {
+                                    activeVerifier = deps.createVerificationSupervisor
+                                        ? deps.createVerificationSupervisor({
+                                            layout: ctx.layout,
+                                            settings: () => ctx.settings,
+                                            expectedVersion,
+                                        })
+                                        : new CoreSupervisor({
+                                            layout: ctx.layout,
+                                            settings: () => ctx.settings,
+                                            expectedVersion,
+                                        });
+                                    const started = await activeVerifier.start();
+                                    log.info(`Core ${expectedVersion} health check passed (PID=${started.pid})`);
+                                },
+                            }
+                            : undefined;
+                        try {
+                            coreCommitStarted = true;
+                            return await commitCoreUpdate({
+                                layout: ctx.layout,
+                                staged,
+                                runtime,
+                                forceRepair,
+                                verifyExecutable: verifier,
+                                beforeRollback: () => {
+                                    rollbackRetainedManagedStateTransaction(ctx.layout);
+                                },
+                            });
+                        }
+                        finally {
+                            await activeVerifier?.stop();
+                        }
+                    }
+                    catch (err) {
+                        if (!coreCommitStarted) {
+                            try {
+                                rollbackRetainedManagedStateTransaction(ctx.layout);
+                            }
+                            catch (rollbackErr) {
+                                throw new Error(`${err.message}; managed-state rollback also failed: ${rollbackErr.message}`);
+                            }
+                        }
+                        throw err;
+                    }
+                }), {
+                    ...(forceRepair ? { allowInconsistentCore: "force-update" } : {}),
+                    migrateProfiles: true,
+                });
+            }
+            catch (err) {
+                if (callbackEntered || !(err instanceof ProfileConflictError) || attempt >= 1)
+                    throw err;
+                return commitPreparedUpdate(attempt + 1);
+            }
+        };
+        const result = await commitPreparedUpdate();
+        resultVersion = result.version;
+        pendingStartupValidation = result.pendingStartupValidation;
+    }
+    catch (err) {
+        updateError = err;
+    }
+    let recoveryError;
+    if (updateError) {
+        try {
+            await runOfflineMutation(ctx, "recover failed Core update", () => undefined, {
+                reconcileRuntime: {
+                    ...(deps.runtimeRecovery ? { deps: deps.runtimeRecovery } : {}),
+                },
+            });
+        }
+        catch (err) {
+            recoveryError = err;
+        }
+    }
+    ctx.settings = loadSettings(ctx.layout);
+    let restartError;
+    if (maintenance.daemonWasRunning && recoveryError) {
+        restartError = new Error(`runtime was not restarted because update rollback ownership remains unresolved: ${recoveryError.message}`);
+    }
+    else if (maintenance.daemonWasRunning) {
+        try {
+            await (deps.ensureDaemon ?? ensureDaemon)({ layout: ctx.layout, settings: ctx.settings });
+            ctx.settings = loadSettings(ctx.layout);
+            if (maintenance.coreWasRunning) {
+                const daemon = await (deps.evaluateDaemon ?? evaluateDaemon)(ctx.layout, ctx.settings);
+                if (daemon.kind !== "healthy") {
+                    throw new Error("sashd did not become healthy during update restoration");
+                }
+                const client = (deps.clientFactory ?? ((port, secret) => new SashDaemonClient(port, secret)))(daemon.port, ctx.settings.daemonSecret);
+                const started = await client.startCore();
+                log.info(`runtime restored (PID=${started.pid})`);
+            }
+        }
+        catch (err) {
+            restartError = err;
+        }
+    }
+    if (updateError) {
+        const suffix = recoveryError
+            ? `; update recovery failed: ${recoveryError.message}${maintenance.daemonWasRunning ? "; runtime was not restarted" : ""}`
+            : restartError
+                ? `; runtime restoration failed: ${restartError.message}`
+                : "";
+        log.warn("update failed; the previous binary and install metadata were restored when possible");
+        throw new Error(`${updateError.message}${suffix}`);
+    }
+    if (restartError) {
+        const attemptedVersion = resultVersion ?? staged.version;
+        const restoredVersion = currentCoreVersion(ctx.layout);
+        if (!readCoreUpdateTransaction(ctx.layout) && restoredVersion !== attemptedVersion) {
+            throw new Error(`Core ${attemptedVersion} failed during runtime restoration and was rolled back${restoredVersion ? ` to ${restoredVersion}` : ""}: ${restartError.message}`);
+        }
+        throw new Error(`Core ${attemptedVersion} was installed and verified, but runtime restoration failed: ${restartError.message}. The previous binary remains in the rollback slot.`);
+    }
+    if (pendingStartupValidation) {
+        log.ok(`core ${resultVersion ?? staged.version} staged; rollback is retained until the next successful \`sash start\``);
+        return;
+    }
+    finalizeCoordinatedCoreUpdate(ctx.layout, verifier);
+    log.ok(`core updated to ${resultVersion ?? staged.version}`);
+}