@h-rig/cli 0.0.6-alpha.64 → 0.0.6-alpha.65

package/dist/src/commands/agent.js

@@ -4,10 +4,19 @@ import { resolve as resolve2 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function takeFlag(args, flag) {
   const rest = [];
   let value = false;
@@ -28,7 +37,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -210,7 +219,7 @@ function parseIsolationMode(value, allowOff) {
   if (allowOff && value === "off") {
     return value;
   }
-  throw new CliError2(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
+  throw new CliError(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
 }
 
 // packages/cli/src/commands/_preflight.ts
@@ -219,6 +228,7 @@ import { ensureProjectMainFreshBeforeRun } from "@rig/runtime/control-plane/proj
 // packages/cli/src/commands/_server-client.ts
 import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
 var scopedGitHubBearerTokens = new Map;
+var serverReachabilityCache = new Map;
 
 // packages/cli/src/commands/_preflight.ts
 async function runProjectMainSyncPreflight(context, options) {
@@ -234,7 +244,7 @@ async function runProjectMainSyncPreflight(context, options) {
     runBootstrap: async () => {
       const bootstrap = await context.runCommand(["bun", "run", "bootstrap"]);
       if (bootstrap.exitCode !== 0) {
-        throw new CliError2(bootstrap.stderr || bootstrap.stdout || "bun run bootstrap failed during project pre-run sync", bootstrap.exitCode || 1);
+        throw new CliError(bootstrap.stderr || bootstrap.stdout || "bun run bootstrap failed during project pre-run sync", bootstrap.exitCode || 1);
       }
     }
   });
@@ -313,7 +323,7 @@ async function executeAgent(context, args) {
       const id = idResult.value || agentId("agent");
       const taskId = taskResult.value?.trim();
       if (!taskId) {
-        throw new CliError2("Usage: rig agent prepare --task <id> [--id <id>] [--mode worktree]");
+        throw new CliError("Usage: rig agent prepare --task <id> [--id <id>] [--mode worktree]");
       }
       const runtime = await withMutedConsole(context.outputMode === "json", () => ensureAgentRuntime({
         projectRoot: context.projectRoot,
@@ -331,7 +341,7 @@ async function executeAgent(context, args) {
     case "run": {
       const { options, commandParts } = splitAtDoubleDash(rest);
       if (commandParts.length === 0) {
-        throw new CliError2("Usage: rig agent run [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
+        throw new CliError("Usage: rig agent run [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
       }
       let pending = options;
       const idResult = takeOption(pending, "--id");
@@ -347,7 +357,7 @@ async function executeAgent(context, args) {
       const id = idResult.value || agentId("agent-run");
       const taskId = taskResult.value?.trim();
       if (!taskId) {
-        throw new CliError2("Usage: rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
+        throw new CliError("Usage: rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
       }
       await runProjectMainSyncPreflight(context, { disabled: skipProjectSyncResult.value });
       const createdAt = new Date().toISOString();
@@ -406,7 +416,7 @@ async function executeAgent(context, args) {
             pid: process.pid,
             errorText: result.stderr ? result.stderr.trim() : `Agent runtime command failed (${result.exitCode})`
           });
-          throw new CliError2(`Agent runtime command failed (${result.exitCode}) in ${runtime.id}${result.stderr ? `
+          throw new CliError(`Agent runtime command failed (${result.exitCode}) in ${runtime.id}${result.stderr ? `
 ${result.stderr.trim()}` : ""}`, result.exitCode);
         }
         const completedAt = new Date().toISOString();
@@ -463,7 +473,7 @@ ${result.stderr.trim()}` : ""}`, result.exitCode);
       pending = idResult.rest;
       requireNoExtraArgs(pending, "rig agent cleanup (--id <id> | --all)");
       if (!allResult.value && !idResult.value) {
-        throw new CliError2("Provide --id <id> or --all.");
+        throw new CliError("Provide --id <id> or --all.", 1, { hint: "Run `rig agent list` to find agent ids." });
       }
       const runtimes = await listAgentRuntimes(context.projectRoot);
       const targets = allResult.value ? runtimes.map((runtime) => runtime.id) : [idResult.value];
@@ -488,7 +498,7 @@ ${result.stderr.trim()}` : ""}`, result.exitCode);
       };
     }
     default:
-      throw new CliError2(`Unknown agent command: ${command}`);
+      throw new CliError(`Unknown agent command: ${command}`, 1, { hint: "Run `rig agent --help` to list agent commands." });
   }
 }
 export {

package/dist/src/commands/browser.js

@@ -10,10 +10,19 @@ import pc2 from "picocolors";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function takeFlag(args, flag) {
   const rest = [];
   let value = false;
@@ -34,7 +43,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -93,7 +102,7 @@ async function promptBugConfirm(message, initialValue) {
 function unwrapClackPrompt(result) {
   if (clack.isCancel(result)) {
     clack.cancel("Bug report cancelled.");
-    throw new CliError2("Bug report cancelled by user.");
+    throw new CliError("Bug report cancelled by user.");
   }
   return result;
 }
@@ -359,7 +368,7 @@ async function executeBrowser(context, args) {
   if (command === "app" || command === "hp-next") {
     const appSlug = command === "hp-next" ? "hp-next" : process.env.RIG_BROWSER_APP?.trim() || "";
     if (!appSlug) {
-      throw new CliError2(`rig browser app: set RIG_BROWSER_APP=<app-slug> to select which project app scripts to invoke.
+      throw new CliError(`rig browser app: set RIG_BROWSER_APP=<app-slug> to select which project app scripts to invoke.
 ` + `Scripts are invoked as 'bun run app:<mode>:browser:<app-slug>'.
 
 ${browserHelpText()}`);
@@ -371,7 +380,7 @@ ${browserHelpText()}`);
     }
     const modes = ["dev", "start", "check", "e2e", "reset"];
     if (!modes.includes(subcommand)) {
-      throw new CliError2(`Unknown browser ${command} command: ${subcommand}. Valid modes: ${modes.join(", ")}.
+      throw new CliError(`Unknown browser ${command} command: ${subcommand}. Valid modes: ${modes.join(", ")}.
 
 ${browserHelpText()}`);
     }
@@ -391,9 +400,9 @@ ${browserHelpText()}`);
     await context.runCommand(["bun", "run", "--filter=@rig/browser", packageScript]);
     return { ok: true, group: "browser", command };
   }
-  throw new CliError2(`Unknown browser command: ${command}
+  throw new CliError(`Unknown browser command: ${command}
 
-${browserHelpText()}`);
+${browserHelpText()}`, 1, { hint: "Run `rig browser help` for the full browser command reference." });
 }
 async function executeBrowserDemo(context, args) {
   const [maybeHelp] = args;
@@ -416,11 +425,11 @@ async function executeBrowserDemo(context, args) {
   pending = noBuildFlag.rest;
   requireNoExtraArgs(pending, "rig browser demo [--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]");
   if (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new CliError2("rig browser demo requires an interactive TTY in text mode.");
+    throw new CliError("rig browser demo requires an interactive TTY in text mode.", 1, { hint: "Run `rig browser demo` from an interactive terminal (no --json, no piped stdin)." });
   }
   const port = portResult.value ? Number.parseInt(portResult.value, 10) : undefined;
   if (port !== undefined && (!Number.isFinite(port) || port <= 0)) {
-    throw new CliError2(`Invalid --port value: ${portResult.value}`);
+    throw new CliError(`Invalid --port value: ${portResult.value}`, 1, { hint: "Pass a positive port number, e.g. `--port 9222`." });
   }
   const runtime = buildBrowserDemoRuntime(context.projectRoot, {
     ...port !== undefined ? { port } : {},
@@ -575,7 +584,7 @@ function runBrowserDemoBuild(projectRoot) {
   if (result.exitCode !== 0) {
     const details = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join(`
 `);
-    throw new CliError2(`Browser demo build failed.${details ? `
+    throw new CliError(`Browser demo build failed.${details ? `
 ${details}` : ""}`, result.exitCode);
   }
 }
@@ -630,7 +639,7 @@ function readBrowserDemoCommandLine(command) {
         cleanup();
         stdout.write(`
 `);
-        rejectInput(new CliError2("Browser demo cancelled."));
+        rejectInput(new CliError("Browser demo cancelled."));
         return;
       }
       if (key.name === "return" || key.name === "enter") {
@@ -696,7 +705,7 @@ async function waitForBrowserDemoReady(runtime, child) {
     return { targets: nextTargets, pageTarget: nextPageTarget };
   }, child, "CDP demo page target");
   if (!version.Browser) {
-    throw new CliError2("Browser demo reached CDP but /json/version did not include Browser metadata.");
+    throw new CliError("Browser demo reached CDP but /json/version did not include Browser metadata.");
   }
   return { version, targets, pageTarget };
 }
@@ -709,14 +718,14 @@ async function waitForBrowserDemo(check, child, label, timeoutMs = 18000) {
   let lastError = null;
   for (;; ) {
     if (child.exitCode !== null || child.signalCode !== null) {
-      throw new CliError2(`Rig Browser exited before ${label} became ready.`);
+      throw new CliError(`Rig Browser exited before ${label} became ready.`);
     }
     try {
       return await check();
     } catch (error) {
       lastError = error;
       if (Date.now() - startedAt > timeoutMs) {
-        throw new CliError2(`${label} did not become ready within ${timeoutMs}ms: ${String(lastError)}`);
+        throw new CliError(`${label} did not become ready within ${timeoutMs}ms: ${String(lastError)}`);
       }
       await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
     }

package/dist/src/commands/connect.js

@@ -4,10 +4,19 @@ import { cancel, isCancel, select } from "@clack/prompts";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function requireNoExtraArgs(args, usage) {
   if (args.length > 0) {
     throw new CliError(`Unexpected arguments: ${args.join(" ")}
@@ -37,7 +46,7 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
 function writeJsonFile(path, value) {
@@ -80,7 +89,7 @@ function writeGlobalConnections(state, options = {}) {
 function upsertGlobalConnection(alias, connection, options = {}) {
   const cleanAlias = alias.trim();
   if (!cleanAlias)
-    throw new CliError2("Connection alias is required.", 1);
+    throw new CliError("Connection alias is required.", 1, { hint: "Save a server with `rig server add <alias> <url>`." });
   const state = readGlobalConnections(options);
   state.connections[cleanAlias] = connection;
   writeGlobalConnections(state, options);
@@ -180,15 +189,15 @@ function parseConnection(alias, value, options) {
   if (alias === "local" && !value)
     return { kind: "local", mode: "auto" };
   if (!value)
-    throw new CliError2(`Missing remote server URL. Usage: ${usageName(options)} add <alias> <url>`, 1);
+    throw new CliError(`Missing remote server URL. Usage: ${usageName(options)} add <alias> <url>`, 1);
   let parsed;
   try {
     parsed = new URL(value);
   } catch {
-    throw new CliError2(`Invalid Rig server URL: ${value}`, 1);
+    throw new CliError(`Invalid Rig server URL: ${value}`, 1, { hint: "Pass a full http(s) URL, e.g. `rig server add prod https://rig.example.com`." });
   }
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new CliError2("Rig remote server URL must be http(s).", 1);
+    throw new CliError("Rig remote server URL must be http(s).", 1, { hint: "Use an http:// or https:// URL, e.g. `rig server add prod https://rig.example.com`." });
   }
   return { kind: "remote", baseUrl: parsed.toString().replace(/\/+$/, "") };
 }
@@ -217,7 +226,7 @@ async function promptForConnectionAlias(context) {
   });
   if (isCancel(answer)) {
     cancel("No server selected.");
-    throw new CliError2("No server selected.", 3);
+    throw new CliError("No server selected.", 3);
   }
   return String(answer);
 }
@@ -233,7 +242,7 @@ async function executeConnectionCommand(context, args, options) {
     case "add": {
       const [alias, url, ...extra] = rest;
       if (!alias)
-        throw new CliError2(`Missing alias. Usage: ${usageName(options)} add <alias> <url>`, 1);
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} add <alias> <url>`, 1);
       requireNoExtraArgs(extra, `${usageName(options)} add <alias> <url>`);
       const connection = parseConnection(alias, url, options);
       const state = upsertGlobalConnection(alias, connection);
@@ -251,11 +260,11 @@ async function executeConnectionCommand(context, args, options) {
         alias = await promptForConnectionAlias(context);
       }
       if (!alias)
-        throw new CliError2(`Missing alias. Usage: ${usageName(options)} use <alias|local>`, 1);
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} use <alias|local>`, 1);
       if (alias !== "local") {
         const state = readGlobalConnections();
         if (!state.connections[alias])
-          throw new CliError2(`Unknown Rig server: ${alias}`, 1);
+          throw new CliError(`Unknown Rig server: ${alias}`, 1, { hint: "Run `rig server list` to see saved aliases, or save one with `rig server add <alias> <url>`." });
       }
       const repoState = { selected: alias, linkedAt: new Date().toISOString() };
       writeRepoConnection(context.projectRoot, repoState);
@@ -275,14 +284,10 @@ async function executeConnectionCommand(context, args, options) {
       return { ok: true, group: options.group, command: "status", details };
     }
     default:
-      throw new CliError2(`Unknown ${options.group} command: ${String(command)}
+      throw new CliError(`Unknown ${options.group} command: ${String(command)}
 Usage: ${usageName(options)} <list|add|use|status>`, 1);
   }
 }
-async function executeConnect(context, args) {
-  return executeConnectionCommand(context, args, { group: "connect" });
-}
 export {
-  executeConnectionCommand,
-  executeConnect
+  executeConnectionCommand
 };

package/dist/src/commands/dist.js

@@ -17,10 +17,19 @@ import { resolve as resolve3 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function takeOption(args, option) {
   const rest = [];
   let value;
@@ -29,7 +38,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -65,7 +74,7 @@ function parseInstallScope(value) {
   if (value === "system") {
     return "system";
   }
-  throw new CliError2(`Invalid --scope value: ${value}. Use user|system.`);
+  throw new CliError(`Invalid --scope value: ${value}. Use user|system.`);
 }
 function resolveInstallDir(scope, explicitPath) {
   if (explicitPath) {
@@ -209,7 +218,7 @@ async function executeDist(context, args) {
         source = resolve3(buildDir, "bin", "rig");
       }
       if (!existsSync(source)) {
-        throw new CliError2(`Unable to locate rig binary at ${source}.`, 2);
+        throw new CliError(`Unable to locate rig binary at ${source}.`, 2, { hint: "Build it first with `rig dist build`, then re-run `rig dist install`." });
       }
       const installedPath = resolve3(installDir, "rig");
       if (existsSync(installedPath)) {
@@ -391,7 +400,7 @@ async function executeDist(context, args) {
       return { ok: true, group: "dist", command, details: { imageId: currentId, count: targets.length } };
     }
     default:
-      throw new CliError2(`Unknown dist command: ${command}`);
+      throw new CliError(`Unknown dist command: ${command}`, 1, { hint: "Run `rig dist --help` \u2014 commands are build|install|doctor." });
   }
 }
 export {

package/dist/src/commands/doctor.js

@@ -3,10 +3,19 @@ var __require = import.meta.require;
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function requireNoExtraArgs(args, usage) {
   if (args.length > 0) {
     throw new CliError(`Unexpected arguments: ${args.join(" ")}
@@ -41,7 +50,7 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
 function writeJsonFile(path, value) {
@@ -105,7 +114,7 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
   return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
 }
@@ -181,7 +190,7 @@ async function ensureServerForCli(projectRoot) {
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
@@ -231,15 +240,64 @@ function diagnosticMessage(payload) {
   });
   return messages.length > 0 ? messages.join("; ") : null;
 }
+var serverReachabilityCache = new Map;
+async function probeServerReachability(baseUrl, authToken) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/server/status`, {
+      headers: mergeHeaders(undefined, authToken),
+      signal: AbortSignal.timeout(1500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function cachedServerReachability(projectRoot, baseUrl, authToken) {
+  const key = resolve2(projectRoot);
+  const cached = serverReachabilityCache.get(key);
+  if (cached)
+    return cached;
+  const probe = probeServerReachability(baseUrl, authToken);
+  serverReachabilityCache.set(key, probe);
+  return probe;
+}
+function describeSelectedServer(projectRoot, server) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected) {
+      return {
+        alias: selected.alias,
+        target: selected.connection.kind === "remote" ? selected.connection.baseUrl : server.baseUrl
+      };
+    }
+  } catch {}
+  return { alias: server.connectionKind === "remote" ? "remote" : "local", target: server.baseUrl };
+}
+async function buildServerFailureContext(projectRoot, server) {
+  const { alias, target } = describeSelectedServer(projectRoot, server);
+  const reachable = await cachedServerReachability(projectRoot, server.baseUrl, server.authToken);
+  const reachability = reachable ? "server is reachable" : "server is unreachable";
+  return {
+    contextLine: `Currently connected to: ${alias} at ${target} (${reachability}).`,
+    hint: "Check the selected server with `rig server status`, or switch with `rig server use <alias|local>`."
+  };
+}
 async function requestServerJson(context, pathname, init = {}) {
   const server = await ensureServerForCli(context.projectRoot);
   const headers = mergeHeaders(init.headers, server.authToken);
   if (server.serverProjectRoot)
     headers.set("x-rig-project-root", server.serverProjectRoot);
-  const response = await fetch(`${server.baseUrl}${pathname}`, {
-    ...init,
-    headers
-  });
+  let response;
+  try {
+    response = await fetch(`${server.baseUrl}${pathname}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed: ${error instanceof Error ? error.message : String(error)}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
   const text = await response.text();
   const payload = text.trim().length > 0 ? (() => {
     try {
@@ -251,7 +309,9 @@ async function requestServerJson(context, pathname, init = {}) {
   if (!response.ok) {
     const diagnostics = diagnosticMessage(payload);
     const detail = diagnostics ?? (text || response.statusText);
-    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed (${response.status}): ${detail}
+${failure.contextLine}`, 1, { hint: failure.hint });
   }
   return payload;
 }