baldart 4.36.0 → 4.37.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to BALDART 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).
 
+## [4.37.0] - 2026-06-15
+
+**`baldart doctor` now detects and reaps orphaned MCP-server processes left behind by BALDART's Codex calls.** A real machine hit ~100% CPU from ~45 orphaned `@playwright/mcp` processes (plus stray `obsidian-mcp-server` instances), all children of OpenAI Codex CLI sessions that had since died. Root cause traced through the Codex companion plugin: every BALDART Codex finder call (`/new`, `new2`, `/codexreview`, the cron review engine) drives `codex app-server` via `codex-companion.mjs`, which attaches to a **shared, `detached + unref'd` broker** (`broker-lifecycle.mjs`). That broker spawns every MCP server declared in the user's `~/.codex/config.toml` (Playwright, Figma, …) as its own children; when the broker dies the OS reparents those MCP servers to init (ppid 1) and they keep running — an `@playwright/mcp` can peg a core for days. The leak compounds across sessions. We cannot suppress the MCP spawn per-call (the companion attaches to a broker it does not control, and exposes no shutdown verb), so the fix is a **safe reaper** owned by the doctor. **MINOR** (new doctor diagnostic + self-heal action; backwards-compatible — zero output on a clean machine, no install/layout change, not a `baldart.config.yml` key ⇒ schema-propagation rule N/A).
+
+### Added
+
+- **`src/utils/codex-orphans.js`** — orphaned-MCP-server detector + reaper. `detectOrphans()` snapshots `ps -axo` and returns MCP servers that are **orphaned (ppid 1) AND match an MCP-server command signature** (`@playwright/mcp`, `playwright-mcp`, `*-mcp-server`, `@modelcontextprotocol/*`, `obsidian-mcp`, npx `*-mcp@*`). `reapOrphans()` kills each orphan's full process tree (so a Playwright MCP's browser children go too) via `process.kill(pid, 'SIGKILL')` — a direct syscall, immune to sandboxed shells that silently swallow multi-arg `kill`/for-loops. **Safety invariant**: ppid 1 means the parent is dead, so an MCP server's stdio pipe is broken and the process is unreconnectable dead weight — safe to reap. The `codex app-server` broker is deliberately NOT reaped: it is `detached + unref'd` by design, so a *live, in-use* shared runtime also shows ppid 1 and ppid 1 cannot tell a leaked broker from a healthy one. Broker processes are detected for visibility only. Fully fail-safe (Windows / any error → "no orphans"); no age threshold (an orphan is dead weight at any age).
+- **`src/commands/doctor.js`** — new probe (`state.mcpOrphans`), diagnostic line (`Codex MCP leak — N orphaned MCP server(s) running`, shown only when present so a clean machine prints nothing), and self-heal action `reap-mcp-orphans` (`autoOk: false` — killing processes warrants explicit intent; re-detects against a fresh snapshot at run time so it never acts on a stale list).
+
 ## [4.36.0] - 2026-06-13
 
 **`/new` security-domain fixes are now applied by `security-reviewer`, not `coder` — the v4.26.1 canonical writer map, finally propagated from `new2` to `/new`.** Auditing the `new2` lessons for guards/logic missing on `/new` surfaced one real gap (the others — args-string guard, JS router clamp, no-self-judge + specialist-owned lane, relevance-gated fan-out — were already present on `/new`). `new2-resolve.js` routes security fixes to `security-reviewer` (`fixerAgent = {doc:'doc-reviewer', ui:'ui-expert', security:'security-reviewer'}[domain] || 'coder'`), but the canonical writer map was never propagated to `/new`'s SSOT: the `Domain-Override Domains` table (SKILL.md) and every fix-routing site still sent `security` → `coder`. A coder applying a one-line RLS/permission/auth fix lacks the security-invariant contract that lives in `security-reviewer`'s system prompt — the same class of error as "wrong agent for the card", and a direct violation of the user's standing strict-specialization principle. **MINOR** (changes which agent applies security fixes across `/new`; backwards-compatible — `migration` stays `coder`, no install/layout change, no `baldart.config.yml` key ⇒ schema-propagation rule N/A).

package/README.md

@@ -496,8 +496,17 @@ still exist for power users, but the seamless default makes them unnecessary.
 
 Smart diagnostic that detects the install state and proposes the next sensible
 action (install, migrate legacy layout, configure, refresh config schema,
-update, push, or "nothing to do"). Prints a status table then runs the
-proposed actions with confirmation per step.
+update, push, repair symlinks, reap orphaned Codex MCP servers, or "nothing to
+do"). Prints a status table then runs the proposed actions with confirmation per
+step.
+
+Since v4.37.0 it also surfaces **orphaned MCP-server processes left by Codex
+calls** — every BALDART Codex finder call (`/new`, `new2`, `/codexreview`, the
+cron review engine) drives `codex app-server`, whose detached broker spawns the
+MCP servers from `~/.codex/config.toml` (Playwright, …) and leaks them to init
+(ppid 1) when it dies, where they keep burning CPU. The doctor reaps the
+orphaned MCP servers (and their browser children) directly via syscall; the live
+`codex app-server` broker is never touched.
 
 ```bash
 npx baldart            # diagnostic + interactive prompts

package/VERSION

@@ -1 +1 @@
-4.36.0
+4.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.36.0",
+  "version": "4.37.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/doctor.js

@@ -33,6 +33,7 @@ const Hooks = require('../utils/hooks');
 const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const GraphifyInstaller = require('../utils/graphify-installer');
+const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
 
@@ -388,6 +389,23 @@ async function detectState(cwd, opts = {}) {
         }
       }
     } catch (_) { /* never block doctor on graph probe */ }
+
+    // ---- Orphaned MCP servers from Codex calls (since v4.37.0) ---------
+    // BALDART's Codex finder calls (/new, new2, /codexreview, cron engine)
+    // drive `codex app-server` via the companion plugin. That broker spawns the
+    // MCP servers from ~/.codex/config.toml (Playwright, …) as children and,
+    // being detached, leaks them to init (ppid 1) when it dies — they keep
+    // running (an @playwright/mcp can peg a core for days). Surface the orphans
+    // so the planner can offer a safe reap (orphaned MCP servers only; never the
+    // broker — see codex-orphans.js for the ppid-1 safety invariant). Fully
+    // fail-safe: any error → no orphans reported.
+    state.mcpOrphans = [];
+    state.codexRuntimeOrphans = [];
+    try {
+      const { mcp, runtime } = CodexOrphans.detectOrphans();
+      state.mcpOrphans = mcp;
+      state.codexRuntimeOrphans = runtime;
+    } catch (_) { /* never block doctor on the process probe */ }
   }
 
   return state;
@@ -781,6 +799,37 @@ function planActions(state) {
     });
   }
 
+  // Orphaned MCP servers from Codex calls (since v4.37.0). BALDART's Codex
+  // finder calls leave behind MCP-server processes (Playwright, obsidian-mcp, …)
+  // reparented to init when their `codex app-server` broker dies. They keep
+  // burning CPU. Offer a safe reap — orphaned MCP servers only (ppid 1 ⇒ parent
+  // dead ⇒ stdio broken ⇒ dead weight). The action is NOT autoOk: killing
+  // processes warrants explicit intent.
+  if (state.mcpOrphans && state.mcpOrphans.length > 0) {
+    const n = state.mcpOrphans.length;
+    actions.push({
+      key: 'reap-mcp-orphans',
+      label: `Reap ${n} orphaned MCP server process(es) left by Codex`,
+      why: `${n} MCP server(s) are orphaned (ppid 1 — their parent Codex session/broker is dead) and still running. They cannot be reconnected to (their stdio pipe is broken) and waste CPU. Reaping kills each process tree directly via syscall. The codex app-server broker itself is never touched.`,
+      autoOk: false, // kills processes — require explicit intent
+      run: async () => {
+        const procs = CodexOrphans.listProcesses();
+        // Re-detect against a fresh snapshot so we never act on a stale list.
+        const { mcp } = CodexOrphans.detectOrphans(procs);
+        if (mcp.length === 0) {
+          UI.info('No orphaned MCP servers remain — nothing to reap.');
+          return;
+        }
+        const { killed, failed } = CodexOrphans.reapOrphans(mcp, procs);
+        if (killed.length) UI.success(`Reaped ${killed.length} orphaned process(es) (incl. descendants).`);
+        if (failed.length) {
+          UI.warning(`${failed.length} could not be killed:`);
+          failed.forEach((f) => console.log(`    pid ${f.pid}: ${f.error}`));
+        }
+      },
+    });
+  }
+
   // v3.25.0+: drift detection is authoritative via VERSION compare (isAligned).
   // The HEAD...FETCH_HEAD commit count is subtree-merge noise and never reaches
   // 0, so we MUST NOT use it as the "needs update" signal.
@@ -1037,6 +1086,19 @@ function renderDiagnostic(state) {
     console.log(statusLine('Code graph', 'disabled', 'ok'));
   }
 
+  // Orphaned MCP servers left by Codex calls (v4.37.0). Only shown when present
+  // — a clean machine prints nothing here (zero noise).
+  if (state.mcpOrphans && state.mcpOrphans.length > 0) {
+    console.log(statusLine(
+      'Codex MCP leak',
+      `${state.mcpOrphans.length} orphaned MCP server(s) running — will be reaped`,
+      'warn'
+    ));
+    state.mcpOrphans.slice(0, 6).forEach((p) =>
+      console.log(`   • pid ${p.pid} (up ${p.etime}): ${p.command.slice(0, 70)}`));
+    if (state.mcpOrphans.length > 6) console.log(`   • … and ${state.mcpOrphans.length - 6} more`);
+  }
+
   console.log();
 }
 

package/src/utils/codex-orphans.js

@@ -0,0 +1,182 @@
+/**
+ * Orphaned-MCP-server reaper (since v4.37.0).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * BALDART's Codex integration (the `/new`, `new2`, `/codexreview` finder calls
+ * and the cron review engine) drives the OpenAI Codex CLI through the
+ * `codex-companion.mjs` plugin. That companion attaches to a SHARED, persistent
+ * `codex app-server` broker which is spawned `detached + unref'd`
+ * (broker-lifecycle.mjs) and which, in turn, spawns every MCP server declared in
+ * the user's `~/.codex/config.toml` (Playwright, Figma, …) as its own children.
+ *
+ * When that broker eventually dies, its MCP children are NOT reaped: the OS
+ * reparents them to init (ppid 1) and they keep running — an `@playwright/mcp`
+ * server can sit at ~100% CPU for days. Over many Codex sessions these
+ * accumulate (the symptom that motivated this utility: ~45 orphaned Playwright
+ * MCP processes pegging the machine).
+ *
+ * SAFETY INVARIANT (read before touching the matchers)
+ * ----------------------------------------------------
+ * We reap a process ONLY when BOTH hold:
+ *   1. ppid === 1  → the process was reparented to init, i.e. its controlling
+ *      parent is DEAD. An MCP server is a stdio child of whatever launched it;
+ *      once that parent dies the stdio pipe is broken and the server is dead
+ *      weight that can never be reconnected to. Reaping it is safe.
+ *   2. the command matches a known MCP-server signature (below).
+ *
+ * We deliberately DO NOT reap the `codex app-server` broker itself. The broker
+ * is `detached + unref'd` BY DESIGN, so a perfectly healthy, in-use shared
+ * runtime ALSO shows ppid 1 — ppid 1 cannot distinguish a leaked broker from a
+ * live one. Killing it could interrupt an in-flight Codex turn. We only report
+ * broker processes for visibility; we never auto-kill them.
+ *
+ * We use Node's `process.kill(pid)` (a direct syscall) rather than shelling out
+ * to `kill` — some sandboxed shells silently swallow multi-arg `kill`/for-loops,
+ * and the syscall path is immune to that.
+ *
+ * Fully fail-safe: any internal error degrades to "no orphans found" / "nothing
+ * reaped". This is hygiene, never a blocker.
+ */
+
+const { execSync } = require('child_process');
+
+// Command signatures that identify an MCP server. When such a process is
+// orphaned (ppid 1) it is safe to reap (its stdio parent is gone).
+const MCP_SIGNATURES = [
+  /@playwright\/mcp/,
+  /\bplaywright-mcp\b/,
+  /@modelcontextprotocol\//,
+  /-mcp-server\b/,
+  /\bmcp-server\b/,
+  /\bobsidian-mcp/,
+  /[\w@/.-]+-mcp@/, // npx-launched `<pkg>-mcp@<version>`
+];
+
+// Codex runtime processes — DETECTED for visibility, never auto-reaped (see the
+// safety note above: a detached broker at ppid 1 may still be the live runtime).
+const CODEX_RUNTIME_SIGNATURES = [
+  /codex\s+app-server/,
+  /codex-companion\.mjs/,
+];
+
+function matchesAny(signatures, command) {
+  return signatures.some((re) => re.test(command));
+}
+
+/**
+ * Snapshot every process as { pid, ppid, etime, command }.
+ * `ps -axo` works on both macOS and Linux. Returns [] on any failure or on
+ * Windows (the orphan-reparent-to-init leak is a POSIX phenomenon).
+ */
+function listProcesses() {
+  if (process.platform === 'win32') return [];
+  let raw;
+  try {
+    raw = execSync('ps -axo pid=,ppid=,etime=,command=', {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: 5000,
+    });
+  } catch (_) {
+    return [];
+  }
+  const procs = [];
+  for (const line of raw.split('\n')) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+    if (!m) continue;
+    procs.push({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      etime: m[3],
+      command: m[4],
+    });
+  }
+  return procs;
+}
+
+/**
+ * Detect orphaned MCP servers (reapable) and Codex runtime processes (info only).
+ *
+ * @returns {{ mcp: Array, runtime: Array }}
+ *   mcp     — orphaned MCP servers (ppid 1 + MCP signature) safe to reap
+ *   runtime — codex app-server / companion processes (reported, NOT reaped)
+ */
+function detectOrphans(procs = listProcesses()) {
+  const self = process.pid;
+  const mcp = [];
+  const runtime = [];
+  for (const p of procs) {
+    if (p.pid === self) continue;
+    if (p.ppid !== 1) continue; // only true orphans — parent is dead
+    if (matchesAny(MCP_SIGNATURES, p.command)) mcp.push(p);
+    else if (matchesAny(CODEX_RUNTIME_SIGNATURES, p.command)) runtime.push(p);
+  }
+  return { mcp, runtime };
+}
+
+/**
+ * Collect a pid plus all of its descendants (so killing an orphaned MCP server
+ * also takes down the browser/worker subprocesses it spawned).
+ */
+function collectTree(rootPid, procs) {
+  const childrenOf = new Map();
+  for (const p of procs) {
+    if (!childrenOf.has(p.ppid)) childrenOf.set(p.ppid, []);
+    childrenOf.get(p.ppid).push(p.pid);
+  }
+  const tree = [];
+  const seen = new Set();
+  const stack = [rootPid];
+  while (stack.length) {
+    const pid = stack.pop();
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    tree.push(pid);
+    for (const child of childrenOf.get(pid) || []) stack.push(child);
+  }
+  return tree;
+}
+
+/**
+ * Reap the given orphaned MCP-server processes (and their descendant trees).
+ * Uses process.kill(pid, 'SIGKILL') per-pid — immune to shells that swallow
+ * multi-arg kills. Never throws.
+ *
+ * @param {Array} orphans  the `mcp` array from detectOrphans()
+ * @param {Array} procs    full process snapshot (for descendant resolution)
+ * @returns {{ killed: number[], failed: Array<{pid:number,error:string}> }}
+ */
+function reapOrphans(orphans = [], procs = listProcesses()) {
+  const self = process.pid;
+  const targets = new Set();
+  for (const o of orphans) {
+    for (const pid of collectTree(o.pid, procs)) {
+      if (pid !== self && Number.isInteger(pid) && pid > 1) targets.add(pid);
+    }
+  }
+  const killed = [];
+  const failed = [];
+  // Kill descendants before roots so a parent can't immediately re-fork: sort
+  // by depth is overkill — SIGKILL is unconditional — so a single pass suffices.
+  for (const pid of targets) {
+    try {
+      process.kill(pid, 'SIGKILL');
+      killed.push(pid);
+    } catch (err) {
+      // ESRCH = already gone (e.g. died with its parent tree) → treat as success.
+      if (err && err.code === 'ESRCH') killed.push(pid);
+      else failed.push({ pid, error: (err && err.message) || String(err) });
+    }
+  }
+  return { killed, failed };
+}
+
+module.exports = {
+  MCP_SIGNATURES,
+  CODEX_RUNTIME_SIGNATURES,
+  listProcesses,
+  detectOrphans,
+  collectTree,
+  reapOrphans,
+};