@baize-ai/core 0.3.15 → 0.3.17

package/docs/ops-runbook.md

@@ -0,0 +1,161 @@
+# Baize Agent 容器运维排查手册
+
+> 适用：docker 部署的 baize agent（`baize-core` 镜像）。
+> 原则：先只读诊断定位，再修改；生产环境每步执行前确认。
+
+---
+
+## 1. 症状：AI main 会话起不来
+
+**表现**：agent 不再响应任务；`web-console` 可能还活着，但调度/消息链路断了。
+
+**"main 会话"是什么**：AI 主循环（Claude Code / Codex）跑在持久 **tmux 会话**里
+（`claude-main` / `codex-main`），由 `activity-monitor`（Guardian 看门狗）负责拉起，
+`scheduler` 依赖它收发消息。会话没了 = 看门狗没拉起或拉起失败。
+
+---
+
+## 2. 快速排查流程（只读，从外到内）
+
+```bash
+# ① 容器状态（是否在跑 / 重启次数）
+docker ps -a | grep -i baize
+
+# ② pm2 服务（web-console / scheduler / c4-dispatcher / activity-monitor）
+docker exec <容器名> pm2 list
+
+# ③ tmux 会话（main 会话在不在）
+docker exec <容器名> bash -lc "tmux ls"
+
+# ④ 看门狗日志（核心——Guardian 为什么没拉起）
+docker exec <容器名> bash -lc "pm2 logs activity-monitor --lines 30 --nostream"
+
+# ⑤ 调度器日志
+docker exec <容器名> bash -lc "pm2 logs scheduler --lines 20 --nostream"
+
+# ⑥ 初始化状态（runtime 装没装完）
+docker exec <容器名> bash -lc "cat ~/baize/init-state.json 2>/dev/null"
+```
+
+**日志判读**：
+
+| 日志 | 含义 | 下一步 |
+|---|---|---|
+| `spawnSync codex ENOENT` / `spawnSync claude ENOENT` | **PATH 问题**（可执行文件不在 PATH）→ 见 §3 | §3 |
+| `tmux ls` 无会话 + pm2 正常 | 看门狗没触发或拉起失败 | ④ 看 Guardian 日志 |
+| `init-state.json` 失败 | 初始化未完成（runtime/模型未配置） | web 控制台模型设置重新安装 |
+| tmux 会话在但卡住 | Claude/Codex 等输入 / 认证过期 / API 错误 | `tmux attach -t claude-main` 看输出 |
+
+---
+
+## 3. 本次实战：PATH 污染导致 `spawnSync codex ENOENT`
+
+### 现象
+
+```
+activity-monitor: Guardian: Failed to start Codex: spawnSync codex ENOENT
+scheduler:       Waiting for agent runtime (offline or stopped)...
+tmux ls:         no server running on /tmp/tmux-1001/default
+```
+
+### 诊断证据链
+
+```bash
+# ① codex symlink 在不在（npm 全局 bin 通常是 symlink）
+docker exec baize-2 bash -lc "ls -la ~/.npm-global/bin/codex; readlink -f ~/.npm-global/bin/codex"
+# → lrwxrwxrwx ... codex -> ../lib/node_modules/@openai/codex/bin/codex.js   （symlink 完好）
+
+# ② codex 二进制本身能不能跑（关键——区分"二进制坏了" vs "PATH 找不到"）
+docker exec baize-2 bash -lc "~/.npm-global/bin/codex --version; echo EXIT=\$?"
+# → codex-cli 0.153.2 / EXIT=0   （二进制完好！）
+
+# ③ pm2 进程实际 PATH（Guardian 用它 spawn codex）
+docker exec baize-2 bash -lc "cat /proc/\$(pgrep -f 'activity-monitor' | head -1)/environ | tr '\0' '\n' | grep '^PATH='"
+# → PATH=...codex-path:/home/baize/baize/bin:...（★ 没有 ~/.npm-global/bin）
+
+# ④ 谁污染了 PATH（login shell 的 profile）
+docker exec baize-2 bash -lc "grep -n 'PATH' ~/.bashrc ~/.profile ~/.bash_profile 2>/dev/null"
+# → .bashrc/.profile 里有 export PATH="/home/baize/baize/bin:$PATH"
+```
+
+**判定**：`codex` 二进制完好但 **pm2 进程 PATH 缺 `~/.npm-global/bin`**（codex symlink
+所在目录）→ `spawnSync codex` 找不到 → ENOENT。
+
+### 根因
+
+1. **PATH 被污染**：`~/.bashrc`/`~/.profile` 前置 `baize/bin` + codex npm 包
+   postinstall 前插 vendor 路径，把 `~/.npm-global/bin` 挤掉。
+2. **坏环境被固化**：在污染 PATH 的 shell 里执行过 `pm2 start`/`pm2 save`，
+   pm2 dump 保存了坏环境，之后 pm2 进程一直继承（`docker restart` 若走 pm2
+   resurrect 也不会恢复）。
+3. **谁干的**：使用人在容器内让 AI 执行环境类操作（改 profile / 重装 runtime /
+   重跑 pm2）时污染了环境并固化。
+
+### 修复（干净 PATH + --update-env 覆盖 pm2 固化环境）
+
+```bash
+# 用干净 PATH 重启看门狗；--update-env 强制用当前 shell 环境覆盖 pm2 dump
+docker exec -e PATH=/home/baize/.npm-global/bin:/home/baize/.local/bin:/usr/local/bin:/usr/bin:/bin \
+  <容器名> pm2 restart activity-monitor --update-env
+
+# 验证：15s 后会话出现、日志不再 ENOENT
+sleep 15
+docker exec <容器名> bash -lc "tmux ls"
+docker exec <容器名> bash -lc "pm2 logs activity-monitor --lines 6 --nostream"
+```
+
+> `docker exec -e PATH=...` 用 `-e` 注入，避免嵌套引号。
+> 其他 pm2 服务（scheduler 等）若同样 PATH 坏，按同法 `--update-env` 重启。
+
+---
+
+## 4. 预防（如何避免再发生）
+
+### 操作纪律（人和 AI 都要遵守）
+
+1. **容器内操作统一走封装入口**：优先用 web 控制台 / `baize` CLI，避免裸
+   `docker exec ... bash -lc`（login shell 会加载 profile，触发 PATH 污染）。
+2. **禁止手工改 `~/.bashrc` / `~/.profile` 的 PATH**：本次污染源头。若必须加
+   路径，用 `export PATH="$PATH:<新路径>"` **追加**，且绝不动
+   `~/.npm-global/bin` / `~/.local/bin` 两项。
+3. **不在容器内手工 `pm2 save`**：pm2 dump 会固化当时的 PATH 环境；容器重启
+   由 entrypoint 统一注入环境（它会重存 `SYSTEM_PATH`）。
+4. **AI 执行环境修改类操作前先备份**：`cp ~/.bashrc ~/.bashrc.bak`，
+   记录改动 diff，改完验证 `which codex claude baize node` 全部可解析。
+
+### 工程加固（D54 已落地，0.3.17 起）
+
+- **PATH 完整性收敛到 init.js**：`baize init` 每次运行修复 shell profile 完整 bin PATH
+  （`~/.npm-global/bin` + `.local/bin` + `.claude/bin` + `baize/bin` + `.local/node/bin`），
+  幂等 + 存量缺失自动补。裸机/docker/存量升级全部覆盖（docker entrypoint 每次启动跑 init）。
+- **共享 `path-bins.js`**：所有 runtime 二进制 spawn（codex/claude/baize）统一走
+  `completeBinPath()`（子进程 env 补完整 PATH）——登录 shell PATH 污染不再导致 ENOENT。
+- **ecosystem `ENHANCED_PATH` 显式含 `~/.npm-global/bin`**：PM2 服务即使继承残缺 PATH 也能
+  找到 runtime。
+- **Guardian 告警**：连续 3 次启动失败 → 写 `~/baize/activity-monitor/guardian-alert.json`
+  + 日志；恢复后自动清除。静默宕机不再发生。
+- **doctor 检查**：`baize doctor` 新增 PATH 完整性组（`path_incomplete` issue）。
+- install.sh / Dockerfile **不改**（收敛到 init.js）；`--update-env` 从根源安全化。
+
+### 巡检（可选定时）
+
+```bash
+# 检查 main 会话与 PATH 健康度
+docker exec <容器名> bash -lc "tmux ls"
+docker exec <容器名> bash -lc "which codex claude baize node"
+# 告警文件存在 = 有未恢复的连续失败（无文件=健康）
+docker exec <容器名> bash -lc "cat ~/baize/activity-monitor/guardian-alert.json 2>/dev/null"
+# doctor PATH 组
+docker exec <容器名> bash -lc "baize doctor --json" | python3 -c "import json,sys;print(json.load(sys.stdin)['groups']['path'])"
+```
+
+---
+
+## 5. 其他常见问题速查
+
+| 问题 | 快速处理 |
+|---|---|
+| web 控制台打不开 | `pm2 logs web-console`；D51 起检查 `~/.claude/cli/lib` 是否存在（init 部署缺陷已修复，见 0.3.16） |
+| 会话起了但任务不响应 | `tmux attach -t <claude-main\|codex-main>` 看 AI 输出；`pm2 logs scheduler` |
+| 容器一直 restart | `docker logs <容器名>`（entrypoint 崩溃）；检查 `init-state.json` |
+| A2A 端口不通 | `docker exec <容器名> pm2 list` 看 baize-a2a；`ss -tlnp | grep 8443` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baize-ai/core",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "type": "module",
   "description": "Baize (白泽) — autonomous AI agent infrastructure",
   "main": "cli/baize.js",
@@ -46,4 +46,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/scripts/docker-publish.sh

@@ -30,15 +30,21 @@ ACR_NAMESPACE="${ACR_NAMESPACE:-baize01}"
 
 # ── Build ────────────────────────────────────────────────────────────────────
 echo "==> Building baize-core:${VERSION} (from npm @baize-ai/core@${VERSION})"
+# Temp build context: .dockerignore is a whitelist (source stays out of the
+# image), and the optional COPY core.tgz needs a placeholder file present —
+# a temp dir keeps the repo worktree clean.
+BUILD_CTX="$(mktemp -d)"
+trap 'rm -rf "$BUILD_CTX"' EXIT
+cp Dockerfile .dockerignore "$BUILD_CTX"/
+mkdir -p "$BUILD_CTX/templates/pm2" "$BUILD_CTX/docker"
+cp templates/pm2/ecosystem.config.cjs "$BUILD_CTX/templates/pm2/"
+cp docker/entrypoint.sh "$BUILD_CTX/docker/"
+touch "$BUILD_CTX/core.tgz"   # placeholder — registry install ignores it (BAZE_CORE_TARBALL empty)
 docker build \
   --build-arg BAZE_CORE_VERSION="${VERSION}" \
   -t "${GHCR_IMAGE}:${VERSION}" \
   -t "${GHCR_IMAGE}:latest" \
-  .
-  "${BUILD_ARGS[@]}" \
-  -t "${GHCR_IMAGE}:${VERSION}" \
-  -t "${GHCR_IMAGE}:latest" \
-  .
+  "$BUILD_CTX"
 
 if [ -n "${ACR_REGISTRY}" ] && [ -n "${ACR_NAMESPACE}" ]; then
   ACR_IMAGE="${ACR_REGISTRY}/${ACR_NAMESPACE}/baize-core"

package/scripts/pack-release.sh

@@ -11,7 +11,7 @@
 #                                     兼容 web 控制台上传与 `baize add --file` 两种安装）
 #   baize-admin-workspace-<v>.tgz     admin 套件源码：server 源码 + admin-ui 构建产物 +
 #                                     Dockerfile + 部署说明（自建镜像 / 自托管用）
-#   baize-admin-workspace-<v>.tar     docker save 的 admin 镜像（docker load 直接运行，推荐）
+#   baize-admin-workspace-<v>.tar     （可选）docker save 的 admin 镜像——仅 BUILD_ADMIN_DOCKER=1 打包时产出
 #   INSTALL.md                        客户侧安装说明（上传 / --file 安装 + 切集群 + admin 部署）
 #
 # 用法：
@@ -155,8 +155,14 @@ build_admin_tgz() {
   log "    → ${out} ($(size "${out}"))"
 }
 
-# ── 3. Admin Docker 镜像（docker save）──────────────────────────────────────
+# ── 3. Admin Docker 镜像（docker save）——可选 ─────────────────────────────
+# 商业版 admin 默认源码交付（tgz 含 server + 已构建 admin-ui/dist）。
+# 仅当 BUILD_ADMIN_DOCKER=1 时才导出 docker save 镜像（需先构建 baize-admin-workspace:test）。
 save_admin_image() {
+  if [ "${BUILD_ADMIN_DOCKER:-0}" != "1" ]; then
+    step "跳过 admin Docker 镜像导出（源码交付模式；需要时 BUILD_ADMIN_DOCKER=1 重跑）"
+    return 0
+  fi
   step "导出 admin Docker 镜像"
   local image="baize-admin-workspace:test"
   if ! docker image inspect "${image}" >/dev/null 2>&1; then
@@ -231,36 +237,35 @@ baize a2a status    # 期望：集群·在线
 ```bash
 baize a2a disable    # 停 daemon，保留配置与注册数据，模式回 standalone
 ```
+### 方式 A：源码部署（推荐——商业版默认交付形态）
 
-## 三、部署 Admin（控制面）
-
-### 方式 A：Docker 镜像（推荐）
+套件已含 server 源码与**构建好的** `admin-ui/dist`，无需前端构建：
 
 ```bash
-docker load -i baize-admin-workspace-__VERSION__.tar
-docker run -d --name baize-admin -p 8080:8080 \
-  -v baize-admin-data:/data \
-  -e BAIZE_ADMIN_TOKEN='<初始口令>' \
-  baize-admin-workspace:test
+tar xzf baize-admin-workspace-__VERSION__.tgz
+cd baize-admin-workspace-__VERSION__
+npm ci --omit=dev                                 # Node ≥ 20.11
+BAIZE_ADMIN_TOKEN='<初始口令>' BAIZE_ADMIN_DIR=/srv/baize-admin \
+  pm2 start server/src/index.js --name baize-admin  # 或 nohup node server/src/index.js
 ```
 
-- 访问 `http://<主机>:8080`，首次登录：`admin` + 初始口令（日志打印或 `BAIZE_ADMIN_TOKEN`）；
-- 登录后立即修改口令；数据全部落在 `/data` 卷（SQLite 库与签名密钥），务必持久化；
-- 公网部署建议放在 HTTPS 反代后面，`baize a2a enable --admin` 使用对外 HTTPS 地址。
+- API 监听 8080；`BAIZE_ADMIN_DIR` 是数据目录（SQLite/CA/签名钥），必须持久化并提前建目录；
+- 前端 `admin-ui/dist` 是静态产物：用 nginx/Caddy 反代到与 API 同源的根路径；
+- 公网部署必须 `TRUST_PROXY=1`（信任反代 X-Forwarded-For，否则限流按代理 IP 计数）；
+- 首次登录 `admin` + 初始口令（日志打印），登录后到「设置」改口令。
 
-### 方式 B：源码套件（自建镜像 / 自托管）
+### 方式 B：Docker（可选——需自建镜像）
 
 ```bash
-tar xzf baize-admin-workspace-__VERSION__.tgz
-cd baize-admin-workspace-__VERSION__
 docker build -t baize-admin-workspace .          # 多阶段：node:22 构建 admin-ui → node:22-slim 运行
-docker run -d --name baize-admin -p 8080:8080 -v baize-admin-data:/data baize-admin-workspace
+docker run -d --name baize-admin -p 8080:8080 \
+  -v baize-admin-data:/data -e BAIZE_ADMIN_TOKEN='<初始口令>' baize-admin-workspace
 ```
 
-- 本地运行：`npm ci && npm start`（Node ≥ 20.11，默认 8080）；
-- 前端构建产物已含在 `admin-ui/dist`（容器内 `/app/dist`），可与 API 同源静态提供。
+> 厂商如需分发 Docker 镜像 tar：打包时 `BUILD_ADMIN_DOCKER=1 ./scripts/pack-release.sh`（本默认交付不包含 tar）。
 
-## 四、卸载
+- 前端构建产物已含在 `admin-ui/dist`，与 API 同源静态提供（nginx/Caddy 指到该目录即可）。
+- API 默认 8080（`PORT` 可改）；本地直跑：`BAIZE_ADMIN_DIR=/srv/baize-admin npm start`。
 
 ```bash
 baize a2a disable          # 先切回单机 / 停服务
@@ -332,13 +337,16 @@ verify() {
     echo "  !! ${admin_tgz} 校验失败（解压或 manifest 不正确）" >&2
     rc=1
   fi
-
-  # docker save 产物：存在且非空
-  if [ -s "${admin_tar}" ]; then
-    log "  OK  ${admin_tar} ($(size "${admin_tar}"))  存在且非空"
+  # docker save 产物：可选（BUILD_ADMIN_DOCKER=1 打包时才存在）
+  if [ -e "${admin_tar}" ] || [ "${BUILD_ADMIN_DOCKER:-0}" = "1" ]; then
+    if [ -s "${admin_tar}" ]; then
+      log "  OK  ${admin_tar} ($(size "${admin_tar}"))  存在且非空"
+    else
+      echo "  !! ${admin_tar} 不存在或为空" >&2
+      rc=1
+    fi
   else
-    echo "  !! ${admin_tar} 不存在或为空" >&2
-    rc=1
+    log "  --  ${admin_tar##*/} 未打包（源码交付模式，BUILD_ADMIN_DOCKER=1 可启用）"
   fi
 
   [ -f "${DIST_DIR}/INSTALL.md" ] && log "  OK  ${DIST_DIR}/INSTALL.md ($(size "${DIST_DIR}/INSTALL.md"))"

package/skills/activity-monitor/scripts/__tests__/guardian.test.js

@@ -48,6 +48,7 @@ function createDeps(overrides = {}) {
     nowMs: overrides.nowMs ?? (() => 100_000),
     initialRuntimeLaunchAtMs: overrides.initialRuntimeLaunchAtMs ?? 0,
   };
+  if (overrides.alert) deps.alert = overrides.alert;
 
   return { deps, calls };
 }
@@ -174,4 +175,54 @@ describe('Guardian', () => {
     await Promise.resolve();
     assert.deepEqual(order, ['prepare', 'launch', 'prompt']);
   });
+
+  it('raises alert after ALERT_AFTER_RESTARTS consecutive ENOENT launch failures (D54 P2)', async () => {
+    const alerts = [];
+    const adapter = {
+      sessionName: 'test-main',
+      displayName: 'TestRuntime',
+      runtimeId: 'codex',
+      isRunning: async () => false,
+      launch: async () => { throw Object.assign(new Error('spawnSync codex ENOENT'), { code: 'ENOENT' }); },
+      clearStaleState: () => {},
+      enqueueStartupPrompt: () => {},
+    };
+    const { deps } = createDeps({ alert: (info) => alerts.push(info) });
+    const guardian = new Guardian(adapter, deps);
+    guardian._maybeAlert('spawnSync codex ENOENT'); // below threshold → no alert
+    assert.equal(alerts.length, 0);
+
+    // simulate 3 consecutive failed launches crossing the threshold
+    guardian.consecutiveRestarts = 3;
+    guardian._maybeAlert('spawnSync codex ENOENT');
+    guardian._maybeAlert('spawnSync codex ENOENT'); // no duplicate
+    assert.equal(alerts.length, 1, 'alert must fire exactly once per episode');
+    assert.equal(alerts[0].runtime, 'codex');
+    assert.equal(alerts[0].consecutive_restarts, 3);
+    assert.ok(/ENOENT/.test(alerts[0].reason));
+
+    // recovery resets alerted → next episode may alert again
+    guardian.alerted = false;
+    guardian._maybeAlert('again');
+    assert.equal(alerts.length, 2, 'alert must fire again after recovery');
+  });
+
+  it('logs a repair hint on ENOENT launch failure (D54 P2)', async () => {
+    const adapter = {
+      sessionName: 'test-main',
+      displayName: 'TestRuntime',
+      runtimeId: 'codex',
+      isRunning: async () => false,
+      launch: async () => { throw Object.assign(new Error('spawnSync codex ENOENT'), { code: 'ENOENT' }); },
+      clearStaleState: () => {},
+      enqueueStartupPrompt: () => {},
+    };
+    const { deps, calls } = createDeps({ alert: () => {} });
+    const guardian = new Guardian(adapter, deps);
+    guardian.consecutiveRestarts = 0;
+    await guardian.startAgent();
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.ok(calls.log.some(m => m.includes('ENOENT') && m.includes('baize init')), 'must log the repair hint');
+  });
 });

package/skills/activity-monitor/scripts/adapters/runtime-components.js

@@ -1,5 +1,6 @@
 import { execFileSync, execSync } from 'child_process';
 import fs from 'fs';
+import path from 'path';
 import { Guardian } from '../guardian.js';
 import { HealthEngine } from '../health-engine.js';
 import { ProcSampler } from '../proc-sampler.js';
@@ -62,6 +63,7 @@ export function createGuardian(activeAdapter, activeToolPipeline, initialRuntime
   hookStateFile,
   log,
 }) {
+  const monitorDir = apiActivityFile ? path.dirname(apiActivityFile) : undefined;
   return new Guardian(activeAdapter, {
     log,
     initialRuntimeLaunchAtMs,
@@ -76,6 +78,31 @@ export function createGuardian(activeAdapter, activeToolPipeline, initialRuntime
       }));
       fs.writeFileSync(hookStateFile, JSON.stringify({ active_tools: 0 }));
     },
+    // D54 P2: consecutive-failure alert — write a visible file in the monitor
+    // dir (alongside agent-status.json) so ops/AI can discover an outage that
+    // Guardian keeps retrying. Cleared on recovery via onRecovered.
+    alert: (info) => {
+      if (!monitorDir) return;
+      const alertFile = path.join(monitorDir, 'guardian-alert.json');
+      try {
+        const tmp = `${alertFile}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, `${JSON.stringify(info, null, 2)}\n`);
+        fs.renameSync(tmp, alertFile);
+        log(`Guardian: ⚠ ALERT after ${info.consecutive_restarts} consecutive failures — ${info.reason}`);
+      } catch (e) {
+        log(`Guardian: alert write failed: ${e.message}`);
+      }
+    },
+    onRecovered: () => {
+      if (!monitorDir) return;
+      const alertFile = path.join(monitorDir, 'guardian-alert.json');
+      try {
+        if (fs.existsSync(alertFile)) fs.unlinkSync(alertFile);
+        log('Guardian: runtime recovered — alert cleared');
+      } catch (e) {
+        log(`Guardian: alert clear failed: ${e.message}`);
+      }
+    },
   });
 }
 

package/skills/activity-monitor/scripts/guardian.js

@@ -5,6 +5,9 @@ export const MAX_RESTART_DELAY = 60;
 export const BACKOFF_RESET_THRESHOLD = 60;
 export const STARTUP_GRACE_TICKS = 30;
 export const MAINTENANCE_WAIT_TIMEOUT = 300;
+// D54 P2: after this many consecutive launch failures, raise an alert —
+// the 09-13 incident stayed silent for 44 attempts / 48 minutes.
+export const ALERT_AFTER_RESTARTS = 3;
 
 export function getRunningMaintenance({ execSyncImpl = defaultExecSync } = {}) {
   try {
@@ -76,6 +79,8 @@ export class Guardian {
       execSyncImpl: defaultExecSync,
       nowMs: () => Date.now(),
       initialRuntimeLaunchAtMs: 0,
+      alert: () => {}, // D54 P2: consecutive-failure alert sink (default no-op)
+      onRecovered: () => {}, // D54 P2: clears the alert once the episode ends
       ...deps,
     };
     this.notRunningCount = 0;
@@ -84,6 +89,7 @@ export class Guardian {
     this.startupGrace = 0;
     this.startAgentInProgress = false;
     this.runtimeLaunchAtMs = this.deps.initialRuntimeLaunchAtMs;
+    this.alerted = false; // D54 P2: raise alert at most once per outage episode
   }
 
   getState() {
@@ -135,6 +141,8 @@ export class Guardian {
       } else if (currentTime - this.stableRunningSince >= BACKOFF_RESET_THRESHOLD) {
         this.consecutiveRestarts = 0;
         this.stableRunningSince = 0;
+        this.alerted = false; // D54 P2: outage episode over — next one may alert again
+        try { this.deps.onRecovered(); } catch (e) { this.deps.log(`Guardian: recovery callback failed: ${e.message}`); }
       }
     }
 
@@ -148,6 +156,29 @@ export class Guardian {
     };
   }
 
+  /**
+   * D54 P2: raise the consecutive-failure alert exactly once per outage
+   * episode (threshold ALERT_AFTER_RESTARTS). Sink is injectable — the
+   * activity-monitor wires it to a visible status/alert file.
+   */
+  _maybeAlert(reason) {
+    if (this.alerted) return;
+    if (this.consecutiveRestarts < ALERT_AFTER_RESTARTS) return;
+    this.alerted = true;
+    try {
+      this.deps.alert({
+        agent: this.adapter.displayName,
+        runtime: this.adapter.runtimeId,
+        consecutive_restarts: this.consecutiveRestarts,
+        reason: String(reason || '').slice(0, 500),
+        at: this.deps.nowMs(),
+        atIso: new Date(this.deps.nowMs()).toISOString(),
+      });
+    } catch (e) {
+      this.deps.log(`Guardian: alert sink failed: ${e.message}`);
+    }
+  }
+
   _handleNotRunning({ state, message, restartLog }) {
     if (this.startupGrace > 0) {
       this.startupGrace -= 1;
@@ -204,6 +235,11 @@ export class Guardian {
 
       this.deps.log(`Guardian: Starting ${this.adapter.displayName}...`);
 
+      // D54 P2: alert on consecutive startAgent attempts regardless of WHERE
+      // the failure lands (launch throw, or silent tmux-session-with-dead-runtime).
+      // Raised here (threshold checked inside) so every retry episode counts.
+      this._maybeAlert(`startAgent attempt #${this.consecutiveRestarts}`);
+
       try {
         this.adapter.clearStaleState?.();
       } catch { }
@@ -213,7 +249,15 @@ export class Guardian {
       } catch { }
 
       const reportFailure = (err) => {
-        this.deps.log(`Guardian: Failed to start ${this.adapter.displayName}: ${err.message}`);
+        const msg = err?.message || String(err);
+        this.deps.log(`Guardian: Failed to start ${this.adapter.displayName}: ${msg}`);
+        // D54 P2: an ENOENT on launch means the runtime binary is missing from
+        // PATH (or uninstalled) — surface the repair hint instead of silently
+        // retrying; then raise an alert once the failure count crosses the bar.
+        if (err?.code === 'ENOENT' || /ENOENT/.test(msg)) {
+          this.deps.log(`Guardian: runtime binary not found (ENOENT) — run "baize init" to repair PATH/binaries, or reinstall the ${this.adapter.displayName} runtime`);
+        }
+        this._maybeAlert(msg);
       };
       const launchPrepared = () => {
         try {

package/skills/activity-monitor/scripts/monitor-orchestrator.js

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import path from 'path';
 import {
   WATCHDOG_INTERRUPT_AVAILABLE_IN_SEC,
   evaluateToolWatchdogTransition,
@@ -51,7 +52,13 @@ export class MonitorOrchestrator {
     const runtimeLaunchAtMs = Number(initialStatus.runtime_launch_at) || nowMs();
 
     const engine = createHealthEngine(adapter, initialStatus);
-    const guardian = createGuardian(adapter, toolPipeline, runtimeLaunchAtMs);
+    // D54 P2: pass the alert sink wiring (apiActivityFile/hookStateFile/log)
+    // so Guardian's consecutive-failure alert writes guardian-alert.json.
+    const guardian = createGuardian(adapter, toolPipeline, runtimeLaunchAtMs, {
+      apiActivityFile: path.join(monitorDir, 'api-activity.json'),
+      hookStateFile: path.join(monitorDir, 'hook-state.json'),
+      log,
+    });
 
     if (initialHealth === 'rate_limited' && initialStatus.cooldown_until) {
       engine.enterRateLimited(initialStatus.cooldown_until, initialStatus.rate_limit_reset || '');

package/skills/activity-monitor/scripts/upgrade-check.js

@@ -10,6 +10,7 @@ import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { completeBinPath } from '../../../cli/lib/path-bins.js';
 
 const BAIZE_DIR = process.env.BAIZE_DIR || path.join(os.homedir(), 'baize');
 const MONITOR_DIR = path.join(BAIZE_DIR, 'activity-monitor');
@@ -93,7 +94,8 @@ function main() {
   // Check baize-core
   try {
     const coreVersion = execFileSync('baize', ['--version'], {
-      encoding: 'utf8', stdio: 'pipe', timeout: 5000
+      encoding: 'utf8', stdio: 'pipe', timeout: 5000,
+      env: { ...process.env, PATH: completeBinPath() },
     }).trim();
     const result = getLatestTag('baize-ai/baize-core');
     if (result.error) {