huaweicloud-devkit 1.1.12-next.0 → 1.1.13-next.0

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.12-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.13-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **[中文](README.zh-CN.md) | English**
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.12-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.13-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **中文 | [English](README.md)**
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.12-next.0",
+  "version": "1.1.13-next.0",
   "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",
@@ -43,7 +43,7 @@
     "postinstall": "node ./bin/dsh-postinstall.cjs"
   },
   "dependencies": {
-    "undici": "^8.11.2"
+    "undici": "^8.12.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

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.12-next.0",
+  "version": "1.1.13-next.0",
   "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.12-next.0",
+  "version": "1.1.13-next.0",
   "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.12-next.0",
+  "version": "1.1.13-next.0",
   "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.12-next.0",
+  "version": "1.1.13-next.0",
   "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.12-next.0",
+  "version": "1.1.13-next.0",
   "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.12-next.0",
+  "version": "1.1.13-next.0",
   "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

@@ -1,6 +1,6 @@
 ---
 name: huawei-sandbox
-description: 'Use when creating, connecting, or managing Huawei Cloud Sandbox instances and workspace terminals, or when a task needs a temporary runtime to deploy, run, or preview a web application. Covers sandbox lifecycle (check-user, sign-agreement, connect, release), session-based terminal execution, and credential injection. Triggers on: sandbox, workspace, terminal, web app deployment, deploy web app, preview app, deploy github, github repo, deploy repo, website, static site, web application, hwlink, devstation, hdkitservice, remote exec. NOT for: ECS instances (use huawei-ecs), CCE clusters (use huawei-cce).'
+description: 'Use when creating, connecting, or managing Huawei Cloud Sandbox instances and workspace terminals, or when a task needs a temporary runtime to deploy, run, or preview a web application, backend service, or full-stack workbench. Covers sandbox lifecycle (check-user, sign-agreement, connect, release), session-based terminal execution, and credential injection. Triggers on: sandbox, workspace, terminal, web app deployment, deploy web app, preview app, deploy github, github repo, deploy repo, website, static site, web application, backend service, 工作台, workbench, full-stack, 全栈, CRUD 应用, database-backed REST API, PostgREST, postgres, hwlink, devstation, hdkitservice, remote exec. NOT for: ECS instances (use huawei-ecs), CCE clusters (use huawei-cce).'
 version: 1
 ---
 
@@ -27,6 +27,22 @@ Hard rules:
 - Include the OBS domain reminder and the ECS EIP pairing reminder in the options as presented.
 - After the choice: sandbox → continue with this skill; OBS → `huawei-obs`; ECS → `huawei-ecs` / `huawei-iac`; CCE → `huawei-cce`.
 
+## Stack-Selection Gate (MANDATORY — do not skip)
+
+When the request involves a **workbench / 工作台 / 全栈 / full-stack project** — front-end plus back-end, CRUD with persistence, or a database-backed app — you MUST treat it as a **full-stack workbench deployment**: the back end defaults to **PostgreSQL + PostgREST** even when the developer never mentions 数据库/postgres/CRUD. Do NOT silently fall through to the SPA/nginx-only path.
+
+Use the `question` tool to confirm the stack whenever the backend is ambiguous, presenting the PostgREST default first:
+
+1. **PostgreSQL + PostgREST 全栈 (recommended)** — schema + read-only `api_user` role, nginx `/api/` reverse proxy; the REST layer needs zero application code
+2. **应用自带后端** — the project ships its own server (Express/Next API/Nuxt server routes); deploy it inside the sandbox per its framework
+3. **纯静态/SPA** — no persistence; nginx-only
+
+Hard rules:
+
+- **NEVER infer or default the stack to SPA** when persistence is implied: 工作台/workbench/全栈/full-stack/CRUD/数据库/持久化 ⇒ full-stack (PostgREST default) unless the developer explicitly picks otherwise.
+- **Pre-code checkpoint (MANDATORY)**: before uploading or writing ANY application code, verify the backend choice matches this gate. If an SPA-only deployment already started and persistence turns out to be implied, STOP, tell the developer, and redirect to the full-stack path — do not paper over it with a bolted-on static backend.
+- After the choice: PostgREST → follow [Full-Stack: REST API over PostgreSQL](#full-stack-rest-api-over-postgresql-postgrest) **FIRST** (backend before any frontend code), then continue with the web deployment steps; 自带后端 / 纯静态 → continue with [Web Application Deployment](#web-application-deployment).
+
 ## Overview
 
 Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace terminal execution. Covers sandbox lifecycle via hdkitservice API and remote terminal command execution via hwlink protocol.
@@ -117,6 +133,8 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 **Step 0 — Target-Selection Gate (MANDATORY)**: before any sandbox lifecycle tool, confirm the target. If the developer asked to deploy/host/publish a site without naming a target, STOP and run the [Target-Selection Gate](#target-selection-gate-mandatory--do-not-skip) first; do NOT call `huaweicloud_sandbox_connect` until it is resolved. Proceed with this workflow only if the target is already confirmed as sandbox (or a temporary runtime).
 
+**Step 0.5 — Stack-Selection Gate (MANDATORY)**: before uploading or writing any application code, confirm the backend stack via the [Stack-Selection Gate](#stack-selection-gate-mandatory--do-not-skip). 工作台/workbench/全栈/full-stack/CRUD/持久化 ⇒ full-stack (PostgreSQL + PostgREST default) — do NOT start an SPA-only deployment for a workbench request.
+
 Setup is a **plugin-side preflight** — the developer should be asked a question only once, when the agreement actually needs signing:
 
 1. **Check user** (transparent): `huaweicloud_sandbox_check_user` — returns `realnameVerified`/`agreementSigned` (200) when all good, OR throws a 403 error with one of these codes:
@@ -462,13 +480,13 @@ When deploying a **full-stack workbench project** (前后端工作台) or asking
 3. **Nginx single-origin** — `/` serves the frontend, `/api/` reverse-proxies to PostgREST (no CORS, same origin). The frontend dir needs `chmod o+x` on the whole path chain or nginx returns 403.
 4. **Expose + keep alive (automatic)** — `huaweicloud_sandbox_expose_tunnel` with the nginx port; it AUTO-enrolls the tunnel into the keepalive watchdog (merged into existing coverage). Prefer `expiry_hours: 720` for long-lived workbench deployments.
 
-Complete measured procedure (with the full command chain): see `references/fullstack-postgrest.md`.
+Complete measured procedure (full command chain) plus the 2026-10 field notes (Aliyun mirror URLs, cross-mirror resume corruption, `upload_file` 640 → PGRST002, exec-channel escaping → upload files and run `psql -f` / `curl -d @file`): see `references/fullstack-postgrest.md`. For the sandbox restart recovery checklist (what survives on `/workspace` vs what is lost on the 系统盘, plus the write-GRANT rollback trap): see the `Sandbox Restart Recovery Checklist` section in the same file.
 
 ## Web Application Deployment
 
 When deploying a web application to the sandbox, build the app inside the sandbox before exposing it. Source code is uploaded, dependencies installed, and the framework built in the sandbox environment.
 
-**Backend present?** If the project includes a PostgreSQL + PostgREST backend (or the developer asks for one), set up the backend FIRST by following [Full-Stack: REST API over PostgreSQL](#full-stack-rest-api-over-postgresql-postgrest) — install PostgreSQL/PostgREST, create the schema, and point the frontend's nginx `/api/` location at PostgREST — then continue with the steps below. Every tunnel exposed afterwards is auto-enrolled into the keepalive watchdog.
+**Backend selection (Stack-Selection Gate)**: the backend choice was already confirmed by the [Stack-Selection Gate](#stack-selection-gate-mandatory--do-not-skip) before any code was uploaded. If the project includes a PostgreSQL + PostgREST backend (or the developer asked for one), set up the backend FIRST by following [Full-Stack: REST API over PostgreSQL](#full-stack-rest-api-over-postgresql-postgrest) — install PostgreSQL/PostgREST, create the schema, and point the frontend's nginx `/api/` location at PostgREST — then continue with the steps below. Every tunnel exposed afterwards is auto-enrolled into the keepalive watchdog.
 
 **沙箱无 systemd（实测 #935 报告3 问题3）**：沙箱为无 systemd 的容器环境，`systemctl` 全部失效（`System has not been booted with systemd`）—— 不要用 `systemctl start/reload/restart nginx`。Nginx 配置变更直接使用 `nginx -t` 验证 + `nginx -s reload` 热加载，或直接执行 nginx 二进制（`sudo nginx` 启动 / `nginx -s stop` 停止）。`huaweicloud_sandbox_deploy_nginx` 工具返回的 nextStep 文案与该语义一致（配置写入后自动回验存在性与 `nginx -t`，通过后即生效，无需 systemctl）。
 

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

@@ -25,10 +25,12 @@ 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.
+# Use the Aliyun mirror: download.postgresql.org / repo.almalinux.org measure ~8KB/s from
+# sandbox CN egress (a 6.8MB server RPM times out inside 240s); the mirror returns in seconds.
 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/
+name=PostgreSQL 16 for RHEL8 aarch64 (Aliyun mirror)
+baseurl=https://mirrors.aliyun.com/postgresql/repos/yum/16/redhat/rhel-8-aarch64/
 enabled=1
 gpgcheck=0
 PGDG_EOF
@@ -39,10 +41,13 @@ 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.
+# Aliyun mirror (measured 2026-10: seconds per RPM vs ~8KB/s timeouts on the official source).
+# Download with resume (--max-time + -C -) WITHIN THE SAME MIRROR only: a partial file
+# resumed from a DIFFERENT mirror fails rpm verification ("Payload SHA256 digest: BAD") —
+# when switching sources, rm the partial file and re-download in full (see field notes).
+# A corrupt RPM also ABORTS the whole transaction, silently skipping the other RPMs in the
+# same rpm -ivh call. Install one RPM per call.
+BASE="https://mirrors.aliyun.com/postgresql/repos/yum/16/redhat/rhel-8-aarch64"
 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
@@ -56,9 +61,10 @@ 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):
+# Install the REAL el8 libicu60 (different sonames, coexists with HCE's icu69);
+# AlmaLinux official repo is also ~8KB/s from the sandbox — use the Aliyun mirror:
 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
+  "https://mirrors.aliyun.com/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.
@@ -72,12 +78,16 @@ 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):
+Init and start (PG refuses root; no systemd on HCE). **The data directory
+MUST live on the data disk** (`/workspace`), not `/var/lib/pgsql` —
+`/var/lib/pgsql` is on the 系统盘 (system disk) and a sandbox reboot rolls it
+back to the image state, destroying all databases. `/workspace` is the data
+disk and survives reboots (#999):
 
 ```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"
+mkdir -p /workspace/pgsql/16/data && chown postgres:postgres /workspace/pgsql/16/data
+su - postgres -c "/usr/pgsql-16/bin/initdb -D /workspace/pgsql/16/data"
+su - postgres -c "/usr/pgsql-16/bin/pg_ctl -D /workspace/pgsql/16/data -l /workspace/pgsql/16/logfile start"
 ```
 
 ## Step 2: PostgREST (static build) + schema
@@ -87,8 +97,30 @@ 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
+# Asset name has NO patch version: it is postgrest-v16.5-linux-static-aarch64.tar.xz
+# (v16.4 likewise) — writing "v16.5.0" 404s and is easily misdiagnosed as a broken proxy.
+# Verify the real asset name via the GitHub API before downloading:
+curl -fsSL https://api.github.com/repos/PostgREST/postgrest/releases \
+  | grep -o '"name": *"postgrest-v16[^"]*aarch64[^"]*"'
+# GitHub direct is slow from the sandbox; prefix proxies measure ~500KB/s (2026-10):
+#   https://ghfast.top/https://github.com/...   or   https://gh-proxy.com/https://github.com/...
+# ⚠️ Those proxies are THIRD-PARTY: never extract their bytes unverified (supply-chain
+# risk). Pull the official asset sha256 digest from the GitHub releases API, download
+# through the proxy, and verify with sha256sum BEFORE extracting — this also catches
+# partial downloads (a truncated tar.xz fails the check instead of a cryptic tar error).
+PGRST_SHA256="$(curl -fsSL https://api.github.com/repos/PostgREST/postgrest/releases/tags/v16.5 \
+  | grep -A30 '"name": *"postgrest-v16.5-linux-static-aarch64.tar.xz"' \
+  | grep -o '"digest": *"sha256:[a-f0-9]*"' | head -1 \
+  | sed 's/.*sha256://; s/"$//')"
+# ⚠️ The sed strips both the `sha256:` prefix and the closing quote.
+# Using `cut` by delimiter instead would leave a trailing double-quote on the
+# hash, making `sha256sum -c -` fail with "no properly formatted checksum
+# lines found" even when the download is correct.
+test -n "$PGRST_SHA256"   # empty digest = API lookup failed; do NOT proceed unverified
+curl -fsSL --http1.1 --max-time 240 -C - -o /tmp/pgrst.tar.xz \
+  "https://ghfast.top/https://github.com/PostgREST/postgrest/releases/download/v16.5/postgrest-v16.5-linux-static-aarch64.tar.xz"
+echo "$PGRST_SHA256  /tmp/pgrst.tar.xz" | sha256sum -c -   # must print ": OK" before tar
+mkdir -p /opt/postgrest && tar -xJf /tmp/pgrst.tar.xz -C /opt/postgrest
 
 cat > /opt/postgrest/pgrst.conf << 'PGRST_EOF'
 db-uri = "postgres://api_user:<db-password>@localhost:5432/postgres"
@@ -97,8 +129,11 @@ db-anon-role = "api_user"
 server-host = "127.0.0.1"
 server-port = 3000
 PGRST_EOF
+# ⚠️ Via the MCP exec channel, do NOT build pgrst.conf / SQL inline (escaping breaks
+# them — see field notes below): write the file locally and huaweicloud_sandbox_upload_file it.
 
-# Schema + read-only API role (the anon role gates all writes)
+# Schema + read-only API role (the anon role gates all writes).
+# Same escaping trap: prefer a local schema.sql → upload_file → psql -f (field notes).
 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 &
@@ -145,5 +180,131 @@ devbridge host -p <port> -e 720
 ```
 
 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).
+(data, 200), `POST /api/todos` (**401 by default** — the anon role has SELECT
+only). To enable writes on one table, `GRANT INSERT ON api.todos TO api_user`
+(never a broad grant to anon); after that targeted grant the same POST returns
+**201**.
+
+## Field notes (2026-10 retest): 5 measured traps
+
+Re-measured 2026-10-23 on HCE 2.0 (aarch64, no systemd) with PG 16.15 +
+PostgREST 16.5; all five traps reproduced and solved, end-to-end verified
+(page 200 / API 200 / POST 401 anon-default, 201 after `GRANT INSERT` on
+`api.todos`).
+
+### 1. RPM sources: use the Aliyun mirror
+
+`download.postgresql.org` and `repo.almalinux.org` measure **~8KB/s** from the
+sandbox CN egress (the 6.8MB server RPM times out mid-transfer at 240s). The
+Aliyun mirror completes in seconds:
+
+- PG 16: `https://mirrors.aliyun.com/postgresql/repos/yum/16/redhat/rhel-8-aarch64/`
+- libicu60: `https://mirrors.aliyun.com/almalinux/8/BaseOS/aarch64/os/Packages/`
+- PostgREST: `ghfast.top` / `gh-proxy.com` prefix proxies (~500KB/s) — but see
+  trap 3 first: the asset name must be exact, and the proxy is third-party:
+  fetch the official GitHub asset digest and `sha256sum -c` the tarball before
+  extracting (see the Step 2 download block).
+
+### 2. Cross-mirror resume corrupts RPMs
+
+Resuming a partial download with `-C -` **from a different mirror** produces a
+file that fails rpm verification (`Payload SHA256 digest: BAD`). When switching
+sources, `rm` the partial file and re-download it in full — never resume across
+mirrors.
+
+### 3. PostgREST 404 is usually the asset name, not the proxy
+
+The release asset is `postgrest-v16.5-linux-static-aarch64.tar.xz` — the version
+has **no patch number** (v16.4 likewise); guessing `v16.5.0` returns 404 and
+gets misdiagnosed as "proxy broken". Check the real name first:
+
+```bash
+curl -fsSL https://api.github.com/repos/PostgREST/postgrest/releases \
+  | grep -o '"name": *"postgrest-v16[^"]*aarch64[^"]*"'
+```
+
+### 4. `upload_file` lands as 640 → silent schema failure → PGRST002
+
+Files uploaded by root via `huaweicloud_sandbox_upload_file` arrive as
+`rw-r-----` (640). `su - postgres -c "psql -f /tmp/schema.sql"` then fails with
+`Permission denied`, the schema/role are **silently not created**, and
+PostgREST starts but keeps logging
+`PGRST002: Could not query the database for the schema cache`.
+
+Fix: `chmod o+r` the uploaded file before `psql -f`. When troubleshooting
+PGRST002, first confirm the schema/role actually exist (`\dn`, `\du`) — the
+`psql -f` error may have scrolled out of the output tail you looked at.
+
+### 5. MCP exec channel mangles nested quotes — upload files instead
+
+Nested quotes / inline JSON (pgrst.conf, `psql -c` SQL, `curl -d '{...}'`) get
+corrupted by the exec channel's multi-layer escaping (symptoms: POST 400, SQL
+written wrong). The heredoc/inline `printf` snippets above are for a direct
+shell; over MCP, always use the file-upload pattern:
+
+```bash
+# locally: write schema.sql / pgrst.conf / payload.json, then upload_file them, then on the sandbox:
+chmod o+r /tmp/schema.sql && su - postgres -c "/usr/pgsql-16/bin/psql -f /tmp/schema.sql"
+curl -s -X POST -H "Content-Type: application/json" -d @/tmp/payload.json http://127.0.0.1:3000/todos
+```
+
+## Sandbox Restart Recovery Checklist (2026-10)
+
+A sandbox reboot rolls the **系统盘 (system disk)** back to the image state —
+everything installed under `/`, `/usr`, `/etc`, `$HOME` is lost. Only
+`/workspace` (the data disk) survives. Below is the measured recovery
+checklist, assuming PG data was initialized on `/workspace/pgsql/16/data` per
+Step 1 above.
+
+### Lost on reboot (系统盘 — must rebuild)
+
+| Component              | Location                  | Recovery action                                                                  |
+| ---------------------- | ------------------------- | -------------------------------------------------------------------------------- |
+| PostgreSQL 16 RPMs     | `/usr/pgsql-16/`          | Re-run the Step 1 `rpm -ivh --nodeps` block                                      |
+| Soname shims           | `/usr/lib64/lib*.so.*`    | Re-run the Step 1 symlink + `ldconfig` block                                     |
+| `postgres` user        | `/etc/passwd` entry       | `useradd -r -m postgres` then `chown postgres:postgres /workspace/pgsql/16/data` |
+| PostgREST binary       | `/opt/postgrest/`         | Re-download + sha256-verify + extract (Step 2)                                   |
+| pgrst.conf             | `/opt/postgrest/`         | Re-upload via `huaweicloud_sandbox_upload_file`                                  |
+| nginx config           | `/etc/nginx/conf.d/`      | Re-create via `huaweicloud_sandbox_deploy_nginx`                                 |
+| DevBridge 0.2.x binary | `~/.huawei/bin/` (系统盘) | Re-install to `/workspace/.local/bin` (see #999)                                 |
+| DevBridge tunnel       | in-memory                 | Re-run `huaweicloud_sandbox_expose_tunnel`                                       |
+| `/tmp` credentials     | `/tmp/hw_creds.sh` etc.   | Re-run `huaweicloud_sandbox_credentials`                                         |
+
+### Survives reboot (/workspace — no rebuild needed)
+
+| Component              | Location                   | Notes                                        |
+| ---------------------- | -------------------------- | -------------------------------------------- |
+| Frontend pages         | `/workspace/<repo>/`       | Uploaded project persists                    |
+| PG data directory      | `/workspace/pgsql/16/data` | Schema, roles, tables, seed data ALL survive |
+| DevBridge 0.2.x binary | `/workspace/.local/bin/`   | If installed per #999 guidance               |
+
+Because PG data lives on `/workspace`, a restart does **NOT** require rebuilding
+the schema (`schema.sql`) or re-seeding data — `initdb` is also unnecessary.
+Only the PG server RPMs and the `postgres` user need rebuilding; then
+`pg_ctl -D /workspace/pgsql/16/data start` resumes the surviving cluster
+immediately.
+
+### Write-permission GRANT rollback trap (POST 401 → GRANT → 201)
+
+The `postgres` system user and PG RPMs live on the 系统盘, so after a reboot
+you must recreate the user and re-install PG before `pg_ctl` can start the
+surviving data directory. Once PG starts against the surviving
+`/workspace/pgsql/16/data`, all roles and grants in the PG catalog are intact
+— no re-grant is needed.
+
+**However**, if you rebuild the schema from a `schema.sql` that only contains
+`GRANT SELECT` (the read-only anon default), writes are blocked: `POST
+/api/todos` returns **401**. The write grant (`GRANT INSERT, UPDATE, DELETE`)
+was stored in the PG catalog; re-running a SELECT-only script overwrites it.
+The measured fix (2026-10):
+
+```sql
+GRANT INSERT, UPDATE, DELETE ON api.todos TO api_user;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA api TO api_user;
+```
+
+After this targeted re-grant the same `POST /api/todos` returns **201**
+(measured 2026-10: POST 401 → `GRANT INSERT, UPDATE, DELETE` → POST 201).
+This mirrors the Step 4 anon-role gating: `db-anon-role` is read-only by
+default; targeted write grants must be re-applied after any schema rebuild.
+Never grant broad write access to the anon role.

package/plugins/huaweicloud-core/src/mcp-protocol.mjs

@@ -1,8 +1,12 @@
 import { TOOL_DEFINITIONS, callTool } from './tools.mjs';
 import { peekCachedUpdateInfo, applyUpdateHint, readInstalledVersion } from './update-check.mjs';
-import { initTelemetry } from './telemetry/telemetry.mjs';
+import { initTelemetry, flushEvents } from './telemetry/telemetry.mjs';
 import { detectAgent } from './telemetry/agent-detect.mjs';
 
+// #1014 P0: 领券类工具同步上报——callTool 完毕后 await flushEvents()，
+// 防止进程提前退出导致领券遥测丢失。
+const P0_SYNC_FLUSH_TOOLS = new Set(['huaweicloud_voucher_claim', 'huaweicloud_competition_voucher_claim']);
+
 const pkgVersion = readInstalledVersion() || '0.0.0';
 
 // 会话内首个非 check/upgrade 工具调用附加 _updateInfo，只消费一次。
@@ -78,6 +82,9 @@ export async function dispatch(method, params, opts = {}) {
       throw invalidParamsError;
     }
     const result = await callTool(params.name, params.arguments || {});
+    if (P0_SYNC_FLUSH_TOOLS.has(params.name)) {
+      await flushEvents().catch(() => {});
+    }
     const decorated = _decorateResult(sessionId, params.name, result);
     return {
       content: [

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

@@ -1,6 +1,7 @@
 import { getCredentials } from './hwlink-api.mjs';
 import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
 import { cacheUserHash } from '../telemetry/telemetry.mjs';
+import { detectAgent } from '../telemetry/agent-detect.mjs';
 import { readInstalledVersion } from '../update-check.mjs';
 
 function getHdkitBaseUrl() {
@@ -21,6 +22,8 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
     'X-HW-AK': ak,
     'X-HW-SK': sk,
     'X-HW-Client-Version': readInstalledVersion() || '0.0.0',
+    // #1040: 对外请求统一携带 X-HW-Agent（值=detectAgent 结果 harness）
+    'X-HW-Agent': detectAgent().harness,
   };
   if (securitytoken) {
     headers['X-HW-Security-Token'] = securitytoken;

package/plugins/huaweicloud-core/src/setup-cli.mjs

@@ -75,6 +75,13 @@ function configRoot(target = 'opencode') {
   return join(home, '.config', target);
 }
 
+// Must match telemetry.mjs GLOBAL_TELEMETRY_DIR root: HUAWEICLOUD_DEVKIT_HOME
+// overrides homedir() so sandbox/multi-HOME environments stay consistent (#1014).
+function devkitTelemetryDir() {
+  const home = (process.env.HUAWEICLOUD_DEVKIT_HOME || '').trim() || homedir();
+  return join(home, '.huaweicloud-devkit', 'telemetry');
+}
+
 function opencodeSkillsDir() {
   return join(configRoot('opencode'), 'skills');
 }
@@ -1814,7 +1821,7 @@ function deployWorkBuddyHooks() {
 
   // 4. Ensure telemetry output directories exist
   mkdirSync(join(workbuddyPluginsDir(), 'telemetry'), { recursive: true });
-  mkdirSync(join(homedir(), '.huaweicloud-devkit', 'telemetry'), { recursive: true });
+  mkdirSync(devkitTelemetryDir(), { recursive: true });
 }
 
 // ── AtomCode hooks deployment ────────────────────────────────
@@ -1982,10 +1989,10 @@ function uninstallWorkBuddy() {
     console.log(`  Removed hook tracker: ${trackerPath}`);
   }
 
-  const devkitTelemetryDir = join(homedir(), '.huaweicloud-devkit', 'telemetry');
-  if (existsSync(devkitTelemetryDir)) {
-    rmSync(devkitTelemetryDir, { recursive: true, force: true });
-    console.log(`  Removed telemetry cache: ${devkitTelemetryDir}`);
+  const devkitTelemetryPath = devkitTelemetryDir();
+  if (existsSync(devkitTelemetryPath)) {
+    rmSync(devkitTelemetryPath, { recursive: true, force: true });
+    console.log(`  Removed telemetry cache: ${devkitTelemetryPath}`);
   }
 }
 

package/plugins/huaweicloud-core/src/telemetry/agent-detect.mjs

@@ -1,24 +1,31 @@
-import { AGENTS, matchAgent, detectVersion, installSegment } from './agent-registry.mjs';
+import { AGENTS, matchAgent, detectVersion } from './agent-registry.mjs';
 
 /**
- * 仅返回 harness 字符串（或 null），不返回 version。
- * 用于简单场景（如 keepalive 判断、测试断言）。
+ * 仅返回 harness 字符串，不返回 version。
+ * #1040: 白名单 / AGENT_HARNESS 未命中时一律返回 'unknown'——
+ * 不再透传 clientInfo.name（startup、voucher-claim*、test* 等探针类 clientName 同样归 unknown），
+ * 也不拼接 installSegment，避免 agent 名出现 '|' 污染。
  */
 export function detectAgentHarness(clientInfo = {}) {
-  if (process.env.AGENT_HARNESS) return process.env.AGENT_HARNESS;
+  const envHarness = process.env.AGENT_HARNESS;
+  if (envHarness && AGENTS.some((a) => a.id === envHarness)) return envHarness;
   for (const agent of AGENTS) {
     if (matchAgent(agent, clientInfo)) return agent.id;
   }
-  return clientInfo.name || null;
+  return 'unknown';
 }
 
 export function detectAgent(clientInfo = {}) {
-  if (process.env.AGENT_HARNESS) {
-    const cfg = AGENTS.find((a) => a.id === process.env.AGENT_HARNESS) || null;
-    return {
-      harness: process.env.AGENT_HARNESS,
-      version: detectVersion(cfg ? cfg.version : null) || clientInfo.version || '0.0.0',
-    };
+  // AGENT_HARNESS 仅在命中白名单时生效；未命中视为不可信输入，不透传任意环境值。
+  const envHarness = process.env.AGENT_HARNESS;
+  if (envHarness) {
+    const cfg = AGENTS.find((a) => a.id === envHarness) || null;
+    if (cfg) {
+      return {
+        harness: envHarness,
+        version: detectVersion(cfg.version) || clientInfo.version || '0.0.0',
+      };
+    }
   }
 
   for (const agent of AGENTS) {
@@ -30,11 +37,9 @@ export function detectAgent(clientInfo = {}) {
     }
   }
 
-  const seg = installSegment();
-  const base = clientInfo.name || 'unknown';
-  const harness = seg ? `${base}|${seg}` : base;
+  // #1040: 兜底收敛 'unknown'——安装位置信息走遥测独立字段 installSegment，不进入 agent 名。
   return {
-    harness: harness.length > 32 ? harness.slice(0, 32) : harness,
+    harness: 'unknown',
     version: clientInfo.version || '0.0.0',
   };
 }

package/plugins/huaweicloud-core/src/telemetry/agent-registry.mjs

@@ -10,6 +10,10 @@ const selfPath = (() => {
   }
 })();
 
+/**
+ * #1040: 安装位置段——仅用于遥测的独立安装位置字段（telemetry 事件 installSegment），
+ * 不进入 agent 名/harness；AGENTS 白名单与 matchAgent 规则不受安装位置影响。
+ */
 export function installSegment() {
   const parts = selfPath.split('/').filter(Boolean);
   const srcIdx = parts.lastIndexOf('src');

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

@@ -14,6 +14,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { fetchWithProxy } from '../proxy/proxy-agent.mjs';
+import { installSegment } from './agent-registry.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -68,7 +69,7 @@ const MAX_RETRIES = 3;
 const DEFAULT_ENDPOINT = 'https://devkit.huaweicloud.com/rest/developer/server/hdkitservice/telemetry/events';
 
 let eventQueue = [];
-let isFlushing = false;
+let currentFlush = null;
 let flushTimer = null;
 let lastCheckedDate = '';
 let installId = null;
@@ -207,6 +208,9 @@ function buildEvent(raw) {
     os: osTypeStr,
     osVersion: osVersionStr,
   };
+  // #1040: 安装位置独立字段——原拼接进 harness 的 installSegment 改为单列上报。
+  const seg = installSegment();
+  if (seg) event.installSegment = sanitizeValue(seg);
   const cap = raw.capability || capabilityFromKey(raw.key);
   if (cap) event.capability = cap;
   return event;
@@ -214,7 +218,9 @@ function buildEvent(raw) {
 
 export function enqueueEvent(raw) {
   if (!isTelemetryEnabled()) return;
-  if (!installId) return;
+  // #1014: installId 未初始化时（如未走 initialize 直接 tools/call）不再丢弃事件，
+  // 惰性恢复，避免 telemetry_event 缺记录。
+  if (!installId) installId = generateOrRecoverInstallId();
 
   ingestHookEvents();
 
@@ -324,10 +330,37 @@ export function clearUserHash() {
   } catch {}
 }
 
-function flushEvents() {
-  if (isFlushing) return;
-  if (eventQueue.length === 0) return;
-  isFlushing = true;
+// #1014: flush 前兜底补齐队列事件的缺失身份字段——
+// userHash 在 enqueue 之后才解析到（领券响应 / user-hash 文件）时，
+// 已入队事件的 userHash 仍为 null，这里统一回填，降低 user_hash null 占比。
+function backfillIdentityFields() {
+  try {
+    if (!installId) installId = generateOrRecoverInstallId();
+    if (!userHash) loadUserHash();
+    for (const event of eventQueue) {
+      if (!event.installId && installId) event.installId = installId;
+      if (event.userHash == null && userHash) event.userHash = userHash;
+    }
+  } catch (_) {
+    debugLog('BACKFILL identity fields failed');
+  }
+}
+
+// #1014: flush 可被 await（P0 领券类工具同步上报）；
+// 并发调用复用同一次 in-flight flush（currentFlush 声明于模块顶部）。
+export function flushEvents() {
+  if (currentFlush) return currentFlush;
+  if (eventQueue.length === 0) return Promise.resolve();
+  currentFlush = performFlush().finally(() => {
+    currentFlush = null;
+  });
+  return currentFlush;
+}
+
+async function performFlush() {
+  // flush 前统一回填身份字段（含 userHash 重解析，#1014）：
+  // 入队时身份未解析的事件此前会永久携带 null userHash。
+  backfillIdentityFields();
 
   const batch = eventQueue.splice(0, BATCH_SIZE);
   const keys = batch.map((e) => e.key).join(',');
@@ -339,34 +372,72 @@ function flushEvents() {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
 
-  fetchWithProxy(endpoint, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(batch.map(({ _retries, ...rest }) => rest)),
-    signal: controller.signal,
-  })
-    .then((resp) => {
-      clearTimeout(timer);
-      debugLog(`POST status=${resp.status} events=${batch.length}`);
-      if (resp.ok) {
-        for (const event of batch) {
-          if (event.key === 'dau:active_today') touchFile(dauStampPath());
-          if (event.key === 'plugin:install') touchFile(installStampPath());
-          if (event.key === 'plugin:first_use') touchFile(firstUseStampPath());
-        }
-      } else if (resp.status >= 400 && resp.status < 500) {
-        debugLog(`POST status=${resp.status} dropping ${batch.length} events (client error)`);
-      } else {
-        requeueEvents(batch);
+  try {
+    const resp = await fetchWithProxy(endpoint, {
+      method: 'POST',
+      // #1040: 对外上报统一携带 X-HW-Agent（值=detectAgent 结果 harness，initTelemetry 缓存）
+      headers: { 'Content-Type': 'application/json', 'X-HW-Agent': agentHarness || 'unknown' },
+      body: JSON.stringify(batch.map(({ _retries, ...rest }) => rest)),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    debugLog(`POST status=${resp.status} events=${batch.length}`);
+    if (resp.ok) {
+      for (const event of batch) {
+        if (event.key === 'dau:active_today') touchFile(dauStampPath());
+        if (event.key === 'plugin:install') touchFile(installStampPath());
+        if (event.key === 'plugin:first_use') touchFile(firstUseStampPath());
       }
-      isFlushing = false;
-    })
-    .catch((error) => {
-      clearTimeout(timer);
-      debugLog(`POST FAIL err=${error.message} events=${batch.length}`);
+    } else if (resp.status >= 400 && resp.status < 500) {
+      debugLog(`POST status=${resp.status} dropping ${batch.length} events (client error)`);
+    } else {
       requeueEvents(batch);
-      isFlushing = false;
+    }
+  } catch (error) {
+    clearTimeout(timer);
+    debugLog(`POST FAIL err=${error.message} events=${batch.length}`);
+    requeueEvents(batch);
+  }
+}
+
+// #1014 P1: 排空整个队列（退出兜底用，单次 flush 只发一个 batch）。
+export async function flushAllEvents() {
+  const maxBatches = Math.ceil(MAX_QUEUE_SIZE / BATCH_SIZE) + 1;
+  for (let i = 0; i < maxBatches && eventQueue.length > 0; i++) {
+    await flushEvents();
+  }
+}
+
+const EXIT_FLUSH_TIMEOUT_MS = 3000;
+let exitFlushRegistered = false;
+
+// #1014 P1: SIGTERM/SIGINT 退出兜底 flush（有界超时，避免阻塞退出）。
+// 返回反注册函数（仅测试使用）。
+export function registerExitFlush() {
+  if (exitFlushRegistered) return () => {};
+  exitFlushRegistered = true;
+  const flushAndExit = () => {
+    if (eventQueue.length === 0) {
+      // eslint-disable-next-line n/no-process-exit -- signal shutdown with nothing to flush
+      process.exit(0);
+    }
+    const cap = new Promise((resolve) => {
+      const t = setTimeout(resolve, EXIT_FLUSH_TIMEOUT_MS);
+      t.unref?.();
+    });
+    const done = flushAllEvents().catch(() => {});
+    Promise.race([done, cap]).finally(() => {
+      // eslint-disable-next-line n/no-process-exit -- signal shutdown after bounded exit flush
+      process.exit(0);
     });
+  };
+  process.once('SIGTERM', flushAndExit);
+  process.once('SIGINT', flushAndExit);
+  return () => {
+    process.removeListener('SIGTERM', flushAndExit);
+    process.removeListener('SIGINT', flushAndExit);
+    exitFlushRegistered = false;
+  };
 }
 
 function requeueEvents(batch) {
@@ -390,6 +461,9 @@ export function initTelemetry({ harness, version }) {
 
   loadUserHash();
 
+  // #1014 P1: SIGTERM/SIGINT 退出兜底 flush（队列空时立即退出，零开销）。
+  registerExitFlush();
+
   if (!isTelemetryEnabled()) return;
 
   if (!stampExists(installStampPath()) && !existsSync(installCounterPath())) {

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

@@ -54,7 +54,7 @@ import {
   parseStsExpiry,
   resolveCredentialsWithRuntime,
 } from './auth/credentials.mjs';
-import { trackToolInvoke, trackSkillRetrieve, clearUserHash } from './telemetry/telemetry.mjs';
+import { trackToolInvoke, trackSkillRetrieve, clearUserHash, cacheUserHash } from './telemetry/telemetry.mjs';
 import { fetchWithProxy } from './proxy/proxy-agent.mjs';
 import { fingerprint, runHcloudConfigure, runHcloudProfileDelete, resolveManagedProfile } from './auth/reconcile.mjs';
 import {
@@ -1785,10 +1785,17 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
     }
     case 'huaweicloud_voucher_status':
       return await hdkitVoucherStatus(args.domain_id);
-    case 'huaweicloud_voucher_claim':
-      return await hdkitVoucherClaim(args.domain_id);
-    case 'huaweicloud_competition_voucher_claim':
-      return await hdkitCompetitionVoucherClaim(args.domain_id);
+    case 'huaweicloud_voucher_claim': {
+      const result = await hdkitVoucherClaim(args.domain_id);
+      // #1014 P0: 领券成功后补缓存 userHash（响应携带时），flush 前兜底补齐队列缺失字段。
+      if (result?.userHash) cacheUserHash(result.userHash);
+      return result;
+    }
+    case 'huaweicloud_competition_voucher_claim': {
+      const result = await hdkitCompetitionVoucherClaim(args.domain_id);
+      if (result?.userHash) cacheUserHash(result.userHash);
+      return result;
+    }
     case 'huaweicloud_check_update':
       return await handleCheckUpdate(args, { sessionId: opts?.sessionId, doQuery: opts?.doQuery });
     case 'huaweicloud_upgrade':