@baize-ai/core 0.3.16 → 0.3.17

package/.dockerignore

@@ -6,3 +6,4 @@
 !templates/pm2/ecosystem.config.cjs
 !.claude-local/claude
 !.claude-local/claude.version
+!core.tgz

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.17] - 2026-09-14
+
+### Added
+- 启动链路 PATH 完整性加固（D54）：共享 `cli/lib/path-bins.js`（`completeBinPath`/`knownBinDirs`——静态 `~/.npm-global/bin` + 动态 npm prefix）；所有 runtime 二进制 spawn（codex/claude/baize）子进程 env 补完整 PATH——登录 shell PATH 污染（09-13 事故根因：缺 `~/.npm-global/bin`）不再导致 ENOENT
+- `init.js ensureCompletePathProfile`：每次 init 修复 shell profile 完整 bin PATH（npm-global/.local/claude/baize/node），幂等 + 存量缺失自动补；`saveSystemPath` 写显式完整集
+- `ecosystem.config.cjs` `ENHANCED_PATH` 显式含 `~/.npm-global/bin`（PM2 服务不依赖 SYSTEM_PATH/进程 PATH）
+- Guardian 连续失败告警（`ALERT_AFTER_RESTARTS=3` → `~/baize/activity-monitor/guardian-alert.json` + 日志，恢复自动清除）；ENOENT 启动失败打修复提示
+- `baize doctor` 新增 PATH 完整性检查（`path_incomplete` issue + path 组）
+- Dockerfile 本地源码构建层序修复：`COPY core.tgz` 移到 npm install RUN 前（tarball 变更正确失效 npm 层缓存）
+- 运维手册 `docs/ops-runbook.md`：PATH 事故排查 + D54 加固说明 + 巡检命令
+
+### Changed
+- `docker/entrypoint.sh` 不再写 `SYSTEM_PATH`（init.js `saveSystemPath` 唯一写者，写完整集）
+- `templates/pm2/ecosystem.config.cjs` 与 `docker-publish.sh`：发布构建临时 context + 空 `core.tgz` 占位（可选 COPY 不破坏 registry 构建）
+
 ## [0.3.16] - 2026-09-13
 
 ### Added

package/Dockerfile

@@ -86,6 +86,11 @@ ARG BAZE_CORE_VERSION=latest
 # build context) to install the workspace package instead of the registry
 # version — lets us verify un-released fixes (e.g. D51) in the image.
 ARG BAZE_CORE_TARBALL=
+# Local-source build tarball — COPY'd BEFORE the install RUN so the file is
+# present in that layer AND a tarball change invalidates the install layer.
+# Registry builds provide an empty placeholder via docker-publish.sh's temp
+# context (or omit BAZE_CORE_TARBALL → the COPY still needs a file present).
+COPY core.tgz /tmp/core.tgz
 WORKDIR /home/baize
 RUN if [ -n "${BAZE_CORE_TARBALL}" ]; then npm install -g /tmp/${BAZE_CORE_TARBALL}; else npm install -g @baize-ai/core@${BAZE_CORE_VERSION}; fi \
     && baize --version \
@@ -138,11 +143,6 @@ RUN mkdir -p \
 # ── Copy PM2 ecosystem config ─────────────────────────────────────────────────
 COPY --chown=baize:baize templates/pm2/ecosystem.config.cjs /home/baize/baize/pm2/ecosystem.config.cjs
 
-# ── Local-source build context (optional) ────────────────────────────────────
-# When BAZE_CORE_TARBALL is set, the tarball must live at ./core.tgz in the
-# build context; it is staged at /tmp so the install RUN above can consume it.
-COPY core.tgz /tmp/core.tgz
-
 # ── Copy entrypoint ───────────────────────────────────────────────────────────
 COPY --chown=baize:baize docker/entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh

package/cli/commands/doctor.js

@@ -20,6 +20,7 @@ import { loadComponents } from '../lib/components.js';
 import { fetchLatestTagAsync, compareSemverDesc } from '../lib/github.js';
 import { getCurrentVersion } from '../lib/self-upgrade.js';
 import { commandExists } from '../lib/shell-utils.js';
+import { completeBinPath } from '../lib/path-bins.js';
 import { parseSkillMd } from '../lib/skill.js';
 import { bold, dim, green, red, yellow, heading } from '../lib/colors.js';
 import { getActiveAdapter } from '../lib/runtime/index.js';
@@ -280,6 +281,30 @@ function checkTmuxSession() {
   }
 }
 
+/**
+ * D54: verify the runtime binaries are resolvable from the CURRENT process
+ * PATH (i.e. PM2 services spawned from here can find codex/claude). A
+ * login-shell-polluted PATH (missing ~/.npm-global/bin) shows up here as
+ * missing binaries even though the files exist.
+ */
+function checkBinResolvable(bin) {
+  try {
+    execFileSync(bin, ['--version'], {
+      stdio: 'pipe', encoding: 'utf8', timeout: 10000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkPathComplete() {
+  const bins = ['baize'];
+  if (ACTIVE_RUNTIME === 'codex') bins.push('codex');
+  else bins.push('claude');
+  const missing = bins.filter((b) => !checkBinResolvable(b));
+  return { complete: missing.length === 0, missing };
+}
+
 // ── Diagnostics collection ───────────────────────────────────────
 
 async function collectDiagnostics(env) {
@@ -308,11 +333,13 @@ async function collectDiagnostics(env) {
     ? checkPm2Services()
     : { running: false, total: 0, online: 0, activityMonitor: false, procs: [] };
   const session = tmux.installed ? checkTmuxSession() : false;
+  const pathCheck = checkPathComplete();
 
   return {
     system: { tmux, pm2, network: net },
     ai: { cli, auth, authStatus, autonomous, networkSkipped: !net.reachable },
     services: { ...services, session },
+    path: pathCheck,
   };
 }
 
@@ -366,6 +393,19 @@ function buildDiagnosticJson(diag, coreVersion) {
       }
     }
   }
+  // D54: PATH completeness — runtime binaries must resolve from the current
+  // process PATH (services spawned from here inherit it). A polluted login
+  // shell PATH missing ~/.npm-global/bin surfaces here as ENOENT risk.
+  // Only relevant when the CLI is actually installed (else cli_missing covers
+  // it and a PATH repair hint would be misleading).
+  const pathSkipped = !diag.ai.cli.installed;
+  if (!pathSkipped && !diag.path.complete) {
+    issues.push({
+      id: 'path_incomplete',
+      label: `PATH 缺失运行时二进制: ${diag.path.missing.join(', ')}`,
+      hint: 'Run: baize init（修复 ~/.npm-global/bin 等完整 PATH）',
+    });
+  }
 
   return {
     version: coreVersion.success ? coreVersion.version : null,
@@ -395,6 +435,10 @@ function buildDiagnosticJson(diag, coreVersion) {
         procs: diag.services.procs.map(p => ({ name: p.name, status: p.pm2_env?.status || 'unknown' })),
         session: { active: diag.services.session },
       },
+      path: {
+        passed: !diag.ai.cli.installed ? null : diag.path.complete,
+        checks: { missing: diag.path.missing },
+      },
     },
     issues,
   };
@@ -512,6 +556,18 @@ function displayServiceGroup(diag, jsonGroup) {
   logToFile(`check: services — ${jsonGroup.passed ? 'passed' : 'failed'}`);
 }
 
+// D54: PATH completeness group — runtime binaries must resolve from the
+// current process PATH (services spawned from here inherit it).
+function displayPathGroup(diag, jsonGroup) {
+  if (!diag.path.complete) {
+    const checks = diag.path.missing.map((b) => red(`${b} 不可解析（ENOENT 风险）`));
+    displayCheckGroup('PATH', 'fail', checks);
+  } else {
+    displayCheckGroup('PATH', 'pass', [green('运行时二进制可解析（npm-global/.local/claude/baize）')]);
+  }
+  logToFile(`check: path — ${jsonGroup.passed ? 'passed' : 'failed'}`);
+}
+
 // ── Channel discovery ────────────────────────────────────────────
 
 function getNetworkIP() {
@@ -651,6 +707,7 @@ function runClaudeFix(diagnosticJson) {
     const proc = spawn('claude', ['-p', prompt, ...permArgs], {
       cwd: BAIZE_DIR,
       stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, PATH: completeBinPath() },
     });
 
     let stdout = '';
@@ -772,6 +829,9 @@ export async function doctorCommand(args) {
   displaySystemGroup(diag, diagnostic.groups.system);
   displayAiGroup(diag, diagnostic.groups.ai_service);
   displayServiceGroup(diag, diagnostic.groups.services);
+  if (diagnostic.groups.path.passed !== null) {
+    displayPathGroup(diag, diagnostic.groups.path);
+  }
 
   // ── Phase 4: Channels ─────────────────────────────────────────
 

package/cli/commands/init.js

@@ -17,6 +17,7 @@ import { generateManifest, saveMergeBaseline } from '../lib/manifest.js';
 import { prompt, promptYesNo, promptChoice, promptSecret } from '../lib/prompts.js';
 import { bold, dim, green, red, yellow, cyan, bgGreen, success, error, warn, heading } from '../lib/colors.js';
 import { commandExists } from '../lib/shell-utils.js';
+import { knownBinDirs, completeBinPath } from '../lib/path-bins.js';
 import { getActiveAdapter } from '../lib/runtime/index.js';
 import {
   activateFreshSplitInstructions,
@@ -114,54 +115,68 @@ function installSystemPackage(pkg) {
 }
 
 /**
- * Ensure ~/.local/bin is in the user's shell profile.
- * Detects shell from $SHELL and writes to the appropriate rc file.
+ * D54: ensure the user's shell profile carries the COMPLETE bin PATH —
+ * every directory where baize/claude/codex binaries actually live:
+ *   ~/.npm-global/bin (static — codex/baize default install),
+ *   npm global prefix bin (dynamic), ~/.local/bin (claude default),
+ *   ~/.claude/bin, ~/baize/bin (components), ~/.local/node/bin.
+ * Idempotent (marker-based) and repairs existing profiles that miss any bin
+ * (the 09-13 incident root: ~/.npm-global/bin was never added, so login-shell
+ * PATH was always incomplete).
+ * NOTE: rc files are NOT chattr/chflags-locked — content-marker idempotency
+ * already prevents duplicate writes, and a lock would make `baize
+ * self-uninstall` / install.sh re-runs abort with EPERM (D54 review P1-3).
  * Returns the profile path if modified, null otherwise.
  */
-function ensureLocalBinInProfile() {
+function ensureCompletePathProfile() {
   const homedir = os.homedir();
   const shell = (process.env.SHELL || '').split('/').pop();
-  const pathLine = 'export PATH="$HOME/.local/bin:$PATH"';
-
-  // Map shell to profile file
   const profileMap = {
     zsh: '.zshrc',
     bash: '.bashrc',
-    fish: null, // fish uses different syntax
+    fish: null, // fish uses a different config mechanism (handled elsewhere)
     sh: '.profile',
   };
-
   const profileName = profileMap[shell] || '.profile';
   if (!profileName) return null; // unsupported shell (fish)
-
   const profilePath = path.join(homedir, profileName);
 
-  // Check if already present
-  try {
-    const content = fs.readFileSync(profilePath, 'utf8');
-    if (content.includes('.local/bin')) return null; // already there
-  } catch {
-    // File doesn't exist — we'll create it
-  }
+  // ── Complete bin set (single source of truth: cli/lib/path-bins.js) ──────
+  const bins = new Set(knownBinDirs());
 
-  try {
-    fs.appendFileSync(profilePath, `\n# Added by baize init\n${pathLine}\n`);
-    return `~/${profileName}`;
-  } catch {
-    return null;
+  // Read existing profile content (missing file → create)
+  let content = '';
+  try { content = fs.readFileSync(profilePath, 'utf8'); } catch { /* absent */ }
+
+  // ── Idempotent + repair: add any bin not already present ─────────────────
+  const toAdd = [];
+  for (const bin of bins) {
+    // match both absolute (~/...) and $HOME-relative forms already in profile
+    const rel = bin.startsWith(homedir) ? bin.slice(homedir.length) : bin;
+    if (content.includes(bin) || content.includes(`$HOME${rel}`)) continue;
+    const portable = bin.startsWith(homedir) ? `$HOME${rel}` : bin;
+    toAdd.push(`export PATH="${portable}:$PATH"`);
   }
+  if (toAdd.length === 0) return null; // already complete
+
+  fs.appendFileSync(profilePath, `\n# Added by baize init (D54 complete PATH)\n${toAdd.join('\n')}\n`);
+  return `~/${profileName}`;
 }
 
 /**
- * Save the current shell PATH to .env so PM2 services can use it.
- * Updates SYSTEM_PATH= line if exists, appends if not.
+ * Save the COMPLETE bin PATH to .env so PM2 services can use it.
+ * D54: no longer captures process.env.PATH (which may be polluted by a login
+ * shell) — builds the full known-good set explicitly: npm global prefix bin,
+ * ~/.local/bin, ~/.claude/bin, ~/baize/bin, ~/.local/node/bin.
  */
 function saveSystemPath(envPath) {
-  const currentPath = process.env.PATH || '';
-  // Deduplicate PATH entries before saving — prevents bloat when baize init
-  // runs while PM2 is already live (process.env.PATH may already contain
-  // the previous ENHANCED_PATH from ecosystem.config.cjs).
-  const dedupedPath = [...new Set(currentPath.split(':').filter(Boolean))].join(':');
+  const homedir = os.homedir();
+  // D54: build the full known-good set via path-bins (single source of truth)
+  const bins = new Set(knownBinDirs());
+  // keep the current PATH too (it may carry user-added entries worth keeping)
+  for (const entry of (process.env.PATH || '').split(':').filter(Boolean)) bins.add(entry);
+  const fullPath = [...bins].join(':');
+
   let content = '';
   try {
     content = fs.readFileSync(envPath, 'utf8');
@@ -169,7 +184,7 @@ function saveSystemPath(envPath) {
     return; // .env doesn't exist yet
   }
 
-  const line = `SYSTEM_PATH=${dedupedPath}`;
+  const line = `SYSTEM_PATH=${fullPath}`;
   if (content.includes('SYSTEM_PATH=')) {
     content = content.replace(/^SYSTEM_PATH=.*$/m, line);
   } else {
@@ -477,7 +492,7 @@ function verifySetupToken() {
   try {
     const result = spawnSync('claude', ['-p', 'hi', '--max-turns', '1'], {
       timeout: 30000,
-      env: { ...process.env },
+      env: { ...process.env, PATH: completeBinPath() },
       stdio: ['pipe', 'pipe', 'pipe'],
     });
 
@@ -2178,7 +2193,7 @@ export async function initCommand(args) {
               console.log(`\n  ${cyan('Starting Codex device auth...')}`);
               console.log(`  ${dim('Follow the instructions to authenticate. Press Ctrl+C when done.')}\n`);
               try {
-                spawnSync('codex', ['login', '--device-auth'], { stdio: 'inherit' });
+                spawnSync('codex', ['login', '--device-auth'], { stdio: 'inherit', env: { ...process.env, PATH: completeBinPath() } });
               } catch { /* user may Ctrl+C */ }
               codexAuthenticated = isCodexAuthenticated();
               if (codexAuthenticated) {
@@ -2192,7 +2207,7 @@ export async function initCommand(args) {
               console.log(`\n  ${cyan('Starting Codex browser login...')}`);
               console.log(`  ${dim('After login completes, press Ctrl+C to return.')}\n`);
               try {
-                spawnSync('codex', ['login'], { stdio: 'inherit' });
+                spawnSync('codex', ['login'], { stdio: 'inherit', env: { ...process.env, PATH: completeBinPath() } });
               } catch { /* user may Ctrl+C */ }
               codexAuthenticated = isCodexAuthenticated();
               if (codexAuthenticated) {
@@ -2309,9 +2324,9 @@ export async function initCommand(args) {
             // /dev/tty redirects. Use `script` to allocate a fresh pseudo-terminal
             // that gives Claude full terminal control.
             if (process.platform === 'darwin') {
-              spawnSync('script', ['-q', '/dev/null', 'claude'], { stdio: 'inherit' });
+              spawnSync('script', ['-q', '/dev/null', 'claude'], { stdio: 'inherit', env: { ...process.env, PATH: completeBinPath() } });
             } else {
-              spawnSync('claude', [], { stdio: 'inherit' });
+              spawnSync('claude', [], { stdio: 'inherit', env: { ...process.env, PATH: completeBinPath() } });
             }
           } catch { /* user may Ctrl+C */ }
           process.removeAllListeners('SIGINT');
@@ -2623,9 +2638,13 @@ export async function initCommand(args) {
 
   printWebConsoleInfo();
 
-  if (claudeJustInstalled) {
-    // Auto-add ~/.local/bin to shell profile so future shell sessions find claude
-    ensureLocalBinInProfile();
+  // D54: EVERY init run repairs the complete bin PATH in the shell profile
+  // (npm-global/.local/claude/baize/node bins) — idempotent, no-op when
+  // complete. Runs unconditionally: a claude-runtime deployment re-running
+  // init with --yes/--quiet must also get the missing bins repaired.
+  const profile = ensureCompletePathProfile();
+  if (profile && !quiet) {
+    console.log(`${green(`  ✔ PATH 已写入 ${profile}（含 npm-global/.local/claude/baize/node bin）`)}`);
   }
 
   if (!quiet) {

package/cli/lib/__tests__/runtime-launch.test.js

@@ -278,12 +278,14 @@ describe('Claude launch — compat mode PATH dedupe', () => {
       await makeAdapter(ClaudeAdapter).launch({ bypassPermissions: false });
       const env = readSpecEnv();
       assert.ok(env, 'spec should be written');
-      assert.equal(env.PATH, '/a:/b:/c', 'PATH must be deduplicated in compat mode');
+      // D54: known bin dirs first + deduplicated (npm-global static first)
+      const expected = `${fakeHome}/.npm-global/bin:${fakeHome}/.local/bin:${fakeHome}/.claude/bin:${fakeHome}/baize/bin:${fakeHome}/.local/node/bin:/a:/b:/c`;
+      assert.equal(env.PATH, expected, 'PATH must carry known bins first and be deduplicated in compat mode');
 
       const tmux = findTmuxNewSession();
       const pathArg = tmux.args.find(a => a.startsWith('PATH='));
       assert.ok(pathArg, 'tmux args should contain PATH= env');
-      assert.equal(pathArg, 'PATH=/a:/b:/c', 'tmux -e PATH must also be deduplicated');
+      assert.equal(pathArg, `PATH=${expected}`, 'tmux -e PATH must also carry known bins + dedupe');
     } finally {
       process.env.PATH = origPath;
       // Restore default (clean env is now the default)

package/cli/lib/__tests__/tmux-env.test.js

@@ -464,11 +464,20 @@ describe('buildCleanEnv', () => {
 // ── buildCompatEnv ─────────────────────────────────────────────────────────
 
 describe('buildCompatEnv', () => {
-  it('passes through full processEnv', () => {
+  it('passes through full processEnv and prepends known bin dirs (D54)', () => {
     const processEnv = { PATH: '/usr/bin', HOME: '/home/test', SECRET: 'abc123' };
     const { env } = buildCompatEnv({ processEnv, dotenvVars: {} });
     assert.equal(env.SECRET, 'abc123');
-    assert.equal(env.PATH, '/usr/bin');
+    const parts = env.PATH.split(':');
+    // D54: known bin dirs are ALWAYS prepended (npm-global static first),
+    // original PATH entries preserved, no duplicates.
+    assert.equal(parts[0], '/home/test/.npm-global/bin');
+    assert.ok(parts.includes('/home/test/.local/bin'));
+    assert.ok(parts.includes('/home/test/.claude/bin'));
+    assert.ok(parts.includes('/home/test/baize/bin'));
+    assert.ok(parts.includes('/home/test/.local/node/bin'));
+    assert.ok(parts.includes('/usr/bin'));
+    assert.equal(new Set(parts).size, parts.length, 'PATH must be deduplicated');
   });
 
   it('overrides with BAIZE_TMUX_ENV manifest vars', () => {
@@ -478,10 +487,15 @@ describe('buildCompatEnv', () => {
     assert.equal(env.MY_VAR, 'new_value');
   });
 
-  it('deduplicates PATH preserving first-occurrence order', () => {
+  it('deduplicates PATH preserving first-occurrence order with known bins first (D54)', () => {
     const processEnv = { PATH: '/a:/b:/a:/c:/b', HOME: '/home/test' };
     const { env } = buildCompatEnv({ processEnv, dotenvVars: {} });
-    assert.equal(env.PATH, '/a:/b:/c');
+    const parts = env.PATH.split(':');
+    assert.equal(parts[0], '/home/test/.npm-global/bin');
+    // original entries deduped, first-occurrence order preserved after known bins
+    const tail = parts.slice(parts.indexOf('/a'));
+    assert.deepEqual(tail, ['/a', '/b', '/c']);
+    assert.equal(new Set(parts).size, parts.length);
   });
 
   it('does not inject GH_PROMPT_DISABLED, Homebrew paths, or PATH manifest', () => {
@@ -492,7 +506,7 @@ describe('buildCompatEnv', () => {
     };
     const { env } = buildCompatEnv({ processEnv, dotenvVars });
     assert.equal(env.GH_PROMPT_DISABLED, undefined);
-    assert.ok(!env.PATH.includes('/opt/homebrew'), 'compat mode should not add Homebrew paths');
+    // compat mode does NOT apply PATH manifest PREPEND/APPEND (clean-env only)
     assert.ok(!env.PATH.includes('/custom/pre'), 'compat mode should not apply PREPEND');
     assert.ok(!env.PATH.includes('/custom/post'), 'compat mode should not apply APPEND');
   });

package/cli/lib/claude-eval.js

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { completeBinPath } from './path-bins.js';
 import { parseSkillMd } from './skill.js';
 
 const MAX_FILE_LINES = 500;
@@ -133,7 +134,7 @@ function callClaude(prompt) {
 
     const child = spawn('claude', ['--print', '--output-format', 'text'], {
       stdio: ['pipe', 'pipe', 'ignore'],
-      env: { ...process.env },
+      env: { ...process.env, PATH: completeBinPath() },
     });
 
     child.stdin.on('error', () => {}); // Ignore EPIPE if child exits early

package/cli/lib/codex-hooks.js

@@ -289,12 +289,23 @@ function writeTrustMarker(markerPath, marker) {
   fs.writeFileSync(markerPath, JSON.stringify(stable(marker), null, 2) + '\n', { mode: 0o600 });
 }
 
+/**
+ * D54 PATH hardening: build a PATH that always includes the known bin dirs
+ * (npm global prefix bin, ~/.local/bin, ~/.claude/bin, ~/baize/bin) on top of
+ * the current PATH — a login-shell-polluted PATH (missing ~/.npm-global/bin)
+ * must not make a bare `codex` spawn fail with ENOENT (09-13 incident).
+ * Single source of truth: cli/lib/path-bins.js.
+ */
+import { completeBinPath } from './path-bins.js';
+export { completeBinPath };
+
 export function getCodexVersion({ codexBin = process.env.CODEX_BIN || 'codex', execFileSyncImpl } = {}) {
   const execImpl = execFileSyncImpl || execFileSync;
   return String(execImpl(codexBin, ['--version'], {
     encoding: 'utf8',
     timeout: 10_000,
     stdio: 'pipe',
+    env: { ...process.env, PATH: completeBinPath() },
   })).trim();
 }
 
@@ -470,6 +481,7 @@ send('initialize', {
     cwd: baizeDir,
     env: {
       ...process.env,
+      PATH: completeBinPath(),
       BAIZE_CODEX_TRUST_CWD: baizeDir,
       BAIZE_CODEX_BIN: codexBin,
     },

package/cli/lib/path-bins.js

@@ -0,0 +1,54 @@
+/**
+ * D54: complete known-good bin PATH — the single source of truth for the bin
+ * directories where baize/claude/codex binaries actually live. Every spawn
+ * of a runtime binary must pass PATH built from this so a login-shell-polluted
+ * PATH (missing ~/.npm-global/bin — 09-13 incident) can never cause ENOENT.
+ *
+ * Consumers: init.js (profile repair + SYSTEM_PATH), codex-hooks.js
+ * (getCodexVersion), runtime-setup.js (auth checks), claude-eval.js,
+ * runtime/codex.js + runtime/claude.js (launch auth checks).
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.currentPath]  base PATH to extend (default process.env.PATH)
+ * @returns {string} deduplicated PATH with all known bin dirs first
+ */
+export function completeBinPath({ currentPath = process.env.PATH || '', home = os.homedir() } = {}) {
+  const bins = [];
+  // ~/.npm-global/bin — STATIC first (the 09-13 incident dir): codex/baize
+  // install there in the standard (Dockerfile NPM_CONFIG_PREFIX + install.sh
+  // user prefix) layouts; must never depend on `npm` being resolvable from
+  // the calling process (PM2 services, containers with replaced PATH).
+  bins.push(path.join(home, '.npm-global', 'bin'));
+  // npm global prefix bin — dynamic (npm config get prefix); covers custom
+  // prefixes (e.g. /opt/homebrew) in addition to the default.
+  try {
+    const prefix = execFileSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', timeout: 10_000 }).trim();
+    if (prefix && prefix !== 'undefined' && prefix !== 'null') bins.push(path.join(prefix, 'bin'));
+  } catch { /* npm unavailable */ }
+  bins.push(path.join(home, '.local', 'bin'));
+  bins.push(path.join(home, '.claude', 'bin'));
+  bins.push(path.join(home, 'baize', 'bin'));
+  bins.push(path.join(home, '.local', 'node', 'bin'));
+  for (const entry of currentPath.split(':').filter(Boolean)) bins.push(entry);
+  return [...new Set(bins)].join(':');
+}
+
+/** Known bin dirs (without the current PATH tail) — for profile writes. */
+export function knownBinDirs(home = os.homedir()) {
+  const bins = [];
+  bins.push(path.join(home, '.npm-global', 'bin'));
+  try {
+    const prefix = execFileSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', timeout: 10_000 }).trim();
+    if (prefix && prefix !== 'undefined' && prefix !== 'null') bins.push(path.join(prefix, 'bin'));
+  } catch { /* npm unavailable */ }
+  bins.push(path.join(home, '.local', 'bin'));
+  bins.push(path.join(home, '.claude', 'bin'));
+  bins.push(path.join(home, 'baize', 'bin'));
+  bins.push(path.join(home, '.local', 'node', 'bin'));
+  return [...new Set(bins)];
+}

package/cli/lib/runtime/claude.js

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, execFile } from 'node:child_process';
+import { completeBinPath } from '../path-bins.js';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
@@ -104,7 +105,7 @@ export class ClaudeAdapter extends RuntimeAdapter {
    */
   async checkAuth() {
     // Build subprocess env: inherit current env, inject .env API keys (same as launch()).
-    const injectedEnv = { ...process.env };
+    const injectedEnv = { ...process.env, PATH: completeBinPath() };
     let envApiKey = '';
     let envOauthToken = '';
     let envBaseUrl = '';
@@ -257,6 +258,7 @@ export class ClaudeAdapter extends RuntimeAdapter {
       try {
         const out = execFileSync(CLAUDE_BIN, ['auth', 'status'], {
           encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, PATH: completeBinPath() },
         });
         const status = JSON.parse(out);
         if (status?.loggedIn === true && status?.authMethod === 'claude.ai') {
@@ -435,7 +437,7 @@ function _ensureOnboardingComplete(projectDir) {
       config.hasCompletedOnboarding = true;
       try {
         config.lastOnboardingVersion = execFileSync(
-          CLAUDE_BIN, ['--version'], { encoding: 'utf8', timeout: 5000 }
+          CLAUDE_BIN, ['--version'], { encoding: 'utf8', timeout: 5000, env: { ...process.env, PATH: completeBinPath() } }
         ).trim();
       } catch {
         config.lastOnboardingVersion = '2.1.59';

package/cli/lib/runtime/codex.js

@@ -18,6 +18,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { completeBinPath } from '../path-bins.js';
 
 const execFileAsync = promisify(execFile);
 import { RuntimeAdapter } from './base.js';
@@ -147,6 +148,7 @@ export class CodexAdapter extends RuntimeAdapter {
       try {
         const { stdout, stderr } = await execFileAsync(CODEX_BIN, ['login', 'status'], {
           stdio: 'pipe', encoding: 'utf8', timeout: 10_000,
+          env: { ...process.env, PATH: completeBinPath() },
         });
         const status = classifyCodexLoginStatus((stdout || '') + (stderr || ''));
         if (status === 'success') return { status: 'success', reason: 'codex_login_status' };

package/cli/lib/runtime/tmux-env.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { completeBinPath } from '../path-bins.js';
 
 const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -280,10 +281,10 @@ export function buildCleanEnv({ processEnv, dotenvVars, manifest, platform, uid,
 export function buildCompatEnv({ processEnv, dotenvVars }) {
   const env = { ...processEnv };
 
-  // Deduplicate PATH to prevent bloat across restarts (PR #499 defense)
-  if (env.PATH) {
-    env.PATH = [...new Set(env.PATH.split(':').filter(Boolean))].join(':');
-  }
+  // D54: PATH built from the shared single source of truth (path-bins) —
+  // always prepends npm-global/.local/.claude/baize/node bins and dedupes;
+  // a polluted login-shell PATH can never hide the runtime binaries.
+  env.PATH = completeBinPath({ currentPath: env.PATH, home: processEnv.HOME });
 
   // Override with BAIZE_TMUX_ENV manifest vars from dotenvVars
   const warnings = [];

package/cli/lib/runtime-setup.js

@@ -13,6 +13,7 @@ import { execSync, execFileSync, spawnSync } from 'node:child_process';
 import { parse, stringify } from 'smol-toml';
 import crypto from 'node:crypto';
 import { BAIZE_DIR } from './config.js';
+import { completeBinPath } from './path-bins.js';
 import { commandExists } from './shell-utils.js';
 import { parseClaudeAuthStatus, parseCodexLoginStatus } from './auth-parsers.js';
 import { installCoreCodexHook } from './codex-hooks.js';
@@ -90,6 +91,7 @@ export function isClaudeAuthenticated() {
       stdio: 'pipe',
       encoding: 'utf8',
       timeout: 10000,
+      env: { ...process.env, PATH: completeBinPath() },
     });
     return parseClaudeAuthStatus(result.stdout);
   } catch {
@@ -129,6 +131,7 @@ export function isCodexAuthenticated() {
   try {
     const result = spawnSync('codex', ['login', 'status'], {
       stdio: 'pipe', encoding: 'utf8', timeout: 10000,
+      env: { ...process.env, PATH: completeBinPath() },
     });
     return parseCodexLoginStatus((result.stdout || '') + (result.stderr || ''));
   } catch {
@@ -158,7 +161,7 @@ export function approveApiKey(keyOrToken) {
     if (!config.hasCompletedOnboarding) {
       config.hasCompletedOnboarding = true;
       try {
-        const ver = execSync('claude --version 2>/dev/null', { encoding: 'utf8' }).trim();
+        const ver = execSync('claude --version 2>/dev/null', { encoding: 'utf8', env: { ...process.env, PATH: completeBinPath() } }).trim();
         config.lastOnboardingVersion = ver;
       } catch { /* omit if claude binary not yet available */ }
     }

package/docker/entrypoint.sh

@@ -124,8 +124,10 @@ upsert_env "CODEX_BYPASS_PERMISSIONS" "${CODEX_BYPASS_PERMISSIONS:-true}"
 upsert_env "OPENAI_API_KEY" "${OPENAI_API_KEY:-}"
 upsert_env "CODEX_API_KEY" "${CODEX_API_KEY:-}"
 
-# Save current PATH so PM2 services can find claude and node
-upsert_env "SYSTEM_PATH" "${PATH}"
+# D54: SYSTEM_PATH is owned exclusively by baize init (saveSystemPath writes
+# the complete known-good bin PATH). entrypoint no longer captures the
+# container PATH here — ecosystem.config.cjs carries an explicit
+# ~/.npm-global/bin fallback, so a polluted shell can never degrade services.
 
 # ── Graceful shutdown ─────────────────────────────────────────────────────────
 # docker stop sends SIGTERM to PID 1 (this script). Clean up tmux + PM2.

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.16",
+  "version": "0.3.17",
   "type": "module",
   "description": "Baize (白泽) — autonomous AI agent infrastructure",
   "main": "cli/baize.js",

package/scripts/docker-publish.sh

@@ -30,11 +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_CTX"
 
 if [ -n "${ACR_REGISTRY}" ] && [ -n "${ACR_NAMESPACE}" ]; then
   ACR_IMAGE="${ACR_REGISTRY}/${ACR_NAMESPACE}/baize-core"

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) {

package/templates/pm2/ecosystem.config.cjs

@@ -28,11 +28,12 @@ function readEnvValue(key, defaultValue = '') {
   return defaultValue;
 }
 
-// Build PATH: Claude locations + user's full shell PATH + PM2's own PATH
-// Deduplicate to prevent PATH bloat across PM2 restarts — each restart
-// re-evaluates this file with process.env.PATH already containing the
-// previous ENHANCED_PATH, which would otherwise compound indefinitely.
+// Build PATH: npm global bin + Claude locations + user's full shell PATH +
+// PM2's own PATH. D54: ~/.npm-global/bin is added EXPLICITLY (independent of
+// SYSTEM_PATH / process.env.PATH) — codex/baize live there; a polluted login
+// shell PATH must never hide them from PM2 services.
 const ENHANCED_PATH = [...new Set([
+  path.join(HOME, '.npm-global', 'bin'),
   path.join(HOME, '.local', 'bin'),
   path.join(HOME, '.claude', 'bin'),
   ...(readEnvValue('SYSTEM_PATH') || '').split(':').filter(Boolean),