@pellux/goodvibes-agent 1.4.4 → 1.5.1

package/src/core/away-digest.ts

@@ -0,0 +1,161 @@
+/**
+ * Away digest — a friendly "while you were away" summary shown once at launch.
+ *
+ * This module is intentionally pure: buildAwayDigest() takes a plain snapshot
+ * object and returns a structured digest (or null when nothing happened). No
+ * side-effects, no imports from the runtime.
+ */
+
+export interface AwayDigestScheduleItem {
+  readonly name: string;
+  readonly lastRunAt?: number;
+  readonly runCount: number;
+}
+
+export interface AwayDigestTaskItem {
+  readonly title: string;
+  readonly status: string;
+  readonly completedAt?: number;
+}
+
+export interface AwayDigestDeliveryItem {
+  readonly label: string;
+  readonly at?: number;
+}
+
+export interface AwayDigestInput {
+  /** Epoch ms when the user last used the app. null = first run — digest is suppressed. */
+  readonly lastSeenAt: number | null;
+  /** Schedules that ran since lastSeenAt. */
+  readonly schedules: readonly AwayDigestScheduleItem[];
+  /** Tasks whose status changed since lastSeenAt. */
+  readonly tasks: readonly AwayDigestTaskItem[];
+  /** Number of approvals currently waiting. */
+  readonly pendingApprovals: number;
+  /** Optional channel deliveries since lastSeenAt. */
+  readonly deliveries?: readonly AwayDigestDeliveryItem[];
+}
+
+export interface AwayDigest {
+  readonly headline: string;
+  readonly lines: readonly string[];
+}
+
+/**
+ * Maximum number of lines in the digest body (the headline is extra).
+ * Keeps the digest compact enough to scan without scrolling.
+ */
+const MAX_LINES = 5;
+
+/**
+ * Format a relative time from `from` to `at`, e.g. "9:00" or "yesterday 9:00".
+ * Keeps language simple and avoids raw timestamps in user-facing copy.
+ */
+export function formatDigestTime(at: number, from: number = Date.now()): string {
+  const d = new Date(at);
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mm = String(d.getMinutes()).padStart(2, '0');
+  const time = `${hh}:${mm}`;
+
+  const fromDate = new Date(from);
+  const sameDay =
+    d.getFullYear() === fromDate.getFullYear() &&
+    d.getMonth() === fromDate.getMonth() &&
+    d.getDate() === fromDate.getDate();
+
+  if (sameDay) return time;
+
+  // Check if it was yesterday
+  const yesterday = new Date(from);
+  yesterday.setDate(yesterday.getDate() - 1);
+  const wasYesterday =
+    d.getFullYear() === yesterday.getFullYear() &&
+    d.getMonth() === yesterday.getMonth() &&
+    d.getDate() === yesterday.getDate();
+
+  if (wasYesterday) return `yesterday ${time}`;
+  return `${d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })} ${time}`;
+}
+
+/**
+ * Format a relative duration label for an upcoming item, e.g. "in 2h" or "in 30m".
+ */
+export function formatRelativeTime(targetMs: number, nowMs: number = Date.now()): string {
+  const diffMs = targetMs - nowMs;
+  if (diffMs <= 0) return 'soon';
+  const diffMin = Math.round(diffMs / 60_000);
+  if (diffMin < 60) return `in ${diffMin}m`;
+  const diffHours = Math.round(diffMs / 3_600_000);
+  if (diffHours < 24) return `in ${diffHours}h`;
+  const diffDays = Math.round(diffMs / 86_400_000);
+  return `in ${diffDays}d`;
+}
+
+/**
+ * Build a friendly digest from a plain snapshot. Returns null when there is
+ * nothing to report or when lastSeenAt is null (first run).
+ */
+export function buildAwayDigest(input: AwayDigestInput): AwayDigest | null {
+  if (input.lastSeenAt === null) return null;
+
+  const lines: string[] = [];
+  const now = Date.now();
+
+  // ── Pending approvals (highest urgency first) ──────────────────────────────
+  if (input.pendingApprovals > 0) {
+    const word = input.pendingApprovals === 1 ? 'approval is waiting' : 'approvals are waiting';
+    lines.push(`${input.pendingApprovals} ${word} for you`);
+  }
+
+  // ── Tasks that completed/changed ──────────────────────────────────────────
+  const doneTasks = input.tasks.filter(
+    (t) => t.status === 'done' || t.status === 'completed' || t.status === 'finished',
+  );
+  const failedTasks = input.tasks.filter(
+    (t) => t.status === 'failed' || t.status === 'error',
+  );
+
+  if (doneTasks.length === 1) {
+    const t = doneTasks[0]!;
+    const when = t.completedAt ? ` (${formatDigestTime(t.completedAt, now)})` : '';
+    lines.push(`Research task finished: ${t.title}${when}`);
+  } else if (doneTasks.length > 1) {
+    lines.push(`${doneTasks.length} tasks finished since you were away`);
+  }
+
+  if (failedTasks.length === 1) {
+    lines.push(`A task needs attention: ${failedTasks[0]!.title}`);
+  } else if (failedTasks.length > 1) {
+    lines.push(`${failedTasks.length} tasks need attention since you were away`);
+  }
+
+  // ── Schedule runs ─────────────────────────────────────────────────────────
+  if (input.schedules.length === 1) {
+    const s = input.schedules[0]!;
+    const last = s.lastRunAt ? ` (last: ${s.name}, ${formatDigestTime(s.lastRunAt, now)})` : '';
+    lines.push(`1 reminder fired${last}`);
+  } else if (input.schedules.length > 1) {
+    // Find the most-recently fired for the "last:" note
+    const sorted = [...input.schedules].sort((a, b) => (b.lastRunAt ?? 0) - (a.lastRunAt ?? 0));
+    const mostRecent = sorted[0]!;
+    const last = mostRecent.lastRunAt
+      ? `, last: ${mostRecent.name}, ${formatDigestTime(mostRecent.lastRunAt, now)}`
+      : '';
+    lines.push(`${input.schedules.length} reminders fired${last}`);
+  }
+
+  // ── Channel deliveries ────────────────────────────────────────────────────
+  const deliveries = input.deliveries ?? [];
+  if (deliveries.length === 1) {
+    lines.push(`1 message delivered: ${deliveries[0]!.label}`);
+  } else if (deliveries.length > 1) {
+    lines.push(`${deliveries.length} messages delivered`);
+  }
+
+  if (lines.length === 0) return null;
+
+  return {
+    headline: 'While you were away',
+    lines: lines.slice(0, MAX_LINES),
+  };
+}

package/src/core/conversation-rendering.ts

@@ -1,6 +1,7 @@
 import { UIFactory } from '../renderer/ui-factory.ts';
 import { renderMarkdownTracked } from '../renderer/markdown.ts';
 import { renderToolCallBlock } from '../renderer/tool-call.ts';
+import { friendlyToolLabel } from '../renderer/tool-labels.ts';
 import { renderThinkingBlock } from '../renderer/thinking.ts';
 import { renderSystemMessage } from '../renderer/system-message.ts';
 import { createEmptyLine, type Line, type Cell } from '../types/grid.ts';
@@ -184,7 +185,9 @@ export function renderConversationSystemMessage(
   const sysStartLine = context.history.getLineCount();
   const sysLines = renderSystemMessage(message.content, width);
   context.history.addLines(sysLines);
-  if (/error/i.test(message.content)) {
+  // Match only messages that begin with a severity tag or bare "Error:" / "Error!" prefix.
+  // Bare /error/i over-matches false positives like "No errors found", "terror", etc.
+  if (/^\s*(\[(error|critical)\]|error[:!])/i.test(message.content)) {
     context.errorLineRegistry.push(sysStartLine);
   }
 }
@@ -224,14 +227,15 @@ export function renderConversationToolMessage(
     detailFg: '244',
   }, [
     ...(message.toolName
-      ? [{ text: ` ${message.toolName} `, fg: '#e2e8f0' as const }]
+      ? [{ text: ` ${friendlyToolLabel(message.toolName)} `, fg: '#e2e8f0' as const }]
       : [{ text: ` ${summarizeCallId(message.callId || 'standalone')} `, fg: '244' as const, dim: true }]),
     { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${lineCount} line${lineCount === 1 ? '' : 's'} `, fg: '244', dim: true },
   ]));
 
   if (isCollapsed) {
     const collapseSuffixReserve = 30;
-    const preview = contentLines[0].slice(0, width - LAYOUT.LEFT_MARGIN - LAYOUT.RIGHT_MARGIN - collapseSuffixReserve);
+    const previewWidth = Math.max(0, width - LAYOUT.LEFT_MARGIN - LAYOUT.RIGHT_MARGIN - collapseSuffixReserve);
+    const preview = contentLines[0].slice(0, previewWidth);
     const hiddenCount = lineCount - 1;
     const collapsedText = hiddenCount > 0
       ? `${preview}...  [${GLYPHS.navigation.collapsed} ${hiddenCount} hidden]`

package/src/core/conversation.ts

@@ -60,8 +60,7 @@ export class ConversationManager extends SdkConversationManager {
   private lastRenderedWidth = 0;
   /** When true the buffer needs to be rebuilt before the next display. */
   private dirty = true;
-  /** Index of the first message not yet appended to the buffer. */
-  private appendedUpTo = 0;
+
   /** Optional config manager for display settings. */
   private _configManager: ConfigManager | null = null;
   /** Collapse state: stable key (msg_N) -> collapsed (true = collapsed). */
@@ -70,7 +69,7 @@ export class ConversationManager extends SdkConversationManager {
   protected blockRegistry: BlockMeta[] = [];
   /** Message index -> first rendered line index in the history buffer. */
   private messageLineRegistry: number[] = [];
-  /** Registry of rendered line indices for system messages matching /error/i. */
+  /** Registry of rendered line indices for system messages matching a leading [error]/[critical] tag or error:/error! prefix. */
   private errorLineRegistry: number[] = [];
   /** Streaming block start line in history buffer (for incremental streaming update). */
   private streamingStartLine = -1;
@@ -184,11 +183,25 @@ export class ConversationManager extends SdkConversationManager {
    */
   public override updateStreamingBlock(content: string): void {
     super.updateStreamingBlock(content);
-    // Incrementally update the history buffer instead of full rebuild
+    // Incrementally update the history buffer instead of full rebuild.
+    // Use the same width computation as the finalized path in renderConversationAssistantMessage
+    // so that streaming content does not reflow when it finalizes.
+    // NOTE: The 'all' line-number mode requires a two-pass measurement (total line count first,
+    // then render with gutter) which is impractical during streaming. For 'all' mode we apply
+    // a fixed pessimistic gutter (numWidth=3, gutterW=6) so the streaming width closely
+    // matches the finalized width; a single-line reflow may still occur if the final message
+    // exceeds 999 lines (extremely unlikely in practice). This is documented here as an
+    // intentional approximation, not a bug.
     if (this.streamingStartLine >= 0) {
       const width = this._getWidth();
+      const lineNumberMode = this._configManager?.get('display.lineNumbers') ?? 'off';
+      const showAllLineNumbers = lineNumberMode === 'all';
+      // Match the gutter computation from renderConversationAssistantMessage:
+      // use numWidth=3 (minimum) during streaming since total line count is unknown.
+      const gutterW = showAllLineNumbers ? 3 + 3 : 0; // numWidth=3, separator=' | ' = +3
+      const renderWidth = showAllLineNumbers ? width - gutterW : width;
       this.history.truncateToLine(this.streamingStartLine);
-      const rendered = renderMarkdown(content, width);
+      const rendered = renderMarkdown(content, renderWidth);
       this.history.addLines(rendered);
     }
   }
@@ -214,7 +227,6 @@ export class ConversationManager extends SdkConversationManager {
   public override resetAll(): void {
     super.resetAll();
     this.history.clear();
-    this.appendedUpTo = 0;
     this.lastRenderedWidth = 0;
     this.dirty = true;
     this.collapseState.clear();
@@ -235,7 +247,6 @@ export class ConversationManager extends SdkConversationManager {
   public override replaceMessagesForLLM(newMessages: ProviderMessage[]): void {
     super.replaceMessagesForLLM(newMessages);
     this.history.clear();
-    this.appendedUpTo = 0;
     this.lastRenderedWidth = 0;
     this.dirty = true;
   }
@@ -273,7 +284,6 @@ export class ConversationManager extends SdkConversationManager {
   }): void {
     super.fromJSON(data);
     this.history.clear();
-    this.appendedUpTo = 0;
     this.lastRenderedWidth = 0;
     this.dirty = true;
   }
@@ -288,12 +298,10 @@ export class ConversationManager extends SdkConversationManager {
   }
 
   /**
-   * rebuildHistory - Full rebuild. Called when width changes or on first render.
-   * For incremental appends use flushHistory().
+   * rebuildHistory - Full rebuild. Called when dirty flag is set or terminal width changes.
    */
   public rebuildHistory(): void {
     this.history.clear();
-    this.appendedUpTo = 0;
     this.blockRegistry = [];
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
@@ -322,12 +330,12 @@ export class ConversationManager extends SdkConversationManager {
     }
 
     this.appendMessages(visibleSnapshot, width);
-    this.appendedUpTo = snapshot.length;
   }
 
   /**
-   * flushHistory - Incremental update. Appends only newly added messages.
-   * Falls back to a full rebuild when the terminal width has changed.
+   * flushHistory - Rebuilds the full buffer when dirty or when the terminal width has changed.
+   * Clears the history buffer and re-renders all messages from scratch on each call.
+   * No-ops when the buffer is clean and width is unchanged.
    */
   public flushHistory(): void {
     const currentWidth = this._getWidth();
@@ -541,7 +549,6 @@ export class ConversationManager extends SdkConversationManager {
     // Advance _displayFromMessageIndex to exclude all current messages from display.
     // rebuildHistory() will only render messages added AFTER this point.
     this._displayFromMessageIndex = this.getMessageSnapshot().length;
-    this.appendedUpTo = this._displayFromMessageIndex;
     this.dirty = false;
     // Do NOT re-render here — display stays blank until the next message is added.
     // The lastRenderedWidth is kept so subsequent appends use the correct width.

package/src/core/hardware-profile.ts

@@ -0,0 +1,362 @@
+import { readFileSync } from 'node:fs';
+import { cpus, freemem, totalmem } from 'node:os';
+import { spawn } from 'node:child_process';
+
+/**
+ * Raw hardware snapshot for this process.
+ * All fields that cannot be determined safely are null.
+ * This module never throws — callers always receive a result.
+ */
+export interface HardwareProfile {
+  /** Total physical RAM in bytes, or null when unreadable. */
+  readonly totalRamBytes: number | null;
+  /** Available/free RAM in bytes at probe time, or null when unreadable. */
+  readonly availableRamBytes: number | null;
+  /** Discovered GPUs with VRAM sizes (empty when none detected). */
+  readonly gpus: readonly GpuInfo[];
+  /** Logical CPU core count (hyperthreaded), or null when unreadable. */
+  readonly cpuCores: number | null;
+}
+
+export interface GpuInfo {
+  /** GPU product name (e.g. "NVIDIA GeForce RTX 3090"). */
+  readonly name: string;
+  /** Total VRAM in bytes, or null when not reported. */
+  readonly vramBytes: number | null;
+}
+
+/**
+ * Plain-language verdict for whether a model fits on this machine.
+ *
+ * Heuristic (documented):
+ *   Quantized model size in bytes is estimated as: params * bytesPerWeight
+ *   Default quant assumed Q4 => bytesPerWeight = 0.6 bytes/param
+ *   (1-bit quants like Q1 => 0.125, Q2 => 0.25, Q4 => ~0.55, Q8 => 1.0, fp16 => 2.0)
+ *
+ *   fits-gpu  : modelSizeBytes <= 0.80 * max(gpus[].vramBytes)  (80% headroom for activations)
+ *   fits-ram  : modelSizeBytes <= 0.60 * availableRamBytes       (60% of free RAM to leave OS headroom)
+ *   tight     : modelSizeBytes <= totalRamBytes                  (fits but will starve other processes)
+ *   too-big   : modelSizeBytes > totalRamBytes
+ *   unknown   : any required profile field is null / no data
+ */
+export type FitVerdict = 'fits-gpu' | 'fits-ram' | 'tight' | 'too-big' | 'unknown';
+
+/**
+ * Bytes-per-weight constants for common quantization levels.
+ * Use these when converting a parameter count to an estimated model size.
+ */
+export const BYTES_PER_WEIGHT: Readonly<Record<string, number>> = {
+  q2: 0.25,
+  q4: 0.55,  // Q4_K_M midpoint
+  q5: 0.69,
+  q8: 1.0,
+  f16: 2.0,
+  f32: 4.0,
+};
+
+/** Default quantization assumed when none is specified (Q4 GGUF). */
+export const DEFAULT_BYTES_PER_WEIGHT = BYTES_PER_WEIGHT.q4;
+
+/**
+ * Estimate model size in bytes from a parameter count.
+ * @param params  Parameter count (e.g. 7_000_000_000 for a 7B model).
+ * @param bytesPerWeight  Bytes per weight for the target quant. Defaults to Q4 (0.55).
+ */
+export function estimateModelBytes(params: number, bytesPerWeight = DEFAULT_BYTES_PER_WEIGHT): number {
+  return Math.round(params * bytesPerWeight);
+}
+
+/**
+ * Assess whether a model fits on the given hardware profile.
+ * @param modelSizeBytes  Estimated model size in bytes (use estimateModelBytes if you have param count).
+ * @param profile         Hardware profile from readHardwareProfile().
+ */
+export function fitAssessment(modelSizeBytes: number, profile: HardwareProfile): FitVerdict {
+  // Try GPU first — fastest/best path
+  const maxVram = maxVramBytes(profile.gpus);
+  if (maxVram !== null && modelSizeBytes <= Math.floor(maxVram * 0.80)) {
+    return 'fits-gpu';
+  }
+
+  // RAM fallback
+  if (profile.availableRamBytes !== null) {
+    if (modelSizeBytes <= Math.floor(profile.availableRamBytes * 0.60)) {
+      return 'fits-ram';
+    }
+  }
+
+  if (profile.totalRamBytes !== null) {
+    return modelSizeBytes <= profile.totalRamBytes ? 'tight' : 'too-big';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Representative parameter count for a 7B starter model, used when estimating
+ * hardware fit across multiple call sites.
+ */
+export const REPRESENTATIVE_7B_PARAMS = 7_000_000_000;
+
+/**
+ * Plain-language description of a fit verdict for display in the TUI renderer and cookbook.
+ * When `sizeDescriptor` is provided (e.g. '70B', '3B'), it is used in place of '7B' in the
+ * label so the hint reflects the actual model size. When omitted, falls back to '7B'
+ * (the representative constant used for the cookbook and unknown-size models).
+ * Returns an empty string when verdict is 'unknown' (no annotation shown).
+ */
+export function fitVerdictLabel(verdict: FitVerdict, sizeDescriptor?: string): string {
+  const size = sizeDescriptor ?? '7B';
+  switch (verdict) {
+    case 'fits-gpu': return `a ${size} model fits in GPU memory here`;
+    case 'fits-ram': return `a ${size} model runs on CPU RAM here`;
+    case 'tight':    return `a ${size} model is tight here — close other apps`;
+    case 'too-big':  return `a ${size} model needs more memory than this machine has`;
+    case 'unknown':  return '';
+  }
+}
+
+/**
+ * Parse a parameter count from a model identifier or display name.
+ * Matches patterns like '70b', '3b', '1.5b', '7B' (case-insensitive, word-boundary-like).
+ * Returns the count as a number (e.g. 70e9 for '70b') or null when no size token is found.
+ *
+ * Examples:
+ *   'llama-3.1-70b'  → 70_000_000_000
+ *   'qwen2.5-3b'     → 3_000_000_000
+ *   '7b'             → 7_000_000_000
+ *   'gpt-4o'         → null
+ */
+export function paramCountFromModel(model: { id: string; displayName?: string }): number | null {
+  const candidates = [model.id, model.displayName ?? ''];
+  const re = /(\d+(?:\.\d+)?)\s*b\b/i;
+  for (const s of candidates) {
+    const m = re.exec(s);
+    if (m) {
+      const val = parseFloat(m[1]!);
+      if (Number.isFinite(val) && val > 0) {
+        return Math.round(val * 1e9);
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Process-level cache — the probe runs at most once per process.
+// ---------------------------------------------------------------------------
+let cachedProfile: HardwareProfile | null = null;
+
+/**
+ * Return a hardware profile immediately without spawning any child process.
+ * RAM and CPU are read from OS APIs (cheap, synchronous, non-blocking).
+ * GPU information is populated only if a prior `startHardwareProbe()` call
+ * has already completed and written to the module cache; otherwise `gpus` is
+ * an empty array.
+ *
+ * This is the correct reader for render-path callers (TUI renderer, cookbook).
+ * Never throws; degraded fields are null.
+ */
+export function readHardwareProfileSync(): HardwareProfile {
+  if (cachedProfile !== null) return cachedProfile;
+  // Build an immediate profile with RAM+CPU only (no GPU spawn).
+  // Populate the cache so repeated sync calls return the same object, and so
+  // that subsequent renders are instant. startHardwareProbe() will upgrade
+  // this entry with GPU data when the async probe completes.
+  const { totalRamBytes, availableRamBytes } = probeRam();
+  const cpuCores = probeCpuCores();
+  cachedProfile = { totalRamBytes, availableRamBytes, gpus: [], cpuCores };
+  return cachedProfile;
+}
+
+/**
+ * Probe hardware and return a snapshot.
+ * Safe to call many times — the OS probe runs exactly once per process.
+ * Never throws; degraded fields are null.
+ *
+ * @deprecated Delegates to `readHardwareProfileSync()`. Prefer calling
+ *   `readHardwareProfileSync()` directly on the render path.
+ *   GPU data is populated asynchronously — call `startHardwareProbe()` at
+ *   application startup so that subsequent `readHardwareProfileSync()` calls
+ *   include GPU information; this alias does not trigger the probe itself.
+ */
+export function readHardwareProfile(): HardwareProfile {
+  return readHardwareProfileSync();
+}
+
+/**
+ * Start a one-time async nvidia-smi probe in the background.
+ * When the probe completes it writes a full profile (RAM + CPU + GPUs) into
+ * the module cache, so subsequent `readHardwareProfileSync()` calls will
+ * include GPU data.
+ *
+ * Call once at application startup — off the render frame.
+ * Never throws; GPU errors are silently ignored.
+ */
+export function startHardwareProbe(): void {
+  try {
+    const child = spawn(
+      'nvidia-smi',
+      ['--query-gpu=name,memory.total', '--format=csv,noheader,nounits'],
+      { timeout: 1500 },
+    );
+    const chunks: Buffer[] = [];
+    child.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk));
+    child.on('close', (code: number | null) => {
+      try {
+        const { totalRamBytes, availableRamBytes } = probeRam();
+        const cpuCores = probeCpuCores();
+        const gpus = code === 0 && chunks.length > 0
+          ? parseNvidiaSmiOutput(Buffer.concat(chunks).toString('utf-8'))
+          : [];
+        // Populate if cache is cold, or upgrade an existing sync-only entry
+        // (gpus: []) with the GPU data returned by the async probe.
+        cachedProfile = _mergeProbeIntoCache(cachedProfile, { totalRamBytes, availableRamBytes, gpus, cpuCores });
+      } catch {
+        // GPU probe failure is non-fatal — leave cache unpopulated.
+      }
+    });
+    child.on('error', () => {
+      // nvidia-smi not found or not executable — leave cache unpopulated.
+    });
+  } catch {
+    // spawn itself failed — leave cache unpopulated.
+  }
+}
+
+/** Reset the process-level cache (test use only). */
+export function _resetHardwareProfileCache(): void {
+  cachedProfile = null;
+}
+
+/**
+ * Inject a hardware profile into the process-level cache (test use only).
+ * Useful when tests need a deterministic hardware profile to exercise
+ * verdict/label paths without depending on the real machine's hardware.
+ */
+export function _setHardwareProfileForTest(profile: HardwareProfile): void {
+  cachedProfile = profile;
+}
+
+/**
+ * Pure helper: decide how to merge a freshly-probed profile into the current
+ * module cache. Extracted so the merge logic can be unit-tested independently
+ * of the child-process lifecycle.
+ *
+ * Rules:
+ *   - current === null  →  use fresh as-is (cold-cache populate)
+ *   - current.gpus.length === 0 && fresh.gpus.length > 0
+ *       →  { ...current, gpus: fresh.gpus }  (upgrade only the empty gpus field;
+ *          all other fields — RAM, CPU — are kept from the existing entry)
+ *   - otherwise  →  return current unchanged (never overwrite non-empty gpus)
+ */
+export function _mergeProbeIntoCache(
+  current: HardwareProfile | null,
+  fresh: HardwareProfile,
+): HardwareProfile {
+  if (current === null) return fresh;
+  if (current.gpus.length === 0 && fresh.gpus.length > 0) {
+    return { ...current, gpus: fresh.gpus };
+  }
+  return current;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function probeRam(): { totalRamBytes: number | null; availableRamBytes: number | null } {
+  // Linux: try /proc/meminfo first (accurate, no system call overhead)
+  try {
+    const raw = readFileSync('/proc/meminfo', 'utf-8');
+    const parsed = parseProcMeminfo(raw);
+    if (parsed.totalRamBytes !== null) return parsed;
+  } catch {
+    // not Linux or permission denied — fall through to node:os
+  }
+
+  // Fallback: node:os (works on macOS/Windows too)
+  try {
+    const total = totalmem();
+    const avail = freemem();
+    return {
+      totalRamBytes: Number.isFinite(total) && total > 0 ? total : null,
+      availableRamBytes: Number.isFinite(avail) && avail > 0 ? avail : null,
+    };
+  } catch {
+    return { totalRamBytes: null, availableRamBytes: null };
+  }
+}
+
+/**
+ * Parse /proc/meminfo text and extract MemTotal and MemAvailable.
+ * Lines look like: "MemTotal:       16384000 kB"
+ */
+export function parseProcMeminfo(raw: string): { totalRamBytes: number | null; availableRamBytes: number | null } {
+  let totalKb: number | null = null;
+  let availableKb: number | null = null;
+
+  for (const line of raw.split('\n')) {
+    if (totalKb === null && line.startsWith('MemTotal:')) {
+      totalKb = parseKbLine(line);
+    } else if (availableKb === null && line.startsWith('MemAvailable:')) {
+      availableKb = parseKbLine(line);
+    }
+    if (totalKb !== null && availableKb !== null) break;
+  }
+
+  return {
+    totalRamBytes: totalKb !== null ? totalKb * 1024 : null,
+    availableRamBytes: availableKb !== null ? availableKb * 1024 : null,
+  };
+}
+
+function parseKbLine(line: string): number | null {
+  // Format: "MemTotal:       16384000 kB"
+  const parts = line.split(/\s+/);
+  const kb = parts[1] !== undefined ? Number(parts[1]) : NaN;
+  return Number.isFinite(kb) && kb > 0 ? kb : null;
+}
+
+/**
+ * Parse nvidia-smi CSV output lines into GpuInfo entries.
+ * Each line: "GPU Name, vramMiB"
+ */
+export function parseNvidiaSmiOutput(raw: string): readonly GpuInfo[] {
+  const gpus: GpuInfo[] = [];
+  for (const line of raw.trim().split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Last comma-separated field is the memory in MiB
+    const lastComma = trimmed.lastIndexOf(',');
+    if (lastComma < 0) {
+      gpus.push({ name: trimmed, vramBytes: null });
+      continue;
+    }
+    const name = trimmed.slice(0, lastComma).trim();
+    const mibStr = trimmed.slice(lastComma + 1).trim();
+    const mib = Number(mibStr);
+    const vramBytes = Number.isFinite(mib) && mib > 0 ? Math.round(mib * 1024 * 1024) : null;
+    gpus.push({ name, vramBytes });
+  }
+  return gpus;
+}
+
+function probeCpuCores(): number | null {
+  try {
+    const count = cpus().length;
+    return count > 0 ? count : null;
+  } catch {
+    return null;
+  }
+}
+
+function maxVramBytes(gpus: readonly GpuInfo[]): number | null {
+  let max: number | null = null;
+  for (const gpu of gpus) {
+    if (gpu.vramBytes !== null && (max === null || gpu.vramBytes > max)) {
+      max = gpu.vramBytes;
+    }
+  }
+  return max;
+}