@polderlabs/bizar 5.0.0 → 5.0.2

package/bizar-dash/src/server/routes/_shared.mjs

@@ -131,8 +131,8 @@ export const DEFAULT_SETTINGS = {
   },
   systemLlm: {
     enabled: true,
-    provider: 'opencode',
-    model: 'opencode/deepseek-v4-flash-free',
+    provider: 'minimax',
+    model: 'minimax/MiniMax-M2.7',
   },
   // v4.5.0 — MiniMax Token Plan integration. `apiKey` is the
   // user's Subscription Key from

package/bizar-dash/src/server/routes/doctor.mjs

@@ -0,0 +1,71 @@
+/**
+ * src/server/routes/doctor.mjs
+ *
+ * v6.0.0 — Doctor REST surface for the dashboard Doctor page.
+ *
+ *   GET  /api/doctor         — full system snapshot (collectDiagnostics)
+ *   GET  /api/doctor/health  — rolled-up status + per-group issues
+ *   POST /api/doctor/check   — run a single named check
+ *
+ * Mounted at /doctor by api.mjs. Existing /api/diagnostics/* routes
+ * (legacy v3) are untouched and keep using `diagnosticsStore.snapshot()`
+ * / `.health()`.
+ */
+import { Router } from 'express';
+import { wrap } from './_shared.mjs';
+import { collectDiagnostics, runCheck, health } from '../diagnostics-store.mjs';
+import { info } from '../logger.mjs';
+
+/**
+ * @returns {import('express').Router}
+ */
+export function createDoctorRouter() {
+  const router = Router();
+
+  // GET /api/doctor — full snapshot. Bounded by the underlying
+  // `collectDiagnostics()` (recentErrors is capped at 50, checks at
+  // ~12 entries, agent file list at directory size).
+  router.get('/', wrap(async (_req, res) => {
+    const snap = await collectDiagnostics();
+    info('doctor.snapshot', { status: snap.health.status, issues: snap.health.issues.length });
+    res.json(snap);
+  }));
+
+  // GET /api/doctor/health — rolled-up health. Cheap; the Doctor
+  // page polls this on every auto-refresh tick (30s) and only
+  // fetches the full snapshot when the user clicks "Refresh".
+  router.get('/health', wrap(async (_req, res) => {
+    const result = await health();
+    res.json(result);
+  }));
+
+  // POST /api/doctor/check — run a single named check.
+  //
+  // Body: `{ checkName: string }`.
+  //
+  // Returns the single check on success, or `{ status: 'fail',
+  // message: 'unknown check', error: '...' }` with HTTP 404 when
+  // the name doesn't match any registered check. The dashboard
+  // surfaces the message inline so the operator can fix the
+  // underlying issue without leaving the Doctor page.
+  router.post('/check', wrap(async (req, res) => {
+    const checkName = String(req.body?.checkName || '').trim();
+    if (!checkName) {
+      res.status(400).json({
+        status: 'fail',
+        name: '',
+        message: 'checkName required',
+        error: 'POST body must include { checkName: string }',
+      });
+      return;
+    }
+    const result = await runCheck(checkName);
+    if (result.status === 'fail' && result.message === 'unknown check') {
+      res.status(404).json(result);
+      return;
+    }
+    res.json(result);
+  }));
+
+  return router;
+}

package/bizar-dash/src/server/routes/env-vars.mjs

@@ -1,7 +1,7 @@
 /**
  * src/server/routes/env-vars.mjs
  *
- * v1 — Bizar env vars stored in ~/.config/bizar/env.json (mode 0600).
+ * v2 — Bizar env vars stored in ~/.config/bizar/env.json (mode 0600).
  *
  * Endpoints:
  *   GET    /api/env-vars           — list all (masked values)
@@ -9,6 +9,9 @@
  *   PUT    /api/env-vars/:name     — update {value}
  *   DELETE /api/env-vars/:name     — remove + delete from process.env
  *   POST   /api/env-vars/:name/test — {referenced, inProcessEnv}
+ *   POST   /api/env-vars/bulk-import — {ok, imported, skipped, errors[]}
+ *   GET    /api/env-vars/export    — text/plain .env format
+ *   GET    /api/env-vars/grouped   — { "BIZAR_*": [...], "PROVIDER_*": [...] }
  *
  * Name must match /^BIZAR_[A-Z0-9_]+$/.
  * On startup, loadEnvJson() sets process.env[name] = value for every entry.
@@ -161,5 +164,68 @@ export function createEnvVarsRouter() {
     res.json({ referenced: inProcessEnv, inProcessEnv });
   }));
 
+  // POST /api/env-vars/bulk-import — parse KEY=value lines
+  router.post('/env-vars/bulk-import', wrap(async (req, res) => {
+    const { envContent } = req.body || {};
+    if (typeof envContent !== 'string') {
+      res.status(400).json({ error: 'envContent_required', message: 'envContent string is required' });
+      return;
+    }
+    const lines = envContent.split('\n');
+    const store = readStore();
+    let imported = 0;
+    let skipped = 0;
+    const errors = [];
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) { skipped++; continue; }
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx < 1) { errors.push(`Invalid line (no '='): ${trimmed.slice(0, 40)}`); skipped++; continue; }
+      const rawName = trimmed.slice(0, eqIdx).trim();
+      const value = trimmed.slice(eqIdx + 1);
+      if (!NAME_RE.test(rawName)) { errors.push(`Invalid name: ${rawName}`); skipped++; continue; }
+      const name = rawName.toUpperCase();
+      if (store[name]) { errors.push(`Already exists (skipping): ${name}`); skipped++; continue; }
+      const entry = { value, createdAt: new Date().toISOString(), source: 'bulk-import' };
+      store[name] = entry;
+      process.env[name] = value;
+      imported++;
+    }
+
+    if (imported > 0) writeStore(store);
+    res.json({ ok: true, imported, skipped, errors });
+  }));
+
+  // GET /api/env-vars/export — return .env format
+  router.get('/env-vars/export', wrap(async (_req, res) => {
+    const store = readStore();
+    const lines = [];
+    for (const [name, entry] of Object.entries(store)) {
+      lines.push(`${name}=${entry.value}`);
+    }
+    res.setHeader('Content-Type', 'text/plain');
+    res.setHeader('Content-Disposition', 'attachment; filename=".env"');
+    res.send(lines.join('\n'));
+  }));
+
+  // GET /api/env-vars/grouped — return vars grouped by prefix
+  router.get('/env-vars/grouped', wrap(async (_req, res) => {
+    const store = readStore();
+    const groups = {};
+    for (const [name, entry] of Object.entries(store)) {
+      // Extract second-level prefix: BIZAR_EXT_A -> EXT_, BIZAR_PROVIDER_KEY -> PROVIDER_
+      const m = name.match(/^BIZAR_([A-Z0-9]+_)/);
+      const prefix = m ? m[1] : name;
+      (groups[prefix] ??= []).push({
+        name,
+        value: mask(entry.value),
+        createdAt: entry.createdAt,
+        source: entry.source,
+      });
+    }
+    res.json(groups);
+  }));
+
   return router;
 }

package/bizar-dash/src/server/routes/memory.mjs

@@ -48,6 +48,9 @@ function redactLightRAGConfig(config) {
 }
 
 export function createMemoryRouter({ projectRoot }) {
+  // Auto-create the default vault and git-init if needed — idempotent.
+  memoryStore.ensureVaultExists();
+
   const router = Router();
 
   // GET /memory/status

package/bizar-dash/src/server/routes/opencode-session-detail.mjs

@@ -31,24 +31,34 @@
  * `error` event and end the stream rather than risk file-descriptor
  * exhaustion when many tabs are open.
  *
- * The directory resolver walks `listOpencodeSessions` first (so a
- * session started from any worktree gets its own directory), then
- * falls back to `info.worktree` (the plugin's cwd). If neither is
- * known we 503.
+ * The directory resolver lives in `serve-info.mjs` as
+ * `resolveSessionDirectory(sessionId, serveInfo)` and is shared with
+ * `routes/opencode-sessions.mjs`. It probes the recorded worktree
+ * first (cheap), then falls back to listing every session and
+ * matching on id. If neither yields a directory we 503 with
+ * `directory_unknown`.
+ *
+ * v5.0.0 — bug #4 fix: structured error envelopes with `cause`,
+ * `status`, and `suggestion`; structured `logger.error` on every
+ * upstream failure for diagnostics.
  */
 
 import { Router } from 'express';
 import {
   readServeInfo,
   listOpencodeMessages,
-  listOpencodeSessions,
+  resolveSessionDirectory,
   sendOpencodePrompt,
   unwrapOpencodeSseEvent,
   buildAuthHeader,
   extractContentFromOpencodeMessage,
 } from '../serve-info.mjs';
+import { child as loggerChild } from '../logger.mjs';
 import { wrap } from './_shared.mjs';
 
+/** Structured logger scoped to this route — emits `{module:'opencode-session-detail', ...}` on every line. */
+const logger = loggerChild({ module: 'opencode-session-detail' });
+
 /** Maximum number of concurrent SSE subscribers on this dashboard process. */
 const MAX_SSE_SUBSCRIBERS = 50;
 /** Read the heartbeat interval on demand so tests can shrink it via
@@ -62,39 +72,6 @@ const LIST_MESSAGES_TIMEOUT_MS = 8_000;
 /** Default timeout for the upstream prompt endpoint. */
 const SEND_PROMPT_TIMEOUT_MS = 12_000;
 
-/**
- * Resolve the opencode `directory` query parameter for a session.
- *
- * Tries (in order):
- *   1. The session's own `location.directory` from `listOpencodeSessions`.
- *   2. `info.worktree` (the plugin's recorded cwd at startup).
- *
- * Returns `null` when neither is known — callers should 503 in that
- * case so the UI can show "directory unknown" rather than sending the
- * prompt with a blank directory (which the opencode API would 400).
- *
- * @param {ReturnType<typeof readServeInfo>} info
- * @param {string} sessionId
- * @returns {Promise<string|null>}
- */
-async function resolveSessionDirectory(info, sessionId) {
-  if (!info) return null;
-  try {
-    const sessions = await listOpencodeSessions(info, 5_000);
-    if (Array.isArray(sessions)) {
-      const entry = sessions.find((s) => s && s.id === sessionId);
-      const dir = entry?.location?.directory;
-      if (typeof dir === 'string' && dir.length > 0) return dir;
-    }
-  } catch {
-    /* fall through to worktree */
-  }
-  if (typeof info.worktree === 'string' && info.worktree.length > 0) {
-    return info.worktree;
-  }
-  return null;
-}
-
 /**
  * Normalize an opencode message into the dashboard's chat shape:
  *   { id, role, content, ts }
@@ -145,21 +122,44 @@ export function createOpencodeSessionDetailRouter() {
       return res.status(503).json({
         error: 'plugin_offline',
         message: 'opencode plugin is not running',
+        suggestion: 'Run `bizar doctor` for diagnostics, or start opencode with `opencode serve`',
       });
     }
-    const directory = await resolveSessionDirectory(info, sessionId);
+    const directory = await resolveSessionDirectory(sessionId, info);
     if (!directory) {
       return res.status(503).json({
         error: 'directory_unknown',
         message:
           'Cannot determine the opencode session directory; ensure the opencode plugin is running with serve.json containing worktree.',
+        suggestion: 'Create a new session or restart opencode serve.',
       });
     }
     const result = await listOpencodeMessages(info, sessionId, directory, LIST_MESSAGES_TIMEOUT_MS);
     if (!result?.ok) {
+      const errMsg = result?.error || 'unknown error from opencode serve';
+      // v5.0.0 — bug #4: prefer the structured `cause` field if the
+      // helper surfaced one (it carries `ECONNREFUSED` / `UND_ERR_*`
+      // from the underlying fetch); fall back to substring inference
+      // for older error message shapes.
+      let cause = result?.cause || 'unknown';
+      if (cause === 'unknown') {
+        if (errMsg.includes('timed out')) cause = 'timeout';
+        else if (errMsg.includes('network error') || errMsg.includes('fetch failed')) cause = 'network';
+      }
+      logger.error('opencode listMessages failed', {
+        sessionId,
+        worktree: directory,
+        servePort: info.port,
+        status: result?.status ?? null,
+        cause,
+        err: errMsg,
+      });
       return res.status(502).json({
         error: 'opencode_error',
-        message: result?.error || 'unknown error from opencode serve',
+        message: errMsg,
+        cause,
+        status: result?.status ?? undefined,
+        suggestion: 'Check that the opencode serve child is running. Try `bizar doctor` or restart the plugin.',
       });
     }
     const messages = Array.isArray(result.messages) ? result.messages.map(toChatMessage) : [];
@@ -191,14 +191,16 @@ export function createOpencodeSessionDetailRouter() {
       return res.status(503).json({
         error: 'plugin_offline',
         message: 'opencode plugin is not running',
+        suggestion: 'Run `bizar doctor` for diagnostics, or start opencode with `opencode serve`',
       });
     }
-    const directory = await resolveSessionDirectory(info, sessionId);
+    const directory = await resolveSessionDirectory(sessionId, info);
     if (!directory) {
       return res.status(503).json({
         error: 'directory_unknown',
         message:
           'Cannot determine the opencode session directory; ensure the opencode plugin is running with serve.json containing worktree.',
+        suggestion: 'Create a new session or restart opencode serve.',
       });
     }
     // Synthesize a unique messageID so the client can correlate the
@@ -211,9 +213,26 @@ export function createOpencodeSessionDetailRouter() {
       SEND_PROMPT_TIMEOUT_MS,
     );
     if (!result?.ok) {
+      const errMsg = result?.error || 'unknown error from opencode serve';
+      let cause = result?.cause || 'unknown';
+      if (cause === 'unknown') {
+        if (errMsg.includes('timed out')) cause = 'timeout';
+        else if (errMsg.includes('network error') || errMsg.includes('fetch failed')) cause = 'network';
+      }
+      logger.error('opencode sendPrompt failed', {
+        sessionId,
+        worktree: directory,
+        servePort: info.port,
+        status: result?.status ?? null,
+        cause,
+        err: errMsg,
+      });
       return res.status(502).json({
         error: 'opencode_error',
-        message: result?.error || 'unknown error from opencode serve',
+        message: errMsg,
+        cause,
+        status: result?.status ?? undefined,
+        suggestion: 'Check that the opencode serve child is running. Try `bizar doctor` or restart the plugin.',
       });
     }
     return res.json({ ok: true, messageId: result.messageId });

package/bizar-dash/src/server/routes/schedules.mjs

@@ -14,10 +14,31 @@
  * rest of the schedule.
  */
 import { Router } from 'express';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { schedulesStore } from '../schedules-store.mjs';
 import { schedulesRunner } from '../schedules-runner.mjs';
 import { readActiveProjectId, wrap } from './_shared.mjs';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', '..', '..', '..', 'templates', 'schedules');
+
+/**
+ * Load all schedule templates from templates/schedules/.
+ * Each template gets `source: 'template'` and `templateFile` added.
+ * Missing directory returns an empty array.
+ */
+function loadTemplates() {
+  if (!existsSync(TEMPLATES_DIR)) return [];
+  return readdirSync(TEMPLATES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      const content = JSON.parse(readFileSync(join(TEMPLATES_DIR, f), 'utf8'));
+      return { ...content, source: 'template', templateFile: f };
+    });
+}
+
 /**
  * @param {object} deps
  * @param {Function} deps.broadcast
@@ -100,5 +121,39 @@ export function createSchedulesRouter({ broadcast }) {
     res.status(204).end();
   }));
 
+  // GET /api/schedules/templates → { templates: [...] }
+  router.get('/schedules/templates', wrap(async (_req, res) => {
+    res.json({ templates: loadTemplates() });
+  }));
+
+  // POST /api/schedules/from-template → creates a schedule from a template
+  router.post('/schedules/from-template', wrap(async (req, res) => {
+    const projectId = req.body?.projectId || readActiveProjectId() || 'default';
+    const { templateId, name: customName } = req.body || {};
+    if (!templateId) {
+      res.status(400).json({ error: 'templateId is required' });
+      return;
+    }
+    const templates = loadTemplates();
+    const template = templates.find((t) => t.id === templateId);
+    if (!template) {
+      res.status(404).json({ error: 'template not found' });
+      return;
+    }
+    // Build a schedule payload from the template, allowing name override
+    const schedulePayload = {
+      name: customName || template.name,
+      type: template.type,
+      schedule: template.schedule,
+      timezone: template.timezone || 'UTC',
+      action: template.action,
+      budgetCheck: template.budgetCheck,
+      enabled: true,
+    };
+    const sched = schedulesStore.add(projectId, schedulePayload);
+    broadcast({ type: 'schedules:change' });
+    res.status(201).json(sched);
+  }));
+
   return router;
 }

package/bizar-dash/src/server/serve-info.mjs

@@ -56,6 +56,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createConnection, isIP } from 'node:net';
+import { warn as loggerWarn, error as loggerError } from './logger.mjs';
 
 const HOME = homedir();
 
@@ -321,6 +322,147 @@ export async function listOpencodeSessions(info, timeoutMs = 5000) {
 
 export const SERVE_INFO_FILE_PATHS = DEFAULT_SERVE_INFO_FILES;
 
+// ── v5.0.0 — bug #4 — directory resolver (shared between route modules) ──
+//
+// Both `routes/opencode-sessions.mjs` and `routes/opencode-session-detail.mjs`
+// need the same logic: given a sessionId and the plugin's serve-info, figure
+// out which `directory` (worktree) to pass as a `?directory=…` query param
+// to opencode's HTTP API. We previously had two copies of this resolver
+// inline in each route; now there's one in serve-info.mjs so a fix here
+// reaches both routes.
+//
+// Strategy (per issue #4 brief):
+//   1. If serve.json has a `worktree` AND a fast probe (`GET
+//      /api/session/{id}?directory=<worktree>`) succeeds (HTTP 200), use
+//      the worktree — no need to list every opencode session.
+//   2. Otherwise, list every session via `GET /api/session` and find the
+//      one whose id matches. Use its `location.directory` (or the legacy
+//      `worktree` field, if present) as the directory.
+//   3. If neither yields a directory, return null — callers should 503
+//      so the UI can show "directory unknown" rather than sending the
+//      request with a blank `?directory=` (opencode 400s on that).
+//
+// `worktreeHasSession` is a small `GET /api/session/{id}?directory=...`
+// probe used as a fast-path so we don't pay the cost of listing every
+// session on every listMessages call. The endpoint returns 200 when the
+// session exists in that worktree, 404 when it doesn't. We treat 2xx
+// other than 200 as success (opencode has shipped both `200` and `204`
+// on this endpoint across versions).
+
+/**
+ * Lightweight probe — does `sessionId` exist in `worktree`?
+ *
+ * Implemented as `GET /api/session/{id}?directory={worktree}`. Returns
+ * `true` on 2xx, `false` on 404, `null` on network / auth / other
+ * errors (the caller should fall back to the slower list path and
+ * trust THAT result).
+ *
+ * Never throws.
+ *
+ * @param {ServeInfo} info
+ * @param {string} sessionId
+ * @param {string} worktree
+ * @param {number} [timeoutMs]
+ * @returns {Promise<boolean|null>}
+ */
+async function worktreeHasSession(info, sessionId, worktree, timeoutMs = 2_500) {
+  if (!info || !sessionId || !worktree) return null;
+  const url = `${info.baseUrl}/api/session/${encodeURIComponent(sessionId)}?directory=${encodeURIComponent(worktree)}`;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: buildAuthHeader(info),
+        Accept: 'application/json',
+      },
+      signal: ac.signal,
+    });
+    if (res.status >= 200 && res.status < 300) return true;
+    if (res.status === 404) return false;
+    // 401/403/5xx → don't trust the result, let the fallback path decide.
+    return null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve the opencode `directory` (worktree) for a session.
+ *
+ * Per the brief:
+ *   1. If we have a worktree AND a fast probe confirms the session
+ *      lives there, return it.
+ *   2. Otherwise, list every session and find the matching one; use
+ *      its `location.directory` (or legacy `worktree`).
+ *   3. Return null if neither yields a directory.
+ *
+ * Signature is `(sessionId, serveInfo)` (positional, sessionId first)
+ * to match the brief. Callers that only have `serveInfo` can pass
+ * `null` for `sessionId` and the function will fall through to the
+ * list path.
+ *
+ * Never throws.
+ *
+ * @param {string|null|undefined} sessionId
+ * @param {ServeInfo|null|undefined} serveInfo
+ * @returns {Promise<string|null>}
+ */
+export async function resolveSessionDirectory(sessionId, serveInfo) {
+  if (!serveInfo) return null;
+
+  // Fast path: probe the recorded worktree first. If the session lives
+  // there, we save the round-trip to /api/session.
+  if (typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+    const probe = await worktreeHasSession(serveInfo, sessionId || '', serveInfo.worktree);
+    if (probe === true) return serveInfo.worktree;
+  }
+
+  // Slower fallback: list every session and find the match.
+  try {
+    const sessions = await listOpencodeSessions(serveInfo, 5_000);
+    if (Array.isArray(sessions)) {
+      const entry = sessionId
+        ? sessions.find(
+            (s) =>
+              s && (s.id === sessionId || (typeof s.sessionId === 'string' && s.sessionId === sessionId)),
+          )
+        : null;
+      if (entry) {
+        const dir = entry?.location?.directory;
+        if (typeof dir === 'string' && dir.length > 0) return dir;
+        // Defensive: some opencode builds store the worktree on the
+        // session at the top level instead of under `location`.
+        const legacy = entry?.worktree;
+        if (typeof legacy === 'string' && legacy.length > 0) return legacy;
+      }
+      // No matching session, but we have a worktree from serve.json —
+      // last-chance fallback. This mirrors the pre-v5.0.0 inline
+      // resolver behaviour so an unmatched session still routes to
+      // the plugin's recorded cwd rather than 503'ing.
+      if (!entry && typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+        return serveInfo.worktree;
+      }
+    } else if (typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+      // listOpencodeSessions returned null (serve offline / auth fail).
+      // Fall back to the worktree so we at least try the same
+      // directory the plugin recorded — the upstream 404/502 will
+      // surface a clearer error than a 503 directory_unknown.
+      return serveInfo.worktree;
+    }
+  } catch (err) {
+    loggerWarn('resolveSessionDirectory: listOpencodeSessions failed', {
+      sessionId: sessionId || null,
+      err: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return null;
+}
+
 // ── v3.5.4 (bug: dispatch stuck) — spawn helpers ─────────────────────────
 //
 // The dashboard's task delegator used to shell out to
@@ -473,8 +615,21 @@ export async function sendOpencodePrompt(info, opts, directory, timeoutMs = DEFA
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const isAbort = err instanceof Error && err.name === 'AbortError';
+    let cause = 'unknown';
+    if (isAbort) cause = 'timeout';
+    else if (err && typeof err === 'object') {
+      const code = /** @type {any} */ (err).code;
+      if (typeof code === 'string' && code.length > 0) {
+        cause = code.startsWith('ECONN') || code.startsWith('UND_ERR') || code === 'ENOTFOUND'
+          ? 'network'
+          : code;
+      } else {
+        cause = 'network';
+      }
+    }
     return {
       ok: false,
+      cause,
       error: isAbort ? `sendPrompt timed out after ${timeoutMs}ms` : `sendPrompt network error: ${msg}`,
     };
   } finally {
@@ -543,8 +698,25 @@ export async function listOpencodeMessages(info, sessionId, directory, timeoutMs
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const isAbort = err instanceof Error && err.name === 'AbortError';
+    // v5.0.0 — bug #4: surface a structured `cause` to the route so it
+    // can render a useful suggestion without substring-sniffing the
+    // error message. Prefers the underlying network error code
+    // (ECONNREFUSED, UND_ERR_SOCKET, …) when present.
+    let cause = 'unknown';
+    if (isAbort) cause = 'timeout';
+    else if (err && typeof err === 'object') {
+      const code = /** @type {any} */ (err).code;
+      if (typeof code === 'string' && code.length > 0) {
+        cause = code.startsWith('ECONN') || code.startsWith('UND_ERR') || code === 'ENOTFOUND'
+          ? 'network'
+          : code;
+      } else {
+        cause = 'network';
+      }
+    }
     return {
       ok: false,
+      cause,
       error: isAbort ? `listMessages timed out after ${timeoutMs}ms` : `listMessages network error: ${msg}`,
     };
   } finally {