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

package/dist/src/commands/inspect.js

@@ -1,16 +1,23 @@
 // @bun
 // packages/cli/src/commands/inspect.ts
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+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 { 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;
@@ -19,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;
@@ -55,31 +62,507 @@ import {
 import { changedFilesForTask } from "@rig/runtime/control-plane/native/task-ops";
 import { resolveHarnessPaths, resolveMonorepoRoot, runCapture } from "@rig/runtime/control-plane/native/utils";
 import { readTaskArtifactPreview } from "@rig/runtime/control-plane/native/workspace-ops";
+
+// packages/cli/src/commands/_server-client.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+
+// packages/cli/src/commands/_connection-state.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+function resolveGlobalConnectionsPath(env = process.env) {
+  const explicit = env.RIG_CONNECTIONS_FILE?.trim();
+  if (explicit)
+    return resolve(explicit);
+  const stateDir = env.RIG_GLOBAL_STATE_DIR?.trim();
+  if (stateDir)
+    return resolve(stateDir, "connections.json");
+  return resolve(homedir(), ".rig", "connections.json");
+}
+function resolveRepoConnectionPath(projectRoot) {
+  return resolve(projectRoot, ".rig", "state", "connection.json");
+}
+function readJsonFile(path) {
+  if (!existsSync(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    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;
+  const record = value;
+  if (record.kind === "local")
+    return { kind: "local", mode: "auto" };
+  if (record.kind === "remote" && typeof record.baseUrl === "string" && record.baseUrl.trim()) {
+    const baseUrl = record.baseUrl.trim().replace(/\/+$/, "");
+    return { kind: "remote", baseUrl };
+  }
+  return null;
+}
+function readGlobalConnections(options = {}) {
+  const path = resolveGlobalConnectionsPath(options.env ?? process.env);
+  const payload = readJsonFile(path);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { connections: {} };
+  }
+  const rawConnections = payload.connections;
+  const connections = {};
+  if (rawConnections && typeof rawConnections === "object" && !Array.isArray(rawConnections)) {
+    for (const [alias, raw] of Object.entries(rawConnections)) {
+      const connection = normalizeConnection(raw);
+      if (connection)
+        connections[alias] = connection;
+    }
+  }
+  return { connections };
+}
+function readRepoConnection(projectRoot) {
+  const payload = readJsonFile(resolveRepoConnectionPath(projectRoot));
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const selected = typeof record.selected === "string" ? record.selected.trim() : "";
+  if (!selected)
+    return null;
+  return {
+    selected,
+    project: typeof record.project === "string" ? record.project : 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" }, serverProjectRoot: repo.serverProjectRoot };
+  const global = readGlobalConnections(options);
+  const connection = global.connections[repo.selected];
+  if (!connection) {
+    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 };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+
+// packages/cli/src/commands/_server-client.ts
+var scopedGitHubBearerTokens = new Map;
+var serverPhaseListener = null;
+function setServerPhaseListener(listener) {
+  const previous = serverPhaseListener;
+  serverPhaseListener = listener;
+  return previous;
+}
+function reportServerPhase(label) {
+  serverPhaseListener?.(label);
+}
+function cleanToken(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+function readPrivateRemoteSessionToken(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.apiSessionToken === "string" ? parsed.apiSessionToken : typeof parsed.sessionToken === "string" ? parsed.sessionToken : undefined);
+  } catch {
+    return null;
+  }
+}
+function readGitHubBearerTokenForRemote(projectRoot) {
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
+  const privateSession = readPrivateRemoteSessionToken(projectRoot);
+  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;
+  }
+}
+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,
+        connectionKind: "remote",
+        serverProjectRoot
+      };
+    }
+    reportServerPhase("Starting local Rig server\u2026");
+    const connection = await ensureLocalRigServerConnection(projectRoot);
+    return {
+      baseUrl: connection.baseUrl,
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      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) {
+    merged.set("authorization", `Bearer ${authToken}`);
+  }
+  return merged;
+}
+function diagnosticMessage(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const diagnostics = Array.isArray(record.diagnostics) ? record.diagnostics : [];
+  const messages = diagnostics.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const diagnostic = entry;
+    const kind = typeof diagnostic.kind === "string" ? diagnostic.kind : "task-source";
+    const message = typeof diagnostic.message === "string" ? diagnostic.message : null;
+    return message ? [`${kind}: ${message}`] : [];
+  });
+  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);
+  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 {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })() : null;
+  if (!response.ok) {
+    const diagnostics = diagnosticMessage(payload);
+    const detail = diagnostics ?? (text || response.statusText);
+    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;
+}
+async function listRunsViaServer(context, options = {}) {
+  const url = new URL("http://rig.local/api/runs");
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  const runs = Array.isArray(payload) ? payload : payload && typeof payload === "object" && !Array.isArray(payload) && Array.isArray(payload.runs) ? payload.runs : [];
+  return runs.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+}
+async function getRunLogsViaServer(context, runId, options = {}) {
+  const url = new URL(`http://rig.local/api/runs/${encodeURIComponent(runId)}/logs`);
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  if (options.cursor)
+    url.searchParams.set("cursor", options.cursor);
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { entries: [] };
+}
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
+
+// packages/cli/src/commands/_async-ui.ts
+import pc from "picocolors";
+
+// 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}
+`);
+    }
+  };
+}
+
+// packages/cli/src/commands/_async-ui.ts
+var CLACK_SPINNER_FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+var DONE_SYMBOL = pc.green("\u25C7");
+var FAIL_SYMBOL = pc.red("\u25A0");
+var activeUpdate = null;
+async function withSpinner(label, work, options = {}) {
+  if (options.outputMode === "json") {
+    return work(() => {});
+  }
+  if (activeUpdate) {
+    const outer = activeUpdate;
+    outer(label);
+    return work(outer);
+  }
+  const output = options.output ?? process.stderr;
+  const isTty = output.isTTY === true;
+  let lastLabel = label;
+  if (!isTty) {
+    output.write(`${label}
+`);
+    const update2 = (next) => {
+      lastLabel = next;
+    };
+    activeUpdate = update2;
+    const previousListener2 = setServerPhaseListener(update2);
+    try {
+      return await work(update2);
+    } finally {
+      activeUpdate = null;
+      setServerPhaseListener(previousListener2);
+    }
+  }
+  const spinner = createTtySpinner({
+    label,
+    output,
+    frames: CLACK_SPINNER_FRAMES,
+    styleFrame: (frame) => pc.magenta(frame)
+  });
+  const update = (next) => {
+    lastLabel = next;
+    spinner.setLabel(next);
+  };
+  activeUpdate = update;
+  const previousListener = setServerPhaseListener(update);
+  try {
+    const result = await work(update);
+    spinner.stop(options.doneLabel ? `${DONE_SYMBOL} ${options.doneLabel}` : undefined);
+    return result;
+  } catch (error) {
+    spinner.stop(`${FAIL_SYMBOL} ${lastLabel}`);
+    throw error;
+  } finally {
+    activeUpdate = null;
+    setServerPhaseListener(previousListener);
+  }
+}
+
+// packages/cli/src/commands/inspect.ts
 async function executeInspect(context, args) {
   const [command = "failures", ...rest] = args;
   switch (command) {
     case "logs": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect logs --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig inspect logs --task <beads-id>");
+      requireNoExtraArgs(remaining, "rig inspect logs --task <task-id>");
+      const requiredTask = requireTask(task, "rig inspect logs --task <task-id>");
       const latestRun = listAuthorityRuns(context.projectRoot).map((entry) => readAuthorityRun(context.projectRoot, entry.runId)).filter((run) => Boolean(run)).filter((run) => run.taskId === requiredTask).sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))[0];
       if (!latestRun) {
-        throw new CliError2(`No runs found for ${requiredTask}.`);
+        const fallback = await withSpinner(`Finding runs for ${requiredTask} on the server\u2026`, async (update) => {
+          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")
+            return null;
+          update(`Reading logs for run ${serverRun.runId}\u2026`);
+          const page = await getRunLogsViaServer(context, serverRun.runId, { limit: 500 });
+          return { runId: serverRun.runId, page };
+        }, { outputMode: context.outputMode });
+        if (!fallback) {
+          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 entries = Array.isArray(fallback.page.entries) ? fallback.page.entries : [];
+        if (context.outputMode === "text") {
+          for (const entry of entries) {
+            const record = entry && typeof entry === "object" ? entry : {};
+            const title = String(record.title ?? "");
+            const detail = String(record.detail ?? "");
+            console.log([title, detail].filter(Boolean).join(" \u2014 "));
+          }
+          if (entries.length === 0)
+            console.log(`(no log entries for run ${fallback.runId})`);
+        }
+        return { ok: true, group: "inspect", command, details: { task: requiredTask, runId: fallback.runId, source: "server", entries } };
       }
-      const logsPath = resolve(resolveAuthorityRunDir(context.projectRoot, latestRun.runId), "logs.jsonl");
-      if (!existsSync(logsPath)) {
-        throw new CliError2(`No logs found for run ${latestRun.runId}.`);
+      const logsPath = resolve3(resolveAuthorityRunDir(context.projectRoot, latestRun.runId), "logs.jsonl");
+      if (!existsSync3(logsPath)) {
+        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 } };
     }
     case "artifacts": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect artifacts --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig inspect artifacts --task <beads-id>");
-      const artifactRoot = resolveTaskArtifactDirs(context.projectRoot, requiredTask).find((path) => existsSync(path));
+      requireNoExtraArgs(remaining, "rig inspect artifacts --task <task-id>");
+      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 } };
@@ -90,10 +573,10 @@ async function executeInspect(context, args) {
       previewPending = task.rest;
       const file = takeOption(previewPending, "--file");
       previewPending = file.rest;
-      requireNoExtraArgs(previewPending, "bun run rig inspect artifact --task <beads-id> --file <name>");
-      const requiredTask = requireTask(task.value, "bun run rig inspect artifact --task <beads-id> --file <name>");
+      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") {
@@ -120,9 +603,9 @@ async function executeInspect(context, args) {
     }
     case "diff": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect diff [--task <beads-id>]");
+      requireNoExtraArgs(remaining, "rig inspect diff [--task <task-id>]");
       if (task) {
-        const files = changedFilesForTask(context.projectRoot, task, false);
+        const files = await withSpinner(`Computing changed files for ${task}\u2026`, async () => changedFilesForTask(context.projectRoot, task, false), { outputMode: context.outputMode });
         for (const file of files) {
           console.log(file);
         }
@@ -132,33 +615,33 @@ async function executeInspect(context, args) {
       return { ok: true, group: "inspect", command, details: { task: task || null } };
     }
     case "failures": {
-      requireNoExtraArgs(rest, "bun run rig inspect failures");
+      requireNoExtraArgs(rest, "rig inspect failures");
       const failed = resolveHarnessPaths(context.projectRoot).failedApproachesPath;
-      if (!existsSync(failed)) {
+      if (!existsSync3(failed)) {
         console.log("No failures recorded.");
       } else {
-        process.stdout.write(readFileSync(failed, "utf-8"));
+        process.stdout.write(readFileSync3(failed, "utf-8"));
       }
       return { ok: true, group: "inspect", command };
     }
     case "graph":
-      requireNoExtraArgs(rest, "bun run rig inspect graph");
+      requireNoExtraArgs(rest, "rig inspect graph");
       {
         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);
       }
       return { ok: true, group: "inspect", command };
     case "audit": {
-      requireNoExtraArgs(rest, "bun run rig inspect audit");
-      const auditPath = resolve(resolveHarnessPaths(context.projectRoot).logsDir, "audit.jsonl");
-      if (!existsSync(auditPath)) {
+      requireNoExtraArgs(rest, "rig inspect audit");
+      const auditPath = resolve3(resolveHarnessPaths(context.projectRoot).logsDir, "audit.jsonl");
+      if (!existsSync3(auditPath)) {
         console.log("No audit log found.");
       } else {
-        const lines = readFileSync(auditPath, "utf-8").split(/\r?\n/).filter(Boolean).slice(-20);
+        const lines = readFileSync3(auditPath, "utf-8").split(/\r?\n/).filter(Boolean).slice(-20);
         for (const line of lines) {
           console.log(line);
         }
@@ -166,7 +649,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 {