@baize-ai/core 0.3.11 → 0.3.13

package/.dockerignore

@@ -6,3 +6,5 @@
 !templates/pm2/ecosystem.config.cjs
 !.claude-local/claude
 !.claude-local/claude.version
+!skills/
+!.docker-local-skills/

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to baize-core will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.13] - 2026-08-28
+
+### Fixed
+- A2A 上传安装后自动 rebuild 原生模块（D44）：上传安装用 --ignore-scripts（vendor 包安全），better-sqlite3 等 native 模块不编译 → 上传后 A2A 状态加载失败；安装流程现追加 `npm rebuild --build-from-source`（只编译、不跑 vendor 脚本），失败回滚
+- Docker 镜像 npm 源修复（D43）：容器 npm 运行时是 baize 用户（prefix /home/baize/.npm-global）——镜像只写了 /usr/etc/npmrc（root 视角）npm 不读 → ACR 镜像 npm 仍走 npmjs；现同时写 /home/baize/.npmrc（优先级最高必读）
+
+## [0.3.12] - 2026-08-28
+
+### Added
+- web 控制台 runtime 未安装时异步安装（D39）：切换 claude/codex 检测 CLI 缺失 → 后台安装（install.sh/npm，900s 超时 + 重试）→ 装完自动切换；状态端点 + 前端进度轮询（修复 240s/300s 双超时导致的切 cc 失败）
+- 初始化失败 web 可见（D40）：entrypoint 写 init-state.json，诊断卡显示「初始化未完成」+ 引导
+- runtime 安装状态可见（D41）：模型设置页每个 runtime 显示安装徽章（✅ 版本 / ❌ 未装 + 失败原因）+ [安装] 按钮（复用 D39 异步安装）+ 当前 runtime 缺失红色警告
+- 环境修复闭环（D42）：环境初始化卡置顶（未就绪缺口人话 + [重新初始化] 一键幂等 init + 失败人话原因 + web 内日志展开）——web 是唯一恢复入口，无需 SSH
+
+### Fixed
+- Docker 镜像：不捆绑 claude（单架构二进制导致另一平台 exec format error）；npm/apt 源跟随推送目标（ghcr 默认官方源，ACR 构建全 npmmirror/阿里云）；entrypoint 首次默认 codex（与 install.sh 统一，已初始化尊重现有 runtime）
+
 ## [0.3.11] - 2026-08-27
 
 ### Fixed

package/Dockerfile

@@ -14,8 +14,21 @@ FROM node:22-slim
 
 LABEL org.opencontainers.image.source="https://github.com/baize01-ai/baize-core"
 LABEL org.opencontainers.image.description="Baize — autonomous AI agent infrastructure"
+# Build flags: official sources by default (npmjs + Debian). Set to "aliyun"
+# when building for the Aliyun ACR (mainland distribution) — npmmirror npm +
+# Aliyun Debian mirror, baked into the image so docker run npm also uses the
+# mainland source. ARG must precede the RUNs that reference them.
+ARG BAIZE_APT_MIRROR=off
+ARG BAIZE_NPM_MIRROR=off
 
 # ── System packages ───────────────────────────────────────────────────────────
+# Point apt at the Aliyun Debian mirror when building on mainland servers
+# (deb.debian.org is unreachable/slow there; env flag lets non-CN builds keep
+# the official source).
+RUN if [ "${BAIZE_APT_MIRROR:-off}" = "aliyun" ]; then \
+      sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources; \
+      sed -i 's|security.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources; \
+    fi
 RUN apt-get update && apt-get install -y --no-install-recommends \
       git \
       curl \
@@ -35,22 +48,20 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       g++ \
     && rm -rf /var/lib/apt/lists/*
 
-# ── Global npm tools ──────────────────────────────────────────────────────────
+# Mainland: registry.npmjs.org is unreachable — point npm at npmmirror
+# (build-arg BAIZE_NPM_MIRROR=off keeps the official registry).
+RUN if [ "${BAIZE_NPM_MIRROR:-off}" = "aliyun" ]; then \
+      npm config set registry https://registry.npmmirror.com --global; \
+      # Also drop a system-wide npmrc so the runtime user (baize) and any
+      # docker exec npm use the mainland mirror too.
+      mkdir -p /usr/etc && printf 'registry=https://registry.npmmirror.com\n' > /usr/etc/npmrc; \
+      # Container npm runs as USER baize with prefix /home/baize/.npm-global —
+      # its globalconfig is NOT /usr/etc/npmrc, so also write the user-level
+      # ~/.npmrc (highest precedence, always read) or npm stays on npmjs.
+      mkdir -p /home/baize && printf 'registry=https://registry.npmmirror.com\n' > /home/baize/.npmrc; \
+    fi
 RUN npm install -g pm2@latest
 
-# ── Claude Code CLI (pre-bundled, pinned version) ─────────────────────────────
-# The official install.sh downloads a ~340MB binary at container runtime, which
-# is unreliable inside container networks (fails ~90% through on Docker
-# Desktop). Bundle a PINNED, verified binary in the image instead:
-#   curl -fsSL https://downloads.claude.ai/claude-code-releases/<ver>/linux-arm64/claude
-#   (verify against .../manifest.json platforms.linux-arm64 checksum)
-#   echo <ver> > .claude-local/claude.version
-# Upgrade = replace the binary + bump claude.version, then rebuild the image
-# (explicit release decision — never auto-fetch latest at build time).
-COPY .claude-local/claude /usr/local/bin/claude
-RUN chmod +x /usr/local/bin/claude
-COPY .claude-local/claude.version /usr/local/bin/claude.version
-LABEL org.opencontainers.image.claude-version="$(cat .claude-local/claude.version 2>/dev/null || echo unknown)" 
 
 # ── Create baize user (non-root) ──────────────────────────────────────────────
 RUN useradd -m -s /bin/bash baize \
@@ -71,6 +82,11 @@ ENV WEB_CONSOLE_BIND=0.0.0.0
 # build context) — source stays private, the image matches the npm version
 # exactly. Build with: docker build --build-arg BAZE_CORE_VERSION=0.2.0 .
 ARG BAZE_CORE_VERSION=latest
+# Local-development override: when building from source with
+# --build-arg BAIZE_LOCAL_SKILLS=1, copy the LOCAL skills over the npm-package
+# skills so un-released fixes (e.g. D44) land in the image without publishing.
+# Official builds leave this off — the published npm package is authoritative.
+ARG BAIZE_LOCAL_SKILLS=0
 WORKDIR /home/baize
 RUN npm install -g @baize-ai/core@${BAZE_CORE_VERSION} \
     && baize --version \
@@ -113,6 +129,14 @@ RUN npm install -g @baize-ai/core@${BAZE_CORE_VERSION} \
     && node -e "const D=require('/home/baize/baize/.claude/skills/web-console/node_modules/better-sqlite3'); new D(':memory:')" \
     && echo "native modules OK (locally compiled, baked into runtime skills)"
 
+# ── Local-source skills override (BAIZE_LOCAL_SKILLS=1) ─────────────────────
+# docker-publish.sh stages the repo's skills/ into .docker-local-skills/ when
+# BAIZE_LOCAL_SKILLS=1 (empty directory otherwise). They land in
+# /home/baize/.local-skills and are applied by entrypoint AFTER init, because
+# init's postinstall syncSkills uses the npm-package skills as source and
+# would otherwise overwrite them. Official images carry an empty dir — no-op.
+COPY --chown=baize:baize .docker-local-skills/ /home/baize/.local-skills/
+
 # ── Workspace directories ─────────────────────────────────────────────────────
 # ~/baize is mounted as a single volume in docker-compose.yml.
 # Creating subdirectories here ensures correct ownership in the image.

package/docker/entrypoint.sh

@@ -65,15 +65,14 @@ if [ -n "${AUTH_TOKEN}" ]; then
   fi
 fi
 
-# Detect runtime — if only Codex credentials are present (no Claude creds), default to codex.
-# BAIZE_RUNTIME env var always wins when explicitly set.
+# Detect runtime — default to codex ONLY on first boot (mainland default;
+# the image no longer bundles claude, which is installed manually when
+# needed). If the workspace is already initialized (config.json exists) the
+# existing runtime is respected — init would otherwise reset a runtime the
+# user switched to in the web console. BAIZE_RUNTIME env always wins.
 RUNTIME_FLAG=""
 if [ -z "${BAIZE_RUNTIME:-}" ]; then
-  HAS_CLAUDE_AUTH=false
-  HAS_CODEX_AUTH=false
-  [ -n "${ANTHROPIC_API_KEY:-}" ] || [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && HAS_CLAUDE_AUTH=true
-  [ -n "${OPENAI_API_KEY:-}" ] || [ -n "${CODEX_API_KEY:-}" ] && HAS_CODEX_AUTH=true
-  if [ "${HAS_CODEX_AUTH}" = true ] && [ "${HAS_CLAUDE_AUTH}" = false ]; then
+  if [ ! -f "${BAIZE_DIR}/.baize/config.json" ]; then
     RUNTIME_FLAG="--runtime codex"
   fi
 fi
@@ -87,9 +86,26 @@ INIT_ARGS="--yes --quiet"
 # shellcheck disable=SC2086
 if ! baize init ${INIT_ARGS}; then
   warn "baize init exited with errors (may be partial). Check logs."
+  # Surface init failure to the web console (diagnostics card) so the user can
+  # discover and fix it in-browser (e.g. a runtime CLI that failed to install).
+  mkdir -p "${BAIZE_DIR}/.baize"
+  printf '{"status":"failed","error":"baize init exited with errors","at":"%s"}\n' "$(date -Iseconds)" > "${BAIZE_DIR}/.baize/init-state.json"
+  exit 1
 fi
-
 ok "Workspace ready"
+mkdir -p "${BAIZE_DIR}/.baize"
+# ── Local-source skills override (BAIZE_LOCAL_SKILLS=1 images) ──────────────
+# Images built with BAIZE_LOCAL_SKILLS=1 bake the repo's skills into
+# /home/baize/.local-skills. syncSkills (npm postinstall) runs during init
+# with the npm-package skills as source, so apply the local override AFTER
+# init to keep un-released fixes (e.g. D44) authoritative.
+# Official images ship an empty .local-skills — this is a no-op there.
+if [ -d /home/baize/.local-skills ]; then
+  cp -rf /home/baize/.local-skills/. "${BAIZE_DIR}/.claude/skills/" 2>/dev/null \
+    && ok "Local-source skills applied (BAIZE_LOCAL_SKILLS=1)"
+fi
+
+# ── Pass through channel env vars to .env ─────────────────────────────────────
 
 # ── Pass through channel env vars to .env ─────────────────────────────────────
 # baize init doesn't write channel tokens — those come from component installs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baize-ai/core",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "type": "module",
   "description": "Baize (\u767d\u6cfd) \u2014 autonomous AI agent infrastructure",
   "main": "cli/baize.js",

package/scripts/build-push-acr.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Multi-platform build + push to Aliyun ACR for the mainland distribution.
+# Usage:  bash build-push-acr.sh [VERSION]   (default 0.3.11)
+# Requires: docker login already done, qemu-arm64 registered
+#           (apt install qemu-user-binfmt), registry mirror configured.
+set -euo pipefail
+
+VERSION="${1:-0.3.11}"
+ACR="crpi-8bg62qbrjs3cr3as.cn-hangzhou.personal.cr.aliyuncs.com/baize01/baize-core"
+
+echo "== Configure buildkit registry mirror (mainland Docker Hub access) =="
+mkdir -p /etc/buildkit
+cat > /etc/buildkit/buildkit.toml <<'EOF'
+[registry."docker.io"]
+  mirrors = ["https://docker.m.daocloud.io"]
+EOF
+
+echo "== Ensure multi-platform builder (reuse for layer cache) =="
+if ! docker buildx inspect multi >/dev/null 2>&1; then
+  docker buildx create --name multi --driver docker-container \
+    --config /etc/buildkit/buildkit.toml --use
+fi
+docker buildx use multi 2>/dev/null || true
+
+echo "== Build + push $VERSION (amd64 + arm64) =="
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --provenance=false --sbom=false \
+  --build-arg BAZE_CORE_VERSION="$VERSION" \
+  --build-arg BAIZE_APT_MIRROR=aliyun \
+  --build-arg BAIZE_NPM_MIRROR=aliyun \
+  -t "$ACR:$VERSION" \
+  -t "$ACR:latest" \
+  --push .
+
+echo "== Verify =="
+docker buildx imagetools inspect "$ACR:$VERSION" | grep -E "Platform|Architecture" | head -4
+echo "== Done =="

package/scripts/docker-publish.sh

@@ -30,11 +30,22 @@ ACR_NAMESPACE="${ACR_NAMESPACE:-baize01}"
 
 # ── Build ────────────────────────────────────────────────────────────────────
 echo "==> Building baize-core:${VERSION} (from npm @baize-ai/core@${VERSION})"
+BUILD_ARGS=(--build-arg "BAZE_CORE_VERSION=${VERSION}")
+rm -rf .docker-local-skills && mkdir -p .docker-local-skills
+if [ "${BAIZE_LOCAL_SKILLS:-0}" = "1" ]; then
+  BUILD_ARGS+=(--build-arg BAIZE_LOCAL_SKILLS=1)
+  echo "==> Overriding skills with LOCAL repo source (BAIZE_LOCAL_SKILLS=1) — un-released fixes baked in"
+  cp -r skills/. .docker-local-skills/
+  # Never ship host-compiled node_modules (mac binaries break linux runtime) —
+  # dependency binaries come from the image's own npm install.
+  find .docker-local-skills -type d -name node_modules -prune -exec rm -rf {} +
+fi
 docker build \
-  --build-arg BAZE_CORE_VERSION="${VERSION}" \
+  "${BUILD_ARGS[@]}" \
   -t "${GHCR_IMAGE}:${VERSION}" \
   -t "${GHCR_IMAGE}:latest" \
   .
+rm -rf .docker-local-skills
 
 if [ -n "${ACR_REGISTRY}" ] && [ -n "${ACR_NAMESPACE}" ]; then
   ACR_IMAGE="${ACR_REGISTRY}/${ACR_NAMESPACE}/baize-core"

package/scripts/install-docker.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Install Docker Engine (with buildx) on a mainland Ubuntu server.
+# Uses the Aliyun docker-ce mirror; falls back from the local Ubuntu
+# codename to noble (24.04) when the mirror has not synced it yet.
+# Run as root:  bash install-docker.sh
+set -euo pipefail
+
+echo "== 1/4 Download Docker GPG key =="
+curl -fsSL -o /tmp/docker.gpg https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg
+gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg /tmp/docker.gpg
+
+echo "== 2/4 Write apt source (deb822) =="
+CODENAME=$(lsb_release -cs)
+{
+  echo "Types: deb"
+  echo "URIs: https://mirrors.aliyun.com/docker-ce/linux/ubuntu"
+  echo "Suites: $CODENAME"
+  echo "Components: stable"
+  echo "Signed-By: /usr/share/keyrings/docker-archive-keyring.gpg"
+} > /etc/apt/sources.list.d/docker.sources
+
+if ! apt-get update; then
+  echo "== $CODENAME not on the mirror yet, falling back to noble =="
+  sed -i "s/Suites: $CODENAME/Suites: noble/" /etc/apt/sources.list.d/docker.sources
+  apt-get update
+fi
+
+echo "== 3/4 Install Docker =="
+apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+echo "== 4/4 Start and verify =="
+systemctl enable --now docker
+docker --version
+docker buildx version
+echo "== Done =="

package/scripts/install.sh

@@ -314,6 +314,7 @@ _ensure_path_in_profile() {
 # Added by baize installer
 fish_add_path -g $HOME/.local/bin
 fish_add_path -g $HOME/baize/bin
+fish_add_path -g $HOME/.local/node/bin
 FISH_EOF
       ok "PATH configured in conf.d/baize.fish"
     fi
@@ -331,15 +332,26 @@ FISH_EOF
     local baize_marker='# baize-managed: bin PATH'
     local baize_bin_export="export PATH=\"\$HOME/baize/bin:\$PATH\""
 
+    # 3. ~/.local/node/bin — Node/npm installed from the npmmirror binary
+    #    mirror (or a bundled Node). Idempotency: dedicated marker.
+    local node_marker='# baize-managed: node bin PATH'
+    local node_bin_export="export PATH=\"\$HOME/.local/node/bin:\$PATH\""
+
     # Write to ~/.profile (login shells + non-interactive shells)
     if ! grep -q 'baize-managed: bin PATH' "$HOME/.profile" 2>/dev/null; then
       printf '\n%s\n%s\n' "$baize_marker" "$baize_bin_export" >> "$HOME/.profile"
     fi
+    if ! grep -q 'baize-managed: node bin PATH' "$HOME/.profile" 2>/dev/null; then
+      printf '\n%s\n%s\n' "$node_marker" "$node_bin_export" >> "$HOME/.profile"
+    fi
     # Write to shell rc file (interactive shells)
     if [ "$shell_rc" != "$HOME/.profile" ]; then
       if ! grep -q 'baize-managed: bin PATH' "$shell_rc" 2>/dev/null; then
         printf '\n%s\n%s\n' "$baize_marker" "$baize_bin_export" >> "$shell_rc"
       fi
+      if ! grep -q 'baize-managed: node bin PATH' "$shell_rc" 2>/dev/null; then
+        printf '\n%s\n%s\n' "$node_marker" "$node_bin_export" >> "$shell_rc"
+      fi
     fi
 
     ok "PATH configured in $(basename "$shell_rc")"
@@ -347,6 +359,7 @@ FISH_EOF
 
   # Export for the running script (so baize init can find binaries)
   export PATH="$HOME/.local/bin:$HOME/baize/bin:$PATH"
+  export PATH="$HOME/.local/node/bin:$PATH"
 }
 
 # ── Install Baize ─────────────────────────────────────────────

package/skills/web-console/public/app.js

@@ -972,6 +972,13 @@ async function switchRuntimeFromAdmin(basePath) {
     setAdminMsg('未登录或会话过期，请重新登录', true);
     return;
   }
+  if (body.installing) {
+    // D39: runtime binary missing — async install in progress, poll status.
+    const label = target === 'claude' ? 'Claude Code' : 'Codex';
+    setAdminMsg(`正在安装 ${label}（下载约 340MB，首次约 2-5 分钟）...`);
+    pollRuntimeInstall(basePath, target);
+    return;
+  }
   if (body.success) {
     const restartNote = body.restart?.restarted ? '，会话已自动重启' : (body.restart?.reason === 'no_session' ? '（无运行中会话）' : '');
     setAdminMsg(`已切换到 ${target}${restartNote}`);
@@ -981,6 +988,165 @@ async function switchRuntimeFromAdmin(basePath) {
   loadAdminStatus(basePath);
 }
 
+async function pollRuntimeInstall(basePath, runtime) {
+  const label = runtime === 'claude' ? 'Claude Code' : 'Codex';
+  let attempts = 0;
+  while (attempts < 400) { // ~20 min cap
+    attempts += 1;
+    const { status, body } = await adminFetch(basePath, `/api/admin/runtime/install-status?runtime=${encodeURIComponent(runtime)}`);
+    if (status !== 200 || !body) {
+      await new Promise((r) => setTimeout(r, 3000));
+      continue;
+    }
+    if (body.status === 'done') {
+      setAdminMsg(`${label} 安装完成，已切换到 ${runtime}，会话重启中`);
+      renderRuntimeInstallBadges(basePath);
+      loadAdminStatus(basePath);
+      return;
+    }
+    if (body.status === 'failed') {
+      setAdminMsg(`${label} 安装失败：${body.error || '未知错误'}（可稍后重试）`, true);
+      renderRuntimeInstallBadges(basePath);
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  setAdminMsg(`${label} 安装仍在进行，请稍后查看状态`, true);
+}
+
+// D41: per-runtime install badges (installed/version/failure) + install button
+// (reuses D39 async install) + a warning when the ACTIVE runtime is missing.
+async function renderRuntimeInstallBadges(basePath) {
+  const badgeClaude = document.getElementById('rt-install-claude');
+  const badgeCodex = document.getElementById('rt-install-codex');
+  const warnEl = document.getElementById('rt-install-warning');
+  if (!badgeClaude || !badgeCodex) return;
+  const { status, body } = await adminFetch(basePath, '/api/admin/diagnostics');
+  if (status !== 200 || !body?.runtimes) return;
+  const rt = body.runtime?.runtime || 'claude';
+  const rtInfo = body.runtimes || {};
+  const badge = (name, info) => {
+    const el = name === 'claude' ? badgeClaude : badgeCodex;
+    if (info.installed) {
+      el.innerHTML = `<span class="channel-state ok">✅ 已安装${info.version ? ` ${escapeHtml(info.version)}` : ''}</span>`;
+      return;
+    }
+    const reason = info.installError ? `（上次失败：${escapeHtml(info.installError)}）` : '';
+    el.innerHTML = `<span class="channel-state warn">❌ 未安装${reason}</span> `
+      + `<button type="button" class="small-btn" data-install="${name}">安装</button>`;
+  };
+  badge('claude', rtInfo.claude || {});
+  badge('codex', rtInfo.codex || {});
+  // Warn when the active runtime CLI is missing — the session cannot start.
+  if (warnEl) {
+    const active = rtInfo[rt] || {};
+    if (!active.installed) {
+      const label = rt === 'claude' ? 'Claude Code' : 'Codex';
+      warnEl.innerHTML = `<span class="channel-state warn">⚠ 会话无法启动：当前运行时 ${escapeHtml(rt)} 未安装——请点上方[安装]或[切换到 ${rt === 'claude' ? 'codex' : 'claude'}]</span>`;
+    } else {
+      warnEl.textContent = '';
+    }
+  }
+  // Wire install buttons (delegate once per render is fine — small page).
+  document.querySelectorAll('[data-install]').forEach((btn) => {
+    btn.onclick = async () => {
+      const r = btn.getAttribute('data-install');
+      btn.disabled = true;
+      btn.textContent = '安装中...';
+      setAdminMsg(`正在安装 ${r === 'claude' ? 'Claude Code' : 'Codex'}（下载约 340MB，首次约 2-5 分钟）...`);
+      const rr = await adminFetch(basePath, '/api/admin/runtime', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ runtime: r }),
+      });
+      if (rr.body?.installing) {
+        pollRuntimeInstall(basePath, r);
+      } else if (rr.body?.success) {
+        setAdminMsg(`${r === 'claude' ? 'Claude Code' : 'Codex'} 已安装`);
+        renderRuntimeInstallBadges(basePath);
+      } else {
+        setAdminMsg(`安装触发失败：${rr.body?.error || '未知错误'}`, true);
+        btn.disabled = false;
+        btn.textContent = '安装';
+      }
+    };
+  });
+}
+
+// D42: environment status card — gaps in plain language, one-click re-init,
+// failure reason (human) + in-web log.
+async function renderEnvironmentStatus(basePath) {
+  const badge = document.getElementById('env-state-badge');
+  const detail = document.getElementById('env-state-detail');
+  const actions = document.getElementById('env-reinit-actions');
+  if (!badge || !detail) return;
+  const { status, body } = await adminFetch(basePath, '/api/admin/environment/status');
+  if (status !== 200 || !body) { detail.textContent = '环境状态检测失败'; return; }
+  const rt = body.runtime || 'codex';
+  const claudeOk = body.runtimes?.claude?.installed ? '✅' : '❌';
+  const codexOk = body.runtimes?.codex?.installed ? '✅' : '❌';
+  const initOk = body.initComplete ? '✅' : '❌';
+  if (body.ready) {
+    badge.textContent = '✅ 就绪';
+    badge.className = 'channel-state ok';
+    detail.innerHTML = `运行时 ${escapeHtml(rt)} · CLI ${rt === 'claude' ? claudeOk : codexOk} · 初始化 ${initOk}`;
+    actions.style.display = 'none';
+    return;
+  }
+  badge.textContent = '⚠ 未就绪';
+  badge.className = 'channel-state warn';
+  const gapLines = (body.gaps || []).map((g) => `<li>${escapeHtml(g)}</li>`).join('');
+  detail.innerHTML = `<ul style="margin:4px 0;padding-left:18px">${gapLines || '<li>环境未就绪</li>'}</ul>`
+    + `<span style="font-size:12px;opacity:.8">Codex ${codexOk} · Claude ${claudeOk} · 初始化 ${initOk}</span>`;
+  actions.style.display = 'block';
+  renderReinitStatus(basePath);
+}
+
+async function renderReinitStatus(basePath) {
+  const prog = document.getElementById('env-reinit-progress');
+  const logBox = document.getElementById('env-reinit-log');
+  const logBody = document.getElementById('env-reinit-log-body');
+  if (!prog) return;
+  const { status, body } = await adminFetch(basePath, '/api/admin/environment/reinit-status');
+  if (status !== 200 || !body || body.status === 'idle') { prog.textContent = ''; return; }
+  if (body.status === 'running') {
+    prog.textContent = '正在重新初始化（补全环境配置，约 1-2 分钟）...';
+    logBox.style.display = 'none';
+  } else if (body.status === 'done') {
+    prog.innerHTML = '<span class="channel-state ok">✅ 初始化完成，环境已就绪，会话拉起中...</span>';
+    logBox.style.display = 'none';
+    setTimeout(() => renderEnvironmentStatus(basePath), 5000);
+    loadAdminStatus(basePath);
+  } else if (body.status === 'failed') {
+    prog.innerHTML = `<span class="channel-state warn">⚠ 初始化失败：${escapeHtml(body.human || '未知原因')}</span>`;
+    if (body.logTail) {
+      logBody.textContent = body.logTail;
+      logBox.style.display = 'block';
+    }
+  }
+}
+
+function startReinitFromAdmin(basePath) {
+  const btn = document.getElementById('btn-env-reinit');
+  if (!btn) return;
+  btn.disabled = true;
+  btn.textContent = '重新初始化中...';
+  setAdminMsg('正在重新初始化环境（幂等，不会清除已有数据）...');
+  adminFetch(basePath, '/api/admin/environment/reinit', { method: 'POST' }).then(({ body }) => {
+    if (!body?.reinit) { setAdminMsg('重新初始化未能启动', true); btn.disabled = false; btn.textContent = '重新初始化（修复环境）'; return; }
+    const iv = setInterval(async () => {
+      const { status, body: b } = await adminFetch(basePath, '/api/admin/environment/reinit-status');
+      if (status !== 200 || !b) return;
+      renderReinitStatus(basePath);
+      if (b.status === 'done' || b.status === 'failed') {
+        clearInterval(iv);
+        btn.disabled = false;
+        btn.textContent = '重新初始化（修复环境）';
+      }
+    }, 3000);
+  });
+}
+
 async function restartSessionFromAdmin(basePath) {
   setAdminMsg('正在重启 agent 会话...');
   const { body } = await adminFetch(basePath, '/api/admin/restart', { method: 'POST' });
@@ -2319,6 +2485,16 @@ async function renderDiagnostics(basePath) {
   }
   const rt = body.runtime || {};
   if (stateEl) stateEl.textContent = `runtime: ${escapeHtml(rt.runtime || '?')}`;
+  // init state (D40): surface init failure so the user can act in-browser
+  const init = body.init || null;
+  if (init && init.status === 'failed') {
+    const initEl = document.getElementById('diag-init-state');
+    if (initEl) {
+      initEl.innerHTML = '<span class="channel-state warn">⚠ 初始化未完成：'
+        + `${escapeHtml(init.error || '未知原因')}</span> —— 请在「模型设置」安装/重试对应 runtime（Claude Code 或 Codex），然后重启 agent 会话。`
+        + (init.at ? ` <small>(${escapeHtml(String(init.at))})</small>` : '');
+    }
+  }
   // runtime + auth
   const auth = body.auth || {};
   const authLine = [];
@@ -2382,6 +2558,8 @@ function showAppView(basePath, view) {
     schedulerView.hidden = true;
     modelView.hidden = false;
     renderDiagnostics(basePath);
+    renderRuntimeInstallBadges(basePath);
+    renderEnvironmentStatus(basePath);
     setNav(navModel, [navChat, navChannels, navA2a, navScheduler]);
     renderModelSettings(basePath);
   } else if (view === 'channels') {
@@ -2587,6 +2765,7 @@ function initViews(basePath) {
   });
   document.getElementById('btn-switch-runtime').addEventListener('click', () => switchRuntimeFromAdmin(basePath));
   document.getElementById('btn-restart-session').addEventListener('click', () => restartSessionFromAdmin(basePath));
+  document.getElementById('btn-env-reinit')?.addEventListener('click', () => startReinitFromAdmin(basePath));
 
   document.getElementById('form-provider').addEventListener('submit', (e) => {
     e.preventDefault();

package/skills/web-console/public/index.html

@@ -109,14 +109,27 @@
         <!-- Section 0: Current connection summary -->
         <section class="settings-section">
           <div class="settings-section-head">
-            <h2>当前连接状态</h2>
-            <p>两个运行时当前生效的接入方式，一目了然。</p>
+            <h2>运行时与连接</h2>
+            <p>环境未就绪时，请先完成「环境初始化」（可自动安装缺失组件并补全配置），再配置运行时接入方式。</p>
+          </div>
+          <div class="settings-card">
+            <div class="card-title">环境初始化 <span class="channel-state" id="env-state-badge"></span></div>
+            <div class="cred-state" id="env-state-detail" aria-live="polite">检测中...</div>
+            <div class="settings-actions" id="env-reinit-actions" style="display:none">
+              <button type="button" class="btn btn-primary" id="btn-env-reinit">重新初始化（一键修复环境）</button>
+            </div>
+            <div class="cred-state" id="env-reinit-progress" aria-live="polite"></div>
+            <details id="env-reinit-log" style="display:none;margin-top:8px">
+              <summary>查看初始化日志</summary>
+              <pre style="font-size:12px;background:var(--bg-2,#1a1a1a);padding:8px;border-radius:6px;white-space:pre-wrap;max-height:300px;overflow:auto" id="env-reinit-log-body"></pre>
+            </details>
           </div>
           <div class="settings-card">
             <div class="conn-summary" id="conn-summary" role="status" aria-live="polite">
-              <div class="conn-summary-row"><span class="conn-summary-name">Codex</span><span class="conn-summary-detail" id="summary-codex">加载中...</span></div>
-              <div class="conn-summary-row"><span class="conn-summary-name">Claude</span><span class="conn-summary-detail" id="summary-claude">加载中...</span></div>
+              <div class="conn-summary-row"><span class="conn-summary-name">Codex</span><span class="conn-summary-detail" id="summary-codex">加载中...</span><span class="runtime-install-badge" id="rt-install-codex"></span></div>
+              <div class="conn-summary-row"><span class="conn-summary-name">Claude</span><span class="conn-summary-detail" id="summary-claude">加载中...</span><span class="runtime-install-badge" id="rt-install-claude"></span></div>
             </div>
+            <div class="cred-state" id="rt-install-warning" aria-live="polite"></div>
             <div class="settings-actions">
               <button type="button" class="btn btn-outline" id="btn-switch-runtime">切换运行时</button>
               <button type="button" class="btn btn-outline" id="btn-restart-session">重启 agent 会话</button>
@@ -239,6 +252,7 @@
           <div class="settings-card">
             <div class="card-title">运行时与认证 <span class="channel-state" id="diag-runtime-state"></span></div>
             <div class="cred-state" id="diag-runtime" aria-live="polite">加载中...</div>
+            <div class="cred-state" id="diag-init-state" aria-live="polite"></div>
           </div>
           <div class="settings-card">
             <div class="card-title">服务状态 <button type="button" class="small-btn" id="btn-diag-refresh">刷新</button></div>

package/skills/web-console/scripts/a2a-admin.js

@@ -328,6 +328,39 @@ function npmInstallDeps(cwd) {
   });
 }
 
+/** Rebuild native modules after --ignore-scripts install (D44).
+ * --ignore-scripts skips postinstall, so better-sqlite3 etc. never compile
+ * their native binary. Rebuilding runs node-gyp only (no vendor lifecycle
+ * scripts) — the security stance is kept while the module becomes loadable. */
+function rebuildNativeDeps(cwd) {
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['rebuild', '--build-from-source', '--no-audit', '--no-fund'], {
+      cwd, env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    let settled = false;
+    child.stderr.on('data', (d) => { stderr += String(d); });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGTERM');
+      resolve({ ok: false, error: `npm rebuild 超时（${Math.round(NPM_INSTALL_TIMEOUT_MS / 1000)}s）` });
+    }, NPM_INSTALL_TIMEOUT_MS);
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, error: err.message });
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(code === 0 ? { ok: true } : { ok: false, error: (stderr.trim() || `exit ${code}`).slice(-500) });
+    });
+  });
+}
+
 /**
  * Install @baize-ai/baize-a2a from an uploaded .tar.gz (D25 私有交付).
  * Pipeline: entry listing + path-safety vetting (no `..`/absolute/links) →
@@ -342,6 +375,7 @@ export async function installA2aTarball(tarballPath, {
   skillsDir = defaultSkillsDir(),
   componentsFile: componentsPath = componentsFile(),
   installDeps = npmInstallDeps,
+  rebuildDeps = rebuildNativeDeps,
   originalName = null,
 } = {}) {
   const file = String(tarballPath || '');
@@ -401,6 +435,13 @@ export async function installA2aTarball(tarballPath, {
     fs.rmSync(targetDir, { recursive: true, force: true });
     return { ok: false, error: `npm install 失败: ${depResult.error}` };
   }
+  // D44: --ignore-scripts skipped native compilation — rebuild modules so
+  // better-sqlite3 etc. are loadable (node-gyp only, no vendor scripts).
+  const rebuildResult = await rebuildDeps(targetDir);
+  if (!rebuildResult.ok) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    return { ok: false, error: `native 模块重建失败: ${rebuildResult.error}` };
+  }
   const components = readComponents(componentsPath);
   components.a2a = {
     version: pkg.version,

package/skills/web-console/scripts/diagnostics.js

@@ -126,13 +126,57 @@ function readErrors() {
   return errors;
 }
 
+/** Init state from .baize/init-state.json (written by entrypoint/init). */
+function readInitState() {
+  try {
+    const p = path.join(process.env.BAIZE_DIR || path.join(os.homedir(), 'baize'), '.baize', 'init-state.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch { return null; }
+}
+
+/** Detect whether a runtime CLI is installed (PATH) + its version.
+ * Note: gate on `command -v` — a plain `<bin> --version | head -1` pipeline
+ * exits with head's status (0), so a missing binary would read as installed. */
+function checkRuntimeBinary(bin) {
+  return new Promise((resolve) => {
+    execFile('sh', ['-c', `command -v ${bin} >/dev/null 2>&1 && ${bin} --version 2>/dev/null | head -1`], { timeout: 5000 }, (err, stdout) => {
+      resolve({ installed: !err, version: err ? null : (String(stdout).trim().split('\n')[0] || null) });
+    });
+  });
+}
+
+/** Read the D39 install state file (failure reason from an async web install). */
+function readRuntimeInstallState(runtime) {
+  try {
+    const p = path.join(process.env.BAIZE_DIR || path.join(os.homedir(), 'baize'), '.baize', `runtime-install-${runtime}.json`);
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch { return null; }
+}
+
+/**
+ * Per-runtime install status: installed + version, plus the last install
+ * failure reason (D39 state file) so the console can tell the user exactly
+ * which runtime is missing and why.
+ */
+export async function readRuntimes() {
+  const [claude, codex] = await Promise.all([checkRuntimeBinary('claude'), checkRuntimeBinary('codex')]);
+  const enrich = (status, runtime) => {
+    const st = readRuntimeInstallState(runtime);
+    if (st && st.status === 'failed') status.installError = st.error || null;
+    return status;
+  };
+  return { claude: enrich(claude, 'claude'), codex: enrich(codex, 'codex') };
+}
+
 /** Full diagnostics payload. */
 export async function readDiagnostics() {
-  const [services, sessions] = await Promise.all([readServices(), readSessions()]);
+  const [services, sessions, runtimes] = await Promise.all([readServices(), readSessions(), readRuntimes()]);
   return {
     success: true,
     at: new Date().toISOString(),
     runtime: readRuntime(),
+    init: readInitState(),
+    runtimes,
     services,
     sessions,
     auth: readAuth(),

package/skills/web-console/scripts/server.js

@@ -15,7 +15,7 @@ import crypto from 'crypto';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
-import { spawn } from 'child_process';
+import { spawn, execFile } from 'child_process';
 import Database from 'better-sqlite3';
 import { fileURLToPath } from 'url';
 import {
@@ -834,9 +834,122 @@ app.get('/api/admin/diagnostics', async (req, res) => {
   }
 });
 
+// ── Runtime install (D39): async install when the target runtime binary is
+// missing — detached spawn (900s timeout + 2 retries), then auto-switch.
+// No task framework: a state JSON + log file are the status.
+const RUNTIME_INSTALL = {
+  claude: { bin: 'claude', cmd: 'curl -fsSL https://claude.ai/install.sh | bash' },
+  codex:  { bin: 'codex',  cmd: 'npm install -g @openai/codex' },
+};
+
+function runtimeInstallStateFile(runtime) {
+  return path.join(BAIZE_DIR, '.baize', `runtime-install-${runtime}.json`);
+}
+function runtimeInstallLogFile(runtime) {
+  return path.join(BAIZE_DIR, '.baize', `runtime-install-${runtime}.log`);
+}
+function readRuntimeInstallState(runtime) {
+  try { return JSON.parse(fs.readFileSync(runtimeInstallStateFile(runtime), 'utf8')); } catch { return null; }
+}
+function writeRuntimeInstallState(runtime, state) {
+  try {
+    fs.mkdirSync(path.join(BAIZE_DIR, '.baize'), { recursive: true });
+    fs.writeFileSync(runtimeInstallStateFile(runtime), JSON.stringify(state));
+  } catch { /* non-fatal */ }
+}
+
+function runtimeInstalled(runtime) {
+  const bin = RUNTIME_INSTALL[runtime]?.bin;
+  if (!bin) return Promise.resolve(true); // unknown runtime: don't gate
+  return new Promise((resolve) => {
+    execFile('sh', ['-c', `command -v ${bin}`], { timeout: 5000 }, (err) => resolve(!err));
+  });
+}
+
+function startRuntimeInstall(runtime) {
+  const spec = RUNTIME_INSTALL[runtime];
+  if (!spec) return false;
+  const cur = readRuntimeInstallState(runtime);
+  if (cur && cur.status === 'installing') {
+    // Stale-guard: a crashed/killed installer (OOM, container restart) would
+    // otherwise wedge the target forever. Budget = 3 attempts x 900s + 240s
+    // switch + buffer.
+    const started = Date.parse(cur.startedAt || '');
+    if (Number.isNaN(started) || Date.now() - started < 55 * 60 * 1000) {
+      return false; // genuinely running (or recent) — don't duplicate
+    }
+  }
+
+  writeRuntimeInstallState(runtime, { status: 'installing', startedAt: new Date().toISOString() });
+
+  const script = `
+const { spawn } = require('child_process');
+const fs = require('fs');
+const LOG = ${JSON.stringify(runtimeInstallLogFile(runtime))};
+const STATE = ${JSON.stringify(runtimeInstallStateFile(runtime))};
+const CMD = ${JSON.stringify(spec.cmd)};
+const RUNTIME = ${JSON.stringify(runtime)};
+const log = (s) => { try { fs.appendFileSync(LOG, s + '\\n'); } catch {} };
+const run = (cmd, timeoutMs) => new Promise((resolve, reject) => {
+  const child = spawn('bash', ['-c', cmd], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; if (out.length > 4000) { log(out); out = ''; } });
+  child.stderr.on('data', (d) => { out += d; if (out.length > 4000) { log(out); out = ''; } });
+  const killTree = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch {} } };
+  const t = setTimeout(() => { killTree(); reject(new Error('timeout ' + timeoutMs + 'ms')); }, timeoutMs);
+  child.on('close', (code) => { clearTimeout(t); if (out) log(out); code === 0 ? resolve() : reject(new Error('exit ' + code)); });
+});
+const update = (s) => { try { fs.writeFileSync(STATE, JSON.stringify(s)); } catch {} };
+(async () => {
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    log('[install] attempt ' + attempt + ' starting: ' + CMD);
+    try {
+      await run(CMD, 900000);
+      log('[install] installed OK');
+      break;
+    } catch (e) {
+      log('[install] attempt ' + attempt + ' failed: ' + e.message);
+      if (attempt === 3) {
+        update({ status: 'failed', error: e.message, doneAt: new Date().toISOString() });
+        process.exit(1);
+      }
+    }
+  }
+  log('[install] switching runtime to ' + RUNTIME);
+  try {
+    await run('baize runtime ' + RUNTIME + ' --no-validate', 240000);
+    update({ status: 'done', doneAt: new Date().toISOString() });
+    log('[install] switch complete');
+  } catch (e) {
+    update({ status: 'failed', error: 'switch failed: ' + e.message, doneAt: new Date().toISOString() });
+    log('[install] switch failed: ' + e.message);
+  }
+})();
+`;
+  try {
+    const scriptPath = path.join(BAIZE_DIR, '.baize', `runtime-install-${runtime}.cjs`);
+    fs.mkdirSync(path.join(BAIZE_DIR, '.baize'), { recursive: true });
+    fs.writeFileSync(scriptPath, script);
+    const child = spawn(process.execPath, [scriptPath], { detached: true, stdio: 'ignore' });
+    child.unref();
+    return true;
+  } catch {
+    writeRuntimeInstallState(runtime, null); // don't leave a stuck 'installing'
+    return false;
+  }
+}
+
 app.post('/api/admin/runtime', async (req, res) => {
   try {
-    const result = await switchRuntime(req.body?.runtime);
+    const runtime = req.body?.runtime;
+    if (!['claude', 'codex'].includes(runtime)) {
+      return res.status(400).json({ success: false, error: `Invalid runtime: ${runtime}` });
+    }
+    if (!(await runtimeInstalled(runtime))) {
+      startRuntimeInstall(runtime);
+      return res.json({ success: true, installing: true, runtime });
+    }
+    const result = await switchRuntime(runtime);
     if (result.success) result.restart = await restartAgentSession();
     res.status(result.success ? 200 : 400).json(result);
   } catch (err) {
@@ -844,6 +957,181 @@ app.post('/api/admin/runtime', async (req, res) => {
   }
 });
 
+// ── Environment status + one-click re-init (D42) ───────────────────────────
+// Web is the only recovery surface: detect init gaps, trigger the idempotent
+// `baize init`, and surface failure reasons (human summary + raw log) in-browser.
+const REINIT_LOG = path.join(BAIZE_DIR, '.baize', 'reinit.log');
+const REINIT_STATE = path.join(BAIZE_DIR, '.baize', 'reinit.json');
+
+function readReinitState() {
+  try { return JSON.parse(fs.readFileSync(REINIT_STATE, 'utf8')); } catch { return null; }
+}
+
+function runtimeBinInstalled(bin) {
+  return new Promise((resolve) => {
+    execFile('sh', ['-c', `command -v ${bin} >/dev/null 2>&1`], { timeout: 5000 }, (err) => resolve(!err));
+  });
+}
+
+/** Init completeness: config.json with a runtime. The instruction file may be
+ * in the split-instruction pending-migration state without blocking the
+ * session (Guardian still launches), so it is not a readiness condition. */
+function initComplete() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(BAIZE_DIR, '.baize', 'config.json'), 'utf8'));
+    return !!(cfg && cfg.runtime);
+  } catch { return false; }
+}
+
+function readCurrentRuntime() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(BAIZE_DIR, '.baize', 'config.json'), 'utf8'));
+    if (cfg && (cfg.runtime === 'codex' || cfg.runtime === 'claude')) return cfg.runtime;
+  } catch {}
+  return 'codex'; // mainland-safe default (init falls back to claude otherwise)
+}
+
+/** Map common failure text to a human-readable (Chinese) summary. */
+function humanError(summary) {
+  const map = [
+    [/claude\.ai/i, '无法连接 Claude 官方服务（大陆不可达）——请使用 Codex 或第三方兼容端点'],
+    [/ETIMEDOUT|ECONNRESET|ECONNREFUSED|network.*(timeout|refused)|i\/o timeout/i, '网络连接失败（超时/被拒绝）——请检查网络后重试'],
+    [/registry\.npmjs\.org|npmmirror/i, '无法连接 npm 源——请检查网络或 npm 源配置'],
+    [/Failed to install (Codex|claude)|Failed to install/i, '运行时 CLI 安装失败——请检查网络后重试'],
+    [/permission denied|EACCES/i, '权限不足——请检查目录权限后重试'],
+    [/command not found/i, '缺少必要命令——请检查环境'],
+  ];
+  for (const [re, msg] of map) {
+    if (re.test(summary)) return msg;
+  }
+  return null;
+}
+
+function startReinit() {
+  const cur = readReinitState();
+  if (cur && cur.status === 'running') {
+    // Stale-guard: a crashed/killed reinit would otherwise wedge the button
+    // forever. Budget = init install window (900s) + buffer.
+    const started = Date.parse(cur.startedAt || '');
+    if (Number.isNaN(started) || Date.now() - started < 30 * 60 * 1000) {
+      return false;
+    }
+  }
+  const runtime = readCurrentRuntime();
+  const now = new Date().toISOString();
+  try {
+    fs.mkdirSync(path.join(BAIZE_DIR, '.baize'), { recursive: true });
+    fs.writeFileSync(REINIT_STATE, JSON.stringify({ status: 'running', runtime, startedAt: now }));
+    fs.writeFileSync(REINIT_LOG, `[reinit] started at ${now} (runtime=${runtime})
+`);
+  } catch { return false; }
+  const script = `
+const { spawn } = require('child_process');
+const fs = require('fs');
+const LOG = ${JSON.stringify(REINIT_LOG)};
+const STATE = ${JSON.stringify(REINIT_STATE)};
+const RUNTIME = ${JSON.stringify(runtime)};
+const log = (s) => { try { fs.appendFileSync(LOG, s + '\\n'); } catch {} };
+const run = (cmd, timeoutMs) => new Promise((resolve, reject) => {
+  const child = spawn('bash', ['-c', cmd], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; if (out.length > 8000) { log(out); out = ''; } });
+  child.stderr.on('data', (d) => { out += d; if (out.length > 8000) { log(out); out = ''; } });
+  const killTree = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch {} } };
+  const t = setTimeout(() => { killTree(); reject(new Error('timeout ' + timeoutMs + 'ms')); }, timeoutMs);
+  child.on('close', (code) => { clearTimeout(t); if (out) log(out); code === 0 ? resolve() : reject(new Error('exit ' + code)); });
+});
+const update = (s) => { try { fs.writeFileSync(STATE, JSON.stringify(s)); } catch {} };
+(async () => {
+  log('[reinit] running baize init (idempotent)...');
+  try {
+    await run('baize init --yes --quiet --runtime ' + RUNTIME, 900000);
+    log('[reinit] init OK');
+    update({ status: 'done', doneAt: new Date().toISOString(), runtime: RUNTIME });
+  } catch (e) {
+    log('[reinit] init failed: ' + e.message);
+    update({ status: 'failed', error: e.message, doneAt: new Date().toISOString(), runtime: RUNTIME });
+  }
+})();
+`;
+  try {
+    const scriptPath = path.join(BAIZE_DIR, '.baize', 'reinit.cjs');
+    fs.writeFileSync(scriptPath, script);
+    const child = spawn(process.execPath, [scriptPath], { detached: true, stdio: 'ignore' });
+    child.unref();
+    return true;
+  } catch {
+    try { fs.writeFileSync(REINIT_STATE, JSON.stringify({ status: 'failed', error: '无法启动初始化进程', doneAt: new Date().toISOString() })); } catch {}
+    return false;
+  }
+}
+
+// Environment status: gaps in plain language + readiness.
+app.get('/api/admin/environment/status', async (req, res) => {
+  try {
+    const [claude, codex] = await Promise.all([runtimeBinInstalled('claude'), runtimeBinInstalled('codex')]);
+    const runtime = readCurrentRuntime();
+    const initDone = initComplete();
+    const gaps = [];
+    if (!claude && !codex) gaps.push('运行时 CLI（Claude Code / Codex）均未安装');
+    else if (runtime === 'claude' && !claude) gaps.push('当前运行时 Claude Code 未安装');
+    else if (runtime === 'codex' && !codex) gaps.push('当前运行时 Codex 未安装');
+    if (!initDone) gaps.push('环境初始化未完成（配置缺失）');
+    res.json({
+      success: true,
+      runtime,
+      runtimes: { claude: { installed: claude }, codex: { installed: codex } },
+      initComplete: initDone,
+      ready: (runtime === 'claude' ? claude : codex) && initDone,
+      gaps,
+    });
+  } catch (err) {
+    jsonError(res, err);
+  }
+});
+
+// Trigger the idempotent re-init (async; poll reinit-status).
+app.post('/api/admin/environment/reinit', (req, res) => {
+  try {
+    const started = startReinit();
+    res.json({ success: true, reinit: started });
+  } catch (err) {
+    jsonError(res, err);
+  }
+});
+
+// Re-init progress/result + human-readable failure reason + log tail.
+app.get('/api/admin/environment/reinit-status', (req, res) => {
+  try {
+    const state = readReinitState();
+    if (!state) return res.json({ success: true, status: 'idle' });
+    let logTail = '';
+    try { logTail = fs.readFileSync(REINIT_LOG, 'utf8').split('\n').filter(Boolean).slice(-20).join('\n'); } catch {}
+    const human = state.status === 'failed' ? (humanError((state.error || '') + '\n' + logTail) || '初始化失败（详见日志）') : null;
+    res.json({ success: true, status: state.status, error: state.error, human, logTail, runtime: state.runtime });
+  } catch (err) {
+    jsonError(res, err);
+  }
+});
+
+app.get('/api/admin/runtime/install-status', (req, res) => {
+  try {
+    const runtime = req.query?.runtime;
+    if (!['claude', 'codex'].includes(runtime)) {
+      return res.status(400).json({ success: false, error: `Invalid runtime: ${runtime}` });
+    }
+    const state = readRuntimeInstallState(runtime);
+    if (!state) return res.json({ success: true, status: 'idle' });
+    let logTail = '';
+    try {
+      logTail = fs.readFileSync(runtimeInstallLogFile(runtime), 'utf8').split('\n').filter(Boolean).slice(-10).join('\n');
+    } catch {}
+    res.json({ success: true, status: state.status, error: state.error, logTail });
+  } catch (err) {
+    jsonError(res, err);
+  }
+});
+
 app.post('/api/admin/restart', async (req, res) => {
   try {
     res.json(await restartAgentSession());