@supacloud/admin 0.7.7 → 0.7.9

package/dist/index.js

@@ -24926,10 +24926,12 @@ import { realpathSync } from "node:fs";
 
 // src/shared/transports/ssh.ts
 var import_ssh2 = __toESM(require_lib3(), 1);
-import { timingSafeEqual } from "node:crypto";
+import { randomUUID, timingSafeEqual } from "node:crypto";
 import { readFileSync } from "node:fs";
 var DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 var MAX_CONFIGURABLE_OUTPUT_BYTES = 16 * 1024 * 1024;
+var DEFAULT_UPLOAD_TIMEOUT_MS = 10 * 60000;
+var DEFAULT_TEXT_UPLOAD_TIMEOUT_MS = 60000;
 function normalizeSshHostFingerprint(value) {
   const trimmed = value.trim();
   const match = trimmed.match(/^SHA256:([A-Za-z0-9+/]{43}=?)$/);
@@ -25143,12 +25145,12 @@ class SshTransport {
         const stderr = new BoundedOutputCollector(outputLimit);
         const timer = setTimeout(() => {
           connectionReusable = false;
-          this.pool.discard(conn);
           reject(new Error(`SSH command timed out after ${timeoutMs}ms`));
         }, timeoutMs);
         conn.exec(command, (err, stream) => {
           if (err) {
             clearTimeout(timer);
+            connectionReusable = false;
             return reject(err);
           }
           stream.on("close", (code) => {
@@ -25161,6 +25163,10 @@ class SshTransport {
               stdoutTruncated: stdout.truncated,
               stderrTruncated: stderr.truncated
             });
+          }).on("error", (streamError) => {
+            clearTimeout(timer);
+            connectionReusable = false;
+            reject(streamError);
           }).on("data", (data) => {
             stdout.append(data);
           }).stderr.on("data", (data) => {
@@ -25171,47 +25177,67 @@ class SshTransport {
     } finally {
       if (connectionReusable)
         this.pool.release(conn);
+      else
+        this.pool.discard(conn);
     }
   }
-  async upload(localPath, remotePath) {
-    const conn = await this.pool.acquire();
-    try {
-      return await new Promise((resolve, reject) => {
-        conn.sftp((err, sftp) => {
-          if (err)
-            return reject(err);
-          sftp.fastPut(localPath, remotePath, (err2) => {
-            if (err2)
-              return reject(err2);
-            resolve();
-          });
-        });
-      });
-    } finally {
-      this.pool.release(conn);
-    }
+  async upload(localPath, remotePath, options = {}) {
+    const mode = normalizeUploadMode(options.mode);
+    const timeoutMs = normalizeUploadTimeout(options.timeoutMs, DEFAULT_UPLOAD_TIMEOUT_MS);
+    const partialPath = `${remotePath}.part-${randomUUID()}`;
+    auditCommand(`upload ${remotePath} (local content redacted)`, this.config.host, false);
+    await this.runSftpOperation(timeoutMs, async (sftp) => {
+      try {
+        await sftpFastPut(sftp, localPath, partialPath);
+        await sftpChmod(sftp, partialPath, mode);
+        await sftpRename(sftp, partialPath, remotePath);
+      } catch (error) {
+        await removePartialUpload(sftp, partialPath, error);
+      }
+    });
   }
   async uploadText(remotePath, content, mode = 384) {
     auditCommand(`upload ${remotePath} (${Buffer.byteLength(content)} bytes; content redacted)`, this.config.host, false);
+    const normalizedMode = normalizeUploadMode(mode);
+    const partialPath = `${remotePath}.part-${randomUUID()}`;
+    await this.runSftpOperation(DEFAULT_TEXT_UPLOAD_TIMEOUT_MS, async (sftp) => {
+      try {
+        await sftpWriteFile(sftp, partialPath, content, normalizedMode);
+        await sftpChmod(sftp, partialPath, normalizedMode);
+        await sftpRename(sftp, partialPath, remotePath);
+      } catch (error) {
+        await removePartialUpload(sftp, partialPath, error);
+      }
+    });
+  }
+  async runSftpOperation(timeoutMs, operation) {
     const conn = await this.pool.acquire();
+    let connectionReusable = true;
+    let timeoutHandle;
     try {
-      await new Promise((resolve, reject) => {
-        conn.sftp((err, sftp) => {
-          if (err)
-            return reject(err);
-          sftp.writeFile(remotePath, content, { mode }, (writeError) => {
-            if (writeError)
-              return reject(writeError);
-            sftp.chmod(remotePath, mode, (chmodError) => {
-              if (chmodError)
-                return reject(chmodError);
-              resolve();
-            });
-          });
-        });
+      const operationPromise = openSftp(conn).then(async (sftp) => {
+        await operation(sftp);
+        sftp.end();
       });
+      await Promise.race([
+        operationPromise,
+        new Promise((_resolve, reject) => {
+          timeoutHandle = setTimeout(() => {
+            connectionReusable = false;
+            reject(new Error(`SFTP upload timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        })
+      ]);
+    } catch (error) {
+      connectionReusable = false;
+      throw error;
     } finally {
-      this.pool.release(conn);
+      if (timeoutHandle)
+        clearTimeout(timeoutHandle);
+      if (connectionReusable)
+        this.pool.release(conn);
+      else
+        this.pool.discard(conn);
     }
   }
   async ping() {
@@ -25222,6 +25248,58 @@ class SshTransport {
     this.pool.closeAll();
   }
 }
+function normalizeUploadMode(mode = 384) {
+  if (!Number.isInteger(mode) || mode < 0 || mode > 511)
+    throw new Error("Upload mode must be an octal permission between 000 and 777");
+  return mode;
+}
+function normalizeUploadTimeout(timeoutMs, fallback) {
+  const resolved = timeoutMs ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > 60 * 60000) {
+    throw new Error("Upload timeout must be between 1ms and 1 hour");
+  }
+  return resolved;
+}
+function openSftp(conn) {
+  return new Promise((resolve, reject) => {
+    conn.sftp((error, sftp) => error ? reject(error) : resolve(sftp));
+  });
+}
+function sftpFastPut(sftp, localPath, remotePath) {
+  return new Promise((resolve, reject) => {
+    sftp.fastPut(localPath, remotePath, (error) => error ? reject(error) : resolve());
+  });
+}
+function sftpWriteFile(sftp, remotePath, content, mode) {
+  return new Promise((resolve, reject) => {
+    sftp.writeFile(remotePath, content, { mode }, (error) => error ? reject(error) : resolve());
+  });
+}
+function sftpChmod(sftp, remotePath, mode) {
+  return new Promise((resolve, reject) => {
+    sftp.chmod(remotePath, mode, (error) => error ? reject(error) : resolve());
+  });
+}
+function sftpRename(sftp, sourcePath, destinationPath) {
+  return new Promise((resolve, reject) => {
+    sftp.rename(sourcePath, destinationPath, (error) => error ? reject(error) : resolve());
+  });
+}
+function sftpUnlink(sftp, remotePath) {
+  return new Promise((resolve, reject) => {
+    sftp.unlink(remotePath, (error) => error ? reject(error) : resolve());
+  });
+}
+async function removePartialUpload(sftp, partialPath, uploadError) {
+  try {
+    await sftpUnlink(sftp, partialPath);
+  } catch (cleanupError) {
+    if (cleanupError.code === 2)
+      throw uploadError;
+    throw new AggregateError([uploadError, cleanupError], `SFTP upload failed and partial cleanup did not complete: ${partialPath}`);
+  }
+  throw uploadError;
+}
 
 // src/shared/cli.ts
 function coerceCliValue(value) {
@@ -25239,7 +25317,10 @@ function sanitizedCliDiagnostic(error) {
 }
 function nestedCliDiagnostics(error) {
   if (error instanceof AggregateError) {
-    return error.errors.flatMap((candidate) => nestedCliDiagnostics(candidate));
+    return [
+      sanitizedCliDiagnostic(error),
+      ...error.errors.flatMap((candidate) => nestedCliDiagnostics(candidate))
+    ];
   }
   return [sanitizedCliDiagnostic(error)];
 }
@@ -25621,7 +25702,1388 @@ class HttpTransport {
 }
 
 // src/shared/tools/ssh-tools.ts
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { dirname } from "node:path";
+
+// src/shared/releases/local-upgrade-transfer.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+import { basename as basename2 } from "node:path";
+
+// ../management-api/src/upgrade-lock.ts
+var SUPACLOUD_UPGRADE_LOCK_PATH = "/run/lock/supacloud-upgrade.lock";
+var INHERITED_UPGRADE_LOCK_FD = 9;
+var UPGRADE_LOCK_FD_ENV = "SUPACLOUD_UPGRADE_LOCK_FD";
+function buildUpgradeLockScript(lockPath) {
+  return [
+    `UPGRADE_LOCK=${quoteShell(lockPath)}`,
+    `test ! -L "$UPGRADE_LOCK" || { echo 'SupaCloud upgrade lock must not be a symlink' >&2; exit 1; }`,
+    'if [ ! -e "$UPGRADE_LOCK" ]; then (umask 077; : >> "$UPGRADE_LOCK"); fi',
+    `test -f "$UPGRADE_LOCK" && test ! -L "$UPGRADE_LOCK" || { echo 'SupaCloud upgrade lock must be a regular file' >&2; exit 1; }`,
+    `test "$(stat -c '%u:%g' "$UPGRADE_LOCK")" = "$(id -u):$(id -g)" || { echo 'SupaCloud upgrade lock has an unexpected owner' >&2; exit 1; }`,
+    `LOCK_MODE=$(stat -c '%a' "$UPGRADE_LOCK")`,
+    `case "$LOCK_MODE" in [0-7]|[0-7][0-7]|[0-7][0-7][0-7]) ;; *) echo 'SupaCloud upgrade lock has special permission bits' >&2; exit 1 ;; esac`,
+    "(( (8#$LOCK_MODE & 0022) == 0 )) || { echo 'SupaCloud upgrade lock is group/other writable' >&2; exit 1; }",
+    `exec ${INHERITED_UPGRADE_LOCK_FD}<>"$UPGRADE_LOCK"`,
+    `flock -E 75 -n ${INHERITED_UPGRADE_LOCK_FD} || { echo 'Another SupaCloud upgrade is already running' >&2; exit 75; }`,
+    `export ${UPGRADE_LOCK_FD_ENV}=${INHERITED_UPGRADE_LOCK_FD}`
+  ].join(`
+`);
+}
+function quoteShell(shellText) {
+  return `'${shellText.split("'").join("'\\''")}'`;
+}
+
+// src/shared/releases/local-upgrade-bundle.ts
+import { spawn } from "node:child_process";
+import { createHash, randomUUID as randomUUID2 } from "node:crypto";
+import { accessSync, chmodSync, constants as fsConstants, createWriteStream, mkdirSync, mkdtempSync, readFileSync as readFileSync3, rmSync, statSync, writeFileSync } from "node:fs";
+import { get } from "node:https";
+import { tmpdir } from "node:os";
+import { basename, delimiter, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Transform as Transform2 } from "node:stream";
+
+// ../management-api/src/release-manifest.ts
+var RELEASE_MANIFEST_NAME = "SUPACLOUD-RELEASE.json";
+var RELEASE_ATTESTATION_NAME = "SUPACLOUD-RELEASE.attestation.jsonl";
+var RELEASE_CHECKSUMS_NAME = "SHA256SUMS";
+var RELEASE_REPOSITORY = "zuohuadong/supacloud";
+var RELEASE_SOURCE_REF = "refs/heads/main";
+var RELEASE_SIGNER_WORKFLOW = `${RELEASE_REPOSITORY}/.github/workflows/release-please.yml`;
+var MEBIBYTE = 1024 * 1024;
+var RELEASE_BUNDLE_SIZE_LIMITS = {
+  manifest: MEBIBYTE,
+  checksums: MEBIBYTE,
+  attestation: 32 * MEBIBYTE,
+  managementBinary: 160 * MEBIBYTE,
+  edgeRuntimeBinary: 160 * MEBIBYTE,
+  webConsole: 64 * MEBIBYTE,
+  caddy: 96 * MEBIBYTE,
+  total: 384 * MEBIBYTE
+};
+var RELEASE_ASSETS = {
+  "management-api": [
+    "SHA256SUMS",
+    "SHA256SUMS.caddy",
+    "supacloud-caddy-linux-amd64",
+    "supacloud-caddy-linux-arm64",
+    "supacloud-linux-amd64",
+    "supacloud-linux-arm64",
+    "supacloud-macos-amd64",
+    "supacloud-macos-arm64",
+    "web-console-build.tar.gz"
+  ],
+  "edge-runtime": [
+    "SHA256SUMS",
+    "supacloud-edge-runtime-linux-amd64",
+    "supacloud-edge-runtime-linux-arm64",
+    "supacloud-edge-runtime-macos-amd64",
+    "supacloud-edge-runtime-macos-arm64"
+  ]
+};
+function manifestObject(candidate, label) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return candidate;
+}
+function assertExactKeys(record, keys, label) {
+  const actual = Object.keys(record).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new Error(`${label} contains unsupported or missing fields`);
+  }
+}
+function exactStableVersion(version) {
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new Error("Release manifest version must be an exact stable version");
+  }
+  return version;
+}
+function releaseTag(component, version) {
+  exactStableVersion(version);
+  return `${component}-v${version}`;
+}
+function releaseAssetNames(component) {
+  return RELEASE_ASSETS[component];
+}
+function releaseAssetSizeLimit(component, name) {
+  if (name === "SHA256SUMS" || name === "SHA256SUMS.caddy") {
+    return RELEASE_BUNDLE_SIZE_LIMITS.checksums;
+  }
+  if (name === "web-console-build.tar.gz")
+    return RELEASE_BUNDLE_SIZE_LIMITS.webConsole;
+  if (name.startsWith("supacloud-caddy-"))
+    return RELEASE_BUNDLE_SIZE_LIMITS.caddy;
+  return component === "management-api" ? RELEASE_BUNDLE_SIZE_LIMITS.managementBinary : RELEASE_BUNDLE_SIZE_LIMITS.edgeRuntimeBinary;
+}
+function parseSource(candidate) {
+  const source = manifestObject(candidate, "Release manifest source");
+  assertExactKeys(source, ["ref", "commit"], "Release manifest source");
+  if (source.ref !== RELEASE_SOURCE_REF || typeof source.commit !== "string" || !/^[0-9a-f]{40}$/.test(source.commit)) {
+    throw new Error("Release manifest source is invalid");
+  }
+  return { ref: RELEASE_SOURCE_REF, commit: source.commit };
+}
+function parseRelease(candidate, expected) {
+  const release = manifestObject(candidate, "Release manifest release");
+  assertExactKeys(release, ["component", "version", "tag"], "Release manifest release");
+  const version = exactStableVersion(release.version);
+  if (release.component !== expected.component || version !== expected.version || release.tag !== releaseTag(expected.component, expected.version)) {
+    throw new Error("Release manifest component, version, or tag does not match the requested release");
+  }
+  return { component: expected.component, version, tag: release.tag };
+}
+function parseArtifact(candidate, index) {
+  const artifact = manifestObject(candidate, `Release manifest artifact ${index}`);
+  assertExactKeys(artifact, ["name", "sha256", "size"], `Release manifest artifact ${index}`);
+  if (typeof artifact.name !== "string" || !/^[A-Za-z0-9._-]+$/.test(artifact.name) || typeof artifact.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(artifact.sha256) || !Number.isSafeInteger(artifact.size) || artifact.size <= 0) {
+    throw new Error(`Release manifest artifact ${index} is invalid`);
+  }
+  return artifact;
+}
+function parseArtifacts(candidate, component) {
+  if (!Array.isArray(candidate))
+    throw new Error("Release manifest artifacts must be an array");
+  const artifacts = candidate.map(parseArtifact);
+  const expectedNames = releaseAssetNames(component);
+  const actualNames = artifacts.map((artifact) => artifact.name);
+  if (actualNames.length !== expectedNames.length || actualNames.some((name, index) => name !== expectedNames[index])) {
+    throw new Error(`Release manifest artifacts do not match the ${component} allowlist`);
+  }
+  const oversized = artifacts.find((artifact) => artifact.size > releaseAssetSizeLimit(component, artifact.name));
+  if (oversized)
+    throw new Error(`Release manifest artifact ${oversized.name} exceeds its size limit`);
+  return artifacts;
+}
+function parseReleaseManifest(text, expected) {
+  let candidate;
+  try {
+    candidate = JSON.parse(text);
+  } catch {
+    throw new Error("Release manifest is not valid JSON");
+  }
+  const manifest = manifestObject(candidate, "Release manifest");
+  assertExactKeys(manifest, ["schemaVersion", "repository", "source", "workflow", "release", "artifacts"], "Release manifest");
+  if (manifest.schemaVersion !== 1 || manifest.repository !== RELEASE_REPOSITORY || manifest.workflow !== RELEASE_SIGNER_WORKFLOW) {
+    throw new Error("Release manifest identity is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    repository: RELEASE_REPOSITORY,
+    source: parseSource(manifest.source),
+    workflow: RELEASE_SIGNER_WORKFLOW,
+    release: parseRelease(manifest.release, expected),
+    artifacts: parseArtifacts(manifest.artifacts, expected.component)
+  };
+}
+function manifestArtifact(manifest, name) {
+  const artifact = manifest.artifacts.find((candidate) => candidate.name === name);
+  if (!artifact)
+    throw new Error(`Release manifest does not contain ${name}`);
+  return artifact;
+}
+function parseReleaseChecksums(text, manifest) {
+  const lines = text.endsWith(`
+`) ? text.slice(0, -1).split(`
+`) : text.split(`
+`);
+  const expectedNames = releaseAssetNames(manifest.release.component).filter((name) => name !== RELEASE_CHECKSUMS_NAME);
+  if (lines.length !== expectedNames.length)
+    throw new Error("SHA256SUMS has an unexpected number of entries");
+  const checksums = new Map;
+  lines.forEach((line, index) => {
+    const match = line.match(/^([0-9a-f]{64})  ([A-Za-z0-9._-]+)$/);
+    if (!match || match[2] !== expectedNames[index])
+      throw new Error("SHA256SUMS is not strict or sorted");
+    const [digest, name] = [match[1], match[2]];
+    if (manifestArtifact(manifest, name).sha256 !== digest) {
+      throw new Error(`SHA256SUMS and release manifest disagree for ${name}`);
+    }
+    checksums.set(name, digest);
+  });
+  return checksums;
+}
+
+// src/shared/releases/local-upgrade-bundle.ts
+var RELEASES_API = `https://api.github.com/repos/${RELEASE_REPOSITORY}/releases`;
+var ATTESTATIONS_API = `https://api.github.com/repos/${RELEASE_REPOSITORY}/attestations`;
+var GH_VERSION = "2.96.0";
+var GH_ARCHIVE_SHA256 = {
+  amd64: "83d5c2ccad5498f58bf6368acb1ab32588cf43ab3a4b1c301bf36328b1c8bd60",
+  arm64: "06f86ec7103d41993b76cd78072f43595c34aaa56506d971d9860e67140bf909"
+};
+var MAX_GH_ARCHIVE_BYTES = 64 * 1024 * 1024;
+var DOWNLOAD_TIMEOUT_MS = 10 * 60000;
+var DOWNLOAD_IDLE_TIMEOUT_MS = 30000;
+var GH_CAPABILITY_TIMEOUT_MS = 30000;
+var GH_VERIFICATION_TIMEOUT_MS = 2 * 60000;
+var GH_TERMINATION_GRACE_MS = 2000;
+var MAX_REDIRECTS = 6;
+var RETRYABLE_DOWNLOAD_CODES = new Set([
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENETUNREACH",
+  "EPIPE",
+  "ETIMEDOUT"
+]);
+var OFFICIAL_DOWNLOAD_HOSTS = new Set([
+  "api.github.com",
+  "github.com",
+  "release-assets.githubusercontent.com"
+]);
+var STRICT_GITHUB_CAPABILITY_FLAGS = [
+  "--bundle",
+  "--signer-workflow",
+  "--source-ref",
+  "--source-digest",
+  "--deny-self-hosted-runners"
+];
+
+class RetryableDownloadError extends Error {
+}
+function githubCliArchiveIdentity(architecture) {
+  const directory = `gh_${GH_VERSION}_linux_${architecture}`;
+  return {
+    archiveName: `${directory}.tar.gz`,
+    member: `${directory}/bin/gh`,
+    sha256: GH_ARCHIVE_SHA256[architecture],
+    version: GH_VERSION
+  };
+}
+function sha256File(filePath) {
+  return createHash("sha256").update(readFileSync3(filePath)).digest("hex");
+}
+function assertPrivateLocalFileMode(mode, label) {
+  if (process.platform !== "win32" && (mode & 4095) !== 384) {
+    throw new Error(`${label} must use exact mode 0600 without special permission bits`);
+  }
+}
+function localUpgradeFile(localPath, relativePath) {
+  const stats = statSync(localPath);
+  if (!stats.isFile())
+    throw new Error(`Local upgrade artifact is not a regular file: ${relativePath}`);
+  assertPrivateLocalFileMode(stats.mode, relativePath);
+  return { localPath, relativePath, sha256: sha256File(localPath), size: stats.size };
+}
+function assertExactStableVersion(version, field) {
+  if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new Error(`${field} must be an exact stable semantic version`);
+  }
+}
+function directChildPath(directory, name) {
+  if (basename(name) !== name || !/^[A-Za-z0-9._-]+$/.test(name)) {
+    throw new Error(`Unsafe release asset name: ${name}`);
+  }
+  return join(directory, name);
+}
+function assertOfficialDownloadUrl(url) {
+  if (url.protocol !== "https:" || url.username || url.password || url.port || !OFFICIAL_DOWNLOAD_HOSTS.has(url.hostname)) {
+    throw new Error(`Release download URL is not an approved official GitHub endpoint: ${url.hostname}`);
+  }
+}
+function boundedWriter(maxBytes) {
+  let receivedBytes = 0;
+  return new Transform2({
+    transform(chunk, _encoding, callback) {
+      receivedBytes += chunk.length;
+      if (receivedBytes > maxBytes)
+        callback(new Error(`Download exceeded ${maxBytes} bytes`));
+      else
+        callback(null, chunk);
+    }
+  });
+}
+function responseLocation(currentUrl, location) {
+  if (!location)
+    throw new Error(`HTTPS redirect from ${currentUrl.hostname} did not include Location`);
+  const redirected = new URL(location, currentUrl);
+  assertOfficialDownloadUrl(redirected);
+  return redirected;
+}
+function downloadCanRetry(error) {
+  return error instanceof RetryableDownloadError || RETRYABLE_DOWNLOAD_CODES.has(error.code || "");
+}
+async function consumeDownloadResponse(response, download) {
+  if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400) {
+    response.resume();
+    await downloadHttpsResponse({
+      ...download,
+      url: responseLocation(download.url, response.headers.location),
+      redirects: download.redirects + 1
+    });
+    return;
+  }
+  if (response.statusCode !== 200) {
+    response.resume();
+    const message = `HTTPS download returned HTTP ${response.statusCode ?? "unknown"}`;
+    if (response.statusCode && response.statusCode >= 500)
+      throw new RetryableDownloadError(message);
+    throw new Error(message);
+  }
+  const contentLength = Number(response.headers["content-length"] || 0);
+  if (contentLength > download.maxBytes) {
+    response.resume();
+    throw new Error(`Download Content-Length exceeded ${download.maxBytes} bytes`);
+  }
+  response.setTimeout(DOWNLOAD_IDLE_TIMEOUT_MS, () => response.destroy(new RetryableDownloadError("Release download stalled")));
+  await pipeline(response, boundedWriter(download.maxBytes), createWriteStream(download.destination, { flags: "wx", mode: 384 }));
+}
+function requestDownloadResponse(download, remainingTime) {
+  return new Promise((resolve2, reject) => {
+    const request = get(download.url, { headers: { "User-Agent": "SupaCloud-Admin" } }, (response) => {
+      consumeDownloadResponse(response, download).then(resolve2, reject);
+    });
+    request.setTimeout(DOWNLOAD_IDLE_TIMEOUT_MS, () => request.destroy(new RetryableDownloadError("Release download connection stalled")));
+    request.on("error", reject);
+    const totalTimer = setTimeout(() => request.destroy(new RetryableDownloadError("Release download timed out")), remainingTime);
+    request.on("close", () => clearTimeout(totalTimer));
+  });
+}
+async function downloadHttpsResponse(download) {
+  if (download.redirects > MAX_REDIRECTS)
+    throw new Error("Release download exceeded the redirect limit");
+  const remainingTime = download.deadline - Date.now();
+  if (remainingTime <= 0)
+    throw new Error("Release download timed out");
+  await requestDownloadResponse(download, remainingTime);
+}
+async function downloadDirect(url, destination, maxBytes) {
+  const parsed = new URL(url);
+  assertOfficialDownloadUrl(parsed);
+  const deadline = Date.now() + DOWNLOAD_TIMEOUT_MS;
+  const retryFailures = [];
+  for (let attempt = 1;attempt <= 3; attempt += 1) {
+    rmSync(destination, { force: true });
+    try {
+      await downloadHttpsResponse({ url: parsed, destination, maxBytes, redirects: 0, deadline });
+      chmodSync(destination, 384);
+      return;
+    } catch (error) {
+      if (!downloadCanRetry(error))
+        throw error;
+      retryFailures.push(error);
+    }
+  }
+  throw new AggregateError(retryFailures, `Unable to download ${parsed.hostname}${parsed.pathname}`);
+}
+function parseJsonFile(filePath, label) {
+  const contents = readFileSync3(filePath, "utf8");
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    if (!(error instanceof SyntaxError))
+      throw error;
+    throw new Error(`${label} is not valid JSON`);
+  }
+}
+function parseGithubReleaseMetadata(candidate, expectedTag) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("GitHub release metadata must be an object");
+  }
+  const release = candidate;
+  if (release.tag_name !== expectedTag || release.draft !== false || release.prerelease !== false || !Array.isArray(release.assets)) {
+    throw new Error(`GitHub release metadata does not describe stable release ${expectedTag}`);
+  }
+  const assets = release.assets.map((asset) => githubReleaseAsset(asset, expectedTag));
+  if (new Set(assets.map((asset) => asset.name)).size !== assets.length) {
+    throw new Error(`GitHub release ${expectedTag} contains duplicate asset names`);
+  }
+  return { tag_name: expectedTag, draft: false, prerelease: false, assets };
+}
+function githubReleaseAsset(candidate, expectedTag) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("GitHub release asset metadata must be an object");
+  }
+  const asset = candidate;
+  if (typeof asset.name !== "string" || typeof asset.browser_download_url !== "string") {
+    throw new Error("GitHub release asset metadata is incomplete");
+  }
+  const downloadUrl = new URL(asset.browser_download_url);
+  assertOfficialDownloadUrl(downloadUrl);
+  const expectedPath = `/${RELEASE_REPOSITORY}/releases/download/${expectedTag}/${asset.name}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(asset.name) || downloadUrl.hostname !== "github.com" || downloadUrl.pathname !== expectedPath || downloadUrl.search || downloadUrl.hash) {
+    throw new Error(`Release asset ${asset.name} does not use its official GitHub release path`);
+  }
+  return { name: asset.name, browser_download_url: downloadUrl.toString() };
+}
+function releaseAssetUrl(release, name) {
+  const matching = release.assets.find((asset) => asset.name === name);
+  if (!matching)
+    throw new Error(`Release ${release.tag_name} does not contain ${name}`);
+  return matching.browser_download_url;
+}
+function serializeAttestationBundles(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("GitHub attestation response must be an object");
+  }
+  const attestations = candidate.attestations;
+  if (!Array.isArray(attestations) || attestations.length === 0) {
+    throw new Error("GitHub attestation response did not contain attestations");
+  }
+  const bundles = attestations.map((attestation) => {
+    if (!attestation || typeof attestation !== "object" || Array.isArray(attestation)) {
+      throw new Error("GitHub attestation entry is invalid");
+    }
+    const bundle = attestation.bundle;
+    if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+      throw new Error("GitHub attestation entry did not contain a bundle");
+    }
+    return JSON.stringify(bundle);
+  });
+  return `${bundles.join(`
+`)}
+`;
+}
+function directEnvironment() {
+  const environment = { ...process.env };
+  for (const key of Object.keys(environment)) {
+    if (/(?:^|_)proxy$/i.test(key) || /^(?:SUPACLOUD_GITHUB_PROXIES|NODE_USE_ENV_PROXY)$/.test(key)) {
+      delete environment[key];
+    }
+  }
+  return environment;
+}
+function githubCliExecutable(environment) {
+  for (const directory of (environment.PATH || "").split(delimiter).filter(Boolean)) {
+    const candidate = join(directory, "gh");
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+      const stats = statSync(candidate);
+      if (stats.isFile()) {
+        if (process.platform !== "win32" && (stats.mode & 4095) > 511) {
+          throw new Error(`GitHub CLI executable has special permission bits: ${candidate}`);
+        }
+        return candidate;
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "EACCES" && error.code !== "ENOTDIR")
+        throw error;
+    }
+  }
+  throw new Error("GitHub CLI executable was not found in PATH");
+}
+async function runGithubCli(arguments_, timeoutMs) {
+  return await new Promise((resolve2, reject) => {
+    const environment = directEnvironment();
+    const child = spawn(githubCliExecutable(environment), arguments_, {
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let forceKillTimer;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      forceKillTimer = setTimeout(() => child.kill("SIGKILL"), GH_TERMINATION_GRACE_MS);
+    }, timeoutMs);
+    const settleExecution = (error, exitCode) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timeout);
+      if (forceKillTimer)
+        clearTimeout(forceKillTimer);
+      if (error)
+        reject(error);
+      else
+        resolve2({ exitCode: timedOut ? 124 : exitCode, stdout, stderr });
+    };
+    child.stdout.on("data", (chunk) => {
+      stdout = `${stdout}${chunk.toString()}`.slice(-8000);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = `${stderr}${chunk.toString()}`.slice(-8000);
+    });
+    child.once("error", (error) => settleExecution(error, 127));
+    child.once("close", (code) => settleExecution(undefined, code ?? 1));
+  });
+}
+function supportsStrictGithubVerification(execution) {
+  const tokens = `${execution.stdout}
+${execution.stderr}`.split(/\s+/);
+  return execution.exitCode === 0 && STRICT_GITHUB_CAPABILITY_FLAGS.every((flag) => tokens.some((token) => token === flag || token.startsWith(`${flag}=`)));
+}
+async function assertLocalGithubVerifier() {
+  const help = await runGithubCli(["attestation", "verify", "--help"], GH_CAPABILITY_TIMEOUT_MS);
+  if (!supportsStrictGithubVerification(help)) {
+    throw new Error("Local artifact transport requires a current gh attestation verifier");
+  }
+}
+async function verifyManifestAttestation(manifestPath, bundlePath, manifest) {
+  const verification = await runGithubCli([
+    "attestation",
+    "verify",
+    manifestPath,
+    "--bundle",
+    bundlePath,
+    "--repo",
+    RELEASE_REPOSITORY,
+    "--signer-workflow",
+    RELEASE_SIGNER_WORKFLOW,
+    "--source-ref",
+    RELEASE_SOURCE_REF,
+    "--source-digest",
+    manifest.source.commit,
+    "--deny-self-hosted-runners"
+  ], GH_VERIFICATION_TIMEOUT_MS);
+  if (verification.exitCode !== 0) {
+    throw new Error(`gh attestation verify failed: ${verification.stderr.trim().slice(-1000) || verification.exitCode}`);
+  }
+}
+function assertSignedArtifact(filePath, manifest) {
+  const artifact = manifestArtifact(manifest, basename(filePath));
+  const fileStats = statSync(filePath);
+  if (!fileStats.isFile() || fileStats.size !== artifact.size) {
+    throw new Error(`${artifact.name} does not match the signed release size`);
+  }
+  assertPrivateLocalFileMode(fileStats.mode, artifact.name);
+  const digest = sha256File(filePath);
+  if (digest !== artifact.sha256) {
+    throw new Error(`${artifact.name} does not match the signed release hashes`);
+  }
+  return digest;
+}
+function verifyDownloadedFile(filePath, manifest, checksums) {
+  const digest = assertSignedArtifact(filePath, manifest);
+  if (checksums.get(basename(filePath)) !== digest) {
+    throw new Error(`${basename(filePath)} does not match SHA256SUMS`);
+  }
+}
+async function downloadReleaseMetadata(component, version, directory) {
+  const expectedTag = releaseTag(component, version);
+  const metadataPath = join(directory, `.release-${randomUUID2()}.json`);
+  try {
+    await downloadDirect(`${RELEASES_API}/tags/${expectedTag}`, metadataPath, RELEASE_BUNDLE_SIZE_LIMITS.manifest);
+    return parseGithubReleaseMetadata(parseJsonFile(metadataPath, "GitHub release metadata"), expectedTag);
+  } finally {
+    rmSync(metadataPath, { force: true });
+  }
+}
+async function downloadManifestAttestation(manifestPath, destination) {
+  const responsePath = `${destination}.response`;
+  try {
+    await downloadDirect(`${ATTESTATIONS_API}/sha256:${sha256File(manifestPath)}`, responsePath, RELEASE_BUNDLE_SIZE_LIMITS.attestation);
+    const bundles = serializeAttestationBundles(parseJsonFile(responsePath, "GitHub attestation response"));
+    writeFileSync(destination, bundles, { mode: 384, flag: "wx" });
+    chmodSync(destination, 384);
+  } finally {
+    rmSync(responsePath, { force: true });
+  }
+}
+async function downloadComponent(request) {
+  const release = await downloadReleaseMetadata(request.component, request.version, request.destination);
+  const manifestPath = directChildPath(request.destination, RELEASE_MANIFEST_NAME);
+  const attestationPath = directChildPath(request.destination, RELEASE_ATTESTATION_NAME);
+  await downloadDirect(releaseAssetUrl(release, RELEASE_MANIFEST_NAME), manifestPath, RELEASE_BUNDLE_SIZE_LIMITS.manifest);
+  const manifest = parseReleaseManifest(readFileSync3(manifestPath, "utf8"), request);
+  await downloadManifestAttestation(manifestPath, attestationPath);
+  await verifyManifestAttestation(manifestPath, attestationPath, manifest);
+  const checksumsPath = directChildPath(request.destination, RELEASE_CHECKSUMS_NAME);
+  await downloadDirect(releaseAssetUrl(release, RELEASE_CHECKSUMS_NAME), checksumsPath, RELEASE_BUNDLE_SIZE_LIMITS.checksums);
+  assertSignedArtifact(checksumsPath, manifest);
+  const checksums = parseReleaseChecksums(readFileSync3(checksumsPath, "utf8"), manifest);
+  for (const assetName of request.assetNames) {
+    const assetPath = directChildPath(request.destination, assetName);
+    await downloadDirect(releaseAssetUrl(release, assetName), assetPath, releaseAssetSizeLimit(request.component, assetName));
+    verifyDownloadedFile(assetPath, manifest, checksums);
+  }
+  return [RELEASE_MANIFEST_NAME, RELEASE_ATTESTATION_NAME, RELEASE_CHECKSUMS_NAME, ...request.assetNames].map((name) => localUpgradeFile(directChildPath(request.destination, name), `bundle/${request.component}/${name}`));
+}
+async function downloadPinnedGithubCli(directory, architecture) {
+  const identity = githubCliArchiveIdentity(architecture);
+  const archivePath = directChildPath(directory, identity.archiveName);
+  const url = `https://github.com/cli/cli/releases/download/v${identity.version}/${identity.archiveName}`;
+  await downloadDirect(url, archivePath, MAX_GH_ARCHIVE_BYTES);
+  if (sha256File(archivePath) !== identity.sha256) {
+    throw new Error("Pinned GitHub CLI archive SHA256 mismatch");
+  }
+  return localUpgradeFile(archivePath, `verifier/${identity.archiveName}`);
+}
+function cleanupLocalUpgradeBundle(bundle) {
+  rmSync(bundle.directory, { recursive: true, force: true });
+}
+function assertLocalUpgradeBundleSize(files) {
+  const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+  if (!Number.isSafeInteger(totalBytes) || totalBytes > RELEASE_BUNDLE_SIZE_LIMITS.total) {
+    throw new Error("Local upgrade bundle exceeds its total size limit");
+  }
+}
+async function observeDownloadFailure(download, failures) {
+  try {
+    return await download;
+  } catch (error) {
+    failures.push(error);
+    throw error;
+  }
+}
+function fulfilledDownload(settlement) {
+  if (settlement.status === "rejected")
+    throw settlement.reason;
+  return settlement.value;
+}
+async function settleLocalBundleDownloads(downloads) {
+  const failures = [];
+  const settlements = await Promise.allSettled([
+    observeDownloadFailure(downloads[0], failures),
+    observeDownloadFailure(downloads[1], failures),
+    observeDownloadFailure(downloads[2], failures)
+  ]);
+  if (failures.length > 0)
+    throw failures[0];
+  return [
+    fulfilledDownload(settlements[0]),
+    fulfilledDownload(settlements[1]),
+    fulfilledDownload(settlements[2])
+  ];
+}
+function createLocalBundleLayout(request) {
+  const directory = mkdtempSync(join(tmpdir(), "supacloud-admin-upgrade-"));
+  chmodSync(directory, 448);
+  const bundleDirectory = join(directory, "bundle");
+  const managementDirectory = join(bundleDirectory, "management-api");
+  const edgeDirectory = join(bundleDirectory, "edge-runtime");
+  const verifierDirectory = join(directory, "verifier");
+  for (const createdDirectory of [bundleDirectory, managementDirectory, edgeDirectory, verifierDirectory]) {
+    mkdirSync(createdDirectory, { recursive: true, mode: 448 });
+    chmodSync(createdDirectory, 448);
+  }
+  return {
+    directory,
+    managementDirectory,
+    edgeDirectory,
+    verifierDirectory,
+    managementBinaryName: `supacloud-linux-${request.architecture}`,
+    edgeRuntimeBinaryName: `supacloud-edge-runtime-linux-${request.architecture}`
+  };
+}
+async function downloadLocalBundle(request, layout) {
+  const { managementBinaryName, edgeRuntimeBinaryName } = layout;
+  const [managementFiles, edgeFiles, verifierArchive] = await settleLocalBundleDownloads([
+    downloadComponent({
+      component: "management-api",
+      version: request.managementVersion,
+      assetNames: [managementBinaryName, "web-console-build.tar.gz"],
+      destination: layout.managementDirectory
+    }),
+    downloadComponent({
+      component: "edge-runtime",
+      version: request.edgeRuntimeVersion,
+      assetNames: [edgeRuntimeBinaryName],
+      destination: layout.edgeDirectory
+    }),
+    request.verifierProvisioning === "bundled" ? downloadPinnedGithubCli(layout.verifierDirectory, request.architecture) : Promise.resolve(null)
+  ]);
+  const files = [...managementFiles, ...edgeFiles];
+  assertLocalUpgradeBundleSize([...files, ...verifierArchive ? [verifierArchive] : []]);
+  return { directory: layout.directory, files, verifierArchive, managementBinaryName, edgeRuntimeBinaryName };
+}
+async function prepareLocalUpgradeBundle(request) {
+  assertExactStableVersion(request.managementVersion, "version");
+  assertExactStableVersion(request.edgeRuntimeVersion, "edge_runtime_version");
+  await assertLocalGithubVerifier();
+  const layout = createLocalBundleLayout(request);
+  try {
+    return await downloadLocalBundle(request, layout);
+  } catch (error) {
+    rmSync(layout.directory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+// src/shared/releases/local-upgrade-transfer.ts
+var REMOTE_STAGE_ROOT = "/var/lib/supacloud/upgrade-staging";
+var REMOTE_RUN_ROOT = "/var/lib/supacloud/upgrade-runs";
+var REMOTE_LOG_ROOT = "/var/log/supacloud";
+var POLL_INTERVAL_MS = 2000;
+var STATE_READ_ATTEMPTS = 3;
+var REMOTE_STATE_READ_TIMEOUT_MS = 15000;
+var UPGRADE_OBSERVATION_TIMEOUT_MS = 30 * 60000;
+
+class RemoteUpgradeReconciliationError extends AggregateError {
+}
+function quoteShell2(shellText) {
+  return `'${shellText.split("'").join("'\\''")}'`;
+}
+function rootCommand(script) {
+  return [
+    'if [ "$(id -u)" -eq 0 ]; then',
+    `  /bin/bash -c ${quoteShell2(script)}`,
+    "else",
+    "  sudo -n true",
+    `  sudo -n /bin/bash -c ${quoteShell2(script)}`,
+    "fi"
+  ].join(`
+`);
+}
+function trustedInstalledGithubFunction() {
+  return [
+    "trusted_installed_gh() {",
+    "  local verifier=$1 mode",
+    `  test -f "$verifier" && test ! -L "$verifier" && test -x "$verifier" || { echo 'Installed GitHub verifier is not a regular executable file' >&2; return 1; }`,
+    `  test "$(stat -c '%u:%g' "$verifier")" = '0:0' || { echo 'Installed GitHub verifier is not owned by root:root' >&2; return 1; }`,
+    `  mode=$(stat -c '%a' "$verifier")`,
+    `  case "$mode" in [0-7]|[0-7][0-7]|[0-7][0-7][0-7]) ;; *) echo 'Installed GitHub verifier has special permission bits' >&2; return 1 ;; esac`,
+    "  (( (8#$mode & 0022) == 0 )) || { echo 'Installed GitHub verifier is group/other writable' >&2; return 1; }",
+    "}"
+  ].join(`
+`);
+}
+function remotePaths(runId) {
+  return {
+    drop: `/tmp/.supacloud-upgrade-upload-${runId}`,
+    stage: `${REMOTE_STAGE_ROOT}/${runId}`,
+    status: `${REMOTE_RUN_ROOT}/${runId}.status`,
+    log: `${REMOTE_LOG_ROOT}/upgrade-${runId}.log`,
+    unit: `supacloud-upgrade-${runId}.service`
+  };
+}
+function parseRemotePreflight(output) {
+  const architecture = output.match(/^ARCH=(amd64|arm64)$/m)?.[1];
+  const verifierProvisioning = output.match(/^VERIFIER=(installed|bundled)$/m)?.[1];
+  if (!architecture || !verifierProvisioning) {
+    throw new Error("Remote upgrade preflight did not return its architecture and verifier capability");
+  }
+  return {
+    architecture,
+    verifierProvisioning
+  };
+}
+function buildRemotePreflightScript() {
+  const capabilityFlags = STRICT_GITHUB_CAPABILITY_FLAGS.join(" ");
+  return [
+    "set -euo pipefail",
+    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    "export PATH",
+    trustedInstalledGithubFunction(),
+    "test -d /run/systemd/system || { echo 'systemd is not the active init system' >&2; exit 1; }",
+    'for tool in systemctl systemd-run sha256sum stat realpath tar file find sort awk grep timeout flock; do command -v "$tool" >/dev/null 2>&1 || { echo "Required local-upgrade tool is missing: $tool" >&2; exit 127; }; done',
+    "systemd-run --help | grep -Eq -- '(^|[[:space:]])--collect([=[:space:]]|$)' || { echo 'systemd-run --collect is required' >&2; exit 1; }",
+    "test -d /run/lock || { echo '/run/lock is unavailable' >&2; exit 1; }",
+    "test -d /var/lib/supacloud || { echo '/var/lib/supacloud is unavailable' >&2; exit 1; }",
+    "test -f /etc/supabase/management-api.env || { echo 'EDGE_RUNTIME_MODE is unavailable' >&2; exit 1; }",
+    `EDGE_MODE=$(awk -F= '$1 == "EDGE_RUNTIME_MODE" { value=$2 } END { gsub(/^[[:space:]\\"'"']+|[[:space:]\\"'"']+$/, "", value); print value }' /etc/supabase/management-api.env)`,
+    `test "$EDGE_MODE" = external || { echo 'Local component upgrade requires persisted external Edge Runtime mode' >&2; exit 1; }`,
+    `case "$(uname -m)" in x86_64|amd64) echo ARCH=amd64 ;; aarch64|arm64) echo ARCH=arm64 ;; *) echo 'Unsupported remote architecture' >&2; exit 1 ;; esac`,
+    "VERIFIER=bundled",
+    "GH=$(type -P gh || true)",
+    'if [ -n "$GH" ] && trusted_installed_gh "$GH"; then',
+    '  if GH_HELP=$(timeout 15s "$GH" attestation verify --help 2>&1); then',
+    "    GH_CAPABLE=true",
+    `    for flag in ${capabilityFlags}; do printf '%s\\n' "$GH_HELP" | grep -Eq -- "(^|[[:space:]])${"$"}{flag}([=[:space:]]|$)" || GH_CAPABLE=false; done`,
+    '    if [ "$GH_CAPABLE" = true ]; then VERIFIER=installed; fi',
+    "  fi",
+    "fi",
+    "echo VERIFIER=$VERIFIER"
+  ].join(`
+`);
+}
+async function remoteUpgradePreflight(ssh) {
+  const preflight = await ssh.exec(rootCommand(buildRemotePreflightScript()), 30000);
+  if (!preflight.success)
+    throw remoteFailure("Remote local-upgrade preflight failed", preflight);
+  return parseRemotePreflight(preflight.stdout);
+}
+function requiredRemoteBytes(bundle) {
+  const transferBytes = [...bundle.files, ...bundle.verifierArchive ? [bundle.verifierArchive] : []].reduce((total, upload) => total + upload.size, 0);
+  return transferBytes * 3 + 512 * 1024 * 1024;
+}
+function buildPrepareDropCommand(paths, bundle) {
+  const directories = [
+    paths.drop,
+    `${paths.drop}/bundle`,
+    `${paths.drop}/bundle/management-api`,
+    `${paths.drop}/bundle/edge-runtime`
+  ];
+  if (bundle.verifierArchive)
+    directories.push(`${paths.drop}/verifier`);
+  const requiredBytes = requiredRemoteBytes(bundle);
+  return [
+    "set -euo pipefail",
+    "umask 077",
+    `test ! -e ${quoteShell2(paths.drop)} && test ! -L ${quoteShell2(paths.drop)} || { echo 'Remote upload drop already exists' >&2; exit 1; }`,
+    "TMP_AVAILABLE_KB=$(df -Pk /tmp | awk 'NR == 2 { print $4 }')",
+    "VAR_AVAILABLE_KB=$(df -Pk /var/lib/supacloud | awk 'NR == 2 { print $4 }')",
+    `test "${"$"}TMP_AVAILABLE_KB" -ge ${Math.ceil(requiredBytes / 1024)} && test "${"$"}VAR_AVAILABLE_KB" -ge ${Math.ceil(requiredBytes / 1024)} || { echo 'Insufficient remote disk space for verified upgrade staging' >&2; exit 1; }`,
+    `install -d -m 700 ${directories.map(quoteShell2).join(" ")}`
+  ].join(`
+`);
+}
+async function prepareRemoteDrop(ssh, paths, bundle) {
+  const prepared = await ssh.exec(buildPrepareDropCommand(paths, bundle), 30000);
+  if (!prepared.success)
+    throw remoteFailure("Unable to prepare remote upload drop", prepared);
+}
+async function uploadBundleFiles(ssh, paths, bundle) {
+  const uploads = [...bundle.files, ...bundle.verifierArchive ? [bundle.verifierArchive] : []];
+  for (const upload of uploads) {
+    await ssh.upload(upload.localPath, `${paths.drop}/${upload.relativePath}`, { mode: 384, timeoutMs: 10 * 60000 });
+  }
+}
+function expectedComponentFiles(bundle) {
+  return {
+    management: [
+      "SHA256SUMS",
+      "SUPACLOUD-RELEASE.attestation.jsonl",
+      "SUPACLOUD-RELEASE.json",
+      bundle.managementBinaryName,
+      "web-console-build.tar.gz"
+    ],
+    edge: [
+      "SHA256SUMS",
+      "SUPACLOUD-RELEASE.attestation.jsonl",
+      "SUPACLOUD-RELEASE.json",
+      bundle.edgeRuntimeBinaryName
+    ]
+  };
+}
+function shellArray(name, entries) {
+  return `${name}=(${entries.map(quoteShell2).join(" ")})`;
+}
+function finishUpgradeFunction() {
+  return [
+    "finish_upgrade() {",
+    "  local code=$?",
+    "  trap '' HUP INT TERM",
+    "  trap - EXIT",
+    "  set +e",
+    '  if [ "$code" -ne 0 ]; then',
+    '    write_status "FAILED:${code}:TRANSACTION" || true',
+    '    if ! rm -rf -- "$STAGE"; then write_status "FAILED:${code}:TRANSACTION_AND_CLEANUP" || true; fi',
+    '    exit "$code"',
+    "  fi",
+    "  write_status CLEANING || { echo 'Unable to publish cleanup state' >&2; exit 1; }",
+    '  if ! rm -rf -- "$STAGE"; then',
+    "    write_status 'FAILED:1:CLEANUP_AFTER_TRANSACTION' || true",
+    "    exit 1",
+    "  fi",
+    "  write_status SUCCEEDED || exit 1",
+    "  exit 0",
+    "}"
+  ].join(`
+`);
+}
+function upgradeScriptSetup(paths) {
+  const bundleDirectory = `${paths.stage}/bundle`;
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    "umask 077",
+    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    "export PATH",
+    `STAGE=${quoteShell2(paths.stage)}`,
+    `STATUS=${quoteShell2(paths.status)}`,
+    `LOG=${quoteShell2(paths.log)}`,
+    `BUNDLE=${quoteShell2(bundleDirectory)}`,
+    `MANAGEMENT_DIR=${quoteShell2(`${bundleDirectory}/management-api`)}`,
+    `EDGE_DIR=${quoteShell2(`${bundleDirectory}/edge-runtime`)}`,
+    `write_status() { local next="\${STATUS}.next"; printf '%s\\n' "$1" > "$next"; chmod 600 "$next"; mv -f "$next" "$STATUS"; }`,
+    finishUpgradeFunction(),
+    "trap finish_upgrade EXIT",
+    "trap 'exit 129' HUP",
+    "trap 'exit 130' INT",
+    "trap 'exit 143' TERM",
+    'exec >>"$LOG" 2>&1',
+    "write_status RUNNING",
+    buildUpgradeLockScript(SUPACLOUD_UPGRADE_LOCK_PATH),
+    `while IFS='=' read -r variable _; do case "$variable" in *PROXY*|*Proxy*|*proxy*) unset "$variable" ;; esac; done < <(env)`,
+    "unset SUPACLOUD_ALLOW_UNVERIFIED_RELEASE SUPACLOUD_GITHUB_REPOSITORY SUPACLOUD_RELEASES_API SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW NODE_USE_ENV_PROXY"
+  ];
+}
+function upgradeScriptFilesystemChecks(bundle) {
+  const componentFiles = expectedComponentFiles(bundle);
+  const stageEntries = ["bundle", "run.sh", ...bundle.verifierArchive ? ["verifier"] : []];
+  const checks = [
+    shellArray("MANAGEMENT_FILES", componentFiles.management),
+    shellArray("EDGE_FILES", componentFiles.edge),
+    `assert_directory() { local path=$1; test -d "$path" && test ! -L "$path"; test "$(stat -c '%u:%g' "$path")" = '0:0'; test "$(stat -c '%a' "$path")" = '700'; }`,
+    `assert_file() { local path=$1 parent=$2; test -f "$path" && test ! -L "$path"; test "$(stat -c '%u:%g:%h' "$path")" = '0:0:1'; test "$(stat -c '%a' "$path")" = '600'; test "$(dirname "$(realpath "$path")")" = "$parent"; }`,
+    `assert_entries() { local directory=$1; shift; local actual expected; actual=$(find "$directory" -mindepth 1 -maxdepth 1 -printf '%f\\n' | LC_ALL=C sort); expected=$(printf '%s\\n' "$@" | LC_ALL=C sort); test "$actual" = "$expected"; }`,
+    'assert_directory "$STAGE"',
+    shellArray("STAGE_FILES", stageEntries),
+    'assert_entries "$STAGE" "${STAGE_FILES[@]}"',
+    'assert_file "$STAGE/run.sh" "$STAGE"',
+    'assert_directory "$BUNDLE"',
+    'assert_entries "$BUNDLE" edge-runtime management-api',
+    'assert_directory "$MANAGEMENT_DIR"',
+    'assert_directory "$EDGE_DIR"',
+    'assert_entries "$MANAGEMENT_DIR" "${MANAGEMENT_FILES[@]}"',
+    'assert_entries "$EDGE_DIR" "${EDGE_FILES[@]}"',
+    'for name in "${MANAGEMENT_FILES[@]}"; do assert_file "$MANAGEMENT_DIR/$name" "$MANAGEMENT_DIR"; done',
+    'for name in "${EDGE_FILES[@]}"; do assert_file "$EDGE_DIR/$name" "$EDGE_DIR"; done'
+  ];
+  if (bundle.verifierArchive) {
+    const archiveName = basename2(bundle.verifierArchive.relativePath);
+    checks.push('assert_directory "$STAGE/verifier"', `assert_entries "$STAGE/verifier" ${quoteShell2(archiveName)}`, `assert_file "$STAGE/verifier/${archiveName}" "$STAGE/verifier"`);
+  }
+  return checks;
+}
+function upgradeScriptTransferVerification(bundle) {
+  const files = [...bundle.files, ...bundle.verifierArchive ? [bundle.verifierArchive] : []];
+  return [
+    `verify_transfer() { local relative=$1 expected_size=$2 expected_sha=$3; local path=$STAGE/$relative; test "$(stat -c '%s' "$path")" = "$expected_size"; test "$(sha256sum "$path" | awk '{print $1}')" = "$expected_sha"; }`,
+    ...files.map((file) => `verify_transfer ${quoteShell2(file.relativePath)} ${file.size} ${quoteShell2(file.sha256)}`)
+  ];
+}
+function upgradeScriptVerifier(paths, bundle, architecture) {
+  const setup = bundle.verifierArchive ? bundledVerifierSetup(paths, architecture) : [
+    trustedInstalledGithubFunction(),
+    "GH=$(type -P gh)",
+    `trusted_installed_gh "$GH" || { echo 'Installed GitHub verifier trust check failed' >&2; exit 1; }`
+  ];
+  const capabilityFlags = STRICT_GITHUB_CAPABILITY_FLAGS.join(" ");
+  return [
+    ...setup,
+    `GH_HELP=$(timeout 15s "$GH" attestation verify --help 2>&1) || { echo 'GitHub verifier capability check failed' >&2; exit 1; }`,
+    `for flag in ${capabilityFlags}; do printf '%s\\n' "$GH_HELP" | grep -Eq -- "(^|[[:space:]])${"$"}{flag}([=[:space:]]|$)" || { echo "GitHub verifier lacks $flag" >&2; exit 1; }; done`,
+    'VERIFIER_PATH=$(dirname "$GH")'
+  ];
+}
+function bundledVerifierSetup(paths, architecture) {
+  const verifier = githubCliArchiveIdentity(architecture);
+  return [
+    `GH_ARCHIVE=${quoteShell2(`${paths.stage}/verifier/${verifier.archiveName}`)}`,
+    `GH_MEMBER=${quoteShell2(verifier.member)}`,
+    'test "$(tar -tzf "$GH_ARCHIVE" | grep -Fxc "$GH_MEMBER")" = 1',
+    `test "$(tar -tvzf "$GH_ARCHIVE" "$GH_MEMBER" | cut -c1)" = '-'`,
+    'VERIFIER_ROOT=$(mktemp -d "${STAGE}/verifier/gh.XXXXXX")',
+    'tar --no-same-owner --same-permissions -xzf "$GH_ARCHIVE" -C "$VERIFIER_ROOT" "$GH_MEMBER"',
+    `test "$(stat -c '%a' "$VERIFIER_ROOT/$GH_MEMBER")" = '755'`,
+    'install -m 0755 "$VERIFIER_ROOT/$GH_MEMBER" "${STAGE}/verifier/gh"',
+    'rm -rf -- "$VERIFIER_ROOT"',
+    "GH=${STAGE}/verifier/gh",
+    `case "$("$GH" --version | head -1)" in 'gh version ${verifier.version}'*) ;; *) echo 'Pinned GitHub verifier version mismatch' >&2; exit 1 ;; esac`
+  ];
+}
+function upgradeScriptExecution(paths, bundle, request) {
+  const runnerAsset = `${paths.stage}/bundle/management-api/${bundle.managementBinaryName}`;
+  const runner = `${paths.stage}/runner`;
+  return [
+    `MANAGEMENT_VERSION=${quoteShell2(request.managementVersion)}`,
+    `RUNNER_ASSET=${quoteShell2(runnerAsset)}`,
+    `RUNNER=${quoteShell2(runner)}`,
+    'file -b "$RUNNER_ASSET" | grep -q ELF',
+    'install -m 0755 "$RUNNER_ASSET" "$RUNNER"',
+    `test "$(sha256sum "$RUNNER"|awk '{print $1}')" = "$(sha256sum "$RUNNER_ASSET"|awk '{print $1}')"`,
+    '"$RUNNER" --version | grep -Eq "(^|[^0-9])${MANAGEMENT_VERSION//./\\.}([^0-9]|$)"',
+    `env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" upgrade --yes --target-version ${quoteShell2(request.managementVersion)} --edge-runtime-version ${quoteShell2(request.edgeRuntimeVersion)} --asset-bundle-dir "$BUNDLE"`
+  ];
+}
+function buildLocalUpgradeRunScript(paths, bundle, request, architecture) {
+  return [
+    ...upgradeScriptSetup(paths),
+    ...upgradeScriptFilesystemChecks(bundle),
+    ...upgradeScriptTransferVerification(bundle),
+    ...upgradeScriptVerifier(paths, bundle, architecture),
+    ...upgradeScriptExecution(paths, bundle, request)
+  ].join(`
+`);
+}
+async function uploadRunScript(ssh, paths, bundle, request, architecture) {
+  await ssh.uploadText(`${paths.drop}/run.sh`, buildLocalUpgradeRunScript(paths, bundle, request, architecture), 384);
+}
+function failedAdoptionRollbackFunction() {
+  return [
+    "rollback_failed_adoption() {",
+    "  local code=$? cleanup_failed=false",
+    "  trap '' HUP INT TERM",
+    "  trap - EXIT",
+    '  if [ "$ADOPTION_ACTIVE" != true ]; then exit "$code"; fi',
+    "  set +e",
+    '  rm -rf -- "$STAGE" || cleanup_failed=true',
+    '  rm -f -- "$STATUS" "${STATUS}.next" "$LOG" || cleanup_failed=true',
+    '  if [ "$cleanup_failed" = true ]; then echo "Upgrade adoption failed (exit $code) and rollback did not complete" >&2; exit 1; fi',
+    '  echo "Upgrade adoption failed (exit $code); transferred state was rolled back" >&2',
+    '  exit "$code"',
+    "}"
+  ].join(`
+`);
+}
+function buildAdoptDropScript(paths) {
+  return [
+    "set -euo pipefail",
+    "umask 077",
+    `DROP=${quoteShell2(paths.drop)}`,
+    `STAGE=${quoteShell2(paths.stage)}`,
+    `STATUS=${quoteShell2(paths.status)}`,
+    `LOG=${quoteShell2(paths.log)}`,
+    `UNIT=${quoteShell2(paths.unit)}`,
+    "ADOPTION_ACTIVE=false",
+    failedAdoptionRollbackFunction(),
+    "trap rollback_failed_adoption EXIT",
+    "trap 'exit 129' HUP",
+    "trap 'exit 130' INT",
+    "trap 'exit 143' TERM",
+    `install -d -o root -g root -m 700 ${quoteShell2(REMOTE_STAGE_ROOT)} ${quoteShell2(REMOTE_RUN_ROOT)} ${quoteShell2(REMOTE_LOG_ROOT)}`,
+    'if [ -e "$STAGE" ] || [ -L "$STAGE" ] || [ -e "$STATUS" ] || [ -L "$STATUS" ] || [ -e "$LOG" ] || [ -L "$LOG" ]; then',
+    "  echo 'Upgrade adoption target already exists' >&2",
+    "  exit 1",
+    "fi",
+    `systemctl status "$UNIT" >/dev/null 2>&1 && { echo 'Upgrade unit already exists' >&2; exit 1; } || true`,
+    "ADOPTION_ACTIVE=true",
+    'mv "$DROP" "$STAGE"',
+    'chown -hR root:root "$STAGE"',
+    ': > "$STATUS"; : > "$LOG"; chmod 600 "$STATUS" "$LOG"',
+    'printf \'PREPARED\\n\' > "${STATUS}.next"; chmod 600 "${STATUS}.next"; mv -f "${STATUS}.next" "$STATUS"',
+    "ADOPTION_ACTIVE=false",
+    "trap - EXIT HUP INT TERM"
+  ].join(`
+`);
+}
+async function adoptRemoteDrop(ssh, paths) {
+  let adoptionFailure;
+  let adoptionOutcomeUncertain = false;
+  try {
+    const adopted = await ssh.exec(rootCommand(buildAdoptDropScript(paths)), 60000);
+    if (adopted.success)
+      return;
+    adoptionFailure = remoteFailure("Unable to adopt the verified upgrade bundle", adopted);
+  } catch (error) {
+    adoptionOutcomeUncertain = true;
+    adoptionFailure = operationError(error, "Unable to adopt the verified upgrade bundle");
+  }
+  const state = await observeRemoteState(ssh, paths, {
+    failureMessage: "Unable to reconcile the interrupted upgrade adoption",
+    precedingFailures: [adoptionFailure]
+  });
+  if (isFullyPreparedUnstartedState(state))
+    return;
+  if (adoptionOutcomeUncertain) {
+    throw remoteReconciliationFailure("Upgrade adoption outcome is still uncertain after SSH interruption", [adoptionFailure], paths);
+  }
+  const noAdoptedStateRemains = !state.stageExists && !state.statusExists && !state.logExists && !state.unitExists;
+  if (noAdoptedStateRemains)
+    throw adoptionFailure;
+  throw remoteReconciliationFailure("Upgrade adoption stopped in an ambiguous state", [adoptionFailure], paths);
+}
+function startUnitScript(paths) {
+  return [
+    "set -euo pipefail",
+    `systemd-run --quiet --collect --unit=${quoteShell2(paths.unit)} --property=Type=exec --property=KillMode=control-group --property=TimeoutStopSec=30s /bin/bash ${quoteShell2(`${paths.stage}/run.sh`)}`,
+    `systemctl is-active --quiet ${quoteShell2(paths.unit)}`
+  ].join(`
+`);
+}
+async function startRemoteUpgrade(ssh, paths) {
+  let startFailure;
+  let startOutcomeUncertain = false;
+  try {
+    const started = await ssh.exec(rootCommand(startUnitScript(paths)), 30000);
+    if (started.success)
+      return;
+    startFailure = remoteFailure("Unable to start the transient upgrade unit", started);
+  } catch (error) {
+    startOutcomeUncertain = true;
+    startFailure = operationError(error, "Unable to start the transient upgrade unit");
+  }
+  const state = await observeRemoteState(ssh, paths, {
+    failureMessage: "Unable to reconcile the interrupted upgrade start",
+    precedingFailures: [startFailure]
+  });
+  if (unitIsRunning(state.serviceState) || /^(?:RUNNING|CLEANING|SUCCEEDED|FAILED:)/.test(state.status))
+    return;
+  if (startOutcomeUncertain) {
+    throw remoteReconciliationFailure("Upgrade start outcome is still uncertain after SSH interruption", [startFailure], paths);
+  }
+  if (!isFullyPreparedUnstartedState(state)) {
+    throw remoteReconciliationFailure("Upgrade start stopped in an ambiguous state", [startFailure], paths);
+  }
+  try {
+    await cleanupUnstartedUpgrade(ssh, paths);
+  } catch (cleanupError) {
+    throw remoteReconciliationFailure("Remote upgrade start and cleanup both failed", [startFailure, cleanupError], paths);
+  }
+  throw startFailure;
+}
+function buildRemoteStateScript(paths) {
+  return [
+    "set -euo pipefail",
+    `DROP=${quoteShell2(paths.drop)}`,
+    `LOG=${quoteShell2(paths.log)}`,
+    `STAGE=${quoteShell2(paths.stage)}`,
+    `STATUS=${quoteShell2(paths.status)}`,
+    `UNIT=${quoteShell2(paths.unit)}`,
+    `printf 'STATUS=%s\\n' "$(sed -n '1p' "$STATUS" 2>/dev/null || true)"`,
+    `printf 'UNIT=%s\\n' "$(systemctl is-active "$UNIT" 2>/dev/null || true)"`,
+    'if [ -e "$STAGE" ] || [ -L "$STAGE" ]; then echo STAGE_EXISTS=yes; else echo STAGE_EXISTS=no; fi',
+    'if [ -d "$STAGE" ] && [ ! -L "$STAGE" ]; then echo STAGE_DIRECTORY=yes; else echo STAGE_DIRECTORY=no; fi',
+    'if [ -e "$DROP" ] || [ -L "$DROP" ]; then echo DROP_EXISTS=yes; else echo DROP_EXISTS=no; fi',
+    'if [ -e "$STATUS" ] || [ -L "$STATUS" ]; then echo STATUS_EXISTS=yes; else echo STATUS_EXISTS=no; fi',
+    'if [ -e "$LOG" ] || [ -L "$LOG" ]; then echo LOG_EXISTS=yes; else echo LOG_EXISTS=no; fi',
+    'UNIT_LOAD_STATE=$(systemctl show --property=LoadState --value "$UNIT" 2>/dev/null || true)',
+    `test -n "$UNIT_LOAD_STATE" || { echo 'Unable to read remote upgrade unit load state' >&2; exit 1; }`,
+    `printf 'UNIT_LOAD=%s\\n' "$UNIT_LOAD_STATE"`,
+    'if [ -n "$UNIT_LOAD_STATE" ] && [ "$UNIT_LOAD_STATE" != not-found ]; then echo UNIT_EXISTS=yes; else echo UNIT_EXISTS=no; fi'
+  ].join(`
+`);
+}
+function remoteStateValue(output, field) {
+  const match = output.match(new RegExp(`^${field}=(.*)$`, "m"));
+  if (!match)
+    throw new Error(`Remote upgrade state is missing ${field}`);
+  return match[1]?.trim() || "";
+}
+function remoteStatePresence(output, field) {
+  const presence = remoteStateValue(output, field);
+  if (presence !== "yes" && presence !== "no") {
+    throw new Error(`Remote upgrade state has invalid ${field}`);
+  }
+  return presence === "yes";
+}
+async function readRemoteState(ssh, paths, timeoutMs = REMOTE_STATE_READ_TIMEOUT_MS) {
+  const state = await ssh.exec(rootCommand(buildRemoteStateScript(paths)), timeoutMs);
+  if (!state.success)
+    throw remoteFailure("Unable to read remote upgrade state", state);
+  return {
+    dropExists: remoteStatePresence(state.stdout, "DROP_EXISTS"),
+    logExists: remoteStatePresence(state.stdout, "LOG_EXISTS"),
+    serviceState: remoteStateValue(state.stdout, "UNIT") || "unknown",
+    stageExists: remoteStatePresence(state.stdout, "STAGE_EXISTS"),
+    stageIsDirectory: remoteStatePresence(state.stdout, "STAGE_DIRECTORY"),
+    status: remoteStateValue(state.stdout, "STATUS"),
+    statusExists: remoteStatePresence(state.stdout, "STATUS_EXISTS"),
+    unitExists: remoteStatePresence(state.stdout, "UNIT_EXISTS"),
+    unitLoadState: remoteStateValue(state.stdout, "UNIT_LOAD")
+  };
+}
+function observationDeadlineFailure(paths, failures) {
+  return remoteReconciliationFailure("Remote upgrade is still nonterminal after the observation deadline", failures, paths);
+}
+async function observeRemoteState(ssh, paths, observation) {
+  const readFailures = [];
+  for (let attempt = 1;attempt <= STATE_READ_ATTEMPTS; attempt += 1) {
+    const remainingMs = observation.deadline === undefined ? REMOTE_STATE_READ_TIMEOUT_MS : observation.deadline - Date.now();
+    if (remainingMs <= 0) {
+      throw observationDeadlineFailure(paths, readFailures);
+    }
+    try {
+      return await readRemoteState(ssh, paths, Math.min(REMOTE_STATE_READ_TIMEOUT_MS, remainingMs));
+    } catch (error) {
+      readFailures.push(error);
+      if (attempt < STATE_READ_ATTEMPTS) {
+        const retryDelay = observation.deadline === undefined ? POLL_INTERVAL_MS : Math.min(POLL_INTERVAL_MS, observation.deadline - Date.now());
+        if (retryDelay <= 0)
+          throw observationDeadlineFailure(paths, readFailures);
+        await delay(retryDelay);
+      }
+    }
+  }
+  throw remoteReconciliationFailure(observation.failureMessage, [...observation.precedingFailures ?? [], ...readFailures], paths);
+}
+async function remoteLogTail(ssh, paths) {
+  const script = [
+    `LOG=${quoteShell2(paths.log)}`,
+    `test -f "$LOG" && test ! -L "$LOG" || { echo 'Remote upgrade log is not a regular file' >&2; exit 1; }`,
+    'tail -80 -- "$LOG"'
+  ].join(`
+`);
+  const output = await ssh.exec(rootCommand(script), 15000);
+  if (!output.success)
+    throw remoteFailure("Unable to read the remote upgrade log", output);
+  return output.stdout.slice(-4000);
+}
+async function cleanupRemoteRecords(ssh, paths) {
+  const cleanup = await ssh.exec(rootCommand(`rm -f -- ${quoteShell2(paths.status)} ${quoteShell2(paths.log)}`), 15000);
+  if (!cleanup.success)
+    throw remoteFailure("Unable to remove remote upgrade status records", cleanup);
+}
+function buildCleanupUnstartedUpgradeScript(paths) {
+  return [
+    "set -euo pipefail",
+    "cleanup_failed=false",
+    `rm -rf -- ${quoteShell2(paths.stage)} || cleanup_failed=true`,
+    `rm -f -- ${quoteShell2(paths.status)} ${quoteShell2(paths.log)} || cleanup_failed=true`,
+    'test "$cleanup_failed" = false'
+  ].join(`
+`);
+}
+async function cleanupUnstartedUpgrade(ssh, paths) {
+  const cleanup = await ssh.exec(rootCommand(buildCleanupUnstartedUpgradeScript(paths)), 15000);
+  if (!cleanup.success)
+    throw remoteFailure("Unable to clean an unstarted local upgrade", cleanup);
+}
+async function cleanupRemoteDrop(ssh, paths) {
+  const cleanup = await ssh.exec(`rm -rf -- ${quoteShell2(paths.drop)}`, 15000);
+  if (!cleanup.success)
+    throw remoteFailure("Unable to remove remote upload drop", cleanup);
+}
+function remoteFailure(message, execution) {
+  const diagnostic = execution.stderr.trim() || execution.stdout.trim() || `exit ${execution.code}`;
+  return new Error(`${message}: ${diagnostic.slice(-500)}`);
+}
+function operationError(error, message) {
+  return error instanceof Error ? error : new Error(`${message}: ${String(error)}`);
+}
+function remoteEvidence(paths) {
+  return `unit=${paths.unit} stage=${paths.stage} status=${paths.status} log=${paths.log} drop=${paths.drop}`;
+}
+function remoteReconciliationFailure(message, failures, paths) {
+  return new RemoteUpgradeReconciliationError(failures.map((failure) => operationError(failure, message)), `${message}; reconcile remote evidence at ${remoteEvidence(paths)}; do not retry blindly`);
+}
+function failureRequiresRemoteReconciliation(error) {
+  return error instanceof RemoteUpgradeReconciliationError;
+}
+function delay(milliseconds) {
+  return new Promise((resolve2) => setTimeout(resolve2, milliseconds));
+}
+function unitIsRunning(serviceState) {
+  return ["active", "activating", "deactivating", "reloading"].includes(serviceState);
+}
+function isFullyPreparedUnstartedState(state) {
+  return state.stageExists && state.stageIsDirectory && state.statusExists && state.logExists && !state.dropExists && !state.unitExists && state.unitLoadState === "not-found" && state.status === "PREPARED";
+}
+function unitStoppedNormally(state) {
+  return state.serviceState === "inactive" && ["loaded", "not-found"].includes(state.unitLoadState) || state.serviceState === "unknown" && state.unitLoadState === "not-found";
+}
+function assertSuccessfulUnitStoppedNormally(state, paths) {
+  if (unitStoppedNormally(state))
+    return;
+  throw remoteReconciliationFailure(`Remote upgrade published SUCCEEDED but the unit stopped abnormally or ambiguously ` + `(state=${state.serviceState} load=${state.unitLoadState})`, [], paths);
+}
+function failedUnitReachedTerminalState(state) {
+  return unitStoppedNormally(state) || state.serviceState === "failed" && state.unitLoadState === "loaded";
+}
+function assertFailedUnitReachedTerminalState(state, paths) {
+  if (failedUnitReachedTerminalState(state))
+    return;
+  throw remoteReconciliationFailure(`Remote upgrade published FAILED but the unit state is ambiguous ` + `(state=${state.serviceState} load=${state.unitLoadState})`, [], paths);
+}
+function assertTerminalEvidence(state, paths) {
+  if (state.status !== "SUCCEEDED" && !state.status.startsWith("FAILED:"))
+    return;
+  const evidenceIssues = [];
+  if (!state.statusExists)
+    evidenceIssues.push("status record is missing");
+  if (!state.logExists)
+    evidenceIssues.push("log is missing");
+  if (state.dropExists)
+    evidenceIssues.push("upload drop still exists");
+  if (state.status === "SUCCEEDED" && state.stageExists)
+    evidenceIssues.push("successful stage still exists");
+  if (state.status.startsWith("FAILED:") && !state.status.includes("CLEANUP") && state.stageExists) {
+    evidenceIssues.push("failed stage still exists without a cleanup failure status");
+  }
+  if (evidenceIssues.length === 0)
+    return;
+  throw remoteReconciliationFailure(`Remote upgrade terminal evidence is incomplete or inconsistent (${evidenceIssues.join(", ")})`, [], paths);
+}
+async function completedUpgradeOutput(ssh, paths) {
+  let log;
+  try {
+    log = await remoteLogTail(ssh, paths);
+  } catch (error) {
+    throw remoteReconciliationFailure("Upgrade succeeded but its retained log could not be read", [error], paths);
+  }
+  try {
+    await cleanupRemoteRecords(ssh, paths);
+  } catch (error) {
+    throw remoteReconciliationFailure("Upgrade succeeded but remote evidence cleanup could not be confirmed", [error], paths);
+  }
+  return `✅ Upgrade done
+${log.slice(-1500)}`;
+}
+async function throwRemoteUpgradeFailure(ssh, paths, status) {
+  let log;
+  try {
+    log = await remoteLogTail(ssh, paths);
+  } catch (error) {
+    throw remoteReconciliationFailure("Remote upgrade failed but its retained log could not be read", [error], paths);
+  }
+  const failure = new Error(`Remote local upgrade failed (${status}): ${log.slice(-1500)}`);
+  if (status.endsWith(":CLEANUP_AFTER_TRANSACTION")) {
+    throw remoteReconciliationFailure("Upgrade transaction completed but staging cleanup is incomplete", [failure], paths);
+  }
+  if (status.includes("CLEANUP")) {
+    throw remoteReconciliationFailure("Upgrade transaction and staging cleanup both failed", [failure], paths);
+  }
+  try {
+    await cleanupRemoteRecords(ssh, paths);
+  } catch (cleanupError) {
+    throw remoteReconciliationFailure("Remote local upgrade failed and status cleanup did not complete", [failure, cleanupError], paths);
+  }
+  throw failure;
+}
+function assertObservableUpgradeState(state, unitRunning, paths) {
+  const knownStatus = ["PREPARED", "RUNNING", "CLEANING", "SUCCEEDED"].includes(state.status) || state.status.startsWith("FAILED:");
+  if (!unitRunning && !knownStatus) {
+    throw remoteReconciliationFailure("Remote upgrade stopped without a terminal status", [], paths);
+  }
+}
+async function awaitRemoteUpgrade(ssh, paths) {
+  const observationDeadline = Date.now() + UPGRADE_OBSERVATION_TIMEOUT_MS;
+  let stoppedObservations = 0;
+  while (true) {
+    const state = await observeRemoteState(ssh, paths, {
+      deadline: observationDeadline,
+      failureMessage: "Unable to observe the remote upgrade lifecycle"
+    });
+    const unitRunning = unitIsRunning(state.serviceState);
+    if (!unitRunning)
+      assertTerminalEvidence(state, paths);
+    if (state.status === "SUCCEEDED" && !unitRunning) {
+      assertSuccessfulUnitStoppedNormally(state, paths);
+      return await completedUpgradeOutput(ssh, paths);
+    }
+    if (state.status.startsWith("FAILED:") && !unitRunning) {
+      assertFailedUnitReachedTerminalState(state, paths);
+      await throwRemoteUpgradeFailure(ssh, paths, state.status);
+    }
+    if (Date.now() >= observationDeadline) {
+      throw observationDeadlineFailure(paths, []);
+    }
+    assertObservableUpgradeState(state, unitRunning, paths);
+    stoppedObservations = unitRunning ? 0 : stoppedObservations + 1;
+    if (stoppedObservations >= 3 && ["PREPARED", "RUNNING", "CLEANING"].includes(state.status)) {
+      throw remoteReconciliationFailure("Remote upgrade unit stopped before publishing a terminal status", [], paths);
+    }
+    const remainingObservationMs = observationDeadline - Date.now();
+    if (remainingObservationMs <= 0)
+      throw observationDeadlineFailure(paths, []);
+    await delay(Math.min(POLL_INTERVAL_MS, remainingObservationMs));
+  }
+}
+async function executeLocalUpgradeTransfer(ssh, request) {
+  const runId = randomUUID3();
+  const paths = remotePaths(runId);
+  const preflight = await remoteUpgradePreflight(ssh);
+  const bundle = await prepareLocalUpgradeBundle({ ...preflight, ...request });
+  let adopted = false;
+  let transferError;
+  try {
+    try {
+      await prepareRemoteDrop(ssh, paths, bundle);
+      await uploadBundleFiles(ssh, paths, bundle);
+      await uploadRunScript(ssh, paths, bundle, request, preflight.architecture);
+      await adoptRemoteDrop(ssh, paths);
+      adopted = true;
+      await startRemoteUpgrade(ssh, paths);
+      return await awaitRemoteUpgrade(ssh, paths);
+    } catch (error) {
+      transferError = error;
+      if (!adopted && !failureRequiresRemoteReconciliation(error)) {
+        try {
+          await cleanupRemoteDrop(ssh, paths);
+        } catch (cleanupError) {
+          transferError = new AggregateError([transferError, cleanupError], "Local upgrade failed and upload-drop cleanup did not complete");
+        }
+      }
+      throw transferError;
+    }
+  } finally {
+    try {
+      cleanupLocalUpgradeBundle(bundle);
+    } catch (cleanupError) {
+      if (transferError) {
+        throw new AggregateError([transferError, cleanupError], "Local upgrade and local bundle cleanup both failed");
+      }
+      throw new AggregateError([cleanupError], "Remote local upgrade completed but local bundle cleanup did not complete");
+    }
+  }
+}
 
 // ../../scripts/lib/release_assets.sh
 var release_assets_default = `#!/usr/bin/env bash
@@ -26032,7 +27494,8 @@ supacloud_verify_attestation() (
             --bundle "$bundle_file" \\
             --repo "$SUPACLOUD_GITHUB_REPOSITORY" \\
             --signer-workflow "$SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW" \\
-            --source-ref "refs/heads/main" 2>&1); then
+            --source-ref "refs/heads/main" \\
+            --deny-self-hosted-runners 2>&1); then
             echo "GitHub artifact attestation verification failed: \${verification_output}" >&2
             return 1
         fi
@@ -26059,7 +27522,8 @@ supacloud_attestation_verifier_available() {
     help=$(gh attestation verify --help 2>&1) || return 1
     grep -Eq -- '(^|[[:space:]])--bundle([=[:space:]]|$)' <<< "$help" || return 1
     grep -Eq -- '(^|[[:space:]])--signer-workflow([=[:space:]]|$)' <<< "$help" || return 1
-    grep -Eq -- '(^|[[:space:]])--source-ref([=[:space:]]|$)' <<< "$help"
+    grep -Eq -- '(^|[[:space:]])--source-ref([=[:space:]]|$)' <<< "$help" || return 1
+    grep -Eq -- '(^|[[:space:]])--deny-self-hosted-runners([=[:space:]]|$)' <<< "$help"
 }
 
 supacloud_download_release_asset() (
@@ -26178,7 +27642,7 @@ function assertSafeReleaseTag(value) {
   }
   return value;
 }
-function assertExactStableVersion(value, fieldName) {
+function assertExactStableVersion2(value, fieldName) {
   if (!/^v?\d+\.\d+\.\d+$/.test(value)) {
     throw new Error(`${fieldName} must be an exact stable semantic version`);
   }
@@ -26219,8 +27683,8 @@ function componentPreflightCommands(request) {
 }
 function signalSafeCleanupTraps(cleanupCommand) {
   return [
-    `trap '${cleanupCommand}' EXIT`,
-    `trap 'trap - EXIT HUP INT TERM; ${cleanupCommand}; exit 1' HUP INT TERM`
+    `trap ${quoteEnvValue(cleanupCommand)} EXIT`,
+    `trap ${quoteEnvValue(`trap - EXIT HUP INT TERM; ${cleanupCommand}; exit 1`)} HUP INT TERM`
   ];
 }
 function buildRootUpgradeScript(request) {
@@ -26232,8 +27696,10 @@ function buildRootUpgradeScript(request) {
     "export PATH",
     "unset SUPACLOUD_ALLOW_UNVERIFIED_RELEASE SUPACLOUD_GITHUB_REPOSITORY SUPACLOUD_RELEASES_API SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW SUPACLOUD_GH_VERSION SUPACLOUD_GH_MIN_VERSION SUPACLOUD_GH_AMD64_SHA256 SUPACLOUD_GH_ARM64_SHA256 GH_PROXY",
     request.githubProxy ? `export SUPACLOUD_GITHUB_PROXY=${quoteEnvValue(request.githubProxy)}` : "unset SUPACLOUD_GITHUB_PROXY SUPACLOUD_GITHUB_PROXIES",
-    'for tool in curl jq file sha256sum tar; do command -v "$tool" >/dev/null 2>&1 || { echo "Required upgrade tool is missing: $tool" >&2; exit 127; }; done',
+    'for tool in curl jq file sha256sum stat tar flock; do command -v "$tool" >/dev/null 2>&1 || { echo "Required upgrade tool is missing: $tool" >&2; exit 127; }; done',
+    "test -d /run/lock || { echo '/run/lock is unavailable' >&2; exit 1; }",
     "test -x /usr/local/bin/supacloud || { echo 'SupaCloud binary not found at /usr/local/bin/supacloud; run ssh install first.' >&2; exit 127; }",
+    buildUpgradeLockScript(SUPACLOUD_UPGRADE_LOCK_PATH),
     ...componentPreflightCommands(request),
     "STAGED_MANAGEMENT=''",
     ...signalSafeCleanupTraps('test -z "$STAGED_MANAGEMENT" || rm -f "$STAGED_MANAGEMENT"'),
@@ -26247,14 +27713,38 @@ function buildRootUpgradeScript(request) {
 }
 function buildOfficialUpgradeCommand(request) {
   const rootScript = buildRootUpgradeScript(request);
+  const cleanupCommand = `rm -rf -- ${quoteEnvValue(dirname(request.helperPath))}`;
   return [
     "set -e",
-    ...signalSafeCleanupTraps(`rm -f ${request.helperPath}`),
+    ...signalSafeCleanupTraps(cleanupCommand),
     'if [ "$(id -u)" -eq 0 ]; then ' + `bash -c ${quoteEnvValue(rootScript)}; ` + "else sudo -n true; " + `sudo -n bash -c ${quoteEnvValue(rootScript)}; fi`
   ].join("; ");
 }
+async function prepareRemoteUpgradeHelperDirectory(ssh, helperPath) {
+  const helperDirectory = dirname(helperPath);
+  const command = [
+    "set -e",
+    "umask 077",
+    `test ! -e ${quoteEnvValue(helperDirectory)}`,
+    `install -d -m 700 -- ${quoteEnvValue(helperDirectory)}`
+  ].join("; ");
+  const preparation = await ssh.exec(command, 30000);
+  if (!preparation.success) {
+    throw new Error(`Failed to prepare remote upgrade helper directory (exit ${preparation.code}): ${preparation.stderr.slice(-300)}`);
+  }
+}
 async function removeRemoteUpgradeHelper(ssh, helperPath) {
-  const cleanup = await ssh.exec(`rm -f ${quoteEnvValue(helperPath)}`);
+  const helperDirectory = dirname(helperPath);
+  const removeCommand = `rm -rf -- ${quoteEnvValue(helperDirectory)}`;
+  const command = [
+    'if [ "$(id -u)" -eq 0 ]; then',
+    `  ${removeCommand}`,
+    "else",
+    `  ${removeCommand} || sudo -n ${removeCommand}`,
+    "fi"
+  ].join(`
+`);
+  const cleanup = await ssh.exec(command, 30000);
   if (!cleanup.success) {
     throw new Error(`Failed to remove remote upgrade helper (exit ${cleanup.code}): ${cleanup.stderr.slice(-300)}`);
   }
@@ -26283,17 +27773,22 @@ function officialUpgradeOutcome(execution, executionError, cleanupError) {
 async function executeOfficialUpgrade(ssh, helperPath, command, timeoutMs) {
   let execution;
   let executionError;
+  let helperPrepared = false;
   try {
+    await prepareRemoteUpgradeHelperDirectory(ssh, helperPath);
+    helperPrepared = true;
     await ssh.uploadText(helperPath, release_assets_default, 384);
     execution = await ssh.exec(command, timeoutMs);
   } catch (error) {
     executionError = error;
   }
   let cleanupError;
-  try {
-    await removeRemoteUpgradeHelper(ssh, helperPath);
-  } catch (error) {
-    cleanupError = error;
+  if (helperPrepared) {
+    try {
+      await removeRemoteUpgradeHelper(ssh, helperPath);
+    } catch (error) {
+      cleanupError = error;
+    }
   }
   return officialUpgradeOutcome(execution, executionError, cleanupError);
 }
@@ -26462,6 +27957,7 @@ Actions: ping, setup, install, upgrade, diagnose, exec, troubleshoot, container_
     storage_type: optional(stringEnum(["juicefs", "minio"]), "[install] Storage backend configurable through Admin"),
     version: optional(Type.String(), "[upgrade] Specific version"),
     edge_runtime_version: optional(Type.String(), "[upgrade] Exact independent Edge Runtime version"),
+    artifact_transport: optional(stringEnum(["local", "remote"]), "[upgrade] Download verified release assets locally or on the server (default: remote)"),
     github_proxy: optional(Type.String(), "[install/upgrade] Explicit GitHub proxy prefix, or direct/none"),
     focus: optional(stringEnum(["all", "containers", "database", "network", "disk", "logs"]), "[troubleshoot] Focus area"),
     container: optional(Type.String(), "[container_logs] Container name"),
@@ -26498,7 +27994,7 @@ Actions: ping, setup, install, upgrade, diagnose, exec, troubleshoot, container_
       case "install": {
         if (!args.public_domain)
           throw new Error("'public_domain' required");
-        const installId = randomUUID();
+        const installId = randomUUID4();
         const DIR = "/opt/supacloud";
         const LOG = `/var/log/supacloud/install-${installId}.log`;
         const STATUS = `/var/log/supacloud/install-${installId}.status`;
@@ -26588,12 +28084,27 @@ ${result.stderr.slice(-500)}`;
           throw new Error("'version' is required with 'edge_runtime_version'");
         }
         if (edgeRuntimeVersion && version) {
-          assertExactStableVersion(version, "version");
-          assertExactStableVersion(edgeRuntimeVersion, "edge_runtime_version");
+          assertExactStableVersion2(version, "version");
+          assertExactStableVersion2(edgeRuntimeVersion, "edge_runtime_version");
         }
         const validatedProxy = args.github_proxy ? assertSafeGithubProxy(args.github_proxy) : undefined;
+        if (args.artifact_transport === "local") {
+          if (!version || !edgeRuntimeVersion) {
+            throw new Error("Local artifact transport requires exact 'version' and 'edge_runtime_version'");
+          }
+          assertExactStableVersion2(version, "version");
+          assertExactStableVersion2(edgeRuntimeVersion, "edge_runtime_version");
+          if (validatedProxy && !["direct", "none"].includes(validatedProxy.toLowerCase())) {
+            throw new Error("Local artifact transport only supports direct GitHub downloads");
+          }
+          text = await executeLocalUpgradeTransfer(ssh, {
+            managementVersion: version.replace(/^v/, ""),
+            edgeRuntimeVersion: edgeRuntimeVersion.replace(/^v/, "")
+          });
+          break;
+        }
         const githubProxy = validatedProxy && !["direct", "none"].includes(validatedProxy.toLowerCase()) ? validatedProxy : undefined;
-        const helperPath = `/tmp/.supacloud-release-assets-${randomUUID()}.sh`;
+        const helperPath = `/tmp/.supacloud-release-assets-${randomUUID4()}/release_assets.sh`;
         const cmd = buildOfficialUpgradeCommand({
           version,
           edgeRuntimeVersion,
@@ -27450,6 +28961,48 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
     return { content: [{ type: "text", text }] };
   });
 }
+// package.json
+var package_default = {
+  name: "@supacloud/admin",
+  version: "0.7.9",
+  description: "Platform administration CLI for SupaCloud operators",
+  type: "module",
+  main: "./dist/index.js",
+  bin: {
+    "supacloud-admin": "dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  scripts: {
+    dev: "bun run --watch src/index.ts",
+    build: "bun build src/index.ts --outdir dist --target node",
+    prepublishOnly: "bun run build",
+    typecheck: "tsc --noEmit"
+  },
+  keywords: [
+    "supacloud",
+    "admin",
+    "ssh",
+    "ops"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/zuohuadong/supacloud.git",
+    directory: "packages/admin"
+  },
+  dependencies: {
+    "@sinclair/typebox": "^0.34.52",
+    ssh2: "^1.17.0"
+  },
+  devDependencies: {
+    "@types/bun": "^1.3.14",
+    "@types/ssh2": "^1.15.5",
+    typescript: "^7.0.2"
+  }
+};
 
 // src/index.ts
 var adminProjectActionSchema = stringEnum([
@@ -27517,6 +29070,7 @@ USAGE
   supacloud-admin <module> <action> [--flags]
   supacloud-admin status
   supacloud-admin --help
+  supacloud-admin --version
 
 EXPECTED CONTEXT
 
@@ -27702,6 +29256,10 @@ async function main() {
     printHelp();
     process.exit(0);
   }
+  if (args.length === 1 && args[0] === "--version") {
+    console.log(package_default.version);
+    return;
+  }
   const cliTools = createAdminTools();
   if (args.length === 1 && cliTools[args[0]]) {
     const result = await cliTools[args[0]].callback({});