baldart 4.37.0 → 4.39.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
+
+### 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).

package/README.md

@@ -508,6 +508,14 @@ MCP servers from `~/.codex/config.toml` (Playwright, …) and leaks them to init
 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
 npx baldart --auto     # CI-friendly: skip y/n; error out on ambiguity

package/VERSION

@@ -1 +1 @@
-4.37.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.37.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/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 ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
@@ -390,6 +391,24 @@ 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
@@ -799,6 +818,31 @@ 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

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;

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 };