baldart 4.36.0 → 4.38.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.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).
+
+### Added
+
+- **`src/utils/tool-currency.js`** — external-tool currency prober. `probeAll()` returns one record per managed tool BALDART can query against its upstream registry, comparing the installed version to the latest published one. Probes today: **Graphify** (`graphifyy` on PyPI, gated on `features.has_code_graph` + binary present) and **LSP language servers** (gated on `features.has_lsp_layer`; `npm-global` adapters queried via the npm registry, `system` adapters — gopls, rust-analyzer — reported `unknown` with their canonical `@latest` reinstall command rather than a probe we can't cheaply run). Invariants mirror the rest of doctor's probes: **best-effort** (a failed probe is omitted, never throws, never blocks), **honest** (`status: 'outdated'` only with BOTH versions known and installed < latest — `unknown`/`current` are never surfaced as a nag), **offline-aware** (the caller skips it entirely under `--offline`).
+- **`src/utils/http.js`** — dependency-free `getJson(url, {timeoutMs})` over `https` core (no reliance on the Node 18 `fetch` flag), resolving `null` on any failure. Used by the currency layer to read registry metadata.
+- **`src/utils/semver-lite.js`** — tolerant dependency-free version comparison (`cmpVersions`) for heterogeneous registry strings (`0.8.39`, `v1.2`, `4.3.3`, `1.2.3-rc1`); returns `0` (no nag) on unparseable input. Shared by `graphify-installer` and `tool-currency`.
+- **`src/utils/graphify-installer.js`** — `checkUpgrade()` (installed CLI vs latest `graphifyy` on PyPI; best-effort, async, never nags on uncertainty) and `upgrade()` (`pipx upgrade graphifyy`, falling back to `pip --user --upgrade`; never throws).
+- **`src/commands/doctor.js`** — new probe (`state.toolCurrency`, network-gated on `!--offline`) and one non-blocking upgrade action per tool **confirmed** behind upstream (`tool-upgrade:<tool>`, `autoOk: false` — upgrading a system-level tool warrants explicit intent). Auto-upgradable tools (pipx/npm) run the upgrade in place; non-auto ones (system toolchains) print the canonical `@latest` command. `unknown`/`current` tools produce no action — no nag without proof.
+
+## [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,25 @@ 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.
+
+Since v4.38.0 it also checks **external-tool version currency** — BALDART pins
+none of the tools it installs (`graphifyy` via pipx, language servers via npm),
+and pipx/npm never auto-upgrade, so an old install silently misses upstream
+security/correctness fixes. The doctor probes the managed tools against their
+registries (PyPI / npm) and surfaces a non-blocking one-command upgrade for any
+confirmed behind upstream (e.g. `Upgrade Graphify 0.8.36 → 0.8.39`). Network-gated
+— skipped under `--offline`, silent when everything is current.
 
 ```bash
 npx baldart            # diagnostic + interactive prompts

package/VERSION

@@ -1 +1 @@
-4.36.0
+4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.36.0",
+  "version": "4.38.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,8 @@ const Hooks = require('../utils/hooks');
 const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const GraphifyInstaller = require('../utils/graphify-installer');
+const ToolCurrency = require('../utils/tool-currency');
+const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
 
@@ -388,6 +390,41 @@ async function detectState(cwd, opts = {}) {
         }
       }
     } catch (_) { /* never block doctor on graph probe */ }
+
+    // ---- External-tool version currency (since v4.38.0) ----------------
+    // BALDART pins none of the external tools it installs (graphifyy via pipx,
+    // language servers via npm/system) — pipx/npm never auto-upgrade, so a
+    // consumer installed months ago is frozen and never receives upstream
+    // security/correctness fixes. Probe the managed tools against their
+    // registries and let the planner surface a non-blocking upgrade. Network;
+    // skipped entirely under --offline. Best-effort — never blocks doctor.
+    state.toolCurrency = [];
+    if (!opts.offline) {
+      try {
+        state.toolCurrency = await ToolCurrency.probeAll({
+          cwd,
+          config: (config && !config.__malformed) ? config : null,
+          lspInstalled: state.lspInstalled,
+        });
+      } catch (_) { /* never block doctor on currency 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 +818,62 @@ function planActions(state) {
     });
   }
 
+  // External-tool version currency (since v4.38.0). One non-blocking upgrade
+  // action per managed tool confirmed behind upstream — the tool-dependency
+  // analogue of the `baldart` CLI's own UpdateNotifier. `unknown`/`current`
+  // records are NOT surfaced (no nag without proof). Auto-upgradable records
+  // (pipx/npm) get a runnable action; non-auto ones (system toolchains) print
+  // the canonical `@latest` command without auto-running it.
+  for (const rec of ToolCurrency.outdated(state.toolCurrency)) {
+    actions.push({
+      key: `tool-upgrade:${rec.tool}`,
+      label: `Upgrade ${rec.label} ${rec.installed} → ${rec.latest}`,
+      why: `${rec.label} is installed at ${rec.installed} but ${rec.latest} is published (${rec.source}). BALDART pins no external-tool versions and ${rec.autoUpgradable ? 'pipx/npm' : 'the system package manager'} never auto-upgrades, so this install is missing every upstream fix since ${rec.installed}. Upgrade with: \`${rec.upgradeCommand}\`.`,
+      autoOk: false, // upgrading a system-level tool warrants explicit intent
+      run: async () => {
+        if (rec.autoUpgradable && typeof rec.upgrade === 'function') {
+          const r = rec.upgrade();
+          if (r && r.ok) UI.success(`${rec.label} upgraded${r.method ? ` via ${r.method}` : ''}.`);
+          else UI.warning(`Upgrade failed: ${(r && r.error) || 'unknown error'}. Run \`${rec.upgradeCommand}\` manually.`);
+        } else {
+          UI.info(`Run to upgrade ${rec.label}:`);
+          console.log(`    ${rec.upgradeCommand}`);
+        }
+      },
+    });
+  }
+
+  // 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 +1130,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,
+};

package/src/utils/graphify-installer.js

@@ -2,6 +2,8 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const UI = require('./ui');
+const { getJson } = require('./http');
+const { cmpVersions } = require('./semver-lite');
 
 /**
  * High-level installer/wrapper for the Graphify code-knowledge-graph layer,
@@ -47,6 +49,51 @@ class GraphifyInstaller {
     }
   }
 
+  // ── Version currency (since v4.38.0) ──────────────────────────────────────
+
+  /**
+   * Compare the installed `graphify` CLI against the latest `graphifyy` on
+   * PyPI. BEST-EFFORT: returns `{ installed, latest, outdated, source }` where
+   * any field may be `null` when it cannot be determined (offline, CLI absent,
+   * PyPI unreachable). `outdated` is only `true` with BOTH versions known and
+   * installed < latest — never nags on uncertainty. Async (network); never
+   * throws. The upgrade command is `pipx upgrade graphifyy` (see `upgrade()`).
+   */
+  async checkUpgrade({ timeoutMs = 4000 } = {}) {
+    const installed = this.verify().version || null;
+    let latest = null;
+    try {
+      const data = await getJson('https://pypi.org/pypi/graphifyy/json', { timeoutMs });
+      latest = (data && data.info && data.info.version) || null;
+    } catch { latest = null; }
+    const outdated = !!(installed && latest && cmpVersions(installed, latest) < 0);
+    return { tool: 'graphify', installed, latest, outdated, source: 'pypi:graphifyy' };
+  }
+
+  /**
+   * Upgrade the Graphify CLI in place via the same package manager that can
+   * install it (pipx preferred, then pip --user). Returns `{ ok, method?,
+   * error? }`. Never throws. Safe to run unattended (no sudo); the command
+   * layer still asks for explicit intent before invoking it.
+   */
+  upgrade({ spinner = true } = {}) {
+    const attempts = [];
+    if (this._hasCmd('pipx')) attempts.push({ method: 'pipx', cmd: 'pipx upgrade graphifyy' });
+    if (this._hasCmd('pip3')) attempts.push({ method: 'pip3 --user', cmd: 'pip3 install --user --upgrade graphifyy' });
+    if (this._hasCmd('pip')) attempts.push({ method: 'pip --user', cmd: 'pip install --user --upgrade graphifyy' });
+    if (!attempts.length) return { ok: false, error: 'no pipx/pip found on PATH' };
+    const sp = spinner ? UI.spinner('Upgrading Graphify (graphifyy)…').start() : null;
+    for (const a of attempts) {
+      try {
+        execSync(a.cmd, { stdio: 'pipe', timeout: 300000 });
+        if (sp) sp.succeed(`Upgraded Graphify via ${a.method}`);
+        return { ok: true, method: a.method };
+      } catch (_) { /* try next */ }
+    }
+    if (sp) sp.fail('Graphify upgrade failed');
+    return { ok: false, error: `upgrade failed (tried: ${attempts.map(a => a.method).join(', ')}). Run \`pipx upgrade graphifyy\` manually.` };
+  }
+
   /** Absolute path to the graph artifact for a graphed root. */
   graphPath(root = this.cwd, outputDir = 'graphify-out') {
     return path.join(root, outputDir, 'graph.json');

package/src/utils/http.js

@@ -0,0 +1,35 @@
+const https = require('https');
+
+/**
+ * Minimal dependency-free JSON GET with a hard timeout.
+ *
+ * Used by the external-tool currency layer (`tool-currency.js`,
+ * `graphify-installer.checkUpgrade`) to ask a package registry "what is the
+ * latest published version?". It is deliberately tiny and BEST-EFFORT:
+ *   - resolves `null` on ANY failure (DNS, TLS, non-200, bad JSON, timeout),
+ *   - never throws, never rejects — currency checks must never break a flow.
+ *
+ * `https` core only (no `node-fetch`, no relying on global `fetch` which is
+ * still flagged on the Node 18 floor). HTTP is not supported on purpose:
+ * registry metadata is always HTTPS.
+ */
+function getJson(url, { timeoutMs = 4000, headers = {} } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val) => { if (!settled) { settled = true; resolve(val); } };
+    let req;
+    try {
+      req = https.get(url, { headers: { 'User-Agent': 'baldart-doctor', Accept: 'application/json', ...headers } }, (res) => {
+        if (res.statusCode !== 200) { res.resume(); return done(null); }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { body += c; if (body.length > 5_000_000) { req.destroy(); done(null); } });
+        res.on('end', () => { try { done(JSON.parse(body)); } catch { done(null); } });
+      });
+    } catch { return done(null); }
+    req.on('error', () => done(null));
+    req.setTimeout(timeoutMs, () => { req.destroy(); done(null); });
+  });
+}
+
+module.exports = { getJson };

package/src/utils/semver-lite.js

@@ -0,0 +1,38 @@
+/**
+ * Tolerant, dependency-free version comparison for the external-tool currency
+ * layer. NOT a full semver implementation — registry version strings from
+ * heterogeneous tools (PyPI `0.8.39`, a language server's `4.3.3`, a `v1.2`
+ * prefix, an `1.2.3-rc1` suffix) only need a stable "is A behind B?" ordering.
+ *
+ * Rules:
+ *   - leading `v`/`graphify ` style noise is stripped, numeric dotted core is
+ *     compared field by field (missing fields treated as 0, so `1.2` < `1.2.1`),
+ *   - any non-numeric suffix (`-rc1`, `+build`) is ignored for ordering — a
+ *     pre-release is treated as equal to its release core, which is acceptable
+ *     for a "should I upgrade?" hint (we never auto-act on a tie),
+ *   - unparseable input yields `null` from `parse`, and `cmpVersions` returns
+ *     `0` (treat as equal → no nag) when either side is unparseable.
+ */
+function parse(v) {
+  if (v == null) return null;
+  const m = String(v).match(/(\d+(?:\.\d+)*)/);
+  if (!m) return null;
+  return m[1].split('.').map((n) => parseInt(n, 10));
+}
+
+/** -1 if a<b, 1 if a>b, 0 if equal/unknown. Never throws. */
+function cmpVersions(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+module.exports = { parse, cmpVersions };

package/src/utils/tool-currency.js

@@ -0,0 +1,148 @@
+const { execSync } = require('child_process');
+const { cmpVersions } = require('./semver-lite');
+const GraphifyInstaller = require('./graphify-installer');
+const { REGISTRY } = require('./lsp-adapters');
+
+/**
+ * External-tool currency layer (since v4.38.0).
+ *
+ * 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). pipx/npm never auto-upgrade, so a
+ * consumer that installed months ago is frozen — security/correctness fixes
+ * never reach them. The `add`/`update`/`configure` flows can't help: they run
+ * at install time, not continuously.
+ *
+ * This module is the missing continuous check. `baldart doctor` probes the
+ * tools it manages against their upstream registries and surfaces a
+ * non-blocking "X is N versions behind — upgrade with: …" action. It is the
+ * tool-dependency analogue of `UpdateNotifier` (which already does this for the
+ * `baldart` npm package itself).
+ *
+ * Invariants (mirroring the rest of doctor's probes):
+ *   - BEST-EFFORT: every probe resolves to a record or is omitted; a failed
+ *     probe never throws and never blocks doctor.
+ *   - HONEST: `status` is `'outdated'` only when BOTH installed and latest are
+ *     known and installed < latest. When latest can't be fetched (offline,
+ *     registry down, system package manager we can't query) the record is
+ *     `'unknown'` — we never claim up-to-date we can't prove, and never nag.
+ *   - OFFLINE-AWARE: the caller skips `probeAll` entirely under `--offline`.
+ *
+ * Record shape:
+ *   { tool, label, installed, latest, status: 'outdated'|'current'|'unknown',
+ *     upgradeCommand, autoUpgradable, source, upgrade? }
+ * `upgrade` (when present) is a thunk doctor can run to perform the upgrade.
+ */
+
+/** Run a command and pull the first dotted-numeric version token from stdout. */
+function _probeBinaryVersion(cmd, timeoutMs = 8000) {
+  try {
+    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs }).toString();
+    const m = out.match(/(\d+\.\d+(?:\.\d+)?)/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+/** `npm view <pkg> version` → latest published version, or null. Network. */
+function _npmLatest(pkg, timeoutMs = 8000) {
+  try {
+    return execSync(`npm view ${pkg} version`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs })
+      .toString().trim() || null;
+  } catch { return null; }
+}
+
+/** Build the Graphify currency record (only when the layer is on + present). */
+async function _graphifyRecord(cwd, config, timeoutMs) {
+  if (!(config && config.features && config.features.has_code_graph === true)) return null;
+  const gi = new GraphifyInstaller(cwd);
+  if (!gi.detect()) return null; // a missing binary is the install action's job, not currency
+  const r = await gi.checkUpgrade({ timeoutMs });
+  return {
+    tool: 'graphify',
+    label: 'Graphify (graphifyy)',
+    installed: r.installed,
+    latest: r.latest,
+    status: r.outdated ? 'outdated' : (r.installed && r.latest ? 'current' : 'unknown'),
+    upgradeCommand: 'pipx upgrade graphifyy',
+    autoUpgradable: true,
+    source: 'pypi:graphifyy',
+    upgrade: () => gi.upgrade({ spinner: false }),
+  };
+}
+
+/**
+ * Build LSP language-server currency records. Only `npm-global` adapters can
+ * be queried generically (npm registry + `<binary> --version`). `system`-mode
+ * servers (gopls, rust-analyzer) live under per-language toolchains we don't
+ * version-probe — we emit an `'unknown'` record carrying the canonical
+ * `@latest` reinstall command so the user can refresh on their terms.
+ */
+function _lspRecords(cwd, config, lspInstalled, timeoutMs) {
+  if (!(config && config.features && config.features.has_lsp_layer === true)) return [];
+  const names = Array.isArray(lspInstalled) ? lspInstalled : [];
+  const records = [];
+  for (const name of names) {
+    const Cls = REGISTRY[name];
+    if (!Cls) continue;
+    let adapter;
+    try { adapter = new Cls(cwd); } catch { continue; }
+    const installed = _probeBinaryVersion(adapter.verifyCommand(), timeoutMs);
+    if (!installed) continue; // broken/absent server is the LSP-repair action's job
+    if (adapter.installMode === 'npm-global') {
+      // First whitespace-separated token of npmPackage is the versioned one.
+      const pkg = String(adapter.npmPackage || adapter.binary).split(/\s+/)[0];
+      const latest = _npmLatest(pkg, timeoutMs);
+      const outdated = !!(latest && cmpVersions(installed, latest) < 0);
+      records.push({
+        tool: `lsp:${name}`,
+        label: `${adapter.label} LSP (${pkg})`,
+        installed,
+        latest,
+        status: outdated ? 'outdated' : (latest ? 'current' : 'unknown'),
+        upgradeCommand: adapter.installCommand(), // already pins @latest
+        autoUpgradable: true,
+        source: `npm:${pkg}`,
+        upgrade: () => {
+          try { execSync(adapter.installCommand(), { stdio: 'pipe', cwd, timeout: 300000 }); return { ok: true, method: 'npm -g' }; }
+          catch (e) { return { ok: false, error: (e.message || '').split('\n')[0] }; }
+        },
+      });
+    } else {
+      records.push({
+        tool: `lsp:${name}`,
+        label: `${adapter.label} LSP (${adapter.binary})`,
+        installed,
+        latest: null,
+        status: 'unknown', // system toolchain — can't cheaply ask "latest"
+        upgradeCommand: adapter.installCommand(), // e.g. `... @latest`
+        autoUpgradable: false,
+        source: 'system',
+      });
+    }
+  }
+  return records;
+}
+
+/**
+ * Probe every external tool BALDART manages for version currency.
+ * Returns an array of records (possibly empty). Async (network). Never throws.
+ * The caller is responsible for skipping this under `--offline`.
+ */
+async function probeAll({ cwd = process.cwd(), config = null, lspInstalled = [], timeoutMs = 6000 } = {}) {
+  const records = [];
+  try {
+    const g = await _graphifyRecord(cwd, config, timeoutMs);
+    if (g) records.push(g);
+  } catch { /* best-effort */ }
+  try {
+    records.push(..._lspRecords(cwd, config, lspInstalled, timeoutMs));
+  } catch { /* best-effort */ }
+  return records;
+}
+
+/** Convenience: only the records that are confirmed behind upstream. */
+function outdated(records) {
+  return (records || []).filter((r) => r.status === 'outdated');
+}
+
+module.exports = { probeAll, outdated, _probeBinaryVersion, _npmLatest };