@supacloud/admin 0.15.4 → 0.16.0

package/README.md

@@ -100,6 +100,7 @@ npx @supacloud/admin status
 npx @supacloud/admin ssh ping
 npx @supacloud/admin ssh versions
 npx @supacloud/admin ssh diagnose
+npx @supacloud/admin ssh upgrade_status --transaction_id 11111111-1111-4111-8111-111111111111
 npx @supacloud/admin project create --name my-app --domain example.com \
   --env_file /secure/path/.env.project-credentials.test --environment test
 npx @supacloud/admin project list
@@ -193,6 +194,33 @@ remote transaction as failed. The CLI reports the unit, stage, status, log, and
 upload-drop paths for reconciliation. Inspect that evidence before retrying and
 do not retry blindly while the remote transaction may still be running.
 
+When observation ends after 30 minutes, or to safely reconcile a retained
+local-artifact upgrade transaction, use the read-only `ssh upgrade_status`
+command:
+
+```bash
+npx @supacloud/admin ssh upgrade_status \
+  --transaction_id 11111111-1111-4111-8111-111111111111
+```
+
+`ssh upgrade_status` is classified as a read-only command and is permitted in
+read-only mode (`SUPACLOUD_READ_ONLY=true`). It requires a strict UUID v4
+transaction ID before performing any SSH access. It never deletes status, log,
+stage, or upload-drop records, and never mutates service state. The command emits
+a strict JSON projection (`supacloud.admin.upgrade-status.v1`) containing the
+normalized transaction ID, lifecycle state (`running`, `succeeded`, or
+`failed`), raw bounded status, systemd active/load states, boolean
+evidence-presence flags, and validated structured receipts:
+- Nonterminal (`running`): no receipts or failure evidence are included.
+- Succeeded: path-free projections of the validated control-plane preflight and
+  transaction safety receipts.
+- Failed: validated failure evidence with credentials and remote paths redacted.
+
+The command fails closed for missing or inconsistent terminal evidence, stopped
+nonterminal units, malformed or missing structured receipts, redacted or
+truncated SSH output, or unknown status, without emitting raw logs, remote
+filesystem paths, secrets, bearer material, env values, or customer data.
+
 `--artifact_transport local` accepts only `--github_proxy direct` or `none` and
 clears proxy environment variables on both hosts. The server-download path
 remains available as `--artifact_transport remote`; it verifies and executes

package/dist/index.js

@@ -25000,11 +25000,10 @@ class BoundedOutputCollector {
       output = lastNewline >= 0 ? output.slice(0, lastNewline + 1) : "";
     }
     const redacted = redactSshOutput(output);
-    if (!this.truncated)
-      return redacted;
-    return `${redacted}${redacted && !redacted.endsWith(`
+    const bounded = !this.truncated ? redacted : `${redacted}${redacted && !redacted.endsWith(`
 `) ? `
 ` : ""}[TRUNCATED: output exceeded ${this.limit}-byte limit]`;
+    return { output: bounded, redacted: redacted !== output };
   }
 }
 var BLOCKED_COMMANDS = [
@@ -25025,11 +25024,73 @@ var BLOCKED_COMMANDS = [
   "chmod -R 777 /"
 ];
 function redactSshCommand(command) {
-  return command.replace(/(\b[A-Z0-9_]*(?:PASSWORD|PASS|SECRET|TOKEN|KEY|CREDENTIAL)[A-Z0-9_]*=)(?:"[^"]*"|'[^']*'|[^\s;]+)/gi, "$1[REDACTED]").replace(/(Authorization\s*[:=]\s*)(['"]?)Bearer\s+[^'"\s;]+\2/gi, "$1$2Bearer [REDACTED]$2").replace(/(\b--(?:password|token|secret|api-key)\s+)(\S+)/gi, "$1[REDACTED]").replace(/(postgres(?:ql)?:\/\/[^:\s/]+:)[^@\s]+@/gi, "$1[REDACTED]@");
+  return command.replace(/(\b[A-Z0-9_]*(?:PASSWORD|PASS|SECRET|TOKEN|KEY|CREDENTIAL)[A-Z0-9_]*=)(?:"[^"]*"|'[^']*'|[^\s;]+)/gi, "$1[REDACTED]").replace(/(Authorization\s*[:=]\s*)(['"]?)Bearer\s+[^'"\s;]+\2/gi, "$1$2Bearer [REDACTED]$2").replace(/(\b--(?:password|token|secret|api-key)\s+)(\S+)/gi, "$1[REDACTED]").replace(/(postgres(?:ql)?:\/\/[^:\s/]*:)[^@\s]+@/gi, "$1[REDACTED]@");
+}
+var SENSITIVE_STRUCTURED_FIELD = /(?:password|pass|secret|token|key|credential|db_uri|database_url|dsn)/i;
+function decodedStructuredFieldName(encodedName) {
+  let decodedName = encodedName.replace(/\\'/g, "'");
+  for (let decodingPass = 0;decodingPass < 3; decodingPass += 1) {
+    if (decodedName.length > 256)
+      return null;
+    try {
+      const nextName = JSON.parse(`"${decodedName.replace(/"/g, "\\\"")}"`);
+      if (typeof nextName !== "string" || nextName === decodedName)
+        return decodedName;
+      decodedName = nextName;
+    } catch {
+      return null;
+    }
+  }
+  return decodedName;
+}
+function containsSensitiveStructuredField(message) {
+  const normalizedQuotes = message.replace(/\\"/g, '"').replace(/\\'/g, "'");
+  const fieldPatterns = [
+    /"((?:\\.|[^"\\\r\n])*)"\s*:/g,
+    /'((?:\\.|[^'\\\r\n])*)'\s*:/g,
+    /(?:^|[{,]\s*)([A-Za-z_$\\][A-Za-z0-9_$\\{}]{0,255})\s*:/g
+  ];
+  return fieldPatterns.some((pattern) => [...normalizedQuotes.matchAll(pattern)].some((match) => {
+    const decodedName = decodedStructuredFieldName(match[1]);
+    return decodedName === null || SENSITIVE_STRUCTURED_FIELD.test(decodedName);
+  }));
+}
+function structuredSensitiveFieldsAreRedacted(message) {
+  const normalizedQuotes = message.replace(/\\"/g, '"').replace(/\\'/g, "'");
+  try {
+    const parsedDiagnostic = JSON.parse(normalizedQuotes);
+    if (!parsedDiagnostic || typeof parsedDiagnostic !== "object")
+      return false;
+    let foundSensitiveField = false;
+    const pending = [parsedDiagnostic];
+    while (pending.length > 0) {
+      const current = pending.pop();
+      if (!current || typeof current !== "object")
+        continue;
+      for (const [fieldName, fieldValue] of Object.entries(current)) {
+        if (SENSITIVE_STRUCTURED_FIELD.test(fieldName)) {
+          foundSensitiveField = true;
+          if (fieldValue !== "[REDACTED]")
+            return false;
+        } else if (fieldValue && typeof fieldValue === "object") {
+          pending.push(fieldValue);
+        }
+      }
+    }
+    return foundSensitiveField;
+  } catch {
+    return false;
+  }
 }
 function redactSshOutput(output) {
-  const redactedLines = output.replace(/^(\s*(?:export\s+)?[A-Z0-9_]*(?:PASSWORD|PASS|SECRET|TOKEN|KEY|CREDENTIAL|DB_URI|DATABASE_URL|DSN)[A-Z0-9_]*\s*=\s*).*$/gim, "$1[REDACTED]");
-  const redactedStructuredFields = redactedLines.replace(/((?:["']?(?:password|pass|secret|token|key|credential|db_uri|database_url|dsn)["']?)\s*:\s*)(?:"[^"]*"|'[^']*'|[^,}\]\r\n]+)/gi, "$1[REDACTED]");
+  const redactedEscapedFields = output.split(`
+`).map((line) => containsSensitiveStructuredField(line) && !structuredSensitiveFieldsAreRedacted(line) ? "[REDACTED: structured secret output]" : line).join(`
+`);
+  const redactedLines = redactedEscapedFields.replace(/^(\s*(?:export\s+)?[A-Z0-9_]*(?:PASSWORD|PASS|SECRET|TOKEN|KEY|CREDENTIAL|DB_URI|DATABASE_URL|DSN)[A-Z0-9_]*\s*=\s*).*$/gim, "$1[REDACTED]");
+  const redactedStructuredFields = redactedLines.replace(/((?:["']?(?:password|pass|secret|token|key|credential|db_uri|database_url|dsn)["']?)\s*:\s*)("[^"]*"|'[^']*'|[^,}\]\r\n]+)/gi, (_match, prefix, literal) => {
+    const quote = literal[0];
+    return `${prefix}${quote === '"' || quote === "'" ? `${quote}[REDACTED]${quote}` : "[REDACTED]"}`;
+  });
   return redactSshCommand(redactedStructuredFields);
 }
 function isCommandBlocked(command) {
@@ -25172,13 +25233,17 @@ class SshTransport {
                 reject(new SshCommandOutcomeUnknownError("SSH command stream closed without a terminal status; remote outcome is unknown"));
                 return;
               }
+              const finalizedStdout = stdout.finalize();
+              const finalizedStderr = stderr.finalize();
               resolve({
                 success: code === 0,
-                stdout: stdout.finalize(),
-                stderr: stderr.finalize(),
+                stdout: finalizedStdout.output,
+                stderr: finalizedStderr.output,
                 code: code ?? 128,
                 stdoutTruncated: stdout.truncated,
-                stderrTruncated: stderr.truncated
+                stderrTruncated: stderr.truncated,
+                stdoutRedacted: finalizedStdout.redacted,
+                stderrRedacted: finalizedStderr.redacted
               });
             }).on("error", () => {
               clearTimeout(timer);
@@ -25837,7 +25902,8 @@ var ACTION_POLICY = {
       "container_logs",
       "tenant_list",
       "tenant_inspect",
-      "tenant_diagnose"
+      "tenant_diagnose",
+      "upgrade_status"
     ],
     write: ["setup", "install", "upgrade", "tenant_migrate"]
   }
@@ -27317,8 +27383,10 @@ var REMOTE_LOG_ROOT = "/var/log/supacloud";
 var REMOTE_UPLOAD_ROOT = "/var/tmp";
 var REMOTE_COMMAND_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
 var CONTROL_PLANE_BACKUP_ROOT = "/var/lib/supacloud/backups/control-plane-upgrades";
+var CONTROL_PLANE_PREFLIGHT_PREFIX = "SUPACLOUD_CONTROL_PLANE_UPGRADE_PREFLIGHT=";
 var CONTROL_PLANE_SAFETY_PREFIX = "SUPACLOUD_CONTROL_PLANE_UPGRADE_SAFETY=";
-var MINIMUM_CONTROL_PLANE_SAFETY_VERSION = [0, 61, 4];
+var UPGRADE_FAILURE_PREFIX = "SUPACLOUD_UPGRADE_FAILURE=";
+var MINIMUM_CONTROL_PLANE_SAFETY_VERSION = [0, 61, 7];
 var POLL_INTERVAL_MS = 2000;
 var STATE_READ_ATTEMPTS = 3;
 var REMOTE_STATE_READ_TIMEOUT_MS = 15000;
@@ -27326,6 +27394,34 @@ var UPGRADE_OBSERVATION_TIMEOUT_MS = 30 * 60000;
 
 class RemoteUpgradeReconciliationError extends AggregateError {
 }
+var UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidTransactionId(transactionId) {
+  if (typeof transactionId !== "string" || !UUID_V4_PATTERN.test(transactionId)) {
+    throw new Error("Invalid 'transaction_id': must be a valid UUID v4");
+  }
+  return transactionId.toLowerCase();
+}
+function upgradeStatusControlPlaneEvidence(receipt) {
+  return {
+    backup_id: receipt.backup_id,
+    bytes: receipt.bytes,
+    candidate_counts: { ...receipt.candidate_counts },
+    completed_at: receipt.completed_at,
+    current_key_checkpoint_present: receipt.current_key_checkpoint_present,
+    receipt_schema: receipt.schema,
+    sha256: receipt.sha256
+  };
+}
+function redactRemotePaths(message) {
+  return message.replace(/\bhttps?:\/\/[^\s"'`,;)\]}]+/gi, "[REDACTED_URL]").replace(/\bfile:\/\/\/[^\s"'`,;)\]}]+/gi, "[REDACTED_PATH]").replace(/(^|[^A-Za-z0-9:/])\/(?!\/)[^\s"'`,;)\]}]+/g, "$1[REDACTED_PATH]");
+}
+function upgradeStatusFailureEvidence(receipt) {
+  return {
+    causes: receipt.causes.map(redactRemotePaths),
+    receipt_schema: receipt.schema,
+    summary: redactRemotePaths(receipt.summary)
+  };
+}
 function exactObjectKeys(candidate, expected) {
   const actual = Object.keys(candidate).sort();
   return actual.length === expected.length && actual.every((key, index) => key === [...expected].sort()[index]);
@@ -27342,13 +27438,13 @@ function canonicalTimestamp(candidate) {
   const timestamp = new Date(candidate);
   return Number.isFinite(timestamp.valueOf()) && timestamp.toISOString() === candidate;
 }
-function parseControlPlaneSafetyEvidence(log) {
-  const receiptLines = log.split(/\r?\n/).filter((line) => line.startsWith(CONTROL_PLANE_SAFETY_PREFIX));
+function parseControlPlaneSafetyReceipt(log, prefix) {
+  const receiptLines = log.split(/\r?\n/).filter((line) => line.startsWith(prefix));
   if (receiptLines.length !== 1)
     throw new Error("Remote upgrade did not emit one control-plane safety receipt");
   let candidate;
   try {
-    candidate = JSON.parse(receiptLines[0].slice(CONTROL_PLANE_SAFETY_PREFIX.length));
+    candidate = JSON.parse(receiptLines[0].slice(prefix.length));
   } catch {
     throw new Error("Remote control-plane safety receipt is not valid JSON");
   }
@@ -27380,6 +27476,46 @@ function parseControlPlaneSafetyEvidence(log) {
   }
   return receipt;
 }
+function parseControlPlaneSafetyEvidence(log) {
+  return parseControlPlaneSafetyReceipt(log, CONTROL_PLANE_SAFETY_PREFIX);
+}
+function parseControlPlanePreflightEvidence(log) {
+  return parseControlPlaneSafetyReceipt(log, CONTROL_PLANE_PREFLIGHT_PREFIX);
+}
+function parsedUpgradeFailureReceipt(log) {
+  const receiptLines = log.split(/\r?\n/).filter((line) => line.startsWith(UPGRADE_FAILURE_PREFIX));
+  if (receiptLines.length !== 1)
+    throw new Error("Remote upgrade did not emit one structured failure receipt");
+  let candidate;
+  try {
+    candidate = JSON.parse(receiptLines[0].slice(UPGRADE_FAILURE_PREFIX.length));
+  } catch {
+    throw new Error("Remote upgrade failure receipt is not valid JSON");
+  }
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("Remote upgrade failure receipt is invalid");
+  }
+  return candidate;
+}
+function upgradeFailureReceiptIsInvalid(receipt) {
+  const causes = receipt.causes;
+  return !exactObjectKeys(receipt, ["causes", "schema", "summary"]) || receipt.schema !== "supacloud.upgrade-failure.v1" || typeof receipt.summary !== "string" || !receipt.summary || receipt.summary.length > 500 || /[\u0000-\u001f\u007f]/.test(receipt.summary) || !Array.isArray(causes) || causes.length > 8 || causes.some((cause) => typeof cause !== "string" || !cause || cause.length > 500 || /[\u0000-\u001f\u007f]/.test(cause));
+}
+function upgradeFailureMessageContainsSensitiveData(message) {
+  const bareBearer = /\bBearer\s+(?!\[REDACTED\](?:\s|$|[,;.)]))\S+/i;
+  return redactSshOutput(message) !== message || bareBearer.test(message);
+}
+function parseUpgradeFailureEvidence(log) {
+  const receipt = parsedUpgradeFailureReceipt(log);
+  if (upgradeFailureReceiptIsInvalid(receipt)) {
+    throw new Error("Remote upgrade failure receipt is invalid");
+  }
+  const messages = [receipt.summary, ...receipt.causes];
+  if (messages.some(upgradeFailureMessageContainsSensitiveData)) {
+    throw new Error("Remote upgrade failure receipt contains sensitive data");
+  }
+  return receipt;
+}
 function assertControlPlaneSafetyVersion(version) {
   const match = version.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
   if (!match)
@@ -27392,7 +27528,7 @@ function assertControlPlaneSafetyVersion(version) {
     if (requested[index] > MINIMUM_CONTROL_PLANE_SAFETY_VERSION[index])
       return;
     if (requested[index] < MINIMUM_CONTROL_PLANE_SAFETY_VERSION[index]) {
-      throw new Error("Local artifact upgrades require Management 0.61.4 or newer with control-plane backup safety");
+      throw new Error("Local artifact upgrades require Management 0.61.7 or newer with control-plane backup preflight safety");
     }
   }
 }
@@ -27713,6 +27849,7 @@ function bundledVerifierSetup(paths, architecture) {
 function upgradeScriptExecution(paths, bundle, request) {
   const runnerAsset = `${paths.stage}/bundle/management-api/${bundle.managementBinaryName}`;
   const runner = `${paths.stage}/runner`;
+  const preflight = 'CONTROL_PLANE_PREFLIGHT_RECEIPT=$(env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" --control-plane-upgrade-preflight)';
   return [
     `MANAGEMENT_VERSION=${quoteShell2(request.managementVersion)}`,
     `RUNNER_ASSET=${quoteShell2(runnerAsset)}`,
@@ -27723,7 +27860,9 @@ function upgradeScriptExecution(paths, bundle, request) {
     '"$RUNNER" --version | grep -Eq "(^|[^0-9])${MANAGEMENT_VERSION//./\\.}([^0-9]|$)"',
     `timeout 5s "$RUNNER" --systemd-unit-helper-sha256 | grep -Eq 'SupaCloud systemd-unit helper SHA-256: [0-9a-f]{64}'`,
     `timeout 5s "$RUNNER" --postgrest-launcher-sha256 | grep -Eq 'SupaCloud PostgREST launcher SHA-256: [0-9a-f]{64}'`,
-    `env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" upgrade --yes --target-version ${quoteShell2(request.managementVersion)} --edge-runtime-version ${quoteShell2(request.edgeRuntimeVersion)} --asset-bundle-dir "$BUNDLE"`
+    preflight,
+    `env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" upgrade --yes --target-version ${quoteShell2(request.managementVersion)} --edge-runtime-version ${quoteShell2(request.edgeRuntimeVersion)} --asset-bundle-dir "$BUNDLE"`,
+    `printf '%s\\n' "$CONTROL_PLANE_PREFLIGHT_RECEIPT"`
   ];
 }
 function buildLocalUpgradeRunScript(paths, bundle, request, architecture) {
@@ -27939,6 +28078,9 @@ async function remoteLogTail(ssh, paths) {
   const output = await ssh.exec(rootCommand(script), 15000);
   if (!output.success)
     throw remoteFailure("Unable to read the remote upgrade log", output);
+  if (output.stdoutRedacted || output.stderrRedacted || output.stdoutTruncated || output.stderrTruncated) {
+    throw new Error("Remote upgrade log required transport redaction or truncation");
+  }
   return output.stdout.slice(-4000);
 }
 async function cleanupRemoteRecords(ssh, paths) {
@@ -28036,11 +28178,13 @@ async function completedUpgradeOutput(ssh, paths) {
   } catch (error) {
     throw remoteReconciliationFailure("Upgrade succeeded but its retained log could not be read", [error], paths);
   }
+  let preflightEvidence;
   let safetyEvidence;
   try {
+    preflightEvidence = parseControlPlanePreflightEvidence(log);
     safetyEvidence = parseControlPlaneSafetyEvidence(log);
   } catch (error) {
-    throw remoteReconciliationFailure("Upgrade succeeded but control-plane safety evidence is invalid", [error], paths);
+    throw remoteReconciliationFailure("Upgrade succeeded but control-plane preflight or safety evidence is invalid", [error], paths);
   }
   try {
     await cleanupRemoteRecords(ssh, paths);
@@ -28048,7 +28192,7 @@ async function completedUpgradeOutput(ssh, paths) {
     throw remoteReconciliationFailure("Upgrade succeeded but remote evidence cleanup could not be confirmed", [error], paths);
   }
   return `✅ Upgrade done
-${JSON.stringify(safetyEvidence)}
+${JSON.stringify({ preflight: preflightEvidence, transaction: safetyEvidence })}
 ${log.slice(-1500)}`;
 }
 async function throwRemoteUpgradeFailure(ssh, paths, status) {
@@ -28058,13 +28202,19 @@ async function throwRemoteUpgradeFailure(ssh, paths, status) {
   } 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);
+    throw remoteReconciliationFailure("Upgrade transaction completed but staging cleanup is incomplete", [new Error(`Remote local upgrade ended with ${status}`)], paths);
   }
   if (status.includes("CLEANUP")) {
-    throw remoteReconciliationFailure("Upgrade transaction and staging cleanup both failed", [failure], paths);
+    throw remoteReconciliationFailure("Upgrade transaction and staging cleanup both failed", [new Error(`Remote local upgrade ended with ${status}`)], paths);
+  }
+  let failureEvidence;
+  try {
+    failureEvidence = parseUpgradeFailureEvidence(log);
+  } catch (error) {
+    throw remoteReconciliationFailure("Remote upgrade failed without valid structured failure evidence", [error], paths);
   }
+  const failure = new Error(`Remote local upgrade failed (${status}): ${failureEvidence.summary}` + (failureEvidence.causes.length > 0 ? `; causes: ${failureEvidence.causes.join(" | ")}` : ""));
   try {
     await cleanupRemoteRecords(ssh, paths);
   } catch (cleanupError) {
@@ -28151,6 +28301,115 @@ async function executeLocalUpgradeTransfer(ssh, request) {
     }
   }
 }
+function upgradeStatusLifecycle(status) {
+  if (["PREPARED", "RUNNING", "CLEANING"].includes(status))
+    return "running";
+  if (status === "SUCCEEDED")
+    return "succeeded";
+  const failedStatus = status.match(/^FAILED:([1-9]\d{0,2}):(TRANSACTION|TRANSACTION_AND_CLEANUP|CLEANUP_AFTER_TRANSACTION)$/);
+  if (failedStatus && Number(failedStatus[1]) <= 255)
+    return "failed";
+  throw new Error("Remote upgrade status is unknown or invalid");
+}
+function upgradeStatusEvidence(state) {
+  return {
+    drop_exists: state.dropExists,
+    log_exists: state.logExists,
+    stage_exists: state.stageExists,
+    stage_is_directory: state.stageIsDirectory,
+    status_exists: state.statusExists,
+    unit_exists: state.unitExists
+  };
+}
+async function readUpgradeStatusState(ssh, paths) {
+  try {
+    return await readRemoteState(ssh, paths);
+  } catch {
+    throw new Error("Unable to read remote upgrade state safely");
+  }
+}
+async function readUpgradeStatusLog(ssh, paths) {
+  try {
+    return await remoteLogTail(ssh, paths);
+  } catch {
+    throw new Error("Remote upgrade retained log could not be read safely");
+  }
+}
+function assertUpgradeStatusTerminalEvidence(state, paths, lifecycle) {
+  try {
+    if (lifecycle === "succeeded")
+      assertSuccessfulUnitStoppedNormally(state, paths);
+    else
+      assertFailedUnitReachedTerminalState(state, paths);
+    assertTerminalEvidence(state, paths);
+  } catch {
+    throw new Error("Remote upgrade terminal evidence is incomplete or inconsistent");
+  }
+}
+function succeededUpgradeStatus(transactionId, state, log) {
+  let preflight;
+  let transaction;
+  try {
+    preflight = parseControlPlanePreflightEvidence(log);
+    transaction = parseControlPlaneSafetyEvidence(log);
+  } catch {
+    throw new Error("Remote upgrade safety receipts are missing or invalid");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "succeeded",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state),
+    preflight: upgradeStatusControlPlaneEvidence(preflight),
+    transaction: upgradeStatusControlPlaneEvidence(transaction)
+  };
+}
+function failedUpgradeStatus(transactionId, state, log) {
+  let failure;
+  try {
+    failure = parseUpgradeFailureEvidence(log);
+  } catch {
+    throw new Error("Remote upgrade failure receipt is missing or invalid");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "failed",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state),
+    failure: upgradeStatusFailureEvidence(failure)
+  };
+}
+function runningUpgradeStatus(transactionId, state) {
+  if (!unitIsRunning(state.serviceState) || state.unitLoadState !== "loaded" || !state.statusExists) {
+    throw new Error("Remote upgrade nonterminal state is inconsistent");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "running",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state)
+  };
+}
+async function inspectRemoteUpgradeStatus(ssh, transactionIdInput) {
+  const transactionId = assertValidTransactionId(transactionIdInput);
+  const paths = buildRemoteUpgradePaths(transactionId);
+  const state = await readUpgradeStatusState(ssh, paths);
+  const lifecycle = upgradeStatusLifecycle(state.status);
+  if (lifecycle === "running")
+    return runningUpgradeStatus(transactionId, state);
+  assertUpgradeStatusTerminalEvidence(state, paths, lifecycle);
+  const log = await readUpgradeStatusLog(ssh, paths);
+  return lifecycle === "succeeded" ? succeededUpgradeStatus(transactionId, state, log) : failedUpgradeStatus(transactionId, state, log);
+}
 
 // ../../scripts/lib/release_assets.sh
 var release_assets_default = '#!/usr/bin/env bash\n\nSUPACLOUD_GITHUB_REPOSITORY="${SUPACLOUD_GITHUB_REPOSITORY:-vibeunion/supacloud}"\nSUPACLOUD_RELEASES_API="${SUPACLOUD_RELEASES_API:-https://api.github.com/repos/${SUPACLOUD_GITHUB_REPOSITORY}/releases}"\nSUPACLOUD_ATTESTATION_SIGNER_WORKFLOW="${SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW:-${SUPACLOUD_GITHUB_REPOSITORY}/.github/workflows/release-please.yml}"\nSUPACLOUD_GH_VERSION="${SUPACLOUD_GH_VERSION:-2.96.0}"\nSUPACLOUD_GH_MIN_VERSION="${SUPACLOUD_GH_MIN_VERSION:-2.68.0}"\nSUPACLOUD_GH_AMD64_SHA256="${SUPACLOUD_GH_AMD64_SHA256:-83d5c2ccad5498f58bf6368acb1ab32588cf43ab3a4b1c301bf36328b1c8bd60}"\nSUPACLOUD_GH_ARM64_SHA256="${SUPACLOUD_GH_ARM64_SHA256:-06f86ec7103d41993b76cd78072f43595c34aaa56506d971d9860e67140bf909}"\nSUPACLOUD_RELEASE_ASSETS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\nSUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT="${SUPACLOUD_RELEASE_ASSETS_DIR}/../../packages/management-api/src/assets/sigstore-public-good-trusted-root.jsonl"\nreadonly SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256="3c2cc7f357dc064ec527fdcd78da6e9245c21a381e1abaa0f2b62b186bcac1a1"\nreadonly SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE="5748"\n\nsupacloud_curl_release_json() {\n    local url="$1"\n    local output="$2"\n    curl -fsSL --proto \'=https\' --proto-redir \'=https\' \\\n        --retry 1 --retry-delay 2 --retry-max-time 60 \\\n        --connect-timeout 15 --max-time 30 --speed-limit 128 --speed-time 10 \\\n        -o "$output" "$url"\n}\n\nsupacloud_curl_release_asset() {\n    local url="$1"\n    local output="$2"\n    curl -fL --proto \'=https\' --proto-redir \'=https\' \\\n        --retry 1 --retry-delay 2 --retry-max-time 180 \\\n        --connect-timeout 15 --max-time 90 --speed-limit 128 --speed-time 60 \\\n        -o "$output" "$url"\n}\n\nsupacloud_component_tag() {\n    local component="$1"\n    local version="$2"\n    case "$version" in\n        "${component}-v"*) printf \'%s\' "$version" ;;\n        v*) printf \'%s-%s\' "$component" "$version" ;;\n        *) printf \'%s-v%s\' "$component" "$version" ;;\n    esac\n}\n\nsupacloud_select_release() {\n    local component="$1"\n    shift\n    local required_assets_json\n    [[ $# -gt 0 ]] || {\n        echo "at least one required release asset must be specified" >&2\n        return 1\n    }\n    required_assets_json=$(printf \'%s\\n\' "$@" | jq -Rsc \'split("\\n")[:-1]\')\n    jq -ce --arg prefix "${component}-v" --argjson required "$required_assets_json" \'\n        map(select(\n            (.draft | not)\n            and (.prerelease | not)\n            and (.tag_name | startswith($prefix))\n            and (. as $release | all($required[]; . as $asset | any($release.assets[]?; .name == $asset)))\n            and any(.assets[]?; .name == "SHA256SUMS")\n        ))\n        | first\n        // error("no matching component release contains all required assets and SHA256SUMS")\n    \'\n}\n\nsupacloud_fetch_component_release() {\n    local component="$1"\n    local version="${2:-latest}"\n    shift 2\n    local required_assets=("$@")\n    local required_assets_json\n    local response\n    [[ ${#required_assets[@]} -gt 0 ]] || {\n        echo "at least one required release asset must be specified" >&2\n        return 1\n    }\n    required_assets_json=$(printf \'%s\\n\' "${required_assets[@]}" | jq -Rsc \'split("\\n")[:-1]\')\n\n    if [[ -n "$version" && "$version" != "latest" ]]; then\n        local tag\n        tag=$(supacloud_component_tag "$component" "$version")\n        response=$(supacloud_fetch_release_json "${SUPACLOUD_RELEASES_API}/tags/${tag}") || return 1\n        jq -ce --argjson required "$required_assets_json" \'\n            select(\n                (.draft | not)\n                and (.prerelease | not)\n                and (. as $release | all($required[]; . as $asset | any($release.assets[]?; .name == $asset)))\n                and any(.assets[]?; .name == "SHA256SUMS")\n            )\n            // error("release does not contain all required assets and SHA256SUMS")\n        \' <<< "$response"\n        return\n    fi\n\n    response=$(supacloud_fetch_release_json "${SUPACLOUD_RELEASES_API}?per_page=100") || return 1\n    supacloud_select_release "$component" "${required_assets[@]}" <<< "$response"\n}\n\nsupacloud_fetch_release_json() (\n    local url="$1"\n    local response_file\n    response_file=$(mktemp) || return 1\n    trap \'rm -f "$response_file"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -f "$response_file"; exit 1\' HUP INT TERM\n    supacloud_download_release_metadata_url "$url" "$response_file" || return 1\n    cat "$response_file"\n)\n\nsupacloud_release_asset_url() {\n    local release_json="$1"\n    local asset_name="$2"\n    jq -er --arg asset "$asset_name" \'\n        first(.assets[]? | select(.name == $asset) | .browser_download_url)\n        // error("release asset URL is missing")\n    \' <<< "$release_json"\n}\n\nsupacloud_download_url() {\n    local url="$1"\n    local output="$2"\n    local proxy="${SUPACLOUD_GITHUB_PROXY:-${GH_PROXY:-}}"\n\n    if supacloud_curl_release_asset "$url" "$output"; then\n        return 0\n    fi\n    if [[ -n "$proxy" ]]; then\n        supacloud_curl_release_asset "${proxy%/}/${url}" "$output"\n        return\n    fi\n    return 1\n}\n\nsupacloud_download_release_metadata_url() {\n    local url="$1"\n    local output="$2"\n    local proxy="${SUPACLOUD_GITHUB_PROXY:-${GH_PROXY:-}}"\n\n    if supacloud_curl_release_json "$url" "$output"; then\n        return 0\n    fi\n    if [[ -n "$proxy" ]]; then\n        supacloud_curl_release_json "${proxy%/}/${url}" "$output"\n        return\n    fi\n    return 1\n}\n\nsupacloud_verify_checksum() {\n    local artifact_file="$1"\n    local asset_name="$2"\n    local checksum_file="$3"\n    local expected\n    expected=$(awk -v asset="$asset_name" \'$2 == asset || $2 == "*" asset { print $1; exit }\' "$checksum_file")\n    if [[ ! "$expected" =~ ^[0-9a-fA-F]{64}$ ]]; then\n        echo "SHA256SUMS does not contain a valid checksum for ${asset_name}" >&2\n        return 1\n    fi\n\n    local actual\n    actual=$(sha256sum "$artifact_file" | awk \'{print $1}\')\n    actual=$(printf \'%s\' "$actual" | tr \'[:upper:]\' \'[:lower:]\')\n    expected=$(printf \'%s\' "$expected" | tr \'[:upper:]\' \'[:lower:]\')\n    if [[ "$actual" != "$expected" ]]; then\n        echo "SHA256 mismatch for ${asset_name}" >&2\n        return 1\n    fi\n}\n\nsupacloud_validate_binary() {\n    local artifact_file="$1"\n    local asset_name="$2"\n    local description\n    description=$(file -b "$artifact_file")\n    if [[ "$description" != *ELF* ]]; then\n        echo "${asset_name} is not an ELF binary: ${description}" >&2\n        return 1\n    fi\n\n    case "$asset_name" in\n        *amd64)\n            [[ "$description" == *x86-64* || "$description" == *x86_64* ]] || {\n                echo "${asset_name} does not contain an x86-64 ELF binary" >&2\n                return 1\n            }\n            ;;\n        *arm64)\n            [[ "$description" == *aarch64* || "$description" == *ARM64* ]] || {\n                echo "${asset_name} does not contain an arm64 ELF binary" >&2\n                return 1\n            }\n            ;;\n    esac\n}\n\nsupacloud_install_pinned_tar_xz_binary() (\n    local archive="$1"\n    local member="$2"\n    local expected_sha256="$3"\n    local arch="$4"\n    local target="$5"\n    local actual_sha256 member_count member_details extract_dir candidate staged_target\n\n    actual_sha256=$(sha256sum "$archive" | awk \'{print $1}\')\n    actual_sha256=$(printf \'%s\' "$actual_sha256" | tr \'[:upper:]\' \'[:lower:]\')\n    expected_sha256=$(printf \'%s\' "$expected_sha256" | tr \'[:upper:]\' \'[:lower:]\')\n    if [[ ! "$expected_sha256" =~ ^[0-9a-f]{64}$ || "$actual_sha256" != "$expected_sha256" ]]; then\n        echo "SHA256 mismatch for pinned archive" >&2\n        return 1\n    fi\n\n    member_count=$(tar -tJf "$archive" | grep -Fxc "$member" || true)\n    if [[ "$member_count" != "1" ]]; then\n        echo "Pinned archive must contain the exact member once: $member" >&2\n        return 1\n    fi\n    member_details=$(tar -tvJf "$archive" "$member") || return 1\n    if [[ "${member_details:0:1}" != "-" ]]; then\n        echo "Pinned archive member is not a regular file: $member" >&2\n        return 1\n    fi\n\n    extract_dir=$(mktemp -d)\n    trap \'rm -rf "$extract_dir"; [[ -z "${staged_target:-}" ]] || rm -f "$staged_target"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -rf "$extract_dir"; [[ -z "${staged_target:-}" ]] || rm -f "$staged_target"; exit 1\' HUP INT TERM\n    if ! tar --no-same-owner --no-same-permissions -xJf "$archive" -C "$extract_dir" "$member"; then\n        return 1\n    fi\n    candidate="${extract_dir}/${member}"\n    supacloud_validate_binary "$candidate" "pinned-linux-${arch}" || return 1\n\n    mkdir -p "$(dirname "$target")"\n    staged_target=$(mktemp "${target}.tmp.XXXXXX")\n    install -m 0755 "$candidate" "$staged_target"\n    mv -f "$staged_target" "$target"\n    staged_target=""\n)\n\nsupacloud_version_at_least() {\n    local current="${1#v}"\n    local required="${2#v}"\n    local current_major=0 current_minor=0 current_patch=0\n    local required_major=0 required_minor=0 required_patch=0\n    [[ "$current" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?$ ]] || return 1\n    [[ "$required" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?$ ]] || return 1\n    IFS=. read -r current_major current_minor current_patch <<EOF\n${current%%-*}\nEOF\n    IFS=. read -r required_major required_minor required_patch <<EOF\n${required%%-*}\nEOF\n    current_major=${current_major:-0}; current_minor=${current_minor:-0}; current_patch=${current_patch:-0}\n    required_major=${required_major:-0}; required_minor=${required_minor:-0}; required_patch=${required_patch:-0}\n    if (( current_major != required_major )); then (( current_major > required_major )); return; fi\n    if (( current_minor != required_minor )); then (( current_minor > required_minor )); return; fi\n    (( current_patch >= required_patch ))\n}\n\nsupacloud_gh_version() {\n    gh --version 2>/dev/null | awk \'NR == 1 && $1 == "gh" && $2 == "version" { print $3; exit }\'\n}\n\nsupacloud_install_gh_archive() {\n    local archive="$1"\n    local version="$2"\n    local arch="$3"\n    local expected_sha256="$4"\n    local target="$5"\n    local member="gh_${version}_linux_${arch}/bin/gh"\n    local actual_sha256 member_count member_details extracted_dir candidate version_output\n\n    actual_sha256=$(sha256sum "$archive" | awk \'{print $1}\')\n    if [[ "$actual_sha256" != "$expected_sha256" ]]; then\n        echo "GitHub CLI archive SHA256 mismatch" >&2\n        return 1\n    fi\n\n    member_count=$(tar -tzf "$archive" | grep -Fxc "$member" || true)\n    if [[ "$member_count" != "1" ]]; then\n        echo "GitHub CLI archive does not contain the exact expected member: $member" >&2\n        return 1\n    fi\n    member_details=$(tar -tvzf "$archive" "$member") || return 1\n    if [[ "${member_details:0:1}" != "-" ]]; then\n        echo "GitHub CLI archive member is not a regular file: $member" >&2\n        return 1\n    fi\n\n    extracted_dir=$(mktemp -d)\n    candidate="${extracted_dir}/${member}"\n    if ! tar --no-same-owner --no-same-permissions -xzf "$archive" -C "$extracted_dir" "$member" \\\n        || ! supacloud_validate_binary "$candidate" "gh-linux-${arch}"; then\n        rm -rf "$extracted_dir"\n        return 1\n    fi\n    chmod 0755 "$candidate"\n    version_output=$("$candidate" --version 2>/dev/null | head -1) || {\n        rm -rf "$extracted_dir"\n        echo "GitHub CLI bootstrap binary failed its version check" >&2\n        return 1\n    }\n    if [[ "$version_output" != "gh version ${version}"* ]]; then\n        rm -rf "$extracted_dir"\n        echo "GitHub CLI bootstrap version mismatch: ${version_output}" >&2\n        return 1\n    fi\n    mkdir -p "$(dirname "$target")"\n    install -m 0755 "$candidate" "$target"\n    rm -rf "$extracted_dir"\n}\n\nsupacloud_install_pinned_gh() {\n    local target="${1:-/usr/local/bin/gh}"\n    local machine arch expected_sha256 asset url archive\n    machine=$(uname -m)\n    case "$machine" in\n        x86_64|amd64)\n            arch="amd64"\n            expected_sha256="$SUPACLOUD_GH_AMD64_SHA256"\n            ;;\n        aarch64|arm64)\n            arch="arm64"\n            expected_sha256="$SUPACLOUD_GH_ARM64_SHA256"\n            ;;\n        *)\n            echo "Unsupported architecture for GitHub CLI bootstrap: $machine" >&2\n            return 1\n            ;;\n    esac\n    asset="gh_${SUPACLOUD_GH_VERSION}_linux_${arch}.tar.gz"\n    url="https://github.com/cli/cli/releases/download/v${SUPACLOUD_GH_VERSION}/${asset}"\n    archive=$(mktemp)\n    if ! supacloud_download_url "$url" "$archive" \\\n        || ! supacloud_install_gh_archive "$archive" "$SUPACLOUD_GH_VERSION" "$arch" "$expected_sha256" "$target"; then\n        rm -f "$archive"\n        return 1\n    fi\n    rm -f "$archive"\n}\n\nsupacloud_validate_tar() {\n    local artifact_file="$1"\n    local entries\n    entries=$(tar -tzf "$artifact_file") || {\n        echo "Web Console archive is not a readable gzip tarball" >&2\n        return 1\n    }\n    if ! printf \'%s\\n\' "$entries" | awk \'\n        /^\\// { exit 1 }\n        /(^|\\/)\\.\\.($|\\/)/ { exit 1 }\n    \'; then\n        echo "Web Console archive contains an unsafe path" >&2\n        return 1\n    fi\n    if ! tar -tvzf "$artifact_file" | awk \'substr($1, 1, 1) != "-" && substr($1, 1, 1) != "d" { exit 1 }\'; then\n        echo "Web Console archive contains links or special files" >&2\n        return 1\n    fi\n    printf \'%s\\n\' "$entries" | grep -Eq \'(^|/)index\\.html$\' || {\n        echo "Web Console archive is invalid or does not contain index.html" >&2\n        return 1\n    }\n}\n\nsupacloud_record_integrity_mode() {\n    local mode="$1"\n    local record_file="${SUPACLOUD_INTEGRITY_MODE_RECORD:-/var/lib/supacloud/artifact-integrity-mode}"\n    mkdir -p "$(dirname "$record_file")" 2>/dev/null || return 0\n    printf \'%s\\n\' "$mode" > "$record_file" 2>/dev/null || return 0\n    chmod 600 "$record_file" 2>/dev/null || true\n}\n\nsupacloud_fetch_attestation_bundle() {\n    local artifact_file="$1"\n    local bundle_file="$2"\n    local digest response\n    digest=$(sha256sum "$artifact_file" | awk \'{print $1}\') || return 1\n    [[ "$digest" =~ ^[0-9a-fA-F]{64}$ ]] || {\n        echo "Unable to calculate the artifact digest for attestation lookup" >&2\n        return 1\n    }\n    digest=$(printf \'%s\' "$digest" | tr \'[:upper:]\' \'[:lower:]\')\n    response=$(supacloud_fetch_release_json \\\n        "https://api.github.com/repos/${SUPACLOUD_GITHUB_REPOSITORY}/attestations/sha256:${digest}") || {\n        echo "Unable to download the public GitHub artifact attestation bundle" >&2\n        return 1\n    }\n    if ! jq -ce \'\n        .attestations\n        | if type != "array" or length == 0 or any(.[]; (.bundle | type) != "object")\n          then error("no valid attestation bundles returned")\n          else .[].bundle\n          end\n    \' <<< "$response" > "$bundle_file"; then\n        echo "GitHub artifact attestation response did not contain a valid bundle" >&2\n        return 1\n    fi\n}\n\nsupacloud_attestation_trusted_root_available() {\n    local trusted_root="${SUPACLOUD_ATTESTATION_TRUSTED_ROOT:-$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT}"\n    local actual_size actual_sha256\n    [[ "$trusted_root" == /* && -f "$trusted_root" && ! -L "$trusted_root" ]] || return 1\n    actual_size=$(wc -c < "$trusted_root" | tr -d \'[:space:]\') || return 1\n    [[ "$actual_size" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE" ]] || return 1\n    actual_sha256=$(sha256sum "$trusted_root" | awk \'{print $1}\') || return 1\n    [[ "$actual_sha256" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256" ]] || return 1\n    [[ "$(wc -l < "$trusted_root" | tr -d \'[:space:]\')" == "1" ]] || return 1\n    jq -e \'type == "object" and .mediaType == "application/vnd.dev.sigstore.trustedroot+json;version=0.1"\' \\\n        "$trusted_root" >/dev/null 2>&1\n}\n\nsupacloud_prepare_attestation_trusted_root() {\n    local destination="$1"\n    local trusted_root="${SUPACLOUD_ATTESTATION_TRUSTED_ROOT:-$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT}"\n    supacloud_attestation_trusted_root_available || {\n        echo "Pinned Sigstore Public Good trusted root is missing or invalid" >&2\n        return 1\n    }\n    jq -ce . "$trusted_root" > "$destination" || return 1\n    chmod 600 "$destination"\n    [[ "$(wc -c < "$destination" | tr -d \'[:space:]\')" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE" ]] || return 1\n    [[ "$(sha256sum "$destination" | awk \'{print $1}\')" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256" ]]\n}\n\nsupacloud_verify_attestation() (\n    local artifact_file="$1"\n    if supacloud_attestation_verifier_available; then\n        local verification_output bundle_dir bundle_file trusted_root_file\n        bundle_dir=$(mktemp -d "${TMPDIR:-/tmp}/supacloud-attestation.XXXXXX") || return 1\n        trap \'rm -rf -- "$bundle_dir"\' EXIT\n        trap \'trap - EXIT HUP INT TERM; rm -rf -- "$bundle_dir"; exit 1\' HUP INT TERM\n        bundle_file="${bundle_dir}/bundle.jsonl"\n        trusted_root_file="${bundle_dir}/trusted_root.jsonl"\n        if ! supacloud_fetch_attestation_bundle "$artifact_file" "$bundle_file"; then\n            return 1\n        fi\n        supacloud_prepare_attestation_trusted_root "$trusted_root_file" || return 1\n        if ! verification_output=$(gh attestation verify "$artifact_file" \\\n            --bundle "$bundle_file" \\\n            --custom-trusted-root "$trusted_root_file" \\\n            --repo "$SUPACLOUD_GITHUB_REPOSITORY" \\\n            --signer-workflow "$SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW" \\\n            --source-ref "refs/heads/main" \\\n            --deny-self-hosted-runners 2>&1); then\n            echo "GitHub artifact attestation verification failed: ${verification_output}" >&2\n            return 1\n        fi\n        supacloud_record_integrity_mode "github-attestation+same-release-sha256"\n        return\n    fi\n\n    if [[ "${SUPACLOUD_ALLOW_UNVERIFIED_RELEASE:-false}" == "true" ]]; then\n        echo "BREAK-GLASS LIMITED INTEGRITY MODE: artifact attestation verification is unavailable; only the same-release SHA256 checksum was verified." >&2\n        supacloud_record_integrity_mode "break-glass:same-release-sha256-only"\n        return 0\n    fi\n\n    echo "Artifact attestation verification is required, but gh attestation verify is unavailable. Install GitHub CLI or explicitly set SUPACLOUD_ALLOW_UNVERIFIED_RELEASE=true for emergency break-glass use." >&2\n    return 1\n)\n\nsupacloud_attestation_verifier_available() {\n    local version help\n    supacloud_attestation_trusted_root_available || return 1\n    command -v gh >/dev/null 2>&1 || return 1\n    version=$(supacloud_gh_version)\n    [[ -n "$version" ]] || return 1\n    supacloud_version_at_least "$version" "$SUPACLOUD_GH_MIN_VERSION" || return 1\n    help=$(gh attestation verify --help 2>&1) || return 1\n    grep -Eq -- \'(^|[[:space:]])--bundle([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--signer-workflow([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--source-ref([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--custom-trusted-root([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--deny-self-hosted-runners([=[:space:]]|$)\' <<< "$help"\n}\n\nsupacloud_download_release_asset() (\n    local release_json="$1"\n    local asset_name="$2"\n    local destination="$3"\n    local asset_kind="$4"\n    local asset_url checksum_url temporary_artifact temporary_checksums\n\n    asset_url=$(supacloud_release_asset_url "$release_json" "$asset_name") || return 1\n    checksum_url=$(supacloud_release_asset_url "$release_json" SHA256SUMS) || return 1\n    mkdir -p "$(dirname "$destination")"\n    temporary_artifact=$(mktemp "${destination}.tmp.XXXXXX")\n    temporary_checksums=$(mktemp "${destination}.SHA256SUMS.tmp.XXXXXX")\n    trap \'rm -f "${temporary_artifact:-}" "${temporary_checksums:-}"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -f "${temporary_artifact:-}" "${temporary_checksums:-}"; exit 1\' HUP INT TERM\n\n    if ! supacloud_download_url "$asset_url" "$temporary_artifact" \\\n        || ! supacloud_download_release_metadata_url "$checksum_url" "$temporary_checksums" \\\n        || ! supacloud_verify_checksum "$temporary_artifact" "$asset_name" "$temporary_checksums"; then\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    fi\n\n    # Authenticate the digest before parsing archives or inspecting binaries.\n    if ! supacloud_verify_attestation "$temporary_artifact"; then\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    fi\n\n    case "$asset_kind" in\n        binary) supacloud_validate_binary "$temporary_artifact" "$asset_name" ;;\n        tar) supacloud_validate_tar "$temporary_artifact" ;;\n        *)\n            echo "Unknown release asset kind: $asset_kind" >&2\n            rm -f "$temporary_artifact" "$temporary_checksums"\n            return 1\n            ;;\n    esac || {\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    }\n\n    mv -f "$temporary_artifact" "$destination"\n    temporary_artifact=""\n    rm -f "$temporary_checksums"\n    temporary_checksums=""\n)\n';
@@ -29043,12 +29302,13 @@ function platformVersionsToolResult(report) {
 }
 function registerSshTools(server, ssh) {
   server.tool("ssh", `Server management via SSH. Available before & after SupaCloud installation.
-Actions: ping, setup, install, upgrade, versions, diagnose, exec, troubleshoot, container_logs, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
+Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec, troubleshoot, container_logs, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
     action: withDescription(stringEnum([
       "ping",
       "setup",
       "install",
       "upgrade",
+      "upgrade_status",
       "versions",
       "diagnose",
       "exec",
@@ -29068,6 +29328,7 @@ Actions: ping, setup, install, upgrade, versions, diagnose, exec, troubleshoot,
     dashboard_password: optional(secretSchema("dashboard_password"), "[install] Console password"),
     edge_runtime: optional(stringEnum(["bun"]), "[install] Runtime (default: bun)"),
     storage_type: optional(stringEnum(["juicefs", "minio"]), "[install] Storage backend configurable through Admin"),
+    transaction_id: optional(Type.String(), "[upgrade_status] UUID v4 transaction ID of a retained local-artifact upgrade"),
     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)"),
@@ -29226,6 +29487,14 @@ ${result.stderr.slice(-500)}`;
 ${upgradeExecution.stdout.slice(-300)}${edgeBoundary}`;
         break;
       }
+      case "upgrade_status": {
+        if (!args.transaction_id)
+          throw new Error("'transaction_id' required");
+        const transactionId = assertValidTransactionId(args.transaction_id);
+        const projection = await inspectRemoteUpgradeStatus(ssh, transactionId);
+        text = JSON.stringify(projection, null, 2);
+        break;
+      }
       case "versions": {
         return platformVersionsToolResult(await platformVersions(ssh));
       }
@@ -32245,7 +32514,7 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.15.4",
+  version: "0.16.0",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",