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

package/dist/src/commands/init.js

@@ -8,10 +8,19 @@ import { basename, resolve as resolve6 } 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;
@@ -32,7 +41,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;
@@ -71,7 +80,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) {
@@ -114,7 +123,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);
@@ -147,7 +156,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 };
 }
@@ -227,7 +236,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;
   }
@@ -277,15 +286,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 {
@@ -297,7 +355,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;
 }
@@ -356,14 +416,14 @@ async function switchServerProjectRootViaServer(context, projectRoot, options =
     }
   }
   if (!switched) {
-    throw new CliError2(`Rig server did not accept project-root switch to ${projectRoot} before timeout (${lastError instanceof Error ? lastError.message : String(lastError ?? "no response")}).`, 1);
+    throw new CliError(`Rig server did not accept project-root switch to ${projectRoot} before timeout (${lastError instanceof Error ? lastError.message : String(lastError ?? "no response")}).`, 1);
   }
   const record = switched && typeof switched === "object" && !Array.isArray(switched) ? switched : {};
   if (record.ok === true) {
     writeRepoServerProjectRoot(context.projectRoot, projectRoot);
     return { ok: true, switched: record };
   }
-  throw new CliError2(`Rig server rejected project-root scope ${projectRoot}: ${String(record.message ?? record.error ?? "unknown error")}`, 1);
+  throw new CliError(`Rig server rejected project-root scope ${projectRoot}: ${String(record.message ?? record.error ?? "unknown error")}`, 1);
 }
 async function ensureTaskLabelsViaServer(context) {
   const payload = await requestServerJson(context, "/api/workspace/task-labels", { method: "POST" });
@@ -891,7 +951,7 @@ function detectOriginRepoSlug(projectRoot) {
 function parseRepoSlug(value) {
   const match = value.trim().match(/^([^/\s]+)\/([^/\s]+)$/);
   if (!match)
-    throw new CliError2(`Invalid GitHub repo slug: ${value}. Expected owner/repo.`, 1);
+    throw new CliError(`Invalid GitHub repo slug: ${value}. Expected owner/repo.`, 1, { hint: "Pass the slug as owner/repo, e.g. `rig init --repo acme/widgets`." });
   return { owner: match[1], repo: match[2], slug: `${match[1]}/${match[2]}` };
 }
 function ensureRigPrivateDirs(projectRoot) {
@@ -973,7 +1033,7 @@ function detectGhLogin() {
 function readGhAuthToken() {
   const result = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
   if (result.status !== 0 || !result.stdout.trim()) {
-    throw new CliError2(result.stderr.trim() || "Could not read GitHub token from `gh auth token`.", result.status || 1);
+    throw new CliError(result.stderr.trim() || "Could not read GitHub token from `gh auth token`.", result.status || 1, { hint: "Sign in with `gh auth login`, or pass a token directly: `rig init --github-auth token --github-token <token>`." });
   }
   return result.stdout.trim();
 }
@@ -1003,22 +1063,22 @@ function clackTextOptions(options) {
 async function promptRequiredText(prompts, options) {
   const value = await prompts.text(clackTextOptions(options));
   if (prompts.isCancel(value))
-    throw new CliError2("Init cancelled.", 1);
+    throw new CliError("Init cancelled.", 1);
   const text = String(value ?? "").trim();
   if (!text)
-    throw new CliError2(`${options.message} is required.`, 1);
+    throw new CliError(`${options.message} is required.`, 1);
   return text;
 }
 async function promptOptionalText(prompts, options) {
   const value = await prompts.text(clackTextOptions(options));
   if (prompts.isCancel(value))
-    throw new CliError2("Init cancelled.", 1);
+    throw new CliError("Init cancelled.", 1);
   return String(value ?? "").trim();
 }
 async function promptSelect(prompts, options) {
   const value = await prompts.select(options);
   if (prompts.isCancel(value))
-    throw new CliError2("Init cancelled.", 1);
+    throw new CliError("Init cancelled.", 1);
   return String(value);
 }
 function repoOwnerFromSlug(repoSlug) {
@@ -1120,7 +1180,7 @@ async function promptGitHubProjectConfig(context, prompts, repoSlug, githubToken
   }
   const owner = repoOwnerFromSlug(repoSlug);
   if (!owner)
-    throw new CliError2(`Cannot derive GitHub owner from repo slug ${repoSlug}.`, 1);
+    throw new CliError(`Cannot derive GitHub owner from repo slug ${repoSlug}.`, 1, { hint: "Pass the slug as owner/repo, e.g. `rig init --repo acme/widgets`." });
   let activeToken = githubToken?.trim() || null;
   let projectsPayload = await listGitHubProjectsForInit(context, owner, activeToken).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error), projects: [] }));
   let projects = recordArray(projectsPayload, "projects");
@@ -1278,6 +1338,100 @@ function runLocalFilesInit(context, options) {
   }
   return { ok: true, group: "init", command: "init", details: { mode: "local-files", projectRoot, taskSourcePath: "tasks" } };
 }
+var DEMO_TASKS_RELATIVE_DIR = ".rig/demo-tasks";
+var DEMO_TASKS = [
+  {
+    id: "demo-1",
+    title: "Add a hello CLI script",
+    body: [
+      "Create `scripts/hello.ts` that prints `Hello from Rig!` plus the current date,",
+      "and add a `hello` script entry to package.json that runs it with bun.",
+      "Keep it dependency-free."
+    ].join(`
+`),
+    status: "ready",
+    labels: ["demo"]
+  },
+  {
+    id: "demo-2",
+    title: "Write a README section about this project",
+    body: [
+      "Add (or extend) README.md with a short `## What this is` section:",
+      "two or three sentences describing the repository and how to run it.",
+      "Plain prose, no badges."
+    ].join(`
+`),
+    status: "ready",
+    labels: ["demo"]
+  },
+  {
+    id: "demo-3",
+    title: "Add a unit test for the hello script",
+    body: [
+      "Add `scripts/hello.test.ts` with a bun test that imports the greeting",
+      "helper from the hello script and asserts it contains `Hello from Rig!`.",
+      "Refactor the script to export that helper if needed."
+    ].join(`
+`),
+    status: "ready",
+    labels: ["demo"]
+  }
+];
+function runDemoInit(context, options) {
+  const projectRoot = context.projectRoot;
+  ensureRigPrivateDirs(projectRoot);
+  ensureGitignoreEntries(projectRoot);
+  writeRepoConnection(projectRoot, { selected: "local", linkedAt: new Date().toISOString() });
+  const configTsPath = resolve6(projectRoot, "rig.config.ts");
+  const configExists = existsSync5(configTsPath) || existsSync5(resolve6(projectRoot, "rig.config.json"));
+  let configWritten = false;
+  if (configExists && !options.repair) {
+    if (context.outputMode !== "json") {
+      console.log("rig.config already exists; leaving it unchanged. Pass --repair to rewrite it for the demo.");
+    }
+  } else {
+    writeFileSync2(configTsPath, buildRigInitConfigSource({
+      projectName: basename(projectRoot) || "rig-demo",
+      taskSource: { kind: "files", path: DEMO_TASKS_RELATIVE_DIR },
+      useStandardPlugin: true
+    }), "utf-8");
+    configWritten = true;
+  }
+  ensureRigConfigPackageDependencies(projectRoot);
+  const demoTasksDir = resolve6(projectRoot, DEMO_TASKS_RELATIVE_DIR);
+  mkdirSync2(demoTasksDir, { recursive: true });
+  const taskIds = [];
+  for (const task of DEMO_TASKS) {
+    const id = String(task.id);
+    taskIds.push(id);
+    const taskPath = resolve6(demoTasksDir, `${id}.json`);
+    if (!existsSync5(taskPath)) {
+      writeFileSync2(taskPath, `${JSON.stringify(task, null, 2)}
+`, "utf-8");
+    }
+  }
+  if (context.outputMode !== "json") {
+    console.log(`Demo Rig project ready (offline, no GitHub).`);
+    console.log(`  config: rig.config.ts (files task source -> ${DEMO_TASKS_RELATIVE_DIR}/)`);
+    console.log(`  tasks:  ${taskIds.join(", ")}`);
+    console.log("Next steps:");
+    console.log("  1. rig task list");
+    console.log("  2. rig task run --next");
+  }
+  return {
+    ok: true,
+    group: "init",
+    command: "init",
+    details: {
+      mode: "demo",
+      projectRoot,
+      taskSourcePath: DEMO_TASKS_RELATIVE_DIR,
+      demoTasksDir,
+      tasks: taskIds,
+      configWritten
+    }
+  };
+}
 async function runControlPlaneInit(context, options) {
   const projectRoot = context.projectRoot;
   const detectedSlug = options.repoSlug ?? detectOriginRepoSlug(projectRoot);
@@ -1286,14 +1440,14 @@ async function runControlPlaneInit(context, options) {
     if ((options.server ?? "local") === "local" && authMethod2 === "skip") {
       return runLocalFilesInit(context, options);
     }
-    throw new CliError2("Could not detect GitHub repo slug from origin. Pass --repo owner/repo \u2014 or run `rig init --yes --server local --github-auth skip` for a local files-source project without GitHub.", 1);
+    throw new CliError("Could not detect GitHub repo slug from origin. Pass --repo owner/repo \u2014 or run `rig init --yes --server local --github-auth skip` for a local files-source project without GitHub.", 1);
   }
   const repo = parseRepoSlug(detectedSlug);
   const serverKind = options.server ?? "local";
   const connectionAlias = options.connectionAlias ?? (serverKind === "local" ? "local" : "remote");
   if (serverKind === "remote") {
     if (!options.remoteUrl)
-      throw new CliError2("Missing --remote-url for --server remote.", 1);
+      throw new CliError("Missing --remote-url for --server remote.", 1, { hint: "Re-run as `rig init --server remote --remote-url https://your-rig-server`." });
     upsertGlobalConnection(connectionAlias, { kind: "remote", baseUrl: options.remoteUrl });
   }
   writeRepoConnection(projectRoot, {
@@ -1338,7 +1492,7 @@ async function runControlPlaneInit(context, options) {
   const authMethod = options.githubAuthMethod ?? (options.githubToken ? "token" : "skip");
   const remoteGhTokenWarning = serverKind === "remote" && authMethod === "gh" ? `This sends a GitHub token from this machine to ${options.remoteUrl ?? "the remote Rig server"}.` : null;
   if (remoteGhTokenWarning && !options.yes) {
-    throw new CliError2(`${remoteGhTokenWarning} Re-run with --yes to confirm this explicit token transfer.`, 1);
+    throw new CliError(`${remoteGhTokenWarning} Re-run with --yes to confirm this explicit token transfer.`, 1);
   }
   const token = authMethod === "gh" && !options.githubToken ? readGhAuthToken() : options.githubToken?.trim();
   if (token) {
@@ -1450,6 +1604,8 @@ async function runControlPlaneInit(context, options) {
 }
 function parseInitOptions(args) {
   let rest = [...args];
+  const demo = takeFlag(rest, "--demo");
+  rest = demo.rest;
   const yes = takeFlag(rest, "--yes");
   rest = yes.rest;
   const repair = takeFlag(rest, "--repair");
@@ -1479,6 +1635,7 @@ function parseInitOptions(args) {
   const ref = takeOption(rest, "--ref");
   rest = ref.rest;
   const options = {
+    demo: demo.value,
     yes: yes.value,
     repair: repair.value,
     privateStateOnly: privateStateOnly.value,
@@ -1492,10 +1649,10 @@ function parseInitOptions(args) {
     githubProjectStatusField: githubProjectStatusField.value
   };
   if (server.value && options.server === undefined) {
-    throw new CliError2("--server must be local or remote.", 1);
+    throw new CliError("--server must be local or remote.", 1);
   }
   if (githubAuth.value && !["gh", "token", "device", "skip"].includes(githubAuth.value)) {
-    throw new CliError2("--github-auth must be gh, token, device, or skip.", 1);
+    throw new CliError("--github-auth must be gh, token, device, or skip.", 1);
   }
   if (remoteCheckout.value) {
     if (remoteCheckout.value === "managed-clone")
@@ -1506,10 +1663,10 @@ function parseInitOptions(args) {
       options.remoteCheckout = { kind: "uploaded-snapshot" };
     else if (remoteCheckout.value === "existing-path") {
       if (!existingPath.value)
-        throw new CliError2("--remote-checkout existing-path requires --existing-path <path>.", 1);
+        throw new CliError("--remote-checkout existing-path requires --existing-path <path>.", 1);
       options.remoteCheckout = { kind: "existing-path", path: existingPath.value };
     } else {
-      throw new CliError2("--remote-checkout must be managed-clone, current-ref, uploaded-snapshot, or existing-path.", 1);
+      throw new CliError("--remote-checkout must be managed-clone, current-ref, uploaded-snapshot, or existing-path.", 1);
     }
   }
   return { options, rest };
@@ -1586,13 +1743,13 @@ async function runInteractiveControlPlaneInit(context, prompts) {
   let remoteGhTokenConfirmed = false;
   if (serverChoice === "remote" && authMethod === "gh") {
     if (!prompts.confirm)
-      throw new CliError2("Remote gh-token import requires explicit confirmation.", 1);
+      throw new CliError("Remote gh-token import requires explicit confirmation.", 1);
     const confirmed = await prompts.confirm({
       message: `This sends a GitHub token from this machine to ${remoteUrl}. Continue?`,
       initialValue: true
     });
     if (prompts.isCancel(confirmed) || confirmed !== true) {
-      throw new CliError2("Remote gh-token import cancelled.", 1);
+      throw new CliError("Remote gh-token import cancelled.", 1);
     }
     remoteGhTokenConfirmed = true;
   }
@@ -1621,22 +1778,32 @@ async function runInteractiveControlPlaneInit(context, prompts) {
 }
 async function executeInit(context, args) {
   const parsed = parseInitOptions(args);
+  if (parsed.options.demo) {
+    if (parsed.rest.length > 0) {
+      throw new CliError(`Unexpected arguments: ${parsed.rest.join(" ")}
+Usage: rig init --demo [--yes] [--repair]`, 1, { hint: "Run `rig init --demo` (optionally with --repair to rewrite an existing rig.config)." });
+    }
+    return runDemoInit(context, parsed.options);
+  }
   if (parsed.options.yes || parsed.options.server || parsed.options.repoSlug || parsed.options.githubToken || parsed.options.privateStateOnly || parsed.options.repair || parsed.options.githubAuthMethod || parsed.options.remoteCheckout) {
     if (parsed.rest.length > 0)
-      throw new CliError2(`Unexpected arguments: ${parsed.rest.join(" ")}
-Usage: rig init [--server local|remote] [--remote-url <url>] [--repo owner/repo] [--github-auth gh|token|device|skip] [--github-token <token>] [--github-project off|<project-id>] [--remote-checkout managed-clone|current-ref|uploaded-snapshot|existing-path] [--yes]`, 1);
+      throw new CliError(`Unexpected arguments: ${parsed.rest.join(" ")}
+Usage: rig init [--demo] [--server local|remote] [--remote-url <url>] [--repo owner/repo] [--github-auth gh|token|device|skip] [--github-token <token>] [--github-project off|<project-id>] [--remote-checkout managed-clone|current-ref|uploaded-snapshot|existing-path] [--yes]`, 1);
     return runControlPlaneInit(context, parsed.options);
   }
   if (parsed.rest.length > 0)
-    throw new CliError2(`Unexpected arguments: ${parsed.rest.join(" ")}
+    throw new CliError(`Unexpected arguments: ${parsed.rest.join(" ")}
 Usage: rig init`, 1);
   if (!process.stdin.isTTY) {
-    throw new CliError2("rig init is interactive and needs a terminal. For scripts, pass flags: rig init --yes --server local --github-auth skip [--repo owner/repo].", 1);
+    throw new CliError("rig init is interactive and needs a terminal. For scripts, pass flags: rig init --yes --server local --github-auth skip [--repo owner/repo].", 1);
   }
   return runInteractiveControlPlaneInit(context, await loadClackPrompts());
 }
 export {
   runInteractiveControlPlaneInit,
+  runDemoInit,
   executeInit,
-  buildRigInitConfigSource
+  buildRigInitConfigSource,
+  DEMO_TASKS_RELATIVE_DIR,
+  DEMO_TASKS
 };

package/dist/src/commands/inspect.js

@@ -5,10 +5,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;
@@ -17,7 +26,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;
@@ -81,7 +90,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) {
@@ -145,7 +154,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 };
 }
@@ -218,7 +227,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;
   }
@@ -268,15 +277,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 {
@@ -288,7 +346,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;
 }
@@ -323,7 +383,7 @@ async function executeInspect(context, args) {
         const serverRuns = await listRunsViaServer(context, { limit: 200 }).catch(() => []);
         const serverRun = serverRuns.filter((run) => String(run.taskId ?? "") === requiredTask).sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))[0];
         if (!serverRun || typeof serverRun.runId !== "string") {
-          throw new CliError2(`No runs found for ${requiredTask} (local or on the selected server).`);
+          throw new CliError(`No runs found for ${requiredTask} (local or on the selected server).`, 1, { hint: "Start one with `rig task run --task <id>`, or check `rig run list`." });
         }
         const page = await getRunLogsViaServer(context, serverRun.runId, { limit: 500 });
         const entries = Array.isArray(page.entries) ? page.entries : [];
@@ -341,7 +401,7 @@ async function executeInspect(context, args) {
       }
       const logsPath = resolve3(resolveAuthorityRunDir(context.projectRoot, latestRun.runId), "logs.jsonl");
       if (!existsSync3(logsPath)) {
-        throw new CliError2(`No logs found for run ${latestRun.runId}.`);
+        throw new CliError(`No logs found for run ${latestRun.runId}.`, 1, { hint: `Try \`rig run show ${latestRun.runId}\` or \`rig run replay ${latestRun.runId}\`.` });
       }
       await context.runCommand(["cat", logsPath]);
       return { ok: true, group: "inspect", command, details: { task: requiredTask, runId: latestRun.runId } };
@@ -352,7 +412,7 @@ async function executeInspect(context, args) {
       const requiredTask = requireTask(task, "rig inspect artifacts --task <task-id>");
       const artifactRoot = resolveTaskArtifactDirs(context.projectRoot, requiredTask).find((path) => existsSync3(path));
       if (!artifactRoot) {
-        throw new CliError2(`No artifacts found for ${requiredTask}.`);
+        throw new CliError(`No artifacts found for ${requiredTask}.`, 1, { hint: "Artifacts appear after a run completes; check `rig run list` for run state." });
       }
       await context.runCommand(["ls", "-la", artifactRoot]);
       return { ok: true, group: "inspect", command, details: { task: requiredTask } };
@@ -366,7 +426,7 @@ async function executeInspect(context, args) {
       requireNoExtraArgs(previewPending, "rig inspect artifact --task <task-id> --file <name>");
       const requiredTask = requireTask(task.value, "rig inspect artifact --task <task-id> --file <name>");
       if (!file.value) {
-        throw new CliError2("Missing --file for rig inspect artifact.");
+        throw new CliError("Missing --file for rig inspect artifact.", 1, { hint: "List artifact files first: `rig inspect artifacts --task <id>`, then pass one with --file." });
       }
       const preview = readTaskArtifactPreview(context.projectRoot, requiredTask, file.value);
       if (context.outputMode === "text") {
@@ -420,7 +480,7 @@ async function executeInspect(context, args) {
         const monorepoRoot = resolveMonorepoRoot(context.projectRoot);
         const result = runCapture(["br", "--no-db", "list", "--pretty"], monorepoRoot);
         if (result.exitCode !== 0) {
-          throw new CliError2(result.stderr || result.stdout || "Failed to inspect graph");
+          throw new CliError(result.stderr || result.stdout || "Failed to inspect graph");
         }
         process.stdout.write(result.stdout);
       }
@@ -439,7 +499,7 @@ async function executeInspect(context, args) {
       return { ok: true, group: "inspect", command };
     }
     default:
-      throw new CliError2(`Unknown inspect command: ${command}`);
+      throw new CliError(`Unknown inspect command: ${command}`, 1, { hint: "Run `rig inspect --help` to list inspect commands." });
   }
 }
 export {