gsd-pi 2.31.2 → 2.32.0-dev.3d7932c

package/src/resources/extensions/gsd/doctor-providers.ts

@@ -0,0 +1,343 @@
+/**
+ * GSD Doctor — Provider & Integration Health Checks
+ *
+ * Fast, deterministic checks for external service configuration.
+ * Checks key presence in auth.json and environment variables — no HTTP calls,
+ * no network I/O, always sub-10ms.
+ *
+ * Covers:
+ *   - LLM providers required by the effective model preferences (per phase)
+ *   - Remote questions channel if configured (Slack/Discord/Telegram token)
+ *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { AuthStorage } from "@gsd/pi-coding-agent";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type ProviderCheckStatus = "ok" | "warning" | "error" | "unconfigured";
+
+export interface ProviderCheckResult {
+  /** Provider id from PROVIDER_REGISTRY (e.g. "anthropic", "slack_bot") */
+  name: string;
+  /** Human-readable label */
+  label: string;
+  /** Functional grouping */
+  category: ProviderCategory;
+  status: ProviderCheckStatus;
+  message: string;
+  /** Optional extra detail (e.g. which env var to set) */
+  detail?: string;
+  /** True if this provider is actively required by preferences */
+  required: boolean;
+}
+
+// ── Model → Provider ID mapping ───────────────────────────────────────────────
+
+/**
+ * Infer the auth provider ID from a model string.
+ * Handles plain model IDs ("claude-sonnet-4-6") and prefixed ones ("openrouter/deepseek").
+ */
+function modelToProviderId(model: string): string | null {
+  if (!model) return null;
+
+  // Explicit provider prefix (e.g. "openrouter/deepseek-r1")
+  if (model.includes("/")) {
+    const prefix = model.split("/")[0].toLowerCase();
+    // Map known prefixes to registry IDs
+    const prefixMap: Record<string, string> = {
+      openrouter: "openrouter",
+      groq: "groq",
+      mistral: "mistral",
+      google: "google",
+      anthropic: "anthropic",
+      openai: "openai",
+    };
+    if (prefixMap[prefix]) return prefixMap[prefix];
+  }
+
+  const lower = model.toLowerCase();
+  if (lower.startsWith("claude"))        return "anthropic";
+  if (lower.startsWith("gpt-") || lower.startsWith("o1") || lower.startsWith("o3")) return "openai";
+  if (lower.startsWith("gemini"))        return "google";
+  if (lower.startsWith("llama") || lower.startsWith("mixtral")) return "groq";
+  if (lower.startsWith("grok"))          return "xai";
+  if (lower.startsWith("mistral") || lower.startsWith("codestral")) return "mistral";
+
+  return null;
+}
+
+/** Collect all model strings from effective preferences across all phases. */
+function collectConfiguredModelProviders(): Set<string> {
+  const providers = new Set<string>();
+
+  try {
+    const loaded = loadEffectiveGSDPreferences();
+    const models = loaded?.preferences?.models;
+    if (!models) {
+      // Default: Anthropic
+      providers.add("anthropic");
+      return providers;
+    }
+
+    const modelEntries = typeof models === "object" ? Object.values(models) : [];
+    for (const entry of modelEntries) {
+      const modelId = typeof entry === "string" ? entry
+        : typeof entry === "object" && entry !== null && "model" in entry
+          ? String((entry as { model: unknown }).model)
+          : null;
+      if (modelId) {
+        const pid = modelToProviderId(modelId);
+        if (pid) providers.add(pid);
+      }
+    }
+  } catch {
+    // Preferences not readable — assume Anthropic as default
+    providers.add("anthropic");
+  }
+
+  if (providers.size === 0) providers.add("anthropic");
+  return providers;
+}
+
+// ── Key resolution ─────────────────────────────────────────────────────────────
+
+interface KeyLookup {
+  found: boolean;
+  source: "auth.json" | "env" | "none";
+  backedOff: boolean;
+}
+
+function resolveKey(providerId: string): KeyLookup {
+  const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+
+  // Check auth.json
+  const authPath = getAuthPath();
+  if (existsSync(authPath)) {
+    try {
+      const auth = AuthStorage.create(authPath);
+      const creds = auth.getCredentialsForProvider(providerId);
+      if (creds.length > 0) {
+        // Filter out empty placeholder keys (from skipped onboarding)
+        const hasRealKey = creds.some(c =>
+          c.type === "oauth" || (c.type === "api_key" && (c as { key?: string }).key)
+        );
+        if (hasRealKey) {
+          return {
+            found: true,
+            source: "auth.json",
+            backedOff: auth.areAllCredentialsBackedOff(providerId),
+          };
+        }
+      }
+    } catch {
+      // auth.json malformed — fall through to env check
+    }
+  }
+
+  // Check environment variable
+  if (info?.envVar && process.env[info.envVar]) {
+    return { found: true, source: "env", backedOff: false };
+  }
+
+  return { found: false, source: "none", backedOff: false };
+}
+
+// ── Individual check groups ────────────────────────────────────────────────────
+
+function checkLlmProviders(): ProviderCheckResult[] {
+  const required = collectConfiguredModelProviders();
+  const results: ProviderCheckResult[] = [];
+
+  for (const providerId of required) {
+    const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+    const label = info?.label ?? providerId;
+    const lookup = resolveKey(providerId);
+
+    if (!lookup.found) {
+      const envVar = info?.envVar ?? `${providerId.toUpperCase()}_API_KEY`;
+      results.push({
+        name: providerId,
+        label,
+        category: "llm",
+        status: "error",
+        message: `${label} — no API key found`,
+        detail: info?.hasOAuth
+          ? `Run /gsd keys to authenticate`
+          : `Set ${envVar} or run /gsd keys`,
+        required: true,
+      });
+    } else if (lookup.backedOff) {
+      results.push({
+        name: providerId,
+        label,
+        category: "llm",
+        status: "warning",
+        message: `${label} — all credentials backed off (rate limited)`,
+        detail: `GSD will retry automatically`,
+        required: true,
+      });
+    } else {
+      results.push({
+        name: providerId,
+        label,
+        category: "llm",
+        status: "ok",
+        message: `${label} — key present (${lookup.source})`,
+        required: true,
+      });
+    }
+  }
+
+  return results;
+}
+
+function checkRemoteQuestionsProvider(): ProviderCheckResult | null {
+  try {
+    const loaded = loadEffectiveGSDPreferences();
+    const rq = loaded?.preferences?.remote_questions;
+    if (!rq) return null;
+
+    const channel = rq.channel as string | undefined;
+    if (!channel) return null;
+
+    const providerMap: Record<string, string> = {
+      slack: "slack_bot",
+      discord: "discord_bot",
+      telegram: "telegram_bot",
+    };
+
+    const providerId = providerMap[channel.toLowerCase()];
+    if (!providerId) return null;
+
+    const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+    const label = info?.label ?? channel;
+    const lookup = resolveKey(providerId);
+
+    if (!lookup.found) {
+      return {
+        name: providerId,
+        label,
+        category: "remote",
+        status: "warning",
+        message: `${label} — channel configured but token not found`,
+        detail: info?.envVar ? `Set ${info.envVar} or run /gsd keys` : `Run /gsd keys to configure`,
+        required: true,
+      };
+    }
+
+    return {
+      name: providerId,
+      label,
+      category: "remote",
+      status: "ok",
+      message: `${label} — token present (${lookup.source})`,
+      required: true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function checkOptionalProviders(): ProviderCheckResult[] {
+  const optional = ["brave", "tavily", "jina", "context7"] as const;
+  const results: ProviderCheckResult[] = [];
+
+  for (const providerId of optional) {
+    const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+    if (!info) continue;
+
+    const lookup = resolveKey(providerId);
+    results.push({
+      name: providerId,
+      label: info.label,
+      category: info.category as ProviderCategory,
+      status: lookup.found ? "ok" : "unconfigured",
+      message: lookup.found
+        ? `${info.label} — key present (${lookup.source})`
+        : `${info.label} — not configured (optional)`,
+      detail: !lookup.found && info.envVar ? `Set ${info.envVar} to enable` : undefined,
+      required: false,
+    });
+  }
+
+  return results;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run all provider checks: required LLM keys, remote questions channel, optional tools.
+ * Fast (sub-10ms) — reads auth.json and env vars only, no network I/O.
+ */
+export function runProviderChecks(): ProviderCheckResult[] {
+  const results: ProviderCheckResult[] = [];
+
+  results.push(...checkLlmProviders());
+
+  const remoteCheck = checkRemoteQuestionsProvider();
+  if (remoteCheck) results.push(remoteCheck);
+
+  results.push(...checkOptionalProviders());
+
+  return results;
+}
+
+/**
+ * Format provider check results as a human-readable report string.
+ */
+export function formatProviderReport(results: ProviderCheckResult[]): string {
+  if (results.length === 0) return "No provider checks run.";
+
+  const lines: string[] = [];
+
+  const groups: Record<string, ProviderCheckResult[]> = {};
+  for (const r of results) {
+    (groups[r.category] ??= []).push(r);
+  }
+
+  const categoryLabels: Record<string, string> = {
+    llm: "LLM Providers",
+    remote: "Notifications",
+    search: "Search",
+    tool: "Tools",
+  };
+
+  for (const [cat, items] of Object.entries(groups)) {
+    lines.push(`${categoryLabels[cat] ?? cat}:`);
+    for (const item of items) {
+      const icon = item.status === "ok" ? "✓"
+        : item.status === "warning" ? "⚠"
+        : item.status === "error" ? "✗"
+        : "·";
+      lines.push(`  ${icon} ${item.message}`);
+      if (item.detail && item.status !== "ok") {
+        lines.push(`    ${item.detail}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Summarise check results to a compact widget-friendly string.
+ * Returns null if all required providers are ok.
+ */
+export function summariseProviderIssues(results: ProviderCheckResult[]): string | null {
+  const errors = results.filter(r => r.required && r.status === "error");
+  const warnings = results.filter(r => r.required && r.status === "warning");
+
+  if (errors.length === 0 && warnings.length === 0) return null;
+
+  const parts: string[] = [];
+  if (errors.length > 0) parts.push(`✗ ${errors[0].label} key missing`);
+  if (warnings.length > 0 && errors.length === 0) parts.push(`⚠ ${warnings[0].label} backed off`);
+  if (errors.length + warnings.length > 1) parts.push(`(+${errors.length + warnings.length - 1} more)`);
+
+  return parts.join(" ");
+}

package/src/resources/extensions/gsd/doctor-types.ts

@@ -32,7 +32,20 @@ export type DoctorIssueCode =
   | "gitignore_missing_patterns"
   | "unresolvable_dependency"
   | "failed_migration"
-  | "broken_symlink";
+  | "broken_symlink"
+  // Environment health checks (#1221)
+  | "env_node_version"
+  | "env_dependencies"
+  | "env_env_file"
+  | "env_port_conflict"
+  | "env_disk_space"
+  | "env_docker"
+  | "env_package_manager"
+  | "env_typescript"
+  | "env_python"
+  | "env_cargo"
+  | "env_go"
+  | "env_git_remote";
 
 /**
  * Issue codes that represent expected completion-transition states.

package/src/resources/extensions/gsd/doctor.ts

@@ -10,12 +10,15 @@ import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
+import { checkEnvironmentHealth } from "./doctor-environment.js";
 
 // ── Re-exports ─────────────────────────────────────────────────────────────
 // All public types and functions from extracted modules are re-exported here
 // so that existing imports from "./doctor.js" continue to work unchanged.
 export type { DoctorSeverity, DoctorIssueCode, DoctorIssue, DoctorReport, DoctorSummary } from "./doctor-types.js";
 export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt } from "./doctor-format.js";
+export { runEnvironmentChecks, runFullEnvironmentChecks, formatEnvironmentReport, type EnvironmentCheckResult } from "./doctor-environment.js";
+export { computeProgressScore, computeProgressScoreWithContext, formatProgressLine, formatProgressReport, type ProgressScore, type ProgressLevel } from "./progress-score.js";
 
 /**
  * Characters that are used as delimiters in GSD state management documents
@@ -390,6 +393,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // Runtime health checks (crash locks, completed-units, hook state, activity logs, STATE.md, gitignore)
   await checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix);
 
+  // Environment health checks (#1221: missing tools, port conflicts, stale deps, disk space)
+  await checkEnvironmentHealth(basePath, issues, { includeRemote: !options?.scope });
+
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
     return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };

package/src/resources/extensions/gsd/error-utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract a human-readable message from an unknown caught value.
+ */
+export function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/resources/extensions/gsd/export.ts

@@ -12,6 +12,7 @@ import {
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/mod.js";
+import { getErrorMessage } from "./error-utils.js";
 
 /**
  * Open a file in the user's default browser.
@@ -226,7 +227,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
       }
     } catch (err) {
       ctx.ui.notify(
-        `HTML export failed: ${err instanceof Error ? err.message : String(err)}`,
+        `HTML export failed: ${getErrorMessage(err)}`,
         "error",
       );
     }

package/src/resources/extensions/gsd/git-service.ts

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 import {
   detectWorktreeName,
@@ -32,6 +33,7 @@ import {
   nativeAddPaths,
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -280,7 +282,7 @@ export function runGit(basePath: string, args: string[], options: { allowFailure
     }).trim();
   } catch (error) {
     if (options.allowFailure) return "";
-    const message = error instanceof Error ? error.message : String(error);
+    const message = getErrorMessage(error);
     throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${filterGitSvnNoise(message)}`);
   }
 }
@@ -532,7 +534,7 @@ export class GitServiceImpl {
       execSync(command, { cwd: this.basePath, stdio: "pipe", encoding: "utf-8" });
       return { passed: true, skipped: false, command };
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = getErrorMessage(err);
       return { passed: false, skipped: false, command, error: msg };
     }
   }
@@ -541,6 +543,14 @@ export class GitServiceImpl {
 
 }
 
+// ─── Factory ───────────────────────────────────────────────────────────────
+
+/** Create a GitServiceImpl with the current effective git preferences. */
+export function createGitService(basePath: string): GitServiceImpl {
+  const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+  return new GitServiceImpl(basePath, gitPrefs);
+}
+
 // ─── Commit Type Inference ─────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -23,13 +23,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 
-// ─── Commit Instruction Helper (local copy — avoids circular dep) ───────────
-
-/** Build commit instruction for queue prompts. .gsd/ is managed externally and always gitignored. */
-function buildDocsCommitInstruction(_message: string): string {
-  return "Do not commit planning artifacts — .gsd/ is managed externally.";
-}
-
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -207,7 +200,7 @@ export async function showQueueAdd(
     preamble,
     existingMilestonesContext: existingContext,
     inlinedTemplates: queueInlinedTemplates,
-    commitInstruction: buildDocsCommitInstruction("docs: queue <milestone list>"),
+    commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
   });
 
   pi.sendMessage(

package/src/resources/extensions/gsd/guided-flow.ts

@@ -44,6 +44,7 @@ export {
   showQueue, handleQueueReorder, showQueueAdd,
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 
@@ -158,9 +159,9 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStart = null;
   startAuto(ctx, pi, basePath, false, { step }).catch((err) => {
-    ctx.ui.notify(`Auto-start failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error");
     if (process.env.GSD_DEBUG) console.error('[gsd] auto start error:', err);
-    debugLog("auto-start-failed", { error: err instanceof Error ? err.message : String(err) });
+    debugLog("auto-start-failed", { error: getErrorMessage(err) });
   });
   return true;
 }

package/src/resources/extensions/gsd/health-widget.ts

@@ -0,0 +1,167 @@
+/**
+ * GSD Health Widget — always-on ambient health signal rendered belowEditor.
+ *
+ * Shows a compact 1-2 line summary: progress score, budget, provider key
+ * status, and doctor/environment issue count. Refreshes every 60 seconds.
+ * Quiet when everything is healthy; turns amber/red when issues arise.
+ *
+ * Widget key: "gsd-health", placement: "belowEditor"
+ */
+
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
+import { runEnvironmentChecks } from "./doctor-environment.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
+import { projectRoot } from "./commands.js";
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+interface HealthWidgetData {
+  hasProject: boolean;
+  budgetCeiling: number | undefined;
+  budgetSpent: number;
+  providerIssue: string | null;      // compact summary from summariseProviderIssues()
+  environmentErrorCount: number;
+  environmentWarningCount: number;
+  lastRefreshed: number;
+}
+
+// ── Data loader ────────────────────────────────────────────────────────────────
+
+function loadHealthWidgetData(basePath: string): HealthWidgetData {
+  let hasProject = false;
+  let budgetCeiling: number | undefined;
+  let budgetSpent = 0;
+  let providerIssue: string | null = null;
+  let environmentErrorCount = 0;
+  let environmentWarningCount = 0;
+
+  try {
+    const prefs = loadEffectiveGSDPreferences();
+    budgetCeiling = prefs?.preferences?.budget_ceiling;
+
+    const ledger = loadLedgerFromDisk(basePath);
+    if (ledger) {
+      hasProject = true;
+      const totals = getProjectTotals(ledger.units ?? []);
+      budgetSpent = totals.cost;
+    }
+  } catch { /* non-fatal */ }
+
+  try {
+    const providerResults = runProviderChecks();
+    providerIssue = summariseProviderIssues(providerResults);
+  } catch { /* non-fatal */ }
+
+  try {
+    const envResults = runEnvironmentChecks(basePath);
+    for (const r of envResults) {
+      if (r.status === "error") environmentErrorCount++;
+      else if (r.status === "warning") environmentWarningCount++;
+    }
+  } catch { /* non-fatal */ }
+
+  return {
+    hasProject,
+    budgetCeiling,
+    budgetSpent,
+    providerIssue,
+    environmentErrorCount,
+    environmentWarningCount,
+    lastRefreshed: Date.now(),
+  };
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────────────
+
+function formatCost(n: number): string {
+  return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+}
+
+/**
+ * Build compact health lines for the widget.
+ * Returns a string array suitable for setWidget().
+ */
+export function buildHealthLines(data: HealthWidgetData): string[] {
+  if (!data.hasProject) {
+    return ["  GSD  No project loaded — run /gsd to start"];
+  }
+
+  const parts: string[] = [];
+
+  // System status signal
+  const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
+  if (totalIssues === 0) {
+    parts.push("● System OK");
+  } else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
+    parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+  } else {
+    parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+  }
+
+  // Budget
+  if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
+    const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
+    parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+  } else if (data.budgetSpent > 0) {
+    parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+  }
+
+  // Provider issue (if any)
+  if (data.providerIssue) {
+    parts.push(data.providerIssue);
+  }
+
+  // Environment issues
+  if (data.environmentErrorCount > 0) {
+    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+  } else if (data.environmentWarningCount > 0) {
+    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+  }
+
+  return [`  ${parts.join("  │  ")}`];
+}
+
+// ── Widget init ────────────────────────────────────────────────────────────────
+
+const REFRESH_INTERVAL_MS = 60_000;
+
+/**
+ * Initialize the always-on gsd-health widget (belowEditor).
+ * Call once from the extension entry point after context is available.
+ */
+export function initHealthWidget(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) return;
+
+  const basePath = projectRoot();
+
+  // String-array fallback — used in RPC mode (factory is a no-op there)
+  const initialData = loadHealthWidgetData(basePath);
+  ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
+
+  // Factory-based widget for TUI mode — replaces the string-array above
+  ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
+    let data = initialData;
+    let cachedLines: string[] | undefined;
+
+    const refreshTimer = setInterval(() => {
+      try {
+        data = loadHealthWidgetData(basePath);
+        cachedLines = undefined;
+        _tui.requestRender();
+      } catch { /* non-fatal */ }
+    }, REFRESH_INTERVAL_MS);
+
+    return {
+      render(_width: number): string[] {
+        if (!cachedLines) cachedLines = buildHealthLines(data);
+        return cachedLines;
+      },
+      invalidate(): void { cachedLines = undefined; },
+      dispose(): void {
+        clearInterval(refreshTimer);
+      },
+    };
+  }, { placement: "belowEditor" });
+}