huaweicloud-devkit 1.1.9 → 1.1.10-next.0

package/plugins/huaweicloud-core/skills/huawei-iam/references/quick-ref.md

@@ -55,6 +55,41 @@ hcloud IAM CreateLoginToken                # create login token
 hcloud IAM GetAccountSummaryV5             # account summary
 ```
 
+## Primary vs Sub-Account Judgment
+
+**Rule (validated against 6 live credentials, zero misjudgment): `username == domainName` → primary account; otherwise IAM sub-user.**
+
+The primary account's operator user is named after the domain, and an IAM user cannot occupy that name (account-unique), so the rule has no false positives.
+
+Preferred path — one MCP call:
+
+```
+huaweicloud_check_account_type            # optional region param, defaults to configured cli-region
+```
+
+CLI fallback (two read-only calls, no identity-policy permission required; works for both primary and sub-user credentials):
+
+```bash
+hcloud STS GetCallerIdentity --cli-region=<region>
+# -> principal_urn "iam::<account_id>:user:<username>" gives username; account_id gives domainId
+hcloud IAM KeystoneListAuthDomains
+# -> domains[0].name gives domainName (domains[0].id must equal account_id — consistency check)
+```
+
+Example: `principal_urn ...:user:dingchunlei` + domain name `es_hwcddbdt_OpenCapability_team` → names differ → IAM sub-user. `...:user:keco_1919aa` + domain name `keco_1919aa` → equal → primary account.
+
+**Do NOT use these two tempting-but-wrong rules** (both disproved in live testing):
+
+| Wrong rule                                    | Why it fails                                                                                         |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `ShowDomainPasswordPolicy` succeeds → primary | Permission-gated, not account-type-gated: a sub-user with IAM permissions also succeeds              |
+| `principal_id == account_id` → primary        | False for primary accounts too (observed on three separate primary samples; IDs only share a prefix) |
+
+Edge cases:
+
+- Agency-session credentials (`principal_urn` starts with `sts::` or contains `assumed-agency`): the rule does not apply — report the identity only.
+- `KeystoneValidateToken` looks like a one-call shortcut (its token payload has both names) but requires an existing token as `--X-Subject-Token`, which AK/SK signing does not provide.
+
 ## Security Best Practices
 
 1. **NEVER create IAM users** — use IAM Identity Center or temporary STS tokens

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

@@ -294,7 +294,7 @@ fi
 Authentication tries three credential sources in order, each verified with a real login + `auth status` before use; a failure falls through to the next tier:
 
 - **Tier 1 — keyring API Key** (preferred): recent sandbox images (hd-space-ai-shell line) get `HW_DEVBRIDGE_API_KEY` auto-injected by the platform into the sandbox keyring — **zero user action, long-lived key**. Read it via `hwcloud keyring get HW_DEVBRIDGE_API_KEY 2>&1` (⚠ the value goes to **stderr** — `2>&1` is mandatory or you silently capture an empty string) and accept only values starting with `devbridge_` (`(not found)` and error text are rejected). If the first read fails, a light revive (restart the D-Bus session bus at `unix:path=/run/dbus-session`, replace a locked keyring daemon with `printf '\n' | gnome-keyring-daemon --unlock`) retries once — no package installs.
-- **Tier 2 — AK/SK** (image builds, legacy sandboxes): image builds keep `--access-key/--secret-key`. STS credentials **must** include `--security-token "$HW_SECURITY_TOKEN"` or the gateway rejects the request with 401 `APIGW.0301`. 0.1.x binaries additionally need `--huaweicloud` (only when their help advertises it).
+- **Tier 2 — AK/SK** (image builds, legacy sandboxes): image builds keep `--access-key/--secret-key`. STS credentials **must** include `--security-token "$HW_SECURITY_TOKEN"` or the gateway rejects the request with 401 `APIGW.0301`. **The `--huaweicloud` SSO login flag does NOT exist in sandbox devbridge 0.2.x binaries (e.g. 0.2.2)** — 文档超前于二进制：不要尝试 `--huaweicloud`，直接使用 `devbridge auth login --access-key/--secret-key`（上方脚本以 `auth login --help` 探测为准）。0.1.x binaries additionally advertised `--huaweicloud` (use it only when their help advertises it).
 - **Tier 3 — `/tmp/hw_api_key`** (release builds, user-provided one-time): the file is written by `huaweicloud_sandbox_credentials` from the local `HW_API_KEY` env (preferred) or the `api_key` param.
 
 `huaweicloud_sandbox_expose_tunnel` runs this waterfall automatically and reports the winning mode (`API_KEY_KEYRING` / `AKSK_SUPPORTED` / `API_KEY_FILE`) or `NO_CREDENTIAL` with a non-sensitive per-tier `attempts` diagnostic. Manual equivalent:
@@ -324,6 +324,11 @@ devbridge auth status   # separate step: a status failure must not mask the logi
 - **`AKSK_SUPPORTED`** → done. The temporary AK/SK injected by `huaweicloud_sandbox_credentials` is used directly (validated against IAM before injection). If login fails, surface the CLI error — expired STS token → re-run `huaweicloud_sandbox_credentials`.
 - **`NO_CREDENTIAL`** → first re-run `huaweicloud_sandbox_credentials` and retry (refreshes STS, most common quick fix). Still failing means an older sandbox whose image cannot auto-acquire (images are frozen at sandbox creation and cannot be upgraded in place) — guide the developer through a one-time API Key creation (wait for the key before continuing):
 
+**沙箱凭证与 devbridge 版本差异陷阱（实测 #935 坑2/坑3）**：
+
+- 沙箱内 devbridge 0.2.2 无技能文档所述 `--huaweicloud` 登录标志（文档超前于二进制）—— 应直接使用 `devbridge auth login --access-key/--secret-key`（`auth login --help` 探测到 `--access-key` 支持时走该分支，见上方手动等价脚本）。
+- 沙箱内 MCP 注入的 STS 凭证为 obsutil 加密态存储：devbridge 读到密文凭证会报 `APIGW.0301`。需先上传本地 DevKit 明文凭证库（AK 20 位 / SK 40 位，通过 `huaweicloud_sandbox_credentials` 注入），再创建隧道。
+
 1. **Why (one sentence)**: "沙箱的地址生成服务发布版构建已移除 AK/SK 登录，仅支持 API Key（镜像内置构建仍支持 AK/SK，Agent 已自动探测）。API Key 按账号管理，创建一次长期可用、所有沙箱通用。"
 2. **Where (exact steps)**: open https://devstation.connect.huaweicloud.com/space/devbridge/apikey → 登录控制台 → 选择 DevBridge 场景 → 点击"创建"。**完整值仅在创建时展示一次，立即复制**（`devbridge_` 开头）。
 3. **How to hand it over** (present both, recommend the first):
@@ -403,6 +408,8 @@ This eliminates the most common deployment failure — historical tunnels from p
 
 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.
 
+**沙箱无 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）。
+
 ### Step 1: Detect Framework Locally
 
 **Always call `huaweicloud_detect_framework` first** before connecting to the sandbox. It scans the local project and returns:

package/plugins/huaweicloud-core/src/account-type.mjs

@@ -0,0 +1,135 @@
+import { runHcloud } from './hcloud-cli.mjs';
+
+// Parse `hcloud STS GetCallerIdentity` stdout into structured identity fields.
+// URN forms (see https://support.huaweicloud.com/usermanual-iam5/iam_01_1275.html):
+//   iam::<account_id>:user:<username>            — user credentials (primary or IAM sub-user)
+//   sts::<account_id>::assumed-agency:<name>/…   — agency session credentials (rule does not apply)
+export function parseCallerIdentity(stdout) {
+  let parsed;
+  try {
+    parsed = typeof stdout === 'string' ? JSON.parse(stdout) : stdout;
+  } catch {
+    return { ok: false, error: 'GetCallerIdentity returned non-JSON output.' };
+  }
+  if (!parsed || typeof parsed !== 'object' || !parsed.principal_urn || !parsed.account_id) {
+    return { ok: false, error: 'GetCallerIdentity response missing principal_urn/account_id.' };
+  }
+  const principalUrn = String(parsed.principal_urn);
+  let urnType = 'unknown';
+  let username;
+  const userMatch = principalUrn.match(/^iam::[^:]+:user:(.+)$/);
+  if (userMatch) {
+    urnType = 'user';
+    username = userMatch[1];
+  } else if (/^sts::/.test(principalUrn) || /assumed-agency/.test(principalUrn)) {
+    urnType = 'agency';
+  }
+  return {
+    ok: true,
+    accountId: String(parsed.account_id),
+    principalUrn,
+    principalId: parsed.principal_id ? String(parsed.principal_id) : undefined,
+    urnType,
+    username,
+  };
+}
+
+// Parse `hcloud IAM KeystoneListAuthDomains` stdout into the domain list.
+export function parseAuthDomains(stdout) {
+  let parsed;
+  try {
+    parsed = typeof stdout === 'string' ? JSON.parse(stdout) : stdout;
+  } catch {
+    return { ok: false, error: 'KeystoneListAuthDomains returned non-JSON output.' };
+  }
+  const domains = Array.isArray(parsed?.domains) ? parsed.domains : [];
+  if (domains.length === 0) {
+    return { ok: false, error: 'IAM returned no domain information. Verify the AK/SK is valid.' };
+  }
+  return {
+    ok: true,
+    domains: domains.map((d) => ({ id: String(d.id), name: String(d.name || '') })),
+  };
+}
+
+// Judge primary vs sub-account. Rule (validated against 6 real credentials + 1 report case):
+//   username == domainName  -> primary account (its operator user is named after the domain)
+//   username != domainName  -> IAM sub-user (a sub-user cannot occupy the domain name)
+// Two tempting-but-wrong rules, kept here so they are not "rediscovered":
+//   - ShowDomainPasswordPolicy is NOT primary-only (it is permission-gated; a sub-user with IAM
+//     permissions can call it) — observed live.
+//   - principal_id == account_id does NOT hold for primary accounts either — observed on three
+//     separate primary-account samples.
+export function judgeAccountType(identity, domains) {
+  if (identity.urnType !== 'user') {
+    return {
+      ok: true,
+      applicable: false,
+      reason:
+        'Credentials are an agency session (principal_urn is not iam::…:user:…). ' +
+        'The primary/sub-account judgment applies to user credentials only.',
+      principalUrn: identity.principalUrn,
+    };
+  }
+  const matched = domains.domains.find((d) => d.id === identity.accountId);
+  if (!matched) {
+    return {
+      ok: false,
+      error:
+        'Inconsistent identity response: GetCallerIdentity account_id does not match any domain ' +
+        'returned by KeystoneListAuthDomains. Retry, and re-run "npx huaweicloud-devkit auth init" if it persists.',
+    };
+  }
+  const isPrimaryAccount = identity.username === matched.name;
+  return {
+    ok: true,
+    applicable: true,
+    isPrimaryAccount,
+    domainId: matched.id,
+    domainName: matched.name,
+    username: identity.username,
+    userId: identity.principalId,
+    principalUrn: identity.principalUrn,
+    evidence: isPrimaryAccount
+      ? `username == domainName ("${identity.username}") — the primary account's operator user is named after the domain.`
+      : `username ("${identity.username}") != domainName ("${matched.name}") — the caller is an IAM user under the domain.`,
+  };
+}
+
+// Orchestrate the two read-only hcloud calls and judge the account type.
+export async function checkAccountType({ region } = {}) {
+  const regionArgs = region ? [`--cli-region=${region}`] : [];
+  const identityResult = await runHcloud(['STS', 'GetCallerIdentity', ...regionArgs], {
+    timeoutMs: 30000,
+    maxRetries: 0,
+  }).catch((error) => ({ ok: false, error: error.message }));
+  if (!identityResult.ok) {
+    return {
+      ok: false,
+      error: identityResult.error || 'STS GetCallerIdentity failed.',
+      hint: 'Re-run "npx huaweicloud-devkit auth init" (invalid/expired AK/SK is the most common cause, e.g. APIGW.0301).',
+    };
+  }
+  const identity = parseCallerIdentity(identityResult.stdout);
+  if (!identity.ok) {
+    return { ok: false, error: identity.error };
+  }
+
+  const domainsResult = await runHcloud(['IAM', 'KeystoneListAuthDomains'], {
+    timeoutMs: 30000,
+    maxRetries: 0,
+  }).catch((error) => ({ ok: false, error: error.message }));
+  if (!domainsResult.ok) {
+    return {
+      ok: false,
+      error: domainsResult.error || 'IAM KeystoneListAuthDomains failed.',
+      hint: 'Re-run "npx huaweicloud-devkit auth init" if credentials are suspected expired.',
+    };
+  }
+  const domains = parseAuthDomains(domainsResult.stdout);
+  if (!domains.ok) {
+    return { ok: false, error: domains.error };
+  }
+
+  return judgeAccountType(identity, domains);
+}

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

@@ -799,8 +799,22 @@ export function extractApiError(stdout) {
   return null;
 }
 
+// A4 (#935): KooCLI 7.2.x prints a version-upgrade banner on EVERY command
+// output (e.g. 「可执行 hcloud update 更新至 7.3.12」), which floods agent
+// conversations and drowns the actual result. Banner lines are stripped from
+// command output here; the only upgrade hint DevKit emits is check_cli/doctor's
+// soft, one-shot mismatch hint — kooCliVersion in package.json is the single
+// source of truth for the paired version, and check_cli/doctor keep their
+// non-blocking semantics.
+export function stripKooCliUpdateBanner(output) {
+  return String(output || '')
+    .split('\n')
+    .filter((line) => !(/hcloud\s+update/i.test(line) && /更新至|update to/i.test(line)))
+    .join('\n');
+}
+
 export function redactOutput(output) {
-  let text = String(output || '');
+  let text = stripKooCliUpdateBanner(String(output || ''));
   const bracketIdx = text.indexOf('{');
   if (bracketIdx > 0) text = text.substring(bracketIdx);
   try {

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

@@ -394,7 +394,13 @@ function splitSimpleCommand(command) {
   return (
     String(command)
       .match(/"[^"]*"|'[^']*'|\S+/g)
-      ?.map((part) => part.replace(/^['"]|['"]$/g, '')) || []
+      // Strip ALL quote characters (not just the outer pair): POSIX shells
+      // remove quotes before executing, so an embedded-quote form like
+      // `hcloud ECS De'leteServer …` actually runs `DeleteServer`. Stripping
+      // only outer quotes left `De'leteServer` in the token and let the write/
+      // secret/execution matchers miss it (#927). This hcloud classification
+      // path only — credential-var lookbehind still sees raw text with quotes.
+      .map((part) => part.replace(/['"]/g, '')) || []
   );
 }
 
@@ -478,12 +484,37 @@ export function extractInnerCommand(text, depth = 0) {
 // ^hcloud still catches wrapped commands and prompt-injections using
 // separators. sudo\s+ preserves the dev-baseline behaviour where
 // `sudo hcloud …` is treated as a real command, not documentation (#760 P0).
+// Keyword-locator pattern shared by the raw-text match and the quote-stripped
+// retry in extractHcloudSubcommand (`im` flag, no `g` — no lastIndex state).
+const HCLOUD_KEYWORD_PATTERN = /(?:^|[;|&]\s*|\$\(\s*|`\s*|sudo\s+|\r?\n\s*)(hcloud(?:\.exe)?\b)/im;
+
 function extractHcloudSubcommand(text) {
   const t = String(text || '');
-  const match = /(?:^|[;|&]\s*|\$\(\s*|`\s*|sudo\s+)(hcloud(?:\.exe)?\b)/i.exec(t);
-  if (!match) return null;
-  const hcloudIndex = match.index + match[0].length - match[1].length;
-  return t.slice(hcloudIndex);
+  // `m` flag + newline in the separator class: a hcloud command at the start
+  // of any line (not just the first) must be located and fully classified —
+  // previously `echo hello\nhcloud ECS DeleteServer …` fell through as
+  // not_huaweicloud allow (#927).
+  const match = HCLOUD_KEYWORD_PATTERN.exec(t);
+  if (match) {
+    const hcloudIndex = match.index + match[0].length - match[1].length;
+    return t.slice(hcloudIndex);
+  }
+  // Keyword-embedded quotes fallback (#927 B1): POSIX shells strip quotes
+  // before execution, so `hc'loud ECS DeleteServer …` runs `hcloud …` — but
+  // the literal match above never sees the keyword through the quotes and the
+  // command fell through as not_huaweicloud allow (its de-quoted form is
+  // DENY). Retry on a quote-stripped COPY used only for hcloud keyword
+  // location; the returned subcommand is the de-quoted text, matching the
+  // de-quote semantics splitSimpleCommand already applies to tokens.
+  // Credential/env-var checks in classifyTextCommand still run on the raw
+  // text — the two paths stay independent — and natural-language mentions
+  // ("see hcloud docs", "echo hcloud is a CLI") match the same anchored
+  // pattern, so no new false positives are introduced.
+  const stripped = t.replace(/['"]/g, '');
+  const strippedMatch = HCLOUD_KEYWORD_PATTERN.exec(stripped);
+  if (!strippedMatch) return null;
+  const hcloudIndex = strippedMatch.index + strippedMatch[0].length - strippedMatch[1].length;
+  return stripped.slice(hcloudIndex);
 }
 
 export function classifyTextCommand(command, options = {}) {

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

@@ -226,12 +226,48 @@ export function buildExposeRemediation(port) {
   return `In the sandbox: source /tmp/hw_creds.sh; source /tmp/hw_api_key 2>/dev/null; devbridge delete-all; devbridge create <name>; devbridge port create <tunnelId> -p ${port} --protocol http -a; nohup devbridge host <tunnelId> -p ${port} > /tmp/host.log 2>&1 & If deploy_nginx reported a different (auto-incremented) port in its "port" field, use THAT port instead of the one shown here. Full procedure in huawei-sandbox skill, Step 7 (Expose via DevBridge).`;
 }
 
-export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
-  if (!existsSync(localPath)) {
-    throw new Error(`sandbox upload: local file not found: ${localPath}`);
+// #953: classify a local upload path BEFORE touching the file, so the error names
+// the real problem instead of a misleading "not found" when an entire parent
+// directory is missing (agent-side paths often do not exist at all).
+// kind: 'file' (uploadFileWithSession) | 'directory' (uploadProjectWithSession).
+// Returns null when the path exists with the expected type; otherwise an Error
+// whose message distinguishes missing-path from missing-parent, with a copy-to-tmp
+// hint that names the actual OS temp dir.
+export function classifyLocalUploadPath(localPath, kind = 'file') {
+  const expected = kind === 'directory' ? 'directory' : 'regular file';
+  const prefix = kind === 'directory' ? 'sandbox upload project' : 'sandbox upload';
+  if (existsSync(localPath)) {
+    const stat = statSync(localPath);
+    const matches = kind === 'directory' ? stat.isDirectory() : stat.isFile();
+    if (!matches) {
+      return new Error(`${prefix}: path is not a ${expected}: ${localPath}`);
+    }
+    return null;
   }
-  if (!statSync(localPath).isFile()) {
-    throw new Error(`sandbox upload: path is not a regular file: ${localPath}`);
+  const parent = dirname(localPath);
+  if (!existsSync(parent)) {
+    return new Error(
+      `${prefix}: directory not found: ${parent}. The DevKit MCP server reads files from ` +
+        `the machine it runs on. Verify the path, or first copy the ${expected} to the local ` +
+        `temp directory (${tmpdir()}) and upload from there.`,
+    );
+  }
+  return new Error(`${prefix}: local ${expected} not found: ${localPath}`);
+}
+
+// #953: reset command for uploadFileWithSession. mkdir -p the remote parent BEFORE any
+// chunk writes — the `printf >>` appends land in "${remotePath}.b64tmp" next to the
+// target, so an absent directory (e.g. /workspace/game2048/) would fail the very first
+// batch. This aligns base64-path behavior with upload_project's file server (which
+// already makedirs). Both paths are quoted; "path with spaces" is covered by tests.
+export function buildUploadResetCommand(remotePath, tmpPath) {
+  return `mkdir -p "$(dirname "${remotePath}")" && rm -f "${tmpPath}"`;
+}
+
+export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
+  const localError = classifyLocalUploadPath(localPath, 'file');
+  if (localError) {
+    throw localError;
   }
   const content = readFileSync(localPath);
   const base64 = content.toString('base64');
@@ -239,7 +275,7 @@ export async function uploadFileWithSession(workspaceId, localPath, remotePath,
   const chunks = splitBase64Chunks(base64);
   const tmp = `${remotePath}.b64tmp`;
 
-  const reset = await execWithSession(workspaceId, `rm -f "${tmp}"`, username, timeoutMs);
+  const reset = await execWithSession(workspaceId, buildUploadResetCommand(remotePath, tmp), username, timeoutMs);
   if (reset.exitCode !== 0) {
     throw new Error(`sandbox upload: failed to reset temp file: ${reset.stdout || reset.error || reset.exitCode}`);
   }
@@ -639,11 +675,9 @@ export async function uploadProjectWithSession(
         'Set HW_WORKSPACE_ID env var or ensure huaweicloud_sandbox_connect was called first.',
     );
   }
-  if (!existsSync(localDir)) {
-    throw new Error(`sandbox upload project: local directory not found: ${localDir}`);
-  }
-  if (!statSync(localDir).isDirectory()) {
-    throw new Error(`sandbox upload project: path is not a directory: ${localDir}`);
+  const localError = classifyLocalUploadPath(localDir, 'directory');
+  if (localError) {
+    throw localError;
   }
 
   rotateUploadLog();
@@ -740,6 +774,56 @@ export async function uploadProjectWithSession(
   };
 }
 
+// A1 (#935): normalize the deploy_nginx configName to a bare filename. A value
+// carrying path separators (e.g. `/root/hc-activity.conf`, `./x/y.conf`) used to
+// be spliced verbatim into `/etc/nginx/conf.d/${configName}.conf`, producing the
+// broken path `/etc/nginx/conf.d//root/hc-activity.conf` (nginx never serves it,
+// the tunnel answers 502). Only the basename is kept and the `.conf` suffix is
+// stripped before the path is rebuilt as `/etc/nginx/conf.d/<name>.conf`. A
+// pure filename (no separators) keeps the previous behavior unchanged.
+export function resolveNginxConfigPath(configName, project) {
+  const raw = String(configName || project || '');
+  const base = raw.split(/[\\/]/).filter(Boolean).pop() || '';
+  const name = base.replace(/\.conf$/i, '') || 'default';
+  return `/etc/nginx/conf.d/${name}.conf`;
+}
+
+// A1 (#935): parse the write-verification block appended to the deploy_nginx
+// script. The old flow returned ok:true whenever the deploy script exited 0,
+// even when the tee write silently failed — the config file never existed and
+// the tunnel answered 502. The verification block emits explicit markers:
+//   DB_NGINX_CONFIG_MISSING=1  — the target config file does not exist
+//   DB_NGINX_T=PASS|FAIL       — nginx -t verdict, with failure output echoed
+//                                as `DB_NGINX_T_OUTPUT: ...` lines
+export function parseDeployNginxVerifyOutput(stdout) {
+  const text = String(stdout || '');
+  const configMissing = /DB_NGINX_CONFIG_MISSING=1/.test(text);
+  const nginxTest = (text.match(/^DB_NGINX_T=(\w+)$/m) || [])[1] || '';
+  const nginxTestOutput = (text.match(/^DB_NGINX_T_OUTPUT: .*$/gm) || [])
+    .map((line) => line.replace(/^DB_NGINX_T_OUTPUT: /, ''))
+    .join('\n');
+  return { configMissing, nginxTest, nginxTestOutput };
+}
+
+// A1 (#935): the deploy verdict. A deploy script exit of 0 alone is NOT proof
+// of success — the tee write can fail silently (broken pipe) and nginx -t can
+// reject the config. Returns ok:false with an explicit, actionable error for
+// any verification failure; a pure function so the verdict is unit-testable.
+export function evaluateDeployNginxVerify(result, verify, configPath) {
+  const exitCode = result?.exitCode;
+  const writeVerified = exitCode === 0 && !verify.configMissing && verify.nginxTest === 'PASS';
+  if (writeVerified) return { ok: true };
+  const problems = [];
+  if (exitCode !== 0) problems.push(`deploy script exited with code ${exitCode}`);
+  if (verify.configMissing) problems.push(`nginx config file ${configPath} was not created (tee write failed)`);
+  if (verify.nginxTest !== 'PASS')
+    problems.push(`nginx -t did not pass${verify.nginxTestOutput ? ` — ${verify.nginxTestOutput}` : ''}`);
+  return {
+    ok: false,
+    error: `sandbox deploy nginx: configuration write verification failed — ${problems.join('; ')}.`,
+  };
+}
+
 export async function deployNginx(
   workspaceId,
   { nginxType, port, project, outputDir, nodePort, publicPort, configName },
@@ -874,10 +958,14 @@ fi`;
     throw new Error(`sandbox deploy nginx: unknown nginxType "${nginxType}". Must be one of: spa, proxy, static`);
   }
 
+  // A1 (#935): configName is normalized to a bare filename so a path-shaped
+  // value can never produce `/etc/nginx/conf.d//root/xxx.conf` again.
+  const configPath = resolveNginxConfigPath(configName, project);
+
   const cmd = [
     resolveScript,
     `sudo mkdir -p /etc/nginx/conf.d`,
-    `sudo tee /etc/nginx/conf.d/${configName || project}.conf > /dev/null << 'NGINX_EOF'`,
+    `sudo tee ${configPath} > /dev/null << 'NGINX_EOF'`,
     config,
     `NGINX_EOF`,
     `# Resolve symlinks for chmod (chmod does not follow symlinks on Linux)`,
@@ -886,6 +974,11 @@ fi`;
     `find "$REAL_PROJECT" -type f -path "*/node_modules/.bin/*" -exec chmod +x {} \\; 2>/dev/null || true`,
     `if pgrep -x nginx > /dev/null 2>&1; then sudo killall -9 nginx 2>/dev/null; sleep 1; fi
     sudo nginx`,
+    `# A1 (#935): verify the config write took effect before reporting success`,
+    `NGINX_CONFIG_PATH=${configPath}`,
+    `if [ ! -f "$NGINX_CONFIG_PATH" ]; then echo "DB_NGINX_CONFIG_MISSING=1"; fi`,
+    `NGINX_T_OUTPUT=$(sudo nginx -t 2>&1 || true)`,
+    `if echo "$NGINX_T_OUTPUT" | grep -Eq "syntax is ok|test is successful"; then echo "DB_NGINX_T=PASS"; else echo "DB_NGINX_T=FAIL"; echo "$NGINX_T_OUTPUT" | sed "s/^/DB_NGINX_T_OUTPUT: /"; fi`,
   ].join('\n');
 
   const result = await execOneShot(workspaceId, cmd, username, timeoutMs);
@@ -912,13 +1005,36 @@ fi`;
   const driftWarning = tunnelActive ? formatPortDriftWarning(basePort, targetPort) : undefined;
   if (driftWarning) warnings.push(driftWarning);
 
+  // A1 (#935): verify the config write before reporting success. Any
+  // verification failure returns ok:false with an explicit, actionable error.
+  const verify = parseDeployNginxVerifyOutput(result.stdout);
+  const verdict = evaluateDeployNginxVerify(result, verify, configPath);
+  if (!verdict.ok) {
+    return {
+      ok: false,
+      error: verdict.error,
+      nginxType,
+      port: targetPort,
+      nodePort: effectiveNodePort || undefined,
+      outputPath,
+      projectPath,
+      configPath,
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      nextStep: 'fix_and_retry',
+      warning: warnings.length > 0 ? warnings.join(' | ') : undefined,
+    };
+  }
+
   return {
-    ok: result.exitCode === 0,
+    ok: true,
     nginxType,
     port: targetPort,
     nodePort: effectiveNodePort || undefined,
     outputPath,
     projectPath,
+    configPath,
+    verification: { configPath, nginxTest: verify.nginxTest },
     exitCode: result.exitCode,
     stdout: result.stdout,
     nextStep: 'expose_via_devbridge',
@@ -1318,11 +1434,22 @@ export function buildDevbridgeExposeScript(port, expiryHours = DEVBRIDGE_HOST_EX
     // not abort the script.
     `if command -v setsid > /dev/null 2>&1; then setsid nohup devbridge host -p ${port} -e ${expiryHours} > ${hostLog} 2>&1 < /dev/null & else nohup devbridge host -p ${port} -e ${expiryHours} > ${hostLog} 2>&1 < /dev/null & fi`,
     `disown 2>/dev/null || true`,
-    `sleep 12`,
-    // Port-anchored extraction: a multi-port host prints one "Tunnel URL:" line per
+    `sleep 6`,
+    // Port-anchored extraction (#943): a multi-port host prints one "Tunnel URL:" line per
     // port, so a port-blind `sed | tail -1` can pick another port's URL.
     `TUNNEL_URL=$(grep -oE "https://[A-Za-z0-9_-]+-${port}\\.devbridge-s2\\.hwtunnel\\.com" ${hostLog} | head -1)`,
-    `HTTP_CODE=$(curl -s -o /tmp/.db_probe_body -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")`,
+    // A2 (#935): probe with retries + backoff — 502/000 before the gateway is
+    // ready is not a failure; the LAST probe decides reachability. The body is
+    // captured every probe so DB_TUNNEL_BODY reflects the final one (#943).
+    `HTTP_CODE="000"`,
+    `if [ -n "$TUNNEL_URL" ]; then`,
+    `  for i in 1 2 3 4; do`,
+    `    HTTP_CODE=$(curl -s -o /tmp/.db_probe_body -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")`,
+    `    echo "DB_PROBE_$i=$HTTP_CODE"`,
+    `    if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "304" ]; then break; fi`,
+    `    if [ "$i" != "4" ]; then sleep 5; fi`,
+    `  done`,
+    `fi`,
     `echo "DB_HOST_LOG="`,
     `tail -n 5 ${hostLog}`,
     `echo "DB_TUNNEL_URL=$TUNNEL_URL"`,
@@ -1362,6 +1489,30 @@ export function buildDevbridgeVerifyScript(tunnelUrl) {
   ].join('\n');
 }
 
+// A2 (#935): parse the probe sequence emitted by buildDevbridgeExposeScript.
+// Each probe echo is `DB_PROBE_<n>=<code>`; reachability is decided by the
+// LAST probe — intermediate 502/000 probes are gateway-not-ready noise, not
+// failures, so they must not leak into the tool's verdict.
+export function parseDevbridgeProbeSequence(stdout) {
+  const text = String(stdout || '');
+  const probes = [];
+  for (const m of text.matchAll(/^DB_PROBE_(\d+)=(\S*)$/gm)) {
+    probes.push({ attempt: Number(m[1]), httpCode: m[2] });
+  }
+  const finalHttpCode = probes.length > 0 ? probes[probes.length - 1].httpCode : '';
+  return { probes, finalHttpCode };
+}
+
+// A2 (#935): the reachability warning must come from the LAST probe's HTTP
+// status, not from a single early curl — the old single-shot check warned
+// "Tunnel reachable check returned HTTP (expected 200/304)" while the same
+// log showed DB_HTTP_CODE=200. 200/304 = no warning; anything else surfaces
+// as-is.
+export function formatTunnelReachabilityWarning(httpCode) {
+  if (httpCode === '200' || httpCode === '304') return undefined;
+  return `Tunnel reachable check returned HTTP ${httpCode || '000'} (expected 200/304). The URL may not be serving yet — the final probe decides.`;
+}
+
 // Parse the raw stdout of buildDevbridgeExposeScript into structured fields.
 // `gatewayTunnelError` marks a URL the s2 gateway itself reports as dead
 // (404 "tunnel not found" / "port not configured") — it can never serve content
@@ -1553,15 +1704,15 @@ export async function exposeTunnel(workspaceId, { port }, username = 'root', tim
       }
     }
 
+    // A2 (#935): the reachability warning uses the FINAL probe's HTTP status —
+    // intermediate 502/000 probes (gateway not ready yet) must not leak into
+    // the verdict, and a sequence of 502/000 → 200 must NOT warn.
     if (parsed.badGateway)
       warnings.push(
         'Tunnel reachable but the gateway reports "bad gateway" — the local service on the exposed port is not serving.',
       );
-    if (parsed.httpCode !== '200' && parsed.httpCode !== '304') {
-      warnings.push(
-        `Tunnel reachable check returned HTTP ${parsed.httpCode} (expected 200/304). The URL may not be serving yet.`,
-      );
-    }
+    const reachabilityWarning = formatTunnelReachabilityWarning(parsed.httpCode);
+    if (reachabilityWarning) warnings.push(reachabilityWarning);
     const expiresAt =
       parsed.expiryHours !== undefined
         ? new Date(Date.now() + parsed.expiryHours * 3_600_000).toISOString()