@h-rig/cli 0.0.6-alpha.7 → 0.0.6-alpha.70

package/dist/src/commands/_snapshot-upload.js

@@ -4,18 +4,24 @@ import { mkdir, readdir, readFile, writeFile } from "fs/promises";
 import { dirname as dirname2, resolve as resolve3, relative, sep } from "path";
 
 // packages/cli/src/commands/_server-client.ts
-import { spawnSync } from "child_process";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { resolve as resolve2 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { 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();
+    }
+  }
+}
 
 // packages/cli/src/commands/_server-client.ts
 import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
@@ -42,9 +48,14 @@ 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) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
 function normalizeConnection(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return null;
@@ -85,25 +96,39 @@ function readRepoConnection(projectRoot) {
   return {
     selected,
     project: typeof record.project === "string" ? record.project : undefined,
-    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
   };
 }
+function writeRepoConnection(projectRoot, state) {
+  writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
+}
 function resolveSelectedConnection(projectRoot, options = {}) {
   const repo = readRepoConnection(projectRoot);
   if (!repo)
     return null;
   if (repo.selected === "local")
-    return { alias: "local", connection: { kind: "local", mode: "auto" } };
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig connection "${repo.selected}" was not found. Run \`rig connect list\` or \`rig connect 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 };
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
 }
 
 // packages/cli/src/commands/_server-client.ts
-var cachedGitHubBearerToken;
+var scopedGitHubBearerTokens = new Map;
+var serverPhaseListener = null;
+function reportServerPhase(label) {
+  serverPhaseListener?.(label);
+}
 function cleanToken(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : null;
@@ -120,49 +145,80 @@ function readPrivateRemoteSessionToken(projectRoot) {
   }
 }
 function readGitHubBearerTokenForRemote(projectRoot) {
-  if (cachedGitHubBearerToken !== undefined)
-    return cachedGitHubBearerToken;
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
   const privateSession = readPrivateRemoteSessionToken(projectRoot);
-  if (privateSession) {
-    cachedGitHubBearerToken = privateSession;
-    return cachedGitHubBearerToken;
-  }
-  const envToken = cleanToken(process.env.RIG_GITHUB_TOKEN) ?? cleanToken(process.env.GITHUB_TOKEN) ?? cleanToken(process.env.GH_TOKEN);
-  if (envToken) {
-    cachedGitHubBearerToken = envToken;
-    return cachedGitHubBearerToken;
+  if (privateSession)
+    return privateSession;
+  return cleanToken(process.env.RIG_SERVER_AUTH_TOKEN) ?? cleanToken(process.env.RIG_REMOTE_AUTH_TOKEN);
+}
+function readStoredGitHubAuthToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.token === "string" ? parsed.token : undefined);
+  } catch {
+    return null;
   }
-  const result = spawnSync("gh", ["auth", "token"], {
-    encoding: "utf8",
-    timeout: 5000,
-    stdio: ["ignore", "pipe", "ignore"]
-  });
-  cachedGitHubBearerToken = result.status === 0 ? cleanToken(result.stdout) : null;
-  return cachedGitHubBearerToken;
+}
+function readLocalConnectionFallbackToken(projectRoot) {
+  return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
 }
 async function ensureServerForCli(projectRoot) {
   try {
     const selected = resolveSelectedConnection(projectRoot);
     if (selected?.connection.kind === "remote") {
+      reportServerPhase(`Connecting to ${selected.alias}\u2026`);
+      const authToken = readGitHubBearerTokenForRemote(projectRoot);
+      const serverProjectRoot = selected.serverProjectRoot ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
       return {
         baseUrl: selected.connection.baseUrl,
-        authToken: readGitHubBearerTokenForRemote(projectRoot),
-        connectionKind: "remote"
+        authToken,
+        connectionKind: "remote",
+        serverProjectRoot
       };
     }
+    reportServerPhase("Starting local Rig server\u2026");
     const connection = await ensureLocalRigServerConnection(projectRoot);
     return {
       baseUrl: connection.baseUrl,
-      authToken: connection.authToken,
-      connectionKind: "local"
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
 }
+async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
+  const repo = readRepoConnection(projectRoot);
+  const slug = repo?.project?.trim();
+  if (!slug)
+    return null;
+  try {
+    const response = await fetch(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`, {
+      headers: mergeHeaders(undefined, authToken)
+    });
+    if (!response.ok)
+      return null;
+    const payload = await response.json();
+    const project = payload.project && typeof payload.project === "object" && !Array.isArray(payload.project) ? payload.project : null;
+    const checkouts = Array.isArray(project?.checkouts) ? project.checkouts : [];
+    const latestCheckout = [...checkouts].reverse().find((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.path === "string"));
+    const path = typeof latestCheckout?.path === "string" && latestCheckout.path.trim() ? latestCheckout.path.trim() : null;
+    if (path)
+      writeRepoServerProjectRoot(projectRoot, path);
+    return path;
+  } catch {
+    return null;
+  }
+}
 function mergeHeaders(headers, authToken) {
   const merged = new Headers(headers);
   if (authToken) {
@@ -185,12 +241,65 @@ 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 response = await fetch(`${server.baseUrl}${pathname}`, {
-    ...init,
-    headers: mergeHeaders(init.headers, server.authToken)
-  });
+  const headers = mergeHeaders(init.headers, server.authToken);
+  if (server.serverProjectRoot)
+    headers.set("x-rig-project-root", server.serverProjectRoot);
+  reportServerPhase(`${(init.method ?? "GET").toUpperCase()} ${pathname.split("?")[0]}\u2026`);
+  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 {
@@ -202,10 +311,23 @@ 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;
 }
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
 
 // packages/cli/src/commands/_snapshot-upload.ts
 var UPLOADED_SNAPSHOT_PR_MARKER = "<!-- rig:uploaded-snapshot -->";

package/dist/src/commands/_spinner.js

@@ -0,0 +1,65 @@
+// @bun
+// packages/cli/src/commands/_spinner.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function createTtySpinner(input) {
+  const output = input.output ?? process.stdout;
+  const isTty = output.isTTY === true;
+  const frames = input.frames && input.frames.length > 0 ? input.frames : SPINNER_FRAMES;
+  let label = input.label;
+  let frame = 0;
+  let paused = false;
+  let stopped = false;
+  let lastPrintedLabel = "";
+  const render = () => {
+    if (stopped || paused)
+      return;
+    if (!isTty) {
+      if (label !== lastPrintedLabel) {
+        output.write(`${label}
+`);
+        lastPrintedLabel = label;
+      }
+      return;
+    }
+    frame = (frame + 1) % frames.length;
+    const glyph = frames[frame] ?? frames[0] ?? "";
+    output.write(`\r\x1B[2K${input.styleFrame ? input.styleFrame(glyph) : glyph} ${label}`);
+  };
+  const clearLine = () => {
+    if (isTty)
+      output.write("\r\x1B[2K");
+  };
+  render();
+  const timer = isTty ? setInterval(render, input.intervalMs ?? 120) : null;
+  return {
+    setLabel(next) {
+      label = next;
+      render();
+    },
+    pause() {
+      paused = true;
+      clearLine();
+    },
+    resume() {
+      if (stopped)
+        return;
+      paused = false;
+      render();
+    },
+    stop(finalLine) {
+      if (stopped)
+        return;
+      stopped = true;
+      if (timer)
+        clearInterval(timer);
+      clearLine();
+      if (finalLine)
+        output.write(`${finalLine}
+`);
+    }
+  };
+}
+export {
+  createTtySpinner,
+  SPINNER_FRAMES
+};

package/dist/src/commands/_task-picker.js

@@ -1,6 +1,9 @@
 // @bun
 // packages/cli/src/commands/_task-picker.ts
-import { createInterface } from "readline/promises";
+import { cancel, isCancel, select } from "@clack/prompts";
+
+// packages/cli/src/commands/_operator-surface.ts
+import { createInterface as createPromptInterface } from "readline/promises";
 function taskId(task) {
   return typeof task.id === "string" && task.id.trim() ? task.id : "<unknown>";
 }
@@ -13,6 +16,19 @@ function taskStatus(task) {
 function renderTaskPickerRows(tasks) {
   return tasks.map((task, index) => `${index + 1}. ${taskId(task)} \xB7 ${taskStatus(task)} \xB7 ${taskTitle(task)}`);
 }
+async function promptForTaskSelection(question) {
+  const rl = createPromptInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+// packages/cli/src/commands/_task-picker.ts
+function taskId2(task) {
+  return typeof task.id === "string" && task.id.trim() ? task.id : "<unknown>";
+}
 async function selectTaskWithTextPicker(tasks, io = {}) {
   if (tasks.length === 0)
     return null;
@@ -22,25 +38,37 @@ async function selectTaskWithTextPicker(tasks, io = {}) {
   if (!isTty) {
     throw new Error("task run requires an interactive terminal to pick a task; pass --task <id>, --next, or --detach with a task id.");
   }
-  const prompt = io.prompt ?? (async (question) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    try {
-      return await rl.question(question);
-    } finally {
-      rl.close();
+  if (io.prompt || io.renderer) {
+    const prompt = io.prompt ?? promptForTaskSelection;
+    const renderer = io.renderer ?? { writeLine: (line) => process.stdout.write(`${line}
+`) };
+    renderer.writeLine("Select Rig task:");
+    for (const row of renderTaskPickerRows(tasks))
+      renderer.writeLine(`  ${row}`);
+    const answer2 = (await prompt(`Task [1-${tasks.length}] or id: `)).trim();
+    if (!answer2)
+      return null;
+    if (/^\d+$/.test(answer2)) {
+      const index2 = Number.parseInt(answer2, 10) - 1;
+      return tasks[index2] ?? null;
     }
+    return tasks.find((task) => taskId2(task) === answer2) ?? null;
+  }
+  const options = tasks.map((task, index2) => ({
+    value: `${index2}`,
+    label: `${taskId2(task)} \xB7 ${typeof task.title === "string" && task.title.trim() ? task.title.trim() : "Untitled task"}`,
+    hint: typeof task.status === "string" && task.status.trim() ? task.status.trim() : undefined
+  }));
+  const answer = await select({
+    message: "Select Rig task",
+    options
   });
-  console.log("Select Rig task:");
-  for (const row of renderTaskPickerRows(tasks))
-    console.log(`  ${row}`);
-  const answer = (await prompt(`Task [1-${tasks.length}] or id: `)).trim();
-  if (!answer)
+  if (isCancel(answer)) {
+    cancel("No task selected.");
     return null;
-  if (/^\d+$/.test(answer)) {
-    const index = Number.parseInt(answer, 10) - 1;
-    return tasks[index] ?? null;
   }
-  return tasks.find((task) => taskId(task) === answer) ?? null;
+  const index = Number.parseInt(String(answer), 10);
+  return Number.isFinite(index) ? tasks[index] ?? null : null;
 }
 export {
   selectTaskWithTextPicker,

package/dist/src/commands/agent.js

@@ -4,12 +4,19 @@ import { resolve as resolve2 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { 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;
@@ -64,8 +71,7 @@ import { resolve } from "path";
 import {
   readAuthorityRun,
   readJsonlFile,
-  resolveAuthorityRunDir,
-  writeJsonFile
+  writeAuthorityRunRecord
 } from "@rig/runtime/control-plane/authority-files";
 
 // packages/cli/src/commands/_paths.ts
@@ -159,7 +165,7 @@ function upsertAgentAuthorityRun(projectRoot, input) {
   } else if ("errorText" in next) {
     delete next.errorText;
   }
-  writeJsonFile(resolve(resolveAuthorityRunDir(projectRoot, input.runId), "run.json"), next);
+  writeAuthorityRunRecord(projectRoot, input.runId, next);
   return next;
 }
 
@@ -213,7 +219,7 @@ function parseIsolationMode(value, allowOff) {
   if (allowOff && value === "off") {
     return value;
   }
-  throw new CliError2(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
+  throw new CliError(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
 }
 
 // packages/cli/src/commands/_preflight.ts
@@ -221,6 +227,19 @@ 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;
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
 
 // packages/cli/src/commands/_preflight.ts
 async function runProjectMainSyncPreflight(context, options) {
@@ -236,7 +255,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);
       }
     }
   });
@@ -289,7 +308,7 @@ async function executeAgent(context, args) {
   const [command = "list", ...rest] = args;
   switch (command) {
     case "list": {
-      requireNoExtraArgs(rest, "bun run rig agent list");
+      requireNoExtraArgs(rest, "rig agent list");
       const runtimes = await listAgentRuntimes(context.projectRoot);
       if (context.outputMode === "text") {
         if (runtimes.length === 0) {
@@ -310,12 +329,12 @@ async function executeAgent(context, args) {
       pending = modeResult.rest;
       const taskResult = takeOption(pending, "--task");
       pending = taskResult.rest;
-      requireNoExtraArgs(pending, "bun run rig agent prepare --task <id> [--id <id>] [--mode worktree]");
+      requireNoExtraArgs(pending, "rig agent prepare --task <id> [--id <id>] [--mode worktree]");
       const mode = parseIsolationMode(modeResult.value, false);
       const id = idResult.value || agentId("agent");
       const taskId = taskResult.value?.trim();
       if (!taskId) {
-        throw new CliError2("Usage: bun run rig agent prepare --task <id> [--id <id>] [--mode worktree]");
+        throw new CliError("Usage: rig agent prepare --task <id> [--id <id>] [--mode worktree]");
       }
       const runtime = await withMutedConsole(context.outputMode === "json", () => ensureAgentRuntime({
         projectRoot: context.projectRoot,
@@ -333,7 +352,7 @@ async function executeAgent(context, args) {
     case "run": {
       const { options, commandParts } = splitAtDoubleDash(rest);
       if (commandParts.length === 0) {
-        throw new CliError2("Usage: bun run rig agent run [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
+        throw new CliError("Usage: rig agent run [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
       }
       let pending = options;
       const idResult = takeOption(pending, "--id");
@@ -344,12 +363,12 @@ async function executeAgent(context, args) {
       pending = taskResult.rest;
       const skipProjectSyncResult = takeFlag(pending, "--skip-project-sync");
       pending = skipProjectSyncResult.rest;
-      requireNoExtraArgs(pending, "bun run rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
+      requireNoExtraArgs(pending, "rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
       const mode = parseIsolationMode(modeResult.value, false);
       const id = idResult.value || agentId("agent-run");
       const taskId = taskResult.value?.trim();
       if (!taskId) {
-        throw new CliError2("Usage: bun run rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
+        throw new CliError("Usage: rig agent run --task <id> [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...>");
       }
       await runProjectMainSyncPreflight(context, { disabled: skipProjectSyncResult.value });
       const createdAt = new Date().toISOString();
@@ -408,7 +427,7 @@ async function executeAgent(context, args) {
             pid: process.pid,
             errorText: result.stderr ? result.stderr.trim() : `Agent runtime command failed (${result.exitCode})`
           });
-          throw new CliError2(`Agent runtime command failed (${result.exitCode}) in ${runtime.id}${result.stderr ? `
+          throw new CliError(`Agent runtime command failed (${result.exitCode}) in ${runtime.id}${result.stderr ? `
 ${result.stderr.trim()}` : ""}`, result.exitCode);
         }
         const completedAt = new Date().toISOString();
@@ -463,9 +482,9 @@ ${result.stderr.trim()}` : ""}`, result.exitCode);
       pending = allResult.rest;
       const idResult = takeOption(pending, "--id");
       pending = idResult.rest;
-      requireNoExtraArgs(pending, "bun run rig agent cleanup (--id <id> | --all)");
+      requireNoExtraArgs(pending, "rig agent cleanup (--id <id> | --all)");
       if (!allResult.value && !idResult.value) {
-        throw new CliError2("Provide --id <id> or --all.");
+        throw new CliError("Provide --id <id> or --all.", 1, { hint: "Run `rig agent list` to find agent ids." });
       }
       const runtimes = await listAgentRuntimes(context.projectRoot);
       const targets = allResult.value ? runtimes.map((runtime) => runtime.id) : [idResult.value];
@@ -490,7 +509,7 @@ ${result.stderr.trim()}` : ""}`, result.exitCode);
       };
     }
     default:
-      throw new CliError2(`Unknown agent command: ${command}`);
+      throw new CliError(`Unknown agent command: ${command}`, 1, { hint: "Run `rig agent --help` to list agent commands." });
   }
 }
 export {