@h-rig/cli 0.0.6-alpha.9 → 0.0.6-alpha.90

package/dist/src/commands/inspector.d.ts

@@ -0,0 +1,3 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+export declare function executeInspector(context: RunnerContext, args: string[]): Promise<CommandOutcome>;

package/dist/src/commands/inspector.js

@@ -4,12 +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 { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 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;
@@ -30,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;
@@ -55,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;
 }
@@ -104,11 +111,11 @@ async function executeInspector(context, args) {
       pending = secondsResult.rest;
       const pollMsResult = takeOption(pending, "--poll-ms");
       pending = pollMsResult.rest;
-      requireNoExtraArgs(pending, "bun run rig inspector stream [--once] [--seconds <n>] [--poll-ms <n>]");
+      requireNoExtraArgs(pending, "rig inspector stream [--once] [--seconds <n>] [--poll-ms <n>]");
       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);
@@ -135,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;
@@ -198,7 +205,7 @@ async function executeInspector(context, args) {
       let pending = rest;
       const scanIdResult = takeOption(pending, "--scan-id");
       pending = scanIdResult.rest;
-      requireNoExtraArgs(pending, "bun run rig inspector scan-upstream-drift [--scan-id <id>]");
+      requireNoExtraArgs(pending, "rig inspector scan-upstream-drift [--scan-id <id>]");
       const connection = await ensureLocalRigServerConnection(context.projectRoot);
       const response = await fetch(new URL("/api/inspector/tools/invoke", connection.baseUrl), {
         method: "POST",
@@ -212,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") {
@@ -248,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.d.ts

@@ -0,0 +1,3 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+export declare function executePi(context: RunnerContext, args: string[]): Promise<CommandOutcome>;

package/dist/src/commands/pi.js

@@ -0,0 +1,177 @@
+// @bun
+// packages/cli/src/commands/pi.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+
+// packages/cli/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+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";
+
+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(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli/src/commands/pi.ts
+function settingsPath(root) {
+  return resolve(root, ".pi", "settings.json");
+}
+function userSettingsPath() {
+  return resolve(homedir(), ".pi", "agent", "settings.json");
+}
+function readJson(path, fallback) {
+  if (!existsSync(path))
+    return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function packageKey(entry) {
+  if (typeof entry === "string")
+    return entry;
+  if (entry && typeof entry === "object" && typeof entry.source === "string") {
+    return entry.source;
+  }
+  return JSON.stringify(entry);
+}
+function writeSettings(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+}
+async function searchNpmForPiExtensions(term) {
+  const query = encodeURIComponent(term ? `${term} pi extension` : "pi extension");
+  const url = `https://registry.npmjs.org/-/v1/search?text=${query}&size=20`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    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 = [];
+  for (const entry of payload.objects ?? []) {
+    const pkg = entry.package;
+    if (!pkg?.name)
+      continue;
+    const keywords = (pkg.keywords ?? []).map((k) => k.toLowerCase());
+    const piLike = pkg.name.startsWith("pi-") || pkg.name.includes("-pi") || keywords.includes("pi") || keywords.includes("pi-extension") || (pkg.description ?? "").toLowerCase().includes("pi extension") || (pkg.description ?? "").toLowerCase().includes("pi coding agent");
+    if (!piLike)
+      continue;
+    results.push({ name: pkg.name, version: pkg.version ?? "", description: pkg.description ?? "" });
+  }
+  return results;
+}
+async function executePi(context, args) {
+  const [command = "list", ...rest] = args;
+  const projectSettingsPath = settingsPath(context.projectRoot);
+  const managedRecordPath = resolve(context.projectRoot, ".rig", "state", "pi-managed-packages.json");
+  switch (command) {
+    case "list": {
+      requireNoExtraArgs(rest, "rig pi list");
+      const project = readJson(projectSettingsPath, {});
+      const managed = new Set(readJson(managedRecordPath, []));
+      const user = readJson(userSettingsPath(), {});
+      const projectPackages = (Array.isArray(project.packages) ? project.packages : []).map((entry) => ({
+        source: packageKey(entry),
+        managedByRigConfig: managed.has(packageKey(entry))
+      }));
+      const userPackages = (Array.isArray(user.packages) ? user.packages : []).map(packageKey);
+      if (context.outputMode === "text") {
+        console.log("Project Pi packages (.pi/settings.json):");
+        if (projectPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of projectPackages) {
+          console.log(`  ${pkg.source}${pkg.managedByRigConfig ? "  [from rig.config runtime.pi.packages]" : ""}`);
+        }
+        console.log("User Pi packages (~/.pi/agent/settings.json):");
+        if (userPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of userPackages)
+          console.log(`  ${pkg}`);
+        console.log("Add more: `rig pi add <npm-package>` \xB7 discover: `rig pi search <term>`");
+      }
+      return { ok: true, group: "pi", command, details: { projectPackages, userPackages } };
+    }
+    case "add": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi add <package-source>");
+      if (!source) {
+        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 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") {
+        console.log(`Added ${source} to ${projectSettingsPath}.`);
+        console.log("Pi installs missing packages automatically at the next session start (local and worker).");
+      }
+      return { ok: true, group: "pi", command, details: { source, settingsPath: projectSettingsPath } };
+    }
+    case "remove": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi remove <package-source>");
+      if (!source) {
+        throw new CliError("Usage: rig pi remove <package-source>", 2);
+      }
+      const managed = new Set(readJson(managedRecordPath, []));
+      if (managed.has(source)) {
+        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 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)
+        nextSettings.packages = next;
+      else
+        delete nextSettings.packages;
+      writeSettings(projectSettingsPath, nextSettings);
+      if (context.outputMode === "text") {
+        console.log(`Removed ${source} from ${projectSettingsPath}.`);
+      }
+      return { ok: true, group: "pi", command, details: { source } };
+    }
+    case "search": {
+      const term = rest.join(" ").trim();
+      const results = await searchNpmForPiExtensions(term);
+      if (context.outputMode === "text") {
+        if (results.length === 0) {
+          console.log(`No Pi extension packages found on npm${term ? ` for "${term}"` : ""}.`);
+        } else {
+          console.log(`Pi extension packages on npm${term ? ` matching "${term}"` : ""}:`);
+          for (const pkg of results) {
+            console.log(`  ${pkg.name}@${pkg.version}  ${pkg.description.slice(0, 80)}`);
+          }
+          console.log("Install one: `rig pi add <name>`");
+        }
+      }
+      return { ok: true, group: "pi", command, details: { term, results } };
+    }
+    default:
+      throw new CliError(`Unknown pi command: ${command}. Use list|add|remove|search.`, 1, { hint: "Run `rig pi --help` for usage." });
+  }
+}
+export {
+  executePi
+};

package/dist/src/commands/plugin.d.ts

@@ -0,0 +1,16 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+export declare function executePlugin(context: RunnerContext, args: string[]): Promise<CommandOutcome>;
+/**
+ * Resolve a plugin CLI command by exact id ("my-plugin:deploy") or by the
+ * unambiguous local part after the namespace colon ("deploy").
+ */
+export declare function resolvePluginCliCommand(commands: readonly {
+    id: string;
+    command: string;
+    description?: string;
+}[], requested: string): {
+    id: string;
+    command: string;
+    description?: string;
+} | undefined;

package/dist/src/commands/plugin.js

@@ -1,14 +1,25 @@
 // @bun
 var __require = import.meta.require;
 
+// packages/cli/src/commands/plugin.ts
+import { existsSync } from "fs";
+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 { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 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 +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;
@@ -43,6 +54,9 @@ Usage: ${usage}`);
   return taskId;
 }
 
+// packages/cli/src/commands/plugin.ts
+import { buildPluginHostContext } from "@rig/runtime/control-plane/plugin-host-context";
+
 // packages/cli/src/commands/_parsers.ts
 async function loadRigConfigOrNull(projectRoot) {
   try {
@@ -58,8 +72,7 @@ async function executePlugin(context, args) {
   const [command = "list", ...rest] = args;
   switch (command) {
     case "list": {
-      requireNoExtraArgs(rest, "bun run rig plugin list");
-      const legacyPlugins = context.plugins.list();
+      requireNoExtraArgs(rest, "rig plugin list");
       const declarative = [];
       const config = await loadRigConfigOrNull(context.projectRoot);
       if (config && Array.isArray(config.plugins)) {
@@ -75,16 +88,16 @@ async function executePlugin(context, args) {
             taskSources: (c.taskSources ?? []).map((s) => s.id),
             skills: (c.skills ?? []).map((s) => s.id),
             taskFieldExtensions: (c.taskFieldSchemas ?? []).map((f) => f.id),
-            cliCommands: (c.cliCommands ?? []).map((c2) => c2.id)
+            cliCommands: (c.cliCommands ?? []).map((entry) => entry.id)
           });
         }
       }
       if (context.outputMode === "text") {
-        if (legacyPlugins.length === 0 && declarative.length === 0) {
-          console.log("No plugins loaded.");
-        }
-        if (declarative.length > 0) {
-          console.log("Declarative plugins (rig.config.ts):");
+        if (declarative.length === 0) {
+          const configExists = ["rig.config.ts", "rig.config.mts", "rig.config.json"].some((name) => existsSync(resolve(context.projectRoot, name)));
+          console.log(configExists ? "rig.config found but no plugins could be loaded. If the config imports @rig/* packages, run `bun install` in this project first." : "No plugins loaded. Declare plugins in rig.config.ts.");
+        } else {
+          console.log("Plugins (rig.config.ts):");
           for (const p of declarative) {
             console.log(`  ${p.name}@${p.version}`);
             const lines = [];
@@ -103,31 +116,45 @@ async function executePlugin(context, args) {
             if (p.taskFieldExtensions.length)
               lines.push(`    task-fields: ${p.taskFieldExtensions.join(", ")}`);
             if (p.cliCommands.length)
-              lines.push(`    cli-commands: ${p.cliCommands.join(", ")}`);
+              lines.push(`    cli-commands: ${p.cliCommands.join(", ")} (run with \`rig plugin run <id>\`)`);
             for (const line of lines)
               console.log(line);
           }
         }
-        if (legacyPlugins.length > 0) {
-          console.log("Legacy disk-scan plugins (rig/plugins/):");
-          for (const plugin of legacyPlugins) {
-            const validators = plugin.validators.length > 0 ? plugin.validators.join(", ") : "none";
-            console.log(`  ${plugin.name} (validators: ${validators})`);
-          }
-        }
       }
       return {
         ok: true,
         group: "plugin",
         command,
-        details: { declarative, legacy: legacyPlugins }
+        details: { declarative }
       };
     }
     case "validate": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig plugin validate --task <beads-id>");
-      const taskId = requireTask(task, "bun run rig plugin validate --task <beads-id>");
-      const results = await context.plugins.runValidators(taskId);
+      requireNoExtraArgs(remaining, "rig plugin validate --task <task-id>");
+      const taskId = requireTask(task, "rig plugin validate --task <task-id>");
+      const hostCtx = await buildPluginHostContext(context.projectRoot);
+      if (!hostCtx) {
+        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 = [];
+      for (const validator of validators) {
+        try {
+          results.push(await validator.run({
+            taskId,
+            workspaceRoot: context.projectRoot,
+            scope: []
+          }));
+        } catch (error) {
+          results.push({
+            id: validator.id,
+            passed: false,
+            summary: `${validator.id} failed unexpectedly`,
+            details: `${error}`
+          });
+        }
+      }
       const passed = results.filter((result) => result.passed).length;
       const failed = results.length - passed;
       if (context.outputMode === "text") {
@@ -144,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,
@@ -158,10 +185,51 @@ async function executePlugin(context, args) {
         }
       };
     }
+    case "run": {
+      const [commandId, ...commandArgs] = rest;
+      if (!commandId) {
+        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 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 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") {
+          console.log(`[dry-run] ${registration.command}${commandArgs.length ? ` ${commandArgs.join(" ")}` : ""}`);
+        }
+        return { ok: true, group: "plugin", command, details: { id: registration.id, dryRun: true } };
+      }
+      const proc = Bun.spawn(["bash", "-c", `${registration.command} "$@"`, registration.id, ...commandArgs], {
+        cwd: context.projectRoot,
+        env: process.env,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit"
+      });
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        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) {
+  const exact = commands.find((entry) => entry.id === requested);
+  if (exact)
+    return exact;
+  const byLocalPart = commands.filter((entry) => entry.id.split(":").slice(1).join(":") === requested);
+  return byLocalPart.length === 1 ? byLocalPart[0] : undefined;
+}
 export {
+  resolvePluginCliCommand,
   executePlugin
 };

package/dist/src/commands/profile-and-review.d.ts

@@ -0,0 +1,4 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+export declare function executeProfile(context: RunnerContext, args: string[]): Promise<CommandOutcome>;
+export declare function executeReview(context: RunnerContext, args: string[]): Promise<CommandOutcome>;

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

@@ -1,12 +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 { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 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;
@@ -15,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;
@@ -86,22 +93,22 @@ async function executeProfile(context, args) {
   const [command = "show", ...rest] = args;
   switch (command) {
     case "show":
-      requireNoExtraArgs(rest, "bun run rig profile show");
+      requireNoExtraArgs(rest, "rig profile show");
       await withMutedConsole(context.outputMode === "json", () => showProfile(context.projectRoot));
       return { ok: true, group: "profile", command };
     case "set": {
       if (rest.length === 0) {
-        throw new CliError2("Usage: bun run 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: bun run 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,9 +119,9 @@ async function executeProfile(context, args) {
       pending = runtimeResult.rest;
       const pluginResult = takeOption(pending, "--plugin");
       pending = pluginResult.rest;
-      requireNoExtraArgs(pending, "bun run rig profile set [--model ...] [--runtime ...] [--plugin ...]");
+      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, {
@@ -123,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,
@@ -137,39 +144,39 @@ 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) {
   const [command = "show", ...rest] = args;
   switch (command) {
     case "show":
-      requireNoExtraArgs(rest, "bun run rig review show");
+      requireNoExtraArgs(rest, "rig review show");
       await withMutedConsole(context.outputMode === "json", () => showReviewProfile(context.projectRoot));
       return { ok: true, group: "review", command };
     case "set": {
       if (rest.length === 0) {
-        throw new CliError2("Usage: bun run 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: bun run 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");
       pending = providerResult.rest;
-      requireNoExtraArgs(pending, "bun run rig review set <off|advisory|required> [--provider greptile]");
+      requireNoExtraArgs(pending, "rig review set <off|advisory|required> [--provider greptile]");
       try {
         await withMutedConsole(context.outputMode === "json", () => {
           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.d.ts

@@ -0,0 +1,3 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+export declare function executeQueue(context: RunnerContext, args: string[]): Promise<CommandOutcome>;