huaweicloud-devkit 1.1.13-next.4 → 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.4",
+  "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.4",
+  "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.4",
+  "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.4",
+  "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.4",
+  "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.4",
+  "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.4",
+  "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

@@ -49,14 +49,14 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 ## 两池沙箱（pool_type）
 
-> 口径基调：一切以实测为准，口头支持不作数（下表生命周期为实测/平台侧现状，平台调参后本节随之更新）。
+> 口径基调：一切以实测为准，口头支持不作数（下表生命周期为实测/平台侧现状；数值为服务端配置下发的默认口径，平台调参以服务端回显为准）。
 
 `huaweicloud_sandbox_connect` 用 `pool_type` 选择资源池（服务端权威映射模板；**没有 persist_mode 参数**——上游参数面仅 template_id/flavor_id）：
 
-| pool_type           | 语义               | 生命周期（已实测）                                         | 适用                        |
-| ------------------- | ------------------ | ---------------------------------------------------------- | --------------------------- |
-| `ephemeral`（默认） | 非持久沙箱         | 闲置 30 分钟自动关机 + 闲置 1 小时自动删除（平台定时任务） | 临时运行/预览，勿存重要数据 |
-| `persistent`        | 持久沙箱（EVS 盘） | 数据跨关机保留；闲置回收保留期上限 7 天                    | 需要跨会话保留数据          |
+| pool_type           | 语义               | 生命周期（平台策略）                                         | 适用                        |
+| ------------------- | ------------------ | ------------------------------------------------------------ | --------------------------- |
+| `ephemeral`（默认） | 非持久沙箱         | 闲置 30 分钟自动关机 + 闲置 1 小时自动删除（平台定时任务）   | 临时运行/预览，勿存重要数据 |
+| `persistent`        | 持久沙箱（EVS 盘） | 数据跨关机保留；闲置 1 小时自动关机；闲置回收保留期上限 7 天 | 需要跨会话保留数据          |
 
 Selection rules（agent 按意图自动选池，开发者可覆盖；意图不明确时呈现两类供选择）：
 
@@ -70,8 +70,8 @@ Selection rules（agent 按意图自动选池，开发者可覆盖；意图不
 | 跨日评审 / 展示           | persistent | 评审者后续日期回访；实例保留        |
 
 - **配额**：每用户每类型 1 台（1+1 可并存）；同池 connect 自动复用已有实例
-- **429 双错误码**：`HDKIT_QUOTA_EXCEEDED`（账号配额满，重试无效→引导释放/复用）；`HDKIT_CAPACITY_INSUFFICIENT`（池容量不足→建议错峰重试）。响应带 `Retry-After`
-- **TTL 播报**：connect 与执行类工具返回值带池模式/生命周期提示——**ephemeral 池部署的公网地址会随沙箱闲置关机失效**，向开发者交付 URL 时必须附带该提示
+- **429 双错误码**：`HDKIT_QUOTA_EXCEEDED`（账号配额满，重试无效→引导释放/复用）；`HDKIT_CAPACITY_INSUFFICIENT`（池容量不足，服务端直接返回最终文案“DevKit 免费资源当前使用人数较多，建议您错峰使用，感谢理解！”，客户端不再附加引导）。响应带 `Retry-After`
+- **TTL 播报**：仅 connect（会话首次连接 / 复用被唤醒 `started=true`）与 expose_tunnel（交付地址时）返回生命周期提示；其余执行类工具不逐次播报。**ephemeral 池部署的公网地址会随沙箱闲置关机失效**，向开发者交付 URL 时必须转述 `urlLifetimeHint` / `warnings` 中的存活期提示（隧道有效期 ≠ 沙箱存活期）。数值以服务端回显为准，缺失时用默认口径兜底
 - **烧核播报口径**：沙箱运行消耗核时，播报用「平台赠送 + 活动赚取」口径（非直接计费）；账号核时耗尽（`HD.97520422`）时工具返回值给出友好引导
 - **删除纪律**：不向开发者暴露生命周期删除 API（回收走平台闲置策略 G1）；开发者主动删除时必须二次确认（确认要删除？数据不可恢复）；绝不做延后代删
 - 显式 `template_id` 优先于 `pool_type`（自定义模板场景）
@@ -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
    ```
@@ -212,7 +214,7 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
 
 8. **Execute commands**: use `huaweicloud_sandbox_exec_with_session` for interactive work (cd, env setup), or `huaweicloud_sandbox_exec_one_shot` for long-running builds/installs. See [Tool Selection Guide](#tool-selection-guide).
 9. **Upload project** (if deploying local code): `huaweicloud_sandbox_upload_project` to transfer a local project directory into `/workspace/<name>` — uses HTTP tunnel, much faster than base64 for multi-file projects. Use `huaweicloud_sandbox_upload_file` for single files.
-10. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
+10. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer. **Every URL handoff MUST include the sandbox-lifetime notice from `urlLifetimeHint` (or `warnings`)**: the address dies when the sandbox idles out (ephemeral: shutdown/delete; persistent: shutdown, data retained), and the tunnel expiry is not the sandbox lifetime
 
 ## File Transfer (local → sandbox)
 
@@ -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/skills/huawei-sandbox/references/resource-pool.md

@@ -13,23 +13,26 @@
 
 ## 两类沙箱
 
-| 维度     | 非持久化 (ephemeral)                    | 持久化 (persistent)                          |
-| -------- | --------------------------------------- | -------------------------------------------- |
-| 定位     | 预览/试用/一次性任务/敏感即焚           | 开发工作台/带数据库项目/跨日评审展示         |
-| 生命周期 | 闲置 30min 自动关机 + 1h 删除（已实测） | 闲置回收保留期上限 7 天（资源组 DB 硬约束）  |
-| 存储     | 无持久盘                                | 挂 EVS 32G                                   |
-| 配额     | 每用户 1 台（同类复用）                 | 每用户 1 台（同类复用；可与 1 台非持久并存） |
+| 维度     | 非持久化 (ephemeral)                    | 持久化 (persistent)                                                   |
+| -------- | --------------------------------------- | --------------------------------------------------------------------- |
+| 定位     | 预览/试用/一次性任务/敏感即焚           | 开发工作台/带数据库项目/跨日评审展示                                  |
+| 生命周期 | 闲置 30min 自动关机 + 1h 删除（已实测） | 闲置 1h 自动关机（实例与数据保留）；回收上限 7 天（资源组 DB 硬约束） |
+| 存储     | 无持久盘                                | 挂 EVS 32G                                                            |
+| 配额     | 每用户 1 台（同类复用）                 | 每用户 1 台（同类复用；可与 1 台非持久并存）                          |
 
 ## 生命周期（实测口径）
 
 | 项              | 口径                                           | 状态          |
 | --------------- | ---------------------------------------------- | ------------- |
 | 非持久闲置策略  | 30min 自动关机 + 1h 删除（平台定时任务）       | ✅ 已验证生效 |
+| 持久闲置策略    | 闲置 1h 自动关机（实例与数据盘保留）           | 平台侧        |
 | 持久闲置回收    | 保留期上限 7 天（原 14 天口径作废）            | 平台侧        |
 | 活性检测        | 当前仅 connect 单信号（三信号为后续诉求 G2）   | 现状          |
 | 删除/关机前通知 | 不支持（G6 诉求中）→ 客户端 TTL 播报为补偿方案 | 现状          |
 | 两池实际差异    | 仅 EVS 32GiB 数据盘（非持久池无 disks 字段）   | ✅ 已实证     |
 
+> 生命周期数值是**播报口径**，由 hdkitservice 配置（`POOL_EPHEMERAL_IDLE_SHUTDOWN_MINUTES` / `POOL_EPHEMERAL_IDLE_DELETE_MINUTES` / `POOL_PERSISTENT_IDLE_SHUTDOWN_MINUTES` / `POOL_PERSISTENT_RECLAIM_MINUTES`，统一以**分钟**为单位；7 天 = 10080）随 connect 响应回显；客户端以回显为准，缺失时按上表默认值兜底。实际关机/删除策略由平台资源池执行，hdkitservice 不控制。
+
 ## 容量规划（原始申请口径）
 
 | 资源              | 申请容量    |
@@ -47,7 +50,7 @@
 - 每用户每类型 1 台（同类复用，ephemeral + persistent 可并存 1+1）；账号并发上限 5
 - 429 双错误码（均带 `Retry-After: 60`）：
   - `HDKIT_QUOTA_EXCEEDED`：用户配额满（上游 `HD.98320022`）→ 重试无效，引导释放/复用已有实例
-  - `HDKIT_CAPACITY_INSUFFICIENT`：池容量不足（上游 `HD.99003001`/`HD.99008001`/`HD.98330021`）→ 建议错峰重试
+  - `HDKIT_CAPACITY_INSUFFICIENT`：池容量不足（上游 `HD.99003001`/`HD.99008001`/`HD.98330021`）→ 服务端直接返回最终文案“DevKit 免费资源当前使用人数较多，建议您错峰使用，感谢理解！”，客户端原样透传不再附加引导
 - 烧核：`HD.97520422` = 账号核心时长耗尽（沙箱运行消耗核时；客户端对含该码的错误输出友好播报）
 
 ## 烧核播报口径
@@ -57,8 +60,9 @@
 ## 客户端行为（本插件）
 
 - `sandbox_connect` 传 `pool_type`；非法值本地即报错（不发无效请求）；未传由服务端默认 ephemeral
-- connect 返回值富化 `pool` 块（TTL 播报，仅服务端回显 pool_type 时）；exec/upload/deploy/expose 返回值带 `poolMode`/`persistenceHint`
-- 429 结构化 `remediation`（配额满/容量不足差异化引导步骤）+ `retryAfter`
+- 生命周期提示只在两个时机播报：connect（会话首次连接，或复用实例被唤醒 `started=true`）与 `expose_tunnel`（交付地址时，返回 `urlLifetimeHint` + `warnings`）；其余 exec/upload/deploy 工具不逐次播报
+- connect 返回值富化 `pool` 块（数值取服务端回显，缺失时用默认口径）；生命周期口径按 workspace 缓存到 `~/.config/huaweicloud/sandbox-pools.json`（0600，7 天过期），进程重启后仍可播报
+- 429：配额满给 `remediation` 引导；容量不足只透传服务端最终文案 + `retryAfter`
 - 钉扎（可选，运维场景）：`HW_POOL_TEMPLATE_EPHEMERAL`/`HW_POOL_TEMPLATE_PERSISTENT` 环境变量——设置后客户端附带映射 template_id 上送；日常部署无需配置（模板 ID 由服务端权威维护）
 
 ## 平台侧关键依赖（G 清单，非 devkit 交付）

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

@@ -79,8 +79,9 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
         ],
       };
     }
-    // 429 双错误码结构化处理（两池配额契约）：配额满（用户侧，重试无效）与
-    // 池容量不足（平台侧，错峰重试）给出差异化引导；携带服务端 Retry-After
+    // 429 双错误码（两池配额契约）：配额满给出释放/复用引导；池容量不足只透传服务端
+    // 最终文案（“DevKit 免费资源当前使用人数较多，建议您错峰使用，感谢理解！”），
+    // 不再附加额外引导——该文案即最终展示内容。两者均携带服务端 Retry-After。
     if (code === 'HDKIT_QUOTA_EXCEEDED') {
       err.retryAfter = resp.headers.get('Retry-After') || undefined;
       err.remediation = {
@@ -94,13 +95,8 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
     }
     if (code === 'HDKIT_CAPACITY_INSUFFICIENT') {
       err.retryAfter = resp.headers.get('Retry-After') || undefined;
-      err.remediation = {
-        hint: '平台池容量暂时不足（非账号问题）：',
-        steps: [
-          '稍后错峰重试（devkit提供的免费资源紧张，建议错峰使用）',
-          '急需使用时可尝试另一 pool_type（另一池可能有余量）',
-        ],
-      };
+      // 该文案即最终展示内容（不带 "CODE: " 前缀、不附加引导）
+      err.message = data.message || err.message;
     }
     // 烧核播报（缺口#5 代码层）：账号核心时长耗尽——上游码 HD.97520422 经
     // hdkitservice 以 HDKIT_UPSTREAM_ERROR 包装透传，客户端按消息内错误码识别。

package/plugins/huaweicloud-core/src/sandbox/sandbox-pool.mjs

@@ -1,14 +1,35 @@
 // 两池沙箱（pool_type）客户端支持。
 // 机制（定稿）：池 = 平台预置模板，客户端传 pool_type（ephemeral/persistent），
 // 服务端权威映射 template_id；显式 template_id 优先（运维钉扎场景）。
-// - 非持久池（默认）：闲置 30min 自动关机 + 1h 删除（平台定时任务，已实测生效）
+// - 非持久池（默认）：闲置自动关机 + 自动删除（平台策略）
 // - 持久池：EVS 数据盘跨关机保留，闲置回收保留期上限 7 天
+// - 生命周期数值由 hdkitservice 配置回显（仅播报口径，实际策略由平台执行）
 // - 配额：每用户每类型 1 台（同类复用），账号并发上限 5
 
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
 const POOL_TYPES = new Set(['ephemeral', 'persistent']);
 
-/** workspaceId → poolType 缓存：exec/upload/deploy 等工具返回值据此附带池上下文 */
+/** 默认生命周期口径：与服务端默认一致；服务端回显优先，缺失时兜底 */
+export const DEFAULT_POOL_LIFECYCLE = {
+  ephemeral: { idleShutdownMinutes: 30, idleDeleteMinutes: 60, reclaimMinutes: null },
+  // 7 天 = 10080 分钟（与服务端一致，统一以分钟为单位）
+  persistent: { idleShutdownMinutes: 60, idleDeleteMinutes: null, reclaimMinutes: 7 * 24 * 60 },
+};
+
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** workspaceId → { poolType, lifecycle, updatedAt }：connect 回显后缓存 */
 const workspacePool = new Map();
+/** 本进程内已播报过 connect 提示的 workspace（会话级，不落盘） */
+const announcedWorkspaces = new Set();
+let cacheLoaded = false;
+
+function cachePath() {
+  return process.env.HW_SANDBOX_POOL_CACHE_PATH || join(homedir(), '.config', 'huaweicloud', 'sandbox-pools.json');
+}
 
 /**
  * 校验并归一化 pool_type；未传时返回 null（交由服务端默认 ephemeral，不在客户端伪造语义）。
@@ -20,7 +41,7 @@ export function validatePoolType(raw) {
   if (!POOL_TYPES.has(normalized)) {
     throw new Error(
       `invalid pool_type "${raw}" (expected ephemeral or persistent). ` +
-        'ephemeral = 非持久沙箱（闲置 30min 自动关机、1h 删除）；persistent = 持久沙箱（数据盘保留，闲置回收上限 7 天）',
+        'ephemeral = 非持久沙箱（闲置自动关机/删除）；persistent = 持久沙箱（数据盘保留，闲置回收上限 7 天）',
     );
   }
   return normalized;
@@ -37,68 +58,239 @@ export function pinnedTemplateFor(poolType) {
   return '';
 }
 
-/** 记录 workspace 的池归属（来自服务端 connect 响应的 pool_type 回显） */
-export function rememberWorkspacePool(workspaceId, poolType) {
-  if (workspaceId && poolType) workspacePool.set(workspaceId, poolType);
+function positiveNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : null;
 }
 
-/** 清理 workspace 池缓存（测试用） */
+/**
+ * 归一化生命周期口径：服务端字段（snake_case 官方契约）+ camelCase 双读兜底；
+ * 缺失/非法时回退客户端默认值（与服务端默认一致）。
+ */
+function normalizeLifecycle(poolType, raw = {}) {
+  const defaults = DEFAULT_POOL_LIFECYCLE[poolType];
+  if (!defaults) return null;
+  const pick = (...keys) => {
+    for (const key of keys) {
+      const value = positiveNumber(raw[key]);
+      if (value !== null) return value;
+    }
+    return null;
+  };
+  const idleShutdownMinutes =
+    pick('pool_idle_shutdown_minutes', 'poolIdleShutdownMinutes', 'idleShutdownMinutes') ??
+    defaults.idleShutdownMinutes;
+  const idleDeleteMinutes =
+    poolType === 'ephemeral'
+      ? (pick('pool_idle_delete_minutes', 'poolIdleDeleteMinutes', 'idleDeleteMinutes') ?? defaults.idleDeleteMinutes)
+      : null;
+  const reclaimMinutes =
+    poolType === 'persistent'
+      ? (pick('pool_reclaim_minutes', 'poolReclaimMinutes', 'reclaimMinutes') ?? defaults.reclaimMinutes)
+      : null;
+  return { idleShutdownMinutes, idleDeleteMinutes, reclaimMinutes };
+}
+
+function ensureCacheLoaded() {
+  if (cacheLoaded) return;
+  cacheLoaded = true;
+  try {
+    const raw = JSON.parse(readFileSync(cachePath(), 'utf8'));
+    const now = Date.now();
+    for (const [wsId, entry] of Object.entries(raw?.workspaces || {})) {
+      if (!entry || !POOL_TYPES.has(entry.poolType)) continue;
+      if (!Number.isFinite(entry.updatedAt) || now - entry.updatedAt > CACHE_TTL_MS) continue;
+      workspacePool.set(wsId, {
+        poolType: entry.poolType,
+        lifecycle: normalizeLifecycle(entry.poolType, entry.lifecycle || {}),
+        updatedAt: entry.updatedAt,
+      });
+    }
+  } catch {
+    // 首次使用 / 文件损坏：按空缓存处理
+  }
+}
+
+function persistCache() {
+  try {
+    ensureCacheLoaded();
+    const file = cachePath();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const workspaces = {};
+    for (const [wsId, entry] of workspacePool) workspaces[wsId] = entry;
+    const payload = JSON.stringify({ workspaces }, null, 2);
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, payload, { mode: 0o600 });
+    try {
+      renameSync(tmp, file);
+    } catch {
+      writeFileSync(file, payload, { mode: 0o600 });
+    }
+  } catch {
+    // 缓存失败不影响主流程（仅丢失跨进程提示能力）
+  }
+}
+
+/**
+ * 记录 workspace 的池归属与生命周期口径（来自服务端 connect 回显）。
+ * 无 pool_type 回显（自定义模板 / 老服务端）不记录，避免编造池语义。
+ */
+export function rememberWorkspacePool(workspaceId, poolType, lifecycleRaw) {
+  if (!workspaceId || !POOL_TYPES.has(poolType)) return;
+  workspacePool.set(workspaceId, {
+    poolType,
+    lifecycle: normalizeLifecycle(poolType, lifecycleRaw || {}),
+    updatedAt: Date.now(),
+  });
+  persistCache();
+}
+
+/** 清理 workspace 池缓存（测试用 / 会话关闭时） */
 export function forgetWorkspacePool(workspaceId) {
-  if (workspaceId === undefined) workspacePool.clear();
-  else workspacePool.delete(workspaceId);
+  if (workspaceId === undefined) {
+    workspacePool.clear();
+    announcedWorkspaces.clear();
+  } else {
+    workspacePool.delete(workspaceId);
+    announcedWorkspaces.delete(workspaceId);
+  }
+  persistCache();
 }
 
 /**
- * exec/upload/deploy 等工具返回值的池上下文（缺口#2 模式提示）。
- * 未记录池归属（老服务端/自定义模板）时返回 undefined，不附加任何字段。
+ * connect 生命周期提示的播报判定：会话首次 connect 播报；
+ * 复用实例被本次 connect 唤醒（started=true）时再次播报；其余复用静默。
+ */
+export function shouldAnnounceConnect(workspaceId, result = {}) {
+  const started = result.started === true || result.startedFromStopped === true;
+  if (!workspaceId) return true;
+  if (!announcedWorkspaces.has(workspaceId)) {
+    announcedWorkspaces.add(workspaceId);
+    return true;
+  }
+  return started;
+}
+
+/** 分钟数 → 中文口径（60 的整数倍显示为小时） */
+function formatMinutes(minutes, fallback) {
+  const n = Number(minutes) > 0 ? Number(minutes) : fallback;
+  if (n % 60 === 0 && n >= 60) return `${n / 60} 小时`;
+  return `${n} 分钟`;
+}
+
+/** 回收保留期：分钟 → 中文口径（1440 的整数倍显示为天） */
+function formatReclaim(minutes, fallback) {
+  const n = Number(minutes) > 0 ? Number(minutes) : fallback;
+  if (n % 1440 === 0 && n >= 1440) return `${n / 1440} 天`;
+  return `${n} 分钟`;
+}
+
+/**
+ * exec/upload/deploy 等工具的内部池上下文（不再默认并入工具返回，避免逐次刷屏）。
+ * expose_tunnel 用 poolLifecycle 生成交付地址提示；poolMode 用于 DevBridge key 分池。
  */
 export function poolContextFor(workspaceId) {
-  const poolType = workspacePool.get(workspaceId);
+  ensureCacheLoaded();
+  const entry = workspacePool.get(workspaceId);
+  if (!entry) return undefined;
+  const { poolType, lifecycle } = entry;
+  const shutdown = formatMinutes(lifecycle.idleShutdownMinutes, DEFAULT_POOL_LIFECYCLE[poolType].idleShutdownMinutes);
   if (poolType === 'ephemeral') {
+    const del = formatMinutes(lifecycle.idleDeleteMinutes, DEFAULT_POOL_LIFECYCLE.ephemeral.idleDeleteMinutes);
     return {
       poolMode: 'ephemeral',
-      persistenceHint: '非持久沙箱：闲置 30 分钟自动关机、1 小时自动删除，重要数据请及时保存或迁出',
+      poolLifecycle: { poolType, ...lifecycle },
+      persistenceHint: `非持久沙箱：闲置 ${shutdown}自动关机、${del}自动删除，重要数据请及时保存或迁出`,
     };
   }
-  if (poolType === 'persistent') {
+  const reclaim = formatReclaim(lifecycle.reclaimMinutes, DEFAULT_POOL_LIFECYCLE.persistent.reclaimMinutes);
+  return {
+    poolMode: 'persistent',
+    poolLifecycle: { poolType, ...lifecycle },
+    persistenceHint: `持久沙箱：闲置 ${shutdown}自动关机（数据盘保留）；闲置回收保留期最长 ${reclaim}`,
+  };
+}
+
+function buildConnectTtlHint(poolType, lifecycle) {
+  if (poolType === 'ephemeral') {
+    const shutdown = formatMinutes(lifecycle.idleShutdownMinutes, DEFAULT_POOL_LIFECYCLE.ephemeral.idleShutdownMinutes);
+    const del = formatMinutes(lifecycle.idleDeleteMinutes, DEFAULT_POOL_LIFECYCLE.ephemeral.idleDeleteMinutes);
     return {
-      poolMode: 'persistent',
-      persistenceHint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天',
+      lifecycle: `idle shutdown ${lifecycle.idleShutdownMinutes}min + auto-delete ${lifecycle.idleDeleteMinutes}min (platform policy)`,
+      ttl_hint: `非持久沙箱：闲置 ${shutdown}自动关机、${del}自动删除（平台策略）。重要数据请及时保存或迁出。`,
     };
   }
-  return undefined;
+  const shutdown = formatMinutes(lifecycle.idleShutdownMinutes, DEFAULT_POOL_LIFECYCLE.persistent.idleShutdownMinutes);
+  const reclaim = formatReclaim(lifecycle.reclaimMinutes, DEFAULT_POOL_LIFECYCLE.persistent.reclaimMinutes);
+  return {
+    lifecycle: `idle shutdown ${lifecycle.idleShutdownMinutes}min; EVS data disk retained; idle reclaim within ${lifecycle.reclaimMinutes}min max`,
+    ttl_hint: `持久沙箱：闲置 ${shutdown}自动关机（实例与数据盘保留，重新连接可继续使用）；闲置回收保留期最长 ${reclaim}，到期实例与数据将被删除，长期不用请自行导出。`,
+  };
 }
 
 /**
- * connect 结果池富化（缺口#1 TTL 播报）。
- * 仅当服务端回显 pool_type 才播报（两种状态制：服务端未确认池语义不编造）。
- * 钉扎/自定义模板（服务端回显 null）不播报。
- * 读取做 pool_type/poolType 双读兜底（与 devStageId 双读同型，防 wire 命名漂移）。
+ * connect 结果池富化（生命周期播报）。
+ * - 仅当服务端回显 pool_type 才生成提示（自定义模板不编造池语义）
+ * - announce=false 时不播报（会话内重复复用）
+ * - 数值以服务端回显为准，缺失时用客户端默认口径兜底
  */
-export function enrichConnectResult(result) {
+export function enrichConnectResult(result, options = {}) {
   if (!result || typeof result !== 'object') return result;
   const poolType = result.pool_type || result.poolType;
-  if (poolType === 'ephemeral') {
-    result.pool = {
-      pool_type: 'ephemeral',
-      lifecycle: 'idle 30min auto-shutdown + 1h auto-delete (platform scheduled task, verified)',
-      ttl_hint:
-        '非持久沙箱：闲置 30 分钟将自动关机、闲置 1 小时将自动删除（平台定时任务已生效）。' +
-        '重要数据请及时保存或迁出；需要跨会话保留数据请改用 pool_type=persistent。',
-    };
-  } else if (poolType === 'persistent') {
-    result.pool = {
-      pool_type: 'persistent',
-      lifecycle: 'EVS data disk retained; idle reclaim within 7 days max',
-      ttl_hint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天；长期不用请自行导出数据。',
-    };
+  const announce = options.announce !== false;
+  if (!announce || !POOL_TYPES.has(poolType)) {
+    delete result.pool;
+    return result;
   }
+  const lifecycle = normalizeLifecycle(poolType, result);
+  result.pool = {
+    pool_type: poolType,
+    ...buildConnectTtlHint(poolType, lifecycle),
+  };
   return result;
 }
 
-/** 池信息字段并入既有对象结果（非对象结果原样返回） */
-export function withPoolContext(workspaceId, result) {
-  const ctx = poolContextFor(workspaceId);
-  if (!ctx || !result || typeof result !== 'object') return result;
-  return { ...result, ...ctx };
+/**
+ * 交付公网地址时的沙箱存活期提示（expose_tunnel 专用）。
+ * 返回 undefined 表示池语义未知（自定义模板 / 无缓存），不编造提示。
+ */
+export function buildExposeLifetimeNotice(poolContext, expiryHours) {
+  const lifecycle = poolContext?.poolLifecycle;
+  if (!lifecycle) return undefined;
+  const poolType = lifecycle.poolType;
+  const tunnelHours = Number(expiryHours) > 0 ? Number(expiryHours) : 72;
+  if (poolType === 'ephemeral') {
+    const shutdown = formatMinutes(lifecycle.idleShutdownMinutes, DEFAULT_POOL_LIFECYCLE.ephemeral.idleShutdownMinutes);
+    const del = formatMinutes(lifecycle.idleDeleteMinutes, DEFAULT_POOL_LIFECYCLE.ephemeral.idleDeleteMinutes);
+    return {
+      sandboxLifetime: {
+        poolType,
+        idleShutdownMinutes: lifecycle.idleShutdownMinutes,
+        idleDeleteMinutes: lifecycle.idleDeleteMinutes,
+      },
+      urlLifetimeHint:
+        `该公网地址随沙箱存亡：非持久沙箱闲置 ${shutdown}自动关机（地址随即失效）、` +
+        `闲置 ${del}自动删除（地址与数据永久消失）。隧道有效期 ${tunnelHours} 小时不等于沙箱存活期；` +
+        '自动续期只保隧道，不能阻止沙箱关机。',
+      warning:
+        `URL 存活期提示：非持久沙箱闲置 ${shutdown}自动关机、${del}自动删除，此地址届时失效` +
+        `（隧道 ${tunnelHours} 小时有效期不等于沙箱存活期）`,
+    };
+  }
+  const shutdown = formatMinutes(lifecycle.idleShutdownMinutes, DEFAULT_POOL_LIFECYCLE.persistent.idleShutdownMinutes);
+  const reclaim = formatReclaim(lifecycle.reclaimMinutes, DEFAULT_POOL_LIFECYCLE.persistent.reclaimMinutes);
+  return {
+    sandboxLifetime: {
+      poolType,
+      idleShutdownMinutes: lifecycle.idleShutdownMinutes,
+      reclaimMinutes: lifecycle.reclaimMinutes,
+    },
+    urlLifetimeHint:
+      `该公网地址随沙箱存亡：持久沙箱闲置 ${shutdown}自动关机（地址失效，但实例与数据盘保留，` +
+      `重新连接沙箱后可重新暴露端口恢复访问）；闲置回收保留期最长 ${reclaim}，到期实例与数据将被删除。` +
+      `隧道有效期 ${tunnelHours} 小时不等于沙箱存活期；自动续期只保隧道，不能阻止沙箱关机。`,
+    warning:
+      `URL 存活期提示：持久沙箱闲置 ${shutdown}自动关机，此地址届时失效（实例与数据保留，` +
+      `重新连接后可恢复）；闲置回收上限 ${reclaim}`,
+  };
 }