huaweicloud-devkit 1.1.13-next.5 → 1.1.13-next.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "kooCliVersion": "7.3.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.13-next.5",
+  "version": "1.1.13-next.6",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

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

@@ -187,8 +187,10 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
    sleep 1
    # Remove stale nginx configs from previous deployments
    sudo rm -f /etc/nginx/conf.d/*.conf /etc/nginx/conf.d/*.conf.bak 2>/dev/null
-   # Remove stale DevBridge tunnels
-   devbridge delete-all 2>/dev/null || true
+   # Remove stale DevBridge tunnels only (keep other ports/sessions):
+   # list and delete orphan IDs; the automated connect cleanup does this too.
+   devbridge list
+   # devbridge delete <orphan-id>
    # Reload nginx to apply
    sudo nginx -s reload 2>/dev/null || true
    ```
@@ -358,7 +360,7 @@ fi
 
 - `-s` (silent) is **required** in the sandbox — without it the installer blocks reading `/dev/tty`.
 - **Old tunnels do not survive the upgrade**: 0.1.x-created tunnels are not registered on the s2 gateway — always rebuild the tunnel after upgrading (the expose flow below does this via pre-cleanup).
-- If `10006: quota exceeded` appears after upgrading, stale pre-upgrade tunnels still count against the quota — `devbridge delete-all` and retry.
+- If `10006: quota exceeded` appears after upgrading, stale pre-upgrade tunnels still count against the quota — the expose tool now removes orphans first, then the oldest non-keepalive tunnel one at a time. Manually: `devbridge list` and `devbridge delete <id>` for stale entries; reserve `devbridge delete-all` for an explicit full reset.
 
 ### Sandbox filesystem persistence: what survives a reboot (#999)
 
@@ -423,10 +425,10 @@ devbridge auth status
 Run the web server and the tunnel in the background, then read the URL from the log; the app lives in the workspace mount, e.g. `/workspace/<repo-name>`:
 
 ```bash
-# 0. Pre-cleanup: kill old processes and stale tunnels
-pkill -f "devbridge host" 2>/dev/null || true
-sleep 2
-devbridge delete-all 2>/dev/null || true
+# 0. Pre-cleanup: replace ONLY the tunnel bound to <port>; keep other ports/sessions.
+#    (huaweicloud_sandbox_expose_tunnel does this automatically with cleanup_mode=stale.)
+OLD_ID=$(devbridge list 2>/dev/null | awk '$2 ~ /^tunnel-<port>-/ {print $1; exit}')
+[ -n "$OLD_ID" ] && devbridge delete "$OLD_ID" >/dev/null 2>&1 || true
 
 # 1. Start tunnel
 if command -v setsid > /dev/null 2>&1; then setsid nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & else nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & fi
@@ -443,8 +445,9 @@ if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "304" ]; then
   echo "Tunnel verified: $TUNNEL_URL (HTTP $HTTP_CODE)"
 else
   echo "WARN: Tunnel URL unreachable (HTTP $HTTP_CODE). Rebuilding tunnel..."
-  pkill -f "devbridge host" && sleep 2
-  devbridge delete-all 2>/dev/null || true
+  # Rebuild only this port's tunnel; never kill/delete other ports or sessions.
+  OLD_ID=$(devbridge list 2>/dev/null | awk '$2 ~ /^tunnel-<port>-/ {print $1; exit}')
+  [ -n "$OLD_ID" ] && devbridge delete "$OLD_ID" >/dev/null 2>&1 || true
   if command -v setsid > /dev/null 2>&1; then setsid nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & else nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & fi
   disown 2>/dev/null || true
   sleep 10
@@ -465,8 +468,9 @@ fi
 #   0.2.x: `devbridge list` (plain table; data rows start with the 8-char tunnel ID)
 #   0.1.x (legacy): `devbridge list -j` (JSON)
 devbridge list
-# Step B: Remove all stale tunnels
-devbridge delete-all
+# Step B: Remove stale tunnels one by one (the expose tool already does
+#   orphans first, then oldest non-keepalive; keep keepalive-protected tunnels)
+# devbridge delete <stale-id>
 # Step C: Retry tunnel creation
 if command -v setsid > /dev/null 2>&1; then setsid nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & else nohup devbridge host -p <port> -e 72 > /tmp/host.log 2>&1 < /dev/null & fi
 disown 2>/dev/null || true
@@ -1006,7 +1010,7 @@ Follow the standard [Expose the deployed app](#expose-the-deployed-app-public-ur
 
 Use `exec_with_session` to background DevBridge. For SSR, DevBridge tunnels the nginx public port (not the Node port directly).
 
-**Pre-flight**: always run `devbridge delete-all` before creating a new tunnel to prevent `10006: quota exceeded` from accumulated stale tunnels. If you still get quota error, list tunnels with `devbridge list` (0.2.x plain table; 0.1.x legacy `-j` JSON), delete stale ones, and retry.
+**Pre-flight**: `huaweicloud_sandbox_expose_tunnel` now performs **selective cleanup** automatically (default `cleanup_mode=stale`): it removes orphan records/hosts and replaces the tunnel bound to the requested port; all other ports, other sessions and keepalive-protected tunnels are preserved (the same-port tunnel is the one documented exception — a port cannot have two tunnels). On `10006: quota exceeded` it removes all orphans first, then the oldest non-keepalive tunnel one at a time; keepalive-protected tunnels are never auto-deleted and a still-full quota returns `devbridge_tunnel_quota_exceeded`. `cleanup_mode=none` skips cleanup entirely (a stale same-port host can then conflict). For manual flows, prefer `devbridge list` + `devbridge delete <id>` for stale entries; use `devbridge delete-all` only for an explicit full reset (shared-sandbox warning below).
 
 > **Concurrency warning**: `devbridge delete-all` and `pkill -f "devbridge host"` are GLOBAL operations scoped to the whole sandbox — if multiple sessions share the same sandbox, pre-cleaning can kill tunnels published by other sessions and invalidate URLs you handed out earlier. For shared sandboxes, prefer `devbridge list` and delete only stale/your-own tunnels instead of blanket `delete-all`, and re-expose only after confirming the target port is still served.
 

package/plugins/huaweicloud-core/src/sandbox/session-manager.mjs

@@ -1302,8 +1302,10 @@ export async function closeSession(workspaceId, username) {
 //           fallback (devbridge-key.mjs) when keyring injection is unavailable.
 // AK/SK login (--access-key/--secret-key) was REMOVED: devbridge authentication is
 // now fixed to API Key only (定稿决策，2026-11-04).
-// Every tier performs a real `devbridge auth login --api-key` and verifies with
-// `auth status` (must print "Logged in"); on failure the waterfall falls through.
+// Every tier performs a real `devbridge auth login --api-key` (exit code checked),
+// then verifies with `auth status` AND a real authenticated API call (`devbridge list`);
+// on failure the waterfall falls through. The list check is required because a stale
+// key can leave a "Logged in" local token while server-side calls return 40100.
 // DB_ATTEMPT_* lines are non-sensitive diagnostics for support escalation.
 // The HOST orchestrates an auto-create fallback between probe rounds: when the
 // first probe returns NO_CREDENTIAL, the host calls ensureDevbridgeKey() and
@@ -1323,7 +1325,12 @@ export function buildDevbridgeAuthProbe() {
     `DB_VERSION=$(devbridge version 2>/dev/null | head -1)`,
     `echo "DB_VERSION=\${DB_VERSION}"`,
     `DB_OK=0`,
-    `db_login_ok() { devbridge auth status 2>/dev/null | grep -q "Logged in"; }`,
+    `db_login_ok() {`,
+    // 本地 token 可能仍显示 Logged in，但 API key 已在服务端失效（实测 list/renew 返回 40100）。
+    // 因此额外做一次真实鉴权 API 调用，确保探针结果可用（否则 auto-create 自愈不会触发）。
+    `  devbridge auth status 2>/dev/null | grep -q "Logged in" || return 1`,
+    `  devbridge list >/dev/null 2>&1`,
+    `}`,
     `db_diag() { echo "DB_ATTEMPT_$1=$2"; }`,
     ``,
     `# ---- Tier 1: API Key from the sandbox keyring (platform auto-injection) ----`,
@@ -1353,8 +1360,7 @@ export function buildDevbridgeAuthProbe() {
     `  db_diag KEYRING "hwcloud-not-installed"`,
     `fi`,
     `if [ -n "$HW_DB_KEY" ]; then`,
-    `  devbridge auth login --api-key "$HW_DB_KEY" >/tmp/db_auth.log 2>&1`,
-    `  if db_login_ok; then`,
+    `  if devbridge auth login --api-key "$HW_DB_KEY" >/tmp/db_auth.log 2>&1 && db_login_ok; then`,
     `    echo "DB_AUTH_MODE=API_KEY_KEYRING"`,
     `    DB_OK=1`,
     `  else`,
@@ -1368,8 +1374,7 @@ export function buildDevbridgeAuthProbe() {
     `if [ "$DB_OK" -eq 0 ]; then`,
     `  source /tmp/hw_api_key 2>/dev/null`,
     `  if [ -n "$HW_API_KEY" ]; then`,
-    `    devbridge auth login --api-key "$HW_API_KEY" >/tmp/db_auth.log 2>&1`,
-    `    if db_login_ok; then`,
+    `    if devbridge auth login --api-key "$HW_API_KEY" >/tmp/db_auth.log 2>&1 && db_login_ok; then`,
     `      echo "DB_AUTH_MODE=API_KEY_FILE"`,
     `      DB_OK=1`,
     `    else`,
@@ -1450,9 +1455,8 @@ export const DEVBRIDGE_HOST_EXPIRY_HOURS = 72;
 export function buildDevbridgeExposeScript(port, expiryHours = DEVBRIDGE_HOST_EXPIRY_HOURS) {
   const hostLog = '/tmp/host.log';
   return [
-    `pkill -f "devbridge host" 2>/dev/null || true`,
-    `sleep 2`,
-    `devbridge delete-all > /dev/null 2>&1 || true`,
+    // Pre-clean is now selective (cleanupDevbridgeTunnels) and runs before this
+    // script, so other ports/sessions are preserved.
     // #922 (S8): setsid is unavailable on some sandbox images — fall back to a
     // bare nohup launch so the host still starts; persistence is then judged by
     // the independent re-verify below, which emits the 请勿分享 warning in the
@@ -1735,6 +1739,7 @@ export function buildDevbridgeKeepaliveScript(tunnels) {
   const body = [
     `#!/bin/bash`,
     `export PATH="$HOME/.huawei/bin:$PATH"`,
+    `export DBUS_SESSION_BUS_ADDRESS="\${DBUS_SESSION_BUS_ADDRESS:-unix:path=/run/dbus-session}"`,
     `# entries: tunnelId:url (URLs are stable — tunnel IDs never change)`,
     `TUNNELS="${entries}"`,
     `declare -A LAST_RENEW`,
@@ -1753,6 +1758,26 @@ export function buildDevbridgeKeepaliveScript(tunnels) {
     `        echo "$TS renew $ID ok (${DEVBRIDGE_RENEW_HOURS}h)" >> /tmp/tunnel-keepalive.log`,
     `      else`,
     `        echo "$TS renew $ID FAILED: $(head -1 /tmp/keepalive-last-update.log)" >> /tmp/tunnel-keepalive.log`,
+    `        # Self-heal: CLI token 过期但 key 仍有效时，重新登录后立即重试一次`,
+    `        DB_KEY=""`,
+    `        if command -v hwcloud >/dev/null 2>&1; then`,
+    `          DB_KEY=$(hwcloud keyring get HW_DEVBRIDGE_API_KEY 2>&1 || true)`,
+    `          case "$DB_KEY" in "devbridge_"*) : ;; *) DB_KEY="";; esac`,
+    `        fi`,
+    `        if [ -z "$DB_KEY" ] && [ -s /tmp/hw_api_key ]; then`,
+    `          source /tmp/hw_api_key 2>/dev/null || true`,
+    `          DB_KEY="\${HW_API_KEY:-}"`,
+    `        fi`,
+    `        if [ -n "$DB_KEY" ] && devbridge auth login --api-key "$DB_KEY" >/tmp/keepalive-auth.log 2>&1; then`,
+    `          if devbridge update "$ID" -e ${DEVBRIDGE_RENEW_HOURS} > /tmp/keepalive-last-update.log 2>&1; then`,
+    `            echo "$TS renew $ID ok after re-login (${DEVBRIDGE_RENEW_HOURS}h)" >> /tmp/tunnel-keepalive.log`,
+    `          else`,
+    `            echo "$TS renew $ID FAILED after re-login: $(head -1 /tmp/keepalive-last-update.log)" >> /tmp/tunnel-keepalive.log`,
+    `          fi`,
+    `        else`,
+    `          echo "$TS renew $ID AUTH_FAILED: no usable key; next expose_tunnel will auto-create" >> /tmp/tunnel-keepalive.log`,
+    `        fi`,
+    `        unset DB_KEY HW_API_KEY 2>/dev/null`,
     `      fi`,
     `      LAST_RENEW[$ID]=$NOW`,
     `    fi`,
@@ -1854,6 +1879,337 @@ export async function installKeepaliveWatchdog(workspaceId, { tunnels }, usernam
   };
 }
 
+// ── DevBridge selective cleanup ─────────────────────────────────────────────
+// delete-all is intentionally NOT used: it kills other sessions/ports on a shared
+// sandbox. Cleanup removes only orphan tunnels/hosts and (for expose) tunnels bound
+// to the same port, preserving keepalive-protected and live-unknown tunnels.
+// Same-port is the one documented exception: a keepalive-protected tunnel on the
+// target port is replaced (you cannot bind two tunnels to one port).
+
+// Same charset as validateTunnelId: real IDs may contain 0/1/8/9, so parsing must
+// not assume the base32 subset.
+const DEVBRIDGE_TUNNEL_ID_RE = /^[A-Za-z0-9_-]{4,32}$/;
+const DEVBRIDGE_PATH_EXPORT = 'export PATH="/workspace/.local/bin:$HOME/.huawei/bin:$PATH"';
+const DEVBRIDGE_LOCK_PATH = '/tmp/devbridge-cleanup.lock';
+// Worst-case hold: state 60x2 + apply 60x2 + sync ~150 + release 60 ≈ 450s;
+// keep the stale threshold above the worst case so a second cleanup cannot
+// break a lock that is still legitimately held.
+const DEVBRIDGE_LOCK_STALE_MINUTES = 10;
+const DEVBRIDGE_CLEANUP_TIMEOUT_MS = 60000;
+
+export function normalizeCleanupMode(raw) {
+  return ['stale', 'all', 'none'].includes(raw) ? raw : 'stale';
+}
+
+export function parseDevbridgeTunnelList(stdout) {
+  const text = stripTerminalEscapes(String(stdout || ''));
+  const tunnels = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*Tunnel\s+ID\b/i.test(line)) continue;
+    const m = line.match(/^\s*([A-Za-z0-9_-]{4,32})\s+(.+)$/);
+    if (!m || !DEVBRIDGE_TUNNEL_ID_RE.test(m[1])) continue;
+    const id = m[1];
+    const rest = m[2];
+    const name = rest.trim().split(/\s{2,}|\t+/)[0] || '';
+    const portMatch = rest.match(/tunnel-(\d+)-/);
+    const expMatch = rest.match(/(\d+)\s*(day|days|hour|hours|minute|minutes)/i);
+    const unit = expMatch ? expMatch[2].toLowerCase() : '';
+    const multiplier = { day: 86400, days: 86400, hour: 3600, hours: 3600, minute: 60, minutes: 60 }[unit];
+    tunnels.push({
+      id,
+      name,
+      port: portMatch ? Number(portMatch[1]) : null,
+      expiryText: expMatch ? expMatch[0] : '',
+      expirySeconds: expMatch && multiplier ? Number(expMatch[1]) * multiplier : null,
+    });
+  }
+  return tunnels;
+}
+
+export function parseDevbridgeHostProcesses(stdout) {
+  const text = stripTerminalEscapes(String(stdout || ''));
+  const hosts = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*(\d+)\s+(.*)$/);
+    if (!m) continue;
+    // Anchor the executable so a shell wrapper (`bash -c "...devbridge host..."`)
+    // is never mistaken for a real host process.
+    const execMatch = m[2].match(/^(?:\S*\/)?devbridge\s+host\b(.*)$/);
+    if (!execMatch) continue;
+    const rest = execMatch[1].trim();
+    const tokens = rest ? rest.split(/\s+/) : [];
+    let id = null;
+    let port = null;
+    for (let i = 0; i < tokens.length; i += 1) {
+      const token = tokens[i];
+      if (token === '-p' && /^\d+$/.test(tokens[i + 1] || '')) {
+        port = Number(tokens[i + 1]);
+        i += 1;
+      } else if (token === '-e') {
+        i += 1;
+      } else if (token.startsWith('-')) {
+        // unknown flag: skip it
+      } else if (!id && DEVBRIDGE_TUNNEL_ID_RE.test(token) && !/^\d+$/.test(token)) {
+        id = token;
+      }
+    }
+    if (!id && port == null) continue; // unparseable host: ignore, never kill blindly
+    hosts.push({ pid: Number(m[1]), id, port });
+  }
+  return hosts;
+}
+
+/**
+ * Decide which tunnels/hosts to remove.
+ * - protected: keepalive TUNNELS entries (never removed unless mode=all or samePort)
+ * - orphan: tunnel record with no live host  -> removed in stale/quota
+ * - orphan host: host process with no matching tunnel record -> killed
+ * - quota: also removes the oldest non-protected live tunnels (maxExtra per call)
+ */
+export function planDevbridgeCleanup({
+  tunnels = [],
+  hosts = [],
+  keepalive = [],
+  mode = 'stale',
+  samePort = null,
+  maxExtra = 1,
+} = {}) {
+  if (mode === 'none') return { deleteIds: [], killPids: [] };
+
+  const tunnelIds = new Set(tunnels.map((t) => t.id));
+  const protectedIds = new Set(keepalive.map((k) => k.tunnelId).filter(Boolean));
+  const portById = new Map();
+  for (const t of tunnels) if (t.port != null) portById.set(t.id, t.port);
+  for (const k of keepalive) {
+    const m = String(k.url || '').match(/-(\d+)\.devbridge-s2\./);
+    if (m && tunnelIds.has(k.tunnelId)) portById.set(k.tunnelId, Number(m[1]));
+  }
+
+  if (mode === 'all') {
+    return { deleteIds: [...tunnelIds], killPids: hosts.map((h) => h.pid) };
+  }
+
+  const liveIds = new Set();
+  const mappedPids = new Set();
+  for (const h of hosts) {
+    if (!h.id && h.port == null) continue; // unattributable host: never kill blindly
+    if (h.id && tunnelIds.has(h.id)) {
+      liveIds.add(h.id);
+      mappedPids.add(h.pid);
+    } else if (h.port != null) {
+      for (const [id, port] of portById) {
+        if (port === h.port) {
+          liveIds.add(id);
+          mappedPids.add(h.pid);
+        }
+      }
+    }
+  }
+
+  const killPids = new Set(hosts.filter((h) => (h.id || h.port != null) && !mappedPids.has(h.pid)).map((h) => h.pid));
+  const samePortIds = samePort == null ? [] : tunnels.filter((t) => portById.get(t.id) === samePort).map((t) => t.id);
+  const orphanIds = tunnels.filter((t) => !protectedIds.has(t.id) && !liveIds.has(t.id)).map((t) => t.id);
+  const deleteSet = new Set([...orphanIds, ...samePortIds]);
+
+  if (mode === 'quota') {
+    const candidates = tunnels
+      .filter((t) => !protectedIds.has(t.id) && !deleteSet.has(t.id) && liveIds.has(t.id))
+      .sort((a, b) => (a.expirySeconds ?? Number.MAX_SAFE_INTEGER) - (b.expirySeconds ?? Number.MAX_SAFE_INTEGER));
+    for (let i = 0; i < Math.max(0, maxExtra) && i < candidates.length; i += 1) {
+      deleteSet.add(candidates[i].id);
+    }
+  }
+
+  for (const h of hosts) {
+    if (h.id && deleteSet.has(h.id)) killPids.add(h.pid);
+    else if (h.port != null && [...deleteSet].some((id) => portById.get(id) === h.port)) killPids.add(h.pid);
+  }
+
+  return { deleteIds: [...deleteSet], killPids: [...killPids] };
+}
+
+export function buildDevbridgeCleanupApplyScript({ deleteIds = [], killPids = [] } = {}) {
+  for (const id of deleteIds) {
+    if (!DEVBRIDGE_TUNNEL_ID_RE.test(String(id))) {
+      throw new Error(`devbridge cleanup: invalid tunnel id ${JSON.stringify(id)}`);
+    }
+  }
+  for (const pid of killPids) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+      throw new Error(`devbridge cleanup: invalid pid ${JSON.stringify(pid)}`);
+    }
+  }
+  return [
+    DEVBRIDGE_PATH_EXPORT,
+    // Re-check the process identity before killing: state→apply can take minutes,
+    // so a recycled PID must not hit an unrelated process.
+    ...killPids.map(
+      (pid) =>
+        `if ps -p ${pid} -o args= 2>/dev/null | grep -q "devbridge host"; then kill ${pid} >/dev/null 2>&1 || true; fi`,
+    ),
+    `sleep 1`,
+    ...deleteIds.map((id) => `devbridge delete ${id} >/dev/null 2>&1 || true`),
+    `echo "DB_CLEANUP_DELETED=${deleteIds.join(',')}"`,
+    `echo "DB_CLEANUP_KILLED=${killPids.join(',')}"`,
+  ].join('\n');
+}
+
+export function buildDevbridgeCleanupStateScript() {
+  return [
+    DEVBRIDGE_PATH_EXPORT,
+    // Refresh the CLI token from an existing key. A valid API key can leave an
+    // expired CLI token; without this, devbridge list returns 40100 and cleanup
+    // is skipped even though the key is usable. Never creates a new key here.
+    `DB_KEY=""`,
+    `if command -v hwcloud >/dev/null 2>&1; then`,
+    `  DB_KEY=$(hwcloud keyring get HW_DEVBRIDGE_API_KEY 2>&1 || true)`,
+    `  case "$DB_KEY" in "devbridge_"*) : ;; *) DB_KEY="";; esac`,
+    `fi`,
+    `if [ -z "$DB_KEY" ] && [ -s /tmp/hw_api_key ]; then`,
+    `  source /tmp/hw_api_key 2>/dev/null || true`,
+    `  DB_KEY="\${HW_API_KEY:-}"`,
+    `fi`,
+    `if [ -n "$DB_KEY" ]; then devbridge auth login --api-key "$DB_KEY" >/dev/null 2>&1 || true; fi`,
+    `unset DB_KEY HW_API_KEY 2>/dev/null`,
+    `echo "DB_CLEANUP_TUNNELS_BEGIN"`,
+    `devbridge list 2>&1 || true`,
+    `echo "DB_CLEANUP_TUNNELS_END"`,
+    `echo "DB_CLEANUP_HOSTS_BEGIN"`,
+    `pgrep -af "devbridge host" 2>&1 || true`,
+    `echo "DB_CLEANUP_HOSTS_END"`,
+    buildKeepaliveTunnelsReadScript(),
+  ].join('\n');
+}
+
+export function buildDevbridgeCleanupLockScript() {
+  return [
+    `LOCK=${DEVBRIDGE_LOCK_PATH}`,
+    `if mkdir "$LOCK" 2>/dev/null; then echo LOCK_OK; else`,
+    `  if find "$LOCK" -maxdepth 0 -mmin +${DEVBRIDGE_LOCK_STALE_MINUTES} 2>/dev/null | grep -q .; then rmdir "$LOCK" 2>/dev/null || true; fi`,
+    `  if mkdir "$LOCK" 2>/dev/null; then echo LOCK_OK; else echo LOCK_BUSY; fi`,
+    `fi`,
+  ].join('\n');
+}
+
+function cleanupSection(text, name) {
+  const m = String(text || '').match(new RegExp(`DB_CLEANUP_${name}_BEGIN\\r?\\n([\\s\\S]*?)DB_CLEANUP_${name}_END`));
+  return m ? m[1] : '';
+}
+
+async function execCleanupWithRetry(workspaceId, script, username, timeoutMs = 60000) {
+  let lastError;
+  for (let i = 1; i <= 2; i += 1) {
+    try {
+      return await execOneShot(workspaceId, script, username, timeoutMs);
+    } catch (error) {
+      lastError = error;
+      if (i === 2 || !/timeout|websocket/i.test(String(error?.message || ''))) throw error;
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+  }
+  throw lastError;
+}
+
+async function syncKeepaliveAfterCleanup(workspaceId, { deletedIds, liveTunnelIds, pruneMissing, username }) {
+  let current;
+  try {
+    const read = await execCleanupWithRetry(workspaceId, buildKeepaliveTunnelsReadScript(), username, 30000);
+    current = parseKeepaliveTunnelsOutput(read.stdout);
+  } catch {
+    return;
+  }
+  if (!current.length) return;
+  const deleted = new Set(deletedIds || []);
+  // Prune deleted IDs AND entries that no longer exist in the management plane
+  // (ghost tunnels from earlier delete-all calls would otherwise be re-hosted
+  // and renewed forever).
+  // Only prune "absent" entries when we have at least one confirmed live tunnel
+  // (or an explicit all-mode reset). A transient empty list must not wipe the
+  // watchdog and silently stop renewals.
+  const remaining = current.filter((t) => !deleted.has(t.tunnelId) && (!pruneMissing || liveTunnelIds.has(t.tunnelId)));
+  if (remaining.length === current.length) return;
+  if (remaining.length === 0) {
+    try {
+      await execCleanupWithRetry(
+        workspaceId,
+        `pkill -f "tunnel-keepalive.sh" 2>/dev/null || true; rm -f /tmp/tunnel-keepalive.sh`,
+        username,
+        30000,
+      );
+    } catch {}
+    return;
+  }
+  try {
+    await installKeepaliveWatchdog(workspaceId, { tunnels: remaining }, username, 30000);
+  } catch {}
+}
+
+export async function cleanupDevbridgeTunnels(
+  workspaceId,
+  { mode = 'stale', samePort = null, maxExtra = 1, username = 'root' } = {},
+) {
+  if (!workspaceId) throw new Error('devbridge cleanup: workspace_id is required.');
+  if (mode === 'none') return { ok: true, skipped: true, deleteIds: [], killPids: [] };
+
+  let lockResult;
+  try {
+    lockResult = await execOneShot(workspaceId, buildDevbridgeCleanupLockScript(), username, 30000);
+  } catch {
+    return { ok: false, locked: true, deleteIds: [], killPids: [] };
+  }
+  if (!stripTerminalEscapes(lockResult.stdout).includes('LOCK_OK')) {
+    return { ok: false, locked: true, deleteIds: [], killPids: [] };
+  }
+
+  try {
+    const stateResult = await execCleanupWithRetry(workspaceId, buildDevbridgeCleanupStateScript(), username, 60000);
+    const text = stripTerminalEscapes(stateResult.stdout);
+    const tunnelSection = cleanupSection(text, 'TUNNELS');
+    const listOk = /Tunnel ID|No tunnels found/i.test(tunnelSection);
+    if (!listOk) {
+      // list/auth/network failed — do not delete or kill anything on a guess.
+      return { ok: false, listFailed: true, deleteIds: [], killPids: [] };
+    }
+    const tunnels = parseDevbridgeTunnelList(tunnelSection);
+    const hosts = parseDevbridgeHostProcesses(cleanupSection(text, 'HOSTS'));
+    // Output-format drift guard: header matched but rows didn't parse, while host
+    // processes exist. Never mass-kill hosts on a parse we don't trust.
+    if (tunnels.length === 0 && hosts.length > 0 && !/No tunnels found/i.test(tunnelSection)) {
+      return { ok: false, listFailed: true, deleteIds: [], killPids: [] };
+    }
+    const keepalive = parseKeepaliveTunnelsOutput(text);
+    const liveTunnelIds = new Set(tunnels.map((t) => t.id));
+    const pruneMissing = mode === 'all' || liveTunnelIds.size > 0;
+    const plan = planDevbridgeCleanup({ tunnels, hosts, keepalive, mode, samePort, maxExtra });
+    if (plan.deleteIds.length === 0 && plan.killPids.length === 0) {
+      await syncKeepaliveAfterCleanup(workspaceId, {
+        deletedIds: [],
+        liveTunnelIds,
+        pruneMissing,
+        username,
+      });
+      return { ok: true, deleteIds: [], killPids: [], tunnelCount: tunnels.length };
+    }
+    await execCleanupWithRetry(
+      workspaceId,
+      buildDevbridgeCleanupApplyScript(plan),
+      username,
+      DEVBRIDGE_CLEANUP_TIMEOUT_MS,
+    );
+    await syncKeepaliveAfterCleanup(workspaceId, {
+      deletedIds: plan.deleteIds,
+      liveTunnelIds,
+      pruneMissing,
+      username,
+    });
+    return { ok: true, ...plan, tunnelCount: tunnels.length };
+  } finally {
+    try {
+      await execCleanupWithRetry(workspaceId, `rmdir ${DEVBRIDGE_LOCK_PATH} 2>/dev/null || true`, username, 30000);
+    } catch {}
+  }
+}
+
 // Expose a sandbox port to a public DevBridge tunnel URL. `port` MUST be the
 // ACTUAL port reported by deployNginx (deploy_nginx auto-increments on conflict),
 // otherwise the tunnel is bound to a dead port. Returns ok, publicUrl, port,
@@ -1869,6 +2225,7 @@ export async function exposeTunnel(
     keepalive,
     poolType,
     poolContext,
+    cleanupMode = 'stale',
     ensureDevbridgeKey,
     buildKeyringInjectScript,
     listKeysForQuotaHint,
@@ -1979,18 +2336,39 @@ export async function exposeTunnel(
     };
   }
 
+  // Selective pre-clean: remove same-port tunnels + orphan records/hosts only.
+  // Other ports and keepalive-protected tunnels are preserved.
+  const validatedCleanupMode = normalizeCleanupMode(cleanupMode);
+  try {
+    await cleanupDevbridgeTunnels(workspaceId, {
+      mode: validatedCleanupMode,
+      samePort: validatedPort,
+      username,
+    });
+  } catch {}
+
   let result = null;
   let attempt = 0;
-  const maxAttempts = 2;
+  let lastQuotaCleanup = null;
+  const maxAttempts = 4;
   while (attempt < maxAttempts) {
     attempt += 1;
     const exposeScript = buildDevbridgeExposeScript(validatedPort, validatedExpiryHours);
     result = await execOneShot(workspaceId, exposeScript, username, timeoutMs);
     const parsed = parseDevbridgeExposeOutput(result.stdout);
 
-    // 10006 quota exceeded: clean up stale tunnels and retry.
+    // 10006 quota exceeded: remove orphan tunnels first, then the oldest non-protected
+    // live tunnel (one per retry) until the new tunnel fits. Never touches keepalive keys.
     if (parsed.quotaError && attempt < maxAttempts) {
-      continue;
+      const quotaCleanup = await cleanupDevbridgeTunnels(workspaceId, {
+        mode: 'quota',
+        samePort: validatedPort,
+        maxExtra: 1,
+        username,
+      }).catch(() => null);
+      lastQuotaCleanup = quotaCleanup || lastQuotaCleanup;
+      // Kill-only progress frees no tunnel quota; only a deleted record can.
+      if (quotaCleanup?.deleteIds?.length) continue;
     }
     // Unreachable (000), migrated-gateway placeholder, or gateway-level tunnel errors
     // (404 "tunnel not found" / "port not configured"): one cleanup + rebuild retry.
@@ -2003,12 +2381,12 @@ export async function exposeTunnel(
     if (unreachable || migration || gatewayTunnelError || backendDown) {
       if (attempt === 1) {
         try {
-          await execOneShot(
-            workspaceId,
-            `pkill -f "devbridge host" 2>/dev/null || true; sleep 2; devbridge delete-all > /dev/null 2>&1 || true`,
+          // Only the same-port tunnel + orphans; other ports/sessions stay untouched.
+          await cleanupDevbridgeTunnels(workspaceId, {
+            mode: 'stale',
+            samePort: validatedPort,
             username,
-            20000,
-          );
+          });
         } catch {}
         continue;
       }
@@ -2029,8 +2407,20 @@ export async function exposeTunnel(
     }
 
     const warnings = [];
-    if (parsed.quotaError)
-      warnings.push('DevBridge tunnel quota (10006) hit — stale tunnels were cleaned up and the host was retried.');
+    if (parsed.quotaError && !parsed.tunnelUrl) {
+      return {
+        ok: false,
+        error:
+          'DevBridge tunnel quota exceeded (10006) after cleanup. Keepalive-protected tunnels are preserved; ' +
+          'remove unused tunnels or retry with cleanup_mode=all if a full reset is acceptable.',
+        error_code: 'devbridge_tunnel_quota_exceeded',
+        authMode: effectiveAuthMode,
+        attempts,
+        cleanup: lastQuotaCleanup || undefined,
+        warnings: 'tunnel quota (10006) still full after removing orphan/oldest non-protected tunnels',
+        hostLog: String(result.stdout || '').slice(0, 400),
+      };
+    }
 
     // #998: a host that never produced a Tunnel URL must NOT surface as ok:true
     // with an undefined publicUrl — that reads as success and sends the caller
@@ -2162,7 +2552,8 @@ export async function exposeTunnel(
         ? { sandboxLifetime: lifetimeNotice.sandboxLifetime, urlLifetimeHint: lifetimeNotice.urlLifetimeHint }
         : {}),
       tunnelId: parsed.tunnelId || undefined,
-      authMode,
+      // 报告最终生效的认证方式：自动创建兜底成功后应为 API_KEY_AUTO（而非首轮 probe 的 NO_CREDENTIAL）
+      authMode: effectiveAuthMode,
       httpCode: parsed.httpCode,
       verifyHttpCode: verifyHttpCode || undefined,
       verifyNotFound: verifyNotFound || undefined,

package/plugins/huaweicloud-core/src/tools.mjs

@@ -24,6 +24,7 @@ import {
   exposeTunnel,
   renewTunnel,
   installKeepaliveWatchdog,
+  cleanupDevbridgeTunnels,
   getCurrentWorkspaceId,
   setWorkspaceId,
 } from './sandbox/session-manager.mjs';
@@ -776,7 +777,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_expose_tunnel',
     description:
-      'Expose a port on the sandbox to a public DevBridge tunnel URL (devbridge 0.2.x). Authenticates automatically (probing AK/SK vs API-Key builds, using /tmp/hw_creds.sh and /tmp/hw_api_key as injected by huaweicloud_sandbox_credentials), pre-cleans stale tunnels to avoid quota errors, starts the host, extracts the public URL (https://<id>-<port>.devbridge-s2.hwtunnel.com), and health-checks it before returning. AUTO-ENROLLS the tunnel into the keepalive watchdog (host re-attach + daily 720h renewal + health check) by default, merged into existing coverage — pass keepalive:false to opt out. Use the ACTUAL port reported by huaweicloud_sandbox_deploy_nginx (its "port" field auto-increments on conflict) — never the originally requested port. Returns ok, publicUrl, port, tunnelId, keepalive.enrolled, warnings, sandboxLifetime and urlLifetimeHint. The urlLifetimeHint MUST be relayed to the developer together with the URL: the tunnel expiry is NOT the sandbox lifetime — an idle sandbox shuts down (ephemeral also auto-deletes), which kills the URL. If the API Key is missing on a release build it returns ok:false with instructions to create one.',
+      'Expose a port on the sandbox to a public DevBridge tunnel URL (devbridge 0.2.x). Authenticates automatically (keyring → auto-create → /tmp/hw_api_key), selectively cleans only same-port/orphan tunnels (cleanup_mode=stale, default — other ports, other sessions and keepalive-protected tunnels are preserved, except a tunnel bound to THIS port which is replaced), starts the host, extracts the public URL (https://<id>-<port>.devbridge-s2.hwtunnel.com), and health-checks it before returning. On 10006 quota it removes orphans first, then the oldest non-keepalive tunnel one at a time. AUTO-ENROLLS the tunnel into the keepalive watchdog (host re-attach + daily 720h renewal + health check) by default, merged into existing coverage — pass keepalive:false to opt out. Use the ACTUAL port reported by huaweicloud_sandbox_deploy_nginx (its "port" field auto-increments on conflict) — never the originally requested port. Returns ok, publicUrl, port, tunnelId, keepalive.enrolled, warnings, sandboxLifetime and urlLifetimeHint. The urlLifetimeHint MUST be relayed to the developer together with the URL: the tunnel expiry is NOT the sandbox lifetime — an idle sandbox shuts down (ephemeral also auto-deletes), which kills the URL. If the API Key is missing on a release build it returns ok:false with instructions to create one.',
     inputSchema: {
       type: 'object',
       required: ['port'],
@@ -796,6 +797,12 @@ export const TOOL_DEFINITIONS = [
           description:
             'Auto-enroll the tunnel into the keepalive watchdog (default true — every tunnel deployed to the sandbox must be keepalive-protected). Pass false only when the caller explicitly manages keepalive itself.',
         },
+        cleanup_mode: {
+          type: 'string',
+          enum: ['stale', 'all', 'none'],
+          description:
+            'Tunnel cleanup before exposing. stale (default): delete same-port tunnels + orphan records/hosts; preserve other ports, other sessions and keepalive-protected tunnels — except a tunnel bound to THIS port, which is always replaced. all: wipe every tunnel/host (manual reset only). none: no cleanup (a stale same-port host can then conflict).',
+        },
         workspace_id: {
           type: 'string',
           description:
@@ -1657,6 +1664,7 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
           port: args.port,
           expiryHours: args.expiry_hours,
           keepalive: args.keepalive,
+          cleanupMode: args.cleanup_mode,
           // DevBridge API Key 自动创建兜底（认证固定 apikey，AK/SK 已移除）
           poolType: exposePoolContext?.poolMode || 'ephemeral',
           poolContext: exposePoolContext,
@@ -1756,8 +1764,9 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
         // 池归属 + 生命周期口径缓存（服务端回显优先，缺失时客户端默认兜底）。
         // 双读兜底与 devStageId 同型（防服务端 wire 命名漂移，QA #1082 配对复审教训）
         rememberWorkspacePool(devStageId, connectResult?.pool_type || connectResult?.poolType, connectResult || {});
+        // 只清理孤儿隧道/宿主；保留其他端口、其他会话与 keepalive 名单内的隧道
         try {
-          await execOneShot(devStageId, 'devbridge delete-all 2>/dev/null || true', 'root', 15000);
+          await cleanupDevbridgeTunnels(devStageId, { mode: 'stale' });
         } catch {}
         try {
           await execWithSession(