baldart 4.38.0 → 4.39.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.39.0] - 2026-06-15
+
+**`/new`, `/new2`, and `/prd` now auto-reap orphaned Codex MCP servers at their workspace-hygiene finalizers — the v4.37.0 doctor reaper, made automatic.** v4.37.0 added an on-demand reaper to `baldart doctor`, but the leak compounds *per skill run*: every batch's Codex finder calls (`/new`/`new2` per-card review + final review, `/prd` discovery-completeness + plan audit) drive `codex app-server`, whose detached broker spawns the `~/.codex/config.toml` MCP servers (Playwright, …) as children that orphan to init (ppid 1) when the broker dies and keep burning CPU. Waiting for a manual `baldart doctor` let them accumulate between runs. Now each batch ends by sweeping them. A new focused, non-interactive CLI command (`baldart reap-orphans`) is the SSOT the three finalizers call; it shares the v4.37.0 `codex-orphans.js` detection/reaping logic and the same hard safety invariant — it reaps ONLY orphaned MCP servers (ppid 1 ⇒ broker dead ⇒ stdio broken), and NEVER kills a live `codex app-server` broker (a shared, detached runtime that may still serve the user's interactive session). Because an MCP child of a still-warm broker is not yet orphaned, this is a cumulative orphan sweep (catches this run's debris once its broker dies, plus any prior runs'), not a per-run broker teardown. **MINOR** (new CLI command + skill-finalizer wiring; backwards-compatible — non-blocking hygiene step, no-op when nothing is orphaned, no install/layout change, no `baldart.config.yml` key ⇒ schema-propagation rule N/A).
+
+### Added
+
+- **`src/commands/reap-orphans.js`** + **`bin/baldart.js`** — new `baldart reap-orphans` command: detects orphaned MCP servers (ppid 1 + MCP signature) and reaps each process tree via syscall, then prints a one-line summary. `--dry-run` reports without killing; `--json` emits a machine-readable result (`schema:"baldart.reap-orphans/1"`). Always exits 0 (hygiene, never a blocker). Reuses `src/utils/codex-orphans.js` (the v4.37.0 SSOT); live `codex app-server` brokers are detected and reported but never killed.
+
+### Changed
+
+- **`framework/.claude/skills/new/references/merge-cleanup.md`** (Phase 6c, new step 5b), **`framework/.claude/skills/prd/references/validation-phase.md`** (Step 7.5, new non-blocking closer), **`framework/.claude/skills/new2/SKILL.md`** (Step 5, new item 6) — each workspace-hygiene finalizer now runs `npx baldart reap-orphans` as a NON-BLOCKING step and folds its summary into the phase log. `new2` runs it in the main context after the workflow returns (the workflow sandbox cannot run Bash). All three carry the explicit "reaps orphans only, never the broker" note so a future maintainer does not escalate it into a broker kill.
+
 ## [4.38.0] - 2026-06-15
 
 **`baldart doctor` now checks whether the external tools BALDART installs are out of date upstream, and offers a one-command upgrade.** BALDART installs external tools into consumer machines but **pins none of them** — `pipx install graphifyy`, `npm install -g typescript-language-server`, … all grab "latest" at install time, and neither pipx nor npm ever auto-upgrades. So a consumer who installed months ago is frozen on whatever version they got, and never receives upstream security/correctness fixes; the `add`/`update`/`configure` flows can't help because they only run at install time. Concrete trigger: Graphify shipped `0.8.37` (SSRF guard thread-safety + prompt-injection mitigation + a macOS NFC/NFD re-extraction loop fix), `0.8.38` (`calls` edge-direction + JS/TS default import/export + tsconfig `paths` correctness) and `0.8.39` (a `graphify affected` `KeyError` crash fix — a command BALDART agents actually invoke) — all invisible to a frozen install. This release adds the continuous currency check that was missing: the tool-dependency analogue of the `baldart` CLI's own `UpdateNotifier`. **MINOR** (new doctor diagnostic + self-heal action; backwards-compatible — network-gated and skipped under `--offline`, zero output when every tool is current, no install/layout change, no `baldart.config.yml` key ⇒ schema-propagation rule N/A).

package/VERSION

@@ -1 +1 @@
-4.38.0
+4.39.0

package/bin/baldart.js

@@ -154,6 +154,16 @@ program
     await doctorCommand({ auto: !!options.auto, offline: !!options.offline });
   });
 
+program
+  .command('reap-orphans')
+  .description('Sweep orphaned MCP-server processes left by Codex calls (ppid 1 — their broker is dead). Used by the /new and /prd finalizers; safe to run anytime. Never touches a live codex app-server broker.')
+  .option('--json', 'Machine-readable output: emit a single JSON result object on stdout')
+  .option('--dry-run', 'Detect and report orphans without killing anything')
+  .action(async (options) => {
+    const reapCommand = require('../src/commands/reap-orphans');
+    await reapCommand({ json: !!options.json, dryRun: !!options.dryRun });
+  });
+
 const overlayGroup = program
   .command('overlay')
   .description('Author and check .baldart/overlays/ — scaffolds, validates, and detects drift on skill/agent/command overlays');

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -177,6 +177,20 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
      - Question: `"Restore dello stash di Phase 0 ha generato conflitti. Lo stash è ancora presente (NON eliminato). Come procedo?"`
      - Options: `[Lascia lo stash + apri istruzioni per merge manuale]` / `[Mostrami il conflitto inline]` / `[Halt]`.
 
+5b. **Process hygiene — reap orphaned Codex MCP servers (NON-BLOCKING)**. This
+   batch's per-card / final-review Codex calls drive `codex app-server`, whose
+   broker spawns the MCP servers declared in `~/.codex/config.toml` (Playwright,
+   …) as children; when a broker dies the OS reparents those MCP servers to init
+   (ppid 1) and they keep burning CPU. Sweep them now so the batch ends clean:
+   ```bash
+   npx baldart reap-orphans 2>/dev/null || true
+   ```
+   This reaps ONLY orphaned MCP servers (ppid 1 ⇒ their broker is already dead ⇒
+   stdio is broken ⇒ dead weight). It deliberately NEVER kills a live
+   `codex app-server` broker (a shared, detached runtime that may still serve the
+   user's interactive session). Never gate the close on this — any error or a
+   "nothing to reap" result is fine; capture its one-line summary for the log.
+
 6. **Log and exit**:
    ```
    ## Phase 6c — Workspace Hygiene Post-merge
@@ -185,6 +199,7 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    Divergence (local…origin/$TRUNK): <0\t0 | resolved: pushed/cherry-picked/ff-pulled/rebased>
    Sync-deferred markers: <none | reconciled | user-retained>
    Phase 0 snapshot restore: <n/a | popped clean | conflict-deferred-to-user>
+   Codex MCP hygiene: <reaped N/M | nothing to reap | skipped (error)>
    Completed: <timestamp>
    ```
    If any step ended in HALT, set `Status: HALT` and report — Phase 7 must NOT start with an unclean main repo unless the user explicitly chose `[Lascia così]`.

package/framework/.claude/skills/new2/SKILL.md

@@ -265,3 +265,14 @@ returns when the batch is done. It returns:
    deferrals resolving too late — order the dependent card earlier), and `owner_gated_deduped` > 0
    means N defers were collapsed to one external action.
    Do NOT re-summarise the cards — the workflow already did.
+6. **Process hygiene — reap orphaned Codex MCP servers (NON-BLOCKING).** The batch's per-card Codex
+   finder calls drive `codex app-server`, whose broker spawns the `~/.codex/config.toml` MCP servers
+   (Playwright, …) as children; when a broker dies they leak to init (ppid 1) and keep burning CPU.
+   Sweep them in the main context (the workflow sandbox cannot run Bash, so this MUST run here, after
+   the workflow returns) so the run ends clean:
+   ```bash
+   npx baldart reap-orphans 2>/dev/null || true
+   ```
+   Reaps ONLY orphaned MCP servers (ppid 1 ⇒ broker dead); NEVER kills a live `codex app-server`
+   broker. Non-blocking — any error / "nothing to reap" is fine; fold its one-line summary into the
+   record (`codex_mcp_reaped`).

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -247,6 +247,20 @@ markers it can emit, then act:
 empty, no `[SYNC-NEEDS-DECISION]` marker is left unhandled, and the merged remote
 branch is gone (or its deletion is explicitly user-deferred).
 
+**Process hygiene — reap orphaned Codex MCP servers (NON-BLOCKING).** This run's
+Codex calls (discovery-completeness check, plan audit) drive `codex app-server`,
+whose broker spawns the MCP servers from `~/.codex/config.toml` (Playwright, …)
+as children; when a broker dies the OS reparents them to init (ppid 1) and they
+keep burning CPU. Sweep them now so the run ends clean:
+```bash
+npx baldart reap-orphans 2>/dev/null || true
+```
+This reaps ONLY orphaned MCP servers (ppid 1 ⇒ broker dead ⇒ stdio broken ⇒ dead
+weight); it NEVER kills a live `codex app-server` broker (a shared, detached
+runtime that may still serve the user's interactive session). This is NOT part
+of the blocking gate — any error or "nothing to reap" is fine; include its
+one-line summary in the final summary's hygiene line.
+
 ### Step 7.6 — Obsidian back-reference (NON-BLOCKING — runs only when a spec note was given)
 
 **Why this exists.** When the user kicked off the PRD from an Obsidian note (state file

package/package.json

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

package/src/commands/reap-orphans.js

@@ -0,0 +1,90 @@
+/**
+ * `baldart reap-orphans` — sweep orphaned MCP-server processes left by Codex
+ * calls (since v4.38.0).
+ *
+ * Non-interactive, focused companion to the `baldart doctor` reap action: it
+ * detects MCP servers that have been orphaned to init (ppid 1 — their parent
+ * `codex app-server` broker is dead) and kills each process tree. Designed to be
+ * called from the `/new` (Phase 6c) and `/prd` (Step 7.5) workspace-hygiene
+ * finalizers so each batch ends by clearing the MCP debris its Codex finder
+ * calls (and any prior runs) left behind.
+ *
+ * SCOPE & SAFETY (do not "improve" this into killing the broker):
+ *   - Reaps ONLY orphaned MCP servers (ppid 1 + MCP signature). A live, in-use
+ *     `codex app-server` broker is `detached + unref'd` BY DESIGN and also shows
+ *     ppid 1, so we never touch brokers — killing one could break the user's
+ *     concurrent interactive Codex session. Brokers are reported, never killed.
+ *   - Because MCP children of a *still-alive* broker have ppid = broker (not 1),
+ *     a run whose broker is still warm may leave its own MCP non-orphaned at
+ *     finalizer time; those get swept by the next run's finalizer (or `doctor`).
+ *     This command is a cumulative orphan sweep, not a per-run broker teardown.
+ *
+ * Always exits 0 — this is hygiene, never a blocker. The SSOT for detection /
+ * reaping logic is `src/utils/codex-orphans.js`; this command only frames it.
+ */
+
+const UI = require('../utils/ui');
+const CodexOrphans = require('../utils/codex-orphans');
+
+async function reapOrphans(opts = {}) {
+  const json = !!opts.json;
+  const dryRun = !!opts.dryRun;
+
+  const result = {
+    schema: 'baldart.reap-orphans/1',
+    found: 0,
+    reaped: 0,
+    failed: 0,
+    runtimeBrokers: 0,
+    dryRun,
+    orphans: [],
+    failures: [],
+  };
+
+  try {
+    const procs = CodexOrphans.listProcesses();
+    const { mcp, runtime } = CodexOrphans.detectOrphans(procs);
+    result.found = mcp.length;
+    result.runtimeBrokers = runtime.length;
+    result.orphans = mcp.map((p) => ({ pid: p.pid, etime: p.etime, command: p.command }));
+
+    if (!dryRun && mcp.length > 0) {
+      const { killed, failed } = CodexOrphans.reapOrphans(mcp, procs);
+      result.reaped = killed.length;
+      result.failed = failed.length;
+      result.failures = failed;
+    }
+  } catch (err) {
+    result.error = (err && err.message) || String(err);
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return result;
+  }
+
+  // Human output — single concise summary line + optional detail.
+  if (result.error) {
+    UI.warning(`Codex MCP reap skipped (probe error: ${result.error}).`);
+  } else if (result.found === 0) {
+    UI.success('Codex MCP hygiene: no orphaned MCP servers — nothing to reap.');
+  } else if (dryRun) {
+    UI.warning(`Codex MCP hygiene: ${result.found} orphaned MCP server(s) found (dry-run, not killed):`);
+    result.orphans.slice(0, 8).forEach((o) =>
+      console.log(`   • pid ${o.pid} (up ${o.etime}): ${o.command.slice(0, 70)}`));
+    if (result.orphans.length > 8) console.log(`   • … and ${result.orphans.length - 8} more`);
+  } else {
+    UI.success(`Codex MCP hygiene: reaped ${result.reaped}/${result.found} orphaned MCP server(s) (incl. descendants).`);
+    if (result.failed > 0) {
+      UI.warning(`${result.failed} could not be killed:`);
+      result.failures.forEach((f) => console.log(`    pid ${f.pid}: ${f.error}`));
+    }
+  }
+  if (result.runtimeBrokers > 0) {
+    UI.info(`(${result.runtimeBrokers} codex app-server broker(s) detected — left untouched by design.)`);
+  }
+
+  return result;
+}
+
+module.exports = reapOrphans;