baldart 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [3.13.0] - 2026-05-23
+
+BALDART closes **two drift visibility gaps in one release**. (1) The CLI binary (installed globally via `npm i -g baldart`) and the framework payload (`.framework/` inside each consumer repo, updated by `baldart update`) drifted silently — users on an old CLI never learned that new flags, new doctor checks, or new adapters had shipped. (2) The framework payload on disk and the `.baldart/state.json` ledger could drift silently when the ledger write failed (the catch in `update.js` was silent until now), when an update flow exited mid-way, or when a manual commit excluded `.baldart/state.json` — `baldart doctor` had no way to detect or fix this. Both gaps are now closed: a **non-invasive CLI self-update notifier** for the first, and **ledger drift detection + self-heal** in the doctor for the second. The unifying theme is "no silent drift" — every layer that can fall out of sync now reports it and offers a one-step fix.
+
+### Added
+
+- **`src/utils/update-notifier.js`** — best-effort CLI self-update check. HTTPS GET to `https://registry.npmjs.org/baldart/latest` with a 1.5s timeout, cached at `~/.baldart/cli-update-check.json` (TTL 24h). Banner is printed from the cache on subsequent invocations (the very first run shows nothing — that is intentional; the check never blocks the command). The background refresh fire-and-forget: its timer is `unref()`'d and the underlying socket dies with the process, so the check can never hold the event loop open. Suppression: `BALDART_NO_UPDATE_CHECK=1`, `CI=true`, `NODE_ENV=test`, non-TTY stdout, or `--offline` on `baldart` / `baldart doctor` / `baldart version`.
+- **Top-of-run banner in `bin/baldart.js`** — when a newer baldart npm package has been detected on a previous run, every command prints a 3-line hint at startup (yellow arrow + bold version, then two gray lines): `↑ baldart X.Y.Z available (you have A.B.C)` + `Update with: npm i -g baldart@latest` + `Suppress with: BALDART_NO_UPDATE_CHECK=1`. Zero-latency (reads cache only); no banner if cache is missing or up-to-date.
+- **`CLI` row in `baldart doctor` diagnostic table** — always shown (independent of git/framework state), surfaces drift inline alongside framework version / config / overlays / hooks so the doctor remains the single pane of glass. Severity `warn` when an update is available, `ok` otherwise.
+- **CLI drift in `baldart version` box** — the existing `CLI: vX.Y.Z` line now appends `→ vA.B.C available (npm i -g baldart@latest)` when a newer version was detected.
+- **`State.reconcileInstalledVersion({ to, reason })` in `src/utils/state.js`** — new ledger reconciliation helper. Idempotent (no-op when `from === to`), audit-trailed (writes a `ledger-reconcile` history entry distinct from real `update` events), and reversible (pure local file write). Used by the doctor's new `reconcile-state-ledger` action and available for direct call from future recovery flows.
+- **Ledger drift detection in `baldart doctor`** — `detectState` now compares `.framework/VERSION` against `.baldart/state.json:installed_version` and surfaces a `stateLedgerDrift` state field when they diverge. The action planner inserts a `reconcile-state-ledger` action (`autoOk: true`, idempotent, no remote effects) that one-shot fixes the drift via `State.reconcileInstalledVersion()`. Drift is non-blocking — it pairs with other proposed actions instead of short-circuiting them.
+
+### Changed
+
+- **`src/commands/update.js`** — replaced the silent `try { State.recordUpdate(...) } catch (_) {}` on the ledger write with a visible warning + actionable next step. When the write fails or returns an unexpected `installed_version`, the user now sees a yellow warning explaining the drift (framework on disk is at vNEW but ledger still records vOLD) and is told to run `baldart doctor` to reconcile. This is the root cause of most "my doctor says I'm on the wrong version" reports — silent catches were hiding write failures (permissions, EBUSY) for weeks. New behavior makes the failure immediately visible and self-healable.
+
+### Notes
+
+- **CLI vs framework — two independent layers.** `npm i -g baldart@latest` updates the binary on disk (this package); `baldart update` updates the *framework payload* inside the consumer repo (the `.framework/` subtree). They are *independent* by design — a consumer may want to update the framework without touching the global CLI (or vice versa). The notifier surfaces drift on the *CLI* layer; the existing `Remote` row in doctor (and the `Remote:` line in `version`) surfaces drift on the *framework* layer. Both layers are now visible at a glance from the same diagnostic surface.
+- **Why not auto-install.** Three reasons we deliberately reject `npx baldart` auto-running `npm i -g`: (1) blast radius — global install impacts *every* project on the user's machine, not just the one they invoked from; (2) permissions — `npm i -g` often needs sudo (without nvm/volta), and a no-args `baldart` cannot trigger sudo prompts silently; (3) reproducibility — `--auto` runs in CI must be deterministic, so auto-updating the CLI mid-run would change behavior unpredictably. The notifier is the right level: visible, dismissible, never invasive.
+- **No new `baldart.config.yml` keys.** The notifier cache lives in `~/.baldart/cli-update-check.json` (per-user, not per-project), so the schema-change propagation rule (per `feedback_schema_change_propagation`) does not apply to this release. Suppression is via environment variable (`BALDART_NO_UPDATE_CHECK=1`) which is intentionally global — disabling the notifier in one project but enabling it in another is not a use case worth modeling.
+- **Backwards-compatible.** Pre-3.13 consumers see the new banner on their next `baldart` run after the npm package upgrades. Consumers that never want the check set `BALDART_NO_UPDATE_CHECK=1` in their shell rc; CI runs are auto-suppressed.
+- **No framework payload changes.** All work is inside `src/` and `bin/` — the framework agents/skills/commands/protocols are unchanged. This is purely a CLI-layer improvement; no consumer files are touched by `baldart update`.
+
 ## [3.12.0] - 2026-05-23
 
 BALDART completes the **UI excellence loop**: the `ui-expert` agent is upgraded from a "good but generic" baseline to a world-class UI/UX reviewer/designer, and — crucially — the registry-first discipline gains a **post-intervention coherence gate** so visual coherence is enforced not only when work begins (BLOCKING reads) but also when work ends (BLOCKING completion check). The asymmetry of v3.11.0 (registry read before, no verification after) is closed: every UI change introduced by `ui-expert`, the `ui-design` skill, the `frontend-design` skill, or caught by `code-reviewer` must now reconcile the registry (INDEX + per-component specs + tokens-reference) in the **same change**, never deferring drift to the weekly `ds-drift` routine. This release contains zero schema changes — the cascade reuses `features.has_design_system` + `paths.*` already in place.

package/README.md

@@ -156,6 +156,30 @@ last-push info. Use `--offline` to skip the upstream fetch.
 
 State updates happen automatically — no manual bookkeeping required.
 
+### CLI self-update notifier (new in v3.13.0)
+
+The CLI binary (`baldart`, installed globally via `npm i -g baldart`) and the
+framework payload (`.framework/` inside each repo, updated by `baldart update`)
+are two independent layers. Until now the CLI drifted silently — users on an
+old CLI never learned about new flags or new doctor checks.
+
+Now every `baldart` run does a best-effort check against `registry.npmjs.org`
+(cached at `~/.baldart/cli-update-check.json` with a 24h TTL, 1.5s network
+timeout, fire-and-forget). When a newer version is available, a one-shot
+banner appears at the top of the run:
+
+```
+↑ baldart 3.13.0 available (you have 3.12.0)
+  Update with: npm i -g baldart@latest
+  Suppress with: BALDART_NO_UPDATE_CHECK=1
+```
+
+The notifier never installs anything automatically — global installs can
+require sudo and affect every other project on your machine, so the choice
+stays with you. CLI drift also appears inline in `baldart doctor` (new `CLI`
+row) and in `baldart version`. Auto-suppressed in CI, in non-TTY runs, with
+`--offline`, with `NODE_ENV=test`, or via `BALDART_NO_UPDATE_CHECK=1`.
+
 ### Project Configuration (new in v3.0.0)
 
 BALDART skills are **portable across projects**. Instead of hard-coding paths

package/VERSION

@@ -1 +1 @@
-3.12.0
+3.13.0

package/bin/baldart.js

@@ -3,6 +3,20 @@
 const { Command } = require('commander');
 const chalk = require('chalk');
 const packageJson = require('../package.json');
+const updateNotifier = require('../src/utils/update-notifier');
+
+// CLI self-update notifier (v3.13.0+). Best-effort; non-blocking; suppressed
+// in CI / non-TTY / via BALDART_NO_UPDATE_CHECK=1 / when --offline is passed.
+// Prints a one-shot hint at the top of the run if a newer npm version was
+// detected on a previous invocation, then kicks off a background refresh.
+// First-ever run shows nothing — that is intentional; we never block the
+// command on a network call.
+const rawArgsForNotifier = process.argv.slice(2);
+const offlineForNotifier = rawArgsForNotifier.includes('--offline');
+updateNotifier.announceAndRefresh({
+  currentVersion: packageJson.version,
+  offline: offlineForNotifier,
+});
 
 const program = new Command();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.12.0",
+  "version": "3.13.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

@@ -31,6 +31,8 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 const LspInstaller = require('../utils/lsp-installer');
+const UpdateNotifier = require('../utils/update-notifier');
+const cliPackageJson = require('../../package.json');
 
 const FRAMEWORK_DIR = '.framework';
 const REPO_DEFAULT = 'antbald/BALDART';
@@ -146,6 +148,8 @@ async function detectState(cwd, opts = {}) {
   const git = new GitUtils(cwd);
   const state = {
     cwd,
+    cliVersion: cliPackageJson.version,
+    cliUpdate: UpdateNotifier.hint({ currentVersion: cliPackageJson.version }),
     isGitRepo: await git.isGitRepo(),
     frameworkPresent: await git.frameworkExists(),
     legacyLayout: false,
@@ -188,6 +192,19 @@ async function detectState(cwd, opts = {}) {
       ? `v${ledger.last_pushed_version} (${(ledger.last_push_date || '').slice(0, 10) || '—'})`
       : null;
 
+    // Ledger drift detection (v3.13.0+): the framework on disk says one thing,
+    // the ledger says another. Caused by interrupted updates, manual commits
+    // that excluded state.json, or filesystem write failures the old silent
+    // catch in update.js used to hide. Self-healable via `reconcile-state-ledger`.
+    state.stateLedgerDrift = null;
+    if (state.frameworkVersion && ledger.installed_version &&
+        state.frameworkVersion !== ledger.installed_version) {
+      state.stateLedgerDrift = {
+        payload: state.frameworkVersion,
+        ledger: ledger.installed_version
+      };
+    }
+
     state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
     state.commitsAhead = await commitsAheadOfRemote(git);
     state.workingTreeDirty = await localFrameworkChanges(git);
@@ -313,6 +330,28 @@ function planActions(state) {
     // Drift is non-blocking — keep checking for other actions after.
   }
 
+  if (state.stateLedgerDrift) {
+    actions.push({
+      key: 'reconcile-state-ledger',
+      label: `Reconcile state ledger (${state.stateLedgerDrift.ledger} → ${state.stateLedgerDrift.payload})`,
+      why: `.framework/VERSION is v${state.stateLedgerDrift.payload} but .baldart/state.json records installed_version=${state.stateLedgerDrift.ledger}. Typical causes: an update flow that exited mid-way (configure declined, stash conflict), a manual commit that excluded .baldart/state.json, or a write failure that the old silent catch in update.js used to hide (fixed in v3.13.0).`,
+      autoOk: true, // pure local file write, idempotent, fully reversible
+      run: () => {
+        const res = State.reconcileInstalledVersion({
+          to: state.stateLedgerDrift.payload,
+          reason: 'doctor reconcile — payload/ledger drift'
+        });
+        if (res.changed) {
+          UI.success(`Ledger updated: installed_version ${res.from} → ${res.to}`);
+          UI.info('History entry "ledger-reconcile" recorded for audit. Commit .baldart/state.json when ready.');
+        } else {
+          UI.info('No change needed — ledger already matches payload.');
+        }
+      },
+    });
+    // Drift is non-blocking — keep checking for other actions after.
+  }
+
   if (state.editGateRegistered === false) {
     actions.push({
       key: 'register-edit-gate',
@@ -394,6 +433,17 @@ function renderDiagnostic(state) {
   console.log(`Repository:    ${state.cwd}`);
   console.log();
 
+  // CLI version line — always shown (independent of git repo state). When a
+  // newer baldart npm package was detected on a previous run, surface it here
+  // so the doctor table is the single pane of glass for "what's stale".
+  console.log(statusLine(
+    'CLI',
+    state.cliUpdate
+      ? `v${state.cliVersion} → v${state.cliUpdate.latest} available (npm i -g baldart@latest)`
+      : `v${state.cliVersion}`,
+    state.cliUpdate ? 'warn' : 'ok'
+  ));
+
   console.log(statusLine('Git repo', state.isGitRepo ? 'yes' : 'no', state.isGitRepo ? 'ok' : 'err'));
 
   if (!state.isGitRepo) return;
@@ -429,9 +479,11 @@ function renderDiagnostic(state) {
   console.log(statusLine(
     'State ledger',
     state.statePresent
-      ? `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`
+      ? (state.stateLedgerDrift
+          ? `drift: ledger=v${state.stateLedgerDrift.ledger}, payload=v${state.stateLedgerDrift.payload}`
+          : `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`)
       : 'not seeded',
-    state.statePresent ? 'ok' : 'warn'
+    state.stateLedgerDrift ? 'warn' : (state.statePresent ? 'ok' : 'warn')
   ));
 
   if (state.stateLastUpdate) {

package/src/commands/update.js

@@ -246,7 +246,21 @@ async function update(options = {}) {
 
       newVersion = await git.getFrameworkVersion();
       UI.success(`New version: ${newVersion}`);
-      try { State.recordUpdate({ from: currentVersion, to: newVersion }); } catch (_) { /* non-fatal */ }
+      // Update the ledger and VERIFY the write landed. Prior to v3.13.0 this
+      // call used a silent catch — write failures (permissions, EBUSY) were
+      // hidden, and the user only noticed the drift weeks later via doctor.
+      // Now: visible warning + always-actionable next step.
+      try {
+        const after = State.recordUpdate({ from: currentVersion, to: newVersion });
+        if (after.installed_version !== newVersion) {
+          UI.warning(`Ledger write returned installed_version=${after.installed_version}, expected ${newVersion}.`);
+          UI.info('Run `baldart doctor` to reconcile the ledger.');
+        }
+      } catch (err) {
+        UI.warning(`Could not write .baldart/state.json: ${err.message}`);
+        UI.info(`Framework on disk is at v${newVersion} but the ledger still records v${currentVersion}.`);
+        UI.info('Run `baldart doctor` to reconcile, or check filesystem permissions on .baldart/state.json.');
+      }
 
       // Re-apply the pre-update stash (if any). Conflicts mean we leave the
       // stash intact and tell the user how to resolve — never silently drop.

package/src/commands/version.js

@@ -1,6 +1,7 @@
 const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
+const UpdateNotifier = require('../utils/update-notifier');
 
 const REPO_DEFAULT = 'antbald/BALDART';
 const FRAMEWORK_DIR = '.framework';
@@ -48,6 +49,7 @@ async function version(opts = {}) {
     const frameworkVersion = await git.getFrameworkVersion();
     const state = State.load();
     const cliVersion = require('../../package.json').version;
+    const cliUpdate = UpdateNotifier.hint({ currentVersion: cliVersion });
 
     // Optionally fetch upstream to compute drift (default: yes).
     const offline = opts.offline === true;
@@ -75,7 +77,9 @@ async function version(opts = {}) {
       `Last update: ${fmtDate(state.last_update_date)}`,
       `Last push:   v${state.last_pushed_version || '—'}    ${state.last_push_date ? `(${fmtDate(state.last_push_date)})` : ''}`.trim(),
       '',
-      `CLI:         v${cliVersion}`,
+      cliUpdate
+        ? `CLI:         v${cliVersion} → v${cliUpdate.latest} available (npm i -g baldart@latest)`
+        : `CLI:         v${cliVersion}`,
       `Repository:  https://github.com/${state.framework_repo || REPO_DEFAULT}`,
     ].filter((l) => l !== ''));
     UI.newline();

package/src/utils/state.js

@@ -106,6 +106,32 @@ function recordUpdate({ from, to }, cwd = process.cwd()) {
   return state;
 }
 
+/**
+ * Reconcile the ledger's installed_version with the actual framework version
+ * on disk (read from .framework/VERSION). Used by `baldart doctor` when it
+ * detects a mismatch between the payload and the ledger — typically caused by
+ * an interrupted update flow, a manual commit that excluded state.json, or a
+ * filesystem write failure that the silent catch in update.js used to hide.
+ *
+ * Idempotent: calling with the already-current version is a no-op (no history
+ * entry produced). History entry uses event "ledger-reconcile" so the source
+ * of the bump is auditable separately from real updates.
+ */
+function reconcileInstalledVersion({ to, reason }, cwd = process.cwd()) {
+  const state = load(cwd);
+  const from = state.installed_version;
+  if (from === to) return { state, changed: false };
+  state.installed_version = to;
+  state.history = appendHistory(state, {
+    event: 'ledger-reconcile',
+    from,
+    to,
+    note: reason || 'reconcile ledger with .framework/VERSION'
+  });
+  save(state, cwd);
+  return { state, changed: true, from, to };
+}
+
 function recordPush({ from, to, description }, cwd = process.cwd()) {
   const state = load(cwd);
   state.last_pushed_version = to;
@@ -137,6 +163,7 @@ module.exports = {
   recordInstall,
   recordUpdate,
   recordPush,
+  reconcileInstalledVersion,
   readFrameworkVersion,
   STATE_FILE,
   STATE_VERSION,

package/src/utils/update-notifier.js

@@ -0,0 +1,181 @@
+/**
+ * CLI self-update notifier (v3.13.0+).
+ *
+ * The framework payload inside `.framework/` is updated by `baldart update`.
+ * The CLI itself (this package) is updated by `npm i -g baldart@latest`.
+ * Until now those two layers drifted silently — users on an old CLI never
+ * learned new flags, new doctor checks, new adapters had shipped.
+ *
+ * This module surfaces CLI drift WITHOUT auto-installing anything. It is
+ * deliberately non-invasive:
+ *
+ *   - Best-effort HTTP check against the npm registry with a short timeout.
+ *   - Result cached at `~/.baldart/cli-update-check.json` (TTL 24h).
+ *   - Banner printed from the cache on the NEXT invocation (zero latency on
+ *     every run). First-ever run shows nothing — that's intentional.
+ *   - Suppressed in CI, non-TTY, --offline, NODE_ENV=test, or via
+ *     BALDART_NO_UPDATE_CHECK=1.
+ *   - Never blocks the process: the background refresh is fire-and-forget,
+ *     its timer/socket are unref'd so they cannot hold the event loop open.
+ *
+ * Design rationale (see CHANGELOG v3.13.0): we explicitly DO NOT run
+ * `npm i -g baldart@latest` automatically. Auto-updates inside a per-project
+ * CLI invocation would (a) impact every other project on the user's machine,
+ * (b) potentially require sudo, (c) break determinism in CI runs. The banner
+ * gives the user the choice; the cache means they don't pay for it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const REGISTRY_URL = 'https://registry.npmjs.org/baldart/latest';
+const CACHE_DIR = path.join(os.homedir(), '.baldart');
+const CACHE_FILE = path.join(CACHE_DIR, 'cli-update-check.json');
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const DEFAULT_TIMEOUT_MS = 1500;
+
+function isSuppressed({ offline } = {}) {
+  if (offline) return true;
+  if (process.env.BALDART_NO_UPDATE_CHECK === '1') return true;
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.NODE_ENV === 'test') return true;
+  // `process.stdout.isTTY` is `true` when attached to a terminal and
+  // `undefined` (NOT `false`) when not — so we must test for "not strictly
+  // true" rather than "=== false", otherwise piped/redirected runs silently
+  // bypass suppression.
+  if (!(process.stdout && process.stdout.isTTY === true)) return true;
+  return false;
+}
+
+function readCache() {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return null;
+    const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (!data || typeof data !== 'object') return null;
+    return data;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2) + '\n');
+  } catch (_) {
+    // Best-effort: a read-only HOME or denied write is not worth surfacing.
+  }
+}
+
+function cmpSemver(a, b) {
+  // Returns 1 if a>b, -1 if a<b, 0 if equal. Strips prerelease and build
+  // metadata; only X.Y.Z is compared. That is enough for a "is there a newer
+  // stable on npm?" prompt — anything fancier belongs in `semver`, and we are
+  // deliberately staying dep-free here.
+  if (!a || !b) return 0;
+  const norm = (v) => String(v).split(/[-+]/)[0].split('.').map((n) => Number(n) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0, y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+async function fetchLatest(timeoutMs) {
+  if (typeof fetch !== 'function') return null; // Node < 18 fallback — node engine constraint covers this, but defensive.
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body && body.version ? String(body.version) : null;
+  } catch (_) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function refresh({ currentVersion, timeoutMs = DEFAULT_TIMEOUT_MS, force = false } = {}) {
+  const cached = readCache();
+  const now = Date.now();
+  if (!force && cached && cached.checked_at) {
+    const age = now - new Date(cached.checked_at).getTime();
+    if (Number.isFinite(age) && age < DEFAULT_TTL_MS) return cached;
+  }
+  const latest = await fetchLatest(timeoutMs);
+  if (!latest) return cached; // Keep stale cache rather than zeroing it.
+  const data = {
+    checked_at: new Date().toISOString(),
+    latest,
+    current_at_check: currentVersion,
+  };
+  writeCache(data);
+  return data;
+}
+
+function hint({ currentVersion } = {}) {
+  if (!currentVersion) return null;
+  const cached = readCache();
+  if (!cached || !cached.latest) return null;
+  if (cmpSemver(cached.latest, currentVersion) <= 0) return null;
+  return {
+    latest: cached.latest,
+    current: currentVersion,
+    checked_at: cached.checked_at,
+  };
+}
+
+function printBanner(info) {
+  if (!info) return;
+  const chalk = require('chalk');
+  const line1 = chalk.yellow('↑') + ' ' + chalk.bold(`baldart ${info.latest}`) +
+    chalk.gray(` available (you have ${info.current})`);
+  const line2 = chalk.gray('  Update with: ') + chalk.cyan('npm i -g baldart@latest');
+  const line3 = chalk.gray('  Suppress with: BALDART_NO_UPDATE_CHECK=1');
+  console.log('');
+  console.log(line1);
+  console.log(line2);
+  console.log(line3);
+  console.log('');
+}
+
+function backgroundCheck({ currentVersion, offline = false } = {}) {
+  // Fire-and-forget. Returns immediately; never throws; cannot block exit.
+  if (isSuppressed({ offline })) return;
+  refresh({ currentVersion }).catch(() => {});
+}
+
+/**
+ * Cheap entry point for bin/baldart.js: print the banner if a cached update
+ * is known, then kick off a refresh for next time. No-op when suppressed.
+ */
+function announceAndRefresh({ currentVersion, offline = false } = {}) {
+  if (isSuppressed({ offline })) return null;
+  const info = hint({ currentVersion });
+  if (info) printBanner(info);
+  backgroundCheck({ currentVersion, offline });
+  return info;
+}
+
+module.exports = {
+  isSuppressed,
+  refresh,
+  hint,
+  printBanner,
+  backgroundCheck,
+  announceAndRefresh,
+  // Exported for tests / introspection:
+  _cmpSemver: cmpSemver,
+  _CACHE_FILE: CACHE_FILE,
+  _DEFAULT_TTL_MS: DEFAULT_TTL_MS,
+};