huaweicloud-devkit 1.1.10 → 1.1.11

package/plugins/huaweicloud-core/skills/huawei-sandbox/references/fullstack-postgrest.md

@@ -0,0 +1,149 @@
+# Full-Stack on the Sandbox: PostgreSQL 16 + PostgREST + Nginx
+
+A REST API over a real database, fully inside the sandbox: PostgREST generates
+a RESTful API from the PostgreSQL schema; nginx serves a frontend and
+reverse-proxies `/api` to PostgREST on a single origin (no CORS needed).
+All values below are **measured** on HCE 2.0 (aarch64, no systemd, dnf) in the
+2026-10 test. Nginx templates: see `nginx-templates.md`. Tunnel exposure:
+see `tunnel-persistence.md`.
+
+## Architecture
+
+```
+browser → tunnel URL → nginx :8080
+                        ├─ /       → static frontend (index.html)
+                        └─ /api/   → proxy_pass http://127.0.0.1:3000 (PostgREST)
+                                       └─ PostgreSQL 16 :5432 → schema api
+```
+
+## Step 1: PostgreSQL 16 on HCE 2.0 (the hard part)
+
+The OS repo only ships PostgreSQL 13, but PostgREST 16.x **requires PG ≥ 14**
+(it refuses with "Cannot run in this PostgreSQL version, PostgREST needs at
+least 14.0"). PGDG is the source for PG 16 — but HCE is NOT el8-lib-compatible:
+
+```bash
+# PGDG repo RPM fails on HCE ("nothing provides /etc/redhat-release") — write the repo file by hand.
+# The el8 path is rhel-8-aarch64 WITH A HYPHEN: rhel8-aarch64 (no hyphen) 404s.
+cat > /etc/yum.repos.d/pgdg16.repo << 'PGDG_EOF'
+[pgdg16]
+name=PostgreSQL 16 for RHEL8 aarch64
+baseurl=https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-8-aarch64/
+enabled=1
+gpgcheck=0
+PGDG_EOF
+```
+
+The PGDG el8 RPMs need RHEL-8-era libraries HCE does not have. el9 RPMs fail
+differently (they want `libldap-2.5.so.0`). Install the el8 RPMs with
+`--nodeps` and shim the sonames:
+
+```bash
+BASE="https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-8-aarch64"
+# Download with resume (--max-time + -C -): GitHub/pgdn downloads from the CN
+# region stall; a partial RPM fails rpm verification and ABORTS the whole transaction,
+# silently skipping the other RPMs in the same rpm -ivh call. Install one RPM per call.
+curl -fsSL --http1.1 --max-time 240 -C - "$BASE/postgresql16-libs-16.15-1PGDG.rhel8.10.aarch64.rpm" -o /tmp/pg16-libs.rpm
+rpm -ivh --nodeps /tmp/pg16-libs.rpm
+curl -fsSL --http1.1 --max-time 240 -C - "$BASE/postgresql16-16.15-1PGDG.rhel8.10.aarch64.rpm" -o /tmp/pg16.rpm
+rpm -ivh --nodeps /tmp/pg16.rpm
+curl -fsSL --http1.1 --max-time 240 -C - "$BASE/postgresql16-server-16.15-1PGDG.rhel8.10.aarch64.rpm" -o /tmp/pg16-server.rpm
+rpm -ivh --nodeps /tmp/pg16-server.rpm
+```
+
+Soname shims (measured 2026-10):
+
+```bash
+# ICU: versioned symbols (u_strToLower_60) make symlinks IMPOSSIBLE — a
+# libicu.so.60 -> .69 symlink loads but crashes with "undefined symbol".
+# Install the REAL el8 libicu60 (different sonames, coexists with HCE's icu69):
+curl -fsSL --http1.1 --max-time 240 -C - \
+  "https://repo.almalinux.org/almalinux/8/BaseOS/aarch64/os/Packages/libicu-60.3-2.el8_1.aarch64.rpm" -o /tmp/libicu60.rpm
+rpm -ivh --nodeps --force /tmp/libicu60.rpm   # --force: license file conflicts with icu69
+
+# LDAP: postgres only uses it for LDAP auth (not needed here) — symlinks suffice.
+ln -sf /usr/lib64/libldap.so.2.0.200 /usr/lib64/libldap-2.4.so.2
+ln -sf /usr/lib64/libldap.so.2.0.200 /usr/lib64/libldap_r-2.4.so.2   # initdb needs the _r soname
+ln -sf /usr/lib64/liblber.so.2.0.200  /usr/lib64/liblber-2.4.so.2
+
+# readline: psql links libreadline.so.7 (el8); HCE has .8 — API-compatible, symlink fine.
+ln -sf /usr/lib64/libreadline.so.8 /usr/lib64/libreadline.so.7
+
+ldconfig   # registers /usr/pgsql-16/lib (libpq.so.5)
+```
+
+Init and start (PG refuses root; no systemd on HCE):
+
+```bash
+mkdir -p /var/lib/pgsql/16/data && chown postgres:postgres /var/lib/pgsql/16/data
+su - postgres -c "/usr/pgsql-16/bin/initdb -D /var/lib/pgsql/16/data"
+su - postgres -c "/usr/pgsql-16/bin/pg_ctl -D /var/lib/pgsql/16/data -l /var/lib/pgsql/16/logfile start"
+```
+
+## Step 2: PostgREST (static build) + schema
+
+PostgREST 16.4 `linux-static-aarch64` runs on HCE out of the box (musl
+static). **Dynamic Ubuntu builds do NOT work** — HCE glibc 2.34 is older than
+Ubuntu 22.04's 2.35 and the binaries fail on load.
+
+```bash
+# https://github.com/PostgREST/postgrest/releases → postgrest-v16.4.0-linux-static-aarch64.tar.xz
+mkdir -p /opt/postgrest && tar -xJf postgrest-*.tar.xz -C /opt/postgrest
+
+cat > /opt/postgrest/pgrst.conf << 'PGRST_EOF'
+db-uri = "postgres://api_user:<db-password>@localhost:5432/postgres"
+db-schemas = "api"
+db-anon-role = "api_user"
+server-host = "127.0.0.1"
+server-port = 3000
+PGRST_EOF
+
+# Schema + read-only API role (the anon role gates all writes)
+su - postgres -c "/usr/pgsql-16/bin/psql -c \"CREATE SCHEMA api; CREATE TABLE api.todos (id serial primary key, done boolean not null default false, task text not null); CREATE ROLE api_user LOGIN PASSWORD '<db-password>'; GRANT USAGE ON SCHEMA api TO api_user; GRANT SELECT ON ALL TABLES IN SCHEMA api TO api_user;\""
+
+setsid nohup /opt/postgrest/postgrest /opt/postgrest/pgrst.conf > /tmp/pgrst.log 2>&1 < /dev/null &
+disown
+curl -s http://127.0.0.1:3000/todos          # [{"id":1,...}]
+curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/   # OpenAPI root, 200
+```
+
+PostgREST allows all CORS origins by default (`Access-Control-Allow-Origin: *`).
+
+## Step 3: Nginx single-origin (frontend + /api)
+
+```bash
+cat > /etc/nginx/conf.d/app.conf << 'NGINX_EOF'
+server {
+    listen <port>;
+    root /var/www/<app>;
+    index index.html;
+    location /api/ {
+        proxy_pass http://127.0.0.1:3000/;   # trailing slashes strip the /api prefix
+        proxy_set_header Host $host;
+    }
+}
+NGINX_EOF
+nginx -t && nginx -s reload 2>/dev/null || nginx
+```
+
+TRAP (measured 2026-10): nginx runs as the `nginx` user but the frontend dir is
+root-owned — `/` returns **403** until the traverse bit is set on the whole
+path chain: `chmod o+x /var/www /var/www/<app>` (and `o+r` on the files).
+This mirrors the deploy_nginx project-path permission fix.
+
+Frontend pages fetch backend data same-origin: `fetch('/api/todos?order=id.asc')`
+— no CORS, no absolute URLs, no CDN dependencies (keep pages self-contained;
+CN-region CDNs stall sandbox egress).
+
+## Step 4: Expose + keep alive
+
+```bash
+# Port on the tunnel must be the ACTUAL nginx port
+devbridge host -p <port> -e 720
+# Then install the watchdog (renewal + host re-attach + health check)
+# → huaweicloud_sandbox_keepalive_watchdog / references/tunnel-persistence.md
+```
+
+Verify end-to-end through the public URL: `GET /` (page, 200), `GET /api/todos`
+(data, 200), `POST /api/todos` (401 — the anon role has SELECT only; if a write
+API is wanted, grant INSERT/UPDATE on the specific table, never to anon broadly).

package/plugins/huaweicloud-core/skills/huawei-sandbox/references/tunnel-persistence.md

@@ -0,0 +1,121 @@
+# Tunnel Persistence: Renewal, Re-attach, and the Keepalive Watchdog
+
+DevBridge tunnel URLs are bound to the tunnel ID, not to the host process. The
+URL `https://<tunnel-id>-<port>.devbridge-s2.hwtunnel.com` keeps working as long
+as (a) the tunnel has lifetime left and (b) a `devbridge host` process is
+attached. Persistence is therefore about **preventing expiry, not recovering
+URLs** — a tunnel whose record is lost cannot be recovered with the same URL.
+
+All values below are **measured** (2026-10 tunnel-persistence test), not
+inferred. Plugin automation: `huaweicloud_sandbox_renew_tunnel` and
+`huaweicloud_sandbox_keepalive_watchdog`.
+
+## Rolling-window expiry (measured)
+
+The `-e <hours>` expiry is a **rolling window**: renewal sets
+`expiration = now + hours` regardless of remaining time.
+
+```bash
+# 14:15Z: create with a 1-hour window
+devbridge host -p 8080 -e 1          # Tunnel URL: https://nv2dvv6w-8080...
+# 14:25Z: renew 10 minutes later
+devbridge update nv2dvv6w -e 1
+# expiration = 15:25Z = renewal time + 1h (NOT original expiry + 1h)
+```
+
+Consequences:
+
+- Renewing **before** expiry keeps the same URL alive indefinitely — the
+  "permanent link" pattern is daily renewal, never URL recovery.
+- `-e` accepts **1..720** hours (720 = 30 days, exact `+2592001s`). Larger
+  values are rejected.
+
+## Reading the absolute expiration
+
+Non-verbose `show` prints a relative value only; `-v` surfaces the Unix
+timestamp:
+
+```bash
+devbridge show nv2dvv6w -v | grep -oE 'tunnelExpiration[^0-9]+[0-9]+'
+# tunnelExpiration":1795022391  (UTC seconds; ~30 days after a 720h renew)
+```
+
+## Host re-attach: same tunnel, same URL
+
+If the host process dies (sandbox restart, session teardown), re-attach with the
+tunnel ID — the URL does **not** change:
+
+```bash
+devbridge host <tunnel-id>
+```
+
+Always launch in the session-detached form so the host survives the exec
+session: `setsid nohup devbridge host <id> ... < /dev/null &` + `disown`
+(see the expose flow for why all three matter).
+
+## Three-layer keepalive watchdog (the proven pattern)
+
+Layer 1 keeps the host process alive, layer 2 keeps the lifetime topped up
+daily (29 days of tolerance if renewal ever stops firing), layer 3 detects a
+dead URL within 5 minutes. Install via
+`huaweicloud_sandbox_keepalive_watchdog`, or by hand:
+
+```bash
+cat > /tmp/tunnel-keepalive.sh << 'KEEPALIVE_EOF'
+#!/bin/bash
+# /workspace/.local/bin FIRST — it survives sandbox reboots; ~/.huawei/bin is
+# on the system disk and is wiped back to the image state on reboot (#999).
+export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"
+# entries: tunnelId:url — URLs HARDCODED, never derived from port list (see trap 2)
+TUNNELS="<tunnel-id>:https://<tunnel-id>-<port>.devbridge-s2.hwtunnel.com"
+declare -A LAST_RENEW
+while true; do
+  NOW=$(date -u +%s); TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  for entry in $TUNNELS; do
+    ID="${entry%%:*}"; URL="${entry#*:}"
+    # Layer 1: host watchdog — re-attach keeps the URL (bound to tunnel ID)
+    if ! pgrep -f "devbridge host $ID" > /dev/null 2>&1; then
+      setsid nohup devbridge host "$ID" > "/tmp/host-$ID.log" 2>&1 < /dev/null &
+      echo "$TS host $ID restarted" >> /tmp/tunnel-keepalive.log; sleep 8
+    fi
+    # Layer 2: daily renewal (86400s) — rolling window keeps the URL alive
+    if [ $((${LAST_RENEW[$ID]:-0})) -eq 0 ] || [ $((NOW - ${LAST_RENEW[$ID]})) -ge 86400 ]; then
+      devbridge update "$ID" -e 720 >> /tmp/tunnel-keepalive.log 2>&1 \
+        && echo "$TS renew $ID ok (720h)" >> /tmp/tunnel-keepalive.log \
+        || echo "$TS renew $ID FAILED" >> /tmp/tunnel-keepalive.log
+      LAST_RENEW[$ID]=$NOW
+    fi
+    # Layer 3: health check every 5 min (loop sleep), log on non-200/304
+    HC=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$URL/" 2>/dev/null || echo "000")
+    [ "$HC" != "200" ] && [ "$HC" != "304" ] \
+      && echo "$TS health $ID WARN http=$HC" >> /tmp/tunnel-keepalive.log
+  done
+  sleep 300
+done
+KEEPALIVE_EOF
+chmod +x /tmp/tunnel-keepalive.sh
+setsid nohup /tmp/tunnel-keepalive.sh > /dev/null 2>&1 < /dev/null &
+disown
+```
+
+The pgrep pattern MUST be tunnel-specific (`devbridge host $ID`) — a bare
+`pgrep -f "devbridge host"` matches _any_ tunnel's host and silently skips
+re-attaching the dead one (measured 2026-10).
+
+## Traps (all measured)
+
+1. **Health-check URL must match the served content.** The watchdog checks
+   `$URL/` — checking `$URL/todos` against a static page server logs a false
+   404 WARN on every tick. Use the path that actually returns 200/304.
+2. **Never build the health URL from `devbridge port list` output.** The table
+   lines are wrapped in OSC escape sequences, so anchored greps
+   (`^\S+ \K[0-9]+`) silently fail and the constructed URL 404s. Hardcode the
+   URL per tunnel — tunnel IDs never change, so the URL is stable.
+3. **The management plane can lose a tunnel record while the data plane still
+   serves.** `devbridge show <id>` / `devbridge update <id>` return
+   `10002 tunnel not found` even though the URL keeps working (host attached).
+   The tunnel then cannot be renewed or inspected — treat it as disposable and
+   create a fresh tunnel for anything that must survive.
+4. **Renewal success = exit 0 AND absolute expiration visible.** A bare exit
+   code from a still-running host process says nothing about the management
+   record. Verify with `show <id> -v` (see `huaweicloud_sandbox_renew_tunnel`).

package/plugins/huaweicloud-core/skills/huawei-voucher/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: huawei-voucher
 description: '查询和领取华为云激励代金券（一人一次）；领取华为开发者大赛·小红书skill创新赛专属代金券（需已完成赛事报名）。激励代金券：当用户首次使用、开始会话、询问插件能力，或提到"领券/代金券/优惠券/激励金/领取/福利"等话题时，先调 voucher_status 查领取状态：未领取（claimed=false）则主动提示可领取一张代金券并询问是否领取；已领取（claimed=true）或状态不明确则静默不打扰。赛事代金券：仅在用户明确要求领取大赛代金券时调用 competition_voucher_claim，不要主动提示。Triggers: 首次使用, 会话开始, voucher, coupon, incentive, 领券, 代金券, 优惠券, 激励金, 领取, 福利, 华为开发者大赛, 小红书, skill创新赛, 赛事代金券, 大赛代金券, 比赛领券. NOT for: 账单/费用查询（用 huawei-billing）。'
-version: 2
+version: 3
 ---
 
 # 华为云代金券
@@ -43,14 +43,16 @@ version: 2
 
 ### 3. 结果解读（错误码 UX）
 
-| 返回 message 关键特征                                                   | 含义                        | 对用户表述               |
-| ----------------------------------------------------------------------- | --------------------------- | ------------------------ |
-| `领取成功`                                                              | 发券成功                    | 告知券已到账             |
-| `已领取过` / `已领取`                                                   | 该账号已领过                | 告知已领取，不打扰       |
-| `本月代金券总额度已用完，所有账号均无法领取`                            | 全局额度用尽（HD.60630042） | 告知下月再试             |
-| `请先完成实名认证`                                                      | 账号未实名（HD.60630022）   | 引导去控制台实名认证     |
-| `发券失败: <原文>`                                                      | 其他错误                    | 原样转达，不展开         |
-| `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK |
+| 返回 message 关键特征                                                   | 含义                        | 对用户表述                   |
+| ----------------------------------------------------------------------- | --------------------------- | ---------------------------- |
+| `领取成功`                                                              | 发券成功                    | 告知券已到账                 |
+| `已领取过` / `已领取`                                                   | 该账号已领过                | 告知已领取，不打扰           |
+| `code=HDKIT_VOUCHER_NOT_CONFIGURED`（代金券服务配置缺失…）              | 服务端未配置有效期天数      | 告知代金券暂不可用，稍后再试 |
+| `code=HDKIT_VOUCHER_EXPIRE_INVALID`（代金券失效时间配置异常…）          | 失效时间配置非法            | 告知代金券暂不可用，稍后再试 |
+| `本月代金券总额度已用完，所有账号均无法领取`                            | 全局额度用尽（HD.60630042） | 告知下月再试                 |
+| `请先完成实名认证`                                                      | 账号未实名（HD.60630022）   | 引导去控制台实名认证         |
+| `发券失败: <原文>`                                                      | 其他错误                    | 原样转达，不展开             |
+| `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK     |
 
 ## 赛事代金券（华为开发者大赛·小红书skill创新赛）
 
@@ -75,6 +77,8 @@ version: 2
 | `已领取过` / `已领取`                                                   | 该账号已领过赛事券          | 告知已领取，不打扰                |
 | `code=HDKIT_COMPETITION_NOT_FOUND`（赛事不存在或已下线）                | 赛事配置异常                | 告知赛事暂不可用，稍后再试        |
 | `code=HDKIT_COMPETITION_NOT_CONFIGURED`（赛事代金券服务配置缺失…）      | 服务端活动参数未配置        | 告知赛事代金券暂未开放，稍后再试  |
+| `code=HDKIT_VOUCHER_NOT_CONFIGURED`（代金券服务配置缺失…）              | 服务端未配置有效期天数      | 告知代金券暂不可用，稍后再试      |
+| `code=HDKIT_VOUCHER_EXPIRE_INVALID`（代金券失效时间配置异常…）          | 失效时间配置非法            | 告知代金券暂不可用，稍后再试      |
 | `本月代金券总额度已用完，所有账号均无法领取`                            | 全局额度用尽（HD.60630042） | 告知下月再试                      |
 | `请先完成实名认证`                                                      | 账号未实名（HD.60630022）   | 引导去控制台实名认证              |
 | `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK          |

package/plugins/huaweicloud-core/src/safety-policy.mjs

@@ -297,8 +297,12 @@ export function classifyHcloudArgs(args, options = {}) {
     'chattri',
     'bucketpolicy',
     'lifecycle',
-    'cors',
-    'website',
+    // #1001: 'cors' and 'website' were removed — KooCLI 7.x's OBS wrapper does
+    // NOT expose them (`hcloud OBS help cors` → "No such command"; same for
+    // website). A nonexistent command cannot produce a write side effect, so
+    // grading it as a write was safety based on a stale assumption. CORS/static-
+    // website config goes through the REST API (PUT /?cors) — see the
+    // huawei-obs skill common-pitfalls.md CORS chapter.
     'sign',
     'share-add',
     'share-update',

package/plugins/huaweicloud-core/src/sandbox/hwlink-api.mjs

@@ -119,20 +119,41 @@ async function apiPost(path, body, ak, sk, securitytoken) {
   return { status: resp.status, data: await resp.json() };
 }
 
-export async function createConnection(envId, ak, sk, securitytoken) {
-  const { status, data } = await apiPost(
-    `/open-api-public/v1/devenvs/${envId}/connections`,
-    { source: 'CLI' },
-    ak,
-    sk,
-    securitytoken,
-  );
+// Transient/restriction-class error codes from the connection API.
+// HDKIT_SUB_ACCOUNT_RESTRICTED and HD.83700029 are the SAME server-side
+// transient condition under two different codes (measured 2026-10-21/22: the
+// same AK/SK and the same request body got HD.83700029 on the 21st and
+// HDKIT_SUB_ACCOUNT_RESTRICTED on the 22nd — the code drifts between calls).
+// The message accuses the account of being a restricted sub-account, but a
+// fully compliant account (realnameVerified:true, agreementSigned:true, no
+// sub-users) got the SAME error and the identical request succeeded 25 minutes
+// later — the only action that helped was waiting. Retry these instead of
+// failing, and NEVER surface the server's "switch to the main account" advice
+// as actionable: acting on it is an irreversible, account-wide operation
+// triggered by a transient state.
+const TRANSIENT_CONNECTION_CODES = new Set(['HDKIT_SUB_ACCOUNT_RESTRICTED', 'HD.83700029']);
+
+// Classify a connection-API failure (exported for tests). Returns
+// 'transient_restricted' / 'retryable_server' (retried with backoff) or
+// 'fatal' (fails fast, no retry).
+export function classifyConnectionError(data, status) {
+  const code = String(data?.error_code || data?.code || '').toUpperCase();
+  if (TRANSIENT_CONNECTION_CODES.has(code)) return 'transient_restricted';
+  if (status === 429 || (status >= 500 && status < 600)) return 'retryable_server';
+  return 'fatal';
+}
 
-  if (status !== 200 || data?.error_code !== '0000' || !data?.result?.connection_id) {
-    throw new Error(`Failed to create connection: ${JSON.stringify(data)}`);
-  }
+// Default backoff between connection retries, in ms. The measured incident
+// self-resolved in ~25 minutes, so three spaced retries cover the short end
+// without blocking exec callers for long.
+export const CONNECTION_RETRY_BACKOFF_MS = [1000, 4000, 10000];
 
-  const connectionId = data.result.connection_id;
+const CONNECTION_RETRY_HINT =
+  'This is a TRANSIENT server-side state, NOT an account problem: the same request typically succeeds after a short wait ' +
+  '(measured 2026-10-22: HDKIT_SUB_ACCOUNT_RESTRICTED self-resolved in 25 minutes for a fully compliant account — realname verified, agreement signed, no sub-users). ' +
+  'Do NOT switch to the main account, do NOT modify IAM users or credentials based on this error — retry with backoff instead.';
+
+async function waitForConnection(connectionId, envId, ak, sk, securitytoken) {
   const maxAttempts = 60;
 
   for (let i = 0; i < maxAttempts; i++) {
@@ -159,3 +180,45 @@ export async function createConnection(envId, ak, sk, securitytoken) {
 
   throw new Error(`Timed out waiting for connection ${connectionId}`);
 }
+
+export async function createConnection(envId, ak, sk, securitytoken, { maxRetries = 3, backoffMs } = {}) {
+  const backoff = backoffMs || CONNECTION_RETRY_BACKOFF_MS;
+  const maxAttempts = maxRetries + 1;
+  let lastFailure = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (attempt > 1) {
+      const wait = backoff[Math.min(attempt - 2, backoff.length - 1)];
+      process.stderr.write(
+        `createConnection: retryable error (${lastFailure.kind}) — retry ${attempt - 1}/${maxRetries} in ${wait}ms\n`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, wait));
+    }
+    const { status, data } = await apiPost(
+      `/open-api-public/v1/devenvs/${envId}/connections`,
+      { source: 'CLI' },
+      ak,
+      sk,
+      securitytoken,
+    );
+
+    if (status === 200 && data?.error_code === '0000' && data?.result?.connection_id) {
+      return await waitForConnection(data.result.connection_id, envId, ak, sk, securitytoken);
+    }
+
+    const kind = classifyConnectionError(data, status);
+    if (kind === 'fatal') {
+      throw new Error(`Failed to create connection: ${JSON.stringify(data)}`);
+    }
+    lastFailure = { kind, status, data };
+  }
+
+  const err = new Error(
+    `Failed to create connection after ${maxAttempts} attempts (${lastFailure.kind}): ${JSON.stringify(lastFailure.data)}. ${CONNECTION_RETRY_HINT}`,
+  );
+  err.code = String(lastFailure.data?.error_code || `HTTP_${lastFailure.status}`);
+  err.kind = lastFailure.kind;
+  err.retryable = true;
+  err.suggestedRetryAfterMs = backoff[backoff.length - 1];
+  throw err;
+}