@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/utils/vpsSelfUpdate/readAgentsServerFooterVersion.ts

@@ -0,0 +1,335 @@
+import { PROMPTBOOK_ENGINE_VERSION } from '../../../../../src/version';
+import {
+    readConfiguredVpsSelfUpdateOriginRepositoryUrl,
+    VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+} from './vpsSelfUpdateOriginRepository';
+import { resolveManagedPromptbookRepositoryDirectory } from './vpsSelfUpdateConfiguration';
+import { abbreviateCommitSha, readCommitMetadataFromRepository, runGitInRepository } from './vpsSelfUpdateRepository';
+
+/**
+ * Git tag pattern used for Promptbook/Agents Server release tags.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const AGENTS_SERVER_VERSION_TAG_PATTERN = /^v?[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+
+/**
+ * Generated version tag used when the local Git checkout does not expose reachable tags.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const DEFAULT_AGENTS_SERVER_VERSION_TAG = `v${PROMPTBOOK_ENGINE_VERSION}`;
+
+/**
+ * How long the Git-derived footer version summary stays cached.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const AGENTS_SERVER_FOOTER_VERSION_CACHE_TTL_MILLISECONDS = 60 * 1000;
+
+/**
+ * Git tag match patterns accepted by `git describe`.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const GIT_DESCRIBE_VERSION_TAG_MATCH_ARGUMENTS = ['--match', 'v[0-9]*', '--match', '[0-9]*'] as const;
+
+/**
+ * Cached footer version promise shared by concurrent layout renders.
+ *
+ * @private variable of `vpsSelfUpdate`
+ */
+let cachedAgentsServerFooterVersionPromise: Promise<AgentsServerFooterVersion> | null = null;
+
+/**
+ * Expiration timestamp for {@link cachedAgentsServerFooterVersionPromise}.
+ *
+ * @private variable of `vpsSelfUpdate`
+ */
+let cachedAgentsServerFooterVersionExpiresAt = 0;
+
+/**
+ * Lightweight Agents Server version summary consumed by the shared footer.
+ *
+ * @private type of `vpsSelfUpdate`
+ */
+export type AgentsServerFooterVersion = {
+    /**
+     * Release tag shown as the base Agents Server version.
+     */
+    readonly versionTag: string;
+    /**
+     * Display label, optionally including the deployed commit short hash.
+     */
+    readonly label: string;
+    /**
+     * Browser URL of the backing Git repository.
+     */
+    readonly repositoryUrl: string;
+    /**
+     * Browser URL linked from the footer version text.
+     */
+    readonly versionUrl: string;
+    /**
+     * Current deployed commit hash.
+     */
+    readonly currentCommitSha: string | null;
+    /**
+     * Current deployed commit short hash.
+     */
+    readonly currentCommitShortSha: string | null;
+    /**
+     * Commit hash that the release tag points to.
+     */
+    readonly versionCommitSha: string | null;
+    /**
+     * Release commit author timestamp in ISO format.
+     */
+    readonly releasedAt: string | null;
+};
+
+/**
+ * Reads the footer version summary while caching the Git work outside the client footer render path.
+ *
+ * @returns Git-derived Agents Server version information safe to pass into the client footer.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readAgentsServerFooterVersion(): Promise<AgentsServerFooterVersion> {
+    const now = Date.now();
+    const cachedAgentsServerFooterVersion = cachedAgentsServerFooterVersionPromise;
+    const isCacheFresh = cachedAgentsServerFooterVersion !== null && cachedAgentsServerFooterVersionExpiresAt > now;
+
+    if (isCacheFresh) {
+        return cachedAgentsServerFooterVersion;
+    }
+
+    cachedAgentsServerFooterVersionPromise = readUncachedAgentsServerFooterVersion();
+    cachedAgentsServerFooterVersionExpiresAt = now + AGENTS_SERVER_FOOTER_VERSION_CACHE_TTL_MILLISECONDS;
+    return cachedAgentsServerFooterVersionPromise;
+}
+
+/**
+ * Formats the compact version label shown in the footer.
+ *
+ * @param options - Release tag and optional deployed commit short hash.
+ * @returns Footer version label.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function formatAgentsServerFooterVersionLabel(options: {
+    readonly versionTag: string;
+    readonly currentCommitShortSha: string | null;
+}): string {
+    if (!options.currentCommitShortSha) {
+        return options.versionTag;
+    }
+
+    return `${options.versionTag} (${options.currentCommitShortSha})`;
+}
+
+/**
+ * Normalizes a Git repository clone URL to a browser URL.
+ *
+ * @param repositoryUrl - Git clone URL.
+ * @returns Browser URL for the repository.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function normalizeGitRepositoryWebUrl(repositoryUrl: string): string {
+    const normalizedRepositoryUrl = repositoryUrl
+        .trim()
+        .replace(/^git\+/u, '')
+        .replace(/\.git$/u, '');
+    return normalizedRepositoryUrl || VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL.replace(/\.git$/u, '');
+}
+
+/**
+ * Normalizes a release version into the repository tag format.
+ *
+ * @param value - Raw tag or generated version.
+ * @returns Normalized version tag or `null` when the value is not a release tag.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function normalizeAgentsServerVersionTag(value: string | null | undefined): string | null {
+    const trimmedValue = value?.trim() || '';
+    if (!AGENTS_SERVER_VERSION_TAG_PATTERN.test(trimmedValue)) {
+        return null;
+    }
+
+    return trimmedValue.startsWith('v') ? trimmedValue : `v${trimmedValue}`;
+}
+
+/**
+ * Resolves the URL linked from the footer version text.
+ *
+ * @param options - Repository URL, tag, current commit and comparison state.
+ * @returns Browser URL for the most specific Git reference.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function resolveAgentsServerFooterVersionUrl(options: {
+    readonly repositoryUrl: string;
+    readonly versionTag: string;
+    readonly currentCommitSha: string | null;
+    readonly isCurrentCommitNewerThanVersionTag: boolean;
+}): string {
+    if (!options.repositoryUrl.startsWith('https://github.com/')) {
+        return options.repositoryUrl;
+    }
+
+    if (options.isCurrentCommitNewerThanVersionTag && options.currentCommitSha) {
+        return `${options.repositoryUrl}/commit/${options.currentCommitSha}`;
+    }
+
+    return `${options.repositoryUrl}/releases/tag/${encodeURIComponent(options.versionTag)}`;
+}
+
+/**
+ * Reads the footer version summary without using the module-level cache.
+ *
+ * @returns Git-derived Agents Server version information.
+ */
+async function readUncachedAgentsServerFooterVersion(): Promise<AgentsServerFooterVersion> {
+    const repositoryUrl = normalizeGitRepositoryWebUrl(await readFooterVersionOriginRepositoryUrl());
+    const repositoryDirectory = await resolveAgentsServerFooterRepositoryDirectory();
+
+    if (!repositoryDirectory) {
+        return createFallbackAgentsServerFooterVersion(repositoryUrl);
+    }
+
+    const [currentCommit, versionTag] = await Promise.all([
+        readCommitMetadataFromRepository(repositoryDirectory, 'HEAD'),
+        readAgentsServerVersionTagFromRepository(repositoryDirectory),
+    ]);
+    const versionCommit = await readCommitMetadataFromRepository(repositoryDirectory, `${versionTag}^{commit}`);
+    const currentCommitSha = currentCommit?.commitSha ?? readCurrentCommitShaFromEnvironment();
+    const currentCommitShortSha = abbreviateCommitSha(currentCommitSha);
+    const versionCommitSha = versionCommit?.commitSha ?? null;
+    const isCurrentCommitNewerThanVersionTag = Boolean(
+        currentCommitSha && versionCommitSha && currentCommitSha !== versionCommitSha,
+    );
+    const displayedCommitShortSha = isCurrentCommitNewerThanVersionTag ? currentCommitShortSha : null;
+
+    return {
+        versionTag,
+        label: formatAgentsServerFooterVersionLabel({
+            versionTag,
+            currentCommitShortSha: displayedCommitShortSha,
+        }),
+        repositoryUrl,
+        versionUrl: resolveAgentsServerFooterVersionUrl({
+            repositoryUrl,
+            versionTag,
+            currentCommitSha,
+            isCurrentCommitNewerThanVersionTag,
+        }),
+        currentCommitSha,
+        currentCommitShortSha,
+        versionCommitSha,
+        releasedAt: versionCommit?.authoredAt ?? null,
+    };
+}
+
+/**
+ * Reads the configured origin URL without letting optional VPS configuration block footer rendering.
+ *
+ * @returns Configured origin URL or the default Promptbook repository.
+ */
+async function readFooterVersionOriginRepositoryUrl(): Promise<string> {
+    try {
+        return await readConfiguredVpsSelfUpdateOriginRepositoryUrl();
+    } catch {
+        return VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL;
+    }
+}
+
+/**
+ * Resolves a local Git checkout suitable for lightweight version metadata reads.
+ *
+ * @returns Repository directory or `null` when Git metadata is unavailable.
+ */
+async function resolveAgentsServerFooterRepositoryDirectory(): Promise<string | null> {
+    const managedRepositoryDirectory = await resolveManagedPromptbookRepositoryDirectory().catch(() => null);
+    const candidateDirectories = [
+        managedRepositoryDirectory,
+        process.env.PTBK_REPOSITORY_DIR?.trim() || null,
+        process.cwd(),
+    ];
+
+    for (const candidateDirectory of candidateDirectories) {
+        if (!candidateDirectory) {
+            continue;
+        }
+
+        const gitRepositoryRoot = await runGitInRepository(candidateDirectory, ['rev-parse', '--show-toplevel']);
+        if (gitRepositoryRoot) {
+            return candidateDirectory;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Reads the nearest reachable release tag for the deployed checkout.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @returns Normalized release tag.
+ */
+async function readAgentsServerVersionTagFromRepository(repositoryDirectory: string): Promise<string> {
+    const describedTag = await runGitInRepository(repositoryDirectory, [
+        'describe',
+        '--tags',
+        '--abbrev=0',
+        ...GIT_DESCRIBE_VERSION_TAG_MATCH_ARGUMENTS,
+        'HEAD',
+    ]);
+
+    return (
+        normalizeAgentsServerVersionTag(describedTag) ??
+        normalizeAgentsServerVersionTag(DEFAULT_AGENTS_SERVER_VERSION_TAG) ??
+        DEFAULT_AGENTS_SERVER_VERSION_TAG
+    );
+}
+
+/**
+ * Reads the deployed commit hash from public deployment metadata when local Git is unavailable.
+ *
+ * @returns Commit hash or `null`.
+ */
+function readCurrentCommitShaFromEnvironment(): string | null {
+    return process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA?.trim() || null;
+}
+
+/**
+ * Creates a resilient fallback when the server cannot inspect a Git checkout.
+ *
+ * @param repositoryUrl - Browser URL of the configured Git repository.
+ * @returns Fallback footer version summary.
+ */
+function createFallbackAgentsServerFooterVersion(repositoryUrl: string): AgentsServerFooterVersion {
+    const currentCommitSha = readCurrentCommitShaFromEnvironment();
+    const versionTag =
+        normalizeAgentsServerVersionTag(DEFAULT_AGENTS_SERVER_VERSION_TAG) ?? DEFAULT_AGENTS_SERVER_VERSION_TAG;
+
+    return {
+        versionTag,
+        label: formatAgentsServerFooterVersionLabel({
+            versionTag,
+            currentCommitShortSha: null,
+        }),
+        repositoryUrl,
+        versionUrl: resolveAgentsServerFooterVersionUrl({
+            repositoryUrl,
+            versionTag,
+            currentCommitSha,
+            isCurrentCommitNewerThanVersionTag: false,
+        }),
+        currentCommitSha,
+        currentCommitShortSha: abbreviateCommitSha(currentCommitSha),
+        versionCommitSha: null,
+        releasedAt: null,
+    };
+}

package/apps/agents-server/src/utils/vpsSelfUpdate/readPersistedVpsSelfUpdateJob.ts

@@ -4,6 +4,7 @@ import {
     decodeVpsSelfUpdateStatusField,
     readLastVpsSelfUpdateTextFileChunk,
     readVpsSelfUpdateStatusFile,
+    readVpsSelfUpdateStatusFileModifiedAt,
     resolveVpsSelfUpdateLogFilePath,
 } from './vpsSelfUpdateStateFiles';
 import type {
@@ -75,6 +76,12 @@ export async function readPersistedVpsSelfUpdateJob(
     const trigger = isVpsSelfUpdateJobTrigger(rawTrigger) ? rawTrigger : 'manual';
     const isStale = status === 'running' && pid !== null ? !(await isVpsSelfUpdateProcessAlive(pid)) : false;
     const databaseMigrations = parseVpsSelfUpdateDatabaseMigrationSnapshot(statusEntries, status);
+    // A successful self-update restarts the server, which usually terminates the detached installer
+    // before it can write its own `FINISHED_AT`. When such a run is now stale (running status, dead
+    // process), fall back to the status file's last-write time so the real total update time is
+    // still reported instead of a misleading zero-second duration.
+    const recordedFinishedAt = statusEntries.get('FINISHED_AT') || null;
+    const finishedAt = recordedFinishedAt || (isStale ? await readVpsSelfUpdateStatusFileModifiedAt() : null);
 
     return {
         jobId,
@@ -88,7 +95,7 @@ export async function readPersistedVpsSelfUpdateJob(
         targetCommitSha: statusEntries.get('TARGET_COMMIT') || null,
         errorMessage: isStale && !errorMessage ? VPS_SELF_UPDATE_STALE_ERROR_MESSAGE : errorMessage,
         startedAt: statusEntries.get('STARTED_AT') || null,
-        finishedAt: statusEntries.get('FINISHED_AT') || null,
+        finishedAt,
         isStale,
         logTail: options.isLogTailIncluded === false ? null : await readLastVpsSelfUpdateTextFileChunk(logFilePath),
         logFilePath,

package/apps/agents-server/src/utils/vpsSelfUpdate/startVpsSelfUpdate.ts

@@ -25,7 +25,7 @@ import type { VpsSelfUpdateJobTrigger, VpsSelfUpdateOverview, VpsSelfUpdateStart
 /**
  * Starts one detached VPS self-update run for the selected environment.
  *
- * The actual update is executed by `other/vps/install.sh self-update`, while this
+ * The actual update is executed by `install.sh self-update`, while this
  * helper writes the initial persisted state and detaches the background process so
  * the triggering HTTP request can finish before pm2 restarts the server.
  *

package/apps/agents-server/src/utils/vpsSelfUpdate/vpsSelfUpdateAutomaticConfiguration.ts

@@ -75,7 +75,7 @@ export async function readVpsSelfUpdateAutomaticConfiguration(): Promise<VpsSelf
 /**
  * Saves automatic self-update configuration through the shared VPS `.env` writer.
  *
- * @param update - Raw configuration payload from `/admin/update`.
+ * @param update - Raw configuration payload from `/superadmin/update`.
  * @returns Normalized automatic self-update configuration.
  *
  * @private function of `vpsSelfUpdate`

package/apps/agents-server/src/utils/vpsSelfUpdate/vpsSelfUpdateInstalledVersions.ts

@@ -17,7 +17,7 @@ export const AGENTS_SERVER_GC_KEEP_VERSIONS_ENV_NAME = 'AGENTS_SERVER_GC_KEEP_VE
 /**
  * Default total number of installed versions kept by garbage collection (the current one plus two previous ones).
  *
- * Note: [🧹] Keep in sync with the `AGENTS_SERVER_GC_KEEP_VERSIONS` default in `other/vps/install.sh`.
+ * Note: [🧹] Keep in sync with the `AGENTS_SERVER_GC_KEEP_VERSIONS` default in `install.sh`.
  *
  * @private constant of `vpsSelfUpdate`
  */

package/apps/agents-server/src/utils/vpsSelfUpdate/vpsSelfUpdateJobHistory.ts

@@ -3,10 +3,17 @@ import { dirname } from 'path';
 import { resolveVpsSelfUpdateEnvironment } from './vpsSelfUpdateEnvironment';
 import { resolveVpsSelfUpdateJobIdentity } from './vpsSelfUpdateJobIdentity';
 import { readPersistedVpsSelfUpdateJob } from './readPersistedVpsSelfUpdateJob';
+import { resolveVpsSelfUpdateJobForOverview } from './resolveVpsSelfUpdateJobForOverview';
+import {
+    readCurrentVpsSelfUpdateEnvironment,
+    resolveManagedPromptbookRepositoryDirectory,
+} from './vpsSelfUpdateConfiguration';
+import { readCommitMetadataFromRepository } from './vpsSelfUpdateRepository';
 import { resolveVpsSelfUpdateTaskHistoryFilePath } from './vpsSelfUpdateStateFiles';
 import type {
     VpsSelfUpdateDatabaseMigrationSnapshot,
     VpsSelfUpdateDatabaseMigrationStatus,
+    VpsSelfUpdateJobOverviewContext,
     VpsSelfUpdateJobSnapshot,
     VpsSelfUpdateJobStatus,
     VpsSelfUpdateJobTrigger,
@@ -55,34 +62,61 @@ type VpsSelfUpdateTaskHistoryFile = {
     readonly jobs: ReadonlyArray<VpsSelfUpdateJobSnapshot>;
 };
 
+/**
+ * Options for reading task-manager self-update snapshots.
+ *
+ * @private type of `vpsSelfUpdate`
+ */
+type ReadVpsSelfUpdateJobTaskSnapshotsOptions = {
+    /**
+     * Current runtime state used to reinterpret a stale restart as a successful update.
+     */
+    readonly overviewContext?: VpsSelfUpdateJobOverviewContext | null;
+};
+
 /**
  * Archives one latest self-update snapshot before a new self-update overwrites the singleton status file.
  *
  * @param job - Latest job snapshot to preserve in task history.
+ * @param options - Optional current runtime state override.
  *
  * @private function of `vpsSelfUpdate`
  */
-export async function preserveVpsSelfUpdateJobInTaskHistory(job: VpsSelfUpdateJobSnapshot): Promise<void> {
+export async function preserveVpsSelfUpdateJobInTaskHistory(
+    job: VpsSelfUpdateJobSnapshot,
+    options: ReadVpsSelfUpdateJobTaskSnapshotsOptions = {},
+): Promise<void> {
     if (job.status === 'idle') {
         return;
     }
 
+    const [resolvedJob] = await resolveVpsSelfUpdateJobTaskSnapshots([job], options);
     const history = await readVpsSelfUpdateJobTaskHistory();
-    const jobs = collectUniqueVpsSelfUpdateJobs([sanitizeVpsSelfUpdateJobForTaskHistory(job), ...history]);
+    const jobs = collectUniqueVpsSelfUpdateJobs([
+        sanitizeVpsSelfUpdateJobForTaskHistory(resolvedJob ?? job),
+        ...history,
+    ]);
     await writeVpsSelfUpdateJobTaskHistory(jobs);
 }
 
 /**
  * Reads all self-update task snapshots that should be surfaced in the admin task manager.
  *
+ * A successful self-update can restart the old server before it writes the final succeeded status.
+ * Task-manager rows therefore use the same target-commit reconciliation as `/superadmin/update`.
+ *
+ * @param options - Optional current runtime state override.
  * @returns Latest singleton status followed by archived history, with duplicates removed.
  *
  * @private function of `vpsSelfUpdate`
  */
-export async function readVpsSelfUpdateJobTaskSnapshots(): Promise<Array<VpsSelfUpdateJobSnapshot>> {
+export async function readVpsSelfUpdateJobTaskSnapshots(
+    options: ReadVpsSelfUpdateJobTaskSnapshotsOptions = {},
+): Promise<Array<VpsSelfUpdateJobSnapshot>> {
     const latestJob = await readPersistedVpsSelfUpdateJob({ isLogTailIncluded: false });
     const history = await readVpsSelfUpdateJobTaskHistory();
-    return collectUniqueVpsSelfUpdateJobs([latestJob, ...history]).filter((job) => job.status !== 'idle');
+    const jobs = collectUniqueVpsSelfUpdateJobs([latestJob, ...history]).filter((job) => job.status !== 'idle');
+    return await resolveVpsSelfUpdateJobTaskSnapshots(jobs, options);
 }
 
 /**
@@ -155,6 +189,75 @@ function collectUniqueVpsSelfUpdateJobs(
     return [...jobsByIdentity.values()];
 }
 
+/**
+ * Resolves restart-aware task snapshots through the shared update-page reconciliation.
+ *
+ * @param jobs - Self-update task snapshots.
+ * @param options - Optional current runtime state override.
+ * @returns Resolved task snapshots.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+async function resolveVpsSelfUpdateJobTaskSnapshots(
+    jobs: ReadonlyArray<VpsSelfUpdateJobSnapshot>,
+    options: ReadVpsSelfUpdateJobTaskSnapshotsOptions,
+): Promise<Array<VpsSelfUpdateJobSnapshot>> {
+    if (!jobs.some(isRestartedVpsSelfUpdateCandidate)) {
+        return [...jobs];
+    }
+
+    const overviewContext =
+        options.overviewContext === undefined
+            ? await readCurrentVpsSelfUpdateJobOverviewContext()
+            : options.overviewContext;
+
+    if (!overviewContext) {
+        return [...jobs];
+    }
+
+    return jobs.map((job) => resolveVpsSelfUpdateJobForOverview(job, overviewContext));
+}
+
+/**
+ * Returns whether a job could be the stale old process left by a successful restart.
+ *
+ * The full success check stays inside `resolveVpsSelfUpdateJobForOverview`; this predicate only avoids
+ * local git reads for ordinary completed, failed, or running jobs.
+ *
+ * @param job - Self-update job snapshot.
+ * @returns `true` when current repository state may change how the job should be displayed.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+function isRestartedVpsSelfUpdateCandidate(job: VpsSelfUpdateJobSnapshot): boolean {
+    return job.status === 'failed' && job.isStale;
+}
+
+/**
+ * Reads the lightweight current runtime state required for self-update restart reconciliation.
+ *
+ * @returns Current job overview context or `null` when local repository state is unavailable.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+async function readCurrentVpsSelfUpdateJobOverviewContext(): Promise<VpsSelfUpdateJobOverviewContext | null> {
+    const currentEnvironment = await readCurrentVpsSelfUpdateEnvironment();
+    const repositoryDirectory = await resolveManagedPromptbookRepositoryDirectory();
+    if (!repositoryDirectory) {
+        return null;
+    }
+
+    const currentCommit = await readCommitMetadataFromRepository(repositoryDirectory, 'HEAD');
+    if (!currentCommit) {
+        return null;
+    }
+
+    return {
+        currentEnvironment,
+        currentCommitSha: currentCommit.commitSha,
+    };
+}
+
 /**
  * Removes log text before persisting a task-history snapshot.
  *

package/apps/agents-server/src/utils/vpsSelfUpdate/vpsSelfUpdateStateFiles.ts

@@ -110,6 +110,30 @@ export async function readVpsSelfUpdateStatusFile(): Promise<Map<string, string>
     }
 }
 
+/**
+ * Reads the last modification time of the persisted shell-owned self-update status file.
+ *
+ * Used as the effective finish time when a self-update process is terminated by the server
+ * restart it triggers before it can record its own `FINISHED_AT` timestamp.
+ *
+ * @returns ISO modification timestamp or `null` when the status file does not exist yet.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateStatusFileModifiedAt(): Promise<string | null> {
+    const statusFilePath = resolveVpsSelfUpdateStatusFilePath();
+    try {
+        const statusFileStats = await stat(statusFilePath);
+        return statusFileStats.mtime.toISOString();
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
 /**
  * Writes the minimal initial status file before the detached installer takes over.
  *