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

package/dist/src/commands/inspector.js

@@ -4,10 +4,19 @@ import { iterateServerSentEvents } from "@rig/client";
 
 // 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;
@@ -53,11 +62,11 @@ import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
 // packages/cli/src/commands/_parsers.ts
 function parseRequiredPositiveInt(value, option) {
   if (!value) {
-    throw new CliError2(`Missing value for ${option}.`);
+    throw new CliError(`Missing value for ${option}.`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} 10\`.` });
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -106,7 +115,7 @@ async function executeInspector(context, args) {
       const seconds = secondsResult.value ? parseRequiredPositiveInt(secondsResult.value, "--seconds") : null;
       const pollMs = pollMsResult.value ? parseRequiredPositiveInt(pollMsResult.value, "--poll-ms") : null;
       if (context.outputMode === "json" && !onceResult.value && !seconds) {
-        throw new CliError2("--json inspector stream requires --once or --seconds <n>.", 2);
+        throw new CliError("--json inspector stream requires --once or --seconds <n>.", 2, { hint: "Re-run as `rig inspector stream --once --json` or `rig inspector stream --seconds 10 --json`." });
       }
       const connection = await ensureLocalRigServerConnection(context.projectRoot);
       const streamUrl = new URL("/api/inspector/stream", connection.baseUrl);
@@ -133,7 +142,7 @@ async function executeInspector(context, args) {
           signal: controller.signal
         });
         if (!response.ok) {
-          throw new CliError2(`Inspector stream request failed (${response.status}).`, response.status);
+          throw new CliError(`Inspector stream request failed (${response.status}).`, response.status);
         }
         let received = 0;
         let lastEvent = null;
@@ -210,7 +219,7 @@ async function executeInspector(context, args) {
         })
       });
       if (!response.ok) {
-        throw new CliError2(`Upstream drift scan request failed (${response.status}).`, response.status);
+        throw new CliError(`Upstream drift scan request failed (${response.status}).`, response.status);
       }
       const result = await response.json();
       if (context.outputMode === "text") {
@@ -246,7 +255,7 @@ async function executeInspector(context, args) {
       };
     }
     default:
-      throw new CliError2(`Unknown inspector command: ${command}`);
+      throw new CliError(`Unknown inspector command: ${command}`, 1, { hint: "Run `rig inspector --help` \u2014 commands are stream|scan-upstream-drift." });
   }
 }
 export {

package/dist/src/commands/pi.js

@@ -6,10 +6,19 @@ import { dirname, resolve } 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 requireNoExtraArgs(args, usage) {
   if (args.length > 0) {
     throw new CliError(`Unexpected arguments: ${args.join(" ")}
@@ -51,7 +60,7 @@ async function searchNpmForPiExtensions(term) {
   const url = `https://registry.npmjs.org/-/v1/search?text=${query}&size=20`;
   const response = await fetch(url);
   if (!response.ok) {
-    throw new CliError2(`npm registry search failed (${response.status}).`, 2);
+    throw new CliError(`npm registry search failed (${response.status}).`, 2, { hint: "Check network access to registry.npmjs.org, then retry `rig pi search <term>`." });
   }
   const payload = await response.json();
   const results = [];
@@ -102,12 +111,12 @@ async function executePi(context, args) {
       const [source, ...extra] = rest;
       requireNoExtraArgs(extra, "rig pi add <package-source>");
       if (!source) {
-        throw new CliError2("Usage: rig pi add <package-source> (npm name, name@version, or git URL)", 2);
+        throw new CliError("Usage: rig pi add <package-source> (npm name, name@version, or git URL)", 2);
       }
       const settings = readJson(projectSettingsPath, {});
       const packages = Array.isArray(settings.packages) ? settings.packages : [];
       if (packages.some((entry) => packageKey(entry) === source)) {
-        throw new CliError2(`"${source}" is already in ${projectSettingsPath}.`, 2);
+        throw new CliError(`"${source}" is already in ${projectSettingsPath}.`, 2, { hint: "Run `rig pi list` to see installed extensions." });
       }
       writeSettings(projectSettingsPath, { ...settings, packages: [...packages, source] });
       if (context.outputMode === "text") {
@@ -120,17 +129,17 @@ async function executePi(context, args) {
       const [source, ...extra] = rest;
       requireNoExtraArgs(extra, "rig pi remove <package-source>");
       if (!source) {
-        throw new CliError2("Usage: rig pi remove <package-source>", 2);
+        throw new CliError("Usage: rig pi remove <package-source>", 2);
       }
       const managed = new Set(readJson(managedRecordPath, []));
       if (managed.has(source)) {
-        throw new CliError2(`"${source}" is managed by rig.config.ts (runtime.pi.packages); remove it there instead.`, 2);
+        throw new CliError(`"${source}" is managed by rig.config.ts (runtime.pi.packages); remove it there instead.`, 2);
       }
       const settings = readJson(projectSettingsPath, {});
       const packages = Array.isArray(settings.packages) ? settings.packages : [];
       const next = packages.filter((entry) => packageKey(entry) !== source);
       if (next.length === packages.length) {
-        throw new CliError2(`"${source}" is not in ${projectSettingsPath}.`, 2);
+        throw new CliError(`"${source}" is not in ${projectSettingsPath}.`, 2, { hint: "Run `rig pi list` to see what is installed, then `rig pi remove <source>` with an exact entry." });
       }
       const nextSettings = { ...settings };
       if (next.length > 0)
@@ -160,7 +169,7 @@ async function executePi(context, args) {
       return { ok: true, group: "pi", command, details: { term, results } };
     }
     default:
-      throw new CliError2(`Unknown pi command: ${command}. Use list|add|remove|search.`);
+      throw new CliError(`Unknown pi command: ${command}. Use list|add|remove|search.`, 1, { hint: "Run `rig pi --help` for usage." });
   }
 }
 export {

package/dist/src/commands/plugin.js

@@ -7,10 +7,19 @@ import { resolve } 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;
@@ -19,7 +28,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;
@@ -126,7 +135,7 @@ async function executePlugin(context, args) {
       const taskId = requireTask(task, "rig plugin validate --task <task-id>");
       const hostCtx = await buildPluginHostContext(context.projectRoot);
       if (!hostCtx) {
-        throw new CliError2(`No rig.config found at ${context.projectRoot}. Run \`rig init\` to set up plugins.`, 2);
+        throw new CliError(`No rig.config found at ${context.projectRoot}. Run \`rig init\` to set up plugins.`, 2);
       }
       const validators = hostCtx.validatorRegistry.list();
       const results = [];
@@ -162,7 +171,7 @@ async function executePlugin(context, args) {
         }
       }
       if (failed > 0) {
-        throw new CliError2(`Plugin validation failed for ${failed} validator(s).`, 2);
+        throw new CliError(`Plugin validation failed for ${failed} validator(s).`, 2, { hint: "Fix the reported validators, then re-run `rig plugin validate --task <id>`." });
       }
       return {
         ok: true,
@@ -179,16 +188,16 @@ async function executePlugin(context, args) {
     case "run": {
       const [commandId, ...commandArgs] = rest;
       if (!commandId) {
-        throw new CliError2("Usage: rig plugin run <command-id> [args...]");
+        throw new CliError("Usage: rig plugin run <command-id> [args...]", 1, { hint: "Run `rig plugin list` to see plugin-contributed command ids." });
       }
       const hostCtx = await buildPluginHostContext(context.projectRoot);
       if (!hostCtx) {
-        throw new CliError2(`No rig.config found at ${context.projectRoot}. Run \`rig init\` to set up plugins.`, 2);
+        throw new CliError(`No rig.config found at ${context.projectRoot}. Run \`rig init\` to set up plugins.`, 2);
       }
       const registration = resolvePluginCliCommand(hostCtx.pluginHost.listCliCommands(), commandId);
       if (!registration) {
         const available = hostCtx.pluginHost.listCliCommands().map((entry) => entry.id);
-        throw new CliError2(available.length > 0 ? `Unknown plugin command "${commandId}". Available: ${available.join(", ")}` : `No plugin CLI commands are registered. Plugins contribute them via contributes.cliCommands.`, 2);
+        throw new CliError(available.length > 0 ? `Unknown plugin command "${commandId}". Available: ${available.join(", ")}` : `No plugin CLI commands are registered. Plugins contribute them via contributes.cliCommands.`, 2);
       }
       if (context.dryRun) {
         if (context.outputMode === "text") {
@@ -205,12 +214,12 @@ async function executePlugin(context, args) {
       });
       const exitCode = await proc.exited;
       if (exitCode !== 0) {
-        throw new CliError2(`Plugin command "${registration.id}" exited with code ${exitCode}.`, exitCode);
+        throw new CliError(`Plugin command "${registration.id}" exited with code ${exitCode}.`, exitCode, { hint: "Run `rig plugin list` to inspect the contributing plugin, or re-run with --json for details." });
       }
       return { ok: true, group: "plugin", command, details: { id: registration.id, exitCode } };
     }
     default:
-      throw new CliError2(`Unknown plugin command: ${command}`);
+      throw new CliError(`Unknown plugin command: ${command}`, 1, { hint: "Run `rig plugin --help` \u2014 commands are list|validate|run." });
   }
 }
 function resolvePluginCliCommand(commands, requested) {

package/dist/src/commands/profile-and-review.js

@@ -1,10 +1,19 @@
 // @bun
 // 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;
@@ -13,7 +22,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;
@@ -89,17 +98,17 @@ async function executeProfile(context, args) {
       return { ok: true, group: "profile", command };
     case "set": {
       if (rest.length === 0) {
-        throw new CliError2("Usage: rig profile set <claude-code|codex-cli|pi> or set [--model ...] [--runtime ...] [--plugin ...]");
+        throw new CliError("Usage: rig profile set <claude-code|codex-cli|pi> or set [--model ...] [--runtime ...] [--plugin ...]");
       }
       const preset = rest[0];
       if (preset && !preset.startsWith("-")) {
         if (rest.length !== 1) {
-          throw new CliError2("Usage: rig profile set <claude-code|codex-cli|pi>");
+          throw new CliError("Usage: rig profile set <claude-code|codex-cli|pi>");
         }
         try {
           await withMutedConsole(context.outputMode === "json", () => setProfile(context.projectRoot, { preset }));
         } catch (error) {
-          throw new CliError2(error instanceof Error ? error.message : String(error), 2);
+          throw new CliError(error instanceof Error ? error.message : String(error), 2);
         }
         return { ok: true, group: "profile", command, details: { preset } };
       }
@@ -112,7 +121,7 @@ async function executeProfile(context, args) {
       pending = pluginResult.rest;
       requireNoExtraArgs(pending, "rig profile set [--model ...] [--runtime ...] [--plugin ...]");
       if (!modelResult.value && !runtimeResult.value && !pluginResult.value) {
-        throw new CliError2("Provide at least one of --model, --runtime, or --plugin.");
+        throw new CliError("Provide at least one of --model, --runtime, or --plugin.", 1, { hint: "Example: `rig profile set --model claude-sonnet`. See current values with `rig profile show`." });
       }
       try {
         await withMutedConsole(context.outputMode === "json", () => setProfile(context.projectRoot, {
@@ -121,7 +130,7 @@ async function executeProfile(context, args) {
           plugin: pluginResult.value
         }));
       } catch (error) {
-        throw new CliError2(error instanceof Error ? error.message : String(error), 2);
+        throw new CliError(error instanceof Error ? error.message : String(error), 2);
       }
       return {
         ok: true,
@@ -135,7 +144,7 @@ async function executeProfile(context, args) {
       };
     }
     default:
-      throw new CliError2(`Unknown profile command: ${command}`);
+      throw new CliError(`Unknown profile command: ${command}`, 1, { hint: "Run `rig profile --help` \u2014 commands are show|set." });
   }
 }
 async function executeReview(context, args) {
@@ -147,11 +156,11 @@ async function executeReview(context, args) {
       return { ok: true, group: "review", command };
     case "set": {
       if (rest.length === 0) {
-        throw new CliError2("Usage: rig review set <off|advisory|required> [--provider greptile]");
+        throw new CliError("Usage: rig review set <off|advisory|required> [--provider greptile]");
       }
       const mode = rest[0];
       if (!mode) {
-        throw new CliError2("Usage: rig review set <off|advisory|required> [--provider greptile]");
+        throw new CliError("Usage: rig review set <off|advisory|required> [--provider greptile]");
       }
       let pending = rest.slice(1);
       const providerResult = takeOption(pending, "--provider");
@@ -162,12 +171,12 @@ async function executeReview(context, args) {
           return setReviewProfile(context.projectRoot, mode, providerResult.value);
         });
       } catch (error) {
-        throw new CliError2(error instanceof Error ? error.message : String(error), 2);
+        throw new CliError(error instanceof Error ? error.message : String(error), 2);
       }
       return { ok: true, group: "review", command, details: { mode, provider: providerResult.value || null } };
     }
     default:
-      throw new CliError2(`Unknown review command: ${command}`);
+      throw new CliError(`Unknown review command: ${command}`, 1, { hint: "Run `rig review --help` \u2014 commands are show|set." });
   }
 }
 export {

package/dist/src/commands/queue.js

@@ -1,10 +1,19 @@
 // @bun
 // 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;
@@ -25,7 +34,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;
@@ -54,7 +63,7 @@ function parsePositiveInt(value, option, fallback) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -68,7 +77,7 @@ function parseAction(value) {
   if (value === "pipeline") {
     return "pipeline";
   }
-  throw new CliError2(`Invalid --action value: ${value}. Use validate, verify, or pipeline.`);
+  throw new CliError(`Invalid --action value: ${value}. Use validate, verify, or pipeline.`);
 }
 function parseIsolationMode(value, allowOff) {
   if (!value) {
@@ -80,7 +89,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
@@ -89,6 +98,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) {
@@ -104,7 +114,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);
       }
     }
   });
@@ -170,7 +180,7 @@ async function executeQueue(context, args) {
         console.log(`Failed: ${summary.failed}`);
       }
       if (summary.failed > 0) {
-        throw new CliError2(`Queue finished with ${summary.failed} failed task(s).`, 3);
+        throw new CliError(`Queue finished with ${summary.failed} failed task(s).`, 3, { hint: "Inspect the failures with `rig inspect failures`, then re-run `rig queue run`." });
       }
       return {
         ok: true,
@@ -188,7 +198,7 @@ async function executeQueue(context, args) {
       };
     }
     default:
-      throw new CliError2(`Unknown queue command: ${command}`);
+      throw new CliError(`Unknown queue command: ${command}`, 1, { hint: "Run `rig queue --help` \u2014 the primary command is `rig queue run`." });
   }
 }
 export {

package/dist/src/commands/remote.js

@@ -1,10 +1,19 @@
 // @bun
 // 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;
@@ -25,7 +34,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;
@@ -73,17 +82,17 @@ function parseOptionalPositiveInt(value, option) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
 function parseRequiredPositiveInt(value, option) {
   if (!value) {
-    throw new CliError2(`Missing value for ${option}.`);
+    throw new CliError(`Missing value for ${option}.`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} 10\`.` });
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -158,7 +167,7 @@ async function executeRemote(context, args) {
         pending2 = token.rest;
         requireNoExtraArgs(pending2, "rig remote endpoint add --alias <a> --host <h> --port <n> --token <t>");
         if (!alias.value || !host.value || !token.value || !port.value) {
-          throw new CliError2("remote endpoint add requires --alias, --host, --port, and --token.");
+          throw new CliError("remote endpoint add requires --alias, --host, --port, and --token.", 1, { hint: "Re-run as `rig remote endpoint add --alias <a> --host <h> --port <n> --token <t>`." });
         }
         const created = upsertManagedRemoteEndpoint({
           alias: alias.value,
@@ -185,7 +194,7 @@ async function executeRemote(context, args) {
         pending2 = token.rest;
         requireNoExtraArgs(pending2, "rig remote endpoint update --id <id> [--alias <a>] [--host <h>] [--port <n>] [--token <t>]");
         if (!endpointId.value && !alias.value) {
-          throw new CliError2("remote endpoint update requires --id <id> or --alias <a>.");
+          throw new CliError("remote endpoint update requires --id <id> or --alias <a>.", 1, { hint: "List endpoints with `rig remote endpoint list`, then pass --id or --alias." });
         }
         const updated = updateManagedRemoteEndpointInAuthority(context.projectRoot, {
           endpointId: endpointId.value || undefined,
@@ -195,7 +204,7 @@ async function executeRemote(context, args) {
           token: token.value || undefined
         });
         if (!updated) {
-          throw new CliError2("Remote endpoint not found.", 2);
+          throw new CliError("Remote endpoint not found.", 2, { hint: "Run `rig remote endpoint list` to see configured endpoints." });
         }
         if (context.outputMode === "text") {
           console.log(`Updated remote endpoint ${updated.alias} -> ${updated.host}:${updated.port}`);
@@ -208,11 +217,11 @@ async function executeRemote(context, args) {
         pending2 = alias.rest;
         requireNoExtraArgs(pending2, "rig remote endpoint remove --alias <a>");
         if (!alias.value) {
-          throw new CliError2("remote endpoint remove requires --alias.");
+          throw new CliError("remote endpoint remove requires --alias.", 1, { hint: "Run `rig remote endpoint list` to find the alias, then `rig remote endpoint remove --alias <a>`." });
         }
         const removed = removeManagedRemoteEndpoint(alias.value, undefined, context.projectRoot);
         if (!removed) {
-          throw new CliError2(`Remote endpoint alias not found: ${alias.value}`, 2);
+          throw new CliError(`Remote endpoint alias not found: ${alias.value}`, 2, { hint: "Run `rig remote endpoint list` to see configured endpoint aliases." });
         }
         if (context.outputMode === "text") {
           console.log(`Removed remote endpoint ${alias.value}`);
@@ -225,7 +234,7 @@ async function executeRemote(context, args) {
         pending2 = alias.rest;
         requireNoExtraArgs(pending2, "rig remote endpoint test --alias <a>");
         if (!alias.value) {
-          throw new CliError2("remote endpoint test requires --alias.");
+          throw new CliError("remote endpoint test requires --alias.", 1, { hint: "Run `rig remote endpoint list` to find the alias, then `rig remote endpoint test --alias <a>`." });
         }
         const endpoint2 = resolveRemoteEndpoint({ remoteAlias: alias.value, projectRoot: context.projectRoot });
         const client = new RemoteWsClient(endpoint2);
@@ -270,7 +279,7 @@ async function executeRemote(context, args) {
         return { ok: true, group: "remote", command: "endpoint doctor", details: result };
       }
       default:
-        throw new CliError2(`Unknown remote endpoint command: ${subcommand}`);
+        throw new CliError(`Unknown remote endpoint command: ${subcommand}`, 1, { hint: "Run `rig remote --help` for endpoint commands (list|add|update|remove|test)." });
     }
   }
   let pending = rest;
@@ -339,7 +348,7 @@ async function executeRemote(context, args) {
         const seconds = parseOptionalPositiveInt(secondsResult.value, "--seconds");
         const eventFilter = eventResult.value || undefined;
         if (context.outputMode === "json" && !seconds) {
-          throw new CliError2("--json remote watch requires --seconds <n> to produce bounded output.", 2);
+          throw new CliError("--json remote watch requires --seconds <n> to produce bounded output.", 2, { hint: "Re-run as `rig remote watch --seconds 10 --json`." });
         }
         const captured = [];
         let dropped = 0;
@@ -491,11 +500,11 @@ async function executeRemote(context, args) {
         return { ok: true, group: "remote", command, details: toDetails(response) };
       }
       default:
-        throw new CliError2(`Unknown remote command: ${command}`);
+        throw new CliError(`Unknown remote command: ${command}`, 1, { hint: "Run `rig remote --help` to list remote commands." });
     }
   } catch (error) {
     if (error instanceof RemoteCliError) {
-      throw new CliError2(`[${error.code}] ${error.message}`, error.exitCode);
+      throw new CliError(`[${error.code}] ${error.message}`, error.exitCode);
     }
     throw error;
   }

package/dist/src/commands/repo-git-harness.js

@@ -1,10 +1,19 @@
 // @bun
 // 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 formatCommand(parts) {
   return parts.map((part) => /[^a-zA-Z0-9_./:-]/.test(part) ? JSON.stringify(part) : part).join(" ");
 }
@@ -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;
@@ -146,7 +155,7 @@ async function enforceNativeCommandPolicy(context, args, options) {
     appendControlledBashAudit(context, mode, command, args, matchedRuleIds, action === "block" ? "blocked" : action === "warn" ? "warn" : undefined);
   }
   if (action === "block") {
-    throw new CliError2(`Policy blocked command: ${command}`, 126);
+    throw new CliError(`Policy blocked command: ${command}`, 126, { hint: "Review rig/policy/policy.json, or re-run with `--policy-mode observe` to log instead of block." });
   }
 }
 
@@ -167,12 +176,12 @@ async function executeRepo(context, args) {
       return { ok: true, group: "repo", command, details: { keepTaskStatus: keepTaskStatusFlag } };
     }
     default:
-      throw new CliError2(`Unknown repo command: ${command}`);
+      throw new CliError(`Unknown repo command: ${command}`, 1, { hint: "Run `rig repo --help` \u2014 commands are sync|reset-baseline." });
   }
 }
 async function executeGit(context, args) {
   if (args.length === 0) {
-    throw new CliError2("Usage: rig git <git-flow args...>");
+    throw new CliError("Usage: rig git <git-flow args...>");
   }
   await enforceNativeCommandPolicy(context, args, {
     commandPrefix: "rig-agent git",
@@ -187,13 +196,13 @@ async function executeGit(context, args) {
   try {
     await executeHarnessCommand(context.projectRoot, ["git", ...args]);
   } catch (error) {
-    throw new CliError2(error instanceof Error ? error.message : String(error), 2);
+    throw new CliError(error instanceof Error ? error.message : String(error), 2);
   }
   return { ok: true, group: "git", command: args[0] ?? "git" };
 }
 async function executeHarness(context, args) {
   if (args.length === 0) {
-    throw new CliError2("Usage: rig harness <harness args...>");
+    throw new CliError("Usage: rig harness <harness args...>");
   }
   await enforceNativeCommandPolicy(context, args, {
     commandPrefix: "rig-agent",
@@ -208,7 +217,7 @@ async function executeHarness(context, args) {
   try {
     await executeHarnessCommand(context.projectRoot, args);
   } catch (error) {
-    throw new CliError2(error instanceof Error ? error.message : String(error), 2);
+    throw new CliError(error instanceof Error ? error.message : String(error), 2);
   }
   return { ok: true, group: "harness", command: args[0] ?? "harness" };
 }